From 9f5914daf7841d111ce090c3214a39035e653261 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Thu, 14 Dec 2017 23:55:24 +0100 Subject: [PATCH 1/5] coreapi: Basic object API implementation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit License: MIT Signed-off-by: Łukasz Magiera This commit was moved from ipfs/interface-go-ipfs-core@52f5b7ce1f8cc0503ec9d9ce070afdee7997049c This commit was moved from ipfs/boxo@f10a09d9b25f8ec1a43f7e93f9fe182ca5ef82ff --- core/coreiface/interface.go | 42 +++++++++++++++++++------------------ 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/core/coreiface/interface.go b/core/coreiface/interface.go index 720f935e2..2c31d01b1 100644 --- a/core/coreiface/interface.go +++ b/core/coreiface/interface.go @@ -191,27 +191,29 @@ 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) -// } +//TODO: Should this use paths instead of cids? +type ObjectAPI interface { + New(ctx context.Context) (Node, error) + Put(context.Context, Node) error + Get(context.Context, Path) (Node, error) + Data(context.Context, Path) (io.Reader, error) + Links(context.Context, Path) ([]*Link, error) + Stat(context.Context, Path) (*ObjectStat, error) -// type ObjectStat struct { -// Cid cid.Cid -// NumLinks int -// BlockSize int -// LinksSize int -// DataSize int -// CumulativeSize int -// } + AddLink(ctx context.Context, base Path, name string, child Path, create bool) (Node, error) //TODO: make create optional + RmLink(context.Context, Path, string) (Node, error) + AppendData(context.Context, Path, io.Reader) (Node, error) + SetData(context.Context, Path, io.Reader) (Node, error) +} + +type ObjectStat struct { + Cid *cid.Cid + NumLinks int + BlockSize int + LinksSize int + DataSize int + CumulativeSize int +} var ErrIsDir = errors.New("object is a directory") var ErrOffline = errors.New("can't resolve, ipfs node is offline") From b031da2463b9041ca7d09064746067a69b8ae7f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Fri, 22 Dec 2017 17:22:53 +0100 Subject: [PATCH 2/5] coreapi: Object api review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit License: MIT Signed-off-by: Łukasz Magiera This commit was moved from ipfs/interface-go-ipfs-core@3b4b26deb1bc75aefe85df809afca5e3e09f71c6 This commit was moved from ipfs/boxo@85688ca1e91bcfa3cc7441142e5391b760b2b43c --- core/coreiface/interface.go | 10 ++++-- core/coreiface/options/object.go | 56 ++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+), 3 deletions(-) create mode 100644 core/coreiface/options/object.go diff --git a/core/coreiface/interface.go b/core/coreiface/interface.go index 2c31d01b1..db993a5c3 100644 --- a/core/coreiface/interface.go +++ b/core/coreiface/interface.go @@ -193,14 +193,18 @@ type KeyAPI interface { //TODO: Should this use paths instead of cids? type ObjectAPI interface { - New(ctx context.Context) (Node, error) - Put(context.Context, Node) error + New(context.Context, ...options.ObjectNewOption) (Node, error) + WithType(string) options.ObjectNewOption + + Put(context.Context, Node) (Path, error) Get(context.Context, Path) (Node, error) Data(context.Context, Path) (io.Reader, error) Links(context.Context, Path) ([]*Link, error) Stat(context.Context, Path) (*ObjectStat, error) - AddLink(ctx context.Context, base Path, name string, child Path, create bool) (Node, error) //TODO: make create optional + AddLink(ctx context.Context, base Path, name string, child Path, opts ...options.ObjectAddLinkOption) (Node, error) + WithCreate(create bool) options.ObjectAddLinkOption + RmLink(context.Context, Path, string) (Node, error) AppendData(context.Context, Path, io.Reader) (Node, error) SetData(context.Context, Path, io.Reader) (Node, error) diff --git a/core/coreiface/options/object.go b/core/coreiface/options/object.go new file mode 100644 index 000000000..6a144ab2b --- /dev/null +++ b/core/coreiface/options/object.go @@ -0,0 +1,56 @@ +package options + +type ObjectNewSettings struct { + Type string +} + +type ObjectAddLinkSettings struct { + Create bool +} + +type ObjectNewOption func(*ObjectNewSettings) 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 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) WithCreate(create bool) ObjectAddLinkOption { + return func(settings *ObjectAddLinkSettings) error { + settings.Create = create + return nil + } +} From a806b175fa13ec957955c7678a8165d6c1ef25fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Tue, 2 Jan 2018 21:22:20 +0100 Subject: [PATCH 3/5] coreapi: object docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit License: MIT Signed-off-by: Łukasz Magiera This commit was moved from ipfs/interface-go-ipfs-core@55c56578038a9e748aa996f7f9cb7dc1b546f1ac This commit was moved from ipfs/boxo@36545a88bcc2f636493de49939e8105d7fd1977c --- core/coreiface/interface.go | 55 ++++++++++++++++++++++++++++++++----- 1 file changed, 48 insertions(+), 7 deletions(-) diff --git a/core/coreiface/interface.go b/core/coreiface/interface.go index db993a5c3..7809c8b99 100644 --- a/core/coreiface/interface.go +++ b/core/coreiface/interface.go @@ -191,31 +191,72 @@ type KeyAPI interface { Remove(ctx context.Context, name string) (Path, error) } -//TODO: Should this use paths instead of cids? +// 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 node into merkledag Put(context.Context, Node) (Path, error) + + // 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) (Node, error) + + // WithCreate is an option for AddLink which specifies whether create required + // directories for the child WithCreate(create bool) options.ObjectAddLinkOption - RmLink(context.Context, Path, string) (Node, error) + // RmLink removes a link from the node + RmLink(ctx context.Context, base Path, link string) (Node, error) + + // AppendData appends data to the node AppendData(context.Context, Path, io.Reader) (Node, error) + + // SetData sets the data contained in the node SetData(context.Context, Path, io.Reader) (Node, error) } +// ObjectStat provides information about dag nodes type ObjectStat struct { - Cid *cid.Cid - NumLinks int - BlockSize int - LinksSize int - DataSize int + // 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 node CumulativeSize int } From 540ec53bf8308b9b45d1ebbfc6e23d775ec779f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Thu, 4 Jan 2018 17:20:16 +0100 Subject: [PATCH 4/5] coreapi: implement object.Put MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit License: MIT Signed-off-by: Łukasz Magiera This commit was moved from ipfs/interface-go-ipfs-core@104bc87d13e259e45b68c3d00231e140a7b88fb6 This commit was moved from ipfs/boxo@8162a16f7c173b07fa645d5a20121f1ad29e5198 --- core/coreiface/interface.go | 15 +++++++++++++-- core/coreiface/options/object.go | 26 ++++++++++++++++++++++++++ 2 files changed, 39 insertions(+), 2 deletions(-) diff --git a/core/coreiface/interface.go b/core/coreiface/interface.go index 7809c8b99..3e0e3d460 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) @@ -205,8 +208,16 @@ type ObjectAPI interface { // * 'unixfs-dir' - Empty UnixFS directory WithType(string) options.ObjectNewOption - // Put imports the node into merkledag - Put(context.Context, Node) (Path, error) + // 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 // Get returns the node for the path Get(context.Context, Path) (Node, error) diff --git a/core/coreiface/options/object.go b/core/coreiface/options/object.go index 6a144ab2b..fe86a1cde 100644 --- a/core/coreiface/options/object.go +++ b/core/coreiface/options/object.go @@ -4,11 +4,16 @@ type ObjectNewSettings struct { Type string } +type ObjectPutSettings struct { + InputEnc 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) { @@ -25,6 +30,20 @@ func ObjectNewOptions(opts ...ObjectNewOption) (*ObjectNewSettings, error) { return options, nil } +func ObjectPutOptions(opts ...ObjectPutOption) (*ObjectPutSettings, error) { + options := &ObjectPutSettings{ + InputEnc: "json", + } + + 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, @@ -48,6 +67,13 @@ func (api *ObjectOptions) WithType(t string) ObjectNewOption { } } +func (api *ObjectOptions) WithInputEnc(e string) ObjectPutOption { + return func(settings *ObjectPutSettings) error { + settings.InputEnc = e + return nil + } +} + func (api *ObjectOptions) WithCreate(create bool) ObjectAddLinkOption { return func(settings *ObjectAddLinkSettings) error { settings.Create = create From a8a84d5b1bc8125a5113e80b994193e8f3fab9de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Fri, 5 Jan 2018 01:13:07 +0100 Subject: [PATCH 5/5] coreapi: object API tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit License: MIT Signed-off-by: Łukasz Magiera This commit was moved from ipfs/interface-go-ipfs-core@858d49b07c296b36a58fa4d4469f5e08a9f9b5e7 This commit was moved from ipfs/boxo@d878d812272fc70b7e3e799f139056885dab474f --- core/coreiface/interface.go | 18 +++++++++++++----- core/coreiface/options/object.go | 9 +++++++++ 2 files changed, 22 insertions(+), 5 deletions(-) diff --git a/core/coreiface/interface.go b/core/coreiface/interface.go index 3e0e3d460..9dca7f3c9 100644 --- a/core/coreiface/interface.go +++ b/core/coreiface/interface.go @@ -219,6 +219,14 @@ type ObjectAPI interface { // * "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) @@ -234,20 +242,20 @@ type ObjectAPI interface { // 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) (Node, error) + 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) (Node, error) + RmLink(ctx context.Context, base Path, link string) (Path, error) // AppendData appends data to the node - AppendData(context.Context, Path, io.Reader) (Node, error) + AppendData(context.Context, Path, io.Reader) (Path, error) // SetData sets the data contained in the node - SetData(context.Context, Path, io.Reader) (Node, error) + SetData(context.Context, Path, io.Reader) (Path, error) } // ObjectStat provides information about dag nodes @@ -267,7 +275,7 @@ type ObjectStat struct { // DataSize is the size of data block section DataSize int - // CumulativeSize is size of node + // CumulativeSize is size of the tree (BlockSize + link sizes) CumulativeSize int } diff --git a/core/coreiface/options/object.go b/core/coreiface/options/object.go index fe86a1cde..9c8c9a9dd 100644 --- a/core/coreiface/options/object.go +++ b/core/coreiface/options/object.go @@ -6,6 +6,7 @@ type ObjectNewSettings struct { type ObjectPutSettings struct { InputEnc string + DataType string } type ObjectAddLinkSettings struct { @@ -33,6 +34,7 @@ func ObjectNewOptions(opts ...ObjectNewOption) (*ObjectNewSettings, error) { func ObjectPutOptions(opts ...ObjectPutOption) (*ObjectPutSettings, error) { options := &ObjectPutSettings{ InputEnc: "json", + DataType: "text", } for _, opt := range opts { @@ -74,6 +76,13 @@ func (api *ObjectOptions) WithInputEnc(e string) ObjectPutOption { } } +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