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:
1and1.0are different names. A language with one number type must say which it meant.-0.0and0.0are 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.