sensor-db 0.1.0

Append-only sensor database for NOR flash on embedded devices
Documentation
//! Shipping a firmware update that changes a reading's layout.
//!
//! ```sh
//! cargo run --example schema_evolution
//! ```
//!
//! A device has been logging for months. You change the struct — rename a field,
//! rescale it, add one — and flash the update. Every reading already on the
//! device is still stored under that sensor id, and is no longer a `T`.
//!
//! A length check catches the easy half of that. It misses the dangerous half: a
//! change that keeps the size and alters the *meaning*. `celsius` becoming
//! `fahrenheit` is the same four bytes, so the old readings come back as
//! plausible nonsense — no error, no CRC failure, just wrong numbers that look
//! right on a chart.
//!
//! So a typed payload carries a one-byte schema tag in front of the value:
//!
//! ```text
//! payload = [schema_version u8][T's bytes]
//! ```
//!
//! Bump [`SensorData::SCHEMA_VERSION`] on **any** change to the struct — a field
//! added, removed, reordered, retyped, rescaled, or simply given a new meaning.
//! The last of those is the one nothing else catches.
//!
//! # There is no migration pass
//!
//! Keep the old struct, give the new one the next version, and let both name the
//! same sensor id. Each type then reads its own era out of the same log, and
//! nothing has to be rewritten on flash — which matters when the flash in
//! question is the thing you are trying not to wear out.

use sensor_db::mock::MockFlash;
use sensor_db::{Error, SensorData, SensorDb, sensor_registry};
use zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};

const PAGE: usize = 256;
const SECTOR: usize = 4096;
const SECTORS: usize = 8;

type Flash = MockFlash<PAGE, SECTOR>;
type Db = SensorDb<Flash, PAGE, SECTORS>;

/// What the device shipped with: degrees Celsius as an `f32`.
#[derive(Debug, Clone, Copy, PartialEq, FromBytes, IntoBytes, KnownLayout, Immutable)]
#[repr(C)]
struct TemperatureV0 {
    celsius: f32,
}

impl SensorData for TemperatureV0 {
    const SENSOR_ID: u16 = 0x01;
    // SCHEMA_VERSION defaults to 0.
}

/// The update: millikelvin as a `u32`, because the `f32` was losing precision at
/// the top of the range.
///
/// **Same size, different meaning** — exactly the change a length check waves
/// through. Note the id is unchanged: this is still the temperature sensor.
#[derive(Debug, Clone, Copy, PartialEq, FromBytes, IntoBytes, KnownLayout, Immutable)]
#[repr(C)]
struct TemperatureV1 {
    millikelvin: u32,
}

impl SensorData for TemperatureV1 {
    const SENSOR_ID: u16 = 0x01;
    const SCHEMA_VERSION: u8 = 1;
}

/// A later update that also grew the struct, for the case where the size moves
/// as well.
#[derive(Debug, Clone, Copy, PartialEq, FromBytes, IntoBytes, KnownLayout, Immutable)]
#[repr(C)]
struct TemperatureV2 {
    millikelvin: u32,
    sensor_ok: u8,
    _pad: [u8; 3],
}

impl SensorData for TemperatureV2 {
    const SENSOR_ID: u16 = 0x01;
    const SCHEMA_VERSION: u8 = 2;
}

// Three types sharing one id at three versions is schema evolution and has to
// keep working. What must *not* compile is two types sharing an id at the same
// version — same-sized, that is the one corruption nothing can detect at
// runtime, and because the damage is in what was written it cannot be repaired
// later either. This macro turns it into a build error; it expands to an
// anonymous `const _`, so it defines nothing and costs nothing.
sensor_registry![TemperatureV0, TemperatureV1, TemperatureV2];

fn celsius_to_mk(c: f32) -> u32 {
    ((c + 273.15) * 1000.0) as u32
}

