armdb 0.15.1

sharded bitcask key-value storage optimized for NVMe
Documentation
use std::ops::ControlFlow;

use armour_core::{GetRefs, GetType, StorageBackend, StorageClass};

use crate::access::Access;
use crate::armour::collection::Collection;
use crate::key::Key;
use crate::{CollectionMeta, DbResult};

mod sealed {
    pub trait Sealed {}
}

/// What one [`SchemaCollection::scan`] pass could not visit.
///
/// Returned by the pass itself, so a finding derived from it describes the
/// rows *that* pass checked, not those of an independent re-scan: a transient
/// read error that a second pass would not see still marks the first one
/// incomplete.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct ScanOutcome {
    /// Rows handed over as errors and skipped (their value does not decode,
    /// or the row cannot be read), not counting the error in
    /// [`stopped_at`](Self::stopped_at).
    pub skipped: u64,
    /// The error that ended the scan, when one did. Rows after it were not
    /// visited at all, so their number is unknown. Only a segmented
    /// collection stops this way: a storage error inside its k-way merge
    /// cannot be stepped over without exposing an older, shadowed version.
    pub stopped_at: Option<String>,
}

impl ScanOutcome {
    /// Every row was visited.
    pub fn is_complete(&self) -> bool {
        self.skipped == 0 && self.stopped_at.is_none()
    }

    /// Fold another pass over the same collection into this one: the larger
    /// skip count, the first stopping error.
    pub(super) fn merge(&mut self, other: &ScanOutcome) {
        self.skipped = self.skipped.max(other.skipped);
        if self.stopped_at.is_none() {
            self.stopped_at.clone_from(&other.stopped_at);
        }
    }
}

/// Write/delete in an index collection from a generated hook.
pub trait IndexTarget: SchemaCollection {
    fn put_entry(&self, k: &Self::K, v: &Self::V) -> DbResult<()>;
    fn delete_entry(&self, k: &Self::K) -> DbResult<()>;
}

/// Typed collection access for the schema registry and validator.
/// Each impl knows how to scan and check key presence.
pub trait SchemaCollection: Collection + Send + Sync + 'static + sealed::Sealed {
    type K: Key + GetRefs + GetType + 'static;
    type V: CollectionMeta + GetRefs + 'static;

    /// Physical storage class of this collection.
    const STORAGE: StorageClass;

    /// Visit every readable row and report what this pass could not visit.
    ///
    /// A row whose value does not decode, or that cannot be read, is skipped
    /// and counted. A segmented collection ends the walk at a storage error
    /// instead (see [`ScanOutcome::stopped_at`]). The validator and `repair`
    /// turn a non-complete outcome into a finding and hold back destructive
    /// repairs of everything the collection feeds.
    fn scan(&self, f: &mut dyn FnMut(&Self::K, &Self::V)) -> ScanOutcome;

    /// Count rows a [`scan`](Self::scan) would skip because their stored value
    /// cannot be decoded (or the row cannot be read at all), with a separate
    /// pass.
    ///
    /// `validate` and `repair` do not use this: they read the
    /// [`ScanOutcome`] of the very pass that checked the rows, since an
    /// independent re-scan can miss a transient error. Collections whose
    /// `scan` cannot skip anything return `0` without a second pass.
    fn undecodable_rows(&self) -> u64 {
        0
    }

    /// The `(rows, bytes)` budget one `project` call runs under on this open
    /// collection, so `validate`/`repair` evaluate the write path's contract
    /// rather than assuming the crate defaults. `None` — not a projecting family.
    #[doc(hidden)]
    fn effective_projection_limits(&self) -> Option<(usize, usize)> {
        None
    }

    /// Whether a row exists. A read error is returned, never read as absence.
    fn contains_key(&self, key: &Self::K) -> DbResult<bool>;
    /// `Ok(false)` — no record; `Ok(true)` — the record exists and `f` was
    /// called with the value; `Err` — the record could not be read or decoded.
    fn with_value(&self, key: &Self::K, f: &mut dyn FnMut(&Self::V)) -> DbResult<bool>;
}

impl<S, K, V> sealed::Sealed for S
where
    S: Access<Key = K, Val = V> + Collection,
    K: Key + GetRefs + GetType + 'static,
    V: CollectionMeta + GetRefs + 'static,
{
}

impl<S, K, V> SchemaCollection for S
where
    S: Access<Key = K, Val = V> + Collection,
    K: Key + GetRefs + GetType + 'static,
    V: CollectionMeta + GetRefs + 'static,
{
    type K = K;
    type V = V;
    const STORAGE: StorageClass = S::STORAGE;

    fn scan(&self, f: &mut dyn FnMut(&Self::K, &Self::V)) -> ScanOutcome {
        let mut outcome = ScanOutcome::default();
        // The error the walk last handed over, cleared by every row after it.
        let mut last_error: Option<String> = None;
        Access::scan_all(self, &mut |row| {
            match row {
                Ok((k, v)) => {
                    last_error = None;
                    f(k, v);
                }
                Err(e) => {
                    outcome.skipped += 1;
                    last_error = Some(e.to_string());
                }
            }
            ControlFlow::Continue(())
        });
        // A segmented scan stops at a storage error. Nothing distinguishes
        // that error from a final undecodable row, so a walk that ended on an
        // error is reported as stopped there; either way no row after it was
        // visited. The other families step over a bad row and never stop.
        if <S as Access>::STORAGE.backend == StorageBackend::Segmented
            && let Some(error) = last_error
        {
            outcome.skipped -= 1;
            outcome.stopped_at = Some(error);
        }
        outcome
    }

    fn undecodable_rows(&self) -> u64 {
        Access::undecodable_rows(self)
    }

    fn effective_projection_limits(&self) -> Option<(usize, usize)> {
        Access::effective_projection_limits(self)
    }

    fn contains_key(&self, key: &Self::K) -> DbResult<bool> {
        Access::contains(self, key)
    }

    fn with_value(&self, key: &Self::K, f: &mut dyn FnMut(&Self::V)) -> DbResult<bool> {
        Ok(Access::with_value(self, key, |v| f(v))?.is_some())
    }
}

impl<S, K, V> IndexTarget for S
where
    S: Access<Key = K, Val = V> + Collection,
    K: Key + GetRefs + GetType + 'static,
    V: CollectionMeta + GetRefs + 'static,
{
    fn put_entry(&self, k: &Self::K, v: &Self::V) -> DbResult<()> {
        Access::put_ref(self, k, v)
    }

    fn delete_entry(&self, k: &Self::K) -> DbResult<()> {
        Access::delete(self, k)
    }
}