v1.0.0 - Stable API

[jamesgober]

v1.0.0 - Stable API

wire-codec reaches 1.0. The public surface is now frozen: every type, trait,
function signature, and observable behaviour will remain stable across the
entire 1.x line. Bug fixes, performance work, and additive features will
continue; breaking changes will not.

This release ships no new functionality on top of 0.9.0. The work in this
release is the polish that justifies the major version: a substantive
README rewrite, a cookbook in the API reference, a fuller crate-level
rustdoc block, and the final benchmark capture.

What 1.0 means

• API freeze. All public items in wire_codec, wire_codec::error,
  wire_codec::buf, wire_codec::traits, wire_codec::varint,
  wire_codec::zigzag, wire_codec::bitfield, and wire_codec::framing
  are locked. Their signatures will not change without a 2.0 release.
• Behaviour freeze. Encode and decode results, frame boundaries,
  error variants on existing inputs, and bit ordering are locked.
• Wire compatibility. A buffer produced by 1.0 will be decoded
  identically by any 1.x version. A buffer produced by any 1.x version
  will be decoded identically by 1.0.

What can still change in 1.x without a major release:

• New Error variants ([Error] is #[non_exhaustive]).
• New LengthWidth variants ([LengthWidth] is #[non_exhaustive]).
• New methods on existing types.
• New helper functions, modules, traits, or framing strategies that do
  not conflict with the existing API.
• Performance improvements that do not alter observable output.
• New feature flags. Existing feature flags remain additive.

Documentation polish

• README rewritten end-to-end. Adds a "Why wire-codec?" section
  explaining the design boundaries, a feature list with cross-links into
  the API, four usage patterns (length-prefixed, delimited, varint +
  zigzag, bit-packed records), a performance table, a stability
  statement, a no_std and feature-flag table, and a project-layout
  diagram. The edition claim and version pin are corrected to match
  reality.
• docs/API.md gains a 1.0 stability note in the introduction and a
  new "Cookbook" section with four recipes: append-only stream over a
  growing buffer, fixed-output buffer with BufferFull back-pressure,
  length-prefixed envelope around a structured record, and the
  pre-sized-output hot-loop pattern.
• Crate-level rustdoc in src/lib.rs rewritten with a "When to
  reach for this crate" section, a module map table, a stability
  section that mirrors the README, and a feature-flag table. Doctest in
  the rustdoc block continues to pass.

Benchmark baseline at 1.0

Captured on the development machine (Windows 11, single thread, release
profile). Numbers will vary by hardware; these are the reference for
regression detection.

benches/codec.rs

Operation	ns/op
varint::encode_u32 (value 300)	0.36
varint::encode_u32 (u32::MAX)	0.72
varint::decode_u32 (2 bytes)	0.18
varint::decode_u32 (5 bytes)	0.18
varint::encode_u64 (u64::MAX)	1.08
varint::decode_u64 (10 bytes)	1.82
zigzag::encode_i32 (-1)	0.41
zigzag::encode_i64 (i64::MIN)	0.21
ReadBuf::read_u32_be	1.44
WriteBuf::write_u32_be	1.53

benches/framing.rs

Operation	ns/op
LengthPrefixed::write_frame (64 B)	1.62
LengthPrefixed::next_frame (64 B)	1.60
Delimited::next_frame (short line)	2.02
Delimited::next_frame (1 KiB scan + CRLF)	1324

The linear byte-by-byte scan inside Delimited::next_frame remains the
obvious candidate for future SIMD acceleration in a 1.x release.

What did not change from 0.9.0

• No new types. No new traits. No new functions.
• No behavioural changes. Every test that passed against 0.9.0 passes
  unchanged against 1.0.0.
• No new dependencies. The crate still has zero runtime dependencies and
  one dev-only dependency (proptest, capped at <1.6 for MSRV 1.75).
• No CI changes. The build matrix and supply-chain checks introduced in
  0.9.0 carry forward unchanged.

Verification

Built and tested green across the full directives matrix:

• cargo build (default features)
• cargo build --no-default-features
• cargo build --all-features
• cargo +1.75 build --all-features --tests
• cargo +1.75 test --all-features
• cargo fmt --all -- --check
• cargo clippy --all-targets --all-features -- -D warnings
• cargo +1.75 clippy --all-targets --all-features -- -D warnings
• RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
• cargo bench --bench codec
• cargo bench --bench framing

Test totals: 26 unit + 5 integration + 6 + 5 + 6 + 3 property + 3 smoke +
18 doctests = 72 tests green on both stable and MSRV 1.75.

Compatibility

• Edition: 2021
• MSRV: Rust 1.75
• License: Apache-2.0 OR MIT
• Platforms: Linux, macOS, Windows (CI on all three, stable + 1.75)
• Runtime dependencies: none
• Dev dependencies: proptest (test-only)

Migration from 0.9.0

None required. 1.0.0 is 0.9.0 plus documentation. A cargo update -p wire-codec is sufficient.

If you are migrating from 0.5.0 directly to 1.0.0, the only API
change is framing::Delimited::new now returns
Result<Delimited<'_>, Error>. See the 0.9.0 release note for the
migration recipe.

Acknowledgements

wire-codec is published under the dual Apache-2.0 OR MIT license and is
open to contributions under the same terms. The supply chain is enforced
by cargo audit and cargo deny in CI; the standards it adheres to are
captured in REPS.md.

Full Changelog: v0.9.0...v1.0.0

---

This discussion was created from the release v1.0.0 - Stable API.