verstamp 0.1.0

An explicit version tag in the byte stream, plus a forward migration chain, for binary formats that can't describe themselves.
Documentation
  • Coverage
  • 100%
    43 out of 43 items documented14 out of 18 items with examples
  • Size
  • Source code size: 89.8 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 848.4 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 3s Average build duration of successful builds.
  • all releases: 3s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • slepp/verstamp
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • slepp

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:

struct SettingsV1 { volume: u16, brightness: u16 }              // 4 bytes
struct Settings   { volume: u16, brightness: u8, contrast: u8 } // 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(&write_current(&Settings { volume: 5, brightness: 200, contrast: 40 }));
assert_eq!(ghost.brightness, 51_240); // 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

cargo add verstamp

Zero required dependencies, Rust 1.70 and later.

Example

use verstamp::{frame, read, Migrate};

#[derive(Debug, PartialEq)]
struct SettingsV1 { volume: u16, brightness: u16 }
#[derive(Debug, PartialEq)]
struct Settings { volume: u16, brightness: u8, contrast: u8 }

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 }
    }
}

fn main() -> Result<(), verstamp::Error> {
    // A version-1 record framed by an old build: volume 5, brightness 210.
    let old = frame(1, &[0, 5, 0, 210]);

    // `at` names the oldest version; each `then` adds a newer one and migrates
    // forward. A decoder returns (value, bytes_read); any leftover is refused
    // as `TrailingBytes`.
    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 });
    Ok(())
}

Real-codec programs with bincode and postcard, including trailing-byte rejection, are in examples/:

cargo run --example game_save
cargo run --example postcard_config

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

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.