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
flagsbyte, and bothcompute_header_crcandcompute_entry_crcmask flags to0xFFso a committed and an uncommitted entry hash alike. A version stored there would be the one field nothing protects. - Replication would drop it.
Spoolercopies a source entry to the replica as(sensor_id, timestamp, payload). A new header field would have to be threaded throughread_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.