Skip to main content

Crate verstamp

Crate verstamp 

Source
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

modulerole
wireframe/write() add the version tag; read takes it off
chainMigrate and the Chain that routes a tag to one decoder
errorthe 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 Migrate step.
  • 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;

Modules§

chain
The forward migration chain.
error
The single error type returned by reads and writes.
prelude
Common imports.
wire
Framing: putting a version tag in front of a payload, and taking it back off.