# v0.2.0 - Foundation API
`wire-codec` graduates from scaffold to a fully usable foundation. The public
API surface for binary framing and codec composition is now defined,
implemented, and documented, with an end-to-end pipeline test verifying the
pieces fit together.
This release is the first one a downstream crate can build against. The shape
of the API is intended to remain stable through `0.5.0`; subsequent releases
will fill in performance, ergonomics, and additional encodings rather than
reshuffle types.
## Highlights
- **Zero-copy cursors.** `ReadBuf` and `WriteBuf` wrap borrowed byte slices
with tracked positions. Decoders hand back sub-slices that borrow from the
caller's input, so no allocation occurs in the read or write path.
- **Codec trait pair.** `Encode` and `Decode<'de>` are small, allocation-free,
and composable. The `'de` lifetime lets decoders return borrowed payloads
without copying.
- **Varint and zigzag.** LEB128 unsigned varint (`u32` / `u64`) with strict
overflow detection, plus zigzag mapping for signed integers, all
`no_std`-compatible and `const fn` where the math allows.
- **Bitfield cursors.** `BitReader` and `BitWriter` pack arbitrary-width bit
fields, MSB-first, into and out of a borrowed byte buffer. Useful for
protocols that share a byte across multiple fields.
- **Two ready-made framers.** `LengthPrefixed` (u8 / u16 / u32 width, big or
little endian, configurable payload cap) and `Delimited` (one or multiple
delimiter bytes with a bounded scan window). Both implement the same
`Framer` trait, so callers can swap strategies without changing protocol
code.
- **End-to-end smoke test.** A single test exercises `Encode` + `Decode` +
`varint` + `zigzag` + `LengthPrefixed`, demonstrating that the pieces
compose into a working pipeline.
## What you can build with this release
- **Custom binary protocols** carried over any transport that delivers a
contiguous byte slice (sockets buffered into a `Vec<u8>`, in-memory queues,
shared-memory buffers).
- **Length-prefixed message framing** for TCP-style streams, with a
configurable payload cap to bound memory consumption per frame.
- **Newline-delimited or CR/LF-delimited line protocols** with backpressure-
friendly partial-input handling (`next_frame` returns `None` on incomplete
input rather than blocking or erroring).
- **Compact integer encodings** for protocols where wire size matters: varint
for unsigned, zigzag-then-varint for signed.
- **Bit-packed records** where multiple small fields share a byte and where
the protocol pre-dates byte-aligned encoding.
## Public API summary
| `wire_codec` (root re-exports) | `Error`, `Result`, `ReadBuf`, `WriteBuf`, `Encode`, `Decode`, `BitReader`, `BitWriter`, `VERSION` |
| `wire_codec::error` | `Error`, `Result` |
| `wire_codec::buf` | `ReadBuf`, `WriteBuf` |
| `wire_codec::traits` | `Encode`, `Decode` |
| `wire_codec::varint` | `encode_u32`, `encode_u64`, `decode_u32`, `decode_u64`, `encoded_len_u32`, `encoded_len_u64`, `MAX_LEN_U16`, `MAX_LEN_U32`, `MAX_LEN_U64` |
| `wire_codec::zigzag` | `encode_i32`, `decode_i32`, `encode_i64`, `decode_i64` |
| `wire_codec::bitfield` | `BitReader`, `BitWriter`, `MAX_BIT_WIDTH` |
| `wire_codec::framing` | `Frame`, `Framer`, `LengthPrefixed`, `LengthWidth`, `Endian`, `Delimited` |
See `docs/API.md` for full signatures, behaviour notes, and runnable examples
for every item above.
## Notable design decisions
- **Runtime-agnostic.** No async, no `std::io`. Everything operates on
borrowed byte slices. Callers integrate with whatever transport they
choose.
- **`no_std` by default.** The `std` feature only enables
`impl std::error::Error for Error`. The crate compiles and tests with
`--no-default-features`.
- **Zero dependencies.** No third-party crates pulled in. The footprint is
fully self-contained.
- **Const-friendly.** Constructors and width helpers are `const fn` so
framers and constants can be declared at file scope.
- **Edition aligned to MSRV.** The crate was authored against edition 2024
but declared an MSRV of 1.75; that combination is rejected by Cargo
(edition 2024 needs 1.85+). The edition is now `2021`, matching the
declared MSRV.
## Verification
This release was built and tested green under the directives matrix:
- `cargo build` (default features)
- `cargo build --no-default-features`
- `cargo build --all-features`
- `cargo +1.75 build --all-features`
- `cargo +1.75 test --all-features`
- `cargo fmt --all -- --check`
- `cargo clippy --all-targets --all-features -- -D warnings`
- `cargo clippy --no-default-features --all-targets -- -D warnings`
- `cargo test --all-features` — 25 unit + 3 integration + 18 doctests = 46 tests pass
## Compatibility
- Edition: `2021`
- MSRV: Rust `1.75`
- License: Apache-2.0 OR MIT
- Platforms: Linux, macOS, Windows (CI on all three, stable + 1.75)
## What is next
Phase 0.5.0 (Implementation) builds on this foundation:
- Property tests covering varint round-trip, zigzag inverse, and framer
scan invariants.
- Integration tests across realistic protocol shapes (length-prefixed
newline-delimited hybrid, prefix-then-varint records).
- Benchmark harness with baselines committed.
- Documentation drafts polished into reference-grade rustdoc.
See `.dev/ROADMAP.md` for the full plan.