diff --git a/core/coreiface/interface.go b/core/coreiface/interface.go index 6e00d51ab..ddcdc8db6 100644 --- a/core/coreiface/interface.go +++ b/core/coreiface/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) -// } +// 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) -// type ObjectStat struct { -// Cid cid.Cid -// NumLinks int -// BlockSize int -// LinksSize int -// DataSize int -// CumulativeSize int -// } + // 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") diff --git a/core/coreiface/options/object.go b/core/coreiface/options/object.go new file mode 100644 index 000000000..9c8c9a9dd --- /dev/null +++ b/core/coreiface/options/object.go @@ -0,0 +1,91 @@ +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 + } +}