const-cbor 0.3.0

A const-first, no_std, allocation-free CBOR (RFC 8949) codec with no dependencies and no unsafe.
Documentation
  • Coverage
  • 100%
    103 out of 103 items documented2 out of 73 items with examples
  • Size
  • Source code size: 1.0 MB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 672.4 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 3s Average build duration of successful builds.
  • all releases: 2s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • larrydewey/const-cbor
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • larrydewey

const-cbor

CI RFC 8949 no_std unsafe forbidden deps

A const-first, allocation-free CBOR codec implementing RFC 8949. Encode and decode CBOR directly between Rust values and byte buffers — no value tree, no heap, no unsafe, no traits, no dependencies.

flash on Cortex-M3 (thumbv7m-none-eabi, `profile.size`: opt-level=z,
fat LTO, panic=abort, symbols stripped), linked `.text` + `.rodata`,
inputs black_boxed so nothing is const-folded away:

  core only ................................ 3,148 B
  + float (encode + decode exercised) ...... 4,964 B
  + indefinite ............................. 4,496 B
  + bignum ................................. 3,994 B
  + canonical .............................. 4,000 B
  + deterministic (incl. indefinite) ....... 4,496 B
  + diagnostic ............................. 7,462 B
  + diagnostic + float decimal text ........ 21,578 B
  everything enabled and used .............. 24,102 B

Features you do not enable — or call — cost nothing.

Reproduce with the checked-in probe:
`cargo build --profile size --target thumbv7m-none-eabi --example cbor-size`
then `size target/thumbv7m-none-eabi/size/examples/cbor-size`. The same
probe builds and runs on x86_64 (`cargo run --profile size --example cbor-size`),
where the linked `const_cbor` symbols can be inspected directly with
`nm target/size/examples/cbor-size | grep const_cbor`.

Why another CBOR crate?

const-cbor serde-based stacks
Dependencies 0 dozens (transitively)
Heap allocation never pervasive
unsafe forbidden by lint present in deps
Compile-time work heads, widths, lengths, whole items via const fn runtime
Binary size (Cortex-M) ~1–4 KB tens of KB
API model concrete-typed methods, chaining trait impls + derive

Need serde? The const-cbor-serde companion crate adds Serialize/Deserialize adapters over this core — the core itself keeps zero dependencies.

The design pushes work into the compiler: argument widths, head bytes, and encoded sizes are const fns that LLVM folds for statically known inputs — entire items can be built during compilation:

use const_cbor::encode::consts;

/// [-10] — one byte of output, built and checked at compile time.
const NEG_TEN: ([u8; 2], usize) = {
    let mut buf = [0u8; 2];
    let n = consts::put_i64(&mut buf, -10);
    (buf, n)
};
assert_eq!(&NEG_TEN.0[..NEG_TEN.1], &[0x29]);

(Overflowing the buffer here is a compile error, not a runtime panic.)

Quick start

[dependencies]
const-cbor = "0.2"

Encode

use const_cbor::Encoder;

let mut buf = [0u8; 64];
let mut enc = Encoder::new(&mut buf);

// [1000, "hello"]
enc.array_len(2).unwrap();
enc.u32(1000).unwrap();
enc.str("hello").unwrap();

let n = enc.written();
assert_eq!(&buf[..n], &[0x82, 0x19, 0x03, 0xe8, 0x65,
                        b'h', b'e', b'l', b'l', b'o']);

Methods return Result<&mut Self, _> so calls chain; containers declare their length and you write their items in wire order. Every call either writes completely or writes nothing (OUT_OF_SPACE keeps the cursor).

Decode

use const_cbor::{Decoder};

let mut dec = Decoder::new(&buf[..n]);
assert_eq!(dec.array_len().unwrap(), 2);
assert_eq!(dec.u32().unwrap(), 1000);
assert_eq!(dec.str().unwrap(), "hello");   // zero-copy borrow
assert!(dec.is_empty());

Strings and byte strings borrow from your input buffer. Typed getters are range-checked, never truncating.

Features

Nothing beyond the core is compiled unless you ask:

[dependencies]
const-cbor = { version = "0.2", features = ["float", "indefinite"] }
Feature Capability RFC section
(default) Integers (full u64/i64 space), strings, bytes, arrays, maps, tags, simple values, booleans, null/undefined, structural skip §3.1, §5
float f16/f32/f64 with provably-lossless width narrowing and canonical NaN §3.3, App. D
indefinite Indefinite-length strings (chunk-wise, zero-copy iterators) and open-ended arrays/maps §3.2
raw RawValue — validated zero-copy handle to any complete item; lazily re-decodable, verbatim re-emittable §5.4
stream StreamDecoder: incremental decode across arbitrary feed boundaries into one caller-provided scratch buffer —
canonical MapBuilder<N>: deterministic map key ordering without allocation §4.2
diagnostic Human-readable rendering of CBOR into RFC 8949 §8 diagnostic notation §8
bignum Arbitrary-precision integers via tags 2/3, zero-copy magnitudes §3.4.3
deterministic Strict RFC §4.2 validation: minimal widths, shortest floats, sorted map keys §4.2

