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 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 explicit-length strings, bytes, maps and lists will be accepted by Decode;
- only tag 42 is accepted, and it must parse as a CID;
- only 64 bit floats will be emitted by Encode.
DecodeOptions.RelaxedDecode can be used to accept some legacy non-canonical CBOR forms and can disable some strictness checks. Indefinite-length CBOR is rejected even in relaxed mode.
Decode strictness is part of ongoing cross-implementation DAG-CBOR correctness work: non-minimal integer and other CBOR header encodings are rejected, NaN and Infinity are rejected, duplicate map keys are rejected, and undefined is coerced to null.
Some DAG-CBOR strictness rules are not yet enforced on decode: map keys are not required to be sorted, and non-64-bit floats are accepted. With RelaxedDecode, duplicate map keys are also accepted by this decoder.
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.
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
- type EncodeOptions
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidMultibase = errors.New("invalid multibase on IPLD link") ErrAllocationBudgetExceeded = errors.New("message structure demanded too many resources to process") ErrDecodeDepthExceeded = errors.New("message structure exceeded maximum nesting depth") ErrTrailingBytes = errors.New("unexpected content after end of cbor object") )
Functions ¶
func Decode ¶ added in v0.9.0
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 ¶ added in v0.9.0
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 ¶ added in v0.16.0
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 ¶
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 ¶ added in v0.11.0
type DecodeOptions struct {
// If true, parse DAG-CBOR tag(42) as Link nodes, otherwise reject them
AllowLinks bool
// RelaxedDecode allows some legacy non-canonical CBOR forms that are not
// valid DAG-CBOR: non-minimal integer and length encodings, and NaN and
// Infinity values.
//
// Indefinite-length CBOR is always rejected, even in relaxed mode.
// Undefined values are coerced to null for compatibility with existing IPLD
// data. Non-64-bit floats, unsorted map keys, and duplicate map keys are accepted.
RelaxedDecode bool
// If true, the decoder stops reading from the stream at the end of a full,
// valid CBOR object. This may be useful for parsing a stream of undelimited
// CBOR objects.
// As per standard IPLD behavior, in the default mode the parser considers the
// entire block to be part of the CBOR object and will error if there is
// extraneous data after the end of the object.
DontParseBeyondEnd bool
// AllocationBudget sets the maximum budget for the decoder. The budget is
// decremented as the decoder allocates resources (nodes, map entries, list
// elements, string/bytes content). If the budget is exhausted, the decoder
// returns ErrAllocationBudgetExceeded.
//
// When zero, a default budget is used which is generous for typical IPLD
// block sizes.
AllocationBudget int64
// MaxCollectionPrealloc sets the maximum size hint passed to
// BeginMap/BeginList. CBOR headers declare collection sizes upfront;
// this caps the initial allocation while collections grow dynamically
// as entries are decoded.
//
// When zero, a default of 1024 is used.
MaxCollectionPrealloc int64
// MaxDepth sets the maximum nesting depth for decoded structures. If the
// decoder encounters a map or list nested beyond this depth, it returns
// ErrDecodeDepthExceeded.
//
// When zero, a default of 1024 is used.
MaxDepth int64
}
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 ¶ added in v0.11.0
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 ¶ added in v0.11.0
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.
Source Files