Skip to main content

sensor_db/
schema.rs

1//! Schema versioning for typed payloads.
2//!
3//! A [`SensorData`] type binds a Rust struct to a sensor ID. Change the struct
4//! and every entry already on flash is still stored under that ID, but is no
5//! longer a `T`. The length check catches the easy half of that — a field added
6//! or removed — and misses the dangerous half: a change that keeps the size and
7//! alters the *meaning* (`celsius` becoming `fahrenheit`, two fields swapped,
8//! a scale factor changed). Those read back as plausible garbage.
9//!
10//! So a typed payload carries a one-byte schema tag in front of the value:
11//!
12//! ```text
13//! payload = [ schema_version : u8 ] [ T's bytes ]
14//! ```
15//!
16//! # Why the payload and not the entry header
17//!
18//! The entry header is *storage framing* — the fields the scanner needs to walk
19//! the log and check its integrity. A schema version is application meaning: no
20//! part of this crate reads it, indexes on it, or resyncs from it. Two concrete
21//! consequences decided it:
22//!
23//! - **The CRCs would not cover it.** The only spare room in the header is the
24//!   `flags` byte, and both `compute_header_crc` and `compute_entry_crc` mask
25//!   flags to `0xFF` so a committed and an uncommitted entry hash alike. A
26//!   version stored there would be the one field nothing protects.
27//! - **Replication would drop it.** [`Spooler`](crate::Spooler) copies a source
28//!   entry to the replica as `(sensor_id, timestamp, payload)`. A new header
29//!   field would have to be threaded through `read_from`'s callback and both
30//!   spool drivers to survive the trip; a payload tag rides along untouched.
31//!
32//! It also costs nothing on a wire-format bump, and nothing at all for callers
33//! using the raw `append` / `query_range` API.
34//!
35//! # Migrating
36//!
37//! Keep the old struct, give the new one the next version, and let both name the
38//! same sensor ID:
39//!
40//! ```ignore
41//! #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
42//! #[repr(C)]
43//! struct TemperatureV0 { celsius: f32 }
44//! impl SensorData for TemperatureV0 {
45//!     const SENSOR_ID: u16 = 0x01;
46//!     const SCHEMA_VERSION: u8 = 0;
47//! }
48//!
49//! #[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
50//! #[repr(C)]
51//! struct Temperature { millikelvin: u32 }
52//! impl SensorData for Temperature {
53//!     const SENSOR_ID: u16 = 0x01;
54//!     const SCHEMA_VERSION: u8 = 1;
55//! }
56//! ```
57//!
58//! `query_sensor` *skips* entries of another version, so each type reads its own
59//! era out of the same log and a firmware update needs no flash migration pass.
60//! The single-entry reads (`latest_sensor`, `oldest_sensor`) instead report
61//! [`Error::SchemaMismatch`], naming the version they found — enough for a
62//! caller to decide which type to reach for.
63
64use zerocopy::{FromBytes, FromZeros, Immutable, IntoBytes, KnownLayout, Unalign, Unaligned};
65
66use crate::entry::EntryHeader;
67use crate::error::Error;
68use crate::typed::SensorData;
69
70/// Bytes a schema tag adds in front of a typed payload.
71///
72/// A typed entry's `payload_len` is therefore `SCHEMA_TAG_SIZE +
73/// size_of::<T>()`, and the largest storable `T` is one byte smaller than
74/// [`SensorDb::max_payload_size`](crate::SensorDb::max_payload_size).
75pub const SCHEMA_TAG_SIZE: usize = 1;
76
77/// The on-flash framing of a typed payload: the schema tag, then the value.
78///
79/// Both fields have alignment 1 — `Unalign<T>` is what makes that true for an
80/// arbitrary `T` — so the `repr(C)` layout is exactly the tag byte followed by
81/// `T`'s bytes, with no padding anywhere for a CRC to disagree about.
82#[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned)]
83#[repr(C)]
84pub(crate) struct Tagged<T> {
85    schema: u8,
86    value: Unalign<T>,
87}
88
89impl<T: SensorData> Tagged<T> {
90    /// A zeroed frame, sized to receive one stored typed payload.
91    pub(crate) fn empty() -> Self {
92        Self::new_zeroed()
93    }
94
95    /// The frame as it appears on flash.
96    pub(crate) fn bytes(&self) -> &[u8] {
97        self.as_bytes()
98    }
99
100    /// The frame as a read buffer.
101    ///
102    /// This and [`bytes`](Self::bytes) exist so no other module needs a
103    /// zerocopy trait in scope: the framing is this module's business.
104    pub(crate) fn bytes_mut(&mut self) -> &mut [u8] {
105        self.as_mut_bytes()
106    }
107}
108
109/// Fill a frame from a single-entry read and interpret it.
110///
111/// The sync read paths all have this shape. The async ones cannot use it — a
112/// closure cannot return a future borrowing its own argument — and so drive
113/// [`Tagged::empty`] and [`untag`] directly.
114pub(crate) fn read_tagged<T: SensorData>(
115    read: impl FnOnce(&mut [u8]) -> Result<Option<(EntryHeader, usize)>, Error>,
116) -> Result<Option<(EntryHeader, T)>, Error> {
117    let mut framed = Tagged::<T>::empty();
118    let found = read(framed.bytes_mut())?;
119    untag(found, framed)
120}
121
122/// The stored size of a typed payload.
123pub(crate) const fn tagged_size<T: SensorData>() -> usize {
124    SCHEMA_TAG_SIZE + core::mem::size_of::<T>()
125}
126
127/// Frame a value for storage under its declared schema version.
128pub(crate) fn tag<T: SensorData>(data: &T) -> Tagged<T> {
129    let mut framed = Tagged::<T>::new_zeroed();
130    let bytes = framed.as_mut_bytes();
131    bytes[0] = T::SCHEMA_VERSION;
132    bytes[SCHEMA_TAG_SIZE..].copy_from_slice(data.as_bytes());
133    framed
134}
135
136/// Pair a `Tagged<T>`-sized read with the value it filled, or say why the entry
137/// stored under `T::SENSOR_ID` is not a `T`.
138///
139/// Three ways it is not, and each says something different:
140///
141/// - `SchemaMismatch` — another era, named. The usual answer, and the one a
142///   migration dispatches on.
143/// - `SizeMismatch` — *this* version, a different length. Which means the struct
144///   changed and [`SCHEMA_VERSION`](SensorData::SCHEMA_VERSION) did not: exactly
145///   the mistake the tag exists to catch, reported as itself.
146/// - `BufferTooSmall` — raised by the caller before this is reached, when the
147///   stored entry is longer than a `Tagged<T>`. The payload never lands, so the
148///   version cannot be recovered; all it says is "longer than a `T`". Reading
149///   with the largest candidate type first avoids it.
150pub(crate) fn untag<T: SensorData>(
151    found: Option<(EntryHeader, usize)>,
152    framed: Tagged<T>,
153) -> Result<Option<(EntryHeader, T)>, Error> {
154    let Some((header, len)) = found else {
155        return Ok(None);
156    };
157
158    // The version is checked before the length, and the guard is what makes
159    // that sound: the frame was zeroed, so only the first `len` bytes came off
160    // flash. When both differ, the version is the fact a caller can act on —
161    // reporting the length instead would leave a migration unable to tell which
162    // era it just found.
163    if len >= SCHEMA_TAG_SIZE {
164        let found = framed.schema;
165        if found != T::SCHEMA_VERSION {
166            return Err(Error::SchemaMismatch {
167                expected: T::SCHEMA_VERSION,
168                found,
169            });
170        }
171    }
172
173    let expected = tagged_size::<T>();
174    if len != expected {
175        return Err(Error::SizeMismatch {
176            expected,
177            actual: len,
178        });
179    }
180
181    Ok(Some((header, framed.value.into_inner())))
182}
183
184/// Interpret a stored payload as a `T`, or `None` if it is not one.
185///
186/// The streaming reads use this rather than [`untag`]: a query that aborted on
187/// the first entry of another era could never reach the good ones behind it, so
188/// a mismatch has to be a skip.
189pub(crate) fn untag_payload<T: SensorData>(payload: &[u8]) -> Option<T> {
190    let (&schema, body) = payload.split_first()?;
191    if schema != T::SCHEMA_VERSION || body.len() != core::mem::size_of::<T>() {
192        return None;
193    }
194    T::read_from_bytes(body).ok()
195}
196
197#[cfg(test)]
198mod tests {
199    use super::*;
200
201    #[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Debug, PartialEq)]
202    #[repr(C)]
203    struct Reading {
204        celsius: f32,
205        raw: u32,
206    }
207
208    impl SensorData for Reading {
209        const SENSOR_ID: u16 = 0x42;
210    }
211
212    #[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Debug, PartialEq)]
213    #[repr(C)]
214    struct ReadingV2 {
215        celsius: f32,
216        raw: u32,
217    }
218
219    impl SensorData for ReadingV2 {
220        const SENSOR_ID: u16 = 0x42;
221        const SCHEMA_VERSION: u8 = 1;
222    }
223
224    #[test]
225    fn the_tag_precedes_the_value_with_no_padding() {
226        assert_eq!(tagged_size::<Reading>(), 1 + 8);
227
228        let framed = tag(&Reading {
229            celsius: 25.5,
230            raw: 0x0102_0304,
231        });
232        let bytes = framed.as_bytes();
233
234        assert_eq!(bytes.len(), 9);
235        assert_eq!(bytes[0], 0);
236        assert_eq!(&bytes[1..5], 25.5f32.to_ne_bytes());
237        assert_eq!(&bytes[5..9], 0x0102_0304u32.to_ne_bytes());
238    }
239
240    #[test]
241    fn a_value_survives_the_round_trip() {
242        let original = Reading {
243            celsius: -3.25,
244            raw: 7,
245        };
246        let bytes = tag(&original);
247
248        assert_eq!(untag_payload::<Reading>(bytes.as_bytes()), Some(original));
249    }
250
251    #[test]
252    fn two_versions_of_the_same_size_are_distinguishable() {
253        // The case a length check cannot catch: same layout, different meaning.
254        assert_eq!(
255            core::mem::size_of::<Reading>(),
256            core::mem::size_of::<ReadingV2>()
257        );
258
259        let v1 = tag(&Reading {
260            celsius: 1.0,
261            raw: 1,
262        });
263
264        assert!(untag_payload::<ReadingV2>(v1.as_bytes()).is_none());
265        assert!(untag_payload::<Reading>(v1.as_bytes()).is_some());
266    }
267
268    #[test]
269    fn a_wrong_version_is_named_in_the_error() {
270        let stored = tag(&Reading {
271            celsius: 1.0,
272            raw: 1,
273        });
274
275        let mut framed = Tagged::<ReadingV2>::new_zeroed();
276        framed.as_mut_bytes().copy_from_slice(stored.as_bytes());
277
278        let header = EntryHeader {
279            sensor_id: 0x42,
280            timestamp: 0,
281            payload_len: 9,
282            kind: crate::entry::EntryKind::Single,
283        };
284
285        assert_eq!(
286            untag::<ReadingV2>(Some((header, 9)), framed),
287            Err(Error::SchemaMismatch {
288                expected: 1,
289                found: 0
290            })
291        );
292    }
293
294    #[test]
295    fn a_wrong_length_is_a_size_mismatch_including_the_tag() {
296        let framed = Tagged::<Reading>::new_zeroed();
297        let header = EntryHeader {
298            sensor_id: 0x42,
299            timestamp: 0,
300            payload_len: 4,
301            kind: crate::entry::EntryKind::Single,
302        };
303
304        assert_eq!(
305            untag::<Reading>(Some((header, 4)), framed),
306            Err(Error::SizeMismatch {
307                expected: 9,
308                actual: 4
309            })
310        );
311    }
312
313    #[test]
314    fn an_empty_payload_is_not_a_value() {
315        assert!(untag_payload::<Reading>(&[]).is_none());
316    }
317}