graven/
lib.rs

1//! Runtime for **Graven**, a zero-copy binary serialization format.
2//!
3//! Messages are read in place: accessors read fields straight from the buffer, and
4//! strings and byte slices borrow from it. The wire format is specified in
5//! `docs/spec/graven-format-v1.md` (format v1, frozen) and pinned by the conformance
6//! vectors in `testvectors/v1/`.
7//!
8//! Most code does not use this crate directly: the `gravenc` compiler turns a `.graven` schema
9//! into typed readers, verified views and writers built on top of it. This crate provides:
10//!
11//! - [`Builder`] and the writers ([`TableW`], [`FixedW`], list writers): build a message
12//!   into a pooled buffer ([`BufPool`], [`SimplePool`]);
13//! - [`TableRef`] and the list readers: checked, lazy reads, where every access validates
14//!   what it touches and returns an [`Error`] instead of misbehaving;
15//! - [`VerifyCtx`]: the depth and budget limits of a full `verify` (spec §7), which
16//!   generated code runs once before handing out a verified view;
17//! - [`envelope`]: the optional envelope for disk and network (magic, version, schema id,
18//!   CRC32C), including iteration over concatenated envelopes;
19//! - [`validate`]: the results of the validation rules a schema declares
20//!   (`range`, `len`, `finite`, `known`, `check(name)`);
21//! - [`rt`]: support items called by generated code.
22//!
23//! The crate is `no_std` (with `alloc`) when the default `std` feature is disabled.
24//!
25//! ```
26//! use bytes::BytesMut;
27//! use graven::envelope::{decode, encode, schema_id};
28//!
29//! let id = schema_id("bank.Transaction");
30//! let mut out = BytesMut::new();
31//! encode(id, b"payload bytes", &mut out)?;
32//! let env = decode(&out)?;
33//! assert_eq!((env.schema_id, env.payload), (id, &b"payload bytes"[..]));
34//! # Ok::<(), graven::Error>(())
35//! ```
36#![cfg_attr(not(feature = "std"), no_std)]
37#![forbid(unsafe_op_in_unsafe_fn)]
38// The only `unsafe` is `TableRef::str_unchecked` and the support for generated verified
39// views in `rt` (`FromVerified`, `VListR`, `VStrList`); each carries its own `#[allow]`.
40#![deny(unsafe_code)]
41extern crate alloc;
42
43mod crc;
44mod error;
45pub mod rt;
46mod le;
47pub mod read;
48
49pub use bytes::Bytes;
50pub use crc::crc32c;
51pub use error::Error;
52pub use le::Le;
53pub use read::{Bit, Frames, ScalarList, StrList, TableList, TableRef, frames};
54#[cfg(feature = "std")]
55pub use pool::SimplePool;
56pub use pool::BufPool;
57pub use write::{Builder, FixedListW, FixedW, ScalarListW, StreamListW, TableListW, TableW};
58pub mod envelope;
59pub mod pool;
60pub mod write;
61pub mod verify;
62pub use verify::VerifyCtx;
63pub mod validate;
64pub use validate::{Invalid, Rule, ValidateError};
graven/lib.rs

graven/
lib.rs
