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