OpenRPC Support

.gitignore

@@ -14,6 +14,8 @@
 /lotus-pcr
 /lotus-wallet
 /lotus-keygen
+/docgen-md
+/docgen-openrpc
 /bench.json
 /lotuspond/front/node_modules
 /lotuspond/front/build

Makefile

@@ -327,10 +327,32 @@ method-gen:
 
 gen: type-gen method-gen
 
-docsgen:
-	go run ./api/docgen "api/api_full.go" "FullNode" > documentation/en/api-methods.md
-	go run ./api/docgen "api/api_storage.go" "StorageMiner" > documentation/en/api-methods-miner.md
-	go run ./api/docgen "api/api_worker.go" "WorkerAPI" > documentation/en/api-methods-worker.md
+docsgen: docsgen-md docsgen-openrpc
+
+docsgen-md-bin:
+	go build $(GOFLAGS) -o docgen-md ./api/docgen/cmd
+docsgen-openrpc-bin:
+	go build $(GOFLAGS) -o docgen-openrpc ./api/docgen-openrpc/cmd
+
+docsgen-md: docsgen-md-full docsgen-md-storage docsgen-md-worker
+
+docsgen-md-full: docsgen-md-bin
+	./docgen-md "api/api_full.go" "FullNode" > documentation/en/api-methods.md
+docsgen-md-storage: docsgen-md-bin
+	./docgen-md "api/api_storage.go" "StorageMiner" > documentation/en/api-methods-miner.md
+docsgen-md-worker: docsgen-md-bin
+	./docgen-md "api/api_worker.go" "WorkerAPI" > documentation/en/api-methods-worker.md
+
+docsgen-openrpc: docsgen-openrpc-full docsgen-openrpc-storage docsgen-openrpc-worker
+
+docsgen-openrpc-full: docsgen-openrpc-bin
+	./docgen-openrpc "api/api_full.go" "FullNode" -gzip > build/openrpc/full.json.gz
+docsgen-openrpc-storage: docsgen-openrpc-bin
+	./docgen-openrpc "api/api_storage.go" "StorageMiner" -gzip > build/openrpc/miner.json.gz
+docsgen-openrpc-worker: docsgen-openrpc-bin
+	./docgen-openrpc "api/api_worker.go" "WorkerAPI" -gzip > build/openrpc/worker.json.gz
+
+.PHONY: docsgen docsgen-md-bin docsgen-openrpc-bin
 
 print-%:
 	@echo $*=$($*)

api/api_common.go

