sensor-db 0.1.0

Append-only sensor database for NOR flash on embedded devices
Documentation
//! Routing a tiered log: which medium `append` writes to, and when that moves.
//!
//! Pure module — no I/O. [`TieredDb`](crate::spool::TieredDb) and
//! [`TieredDbAsync`](crate::spool::asynch::TieredDbAsync) hold a `TierMode`
//! and supply only the flash work around it.

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

/// Batches allowed when draining the backlog to promote to direct writes.
///
/// Bounded so a pathological backlog cannot make a single `spool_step` run
/// unboundedly; the promotion simply happens on a later pass instead.
pub(crate) const PROMOTE_MAX_BATCHES: u32 = 256;

/// Where new samples land.
///
/// Chosen at construction with no default, because the right answer depends on
/// what the deployment values and both answers are defensible.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum WritePolicy {
    /// Always append to the onboard log; copy to the volume in the background.
    ///
    /// The write path never depends on the volume being present, so a removal at
    /// any instant — clean or not — cannot lose a sample. Costs onboard write
    /// endurance and space, since every sample is written twice.
    OnboardFirst,
    /// Append directly to the volume once the backlog is drained.
    ///
    /// Spares the onboard log both space and wear while the volume is present:
    /// samples bypass it entirely, so it is written only while the volume is
    /// out. A removal at any instant still loses nothing — whatever the volume
    /// held in RAM is rescued into the onboard log, because a yank leaves the
    /// processor running.
    ///
    /// Two costs to weigh against that:
    ///
    /// - **A power cut is not a yank.** It takes the processor too, so samples
    ///   buffered on the volume and not yet [`sync`](crate::spool::TieredDb::sync)ed
    ///   are gone. That window is one page — the same as any un-synced write —
    ///   but under [`OnboardFirst`](Self::OnboardFirst) those samples would have
    ///   been onboard already.
    /// - **There is only one copy.** Under `OnboardFirst` a sample exists in
    ///   both logs until the onboard ring reclaims it. Here, once a sample is on
    ///   the volume it is only there, so the volume filling up and wrapping is
    ///   real loss rather than the loss of a redundant copy. Size the volume for
    ///   the collection interval, and swap it before it wraps —
    ///   [`TieredDb::volume_fill`](crate::spool::TieredDb::volume_fill) is the
    ///   signal that says when that is due.
    ///
    /// One more thing to know about this mode: appends land on the volume, so a
    /// sector rotation there — 100 ms or more on many NOR parts — lands on the
    /// `append` path rather than on replication. Sample
    /// [`SensorDb::sectors_erased`](crate::SensorDb::sectors_erased) on the
    /// volume to see them.
    CardFirst,
}

/// Which log `append` is currently writing to.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum WriteMode {
    /// No volume, or the volume faulted: samples go to the onboard log.
    Onboard,
    /// A volume is attached but the onboard backlog has not drained yet.
    Draining,
    /// The backlog is empty and samples go straight to the volume.
    ///
    /// Only reachable under [`WritePolicy::CardFirst`].
    Direct,
}

/// The write-routing state machine of a tiered log.
///
/// Every transition is here rather than in the drivers, for the reason the whole
/// spool layer is split this way: `tests/tiered_async.rs` compares the two
/// drivers' media byte for byte, so a routing decision duplicated between them
/// is one the parity suite calls correct by construction.
#[derive(Debug, Clone, Copy)]
pub(crate) struct TierMode {
    policy: WritePolicy,
    mode: WriteMode,
}

impl TierMode {
    /// A tier with nothing attached, writing onboard.
    pub(crate) fn new(policy: WritePolicy) -> Self {
        Self {
            policy,
            mode: WriteMode::Onboard,
        }
    }

    /// Which log `append` is currently writing to.
    pub(crate) fn mode(&self) -> WriteMode {
        self.mode
    }

    /// The configured write policy.
    pub(crate) fn policy(&self) -> WritePolicy {
        self.policy
    }

    /// Whether an append should be attempted on the volume.
    pub(crate) fn writes_to_volume(&self) -> bool {
        self.mode == WriteMode::Direct
    }

    /// A volume has been attached: begin draining the backlog onto it.
    ///
    /// Set **before** the fallible part of an attach, so an error cannot strand
    /// an attached volume behind a mode that will never drain it.
    pub(crate) fn attached(&mut self) {
        self.mode = WriteMode::Draining;
    }

    /// The volume is gone, faulted, or being detached: write onboard.
    pub(crate) fn fell_back(&mut self) {
        self.mode = WriteMode::Onboard;
    }

