Search documentation of macula

# macula_cbor_nif (macula v4.4.1)

View Source

CBOR (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

is_nif_loaded()
nif_pack(Term)
nif_unpack(Bytes)
pack(Term)

Encode an Erlang term to CBOR bytes. Crashes ({nif_error, ...}) if the NIF failed to load — intentional, see module-level note on no-fallback.

unpack(Bytes)

Decode CBOR bytes to an Erlang term. Returns an ok-tuple on success or an error-tuple on malformed input.

# Functions

# is_nif_loaded()

    -spec is_nif_loaded() -> boolean().

# nif_pack(Term)

# nif_unpack(Bytes)

# pack(Term)

    -spec pack(term()) -> binary().

Encode an Erlang term to CBOR bytes. Crashes ({nif_error, ...}) if the NIF failed to load — intentional, see module-level note on no-fallback.

# unpack(Bytes)

    -spec unpack(binary()) -> {ok, term()} | {error, term()}.

Decode CBOR bytes to an Erlang term. Returns an ok-tuple on success or an error-tuple on malformed input.