dagcbor

Documentation

Overview

The dagcbor package provides a DAG-CBOR codec implementation.

The Encode and Decode functions match the codec.Encoder and codec.Decoder function interfaces, and can be registered with the go-ipld-prime/multicodec package for easy usage with systems such as CIDs.

Importing this package will automatically have the side-effect of registering Encode and Decode with the go-ipld-prime/multicodec registry, associating them with the standard multicodec indicator numbers for DAG-CBOR.

This implementation follows most of the rules of DAG-CBOR, namely:

- by and large, it does emit and parse CBOR!

- only explicit-length maps and lists will be emitted by Encode;

- only tag 42 is accepted, and it must parse as a CID;

- only 64 bit floats will be emitted by Encode.

This implementation is also not strict about certain rules:

- Encode is order-passthrough when emitting maps (it does not sort, nor abort in error if unsorted data is encountered). To emit sorted data, the node should be sorted before applying the Encode function.

- Decode is order-passthrough when parsing maps (it does not sort, nor abort in error if unsorted data is encountered). To be strict about the ordering of data, additional validation must be applied to the result of the Decode function.

- Decode will accept indeterminate length lists and maps without complaint. (These should not be allowed according to the DAG-CBOR spec, nor will the Encode function re-emit such values, so this behavior should almost certainly be seen as a bug.)

- Decode does not consistently verify that ints and floats use the smallest representation possible (or, the 64-bit version, in the float case). (Only these numeric encodings should be allowed according to the DAG-CBOR spec, and the Encode function will not re-emit variations, so this behavior should almost certainly be seen as a bug.)

A note for future contributors: some functions in this package expose references to packages from the refmt module, and/or use them internally. Please avoid adding new code which expands the visibility of these references. In future work, we'd like to reduce or break this relationship entirely (in part, to reduce dependency sprawl, and in part because several of the imprecisions noted above stem from that library's lack of strictness).

Index

• Variables
• func Decode(na datamodel.NodeAssembler, r io.Reader) error
• func Encode(n datamodel.Node, w io.Writer) error
• func EncodedLength(n datamodel.Node) (int64, error)
• func Marshal(n datamodel.Node, sink shared.TokenSink, options EncodeOptions) error
• func Unmarshal(na datamodel.NodeAssembler, tokSrc shared.TokenSource, options DecodeOptions) error
• type DecodeOptions
  • func (cfg DecodeOptions) Decode(na datamodel.NodeAssembler, r io.Reader) error
• type EncodeOptions
  • func (cfg EncodeOptions) Encode(n datamodel.Node, w io.Writer) error

Variables

var (
	ErrInvalidMultibase         = errors.New("invalid multibase on IPLD link")
	ErrAllocationBudgetExceeded = errors.New("message structure demanded too many resources to process")
	ErrTrailingBytes            = errors.New("unexpected content after end of cbor object")
)

Functions

func Decode

func Decode(na datamodel.NodeAssembler, r io.Reader) error

Decode deserializes data from the given io.Reader and feeds it into the given datamodel.NodeAssembler. Decode fits the codec.Decoder function interface.

A similar function is available on DecodeOptions type if you would like to customize any of the decoding details. This function uses the defaults for the dag-cbor codec (meaning: links (indicated by tag 42) are decoded).

This is the function that will be registered in the default multicodec registry during package init time.

func Encode

func Encode(n datamodel.Node, w io.Writer) error

Encode walks the given datamodel.Node and serializes it to the given io.Writer. Encode fits the codec.Encoder function interface.

A similar function is available on EncodeOptions type if you would like to customize any of the encoding details. This function uses the defaults for the dag-cbor codec (meaning: links are encoded, and map keys are sorted (with RFC7049 ordering!) during encode).

This is the function that will be registered in the default multicodec registry during package init time.

func EncodedLength

func EncodedLength(n datamodel.Node) (int64, error)

EncodedLength will calculate the length in bytes that the encoded form of the provided Node will occupy.

Note that this function requires a full walk of the Node's graph, which may not necessarily be a trivial cost and will incur some allocations. Using this method to calculate buffers to pre-allocate may not result in performance gains, but rather incur an overall cost. Use with care.

func Marshal

func Marshal(n datamodel.Node, sink shared.TokenSink, options EncodeOptions) error

Marshal is a deprecated function. Please consider switching to EncodeOptions.Encode instead.

func Unmarshal

func Unmarshal(na datamodel.NodeAssembler, tokSrc shared.TokenSource, options DecodeOptions) error

Unmarshal is a deprecated function. Please consider switching to DecodeOptions.Decode instead.

Types

type DecodeOptions

type DecodeOptions struct {
	// If true, parse DAG-CBOR tag(42) as Link nodes, otherwise reject them
	AllowLinks bool

	// ExperimentalDeterminism requires decoded DAG-CBOR bytes to be canonical as per
	// the spec. For example, this means that integers and floats be encoded in
	// a particular way, and map keys be sorted.
	//
	// The decoder does not enforce this requirement by default, as the codec
	// was originally implemented without these rules. Because of that, there's
	// a significant amount of published data that isn't canonical but should
	// still decode with the default settings for backwards compatibility.
	//
	// Note that this option is experimental as it only implements partial strictness.
	ExperimentalDeterminism bool
}

DecodeOptions can be used to customize the behavior of a decoding function. The Decode method on this struct fits the codec.Decoder function interface.

func (DecodeOptions) Decode

func (cfg DecodeOptions) Decode(na datamodel.NodeAssembler, r io.Reader) error

Decode deserializes data from the given io.Reader and feeds it into the given datamodel.NodeAssembler. Decode fits the codec.Decoder function interface.

The behavior of the decoder can be customized by setting fields in the DecodeOptions struct before calling this method.

type EncodeOptions

type EncodeOptions struct {
	// If true, allow encoding of Link nodes as CBOR tag(42);
	// otherwise, reject them as unencodable.
	AllowLinks bool

	// Control the sorting of map keys, using one of the `codec.MapSortMode_*` constants.
	MapSortMode codec.MapSortMode
}

EncodeOptions can be used to customize the behavior of an encoding function. The Encode method on this struct fits the codec.Encoder function interface.

func (EncodeOptions) Encode

func (cfg EncodeOptions) Encode(n datamodel.Node, w io.Writer) error

Encode walks the given datamodel.Node and serializes it to the given io.Writer. Encode fits the codec.Encoder function interface.

The behavior of the encoder can be customized by setting fields in the EncodeOptions struct before calling this method.