Merge pull request #4492 from ipfs/feat/coreapi/object

coreapi: Basic object API implementation

interface.go

@@ -64,6 +64,9 @@ type CoreAPI interface {
 	// Key returns an implementation of Key API.
 	Key() KeyAPI
 
+	// ObjectAPI returns an implementation of Object API
+	Object() ObjectAPI
+
 	// ResolvePath resolves the path using Unixfs resolver
 	ResolvePath(context.Context, Path) (Path, error)
 
@@ -191,27 +194,90 @@ type KeyAPI interface {
 	Remove(ctx context.Context, name string) (Path, error)
 }
 
-// type ObjectAPI interface {
-// 	New() (cid.Cid, Object)
-// 	Get(string) (Object, error)
-// 	Links(string) ([]*Link, error)
-// 	Data(string) (Reader, error)
-// 	Stat(string) (ObjectStat, error)
-// 	Put(Object) (cid.Cid, error)
-// 	SetData(string, Reader) (cid.Cid, error)
-// 	AppendData(string, Data) (cid.Cid, error)
-// 	AddLink(string, string, string) (cid.Cid, error)
-// 	RmLink(string, string) (cid.Cid, error)
-// }
-
-// type ObjectStat struct {
-// 	Cid            cid.Cid
-// 	NumLinks       int
-// 	BlockSize      int
-// 	LinksSize      int
-// 	DataSize       int
-// 	CumulativeSize int
-// }
+// ObjectAPI specifies the interface to MerkleDAG and contains useful utilities
+// for manipulating MerkleDAG data structures.
+type ObjectAPI interface {
+	// New creates new, empty (by default) dag-node.
+	New(context.Context, ...options.ObjectNewOption) (Node, error)
+
+	// WithType is an option for New which allows to change the type of created
+	// dag node.
+	//
+	// Supported types:
+	// * 'empty' - Empty node
+	// * 'unixfs-dir' - Empty UnixFS directory
+	WithType(string) options.ObjectNewOption
+
+	// Put imports the data into merkledag
+	Put(context.Context, io.Reader, ...options.ObjectPutOption) (Path, error)
+
+	// WithInputEnc is an option for Put which specifies the input encoding of the
+	// data. Default is "json".
+	//
+	// Supported encodings:
+	// * "protobuf"
+	// * "json"
+	WithInputEnc(e string) options.ObjectPutOption
+
+	// WithDataType specifies the encoding of data field when using Josn or XML
+	// input encoding.
+	//
+	// Supported types:
+	// * "text" (default)
+	// * "base64"
+	WithDataType(t string) options.ObjectPutOption
+
+	// Get returns the node for the path
+	Get(context.Context, Path) (Node, error)
+
+	// Data returns reader for data of the node
+	Data(context.Context, Path) (io.Reader, error)
+
+	// Links returns lint or links the node contains
+	Links(context.Context, Path) ([]*Link, error)
+
+	// Stat returns information about the node
+	Stat(context.Context, Path) (*ObjectStat, error)
+
+	// AddLink adds a link under the specified path. child path can point to a
+	// subdirectory within the patent which must be present (can be overridden
+	// with WithCreate option).
+	AddLink(ctx context.Context, base Path, name string, child Path, opts ...options.ObjectAddLinkOption) (Path, error)
+
+	// WithCreate is an option for AddLink which specifies whether create required
+	// directories for the child
+	WithCreate(create bool) options.ObjectAddLinkOption
+
+	// RmLink removes a link from the node
+	RmLink(ctx context.Context, base Path, link string) (Path, error)
+
+	// AppendData appends data to the node
+	AppendData(context.Context, Path, io.Reader) (Path, error)
+
+	// SetData sets the data contained in the node
+	SetData(context.Context, Path, io.Reader) (Path, error)
+}
+
+// ObjectStat provides information about dag nodes
+type ObjectStat struct {
+	// Cid is the CID of the node
+	Cid *cid.Cid
+
+	// NumLinks is number of links the node contains
+	NumLinks int
+
+	// BlockSize is size of the raw serialized node
+	BlockSize int
+
+	// LinksSize is size of the links block section
+	LinksSize int
+
+	// DataSize is the size of data block section
+	DataSize int
+
+	// CumulativeSize is size of the tree (BlockSize + link sizes)
+	CumulativeSize int
+}
 
 var ErrIsDir = errors.New("object is a directory")
 var ErrOffline = errors.New("can't resolve, ipfs node is offline")

options/object.go

+package options
+
+type ObjectNewSettings struct {
+	Type string
+}
+
+type ObjectPutSettings struct {
+	InputEnc string
+	DataType string
+}
+
+type ObjectAddLinkSettings struct {
+	Create bool
+}
+
+type ObjectNewOption func(*ObjectNewSettings) error
+type ObjectPutOption func(*ObjectPutSettings) error
+type ObjectAddLinkOption func(*ObjectAddLinkSettings) error
+
+func ObjectNewOptions(opts ...ObjectNewOption) (*ObjectNewSettings, error) {
+	options := &ObjectNewSettings{
+		Type: "empty",
+	}
+
+	for _, opt := range opts {
+		err := opt(options)
+		if err != nil {
+			return nil, err
+		}
+	}
+	return options, nil
+}
+
+func ObjectPutOptions(opts ...ObjectPutOption) (*ObjectPutSettings, error) {
+	options := &ObjectPutSettings{
+		InputEnc: "json",
+		DataType: "text",
+	}
+
+	for _, opt := range opts {
+		err := opt(options)
+		if err != nil {
+			return nil, err
+		}
+	}
+	return options, nil
+}
+
+func ObjectAddLinkOptions(opts ...ObjectAddLinkOption) (*ObjectAddLinkSettings, error) {
+	options := &ObjectAddLinkSettings{
+		Create: false,
+	}
+
+	for _, opt := range opts {
+		err := opt(options)
+		if err != nil {
+			return nil, err
+		}
+	}
+	return options, nil
+}
+
+type ObjectOptions struct{}
+
+func (api *ObjectOptions) WithType(t string) ObjectNewOption {
+	return func(settings *ObjectNewSettings) error {
+		settings.Type = t
+		return nil
+	}
+}
+
+func (api *ObjectOptions) WithInputEnc(e string) ObjectPutOption {
+	return func(settings *ObjectPutSettings) error {
+		settings.InputEnc = e
+		return nil
+	}
+}
+
+func (api *ObjectOptions) WithDataType(t string) ObjectPutOption {
+	return func(settings *ObjectPutSettings) error {
+		settings.DataType = t
+		return nil
+	}
+}
+
+func (api *ObjectOptions) WithCreate(create bool) ObjectAddLinkOption {
+	return func(settings *ObjectAddLinkSettings) error {
+		settings.Create = create
+		return nil
+	}
+}