From 55d9ad0b550dfb16397c55c949839213600c7cdf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Thu, 18 Jun 2020 14:30:00 +0200 Subject: [PATCH 1/4] Fix docgen --- api/docgen/docgen.go | 37 ++++++++++++++++++++++--------------- build/params_testnet.go | 4 ++-- 2 files changed, 24 insertions(+), 17 deletions(-) diff --git a/api/docgen/docgen.go b/api/docgen/docgen.go index 4cd982aa7..ced04e7be 100644 --- a/api/docgen/docgen.go +++ b/api/docgen/docgen.go @@ -73,9 +73,13 @@ func init() { addExample(bitfield.NewFromSet([]uint64{5})) addExample(abi.RegisteredSealProof_StackedDrg32GiBV1) + addExample(abi.RegisteredPoStProof_StackedDrgWindow32GiBV1) addExample(abi.ChainEpoch(10101)) addExample(crypto.SigTypeBLS) addExample(int64(9)) + addExample(12.3) + addExample(123) + addExample(uintptr(0)) addExample(abi.MethodNum(1)) addExample(exitcode.ExitCode(0)) addExample(crypto.DomainSeparationTag_ElectionProofProduction) @@ -94,17 +98,17 @@ func init() { addExample(api.PCHInbound) addExample(time.Minute) addExample(&types.ExecutionTrace{ - Msg: exampleValue(reflect.TypeOf(&types.Message{})).(*types.Message), - MsgRct: exampleValue(reflect.TypeOf(&types.MessageReceipt{})).(*types.MessageReceipt), + Msg: exampleValue(reflect.TypeOf(&types.Message{}), nil).(*types.Message), + MsgRct: exampleValue(reflect.TypeOf(&types.MessageReceipt{}), nil).(*types.MessageReceipt), }) addExample(map[string]types.Actor{ - "t01236": exampleValue(reflect.TypeOf(types.Actor{})).(types.Actor), + "t01236": exampleValue(reflect.TypeOf(types.Actor{}), nil).(types.Actor), }) addExample(map[string]api.MarketDeal{ - "t026363": exampleValue(reflect.TypeOf(api.MarketDeal{})).(api.MarketDeal), + "t026363": exampleValue(reflect.TypeOf(api.MarketDeal{}), nil).(api.MarketDeal), }) addExample(map[string]api.MarketBalance{ - "t026363": exampleValue(reflect.TypeOf(api.MarketBalance{})).(api.MarketBalance), + "t026363": exampleValue(reflect.TypeOf(api.MarketBalance{}), nil).(api.MarketBalance), }) maddr, err := multiaddr.NewMultiaddr("/ip4/52.36.61.156/tcp/1347/p2p/12D3KooWFETiESTf1v4PGUvtnxMAcEFMzLZbJGg4tjWfGEimYior") @@ -117,7 +121,7 @@ func init() { } -func exampleValue(t reflect.Type) interface{} { +func exampleValue(t, parent reflect.Type) interface{} { v, ok := ExampleValues[t] if ok { return v @@ -126,25 +130,25 @@ func exampleValue(t reflect.Type) interface{} { switch t.Kind() { case reflect.Slice: out := reflect.New(t).Elem() - reflect.Append(out, reflect.ValueOf(exampleValue(t.Elem()))) + reflect.Append(out, reflect.ValueOf(exampleValue(t.Elem(), t))) return out.Interface() case reflect.Chan: - return exampleValue(t.Elem()) + return exampleValue(t.Elem(), nil) case reflect.Struct: - es := exampleStruct(t) + es := exampleStruct(t, parent) v := reflect.ValueOf(es).Elem().Interface() ExampleValues[t] = v return v case reflect.Array: out := reflect.New(t).Elem() for i := 0; i < t.Len(); i++ { - out.Index(i).Set(reflect.ValueOf(exampleValue(t.Elem()))) + out.Index(i).Set(reflect.ValueOf(exampleValue(t.Elem(), t))) } return out.Interface() case reflect.Ptr: if t.Elem().Kind() == reflect.Struct { - es := exampleStruct(t.Elem()) + es := exampleStruct(t.Elem(), t) //ExampleValues[t] = es return es } @@ -155,12 +159,15 @@ func exampleValue(t reflect.Type) interface{} { panic(fmt.Sprintf("No example value for type: %s", t)) } -func exampleStruct(t reflect.Type) interface{} { +func exampleStruct(t, parent reflect.Type) interface{} { ns := reflect.New(t) for i := 0; i < t.NumField(); i++ { f := t.Field(i) + if f.Type == parent { + continue + } if strings.Title(f.Name) == f.Name { - ns.Elem().Field(i).Set(reflect.ValueOf(exampleValue(f.Type))) + ns.Elem().Field(i).Set(reflect.ValueOf(exampleValue(f.Type, t))) } } @@ -286,7 +293,7 @@ func main() { ft := m.Func.Type() for j := 2; j < ft.NumIn(); j++ { inp := ft.In(j) - args = append(args, exampleValue(inp)) + args = append(args, exampleValue(inp, nil)) } v, err := json.Marshal(args) @@ -294,7 +301,7 @@ func main() { panic(err) } - outv := exampleValue(ft.Out(0)) + outv := exampleValue(ft.Out(0), nil) ov, err := json.Marshal(outv) if err != nil { diff --git a/build/params_testnet.go b/build/params_testnet.go index 202dfb231..69884f3f8 100644 --- a/build/params_testnet.go +++ b/build/params_testnet.go @@ -14,8 +14,8 @@ import ( func init() { power.ConsensusMinerMinPower = big.NewInt(1024 << 30) miner.SupportedProofTypes = map[abi.RegisteredSealProof]struct{}{ - abi.RegisteredSealProof_StackedDrg32GiBV1: {}, - abi.RegisteredSealProof_StackedDrg64GiBV1: {}, + abi.RegisteredSealProof_StackedDrg32GiBV1: {}, + abi.RegisteredSealProof_StackedDrg64GiBV1: {}, } } From 90fbbea3727659b604bfd7ca6cf1c57c84026c25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Thu, 18 Jun 2020 14:37:36 +0200 Subject: [PATCH 2/4] docgen: Make larger inputs/outputs more readable --- api/docgen/docgen.go | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/api/docgen/docgen.go b/api/docgen/docgen.go index ced04e7be..39892c820 100644 --- a/api/docgen/docgen.go +++ b/api/docgen/docgen.go @@ -296,14 +296,14 @@ func main() { args = append(args, exampleValue(inp, nil)) } - v, err := json.Marshal(args) + v, err := json.MarshalIndent(args, "", " ") if err != nil { panic(err) } outv := exampleValue(ft.Out(0), nil) - ov, err := json.Marshal(outv) + ov, err := json.MarshalIndent(outv, "", " ") if err != nil { panic(err) } @@ -338,8 +338,17 @@ func main() { fmt.Printf("### %s\n", m.Name) fmt.Printf("%s\n\n", m.Comment) - fmt.Printf("Inputs: `%s`\n\n", m.InputExample) - fmt.Printf("Response: `%s`\n\n", m.ResponseExample) + if strings.Count(m.InputExample, "\n") > 0 { + fmt.Printf("Inputs:\n```json\n%s\n```\n\n", m.InputExample) + } else { + fmt.Printf("Inputs: `%s`\n\n", m.InputExample) + } + + if strings.Count(m.ResponseExample, "\n") > 0 { + fmt.Printf("Response:\n```json\n%s\n```\n\n", m.ResponseExample) + } else { + fmt.Printf("Response: `%s`\n\n", m.ResponseExample) + } } } } From 382734b057888fb02d7fd3039eb90b53d631a722 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Thu, 18 Jun 2020 14:56:00 +0200 Subject: [PATCH 3/4] docgen: Generate simple index --- api/api_common.go | 8 ++++++-- api/docgen/docgen.go | 9 +++++++++ 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/api/api_common.go b/api/api_common.go index 6d47e35f7..aa63e9815 100644 --- a/api/api_common.go +++ b/api/api_common.go @@ -13,11 +13,13 @@ import ( ) type Common interface { - // Auth + + // MethodGroup: Auth + AuthVerify(ctx context.Context, token string) ([]auth.Permission, error) AuthNew(ctx context.Context, perms []auth.Permission) ([]byte, error) - // network + // MethodGroup: Net NetConnectedness(context.Context, peer.ID) (network.Connectedness, error) NetPeers(context.Context) ([]peer.AddrInfo, error) @@ -27,6 +29,8 @@ type Common interface { NetFindPeer(context.Context, peer.ID) (peer.AddrInfo, error) NetPubsubScores(context.Context) ([]PubsubScore, error) + // MethodGroup: Common + // ID returns peerID of libp2p node backing this API ID(context.Context) (peer.ID, error) diff --git a/api/docgen/docgen.go b/api/docgen/docgen.go index 39892c820..f876e280e 100644 --- a/api/docgen/docgen.go +++ b/api/docgen/docgen.go @@ -325,6 +325,15 @@ func main() { return groupslice[i].GroupName < groupslice[j].GroupName }) + fmt.Printf("# Groups\n") + + for _, g := range groupslice { + fmt.Printf("* [%s](#%s)\n", g.GroupName, g.GroupName) + for _, method := range g.Methods { + fmt.Printf(" * [%s](#%s)\n", method.Name, method.Name) + } + } + for _, g := range groupslice { g := g fmt.Printf("## %s\n", g.GroupName) From c0a50a21432b8d82b71ae173137d2d096532b55f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Thu, 18 Jun 2020 15:44:47 +0200 Subject: [PATCH 4/4] api: Add a bunch of donstrings --- api/api_full.go | 77 +++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 72 insertions(+), 5 deletions(-) diff --git a/api/api_full.go b/api/api_full.go index bbd28b39e..17b0fdce6 100644 --- a/api/api_full.go +++ b/api/api_full.go @@ -35,26 +35,71 @@ type FullNode interface { // ChainNotify returns channel with chain head updates // First message is guaranteed to be of len == 1, and type == 'current' ChainNotify(context.Context) (<-chan []*HeadChange, error) + // ChainHead returns the current head of the chain ChainHead(context.Context) (*types.TipSet, error) + // ChainGetRandomness is used to sample the chain for randomness ChainGetRandomness(ctx context.Context, tsk types.TipSetKey, personalization crypto.DomainSeparationTag, randEpoch abi.ChainEpoch, entropy []byte) (abi.Randomness, error) + // ChainGetBlock returns the block specified by the given CID ChainGetBlock(context.Context, cid.Cid) (*types.BlockHeader, error) ChainGetTipSet(context.Context, types.TipSetKey) (*types.TipSet, error) - ChainGetBlockMessages(context.Context, cid.Cid) (*BlockMessages, error) - ChainGetParentReceipts(context.Context, cid.Cid) ([]*types.MessageReceipt, error) - ChainGetParentMessages(context.Context, cid.Cid) ([]Message, error) + + // ChainGetBlockMessages returns messages stored in the specified block + ChainGetBlockMessages(ctx context.Context, blockCid cid.Cid) (*BlockMessages, error) + + // ChainGetParentReceipts returns receipts for messages in parent tipset of + // the specified block + ChainGetParentReceipts(ctx context.Context, blockCid cid.Cid) ([]*types.MessageReceipt, error) + + // ChainGetParentReceipts returns messages stored in parent tipset of the + // specified block + ChainGetParentMessages(ctx context.Context, blockCid cid.Cid) ([]Message, error) + + // ChainGetTipSetByHeight looks back for a tipset at the specified epoch. + // If there are no blocks at the specified epoch, a tipset at higher epoch + // will be returned ChainGetTipSetByHeight(context.Context, abi.ChainEpoch, types.TipSetKey) (*types.TipSet, error) + + // ChainReadObj reads ipld nodes referenced by the specified CID from chain + // blockstore and returns raw bytes ChainReadObj(context.Context, cid.Cid) ([]byte, error) + + // ChainHasObj checks if a given CID exists in the chain blockstore ChainHasObj(context.Context, cid.Cid) (bool, error) ChainStatObj(context.Context, cid.Cid, cid.Cid) (ObjStat, error) + + // ChainSetHead forcefully sets current chain head. Use with caution ChainSetHead(context.Context, types.TipSetKey) error + + // ChainGetGenesis returns the genesis tipset ChainGetGenesis(context.Context) (*types.TipSet, error) + + // ChainTipSetWeight computes weight for the specified tipset ChainTipSetWeight(context.Context, types.TipSetKey) (types.BigInt, error) ChainGetNode(ctx context.Context, p string) (*IpldObject, error) + + // ChainGetMessage reads a message referenced by the specified CID from the + // chain blockstore ChainGetMessage(context.Context, cid.Cid) (*types.Message, error) + + // ChainGetPath returns a set of revert/apply operations needed to get from + // one tipset to another, for example: + //``` + // to + // ^ + // from tAA + // ^ ^ + // tBA tAB + // ^---*--^ + // ^ + // tRR + //``` + // Would return `[revert(tBA), apply(tAB), apply(tAA)]` ChainGetPath(ctx context.Context, from types.TipSetKey, to types.TipSetKey) ([]*HeadChange, error) + + // ChainExport returns a stream of bytes with CAR dump of chain data ChainExport(context.Context, types.TipSetKey) (<-chan []byte, error) // MethodGroup: Sync @@ -63,23 +108,45 @@ type FullNode interface { // SyncState returns the current status of the lotus sync system SyncState(context.Context) (*SyncState, error) + // SyncSubmitBlock can be used to submit a newly created block to the // network through this node SyncSubmitBlock(ctx context.Context, blk *types.BlockMsg) error + + // SyncIncomingBlocks returns a channel streaming incoming, potentially not + // yet synced block headers. SyncIncomingBlocks(ctx context.Context) (<-chan *types.BlockHeader, error) + + // SyncMarkBad marks a blocks as bad, meaning that it won't ever by synced. + // Use with extreme caution SyncMarkBad(ctx context.Context, bcid cid.Cid) error + + // SyncCheckBad checks if a block was marked as bad, and if it was, returns + // the reason SyncCheckBad(ctx context.Context, bcid cid.Cid) (string, error) // MethodGroup: Mpool // The Mpool methods are for interacting with the message pool. The message pool // manages all incoming and outgoing 'messages' going over the network. + // MpoolPending returns pending mempool messages MpoolPending(context.Context, types.TipSetKey) ([]*types.SignedMessage, error) + + // MpoolPush pushes a signed message to mempool MpoolPush(context.Context, *types.SignedMessage) (cid.Cid, error) - MpoolPushMessage(context.Context, *types.Message) (*types.SignedMessage, error) // get nonce, sign, push + + // MpoolPushMessage atomically assigns a nonce, signs, and pushes a message + // to mempool + MpoolPushMessage(context.Context, *types.Message) (*types.SignedMessage, error) + + // MpoolGetNonce gets next nonce for the specified sender. + // Note that this method may not be atomic. Use MpoolPushMessage instead MpoolGetNonce(context.Context, address.Address) (uint64, error) MpoolSub(context.Context) (<-chan MpoolUpdate, error) - MpoolEstimateGasPrice(context.Context, uint64, address.Address, int64, types.TipSetKey) (types.BigInt, error) + + // MpoolEstimateGasPrice estimates what gas price should be used for a + // message to have high likelihood of inclusion in `nblocksincl` epochs + MpoolEstimateGasPrice(ctx context.Context, nblocksincl uint64, sender address.Address, gaslimit int64, tsk types.TipSetKey) (types.BigInt, error) // MethodGroup: Miner