From a724bbca37e9e0c5238392a68ed5cbd59eff71b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Thu, 20 Sep 2018 23:44:49 +0200 Subject: [PATCH] coreapi unixfs: docs on options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit License: MIT Signed-off-by: Łukasz Magiera --- core/coreapi/interface/options/unixfs.go | 29 +++++++++++++++++++++++- core/coreapi/unixfs.go | 2 +- core/coreapi/unixfs_test.go | 2 +- 3 files changed, 30 insertions(+), 3 deletions(-) diff --git a/core/coreapi/interface/options/unixfs.go b/core/coreapi/interface/options/unixfs.go index 6abfd9622ab..9b003e1aff9 100644 --- a/core/coreapi/interface/options/unixfs.go +++ b/core/coreapi/interface/options/unixfs.go @@ -13,7 +13,7 @@ type Layout int const ( BalancedLayout Layout = iota - TrickleLeyout + TrickleLayout ) type UnixfsAddSettings struct { @@ -95,6 +95,8 @@ type unixfsOpts struct{} var Unixfs unixfsOpts +// CidVersion specifies which CID version to use. Defaults to 0 unless an option +// that depends on CIDv1 is passed. func (unixfsOpts) CidVersion(version int) UnixfsAddOption { return func(settings *UnixfsAddSettings) error { settings.CidVersion = version @@ -102,6 +104,9 @@ func (unixfsOpts) CidVersion(version int) UnixfsAddOption { } } +// Hash function to use. Implies CIDv1 if not set to sha2-256 (default). +// +// Table of functions is declared in https://github.com/multiformats/go-multihash/blob/master/multihash.go func (unixfsOpts) Hash(mhtype uint64) UnixfsAddOption { return func(settings *UnixfsAddSettings) error { settings.MhType = mhtype @@ -109,6 +114,8 @@ func (unixfsOpts) Hash(mhtype uint64) UnixfsAddOption { } } +// RawLeaves specifies whether to use raw blocks for leaves (data nodes with no +// links) instead of wrapping them with unixfs structures. func (unixfsOpts) RawLeaves(enable bool) UnixfsAddOption { return func(settings *UnixfsAddSettings) error { settings.RawLeaves = enable @@ -117,6 +124,11 @@ func (unixfsOpts) RawLeaves(enable bool) UnixfsAddOption { } } +// InlineLimit sets the amount of bytes below which blocks will be encoded +// directly into CID instead of being stored and addressed by it's hash +// +// Note that while there is no hard limit on the number of bytes here, it should +// be kept at something reasonably low like 32b (default for 'ipfs add') func (unixfsOpts) InlineLimit(limit int) UnixfsAddOption { return func(settings *UnixfsAddSettings) error { settings.InlineLimit = limit @@ -124,6 +136,11 @@ func (unixfsOpts) InlineLimit(limit int) UnixfsAddOption { } } +// Chunker specifies settings for the chunking algorithm to use. +// +// Default: size-262144, formats: +// size-[bytes] - Simple chunker splitting data into blocks of n bytes +// rabin-[min]-[avg]-[max] - Rabin chunker func (unixfsOpts) Chunker(chunker string) UnixfsAddOption { return func(settings *UnixfsAddSettings) error { settings.Chunker = chunker @@ -131,6 +148,10 @@ func (unixfsOpts) Chunker(chunker string) UnixfsAddOption { } } +// Layout tells the adder how to balance data between leaves. +// options.BalancedLayout is the default, it's optimized for static seekable +// files. +// options.TrickleLayout is optimized for streaming data, func (unixfsOpts) Layout(layout Layout) UnixfsAddOption { return func(settings *UnixfsAddSettings) error { settings.Layout = layout @@ -138,6 +159,7 @@ func (unixfsOpts) Layout(layout Layout) UnixfsAddOption { } } +// Pin tells the adder to pin the file root recursively after adding func (unixfsOpts) Pin(pin bool) UnixfsAddOption { return func(settings *UnixfsAddSettings) error { settings.Pin = pin @@ -145,6 +167,8 @@ func (unixfsOpts) Pin(pin bool) UnixfsAddOption { } } +// HashOnly will make the adder calculate data hash without storing it in the +// blockstore or announcing it to the network func (unixfsOpts) HashOnly(hashOnly bool) UnixfsAddOption { return func(settings *UnixfsAddSettings) error { settings.OnlyHash = hashOnly @@ -152,6 +176,9 @@ func (unixfsOpts) HashOnly(hashOnly bool) UnixfsAddOption { } } +// Local will add the data to blockstore without announcing it to the network +// +// Note that this doesn't prevent other nodes from getting this data func (unixfsOpts) Local(local bool) UnixfsAddOption { return func(settings *UnixfsAddSettings) error { settings.Local = local diff --git a/core/coreapi/unixfs.go b/core/coreapi/unixfs.go index 399e2688885..d6800ff77bd 100644 --- a/core/coreapi/unixfs.go +++ b/core/coreapi/unixfs.go @@ -78,7 +78,7 @@ func (api *UnixfsAPI) Add(ctx context.Context, r io.ReadCloser, opts ...options. switch settings.Layout { case options.BalancedLayout: // Default - case options.TrickleLeyout: + case options.TrickleLayout: fileAdder.Trickle = true default: return nil, fmt.Errorf("unknown layout: %d", settings.Layout) diff --git a/core/coreapi/unixfs_test.go b/core/coreapi/unixfs_test.go index 2c39f7709c3..30b7ccf3507 100644 --- a/core/coreapi/unixfs_test.go +++ b/core/coreapi/unixfs_test.go @@ -202,7 +202,7 @@ func TestAdd(t *testing.T) { name: "addChunksTrickle", data: strings.Repeat("aoeuidhtns", 200), path: "/ipfs/QmNNhDGttafX3M1wKWixGre6PrLFGjnoPEDXjBYpTv93HP", - opts: []options.UnixfsAddOption{options.Unixfs.Chunker("size-4"), options.Unixfs.Layout(options.TrickleLeyout)}, + opts: []options.UnixfsAddOption{options.Unixfs.Chunker("size-4"), options.Unixfs.Layout(options.TrickleLayout)}, }, // Local {