Merge pull request #4802 from ipfs/feat/coreapi/split-iface

coreapi: Split the interface into multiple files

core/coreapi/coreapi.go

@@ -24,46 +24,48 @@ func NewCoreAPI(n *core.IpfsNode) coreiface.CoreAPI {
 	return api
 }
 
-// Unixfs returns the UnixfsAPI interface backed by the go-ipfs node
+// Unixfs returns the UnixfsAPI interface implementation backed by the go-ipfs node
 func (api *CoreAPI) Unixfs() coreiface.UnixfsAPI {
 	return (*UnixfsAPI)(api)
 }
 
+// Block returns the BlockAPI interface implementation backed by the go-ipfs node
 func (api *CoreAPI) Block() coreiface.BlockAPI {
 	return &BlockAPI{api, nil}
 }
 
-// Dag returns the DagAPI interface backed by the go-ipfs node
+// Dag returns the DagAPI interface implementation backed by the go-ipfs node
 func (api *CoreAPI) Dag() coreiface.DagAPI {
 	return &DagAPI{api, nil}
 }
 
-// Name returns the NameAPI interface backed by the go-ipfs node
+// Name returns the NameAPI interface implementation backed by the go-ipfs node
 func (api *CoreAPI) Name() coreiface.NameAPI {
 	return &NameAPI{api, nil}
 }
 
-// Key returns the KeyAPI interface backed by the go-ipfs node
+// Key returns the KeyAPI interface implementation backed by the go-ipfs node
 func (api *CoreAPI) Key() coreiface.KeyAPI {
 	return &KeyAPI{api, nil}
 }
 
-//Object returns the ObjectAPI interface backed by the go-ipfs node
+//Object returns the ObjectAPI interface implementation backed by the go-ipfs node
 func (api *CoreAPI) Object() coreiface.ObjectAPI {
 	return &ObjectAPI{api, nil}
 }
 
+// Pin returns the PinAPI interface implementation backed by the go-ipfs node
 func (api *CoreAPI) Pin() coreiface.PinAPI {
 	return &PinAPI{api, nil}
 }
 
 // ResolveNode resolves the path `p` using Unixfx resolver, gets and returns the
 // resolved Node.
