Documentation ¶
Overview ¶
Package merkledag implements the IPFS Merkle DAG data structures.
Index ¶
- Variables
- func DecodeProtobufBlock(b blocks.Block) (format.Node, error)
- func DecodeRawBlock(block blocks.Block) (format.Node, error)
- func FetchGraph(ctx context.Context, root cid.Cid, serv format.DAGService) error
- func FetchGraphWithDepthLimit(ctx context.Context, root cid.Cid, depthLim int, serv format.DAGService) error
- func NewDAGService(bs bserv.BlockService) *dagService
- func NewReadOnlyDagService(ng ipld.NodeGetter) ipld.DAGService
- func NewSession(ctx context.Context, g ipld.NodeGetter) ipld.NodeGetter
- func PrefixForCidVersion(version int) (cid.Prefix, error)
- func ProtoNodeConverter(b blocks.Block, nd ipld.Node) (legacy.UniversalNode, error)
- func RawNodeConverter(b blocks.Block, nd ipld.Node) (legacy.UniversalNode, error)
- func V0CidPrefix() cid.Prefix
- func V1CidPrefix() cid.Prefix
- func Walk(ctx context.Context, getLinks GetLinks, c cid.Cid, visit func(cid.Cid) bool, ...) error
- func WalkDepth(ctx context.Context, getLinks GetLinks, c cid.Cid, ...) error
- func WrapSession(s *bserv.Session) format.NodeGetter
- type ComboService
- func (cs *ComboService) Add(ctx context.Context, nd ipld.Node) error
- func (cs *ComboService) AddMany(ctx context.Context, nds []ipld.Node) error
- func (cs *ComboService) Get(ctx context.Context, c cid.Cid) (ipld.Node, error)
- func (cs *ComboService) GetMany(ctx context.Context, cids []cid.Cid) <-chan *ipld.NodeOption
- func (cs *ComboService) Remove(ctx context.Context, c cid.Cid) error
- func (cs *ComboService) RemoveMany(ctx context.Context, cids []cid.Cid) error
- type ErrorService
- func (cs *ErrorService) Add(ctx context.Context, nd ipld.Node) error
- func (cs *ErrorService) AddMany(ctx context.Context, nds []ipld.Node) error
- func (cs *ErrorService) Get(ctx context.Context, c cid.Cid) (ipld.Node, error)
- func (cs *ErrorService) GetMany(ctx context.Context, cids []cid.Cid) <-chan *ipld.NodeOption
- func (cs *ErrorService) Remove(ctx context.Context, c cid.Cid) error
- func (cs *ErrorService) RemoveMany(ctx context.Context, cids []cid.Cid) error
- type GetLinks
- type LinkSlice
- type ProgressTracker
- type ProtoNode
- func (n *ProtoNode) AddNodeLink(name string, that format.Node) error
- func (n *ProtoNode) AddRawLink(name string, l *format.Link) error
- func (n *ProtoNode) AsBool() (bool, error)
- func (n *ProtoNode) AsBytes() ([]byte, error)
- func (n *ProtoNode) AsFloat() (float64, error)
- func (n *ProtoNode) AsInt() (int64, error)
- func (n *ProtoNode) AsLink() (ipld.Link, error)
- func (n *ProtoNode) AsString() (string, error)
- func (n *ProtoNode) Cid() cid.Cid
- func (n *ProtoNode) CidBuilder() cid.Builder
- func (n *ProtoNode) Copy() format.Node
- func (n *ProtoNode) Data() []byte
- func (n *ProtoNode) EncodeProtobuf(force bool) ([]byte, error)
- func (n *ProtoNode) GetLinkedNode(ctx context.Context, ds format.DAGService, name string) (format.Node, error)
- func (n *ProtoNode) GetLinkedProtoNode(ctx context.Context, ds format.DAGService, name string) (*ProtoNode, error)
- func (n *ProtoNode) GetNodeLink(name string) (*format.Link, error)
- func (n *ProtoNode) GetPBNode() *pb.PBNode
- func (n *ProtoNode) IsAbsent() bool
- func (n *ProtoNode) IsNull() bool
- func (n *ProtoNode) Kind() ipld.Kind
- func (n *ProtoNode) Length() int64
- func (n *ProtoNode) Links() []*format.Link
- func (n *ProtoNode) ListIterator() ipld.ListIterator
- func (n *ProtoNode) Loggable() map[string]interface{}
- func (n *ProtoNode) LookupByIndex(idx int64) (ipld.Node, error)
- func (n *ProtoNode) LookupByNode(key ipld.Node) (ipld.Node, error)
- func (n *ProtoNode) LookupBySegment(seg ipld.PathSegment) (ipld.Node, error)
- func (n *ProtoNode) LookupByString(key string) (ipld.Node, error)
- func (n *ProtoNode) MapIterator() ipld.MapIterator
- func (n *ProtoNode) Marshal() ([]byte, error)
- func (n *ProtoNode) MarshalJSON() ([]byte, error)
- func (n *ProtoNode) Multihash() mh.Multihash
- func (n *ProtoNode) Prototype() ipld.NodePrototype
- func (n *ProtoNode) RawData() []byte
- func (n *ProtoNode) RemoveNodeLink(name string) error
- func (n *ProtoNode) Resolve(path []string) (interface{}, []string, error)
- func (n *ProtoNode) ResolveLink(path []string) (*format.Link, []string, error)
- func (n *ProtoNode) SetCidBuilder(builder cid.Builder) error
- func (n *ProtoNode) SetData(d []byte)
- func (n *ProtoNode) SetLinks(links []*format.Link) error
- func (n *ProtoNode) Size() (uint64, error)
- func (n *ProtoNode) Stat() (*format.NodeStat, error)
- func (n *ProtoNode) String() string
- func (n *ProtoNode) Tree(p string, depth int) []string
- func (n *ProtoNode) UnmarshalJSON(b []byte) error
- func (n *ProtoNode) UpdateNodeLink(name string, that *ProtoNode) (*ProtoNode, error)
- type RawNode
- func (rn *RawNode) Copy() format.Node
- func (rn *RawNode) Links() []*format.Link
- func (rn *RawNode) MarshalJSON() ([]byte, error)
- func (rn *RawNode) Resolve(path []string) (interface{}, []string, error)
- func (rn *RawNode) ResolveLink(path []string) (*format.Link, []string, error)
- func (rn *RawNode) Size() (uint64, error)
- func (rn *RawNode) Stat() (*format.NodeStat, error)
- func (rn *RawNode) Tree(p string, depth int) []string
- type SessionMaker
- type WalkOption
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotProtobuf = fmt.Errorf("expected protobuf dag node") ErrNotRawNode = fmt.Errorf("expected raw bytes node") ErrLinkNotFound = fmt.Errorf("no link by that name") )
Common errors
var ErrReadOnly = fmt.Errorf("cannot write to readonly DAGService")
ErrReadOnly is used when a read-only datastructure is written to.
Functions ¶
func DecodeProtobufBlock ¶
DecodeProtobufBlock is a block decoder for protobuf IPLD nodes conforming to node.DecodeBlockFunc
func DecodeRawBlock ¶
DecodeRawBlock is a block decoder for raw IPLD nodes conforming to `node.DecodeBlockFunc`.
func FetchGraph ¶
FetchGraph fetches all nodes that are children of the given node
func FetchGraphWithDepthLimit ¶
func FetchGraphWithDepthLimit(ctx context.Context, root cid.Cid, depthLim int, serv format.DAGService) error
FetchGraphWithDepthLimit fetches all nodes that are children to the given node down to the given depth. maxDepth=0 means "only fetch root", maxDepth=1 means "fetch root and its direct children" and so on... maxDepth=-1 means unlimited.
func NewDAGService ¶
func NewDAGService(bs bserv.BlockService) *dagService
NewDAGService constructs a new DAGService (using the default implementation). Note that the default implementation is also an ipld.LinkGetter.
func NewReadOnlyDagService ¶
func NewReadOnlyDagService(ng ipld.NodeGetter) ipld.DAGService
NewReadOnlyDagService takes a NodeGetter, and returns a full DAGService implementation that returns ErrReadOnly when its 'write' methods are invoked.
func NewSession ¶
func NewSession(ctx context.Context, g ipld.NodeGetter) ipld.NodeGetter
NewSession returns a session backed NodeGetter if the given NodeGetter implements SessionMaker.
func PrefixForCidVersion ¶
PrefixForCidVersion returns the Protobuf prefix for a given CID version
func ProtoNodeConverter ¶
func RawNodeConverter ¶
func V1CidPrefix ¶
V1CidPrefix returns a prefix for CIDv1 with the default settings
func Walk ¶
func Walk(ctx context.Context, getLinks GetLinks, c cid.Cid, visit func(cid.Cid) bool, options ...WalkOption) error
WalkGraph will walk the dag in order (depth first) starting at the given root.
func WalkDepth ¶
func WalkDepth(ctx context.Context, getLinks GetLinks, c cid.Cid, visit func(cid.Cid, int) bool, options ...WalkOption) error
WalkDepth walks the dag starting at the given root and passes the current depth to a given visit function. The visit function can be used to limit DAG exploration.
func WrapSession ¶
func WrapSession(s *bserv.Session) format.NodeGetter
WrapSession wraps a blockservice session to satisfy the format.NodeGetter interface
Types ¶
type ComboService ¶
type ComboService struct { Read ipld.NodeGetter Write ipld.DAGService }
ComboService implements ipld.DAGService, using 'Read' for all fetch methods, and 'Write' for all methods that add new objects.
func (*ComboService) GetMany ¶
func (cs *ComboService) GetMany(ctx context.Context, cids []cid.Cid) <-chan *ipld.NodeOption
GetMany fetches nodes using the Read DAGService.
func (*ComboService) RemoveMany ¶
RemoveMany deletes nodes using the Write DAGService.
type ErrorService ¶
type ErrorService struct {
Err error
}
ErrorService implements ipld.DAGService, returning 'Err' for every call.
func (*ErrorService) GetMany ¶
func (cs *ErrorService) GetMany(ctx context.Context, cids []cid.Cid) <-chan *ipld.NodeOption
GetMany many returns the cs.Err.
func (*ErrorService) RemoveMany ¶
RemoveMany returns the cs.Err.
type GetLinks ¶
GetLinks is the type of function passed to the EnumerateChildren function(s) for getting the children of an IPLD node.
func GetLinksDirect ¶
func GetLinksDirect(serv format.NodeGetter) GetLinks
GetLinksDirect creates a function to get the links for a node, from the node, bypassing the LinkService. If the node does not exist locally (and can not be retrieved) an error will be returned.
func GetLinksWithDAG ¶
func GetLinksWithDAG(ng format.NodeGetter) GetLinks
GetLinksWithDAG returns a GetLinks function that tries to use the given NodeGetter as a LinkGetter to get the children of a given IPLD node. This may allow us to traverse the DAG without actually loading and parsing the node in question (if we already have the links cached).
type ProgressTracker ¶
type ProgressTracker struct { Total int // contains filtered or unexported fields }
ProgressTracker is used to show progress when fetching nodes.
func (*ProgressTracker) DeriveContext ¶
func (p *ProgressTracker) DeriveContext(ctx context.Context) context.Context
DeriveContext returns a new context with value "progress" derived from the given one.
func (*ProgressTracker) Increment ¶
func (p *ProgressTracker) Increment()
Increment adds one to the total progress.
func (*ProgressTracker) Value ¶
func (p *ProgressTracker) Value() int
Value returns the current progress.
type ProtoNode ¶
type ProtoNode struct {
// contains filtered or unexported fields
}
ProtoNode represents a node in the IPFS Merkle DAG. nodes have opaque data and a set of navigable links. ProtoNode is a go-ipld-legacy.UniversalNode, meaning it is both a go-ipld-prime node and a go-ipld-format node. ProtoNode maintains compatibility with it's original implementation as a go-ipld-format only node, which included some mutability, namely the the ability to add/remove links in place
TODO: We should be able to eventually replace this implementation with * go-codec-dagpb for basic DagPB encode/decode to go-ipld-prime * go-unixfsnode ADLs for higher level DAGPB functionality For the time being however, go-unixfsnode is read only and this mutable protonode implementation is needed to support go-unixfs, the only library that implements both read and write for UnixFS v1.
func DecodeProtobuf ¶
DecodeProtobuf decodes raw data and returns a new Node instance.
func NodeWithData ¶
NodeWithData builds a new Protonode with the given data.
func (*ProtoNode) AddNodeLink ¶
AddNodeLink adds a link to another node. The link will be added in sorted order.
If sorting has not already been applied to this node (because it was deserialized from a form that did not have sorted links), the links list will be sorted. If a ProtoNode was deserialized from a badly encoded form that did not already have its links sorted, calling AddNodeLink and then RemoveNodeLink for the same link, will not result in an identically encoded form as the links will have been sorted.
func (*ProtoNode) AddRawLink ¶
AddRawLink adds a copy of a link to this node. The link will be added in sorted order.
If sorting has not already been applied to this node (because it was deserialized from a form that did not have sorted links), the links list will be sorted. If a ProtoNode was deserialized from a badly encoded form that did not already have its links sorted, calling AddRawLink and then RemoveNodeLink for the same link, will not result in an identically encoded form as the links will have been sorted.
func (*ProtoNode) Cid ¶
Cid returns the node's Cid, calculated according to its prefix and raw data contents.
Note that this method may return a CID representing a zero-length byte slice if there is an error performing the encode. To check whether such an error may have occurred, use node.EncodeProtobuf(false), instead (or prior to calling RawData) and check for its returned error value; the result of EncodeProtobuf is cached so there is minimal overhead when invoking both methods.
func (*ProtoNode) CidBuilder ¶
CidBuilder returns the CID Builder for this ProtoNode, it is never nil
func (*ProtoNode) Copy ¶
Copy returns a copy of the node. The resulting node will have a properly sorted Links list regardless of whether the original came from a badly serialized form that didn't have a sorted list. NOTE: This does not make copies of Node objects in the links.
func (*ProtoNode) EncodeProtobuf ¶
EncodeProtobuf returns the encoded raw data version of a Node instance. It may use a cached encoded version, unless the force flag is given.
func (*ProtoNode) GetLinkedNode ¶
func (n *ProtoNode) GetLinkedNode(ctx context.Context, ds format.DAGService, name string) (format.Node, error)
GetLinkedNode returns a copy of the IPLD Node with the given name.
func (*ProtoNode) GetLinkedProtoNode ¶
func (n *ProtoNode) GetLinkedProtoNode(ctx context.Context, ds format.DAGService, name string) (*ProtoNode, error)
GetLinkedProtoNode returns a copy of the ProtoNode with the given name.
func (*ProtoNode) GetNodeLink ¶
GetNodeLink returns a copy of the link with the given name.
func (*ProtoNode) GetPBNode ¶
GetPBNode converts *ProtoNode into it's protocol buffer variant. If you plan on mutating the data of the original node, it is recommended that you call ProtoNode.Copy() before calling ProtoNode.GetPBNode()
func (*ProtoNode) IsAbsent ¶
Absent nodes are returned when traversing a struct field that is defined by a schema but unset in the data. (Absent nodes are not possible otherwise; you'll only see them from `schema.TypedNode`.) The absent flag is necessary so iterating over structs can unambiguously make the distinction between values that are present-and-null versus values that are absent.
Absent nodes respond to `Kind()` as `ipld.Kind_Null`, for lack of any better descriptive value; you should therefore always check IsAbsent rather than just a switch on kind when it may be important to handle absent values distinctly.
func (*ProtoNode) Kind ¶
func (n *ProtoNode) Kind() ipld.Kind
Kind returns a value from the Kind enum describing what the essential serializable kind of this node is (map, list, integer, etc). Most other handling of a node requires first switching upon the kind.
func (*ProtoNode) Length ¶
Length returns the length of a list, or the number of entries in a map, or -1 if the node is not of list nor map kind.
func (*ProtoNode) ListIterator ¶
func (n *ProtoNode) ListIterator() ipld.ListIterator
ListIterator returns an iterator which yields key-value pairs traversing the node. If the node kind is anything other than a list, nil will be returned.
The iterator will yield every entry in the list; that is, it can be expected that itr.Next will be called node.Length times before itr.Done becomes true.
func (*ProtoNode) LookupByIndex ¶
LookupByIndex is the equivalent of LookupByString but for indexing into a list. As with LookupByString, the returned Node may be any of the Kind: a primitive (string, int64, etc), a map, a list, or a link.
If the Kind of this Node is not Kind_List, a nil node and an error will be returned.
If idx is out of range, a nil node and an error will be returned.
func (*ProtoNode) LookupByNode ¶
LookupByNode is the equivalent of LookupByString, but takes a reified Node as a parameter instead of a plain string. This mechanism is useful if working with typed maps (if the key types have constraints, and you already have a reified `schema.TypedNode` value, using that value can save parsing and validation costs); and may simply be convenient if you already have a Node value in hand.
(When writing generic functions over Node, a good rule of thumb is: when handling a map, check for `schema.TypedNode`, and in this case prefer the LookupByNode(Node) method; otherwise, favor LookupByString; typically implementations will have their fastest paths thusly.)
func (*ProtoNode) LookupBySegment ¶
LookupBySegment is will act as either LookupByString or LookupByIndex, whichever is contextually appropriate.
Using LookupBySegment may imply an "atoi" conversion if used on a list node, or an "itoa" conversion if used on a map node. If an "itoa" conversion takes place, it may error, and this method may return that error.
func (*ProtoNode) LookupByString ¶
LookupByString looks up a child object in this node and returns it. The returned Node may be any of the Kind: a primitive (string, int64, etc), a map, a list, or a link.
If the Kind of this Node is not Kind_Map, a nil node and an error will be returned.
If the key does not exist, a nil node and an error will be returned.
func (*ProtoNode) MapIterator ¶
func (n *ProtoNode) MapIterator() ipld.MapIterator
Note that when using codegenerated types, there may be a fifth variant of lookup method on maps: `Get($GeneratedTypeKey) $GeneratedTypeValue`! MapIterator returns an iterator which yields key-value pairs traversing the node. If the node kind is anything other than a map, nil will be returned.
The iterator will yield every entry in the map; that is, it can be expected that itr.Next will be called node.Length times before itr.Done becomes true.
func (*ProtoNode) Marshal ¶
Marshal encodes a *Node instance into a new byte slice. The conversion uses an intermediate PBNode.
func (*ProtoNode) MarshalJSON ¶
MarshalJSON returns a JSON representation of the node.
func (*ProtoNode) Multihash ¶
Multihash hashes the encoded data of this node.
Note that this method may return a multihash representing a zero-length byte slice if there is an error performing the encode. To check whether such an error may have occurred, use node.EncodeProtobuf(false), instead (or prior to calling RawData) and check for its returned error value; the result of EncodeProtobuf is cached so there is minimal overhead when invoking both methods.
func (*ProtoNode) Prototype ¶
func (n *ProtoNode) Prototype() ipld.NodePrototype
Prototype returns a NodePrototype which can describe some properties of this node's implementation, and also be used to get a NodeBuilder, which can be use to create new nodes with the same implementation as this one.
For typed nodes, the NodePrototype will also implement schema.Type.
For Advanced Data Layouts, the NodePrototype will encapsulate any additional parameters and configuration of the ADL, and will also (usually) implement NodePrototypeSupportingAmend.
Calling this method should not cause an allocation.
func (*ProtoNode) RawData ¶
RawData returns the encoded byte form of this node.
Note that this method may return an empty byte slice if there is an error performing the encode. To check whether such an error may have occurred, use node.EncodeProtobuf(false), instead (or prior to calling RawData) and check for its returned error value; the result of EncodeProtobuf is cached so there is minimal overhead when invoking both methods.
func (*ProtoNode) RemoveNodeLink ¶
RemoveNodeLink removes a link on this node by the given name. If there are no links with this name, ErrLinkNotFound will be returned. If there are more than one link with this name, they will all be removed.
func (*ProtoNode) ResolveLink ¶
ResolveLink consumes the first element of the path and obtains the link corresponding to it from the node. It returns the link and the path without the consumed element.
func (*ProtoNode) SetCidBuilder ¶
SetCidBuilder sets the CID builder if it is non nil, if nil then it is reset to the default value. An error will be returned if the builder is not usable.
func (*ProtoNode) SetLinks ¶
SetLinks replaces the node links with a copy of the provided links. Sorting will be applied to the list.
func (*ProtoNode) Size ¶
Size returns the total size of the data addressed by node, including the total sizes of references.
func (*ProtoNode) String ¶
String prints the node's Cid.
Note that this method may return a CID representing a zero-length byte slice if there is an error performing the encode. To check whether such an error may have occurred, use node.EncodeProtobuf(false), instead (or prior to calling RawData) and check for its returned error value; the result of EncodeProtobuf is cached so there is minimal overhead when invoking both methods.
func (*ProtoNode) Tree ¶
Tree returns the link names of the ProtoNode. ProtoNodes are only ever one path deep, so anything different than an empty string for p results in nothing. The depth parameter is ignored.
func (*ProtoNode) UnmarshalJSON ¶
UnmarshalJSON reads the node fields from a JSON-encoded byte slice.
func (*ProtoNode) UpdateNodeLink ¶
UpdateNodeLink return a copy of the node with the link name set to point to that. The link will be added in sorted order. If a link of the same name existed, it is removed.
If sorting has not already been applied to this node (because it was deserialized from a form that did not have sorted links), the links list will be sorted in the returned copy.
type RawNode ¶
type RawNode struct { blocks.Block // Always a node/basic Bytes. // We can't reference a specific type, as it's not exposed there. // If we find that the interface indirection really matters, // then we could possibly use dagpb.Bytes. ipld.Node }
RawNode represents a node which only contains data.
func NewRawNode ¶
NewRawNode creates a RawNode using the default sha2-256 hash function.
func NewRawNodeWPrefix ¶
NewRawNodeWPrefix creates a RawNode using the provided cid builder
func (*RawNode) MarshalJSON ¶
MarshalJSON is required for our "ipfs dag" commands.
func (*RawNode) ResolveLink ¶
ResolveLink returns an error.
type SessionMaker ¶
type SessionMaker interface {
Session(context.Context) ipld.NodeGetter
}
SessionMaker is an object that can generate a new fetching session.
type WalkOption ¶
type WalkOption func(*walkOptions)
WalkOption is a setter for walkOptions
func Concurrency ¶
func Concurrency(worker int) WalkOption
Concurrency is a WalkOption indicating that node fetching should be done in parallel, with a specific concurrency factor. NOTE: When using that option, the walk order is *not* guarantee. NOTE: It *does not* make multiple concurrent calls to the passed `visit` function.
func Concurrent ¶
func Concurrent() WalkOption
Concurrent is a WalkOption indicating that node fetching should be done in parallel, with the default concurrency factor. NOTE: When using that option, the walk order is *not* guarantee. NOTE: It *does not* make multiple concurrent calls to the passed `visit` function.
func IgnoreErrors ¶
func IgnoreErrors() WalkOption
IgnoreErrors is a WalkOption indicating that the walk should attempt to continue even when an error occur.
func IgnoreMissing ¶
func IgnoreMissing() WalkOption
IgnoreMissing is a WalkOption indicating that the walk should continue when a node is missing.
func OnError ¶
func OnError(handler func(c cid.Cid, err error) error) WalkOption
OnError is a WalkOption adding a custom error handler. If this handler return a nil error, the walk will continue.
func OnMissing ¶
func OnMissing(callback func(c cid.Cid)) WalkOption
OnMissing is a WalkOption adding a callback that will be triggered on a missing node.
func SkipRoot ¶
func SkipRoot() WalkOption
SkipRoot is a WalkOption indicating that the root node should skipped