Expand description
§verstamp
verstamp writes a two-byte version tag ahead of your payload and checks that your decoder consumed all of it. Old payloads climb a forward migration chain to the current type. This suits binary formats that do not describe themselves.
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, because nothing on the wire says which layout
the bytes hold. verstamp puts the version in front of the payload and routes
on it: old bytes climb a chain of Migrate steps to the current type,
current bytes decode in place, and a tag no decoder claims is an error rather
than a wrong value. verstamp owns the tag and the chain; you own the encoding.
§Reading
read strips the tag, Frame::at names the oldest version you can
decode, each Chain::then adds the next version with a Migrate step,
and Chain::done returns the current type. Register versions in strictly
increasing order.
A decoder is any FnOnce(&[u8]) -> Result<(value, bytes_read), E> whose
error converts into BoxError, that is Box<dyn Error + Send + Sync + 'static>. bincode’s decode_from_slice already has that
shape, so each step is one inline closure:
let save: Save = verstamp::read(&bytes)?
.at(1, |b| bincode::decode_from_slice::<SaveV1, _>(b, cfg()))
.then(2, |b| bincode::decode_from_slice::<SaveV2, _>(b, cfg()))
.then(3, |b| bincode::decode_from_slice::<Save, _>(b, cfg()))
.done()?;postcard’s take_from_bytes returns the value and the leftover tail rather
than a count; wrap it in from_tail to get the same shape. Complete,
runnable programs for both are in the examples/ directory.
§Writing
frame prepends the tag to bytes you already encoded; write() prepends
it and then lets your encoder append the payload. Starting versions at 1 is a
recommendation: a reader that never registers version 0 then rejects an
all-zero buffer as Error::UnknownVersion. verstamp does not enforce it.
§Migrating
A Migrate step describes how a value grows from the previous version to
the next. Its associated From type names the version a
step migrates from, so each step runs From into Self; keeping that
direction pointed at newer versions is a convention you follow, not something
the compiler checks. The example below decodes a version-1 record and
migrates it forward with a hand-rolled fixed-width codec, so every byte is
visible. SettingsV1 and the current Settings are both four bytes wide, so
only the tag separates them:
use verstamp::{frame, read, Migrate};
#[derive(Debug, PartialEq)]
struct SettingsV1 { volume: u16, brightness: u16 } // 4 bytes
#[derive(Debug, PartialEq)]
struct Settings { volume: u16, brightness: u8, contrast: u8 } // also 4 bytes
impl Migrate for Settings {
type From = SettingsV1;
fn migrate(v1: SettingsV1) -> Settings {
Settings { volume: v1.volume, brightness: v1.brightness.min(255) as u8, contrast: 0 }
}
}
let old = frame(1, &[0, 5, 0, 210]); // volume 5, brightness 210
let settings: Settings = read(&old)?
.at(1, |b| {
if b.len() < 4 {
return Err("short");
}
Ok::<_, &str>((SettingsV1 {
volume: u16::from_be_bytes([b[0], b[1]]),
brightness: u16::from_be_bytes([b[2], b[3]]),
}, 4))
})
.then(2, |b| {
if b.len() < 4 {
return Err("short");
}
Ok::<_, &str>((Settings {
volume: u16::from_be_bytes([b[0], b[1]]), brightness: b[2], contrast: b[3],
}, 4))
})
.done()?;
assert_eq!(settings, Settings { volume: 5, brightness: 210, contrast: 0 });A reader that knows only version 1, handed the version-2 bytes this writer
frames, returns Error::ForwardIncompatible rather than decoding them as a
SettingsV1.
§What the checks catch
The version tag routes the payload to one decoder. A tag newer than the
reader knows is Error::ForwardIncompatible; a tag with no registered
decoder is Error::UnknownVersion. Only the tag distinguishes two
equal-length layouts, the four-into-four case above; the byte count cannot.
Each decoder also reports how many bytes it read. verstamp checks that count
against the payload length and rejects any remainder as
Error::TrailingBytes, catching a wrong-length payload that decodes as a
prefix and stops short. decode_from_slice and take_from_bytes both
report the count; a decoder that yields only a value cannot be passed as is,
so wrap it to supply a count, and that count is what this check compares.
Both checks assume the two-byte tag is intact and the selected decoder is correct. verstamp routes on the tag and rejects mismatched byte counts; it does not checksum the payload or validate a decoder’s output. A corrupted tag can select a registered decoder, and a decoder that reads the wrong type yet consumes the whole payload still returns a value.
§Layout
| module | role |
|---|---|
wire | frame/write() add the version tag; read takes it off |
chain | Migrate and the Chain that routes a tag to one decoder |
error | the single Error type and the context each variant carries |
§Not in scope
- Backward or downgrade migration. The chain runs one direction, old to current. A newer tag is an error, not a downgrade.
- Field renames, type changes, schema diffing. verstamp never inspects
your payload. Whatever changed between versions, you express as a
Migratestep. - Encoding. Bring your own format. verstamp owns two bytes and a chain.
Re-exports§
pub use chain::from_tail;pub use chain::Chain;pub use chain::Migrate;pub use error::Error;pub use wire::frame;pub use wire::read;pub use wire::write;pub use wire::Frame;