    /// A replication pass ran, so a volume is attached and usable.
    ///
    /// Does not disturb [`Direct`](WriteMode::Direct): under
    /// [`CardFirst`](WritePolicy::CardFirst) a pass can still find work — the
    /// tail the onboard log buffered before the promotion — without that meaning
    /// the tier has stopped writing direct.
    pub(crate) fn spooled(&mut self) {
        if self.mode != WriteMode::Direct {
            self.mode = WriteMode::Draining;
        }
    }

    /// Whether a caught-up tier should try to promote to direct writes.
    pub(crate) fn may_promote(&self, attached: bool, faulted: bool) -> bool {
        self.policy == WritePolicy::CardFirst
            && self.mode != WriteMode::Direct
            && attached
            && !faulted
    }

    /// The backlog drained to nothing: appends may go straight to the volume.
    pub(crate) fn promoted(&mut self) {
        self.mode = WriteMode::Direct;
    }

    /// Whether a replication pass can run, falling back to the onboard log when
    /// it cannot.
    ///
    /// `Ok(false)` means no volume — the normal state while the card is out, and
    /// not an error. A **faulted** volume is different, and is reported as
    /// [`Error::VolumeLost`] until it is detached: answering `Ok(false)` there
    /// would let a card that fell out mid-write look identical to no card at
    /// all, and the backlog would grow silently until the ring began dropping
    /// it.
    pub(crate) fn ready_to_spool(&mut self, attached: bool, faulted: bool) -> Result<bool, Error> {
        if faulted {
            self.fell_back();
            return Err(Error::VolumeLost);
        }
        if !attached {
            self.fell_back();
            return Ok(false);
        }
        Ok(true)
    }
}

/// Whether a failed volume operation means the medium should be given up on.
///
/// A driver cannot tell a yanked card from a genuine fault — both arrive as
/// `NorFlashErrorKind::Other` — so any flash error on the volume is treated as
/// removal, and so is finding nothing attached at all. Both lead to the same
/// recovery: rescue whatever the volume still held in RAM into the onboard log
/// and carry on as if the card had never been there.
///
/// Anything else is a real error about the operation requested — a payload too
/// large, an unmounted log — and re-routing the write would only hide it.
pub(crate) fn volume_gone(error: &Error) -> bool {
    matches!(error, Error::Flash(_) | Error::NotAttached)
}

