Skip to main content

sensor_db/spool/
asynch.rs

1//! Async store-and-forward drivers: [`SpoolerAsync`] and [`TieredDbAsync`].
2//!
3//! Mirrors [`blocking`](crate::spool::blocking) operation for operation. Every
4//! decision — where the next cursor record goes, what a scan of the region
5//! means, which log an append is routed to, when duplicates are possible — lives
6//! in the shared pure modules [`cursor`](crate::spool::cursor),
7//! [`policy`](crate::spool::policy) and [`tier`](crate::spool::tier); only the
8//! code that actually touches flash is written twice, because the sync and async
9//! `NorFlash` traits are unrelated types.
10//!
11//! That split is not tidiness. `tests/tiered_async.rs` asserts the two drivers
12//! produce byte-for-byte identical media, so a decision duplicated between them
13//! is one the parity suite calls correct however wrong it is — which has already
14//! happened once, with the `attach`-before-`reconcile` ordering bug.
15//!
16//! See the blocking types for the full rationale behind the protocol; the
17//! documentation here covers only what differs.
18
19use embedded_storage_async::nor_flash::{NorFlash, ReadNorFlash};
20use zerocopy::IntoBytes;
21
22use crate::async_db::SensorDbAsync;
23use crate::db::{LogPosition, Replicated, SpoolStats};
24use crate::entry::{EntryHeader, EntryKind};
25use crate::error::Error;
26use crate::run::{Run, deliver_samples, samples_in};
27use crate::sector::LogId;
28use crate::spool::cursor::{CURSOR_RECORD_SIZE, CursorRegion, SpoolCursorWire};
29use crate::spool::policy::{
30    Attached, BatchSector, CursorFold, CursorScan, EraseTally, RunFingerprint, SpoolBudget,
31    SpoolFailure, SpoolProgress, SpoolerState, VolumeFill,
32};
33use crate::spool::port::Removable;
34use crate::spool::tier::{
35    PROMOTE_MAX_BATCHES, TierMode, WriteMode, WritePolicy, merge, volume_gone,
36};
37
38/// State of the removable volume the spooler owns.
39enum Slot<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> {
40    Empty,
41    Ready(SensorDbAsync<C, PAGE_SIZE, MAX_SECTORS>),
42    Faulted(SensorDbAsync<C, PAGE_SIZE, MAX_SECTORS>),
43}
44
45/// Copies a log onto a removable volume, and remembers how far it got.
46///
47/// Async counterpart of [`Spooler`](crate::spool::Spooler), with the same
48/// guarantees: no loss, duplication bounded by [`SpoolBudget::max_entries`] and
49/// in practice reconciled away on reinsert, and nothing written to a volume
50/// belonging to a different log.
51pub struct SpoolerAsync<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> {
52    slot: Slot<C, PAGE_SIZE, MAX_SECTORS>,
53    /// Every decision this spooler makes, shared verbatim with the blocking one.
54    state: SpoolerState,
55    scratch: [u8; PAGE_SIZE],
56}
57
58/// Inspection that needs no flash access, and therefore no trait bounds.
59impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> SpoolerAsync<C, PAGE_SIZE, MAX_SECTORS> {
60    /// Whether a volume is attached, faulted or not.
61    pub fn is_attached(&self) -> bool {
62        !matches!(self.slot, Slot::Empty)
63    }
64
65    /// Whether the attached volume has faulted and needs detaching.
66    pub fn is_faulted(&self) -> bool {
67        matches!(self.slot, Slot::Faulted(_))
68    }
69
70    /// Source position replication will resume from, if a volume is attached.
71    pub fn resume_point(&self) -> Option<LogPosition> {
72        self.is_attached().then(|| self.state.resume())
73    }
74
75    /// Identity of the log this spooler replicates.
76    pub fn source_log(&self) -> Option<LogId> {
77        self.state.source_log()
78    }
79
80    /// Layout of the cursor region on the volume.
81    pub fn region(&self) -> CursorRegion {
82        *self.state.region()
83    }
84
85    /// Entries of an interrupted batch that the replica already holds and the
86    /// next pass will skip rather than copy again.
87    pub fn pending_reconciliation(&self) -> u32 {
88        self.state.pending_reconciliation()
89    }
90}
91
92impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> SpoolerAsync<C, PAGE_SIZE, MAX_SECTORS>
93where
94    C: NorFlash + ReadNorFlash,
95{
96    /// Create a spooler for a log with the given identity.
97    ///
98    /// See [`Spooler::new`](crate::spool::Spooler::new). `cursor_base` must name
99    /// a region **outside** the volume's database region, which
100    /// [`attach`](Self::attach) enforces with [`Error::RegionOverlap`].
101    pub fn new(
102        source_log: Option<LogId>,
103        cursor_base: u32,
104        sector_size: u32,
105    ) -> Result<Self, Error> {
106        Ok(Self {
107            slot: Slot::Empty,
108            state: SpoolerState::new(source_log, cursor_base, sector_size, PAGE_SIZE as u32)?,
109            scratch: [0xFF; PAGE_SIZE],
110        })
111    }
112
113    /// Attach a mounted volume and read its cursor.
114    ///
115    /// Reconciles an interrupted batch the same way as
116    /// [`Spooler::attach`](crate::spool::Spooler::attach); see there for why the
117    /// replica is the thing that knows how far the batch got.
118    ///
119    /// # Errors
120    /// - `AlreadyAttached` if a volume is already attached
121    /// - `NotMounted` if the volume has not been mounted
122    /// - `ForeignVolume` if its cursor belongs to a different log
123    pub async fn attach(
124        &mut self,
125        volume: SensorDbAsync<C, PAGE_SIZE, MAX_SECTORS>,
126    ) -> Result<Attached, Error> {
127        if !matches!(self.slot, Slot::Empty) {
128            return Err(Error::AlreadyAttached);
129        }
130        if !volume.is_mounted() {
131            return Err(Error::NotMounted);
132        }
133
134        let mut volume = volume;
135        // Attaching to a spooler *is* the declaration that this volume is a
136        // replica: suppress the per-run epoch roll, which would otherwise burn a
137        // sector on every insertion to record an epoch that means nothing here.
138        volume.mark_as_replica();
139        let scan = scan_cursor(&mut volume, &self.state).await?;
140        let landed = fingerprint_landed(&mut volume, &scan).await?;
141
142        let attached = self.state.adopt_scan(scan, landed);
143        self.slot = Slot::Ready(volume);
144        Ok(attached)
145    }
146
147    /// Skip the part of an interrupted batch the replica already holds.
148    ///
149    /// See [`Spooler::reconcile`](crate::spool::Spooler::reconcile).
150    ///
151    /// # Returns
152    /// The number of entries skipped.
153    pub async fn reconcile<S, const SP: usize, const SS: usize>(
154        &mut self,
155        source: &mut SensorDbAsync<S, SP, SS>,
156    ) -> Result<u32, Error>
157    where
158        S: NorFlash + ReadNorFlash,
159    {
160        let landed = self.state.take_pending();
161        if landed.is_empty() {
162            return Ok(0);
163        }
164
165        let mut found = RunFingerprint::new();
166        let mut moved = Replicated::NONE;
167        let cursor = source
168            .read_from(
169                self.state.resume(),
170                landed.entries(),
171                |_, header, payload| {
172                    found.push(header.sensor_id, header.timestamp);
173                    moved.push(samples_in(header.is_run(), payload));
174                    Ok(true)
175                },
176            )
177            .await?;
178        if !self.state.accept_skip(&landed, &found, &cursor) {
179            return Ok(0);
180        }
181
182        // These entries are on the replica; the source may reclaim their sectors.
183        source.note_spooled(cursor.next, moved);
184        Ok(cursor.entries)
185    }
186
187    /// Mark the attached volume faulted and borrow it.
188    ///
189    /// Returns the volume so the caller can still reach data in its RAM page
190    /// buffer, which survives the medium being pulled.
191    pub fn fault(&mut self) -> Option<&mut SensorDbAsync<C, PAGE_SIZE, MAX_SECTORS>> {
192        // Only move out of the slot when there is something to transition, or an
193        // already-faulted volume would be dropped along with its RAM buffer.
194        if matches!(self.slot, Slot::Ready(_))
195            && let Slot::Ready(volume) = core::mem::replace(&mut self.slot, Slot::Empty)
196        {
197            self.slot = Slot::Faulted(volume);
198        }
199        match &mut self.slot {
200            Slot::Faulted(volume) => Some(volume),
201            _ => None,
202        }
203    }
204
205    /// Detach the volume, returning it to the application. Also clears a fault.
206    pub fn detach(&mut self) -> Option<SensorDbAsync<C, PAGE_SIZE, MAX_SECTORS>> {
207        let taken = core::mem::replace(&mut self.slot, Slot::Empty);
208        self.state.reset();
209        match taken {
210            Slot::Empty => None,
211            Slot::Ready(volume) | Slot::Faulted(volume) => Some(volume),
212        }
213    }
214
215    /// The attached volume, if it is usable.
216    pub fn volume(&self) -> Option<&SensorDbAsync<C, PAGE_SIZE, MAX_SECTORS>> {
217        match &self.slot {
218            Slot::Ready(v) => Some(v),
219            _ => None,
220        }
221    }
222
223    /// The attached volume, if it is usable.
224    pub fn volume_mut(&mut self) -> Option<&mut SensorDbAsync<C, PAGE_SIZE, MAX_SECTORS>> {
225        match &mut self.slot {
226            Slot::Ready(v) => Some(v),
227            _ => None,
228        }
229    }
230
231    /// How much room is left on the attached volume.
232    ///
233    /// See [`Spooler::volume_fill`](crate::spool::Spooler::volume_fill).
234    pub fn volume_fill(&self) -> Option<VolumeFill> {
235        let volume = match &self.slot {
236            Slot::Empty => return None,
237            Slot::Ready(v) | Slot::Faulted(v) => v,
238        };
239        Some(VolumeFill::from_stats(&volume.stats()))
240    }
241
242    /// Copy up to `budget.max_entries` durable source entries onto the volume.
243    ///
244    /// See [`Spooler::spool`](crate::spool::Spooler::spool).
245    pub async fn spool<S, const SP: usize, const SS: usize>(
246        &mut self,
247        source: &mut SensorDbAsync<S, SP, SS>,
248        budget: SpoolBudget,
249    ) -> Result<SpoolProgress, Error>
250    where
251        S: NorFlash + ReadNorFlash,
252    {
253        if SP > PAGE_SIZE {
254            return Err(Error::GeometryMismatch);
255        }
256
257        match self.slot {
258            Slot::Empty => return Err(Error::NotAttached),
259            Slot::Faulted(_) => return Err(Error::VolumeLost),
260            Slot::Ready(_) => {}
261        }
262
263        match self.spool_inner(source, budget).await {
264            Ok(progress) => Ok(progress),
265            // A driver cannot distinguish a yanked medium from a genuine fault,
266            // so any flash error on the *volume* is treated as removal. One on
267            // the source is reported as itself — see `SpoolFailure`.
268            Err(f) if !f.from_source && matches!(f.error, Error::Flash(_)) => {
269                self.fault();
270                Err(Error::VolumeLost)
271            }
272            Err(f) => Err(f.error),
273        }
274    }
275
276    async fn spool_inner<S, const SP: usize, const SS: usize>(
277        &mut self,
278        source: &mut SensorDbAsync<S, SP, SS>,
279        budget: SpoolBudget,
280    ) -> Result<SpoolProgress, SpoolFailure>
281    where
282        S: NorFlash + ReadNorFlash,
283    {
284        // Failures are tagged with the side they came from: faulting the volume
285        // is the wrong response to the source's flash failing. A bare `?`
286        // attributes to the volume; source operations say so explicitly.
287        //
288        // Step over whatever an interrupted batch already delivered, so this
289        // pass copies the remainder rather than the whole batch again.
290        SpoolFailure::from_source(self.reconcile(source).await)?;
291
292        let Self {
293            slot,
294            state,
295            scratch,
296        } = self;
297        let Slot::Ready(volume) = slot else {
298            return Err(Error::NotAttached.into());
299        };
300
301        let from = state.resume();
302        let mut erased = EraseTally::new(volume.sectors_erased());
303
304        // Probe before writing an intent so an idle poll burns no cursor slots.
305        // `Ok(false)` rejects the entry, so this consumes nothing.
306        let probe =
307            SpoolFailure::from_source(source.read_from(from, 1, |_, _, _| Ok(false)).await)?;
308        if probe.exhausted {
309            return Ok(SpoolProgress::idle(from, probe.gap));
310        }
311
312        let source_epoch =
313            SpoolFailure::from_source(source.sector_epoch_at(probe.next).await)?.unwrap_or(0);
314
315        let batch = state.plan_batch(source_epoch, volume.head_position(), budget);
316        if let Some((start, end)) = batch.erase(state.region()) {
317            // Erase the sector being moved *into*: the one being left still holds
318            // valid records, so the resume point is never unrecoverable.
319            let region = *state.region();
320            volume
321                .region(region.base(), region.total_size())?
322                .erase(start, end)
323                .await
324                .map_err(Error::from)?;
325            erased.cursor_erase();
326        }
327
328        write_record(
329            volume,
330            state.region(),
331            batch.sector(),
332            batch.intent_slot(),
333            &batch.intent(),
334            scratch,
335        )
336        .await?;
337
338        let mut copied = Replicated::NONE;
339        let mut last_timestamp = 0u64;
340        let mut batch_sector = BatchSector::new();
341
342        // The copy cannot run inside `read_from`'s callback here: appending to
343        // the volume is `async`, and the callback is a plain `FnMut`. Instead the
344        // batch is read into a staging buffer one entry at a time, then written.
345        // One source page of stack, the same as the blocking driver's callback.
346        let mut staged = [0u8; SP];
347        let mut cursor_next = from;
348        let mut exhausted = false;
349        let mut gap = false;
350
351        loop {
352            if copied.entries >= budget.max_entries {
353                break;
354            }
355            let mut pending: Option<(EntryHeader, usize)> = None;
356            let read = SpoolFailure::from_source(
357                source
358                    .read_from(cursor_next, 1, |pos, header, payload| {
359                        if !batch_sector.admits(pos.sequence) {
360                            return Ok(false);
361                        }
362                        staged[..payload.len()].copy_from_slice(payload);
363                        pending = Some((*header, payload.len()));
364                        Ok(true)
365                    })
366                    .await,
367            )?;
368            gap |= read.gap;
369
370            let Some((header, len)) = pending else {
371                // Either nothing is left, or the batch hit a sector boundary.
372                exhausted = read.exhausted;
373                break;
374            };
375
376            // `append_framed`, not `append`: a run must land on the replica as a
377            // run, or its frame becomes one opaque sample no read can interpret.
378            volume.append_framed(&header, &staged[..len]).await?;
379            copied.push(samples_in(header.is_run(), &staged[..len]));
380            last_timestamp = header.timestamp;
381            cursor_next = read.next;
382        }
383
384        // Make the copy durable *before* the commit record claims it is.
385        volume.sync().await?;
386
387        write_record(
388            volume,
389            state.region(),
390            batch.sector(),
391            batch.commit_slot(),
392            &batch.commit(cursor_next, copied, last_timestamp),
393            scratch,
394        )
395        .await?;
396
397        // Only now is it safe to let the source consider this replicated.
398        state.commit_batch(&batch, cursor_next);
399        source.note_spooled(cursor_next, copied);
400
401        Ok(SpoolProgress {
402            entries_copied: copied.entries,
403            committed_upto: cursor_next,
404            caught_up: exhausted,
405            gap,
406            volume_erased: erased.total(volume.sectors_erased()),
407        })
408    }
409
410    /// Copy until the replica is level with the source, or `max_batches` passes
411    /// have run.
412    pub async fn spool_until_caught_up<S, const SP: usize, const SS: usize>(
413        &mut self,
414        source: &mut SensorDbAsync<S, SP, SS>,
415        budget: SpoolBudget,
416        max_batches: u32,
417    ) -> Result<SpoolProgress, Error>
418    where
419        S: NorFlash + ReadNorFlash,
420    {
421        let mut total = SpoolProgress {
422            committed_upto: self.state.resume(),
423            ..SpoolProgress::default()
424        };
425        for _ in 0..max_batches {
426            let progress = self.spool(source, budget).await?;
427            total.absorb(&progress);
428            if progress.caught_up {
429                break;
430            }
431        }
432        Ok(total)
433    }
434}
435
436impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> SpoolerAsync<C, PAGE_SIZE, MAX_SECTORS>
437where
438    C: NorFlash + ReadNorFlash + Removable,
439{
440    /// Like [`spool`](Self::spool), but skip the pass when the driver reports
441    /// the medium absent.
442    pub async fn spool_if_present<S, const SP: usize, const SS: usize>(
443        &mut self,
444        source: &mut SensorDbAsync<S, SP, SS>,
445        budget: SpoolBudget,
446    ) -> Result<Option<SpoolProgress>, Error>
447    where
448        S: NorFlash + ReadNorFlash,
449    {
450        let present = match &mut self.slot {
451            Slot::Empty => return Err(Error::NotAttached),
452            Slot::Faulted(_) => return Err(Error::VolumeLost),
453            Slot::Ready(volume) => volume.driver_mut().is_present(),
454        };
455        if !present {
456            return Ok(None);
457        }
458        self.spool(source, budget).await.map(Some)
459    }
460
461    /// Whether the driver reports the attached medium as present.
462    pub fn is_present(&mut self) -> bool {
463        match &mut self.slot {
464            Slot::Ready(volume) => volume.driver_mut().is_present(),
465            _ => false,
466        }
467    }
468}
469
470/// Read every cursor slot on the volume and work out where to resume.
471async fn scan_cursor<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize>(
472    volume: &mut SensorDbAsync<C, PAGE_SIZE, MAX_SECTORS>,
473    state: &SpoolerState,
474) -> Result<CursorScan, Error>
475where
476    C: NorFlash + ReadNorFlash,
477{
478    let region = *state.region();
479    let expected = state.expected_log();
480    let mut fold = CursorFold::new();
481    let mut buf = [0u8; CURSOR_RECORD_SIZE];
482
483    for at in region.slots() {
484        volume
485            .region(region.base(), region.total_size())?
486            .read(at.offset, &mut buf)
487            .await?;
488        fold.feed(at, &buf, expected)?;
489    }
490
491    Ok(fold.finish())
492}
493
494/// Fingerprint what an interrupted batch actually managed to store.
495///
496/// See the blocking `fingerprint_landed` for why everything at or after the
497/// intent's `dest` belongs to exactly that batch, and
498/// [`CursorScan::accept_landed`] for what makes the run untrustworthy.
499async fn fingerprint_landed<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize>(
500    volume: &mut SensorDbAsync<C, PAGE_SIZE, MAX_SECTORS>,
501    scan: &CursorScan,
502) -> Result<RunFingerprint, Error>
503where
504    C: NorFlash + ReadNorFlash,
505{
506    let Some((dest, limit)) = scan.landed_probe() else {
507        return Ok(RunFingerprint::new());
508    };
509    let mut run = RunFingerprint::new();
510    let cursor = volume
511        .read_from(dest, limit, |_, header, _| {
512            run.push(header.sensor_id, header.timestamp);
513            Ok(true)
514        })
515        .await?;
516    Ok(scan.accept_landed(run, &cursor))
517}
518
519/// Serialise a cursor record into a page-sized slot.
520async fn write_record<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize>(
521    volume: &mut SensorDbAsync<C, PAGE_SIZE, MAX_SECTORS>,
522    region: &CursorRegion,
523    sector: u8,
524    slot: u32,
525    record: &SpoolCursorWire,
526    scratch: &mut [u8; PAGE_SIZE],
527) -> Result<(), Error>
528where
529    C: NorFlash + ReadNorFlash,
530{
531    scratch.fill(0xFF);
532    scratch[..CURSOR_RECORD_SIZE].copy_from_slice(record.as_bytes());
533    let offset = region.slot_offset(sector, slot);
534    volume
535        .region(region.base(), region.total_size())?
536        .write(offset, &scratch[..])
537        .await?;
538    Ok(())
539}
540
541// =============================================================================
542// TieredDbAsync
543// =============================================================================
544
545/// An onboard log plus a removable volume, with `append` routed between them.
546///
547/// Async counterpart of [`TieredDb`](crate::spool::TieredDb).
548pub struct TieredDbAsync<S, C, const SP: usize, const SS: usize, const CP: usize, const CS: usize> {
549    onboard: SensorDbAsync<S, SP, SS>,
550    spooler: SpoolerAsync<C, CP, CS>,
551    /// Where `append` writes, and every rule about when that moves.
552    tier: TierMode,
553}
554
555impl<S, C, const SP: usize, const SS: usize, const CP: usize, const CS: usize>
556    TieredDbAsync<S, C, SP, SS, CP, CS>
557where
558    S: NorFlash + ReadNorFlash,
559    C: NorFlash + ReadNorFlash,
560{
561    /// Combine a mounted onboard log with a spooler for the removable volume.
562    ///
563    /// # Errors
564    /// - `NotMounted` if the onboard log is not mounted
565    /// - `GeometryMismatch` if the volume's pages are smaller than the onboard
566    ///   log's
567    pub fn new(
568        onboard: SensorDbAsync<S, SP, SS>,
569        spooler: SpoolerAsync<C, CP, CS>,
570        policy: WritePolicy,
571    ) -> Result<Self, Error> {
572        if !onboard.is_mounted() {
573            return Err(Error::NotMounted);
574        }
575        if SP > CP {
576            return Err(Error::GeometryMismatch);
577        }
578        Ok(Self {
579            onboard,
580            spooler,
581            tier: TierMode::new(policy),
582        })
583    }
584
585    /// Attach a mounted volume and seed the onboard watermark from its cursor.
586    ///
587    /// An interrupted batch is reconciled here, so the restored watermark
588    /// accounts for what the replica already holds and
589    /// [`Attached::resume_from`] is the reconciled position.
590    ///
591    /// # Errors
592    ///
593    /// As for [`TieredDb::attach`](super::TieredDb::attach), a late error from
594    /// the watermark's boundary scan leaves the volume attached and draining.
595    pub async fn attach(&mut self, volume: SensorDbAsync<C, CP, CS>) -> Result<Attached, Error> {
596        let mut attached = self.spooler.attach(volume).await?;
597
598        // Before the fallible part, so an `Err` cannot strand an attached volume
599        // behind a mode that will not drain it.
600        self.tier.attached();
601
602        // Restored from the *committed* cursor, before reconciling — see
603        // [`TieredDb::attach`](super::TieredDb::attach) for why the order is
604        // load-bearing.
605        self.onboard
606            .restore_spool_watermark(attached.resume_from)
607            .await?;
608
609        self.spooler.reconcile(&mut self.onboard).await?;
610        if let Some(resume) = self.spooler.resume_point() {
611            attached.resume_from = resume;
612        }
613        Ok(attached)
614    }
615
616    /// Detach the volume, rescuing anything it still held in RAM.
617    pub async fn detach(&mut self) -> Option<SensorDbAsync<C, CP, CS>> {
618        let _ = self.recover_from_volume_loss().await;
619        self.tier.fell_back();
620        self.spooler.detach()
621    }
622
623    /// Detach the volume without rescuing its RAM buffer.
624    pub fn detach_without_recovery(&mut self) -> Option<SensorDbAsync<C, CP, CS>> {
625        self.tier.fell_back();
626        self.spooler.detach()
627    }
628
629    /// Append a sample.
630    ///
631    /// Never fails because of the volume: a sample that cannot reach it is
632    /// written onboard instead, along with everything the volume had buffered.
633    pub async fn append(
634        &mut self,
635        sensor_id: u16,
636        timestamp: u64,
637        payload: &[u8],
638    ) -> Result<(), Error> {
639        if !self.tier.writes_to_volume() {
640            return self.onboard.append(sensor_id, timestamp, payload).await;
641        }
642
643        let attempt = match self.spooler.volume_mut() {
644            Some(volume) => volume.append(sensor_id, timestamp, payload).await,
645            None => Err(Error::NotAttached),
646        };
647
648        match attempt {
649            Ok(()) => Ok(()),
650            Err(e) if volume_gone(&e) => {
651                self.recover_from_volume_loss().await?;
652                self.onboard.append(sensor_id, timestamp, payload).await
653            }
654            Err(e) => Err(e),
655        }
656    }
657
658    /// Append a [run](crate::run), routed exactly as [`append`](Self::append) is.
659    pub async fn append_run(&mut self, run: &Run<'_>) -> Result<(), Error> {
660        if !self.tier.writes_to_volume() {
661            return self.onboard.append_run(run).await;
662        }
663
664        let attempt = match self.spooler.volume_mut() {
665            Some(volume) => volume.append_run(run).await,
666            None => Err(Error::NotAttached),
667        };
668
669        match attempt {
670            Ok(()) => Ok(()),
671            Err(e) if volume_gone(&e) => {
672                self.recover_from_volume_loss().await?;
673                self.onboard.append_run(run).await
674            }
675            Err(e) => Err(e),
676        }
677    }
678
679    /// Flush the buffered tail of whichever log is being written.
680    pub async fn sync(&mut self) -> Result<(), Error> {
681        if !self.tier.writes_to_volume() {
682            return self.onboard.sync().await;
683        }
684
685        let attempt = match self.spooler.volume_mut() {
686            Some(volume) => volume.sync().await,
687            None => Err(Error::NotAttached),
688        };
689
690        match attempt {
691            Ok(()) => Ok(()),
692            Err(e) if volume_gone(&e) => {
693                self.recover_from_volume_loss().await?;
694                self.onboard.sync().await
695            }
696            Err(e) => Err(e),
697        }
698    }
699
700    /// Fall back to the onboard log, rescuing whatever the volume held in RAM.
701    ///
702    /// A yank is not a power loss: the processor is still running, so samples in
703    /// the volume's page buffer are still readable. Draining touches no flash on
704    /// the volume, so this works with the medium physically gone.
705    ///
706    /// The rescued samples are staged in a stack buffer before being appended.
707    /// `drain_unflushed` hands them to a synchronous callback, and appending to
708    /// the onboard log is `async`, so they cannot be forwarded in one step. The
709    /// staging encoding is more compact than the on-flash one, so a page's worth
710    /// of entries always fits.
711    async fn recover_from_volume_loss(&mut self) -> Result<u32, Error> {
712        /// `sensor_id` + `timestamp` + `payload_len` + `kind`.
713        ///
714        /// The kind is staged too: a run rescued from the card's RAM buffer has
715        /// to land onboard as a run, or its frame becomes one opaque sample no
716        /// read could interpret.
717        const STAGED_HEADER: usize = 2 + 8 + 2 + 1;
718
719        let Self {
720            onboard,
721            spooler,
722            tier,
723        } = self;
724        tier.fell_back();
725
726        let Some(volume) = spooler.fault() else {
727            return Ok(0);
728        };
729
730        let mut staging = [0u8; CP];
731        let mut used = 0usize;
732        let drained = volume.drain_unflushed(|header, payload| {
733            let needed = STAGED_HEADER + payload.len();
734            if used + needed > staging.len() {
735                // Cannot happen: an on-flash entry costs ENTRY_OVERHEAD (20)
736                // bytes plus payload, more than the 13 staged here, so a page's
737                // worth always fits. Refusing leaves the volume's buffer intact
738                // and the operation retryable.
739                return Err(Error::NoSpace);
740            }
741            staging[used..used + 2].copy_from_slice(&header.sensor_id.to_le_bytes());
742            staging[used + 2..used + 10].copy_from_slice(&header.timestamp.to_le_bytes());
743            staging[used + 10..used + 12].copy_from_slice(&(payload.len() as u16).to_le_bytes());
744            staging[used + 12] = u8::from(header.is_run());
745            staging[used + STAGED_HEADER..used + needed].copy_from_slice(payload);
746            used += needed;
747            Ok(())
748        })?;
749
750        let mut pos = 0usize;
751        while pos + STAGED_HEADER <= used {
752            let sensor_id = u16::from_le_bytes([staging[pos], staging[pos + 1]]);
753            let mut ts = [0u8; 8];
754            ts.copy_from_slice(&staging[pos + 2..pos + 10]);
755            let timestamp = u64::from_le_bytes(ts);
756            let len = u16::from_le_bytes([staging[pos + 10], staging[pos + 11]]) as usize;
757            let kind = match staging[pos + 12] {
758                0 => EntryKind::Single,
759                _ => EntryKind::Run,
760            };
761            let start = pos + STAGED_HEADER;
762            let header = EntryHeader {
763                sensor_id,
764                timestamp,
765                payload_len: len as u16,
766                kind,
767            };
768            onboard
769                .append_framed(&header, &staging[start..start + len])
770                .await?;
771            pos = start + len;
772        }
773
774        Ok(drained)
775    }
776
777    /// Run one replication pass, if a volume is attached.
778    ///
779    /// `Ok(None)` means no volume. A *faulted* volume returns
780    /// [`Error::VolumeLost`] until [`detach`](Self::detach) is called.
781    pub async fn spool_step(
782        &mut self,
783        budget: SpoolBudget,
784    ) -> Result<Option<SpoolProgress>, Error> {
785        if !self
786            .tier
787            .ready_to_spool(self.spooler.is_attached(), self.spooler.is_faulted())?
788        {
789            return Ok(None);
790        }
791        let progress = self.spooler.spool(&mut self.onboard, budget).await?;
792        self.tier.spooled();
793        if progress.caught_up {
794            self.try_promote(budget).await?;
795        }
796        Ok(Some(progress))
797    }
798
799    /// Replicate until the volume is level with the onboard log.
800    pub async fn drain(
801        &mut self,
802        budget: SpoolBudget,
803        max_batches: u32,
804    ) -> Result<Option<SpoolProgress>, Error> {
805        if !self
806            .tier
807            .ready_to_spool(self.spooler.is_attached(), self.spooler.is_faulted())?
808        {
809            return Ok(None);
810        }
811        let progress = self
812            .spooler
813            .spool_until_caught_up(&mut self.onboard, budget, max_batches)
814            .await?;
815        self.tier.spooled();
816        if progress.caught_up {
817            self.try_promote(budget).await?;
818        }
819        Ok(Some(progress))
820    }
821
822    /// Promote to [`WriteMode::Direct`] if the backlog is fully replicated.
823    async fn try_promote(&mut self, budget: SpoolBudget) -> Result<(), Error> {
824        if !self
825            .tier
826            .may_promote(self.spooler.is_attached(), self.spooler.is_faulted())
827        {
828            return Ok(());
829        }
830
831        self.onboard.sync().await?;
832        let progress = self
833            .spooler
834            .spool_until_caught_up(&mut self.onboard, budget, PROMOTE_MAX_BATCHES)
835            .await?;
836        if progress.caught_up {
837            self.tier.promoted();
838        }
839        Ok(())
840    }
841
842    /// Which log `append` is currently writing to.
843    pub fn mode(&self) -> WriteMode {
844        self.tier.mode()
845    }
846
847    /// The configured write policy.
848    pub fn policy(&self) -> WritePolicy {
849        self.tier.policy()
850    }
851
852    /// Whether a volume is attached.
853    pub fn is_attached(&self) -> bool {
854        self.spooler.is_attached()
855    }
856
857    /// Replication accounting for the onboard log.
858    pub fn spool_stats(&self) -> SpoolStats {
859        self.onboard.spool_stats()
860    }
861
862    /// How much room is left on the removable volume.
863    ///
864    /// See [`TieredDb::volume_fill`](crate::spool::TieredDb::volume_fill).
865    pub fn volume_fill(&self) -> Option<VolumeFill> {
866        self.spooler.volume_fill()
867    }
868
869    /// The attached volume, if one is attached and usable.
870    pub fn volume(&self) -> Option<&SensorDbAsync<C, CP, CS>> {
871        self.spooler.volume()
872    }
873
874    /// The attached volume, if one is attached and usable.
875    pub fn volume_mut(&mut self) -> Option<&mut SensorDbAsync<C, CP, CS>> {
876        self.spooler.volume_mut()
877    }
878
879    /// The onboard log.
880    pub fn onboard(&self) -> &SensorDbAsync<S, SP, SS> {
881        &self.onboard
882    }
883
884    /// The onboard log.
885    pub fn onboard_mut(&mut self) -> &mut SensorDbAsync<S, SP, SS> {
886        &mut self.onboard
887    }
888
889    /// Consume this and return the parts.
890    pub fn into_parts(self) -> (SensorDbAsync<S, SP, SS>, SpoolerAsync<C, CP, CS>) {
891        (self.onboard, self.spooler)
892    }
893
894    /// The most recent entry for a sensor, across both logs.
895    ///
896    /// Exact: where the two logs overlap they hold identical entries, so taking
897    /// the later timestamp cannot be perturbed by the duplication.
898    pub async fn latest(
899        &mut self,
900        sensor_id: u16,
901        buf: &mut [u8],
902    ) -> Result<Option<(EntryHeader, usize)>, Error> {
903        let onboard = self.onboard.latest(sensor_id, buf).await?;
904
905        let mut alt = [0u8; CP];
906        let from_volume = match self.spooler.volume_mut() {
907            Some(volume) => volume.latest(sensor_id, &mut alt).await?,
908            None => return Ok(onboard),
909        };
910
911        merge(onboard, from_volume, &alt, buf, |v, o| v > o)
912    }
913
914    /// The oldest entry for a sensor, across both logs.
915    pub async fn oldest(
916        &mut self,
917        sensor_id: u16,
918        buf: &mut [u8],
919    ) -> Result<Option<(EntryHeader, usize)>, Error> {
920        let onboard = self.onboard.oldest(sensor_id, buf).await?;
921
922        let mut alt = [0u8; CP];
923        let from_volume = match self.spooler.volume_mut() {
924            Some(volume) => volume.oldest(sensor_id, &mut alt).await?,
925            None => return Ok(onboard),
926        };
927
928        merge(onboard, from_volume, &alt, buf, |v, o| v < o)
929    }
930
931    /// Entries in a timestamp range, across both logs.
932    ///
933    /// See [`TieredDb::query_range`](crate::spool::TieredDb::query_range) for
934    /// the ordering, the exactness argument, and why the onboard tail is scanned
935    /// without the bloom filter.
936    pub async fn query_range<F>(
937        &mut self,
938        sensor_id: Option<u16>,
939        t_start: u64,
940        t_end: u64,
941        mut callback: F,
942    ) -> Result<u32, Error>
943    where
944        F: FnMut(&EntryHeader, &[u8]) -> bool,
945    {
946        if self.spooler.volume().is_none() {
947            return self
948                .onboard
949                .query_range(sensor_id, t_start, t_end, callback)
950                .await;
951        }
952
953        let mut stopped = false;
954        let mut delivered = {
955            // Records whether the callback asked to stop, which `query_range`
956            // itself does not report.
957            let mut watched = |header: &EntryHeader, payload: &[u8]| {
958                let go = callback(header, payload);
959                stopped |= !go;
960                go
961            };
962            self.spooler
963                .volume_mut()
964                .expect("checked above")
965                .query_range(sensor_id, t_start, t_end, &mut watched)
966                .await?
967        };
968        if stopped {
969            return Ok(delivered);
970        }
971
972        // The onboard phases stream *entries*, so a run arrives whole and has to
973        // be expanded here — the volume's own `query_range` did that internally.
974        let mut scratch = [0u8; SP];
975        let mut expand =
976            |header: &EntryHeader, payload: &[u8], delivered: &mut u32, callback: &mut F| {
977                if sensor_id.is_some_and(|id| header.sensor_id != id) {
978                    return false;
979                }
980                let Some(dst) = scratch.get_mut(..payload.len()) else {
981                    return false;
982                };
983                dst.copy_from_slice(payload);
984                deliver_samples(
985                    header.is_run(),
986                    header.sensor_id,
987                    header.timestamp,
988                    dst,
989                    t_start,
990                    t_end,
991                    delivered,
992                    callback,
993                )
994            };
995
996        let watermark = self.onboard.spool_stats().watermark;
997        self.onboard
998            .read_from(watermark, u32::MAX, |_, header, payload| {
999                stopped = expand(header, payload, &mut delivered, &mut callback);
1000                Ok(!stopped)
1001            })
1002            .await?;
1003
1004        if stopped {
1005            return Ok(delivered);
1006        }
1007
1008        self.onboard.peek_unflushed(|header, payload| {
1009            if !stopped {
1010                stopped = expand(header, payload, &mut delivered, &mut callback);
1011            }
1012            Ok(())
1013        })?;
1014
1015        Ok(delivered)
1016    }
1017
1018    /// Every entry for a sensor across both logs, in log order.
1019    pub async fn query_all<F>(&mut self, sensor_id: Option<u16>, callback: F) -> Result<u32, Error>
1020    where
1021        F: FnMut(&EntryHeader, &[u8]) -> bool,
1022    {
1023        self.query_range(sensor_id, 0, u64::MAX, callback).await
1024    }
1025
1026    /// Total entries across both logs, counted without double-counting.
1027    ///
1028    /// `sensor_id = None` is O(1). After an unclean removal the answer can
1029    /// over-count by at most [`SpoolBudget::max_entries`].
1030    pub async fn count(&mut self, sensor_id: Option<u16>) -> Result<u32, Error> {
1031        // Samples, not entries: `count` has to agree with what `query_range`
1032        // yields, and that expands runs.
1033        let unspooled = self.onboard.spool_stats().unspooled_samples;
1034        let watermark = self.onboard.spool_stats().watermark;
1035
1036        if self.spooler.volume().is_none() {
1037            return self.onboard.count(sensor_id).await;
1038        }
1039
1040        match sensor_id {
1041            None => {
1042                let on_volume = self
1043                    .spooler
1044                    .volume_mut()
1045                    .expect("checked above")
1046                    .count(None)
1047                    .await?;
1048                Ok(on_volume.saturating_add(unspooled))
1049            }
1050            Some(id) => {
1051                let on_volume = self
1052                    .spooler
1053                    .volume_mut()
1054                    .expect("checked above")
1055                    .count(Some(id))
1056                    .await?;
1057                // Count only the un-replicated tail onboard, so nothing is
1058                // counted twice.
1059                let mut tail = 0u32;
1060                let mut tally = |header: &EntryHeader, payload: &[u8]| {
1061                    if header.sensor_id == id {
1062                        tail += samples_in(header.is_run(), payload);
1063                    }
1064                };
1065                self.onboard
1066                    .read_from(watermark, u32::MAX, |_, header, payload| {
1067                        tally(header, payload);
1068                        Ok(true)
1069                    })
1070                    .await?;
1071                // `read_from` stops at the durable tail, so this third phase is
1072                // not optional — `query_range` goes on to `peek_unflushed`, and
1073                // without it `count` reported zero for a sensor whose only entry
1074                // was still in the RAM page buffer.
1075                self.onboard.peek_unflushed(|header, payload| {
1076                    tally(header, payload);
1077                    Ok(())
1078                })?;
1079                Ok(on_volume.saturating_add(tail))
1080            }
1081        }
1082    }
1083}
1084
1085impl<S, C, const SP: usize, const SS: usize, const CP: usize, const CS: usize>
1086    TieredDbAsync<S, C, SP, SS, CP, CS>
1087where
1088    S: NorFlash + ReadNorFlash,
1089    C: NorFlash + ReadNorFlash + Removable,
1090{
1091    /// Notice a removal before a write has to fail.
1092    ///
1093    /// Returns the number of samples rescued; zero when the medium is present.
1094    pub async fn check_presence(&mut self) -> Result<u32, Error> {
1095        if !self.spooler.is_attached() || self.spooler.is_faulted() {
1096            return Ok(0);
1097        }
1098        if self.spooler.is_present() {
1099            return Ok(0);
1100        }
1101        self.recover_from_volume_loss().await
1102    }
1103
1104    /// Run one replication pass, skipping it when the medium reports absent.
1105    pub async fn spool_step_if_present(
1106        &mut self,
1107        budget: SpoolBudget,
1108    ) -> Result<Option<SpoolProgress>, Error> {
1109        self.check_presence().await?;
1110        if !self.spooler.is_attached() || self.spooler.is_faulted() {
1111            return Ok(None);
1112        }
1113        self.spool_step(budget).await
1114    }
1115}
1116
1117// ---------------------------------------------------------------------------
1118// Capability ports
1119// ---------------------------------------------------------------------------
1120//
1121// Async mirror of the blocking impls; see those for why delegation is spelled
1122// with UFCS.
1123
1124impl<S, C, const SP: usize, const SS: usize, const CP: usize, const CS: usize>
1125    crate::port::LogSinkAsync for TieredDbAsync<S, C, SP, SS, CP, CS>
1126where
1127    S: NorFlash + ReadNorFlash,
1128    C: NorFlash + ReadNorFlash,
1129{
1130    fn append(
1131        &mut self,
1132        sensor_id: u16,
1133        timestamp: u64,
1134        payload: &[u8],
1135    ) -> impl core::future::Future<Output = Result<(), Error>> {
1136        TieredDbAsync::append(self, sensor_id, timestamp, payload)
1137    }
1138
1139    fn append_run(
1140        &mut self,
1141        run: &Run<'_>,
1142    ) -> impl core::future::Future<Output = Result<(), Error>> {
1143        TieredDbAsync::append_run(self, run)
1144    }
1145
1146    fn sync(&mut self) -> impl core::future::Future<Output = Result<(), Error>> {
1147        TieredDbAsync::sync(self)
1148    }
1149}
1150
1151impl<S, C, const SP: usize, const SS: usize, const CP: usize, const CS: usize>
1152    crate::port::LogSourceAsync for TieredDbAsync<S, C, SP, SS, CP, CS>
1153where
1154    S: NorFlash + ReadNorFlash,
1155    C: NorFlash + ReadNorFlash,
1156{
1157    fn latest(
1158        &mut self,
1159        sensor_id: u16,
1160        buf: &mut [u8],
1161    ) -> impl core::future::Future<Output = Result<Option<(EntryHeader, usize)>, Error>> {
1162        TieredDbAsync::latest(self, sensor_id, buf)
1163    }
1164
1165    fn oldest(
1166        &mut self,
1167        sensor_id: u16,
1168        buf: &mut [u8],
1169    ) -> impl core::future::Future<Output = Result<Option<(EntryHeader, usize)>, Error>> {
1170        TieredDbAsync::oldest(self, sensor_id, buf)
1171    }
1172
1173    fn count(
1174        &mut self,
1175        sensor_id: Option<u16>,
1176    ) -> impl core::future::Future<Output = Result<u32, Error>> {
1177        TieredDbAsync::count(self, sensor_id)
1178    }
1179
1180    fn query_range(
1181        &mut self,
1182        sensor_id: Option<u16>,
1183        t_start: u64,
1184        t_end: u64,
1185        callback: &mut dyn FnMut(&EntryHeader, &[u8]) -> bool,
1186    ) -> impl core::future::Future<Output = Result<u32, Error>> {
1187        TieredDbAsync::query_range(self, sensor_id, t_start, t_end, callback)
1188    }
1189}
1190
1191impl<S, C, const SP: usize, const SS: usize, const CP: usize, const CS: usize> core::fmt::Debug
1192    for TieredDbAsync<S, C, SP, SS, CP, CS>
1193{
1194    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1195        f.debug_struct("TieredDbAsync")
1196            .field("policy", &self.tier.policy())
1197            .field("mode", &self.tier.mode())
1198            .field("attached", &self.spooler.is_attached())
1199            .finish_non_exhaustive()
1200    }
1201}