Serde support

The companion crate serde/ (workspace member) adds Serialize / Deserialize adapters over the core codec:

[dependencies]
const-cbor-serde = { path = "serde" }   # or from the registry
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct Point { x: i32, y: i32 }

let bytes = const_cbor_serde::to_vec(&Point { x: 1, y: -2 })?;
let p: Point = const_cbor_serde::from_slice(&bytes)?;

Representation follows ecosystem conventions (serde_cbor / ciborium): structs are CBOR maps keyed by field name, enums are externally tagged, sequences use indefinite lengths. The core crate itself remains dependency-free. | std | Host conveniences; the core never requires it | — |

Feature examples

Indefinite strings, chunked both ways:

# use const_cbor::Encoder;
let mut buf = [0u8; 32];
let mut e = Encoder::new(&mut buf);
e.str_indef(&["strea", "ming"]).unwrap();   // (_ "strea", "ming")

let mut d = const_cbor::Decoder::new(&buf);
let mut chunks = d.str_chunks().unwrap();
while let Some(chunk) = chunks.next() {
    // borrows straight from `buf`
}

Canonical map ordering without a heap:

use const_cbor::{Decoder, Encoder};
use const_cbor::canonical::MapBuilder;

let mut buf = [0u8; 64];
let mut enc = Encoder::new(&mut buf);
enc.map_len(2).unwrap();
let mut m = MapBuilder::<2>::new(&mut enc);
m.add(|k| k.str("bb"), |v| v.u8(1)).unwrap();
m.add(|k| k.str("aa"), |v| v.u8(2)).unwrap();
m.finish(&mut [0u8; 32]).unwrap();          // reorders into canonical order

let mut dec = Decoder::new(&buf);
dec.map_len().unwrap();
assert_eq!(dec.str().unwrap(), "aa");       // "aa" pair now comes first

// Note: canonical order is *bytewise over encoded keys* — the length
// prefix participates. "zeta" (4 bytes) canonically precedes "alpha"
// (5 bytes), unlike plain ASCII ordering.

Streaming decode over packet-sized feeds:

use const_cbor::stream::StreamDecoder;

let mut scratch = [0u8; 256];               // bounds max item size
let mut stream = StreamDecoder::new(&mut scratch);
stream.feed(&wire_fragments[0]);
stream.feed(&wire_fragments[1]);
if let Ok(Some(mut item)) = stream.take_item() {
    // `item` is a Decoder over one complete CBOR data item
}

Human-readable diagnostic output:

use const_cbor::{Decoder, Encoder};

let mut buf = [0u8; 64];
let mut enc = Encoder::new(&mut buf);
enc.array_len(3).unwrap();
enc.str("a").unwrap().i16(-25_000).unwrap().bool(true).unwrap();
let (cbor, n) = enc.finish();

let mut text = [0u8; 128];
let pretty = const_cbor::diagnostic::render(&cbor[..n], &mut text).unwrap();
assert_eq!(pretty, "[\"a\", -25000, true]");

Passing unknown fields through untouched:

let raw = decoder.raw_value()?;     // validates structure only
encoder.raw(&raw)?;                 // re-emits verbatim later

Guarantees

Property Guarantee
Panics never at runtime — malformed input is always Err(Error)
Allocation never; links only core, no allocator touched
Unsafe #![forbid(unsafe_code)]
Recursion none — skip uses a fixed 32-entry stack
Failure atomicity failed encoder calls leave the buffer unchanged
Zero-copy string/byte payloads borrow from caller memory
Errors single-byte Copy codes implementing core::error::Error

Strictness follows RFC 8949 §4.2.1: non-minimal integer encodings are accepted on input (preferred form is a SHOULD); genuinely invalid forms — reserved additional information, two-byte simples below 32, non-UTF-8 text, stray breaks — are rejected.

Documentation

Development

cargo test                          # core test suite
cargo test --all-features           # everything
cargo clippy --all-features --all-targets
cargo fmt --check
cargo run  --example const_eval     # compile-time encoding demo
cargo fuzz run decode               # fuzzing (cargo-fuzz)

CI runs tests across every feature combination, clippy with -D warnings, cross-builds for thumbv7m-none-eabi / aarch64-unknown-none, and gates release binary size.

Minimum supported Rust: 1.85 (edition 2024, stable only).

License

MIT OR Apache-2.0