vexil_runtime/lib.rs
1//! # vexil-runtime
2//!
3//! Runtime support library for [Vexil](https://github.com/vexil-lang/vexil)
4//! generated code. Provides the [`Pack`] and [`Unpack`] traits plus
5//! [`BitWriter`] / [`BitReader`] for LSB-first bit-packed encoding and decoding.
6//!
7//! This crate is a dependency of code generated by `vexilc codegen`. You
8//! generally don't use it directly — the generated `Pack` and `Unpack` impls
9//! call into it.
10//!
11//! ## Encoding Model
12//!
13//! - Sub-byte fields are packed LSB-first within each byte
14//! - Multi-byte integers use little-endian byte order
15//! - `@varint` fields use unsigned LEB128
16//! - `@zigzag` fields use ZigZag encoding + LEB128
17//! - Strings and byte arrays are length-prefixed with LEB128
18
19pub mod bit_reader;
20pub mod bit_writer;
21pub mod error;
22pub mod handshake;
23pub mod leb128;
24pub mod traits;
25pub mod zigzag;
26
27pub use bit_reader::BitReader;
28pub use bit_writer::BitWriter;
29pub use error::{DecodeError, EncodeError};
30pub use handshake::{HandshakeResult, SchemaHandshake};
31pub use traits::{Pack, Unpack};
32
33/// Maximum allowed byte length for strings and byte arrays (64 MiB).
34///
35/// Decoding a string or `bytes` field whose LEB128 length prefix exceeds this
36/// value produces [`DecodeError::LimitExceeded`].
37pub const MAX_BYTES_LENGTH: u64 = 1 << 26;
38
39/// Maximum allowed element count for collections (16 M items).
40///
41/// Used by generated code to cap list/map sizes during decoding.
42pub const MAX_COLLECTION_COUNT: u64 = 1 << 24;
43
44/// Maximum number of bytes consumed when reading a LEB128 length prefix.
45///
46/// Limits the length prefix to at most 4 bytes (values up to 2^28 - 1).
47pub const MAX_LENGTH_PREFIX_BYTES: u8 = 4;
48
49/// Maximum nesting depth for recursive types.
50///
51/// [`BitReader::enter_recursive`] returns [`DecodeError::RecursionLimitExceeded`]
52/// when the depth exceeds this value.
53pub const MAX_RECURSION_DEPTH: u32 = 64;