sensor_db/spool/mod.rs
1//! Store-and-forward spooling from an onboard log to a removable volume.
2//!
3//! The problem this solves: a device with no network link collects sensor data
4//! continuously, and the only way to get the data off it is to pull a card and
5//! carry it to a computer. While the card is out, samples must keep landing
6//! somewhere; when it comes back, the backlog must land on it.
7//!
8//! # Layering
9//!
10//! ```text
11//! SensorDb single-device append-only log
12//! └─ Spooler owns the card, copies onboard → card, owns the on-card cursor
13//! └─ TieredDb routes append() between card and onboard
14//! ```
15//!
16//! Each layer is independently useful, and a device with no card slot uses none
17//! of them — plain [`SensorDb`](crate::SensorDb) is unchanged and costs nothing.
18//!
19//! # Module organisation
20//!
21//! - [`cursor`] — the on-medium record that says how far a copy got. Pure.
22//! - [`policy`] — batch planning, resume computation, and the spooler's own
23//! state machine. Pure.
24//! - [`tier`] — which medium `append` writes to, and when that moves. Pure.
25//! - [`port`] — capability traits the spooler needs from drivers. Pure.
26//! - [`blocking`] — the blocking driver.
27//!
28//! The pure modules carry no feature gates and no I/O dependencies; only the
29//! driver modules are gated. Between them they hold **every decision** the
30//! spool layer makes, so each driver contributes only its reads and writes:
31//! the two are unrelated trait families, and `tests/tiered_async.rs` compares
32//! the media they produce byte for byte, which means a decision written twice
33//! is one that suite calls correct by construction.
34//!
35//! # Guarantees
36//!
37//! - **No loss.** The source's watermark advances only after the replica's copy
38//! is durable, so an interruption re-copies rather than skips.
39//! - **Bounded duplication.** A power cut or unclean removal replays at most the
40//! in-flight batch — [`SpoolBudget::max_entries`] entries.
41//! - **In practice, no duplication.** That bound is the fallback. On reinsert,
42//! the interrupted batch's intent record says where on the replica it began,
43//! so the replica itself is read to find how much of it survived, and exactly
44//! that much is skipped on the source. The skip is verified against a
45//! [fingerprint](policy::RunFingerprint) of both runs and abandoned if they
46//! disagree, so a wrong reconciliation costs duplicates rather than data.
47//! - **Exact de-duplication is possible offline.** Each commit record maps a
48//! region of the replica to a source position range, so a reader can spot a
49//! replayed batch by its overlapping range and keep the later one.
50//!
51//! # Example
52//!
53//! ```
54//! use sensor_db::db::DbConfig;
55//! use sensor_db::mock::MockFlash;
56//! use sensor_db::sector::LogId;
57//! use sensor_db::spool::{SpoolBudget, Spooler, TieredDb, WritePolicy};
58//! use sensor_db::SensorDb;
59//!
60//! const PAGE: usize = 256;
61//! const SECTOR: usize = 4096;
62//! const SECTORS: usize = 8;
63//!
64//! let log = LogId::new(0xC0FFEE).unwrap();
65//! let config = DbConfig::new(0, SECTORS as u16, 1)?.with_log_id(log);
66//!
67//! // Onboard log.
68//! let mut onboard: SensorDb<_, PAGE, SECTORS> =
69//! SensorDb::with_config(MockFlash::<PAGE, SECTOR>::new(SECTORS * SECTOR), config)?;
70//! onboard.format()?;
71//!
72//! // The card: two sectors of cursor region, then the replica database.
73//! let cursor_base = 0;
74//! let card_config = DbConfig::new(2 * SECTOR as u32, (SECTORS - 2) as u16, 1)?
75//! .with_log_id(log);
76//! let mut card: SensorDb<_, PAGE, SECTORS> =
77//! SensorDb::with_config(MockFlash::<PAGE, SECTOR>::new(SECTORS * SECTOR), card_config)?;
78//! card.format()?;
79//!
80//! let spooler = Spooler::new(Some(log), cursor_base, SECTOR as u32)?;
81//! let mut db = TieredDb::new(onboard, spooler, WritePolicy::OnboardFirst)?;
82//!
83//! // Collect while the card is out.
84//! for i in 0..100 {
85//! db.append(1, i, &[i as u8])?;
86//! }
87//! db.sync()?;
88//!
89//! // Card goes in: the backlog drains onto it.
90//! db.attach(card)?;
91//! let progress = db.drain(SpoolBudget::default(), 64)?.unwrap();
92//! assert_eq!(progress.entries_copied, 100);
93//! assert!(progress.caught_up);
94//! # Ok::<(), sensor_db::Error>(())
95//! ```
96
97pub mod blocking;
98pub mod cursor;
99pub mod policy;
100pub mod port;
101pub mod tier;
102
103#[cfg(feature = "async")]
104pub mod asynch;
105
106pub use blocking::{Spooler, TieredDb};
107pub use cursor::{CursorKind, CursorRegion, SpoolCursorWire};
108pub use policy::{Attached, RunFingerprint, SpoolBudget, SpoolProgress, VolumeFill};
109pub use port::Removable;
110pub use tier::{WriteMode, WritePolicy};
111
112#[cfg(feature = "async")]
113pub use asynch::{SpoolerAsync, TieredDbAsync};