sensor-db 0.1.0

Append-only sensor database for NOR flash on embedded devices
Documentation
//! 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:
//!
//! ```text
//! 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`](crate::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:
//!
//! ```ignore
//! #[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.

use zerocopy::{FromBytes, FromZeros, Immutable, IntoBytes, KnownLayout, Unalign, Unaligned};

use crate::entry::EntryHeader;
use crate::error::Error;
use crate::typed::SensorData;

/// Bytes a schema tag adds in front of a typed payload.
///
/// A typed entry's `payload_len` is therefore `SCHEMA_TAG_SIZE +
/// size_of::<T>()`, and the largest storable `T` is one byte smaller than
/// [`SensorDb::max_payload_size`](crate::SensorDb::max_payload_size).
pub const SCHEMA_TAG_SIZE: usize = 1;

/// The on-flash framing of a typed payload: the schema tag, then the value.
///
/// Both fields have alignment 1 — `Unalign<T>` is what makes that true for an
/// arbitrary `T` — so the `repr(C)` layout is exactly the tag byte followed by
/// `T`'s bytes, with no padding anywhere for a CRC to disagree about.
#[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned)]
#[repr(C)]
pub(crate) struct Tagged<T> {
    schema: u8,
    value: Unalign<T>,
}

impl<T: SensorData> Tagged<T> {
    /// A zeroed frame, sized to receive one stored typed payload.
    pub(crate) fn empty() -> Self {
        Self::new_zeroed()
    }

    /// The frame as it appears on flash.
    pub(crate) fn bytes(&self) -> &[u8] {
        self.as_bytes()
    }

    /// The frame as a read buffer.
    ///
    /// This and [`bytes`](Self::bytes) exist so no other module needs a
    /// zerocopy trait in scope: the framing is this module's business.
    pub(crate) fn bytes_mut(&mut self) -> &mut [u8] {
        self.as_mut_bytes()
    }
}

/// Fill a frame from a single-entry read and interpret it.
///
/// The sync read paths all have this shape. The async ones cannot use it — a
/// closure cannot return a future borrowing its own argument — and so drive
/// [`Tagged::empty`] and [`untag`] directly.
pub(crate) fn read_tagged<T: SensorData>(
    read: impl FnOnce(&mut [u8]) -> Result<Option<(EntryHeader, usize)>, Error>,
) -> Result<Option<(EntryHeader, T)>, Error> {
    let mut framed = Tagged::<T>::empty();
    let found = read(framed.bytes_mut())?;
    untag(found, framed)
}

/// The stored size of a typed payload.
pub(crate) const fn tagged_size<T: SensorData>() -> usize {
    SCHEMA_TAG_SIZE + core::mem::size_of::<T>()
}

/// Frame a value for storage under its declared schema version.
pub(crate) fn tag<T: SensorData>(data: &T) -> Tagged<T> {
    let mut framed = Tagged::<T>::new_zeroed();
    let bytes = framed.as_mut_bytes();
    bytes[0] = T::SCHEMA_VERSION;
    bytes[SCHEMA_TAG_SIZE..].copy_from_slice(data.as_bytes());
    framed
}

/// Pair a `Tagged<T>`-sized read with the value it filled, or say why the entry
/// stored under `T::SENSOR_ID` is not a `T`.
///
/// Three ways it is not, and each says something different:
///
/// - `SchemaMismatch` — another era, named. The usual answer, and the one a
///   migration dispatches on.
/// - `SizeMismatch` — *this* version, a different length. Which means the struct
///   changed and [`SCHEMA_VERSION`](SensorData::SCHEMA_VERSION) did not: exactly
///   the mistake the tag exists to catch, reported as itself.
/// - `BufferTooSmall` — raised by the caller before this is reached, when the
///   stored entry is longer than a `Tagged<T>`. The payload never lands, so the
///   version cannot be recovered; all it says is "longer than a `T`". Reading
///   with the largest candidate type first avoids it.
pub(crate) fn untag<T: SensorData>(
    found: Option<(EntryHeader, usize)>,
    framed: Tagged<T>,
) -> Result<Option<(EntryHeader, T)>, Error> {
    let Some((header, len)) = found else {
        return Ok(None);
    };

    // The version is checked before the length, and the guard is what makes
    // that sound: the frame was zeroed, so only the first `len` bytes came off
    // flash. When both differ, the version is the fact a caller can act on —
    // reporting the length instead would leave a migration unable to tell which
    // era it just found.
    if len >= SCHEMA_TAG_SIZE {
        let found = framed.schema;
        if found != T::SCHEMA_VERSION {
            return Err(Error::SchemaMismatch {
                expected: T::SCHEMA_VERSION,
                found,
            });
        }
    }

    let expected = tagged_size::<T>();
    if len != expected {
        return Err(Error::SizeMismatch {
            expected,
            actual: len,
        });
    }

    Ok(Some((header, framed.value.into_inner())))
}

