Skip to content

The CBOR codec

Deterministic CBOR: one value, one encoding, one name.

livery.strongroom.cbor encodes a value to the one byte sequence RFC 8949's core deterministic encoding requirements allow, over a restricted subset, and decodes only that byte sequence. Everything the store hashes and everything the fabric hashes goes through it, so an object has exactly one name and a call has exactly one key. The codec imports only the standard library, and importing the store does not load it: reach it by its own path.

Using it

from livery.strongroom.cbor import CodecError, decode, encode

data = encode({"name": "bun", "size": 41_943_040, "parts": [b"\x00", 1.5]})
value = decode(data)
try:
    decode(b"\x18\x01")  # the integer 1 in two bytes
except CodecError as error:
    print(error)  # not the shortest form: 1 in 1 bytes at offset 0

encode takes an integer within 64 bits, a float, bytes, str, a list, a dict with str keys, a bool or None, nested at most MAX_DEPTH deep, and raises CodecError for anything else. decode returns the same Python types and raises CodecError for any input that is not a deterministic encoding, naming the rule and, where it helps, the offset.

The subset

Value Encoded as
integer, -2^64 to 2^64 - 1 major type 0 or 1, shortest argument
bytes major type 2, definite length
text, valid UTF-8 major type 3, definite length
list major type 4, definite count
dict with text keys major type 5, keys sorted by their encoded bytes
False, True, None f4, f5, f6
float the shortest of half, single and double that is exact; one NaN, f97e00

No tags, no indefinite lengths, no other simple values. The full rules and the refusals are in spec/cbor.md beside the package in the repository, and its vectors in spec/vectors/cbor.json. A vector case pins the one encoding of a value, with a diagnostic string in RFC 8949's notation and, where JSON can carry it, the value; a refusal pins an input or a value that must be refused, by a phrase the error must contain. A second implementation needs about two hundred lines and that file; a general CBOR library's canonical mode is not a substitute until the vectors check it.

Three hazards at the boundary

The encoding is deterministic; these are the places where two values that look equal have two names, and a producer decides at its edge:

  • 1 and 1.0 are different names. A language with one number type must say which it meant.
  • -0.0 and 0.0 are different names.
  • Every NaN encodes to the one canonical NaN; a payload has nowhere to go.

The store's own formats carry integers only, so none of the three reaches them.