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}