reliakit_codec/format.rs
1//! Canonical binary format rules.
2//!
3//! Version 0.1 intentionally defines one binary representation per supported
4//! value:
5//!
6//! - integers are fixed-width little-endian,
7//! - `bool` is exactly `0x00` or `0x01`,
8//! - strings are UTF-8 bytes prefixed by a `u32` little-endian byte length,
9//! - vectors are prefixed by a `u32` little-endian item count,
10//! - `Option<T>` and `Result<T, E>` use one-byte tags,
11//! - fixed arrays and tuples encode fields in declaration order.
12//!
13//! # Stability
14//!
15//! This format is stable: the same value always encodes to the same bytes, and
16//! the layouts above will not change in a backwards-incompatible way without a
17//! major version bump. Encoded bytes are safe to persist, hash, and sign.
18//!
19//! Floats, pointer-sized integers, hash maps, unordered maps, schema
20//! negotiation, and non-canonical alternatives are not part of this initial
21//! format. They are omitted because their representation or ordering can be
22//! platform-dependent, ambiguous, or outside this crate's first-version scope.
23//!
24//! The vector length prefix is an item count, not a byte length. Decoding a
25//! vector performs work proportional to that count. For element types that
26//! decode from zero bytes (such as `[u8; 0]`), the declared count is therefore
27//! not bounded by the remaining input length; only decode lengths you are
28//! willing to iterate over from untrusted sources, or frame such inputs before
29//! decoding.
30//!
31//! Generic fixed-array decoding (`[T; N]`) requires the `alloc` feature in this
32//! version because the crate forbids unsafe code and Rust 1.85 does not provide
33//! a stable fallible array initializer. In no-alloc builds, `[u8; N]` decoding is
34//! available because it can be filled directly from the source without heap
35//! allocation.
36
37/// Tag used for `false`.
38pub const BOOL_FALSE: u8 = 0x00;
39/// Tag used for `true`.
40pub const BOOL_TRUE: u8 = 0x01;
41/// Tag used for `None`.
42pub const OPTION_NONE: u8 = 0x00;
43/// Tag used for `Some`.
44pub const OPTION_SOME: u8 = 0x01;
45/// Tag used for `Ok`.
46pub const RESULT_OK: u8 = 0x00;
47/// Tag used for `Err`.
48pub const RESULT_ERR: u8 = 0x01;