wire_codec/
lib.rs

1//! # wire-codec
2//!
3//! A runtime-agnostic toolkit for binary framing and codec composition.
4//!
5//! `wire-codec` provides the primitives you need to build a binary protocol:
6//! zero-copy buffer cursors, variable-length integer codecs, bit-level
7//! cursors, and frame extraction strategies. It allocates nothing on the
8//! encode or decode path, depends on nothing at runtime, and compiles on
9//! `no_std` targets when the `std` feature is disabled.
10//!
11//! # When to reach for this crate
12//!
13//! Pick `wire-codec` when you need to:
14//!
15//! - Implement a custom binary protocol over any transport that delivers
16//!   contiguous byte slices (TCP, UDP, in-memory queue, shared memory,
17//!   serial link).
18//! - Frame a byte stream into discrete messages using a length prefix or
19//!   a delimiter, with bounded memory per frame.
20//! - Encode and decode integers compactly via LEB128 varint and zigzag.
21//! - Pack tagged fields into a record with bit-level precision.
22//!
23//! You probably want a higher-level serialization crate (`serde`, `prost`,
24//! `bincode`) if you need a derive macro, schema evolution, or
25//! introspection. This crate is the layer underneath.
26//!
27//! # Module map
28//!
29//! | Module | Provides |
30//! | ------ | -------- |
31//! | [`buf`] | [`ReadBuf`] and [`WriteBuf`], the zero-copy byte cursors every other module is built on. |
32//! | [`error`] | [`Error`] and [`Result`], the crate-wide error contract. |
33//! | [`traits`] | [`Encode`] and [`Decode`], the codec trait pair. |
34//! | [`varint`] | Unsigned LEB128 varint for `u32` and `u64`. |
35//! | [`zigzag`] | Signed-to-unsigned mapping for compact signed varints. |
36//! | [`bitfield`] | [`BitReader`] and [`BitWriter`] for MSB-first packed bits. |
37//! | [`framing`] | The [`Framer`][`framing::Framer`] trait plus [`LengthPrefixed`][`framing::LengthPrefixed`] and [`Delimited`][`framing::Delimited`] strategies. |
38//!
39//! # Example
40//!
41//! Length-prefix a payload, then read it back:
42//!
43//! ```
44//! use wire_codec::WriteBuf;
45//! use wire_codec::framing::{Endian, Framer, LengthPrefixed, LengthWidth};
46//!
47//! let framer = LengthPrefixed::new(LengthWidth::U16, Endian::Big);
48//!
49//! let mut out = [0u8; 32];
50//! let mut buf = WriteBuf::new(&mut out);
51//! framer.write_frame(b"ping", &mut buf).unwrap();
52//! let n = buf.position();
53//!
54//! let frame = framer.next_frame(&out[..n]).unwrap().unwrap();
55//! assert_eq!(frame.payload(), b"ping");
56//! ```
57//!
58//! # Stability
59//!
60//! From `1.0.0` onward, the public API is frozen. Subsequent `1.x` releases
61//! add only bug fixes, performance improvements, and non-breaking additions:
62//!
63//! - New [`Error`] variants ([`Error`] is `#[non_exhaustive]`).
64//! - New [`framing::LengthWidth`] widths ([`framing::LengthWidth`] is
65//!   `#[non_exhaustive]`).
66//! - New methods on existing types.
67//! - Additional features behind feature flags.
68//!
69//! Any breaking change requires a `2.0` release.
70//!
71//! # Feature flags
72//!
73//! | Feature | Default | Effect |
74//! | ------- | ------- | ------ |
75//! | `std`   | yes     | Adds `impl std::error::Error for Error`. Drop this feature for `no_std` targets. |
76//!
77//! # License
78//!
79//! Dual-licensed under Apache-2.0 OR MIT.
80
81#![doc(html_root_url = "https://docs.rs/wire-codec")]
82#![cfg_attr(docsrs, feature(doc_cfg))]
83#![cfg_attr(not(feature = "std"), no_std)]
84// REPS-mandated lint set. Keep aligned with REPS.md "Compiler & Lint Configuration".
85#![deny(warnings)]
86#![deny(missing_docs)]
87#![deny(unsafe_op_in_unsafe_fn)]
88#![deny(unused_must_use)]
89#![deny(unused_results)]
90#![deny(clippy::unwrap_used)]
91#![deny(clippy::expect_used)]
92#![deny(clippy::todo)]
93#![deny(clippy::unimplemented)]
94#![deny(clippy::unreachable)]
95#![deny(clippy::print_stdout)]
96#![deny(clippy::print_stderr)]
97#![deny(clippy::dbg_macro)]
98#![deny(clippy::undocumented_unsafe_blocks)]
99#![deny(clippy::missing_safety_doc)]
100
101pub mod bitfield;
102pub mod buf;
103pub mod error;
104pub mod framing;
105pub mod traits;
106pub mod varint;
107pub mod zigzag;
108
109pub use bitfield::{BitReader, BitWriter};
110pub use buf::{ReadBuf, WriteBuf};
111pub use error::{Error, Result};
112pub use traits::{Decode, Encode};
113
114/// Crate version string, populated by Cargo at build time.
115pub const VERSION: &str = env!("CARGO_PKG_VERSION");
wire_codec/lib.rs

wire_codec/
lib.rs
