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 framing;
23pub mod geometric;
24pub mod handshake;
25pub mod leb128;
26pub mod traits;
27pub mod zigzag;
28
29pub use bit_reader::BitReader;
30pub use bit_writer::BitWriter;
31pub use error::{DecodeError, EncodeError};
32pub use framing::{FrameReader, FrameWriter};
33pub use geometric::{Mat3, Mat4, Quat, Vec2, Vec3, Vec4};
34pub use handshake::{HandshakeResult, SchemaHandshake};
35pub use traits::{Pack, Unpack};
36
37/// Maximum allowed byte length for strings and byte arrays (64 MiB).
38///
39/// Decoding a string or `bytes` field whose LEB128 length prefix exceeds this
40/// value produces [`DecodeError::LimitExceeded`].
41pub const MAX_BYTES_LENGTH: u64 = 1 << 26;
42
43/// Maximum allowed element count for collections (16 M items).
44///
45/// Used by generated code to cap list/map sizes during decoding.
46pub const MAX_COLLECTION_COUNT: u64 = 1 << 24;
47
48/// Maximum number of bytes consumed when reading a LEB128 length prefix.
49///
50/// Limits the length prefix to at most 4 bytes (values up to 2^28 - 1).
51pub const MAX_LENGTH_PREFIX_BYTES: u8 = 4;
52
53/// Maximum nesting depth for recursive types.
54///
55/// [`BitReader::enter_recursive`] returns [`DecodeError::RecursionLimitExceeded`]
56/// when the depth exceeds this value.
57pub const MAX_RECURSION_DEPTH: u32 = 64;