Skip to main content

Module schema

Module schema 

Source
Expand description

Schema versioning for typed payloads.

A SensorData type binds a Rust struct to a sensor ID. Change the struct and every entry already on flash is still stored under that ID, but is no longer a T. The length check catches the easy half of that — a field added or removed — and misses the dangerous half: a change that keeps the size and alters the meaning (celsius becoming fahrenheit, two fields swapped, a scale factor changed). Those read back as plausible garbage.

So a typed payload carries a one-byte schema tag in front of the value:

payload = [ schema_version : u8 ] [ T's bytes ]

§Why the payload and not the entry header

The entry header is storage framing — the fields the scanner needs to walk the log and check its integrity. A schema version is application meaning: no part of this crate reads it, indexes on it, or resyncs from it. Two concrete consequences decided it:

  • The CRCs would not cover it. The only spare room in the header is the flags byte, and both compute_header_crc and compute_entry_crc mask flags to 0xFF so a committed and an uncommitted entry hash alike. A version stored there would be the one field nothing protects.
  • Replication would drop it. Spooler copies a source entry to the replica as (sensor_id, timestamp, payload). A new header field would have to be threaded through read_from’s callback and both spool drivers to survive the trip; a payload tag rides along untouched.

It also costs nothing on a wire-format bump, and nothing at all for callers using the raw append / query_range API.

§Migrating

Keep the old struct, give the new one the next version, and let both name the same sensor ID:

ⓘ
#[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
#[repr(C)]
struct TemperatureV0 { celsius: f32 }
impl SensorData for TemperatureV0 {
    const SENSOR_ID: u16 = 0x01;
    const SCHEMA_VERSION: u8 = 0;
}

#[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
#[repr(C)]
struct Temperature { millikelvin: u32 }
impl SensorData for Temperature {
    const SENSOR_ID: u16 = 0x01;
    const SCHEMA_VERSION: u8 = 1;
}

query_sensor skips entries of another version, so each type reads its own era out of the same log and a firmware update needs no flash migration pass. The single-entry reads (latest_sensor, oldest_sensor) instead report Error::SchemaMismatch, naming the version they found — enough for a caller to decide which type to reach for.

Constants§

SCHEMA_TAG_SIZE
Bytes a schema tag adds in front of a typed payload.