verstamp
verstamp writes a two-byte version tag ahead of your payload and checks that
your decoder consumed all of it. Old payloads migrate forward, for binary
formats that can't describe themselves.
The hazard
Compact binary formats (bincode, postcard, MessagePack in compact mode) leave field names off the wire. Add a field to a struct and old data stops decoding. Worse, two layouts of the same length can decode into each other as plausible values with no error:
// 4 bytes
// also 4 bytes
// New code writes a Settings value; old code reads it back as SettingsV1 and
// succeeds with a wrong result. Both layouts are four bytes, so nothing trips.
let ghost = read_v1;
assert_eq!; // 200<<8 | 40, silently wrong
Put the version in the bytes and route on it. A reader that knows only version
1, handed version-2 bytes verstamp framed, returns ForwardIncompatible
instead of the silent ghost. verstamp owns the tag and the migration chain;
you keep your encoder.
Install
Zero required dependencies, Rust 1.70 and later.
Example
use ;
Real-codec programs with bincode and postcard, including trailing-byte
rejection, are in examples/:
Docs
Full API and error semantics are on docs.rs: read
returns a Frame; Frame::at starts a Chain, Chain::then / then_with add
versions, and Chain::done yields the current value.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.