-func (api *CoreAPI) ResolveNode(ctx context.Context, p coreiface.Path) (coreiface.Node, error) {
+func (api *CoreAPI) ResolveNode(ctx context.Context, p coreiface.Path) (ipld.Node, error) {
 	return resolveNode(ctx, api.node.DAG, api.node.Namesys, p)
 }
 
-func resolveNode(ctx context.Context, ng ipld.NodeGetter, nsys namesys.NameSystem, p coreiface.Path) (coreiface.Node, error) {
+func resolveNode(ctx context.Context, ng ipld.NodeGetter, nsys namesys.NameSystem, p coreiface.Path) (ipld.Node, error) {
 	p, err := resolvePath(ctx, ng, nsys, p)
 	if err != nil {
 		return nil, err

core/coreapi/dag.go

@@ -12,6 +12,7 @@ import (
 	coredag "github.com/ipfs/go-ipfs/core/coredag"
 
 	cid "gx/ipfs/QmcZfnkapfECQGcLZaf9B79NRg7cRa9EnZh4LSbkCzwNvY/go-cid"
+	ipld "gx/ipfs/Qme5bWv7wtjUNGsK2BNGVUFPKiuxWrsqrtvYwCLRw8YFES/go-ipld-format"
 )
 
 type DagAPI struct {
@@ -50,7 +51,7 @@ func (api *DagAPI) Put(ctx context.Context, src io.Reader, opts ...caopts.DagPut
 }
 
 // Get resolves `path` using Unixfs resolver, returns the resolved Node.
-func (api *DagAPI) Get(ctx context.Context, path coreiface.Path) (coreiface.Node, error) {
+func (api *DagAPI) Get(ctx context.Context, path coreiface.Path) (ipld.Node, error) {
 	return api.core().ResolveNode(ctx, path)
 }
 

core/coreapi/interface/block.go

@@ -0,0 +1,49 @@
+package iface
+
+import (
+	"context"
+	"io"
+
+	options "github.com/ipfs/go-ipfs/core/coreapi/interface/options"
+)
+
+// BlockStat contains information about a block
+type BlockStat interface {
+	// Size is the size of a block
+	Size() int
+
+	// Path returns path to the block
+	Path() Path
+}
+
+// BlockAPI specifies the interface to the block layer
+type BlockAPI interface {
+	// Put imports raw block data, hashing it using specified settings.
+	Put(context.Context, io.Reader, ...options.BlockPutOption) (Path, error)
+
+	// WithFormat is an option for Put which specifies the multicodec to use to
+	// serialize the object. Default is "v0"
+	WithFormat(codec string) options.BlockPutOption
+
+	// WithHash is an option for Put which specifies the multihash settings to use
+	// when hashing the object. Default is mh.SHA2_256 (0x12).
+	// If mhLen is set to -1, default length for the hash will be used
+	WithHash(mhType uint64, mhLen int) options.BlockPutOption
+
+	// Get attempts to resolve the path and return a reader for data in the block
+	Get(context.Context, Path) (io.Reader, error)
+
+	// Rm removes the block specified by the path from local blockstore.
+	// By default an error will be returned if the block can't be found locally.
+	//
+	// NOTE: If the specified block is pinned it won't be removed and no error
+	// will be returned
+	Rm(context.Context, Path, ...options.BlockRmOption) error
+
+	// WithForce is an option for Rm which, when set to true, will ignore
+	// non-existing blocks
+	WithForce(force bool) options.BlockRmOption
+
+	// Stat returns information on
+	Stat(context.Context, Path) (BlockStat, error)
+}

core/coreapi/interface/coreapi.go

@@ -0,0 +1,40 @@
+// Package iface defines IPFS Core API which is a set of interfaces used to
+// interact with IPFS nodes.
+package iface
+
+import (
+	"context"
+
+	ipld "gx/ipfs/Qme5bWv7wtjUNGsK2BNGVUFPKiuxWrsqrtvYwCLRw8YFES/go-ipld-format"
+)
+
+// CoreAPI defines an unified interface to IPFS for Go programs
+type CoreAPI interface {
+	// Unixfs returns an implementation of Unixfs API
+	Unixfs() UnixfsAPI
+
+	// Block returns an implementation of Block API
+	Block() BlockAPI
+
+	// Dag returns an implementation of Dag API
+	Dag() DagAPI
+
+	// Name returns an implementation of Name API
+	Name() NameAPI
+
+	// Key returns an implementation of Key API
+	Key() KeyAPI
+
+	// Pin returns an implementation of Pin API
+	Pin() PinAPI
+
+	// ObjectAPI returns an implementation of Object API
+	Object() ObjectAPI
+
+	// ResolvePath resolves the path using Unixfs resolver
+	ResolvePath(context.Context, Path) (Path, error)
+
+	// ResolveNode resolves the path (if not resolved already) using Unixfs
+	// resolver, gets and returns the resolved Node
+	ResolveNode(context.Context, Path) (ipld.Node, error)
+}

core/coreapi/interface/dag.go

@@ -0,0 +1,42 @@
+package iface
+
+import (
+	"context"
+	"io"
+
+	options "github.com/ipfs/go-ipfs/core/coreapi/interface/options"
+
+	ipld "gx/ipfs/Qme5bWv7wtjUNGsK2BNGVUFPKiuxWrsqrtvYwCLRw8YFES/go-ipld-format"
+)
+
+// DagAPI specifies the interface to IPLD
+type DagAPI interface {
+	// Put inserts data using specified format and input encoding.
+	// Unless used with WithCodec or WithHash, the defaults "dag-cbor" and
+	// "sha256" are used.
+	Put(ctx context.Context, src io.Reader, opts ...options.DagPutOption) (Path, error)
+
+	// WithInputEnc is an option for Put which specifies the input encoding of the
+	// data. Default is "json", most formats/codecs support "raw"
+	WithInputEnc(enc string) options.DagPutOption
+
+	// WithCodec is an option for Put which specifies the multicodec to use to
+	// serialize the object. Default is cid.DagCBOR (0x71)
+	WithCodec(codec uint64) options.DagPutOption
+
+	// WithHash is an option for Put which specifies the multihash settings to use
+	// when hashing the object. Default is based on the codec used
+	// (mh.SHA2_256 (0x12) for DagCBOR). If mhLen is set to -1, default length for
+	// the hash will be used
+	WithHash(mhType uint64, mhLen int) options.DagPutOption
+
+	// Get attempts to resolve and get the node specified by the path
+	Get(ctx context.Context, path Path) (ipld.Node, error)
+
+	// Tree returns list of paths within a node specified by the path.
+	Tree(ctx context.Context, path Path, opts ...options.DagTreeOption) ([]Path, error)
+
+	// WithDepth is an option for Tree which specifies maximum depth of the
+	// returned tree. Default is -1 (no depth limit)
+	WithDepth(depth int) options.DagTreeOption
+}

core/coreapi/interface/errors.go

@@ -0,0 +1,8 @@
+package iface
+
+import "errors"
+
+var (
+	ErrIsDir   = errors.New("object is a directory")
+	ErrOffline = errors.New("can't resolve, ipfs node is offline")
+)