Skip to main content

Module canonical

freenet_git_encoding

Module canonical 

Source
Expand description

Minimal deterministic CBOR encoder for content-addressed hashes.

Used for the ObjectBundle -> ObjectBundleId derivation so that two independent implementations agree on the bundle id given the same logical contents. We encode by hand rather than depending on a CBOR library so the exact byte format is part of this crate’s wire-format pin and cannot drift due to a transitive dependency upgrade.

§Determinism rules (RFC 8949 §4.2.1 subset)

  • Definite-length items only. Maps and arrays carry their element count in the major-type header.
  • Smallest-encoding-of-integers. A u64 value of 5 is encoded in one byte (0x05), not eight.
  • Map keys sorted by their canonical encoded byte representation. Lexicographic byte order, after each key has been canonically encoded.
  • No floating-point.
  • No tags, no semantic types. A bundle id is a hash of structure, not a typed CBOR document.

Only the subset of CBOR we actually use is implemented:

Major typeUsed for
0 (uint)counts, sizes (u32, u64)
2 (bytes)hash bytes
3 (text)enum variant tags, field labels
4 (array)not used in v1, but encoder ready
5 (map)the structured envelope itself

Structs§

MapBuilder
Builder for a canonical CBOR map.

Enums§

Value
A canonical CBOR value. Use Value::map / Value::text / etc. to build, then Value::encode to serialize.