/// Pick between an onboard and a volume result, copying the winner into `buf`.
///
/// `volume_wins` is given the two timestamps, volume first, so the caller
/// supplies only the direction — `>` for the latest entry, `<` for the oldest.
///
/// The union is exact and needs no de-duplication: where the two logs overlap
/// they hold identical entries, so taking one side by timestamp cannot be
/// perturbed by the duplication.
///
/// # Errors
/// - `BufferTooSmall` if the volume's entry wins but does not fit `buf`. It is
///   raised rather than falling back to the onboard entry, because reporting an
///   older entry as the latest is a wrong answer where an error is merely an
///   inconvenient one.
pub(crate) fn merge(
    onboard: Option<(EntryHeader, usize)>,
    from_volume: Option<(EntryHeader, usize)>,
    alt: &[u8],
    buf: &mut [u8],
    volume_wins: impl Fn(u64, u64) -> bool,
) -> Result<Option<(EntryHeader, usize)>, Error> {
    let take_volume = |vh: EntryHeader, vn: usize, buf: &mut [u8]| {
        if vn > buf.len() {
            return Err(Error::BufferTooSmall);
        }
        buf[..vn].copy_from_slice(&alt[..vn]);
        Ok(Some((vh, vn)))
    };

    match (onboard, from_volume) {
        (Some((oh, on)), Some((vh, vn))) => {
            if volume_wins(vh.timestamp, oh.timestamp) {
                take_volume(vh, vn, buf)
            } else {
                Ok(Some((oh, on)))
            }
        }
        (None, Some((vh, vn))) => take_volume(vh, vn, buf),
        (some, None) => Ok(some),
    }
}

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

    fn header(timestamp: u64) -> EntryHeader {
        EntryHeader {
            sensor_id: 1,
            timestamp,
            payload_len: 2,
            kind: EntryKind::Single,
        }
    }

    #[test]
    fn a_tier_starts_onboard_and_only_card_first_ever_leaves_draining() {
        let mut onboard_first = TierMode::new(WritePolicy::OnboardFirst);
        assert_eq!(onboard_first.mode(), WriteMode::Onboard);
        onboard_first.attached();
        assert_eq!(onboard_first.mode(), WriteMode::Draining);
        assert!(!onboard_first.writes_to_volume());
        assert!(
            !onboard_first.may_promote(true, false),
            "OnboardFirst never writes direct, however drained the backlog is"
        );

        let mut card_first = TierMode::new(WritePolicy::CardFirst);
        card_first.attached();
        assert!(card_first.may_promote(true, false));
        card_first.promoted();
        assert_eq!(card_first.mode(), WriteMode::Direct);
        assert!(card_first.writes_to_volume());
        assert!(
            !card_first.may_promote(true, false),
            "already there, so nothing to drain for"
        );
    }

    #[test]
    fn a_pass_over_a_direct_tier_does_not_demote_it() {
        // Under CardFirst a pass can still find the tail the onboard log
        // buffered before the promotion; that is not a reason to stop writing
        // direct.
        let mut tier = TierMode::new(WritePolicy::CardFirst);
        tier.attached();
        tier.promoted();
        tier.spooled();
        assert_eq!(tier.mode(), WriteMode::Direct);

        let mut draining = TierMode::new(WritePolicy::CardFirst);
        draining.attached();
        draining.spooled();
        assert_eq!(draining.mode(), WriteMode::Draining);
    }

    #[test]
    fn a_missing_volume_is_not_an_error_but_a_faulted_one_is() {
        let mut tier = TierMode::new(WritePolicy::CardFirst);
        tier.attached();
        tier.promoted();

        assert_eq!(tier.ready_to_spool(false, false), Ok(false));
        assert_eq!(
            tier.mode(),
            WriteMode::Onboard,
            "with no card, appends must stop being aimed at one"
        );

        tier.attached();
        tier.promoted();
        assert_eq!(tier.ready_to_spool(true, true), Err(Error::VolumeLost));
        assert_eq!(tier.mode(), WriteMode::Onboard);
        assert!(
            !tier.may_promote(true, true),
            "a faulted volume is not a target"
        );

        tier.attached();
        assert_eq!(tier.ready_to_spool(true, false), Ok(true));
    }

    #[test]
    fn only_a_missing_medium_reroutes_a_write() {
        assert!(volume_gone(&Error::NotAttached));
        assert!(volume_gone(&Error::Flash(
            embedded_storage::nor_flash::NorFlashErrorKind::Other
        )));
        // A real complaint about the operation must surface, not be hidden by
        // writing the sample somewhere else.
        assert!(!volume_gone(&Error::PayloadTooLarge));
        assert!(!volume_gone(&Error::NotMounted));
        assert!(!volume_gone(&Error::NoSpace));
    }

    #[test]
    fn merge_takes_the_winner_and_leaves_the_loser_alone() {
        let alt = [0xAAu8; 8];
        let mut buf = [0u8; 8];

        // Volume newer: its bytes land in the caller's buffer.
        let out = merge(
            Some((header(10), 2)),
            Some((header(20), 4)),
            &alt,
            &mut buf,
            |v, o| v > o,
        )
        .unwrap()
        .unwrap();
        assert_eq!(out.0.timestamp, 20);
        assert_eq!(&buf[..4], &[0xAA; 4]);

        // Onboard newer: the buffer already holds it, so it is not touched.
        buf = [0u8; 8];
        let out = merge(
            Some((header(30), 2)),
            Some((header(20), 4)),
            &alt,
            &mut buf,
            |v, o| v > o,
        )
        .unwrap()
        .unwrap();
        assert_eq!(out.0.timestamp, 30);
        assert_eq!(buf, [0u8; 8], "the onboard read already filled it");

        // The same helper reads the other direction for `oldest`.
        let out = merge(
            Some((header(30), 2)),
            Some((header(20), 4)),
            &alt,
            &mut buf,
            |v, o| v < o,
        )
        .unwrap()
        .unwrap();
        assert_eq!(out.0.timestamp, 20);
    }

    #[test]
    fn merge_raises_rather_than_reporting_the_wrong_entry() {
        let alt = [0xAAu8; 8];
        let mut buf = [0u8; 2];
        assert_eq!(
            merge(
                Some((header(10), 2)),
                Some((header(20), 4)),
                &alt,
                &mut buf,
                |v, o| v > o
            ),
            Err(Error::BufferTooSmall),
            "silently reporting the onboard entry would answer a different question"
        );

        // Nothing onboard at all takes the same path.
        assert_eq!(
            merge(None, Some((header(20), 4)), &alt, &mut buf, |v, o| v > o),
            Err(Error::BufferTooSmall)
        );

        // Nothing on the volume: the onboard answer passes through untouched.
        assert_eq!(
            merge(Some((header(10), 2)), None, &alt, &mut buf, |v, o| v > o),
            Ok(Some((header(10), 2)))
        );
    }
}