fn main() -> Result<(), Error> {
    println!("=== schema evolution: a firmware update mid-deployment ===\n");

    let mut db: Db = SensorDb::new(Flash::new(SECTORS * SECTOR), 0, SECTORS as u16, 1)?;
    db.format()?;

    // ---------------------------------------------------------------------
    println!("1. Months of readings from the shipped firmware");
    for i in 0..10u64 {
        db.append_sensor(
            i * 1_000,
            &TemperatureV0 {
                celsius: 20.0 + i as f32,
            },
        )?;
    }
    db.sync()?;
    println!("   logged 10 readings as TemperatureV0 (celsius: f32)");

    // ---------------------------------------------------------------------
    println!("\n2. The update lands. New readings use the new layout.");
    for i in 10..20u64 {
        db.append_sensor(
            i * 1_000,
            &TemperatureV1 {
                millikelvin: celsius_to_mk(20.0 + i as f32),
            },
        )?;
    }
    db.sync()?;
    println!("   logged 10 more as TemperatureV1 (millikelvin: u32)");
    println!("   the log now holds two eras under one sensor id, unmigrated");

    // ---------------------------------------------------------------------
    println!("\n3. A query reads its own era and steps over the other");

    // This is the migration mechanism, and the reason `query_sensor` *skips*
    // rather than raising: aborting on the first entry of another era could
    // never reach the good ones behind it.
    let mut old = Vec::new();
    db.query_all_sensor::<TemperatureV0, _>(|h, v| {
        old.push((h.timestamp, v.celsius));
        true
    })?;

    let mut new = Vec::new();
    db.query_all_sensor::<TemperatureV1, _>(|h, v| {
        new.push((h.timestamp, v.millikelvin));
        true
    })?;

    println!(
        "   TemperatureV0 sees {} readings, t={}..{}",
        old.len(),
        old[0].0,
        old[old.len() - 1].0
    );
    println!(
        "   TemperatureV1 sees {} readings, t={}..{}",
        new.len(),
        new[0].0,
        new[new.len() - 1].0
    );

    assert_eq!(old.len(), 10);
    assert_eq!(new.len(), 10);
    assert_eq!(old[0], (0, 20.0));
    assert_eq!(new[0].0, 10_000);

    // Both eras are present and neither leaked into the other's view.
    assert!(old.iter().all(|(t, _)| *t < 10_000));
    assert!(new.iter().all(|(t, _)| *t >= 10_000));

    // A firmware that wants everything reads both and converts. Nothing on
    // flash changes.
    let unified: Vec<(u64, u32)> = old
        .iter()
        .map(|&(t, c)| (t, celsius_to_mk(c)))
        .chain(new.iter().copied())
        .collect();
    println!(
        "   converting the old era in RAM gives {} readings end to end",
        unified.len()
    );
    assert_eq!(unified.len(), 20);

    // ---------------------------------------------------------------------
    println!("\n4. A single-entry read *raises* instead of skipping");

    // `latest` and `oldest` return one entry, so there is nothing to skip to —
    // and the error names the version found, which is what a caller dispatches
    // on. The newest entry is a v1, so asking for a v0 reports the mismatch.
    match db.latest_sensor::<TemperatureV0>() {
        Err(Error::SchemaMismatch { expected, found }) => {
            println!(
                "   latest_sensor::<TemperatureV0>() -> SchemaMismatch {{ expected: {expected}, found: {found} }}"
            );
            assert_eq!((expected, found), (0, 1));
        }
        other => panic!("expected SchemaMismatch, got {other:?}"),
    }

    // Asking for the right one works.
    let (h, v) = db
        .latest_sensor::<TemperatureV1>()?
        .expect("v1 entries exist");
    println!(
        "   latest_sensor::<TemperatureV1>() -> {} mK at t={}",
        v.millikelvin, h.timestamp
    );

    // ---------------------------------------------------------------------
    println!("\n5. The mistake the tag exists to catch");

    // Change the struct and *forget* to bump the version. Here the size moved
    // too, so the entry is reported as a size mismatch under the same version —
    // which means precisely "the struct changed and SCHEMA_VERSION did not".
    db.append_sensor(
        20_000,
        &TemperatureV2 {
            millikelvin: 300_000,
            sensor_ok: 1,
            _pad: [0; 3],
        },
    )?;
    db.sync()?;

    // A v2 entry is *longer* than a `Tagged<TemperatureV1>`, so reading it as a
    // v1 cannot even land the payload — and with it, the tag. The version is
    // unrecoverable here, and the error says only "longer than a T".
    match db.latest_sensor::<TemperatureV1>() {
        Err(Error::BufferTooSmall) => {
            println!("   a v2 entry read as v1 -> BufferTooSmall");
            println!("   the entry is longer than a Tagged<V1>, so the tag never lands and");
            println!("   the version cannot be reported. Hence the rule: when several eras");
            println!("   may be present, dispatch from the *largest* candidate type down.");
        }
        other => panic!("expected BufferTooSmall, got {other:?}"),
    }

    // Doing exactly that recovers it, and now the version is available.
    let (_, v2) = db.latest_sensor::<TemperatureV2>()?.expect("the v2 entry");
    println!(
        "   latest_sensor::<TemperatureV2>() -> {} mK, sensor_ok={}",
        v2.millikelvin, v2.sensor_ok
    );

    // The other direction — an entry *shorter* than the type asked for — does
    // reach the buffer, so the version is checked first and passes, and the
    // length is what fails. `SizeMismatch` then means something precise: this
    // version, a different length, i.e. the struct changed and SCHEMA_VERSION
    // did not.
    let short_but_tagged_v2 = [TemperatureV2::SCHEMA_VERSION, 0, 0];
    db.append(TemperatureV2::SENSOR_ID, 21_000, &short_but_tagged_v2)?;
    db.sync()?;
    match db.latest_sensor::<TemperatureV2>() {
        Err(Error::SizeMismatch { expected, actual }) => {
            println!(
                "   same version, wrong length -> SizeMismatch {{ expected: {expected}, actual: {actual} }}"
            );
            println!("   i.e. the struct changed and SCHEMA_VERSION did not — a forgotten bump.");
            assert_eq!((expected, actual), (1 + size_of::<TemperatureV2>(), 3));
        }
        other => panic!("expected SizeMismatch, got {other:?}"),
    }

    // ---------------------------------------------------------------------
    println!("\n6. What the tag does not cover");

    // The raw API is untagged by design — it is the escape hatch for bytes this
    // crate should not interpret — so it does not interoperate with the typed
    // API in either direction.
    db.append_value(0x77, 30_000, &1234u32)?;
    db.sync()?;
    let mut buf = [0u8; 8];
    let (_, n) = db.latest(0x77, &mut buf)?.expect("just written");
    println!("   append_value stored {n} bytes — no tag, and unreadable as a T");
    assert_eq!(n, 4, "four bytes, not five: the raw path adds nothing");

    // And the case nothing at runtime can catch: two *different* types sharing
    // an id at the same version, with the same size. The entry is intact, the
    // CRC is correct, and the bytes simply mean something else. That is what
    // `sensor_registry!` above is for — it would have failed this build.
    println!("   two same-sized types at one (id, version) are undetectable at");
    println!("   runtime — `sensor_registry!` makes it a compile error instead.");

    println!("\nOK");
    Ok(())
}