macula_cbor_nif (macula v10.14.1)
View SourceCBOR (RFC 8949) pack/unpack for the Macula mesh wire protocol.
Replaces the pure-Erlang msgpack hex package as the per-frame serialization layer. CBOR was chosen because it composes with UCAN, DID, COSE, and IPLD (all of which the platform already uses for identity and auth), has deterministic encoding rules in the spec (RFC 8949 §4.2.1), and is an IETF standard.
Implementation: thin wrapper over the macula_cbor_nif Rust NIF backed by the ciborium crate. There is NO Erlang fallback — the protocol layer is in the same critical path as macula_quic, which also has no Erlang fallback. Failing fast at NIF-load time is the right behavior; a slow Erlang fallback would silently halve throughput.
Type mapping (Erlang -> CBOR):
atom (true, false) -> bool atom (nil, undefined) -> null atom (other) -> text string (LOSSY — decoder returns binary) binary -> byte string (round-trips as binary) integer -> uint / negative int float -> float list -> array tuple -> array (LOSSY — decoder returns list) map -> map
Atoms and tuples lose their type information across the wire — same constraint as the previous msgpack-era protocol.
Summary
Functions
Encode an Erlang term to CBOR bytes. Crashes ({nif_error, ...}) if the NIF failed to load — intentional, see module-level note on no-fallback.
Deterministic CBOR (RFC 8949 §4.2.1) encode, matching macula_record_cbor:encode/1 byte-for-byte — see that module and native/macula_cbor_nif/src/deterministic.rs for the exact value model. NOT wired into macula_frame/macula_record yet: additive only, pending exhaustive differential testing against the existing Erlang codec. Crashes on unencodable input, same as macula_record_cbor:encode/1 (no clause matches).
Decode CBOR bytes to an Erlang term. Returns an ok-tuple on success or an error-tuple on malformed input.
Deterministic CBOR decode, matching macula_record_cbor:decode/1 exactly, including its strict "no trailing bytes" requirement and its crash-on-malformed-input contract (this raises, it does not return an error tuple).
Functions
-spec is_nif_loaded() -> boolean().
Encode an Erlang term to CBOR bytes. Crashes ({nif_error, ...}) if the NIF failed to load — intentional, see module-level note on no-fallback.
-spec pack_deterministic(macula_record_cbor:value()) -> binary().
Deterministic CBOR (RFC 8949 §4.2.1) encode, matching macula_record_cbor:encode/1 byte-for-byte — see that module and native/macula_cbor_nif/src/deterministic.rs for the exact value model. NOT wired into macula_frame/macula_record yet: additive only, pending exhaustive differential testing against the existing Erlang codec. Crashes on unencodable input, same as macula_record_cbor:encode/1 (no clause matches).
Decode CBOR bytes to an Erlang term. Returns an ok-tuple on success or an error-tuple on malformed input.
-spec unpack_deterministic(binary()) -> macula_record_cbor:value().
Deterministic CBOR decode, matching macula_record_cbor:decode/1 exactly, including its strict "no trailing bytes" requirement and its crash-on-malformed-input contract (this raises, it does not return an error tuple).