/// Interpret a stored payload as a `T`, or `None` if it is not one.
///
/// The streaming reads use this rather than [`untag`]: a query that aborted on
/// the first entry of another era could never reach the good ones behind it, so
/// a mismatch has to be a skip.
pub(crate) fn untag_payload<T: SensorData>(payload: &[u8]) -> Option<T> {
    let (&schema, body) = payload.split_first()?;
    if schema != T::SCHEMA_VERSION || body.len() != core::mem::size_of::<T>() {
        return None;
    }
    T::read_from_bytes(body).ok()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Debug, PartialEq)]
    #[repr(C)]
    struct Reading {
        celsius: f32,
        raw: u32,
    }

    impl SensorData for Reading {
        const SENSOR_ID: u16 = 0x42;
    }

    #[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Debug, PartialEq)]
    #[repr(C)]
    struct ReadingV2 {
        celsius: f32,
        raw: u32,
    }

    impl SensorData for ReadingV2 {
        const SENSOR_ID: u16 = 0x42;
        const SCHEMA_VERSION: u8 = 1;
    }

    #[test]
    fn the_tag_precedes_the_value_with_no_padding() {
        assert_eq!(tagged_size::<Reading>(), 1 + 8);

        let framed = tag(&Reading {
            celsius: 25.5,
            raw: 0x0102_0304,
        });
        let bytes = framed.as_bytes();

        assert_eq!(bytes.len(), 9);
        assert_eq!(bytes[0], 0);
        assert_eq!(&bytes[1..5], 25.5f32.to_ne_bytes());
        assert_eq!(&bytes[5..9], 0x0102_0304u32.to_ne_bytes());
    }

    #[test]
    fn a_value_survives_the_round_trip() {
        let original = Reading {
            celsius: -3.25,
            raw: 7,
        };
        let bytes = tag(&original);

        assert_eq!(untag_payload::<Reading>(bytes.as_bytes()), Some(original));
    }

    #[test]
    fn two_versions_of_the_same_size_are_distinguishable() {
        // The case a length check cannot catch: same layout, different meaning.
        assert_eq!(
            core::mem::size_of::<Reading>(),
            core::mem::size_of::<ReadingV2>()
        );

        let v1 = tag(&Reading {
            celsius: 1.0,
            raw: 1,
        });

        assert!(untag_payload::<ReadingV2>(v1.as_bytes()).is_none());
        assert!(untag_payload::<Reading>(v1.as_bytes()).is_some());
    }

    #[test]
    fn a_wrong_version_is_named_in_the_error() {
        let stored = tag(&Reading {
            celsius: 1.0,
            raw: 1,
        });

        let mut framed = Tagged::<ReadingV2>::new_zeroed();
        framed.as_mut_bytes().copy_from_slice(stored.as_bytes());

        let header = EntryHeader {
            sensor_id: 0x42,
            timestamp: 0,
            payload_len: 9,
            kind: crate::entry::EntryKind::Single,
        };

        assert_eq!(
            untag::<ReadingV2>(Some((header, 9)), framed),
            Err(Error::SchemaMismatch {
                expected: 1,
                found: 0
            })
        );
    }

    #[test]
    fn a_wrong_length_is_a_size_mismatch_including_the_tag() {
        let framed = Tagged::<Reading>::new_zeroed();
        let header = EntryHeader {
            sensor_id: 0x42,
            timestamp: 0,
            payload_len: 4,
            kind: crate::entry::EntryKind::Single,
        };

        assert_eq!(
            untag::<Reading>(Some((header, 4)), framed),
            Err(Error::SizeMismatch {
                expected: 9,
                actual: 4
            })
        );
    }

    #[test]
    fn an_empty_payload_is_not_a_value() {
        assert!(untag_payload::<Reading>(&[]).is_none());
    }
}