@@ -11,6 +11,8 @@ import (
 	"github.com/libp2p/go-libp2p-core/network"
 	"github.com/libp2p/go-libp2p-core/peer"
 	protocol "github.com/libp2p/go-libp2p-core/protocol"
+
+	apitypes "github.com/filecoin-project/lotus/api/types"
 )
 
 type Common interface {
@@ -52,6 +54,9 @@ type Common interface {
 
 	// MethodGroup: Common
 
+	// Discover returns an OpenRPC document describing an RPC API.
+	Discover(ctx context.Context) (apitypes.OpenRPCDocument, error)
+
 	// ID returns peerID of libp2p node backing this API
 	ID(context.Context) (peer.ID, error)
 

api/api_test.go

@@ -37,6 +37,18 @@ func TestDoesntDependOnFFI(t *testing.T) {
 	}
 }
 
+func TestDoesntDependOnBuild(t *testing.T) {
+	deps, err := exec.Command(goCmd(), "list", "-deps", "github.com/filecoin-project/lotus/api").Output()
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, pkg := range strings.Fields(string(deps)) {
+		if pkg == "github.com/filecoin-project/build" {
+			t.Fatal("api depends on filecoin-ffi")
+		}
+	}
+}
+
 func TestReturnTypes(t *testing.T) {
 	errType := reflect.TypeOf(new(error)).Elem()
 	bareIface := reflect.TypeOf(new(interface{})).Elem()

api/apistruct/struct.go

@@ -5,15 +5,15 @@ import (
 	"io"
 	"time"
 
+	"github.com/filecoin-project/go-address"
+	"github.com/filecoin-project/go-bitfield"
 	"github.com/google/uuid"
 	"github.com/ipfs/go-cid"
 	metrics "github.com/libp2p/go-libp2p-core/metrics"
 	"github.com/libp2p/go-libp2p-core/network"
 	"github.com/libp2p/go-libp2p-core/peer"
 	protocol "github.com/libp2p/go-libp2p-core/protocol"
 
-	"github.com/filecoin-project/go-address"
-	"github.com/filecoin-project/go-bitfield"
 	datatransfer "github.com/filecoin-project/go-data-transfer"
 	"github.com/filecoin-project/go-fil-markets/piecestore"
 	"github.com/filecoin-project/go-fil-markets/retrievalmarket"
@@ -33,6 +33,7 @@ import (
 	"github.com/filecoin-project/specs-storage/storage"
 
 	"github.com/filecoin-project/lotus/api"
+	apitypes "github.com/filecoin-project/lotus/api/types"
 	"github.com/filecoin-project/lotus/chain/actors/builtin/miner"
 	"github.com/filecoin-project/lotus/chain/actors/builtin/paych"
 	"github.com/filecoin-project/lotus/chain/types"
@@ -63,6 +64,7 @@ type CommonStruct struct {
 		NetBlockAdd                 func(ctx context.Context, acl api.NetBlockList) error            `perm:"admin"`
 		NetBlockRemove              func(ctx context.Context, acl api.NetBlockList) error            `perm:"admin"`
 		NetBlockList                func(ctx context.Context) (api.NetBlockList, error)              `perm:"read"`
+		Discover                    func(ctx context.Context) (map[string]interface{}, error)        `perm:"read"`
 
 		ID      func(context.Context) (peer.ID, error)        `perm:"read"`
 		Version func(context.Context) (api.APIVersion, error) `perm:"read"`
@@ -382,6 +384,8 @@ type StorageMinerStruct struct {
 		CreateBackup func(ctx context.Context, fpath string) error `perm:"admin"`
 
 		CheckProvable func(ctx context.Context, pp abi.RegisteredPoStProof, sectors []storage.SectorRef, expensive bool) (map[abi.SectorNumber]string, error) `perm:"admin"`
+
+		Discover func(ctx context.Context) (apitypes.OpenRPCDocument, error) `perm:"read"`
 	}
 }
 
@@ -420,6 +424,8 @@ type WorkerStruct struct {
 
 		ProcessSession func(context.Context) (uuid.UUID, error) `perm:"admin"`
 		Session        func(context.Context) (uuid.UUID, error) `perm:"admin"`
+
+		Discover func(ctx context.Context) (apitypes.OpenRPCDocument, error) `perm:"read"`
 	}
 }
 
@@ -544,6 +550,10 @@ func (c *CommonStruct) NetPeerInfo(ctx context.Context, p peer.ID) (*api.Extende
 	return c.Internal.NetPeerInfo(ctx, p)
 }
 
+func (c *CommonStruct) Discover(ctx context.Context) (apitypes.OpenRPCDocument, error) {
+	return c.Internal.Discover(ctx)
+}
+
 // ID implements API.ID
 func (c *CommonStruct) ID(ctx context.Context) (peer.ID, error) {
 	return c.Internal.ID(ctx)
@@ -1612,6 +1622,10 @@ func (c *StorageMinerStruct) CheckProvable(ctx context.Context, pp abi.Registere
 	return c.Internal.CheckProvable(ctx, pp, sectors, expensive)
 }
 
+func (c *StorageMinerStruct) Discover(ctx context.Context) (apitypes.OpenRPCDocument, error) {
+	return c.Internal.Discover(ctx)
+}
+
 // WorkerStruct
 
 func (w *WorkerStruct) Version(ctx context.Context) (api.Version, error) {
@@ -1710,6 +1724,10 @@ func (w *WorkerStruct) Session(ctx context.Context) (uuid.UUID, error) {
 	return w.Internal.Session(ctx)
 }
 
+func (c *WorkerStruct) Discover(ctx context.Context) (apitypes.OpenRPCDocument, error) {
+	return c.Internal.Discover(ctx)
+}
+
 func (g GatewayStruct) ChainGetBlockMessages(ctx context.Context, c cid.Cid) (*api.BlockMessages, error) {
 	return g.Internal.ChainGetBlockMessages(ctx, c)
 }

api/docgen-openrpc/cmd/docgen_openrpc.go

@@ -0,0 +1,77 @@
+package main
+
+import (
+	"compress/gzip"
+	"encoding/json"
+	"io"
+	"log"
+	"os"
+
+	"github.com/filecoin-project/lotus/api/apistruct"
+	docgen_openrpc "github.com/filecoin-project/lotus/api/docgen-openrpc"
+)
+
+/*
+main defines a small program that writes an OpenRPC document describing
+a Lotus API to stdout.
+
+If the first argument is "miner", the document will describe the StorageMiner API.
+If not (no, or any other args), the document will describe the Full API.
+
+Use:
+
+		go run ./api/openrpc/cmd ["api/api_full.go"|"api/api_storage.go"|"api/api_worker.go"] ["FullNode"|"StorageMiner"|"WorkerAPI"]
+
+	With gzip compression: a '-gzip' flag is made available as an optional third argument. Note that position matters.
+
+		go run ./api/openrpc/cmd ["api/api_full.go"|"api/api_storage.go"|"api/api_worker.go"] ["FullNode"|"StorageMiner"|"WorkerAPI"] -gzip
+
+*/
+
+func main() {
+	doc := docgen_openrpc.NewLotusOpenRPCDocument()
+
+	switch os.Args[2] {
+	case "FullNode":
+		doc.RegisterReceiverName("Filecoin", &apistruct.FullNodeStruct{})
+	case "StorageMiner":
+		doc.RegisterReceiverName("Filecoin", &apistruct.StorageMinerStruct{})
+	case "WorkerAPI":
+		doc.RegisterReceiverName("Filecoin", &apistruct.WorkerStruct{})
+	}
+
+	out, err := doc.Discover()
+	if err != nil {
+		log.Fatalln(err)
+	}
+
+	var jsonOut []byte
+	var writer io.WriteCloser
+
+	// Use os.Args to handle a somewhat hacky flag for the gzip option.
+	// Could use flags package to handle this more cleanly, but that requires changes elsewhere
+	// the scope of which just isn't warranted by this one use case which will usually be run
+	// programmatically anyways.
+	if len(os.Args) > 3 && os.Args[3] == "-gzip" {
+		jsonOut, err = json.Marshal(out)
+		if err != nil {
+			log.Fatalln(err)
+		}
+		writer = gzip.NewWriter(os.Stdout)
+	} else {
+		jsonOut, err = json.MarshalIndent(out, "", "    ")
+		if err != nil {
+			log.Fatalln(err)
+		}
+		writer = os.Stdout
+	}
+
+	_, err = writer.Write(jsonOut)
+	if err != nil {
+		log.Fatalln(err)
+	}
+	err = writer.Close()
+	if err != nil {
+		log.Fatalln(err)
+	}
+}