armdb 0.15.0

sharded bitcask key-value storage optimized for NVMe
Documentation
//! Process-loss injection at every durable boundary of the segmented family.
//!
//! Compiled for tests and under `test-faults` only, and not a public API. A
//! child process sets [`STAGE`], runs a workload, and is gone the moment it
//! reaches the stage.
//!
//! # Only in a child process
//!
//! [`STAGE`] and [`SKIP`] are process-global, and reaching the stage ends the
//! **whole process** with `exit(9)`. Set them only in a child process spawned
//! for the purpose (see `tests/seg_crash.rs`), never in a test that shares its
//! process with others: under `cargo test` every other test of the binary
//! dies with it, and any segmented collection open in the process passes the
//! same failpoints.

use std::sync::atomic::{AtomicU8, AtomicU32, Ordering};
use std::{cell::Cell, marker::PhantomData, rc::Rc};

/// Disable every process-loss injection point.
pub const NONE: u8 = 0;
/// The collection root exists and is durable; no manifest yet.
pub const LAYOUT_CREATED: u8 = 1;
/// The first manifest is published; it names no generation.
pub const FIRST_MANIFEST_PUBLISHED: u8 = 2;
/// A generation id is reserved; its directory does not exist.
pub const GENERATION_ID_RESERVED: u8 = 3;
/// A generation directory exists and is durable; the manifest does not name it.
pub const GENERATION_CREATED: u8 = 4;
/// The manifest names the new generation; the view is not replaced.
pub const FREEZE_PUBLISHED: u8 = 5;
/// The first block of a segment is written to its temporary file.
pub const SEGMENT_BEING_WRITTEN: u8 = 6;
/// Both segment files have their final names; the manifest does not name them.
pub const SEGMENT_FILES_RENAMED: u8 = 7;
/// The manifest names the segment; the generation directory still exists.
pub const SEAL_PUBLISHED: u8 = 8;
/// The manifest no longer names a segment; its files still exist.
pub const DROP_PUBLISHED: u8 = 9;
/// `MANIFEST.tmp` is written and synced; it is not renamed.
pub const MANIFEST_TMP_WRITTEN: u8 = 10;
/// `MANIFEST.tmp` is renamed; the directory is not synced.
pub const MANIFEST_RENAMED: u8 = 11;

/// Fail the `n`-th metadata read of this collection from now; zero disarms.
pub fn fail_meta_read<K, T, C, H>(map: &super::SegMap<K, T, C, H>, n: u64)
where
    K: crate::Key + std::hash::Hash + Eq + Send + Sync + 'static,
    C: crate::Codec<T>,
    H: crate::TypedWriteHook<K, T>,
{
    map.core().shared.io.fail_read_at(n);
}

/// Metadata read attempts of this collection, injected failures included.
pub fn meta_read_attempts<K, T, C, H>(map: &super::SegMap<K, T, C, H>) -> u64
where
    K: crate::Key + std::hash::Hash + Eq + Send + Sync + 'static,
    C: crate::Codec<T>,
    H: crate::TypedWriteHook<K, T>,
{
    map.core().shared.io.read_attempts()
}

/// Convert a closed test collection's sidecars to the legacy metadata format.
///
/// All collection handles and its database must be closed and dropped before
/// calling this fixture-only helper. It removes only PAGE_INDEX, preserves all
/// other sections and manifest fields, and updates sidecar length/checksum.
/// Never use it against a live collection or non-test data.
#[cfg(feature = "test-faults")]
pub fn make_legacy_fixture(collection_dir: &std::path::Path) -> crate::DbResult<()> {
    use super::manifest;
    use super::seal::{SEG_DIR, sidx_name};
    use super::sidecar::{
        SECTION_PAGE_INDEX, SIDX_FOOTER_LEN, Sidecar, encode_sidecar, parse_footer, parse_table,
    };
    let mut manifest = manifest::load(collection_dir)?
        .ok_or(crate::DbError::Internal("legacy fixture has no manifest"))?;
    for rec in &mut manifest.segments {
        let path = collection_dir
            .join(SEG_DIR)
            .join(sidx_name(rec.segment_id, rec.version));
        let bytes = std::fs::read(&path)?;
        let fault = |fault: super::FormatFault| fault.into_db(rec.segment_id, None, &path);
        let original = Sidecar::parse(&bytes).map_err(fault)?;
        let footer = bytes.len() - SIDX_FOOTER_LEN;
        let (at, count, crc) = parse_footer(&bytes[footer..], bytes.len() as u64).map_err(fault)?;
        let table = parse_table(&bytes[at as usize..footer], count, crc, at).map_err(fault)?;
        let sections: Vec<_> = table
            .into_iter()
            .filter(|section| section.kind != SECTION_PAGE_INDEX)
            .map(|section| {
                (
                    section.kind,
                    bytes[section.offset as usize..(section.offset + section.len) as usize]
                        .to_vec(),
                )
            })
            .collect();
        let legacy = encode_sidecar(&original.header, &sections);
        std::fs::write(&path, &legacy)?;
        rec.sidx_len = legacy.len() as u64;
        rec.sidx_checksum = xxhash_rust::xxh3::xxh3_64(&legacy);
    }
    manifest::publish(super::fs::real().as_ref(), collection_dir, &manifest)
        .map_err(|error| error.into_inner())
}

/// The stage at which the process ends. [`NONE`] disables every failpoint.
pub static STAGE: AtomicU8 = AtomicU8::new(NONE);
/// Times the stage is passed before the process ends. Lets a test reach the
/// n-th manifest publication.
pub static SKIP: AtomicU32 = AtomicU32::new(0);

/// Exit without running destructors when the selected stage exhausts its skips.
pub fn hit(stage: u8) {
    if STAGE.load(Ordering::SeqCst) != stage {
        return;
    }
    let passed = SKIP
        .fetch_update(Ordering::SeqCst, Ordering::SeqCst, |left| {
            left.checked_sub(1)
        })
        .is_ok();
    if passed {
        return;
    }
    // A hard exit models process loss after the preceding durable action,
    // without running a destructor that could clean up after it.
    std::process::exit(9);
}

/// Suppress worker startup in deterministic crash fixtures. This does not stop
/// workers already running; construct it before opening the collection.
/// Only opens on the caller thread are suppressed; the guard cannot move.
#[must_use]
pub struct WorkerPauseGuard(PhantomData<Rc<()>>);
thread_local! { static WORKER_PAUSED: Cell<bool> = const { Cell::new(false) }; }
impl WorkerPauseGuard {
    /// Claim worker-startup suppression until this guard drops.
    pub fn new() -> Self {
        assert!(
            WORKER_PAUSED.with(|paused| !paused.replace(true)),
            "segmented worker startup is already paused"
        );
        Self(PhantomData)
    }
}
impl Default for WorkerPauseGuard {
    fn default() -> Self {
        Self::new()
    }
}
impl Drop for WorkerPauseGuard {
    fn drop(&mut self) {
        WORKER_PAUSED.with(|paused| paused.set(false));
    }
}
pub(crate) fn worker_paused() -> bool {
    WORKER_PAUSED.with(Cell::get)
}

/// Flush only the active generation, leaving a frozen unflushed tail intact.
/// Used to construct I1's durable younger layer without making G1 durable.
pub fn flush_active<K, T, C, H>(map: &super::SegMap<K, T, C, H>) -> crate::DbResult<()>
where
    K: crate::Key + std::hash::Hash + Eq + Send + Sync + 'static,
    C: crate::Codec<T>,
    H: crate::TypedWriteHook<K, T>,
{
    map.core().view().active.durable_flush()
}

/// Historical generation topology/ranges, active first then frozen layers.
/// The snapshot lets crash oracles prove which generation replay must target.
pub fn generation_ranges<K, T, C, H>(map: &super::SegMap<K, T, C, H>) -> Vec<(u64, usize, u64, u64)>
where
    K: crate::Key + std::hash::Hash + Eq + Send + Sync + 'static,
    C: crate::Codec<T>,
    H: crate::TypedWriteHook<K, T>,
{
    let view = map.core().view();
    std::iter::once(&view.active)
        .chain(view.frozen.iter())
        .map(|g| (g.id(), g.shard_count(), g.min_gsn(), g.max_gsn()))
        .collect()
}

/// Return a finish error while the context still owns its index locks. The
/// context destructor must clean up logged debt before releasing those locks.
/// Only finishes on the caller thread are affected; the guard cannot move.
#[must_use]
pub struct FinishFailGuard(PhantomData<Rc<()>>);
thread_local! { static FINISH_FAIL: Cell<bool> = const { Cell::new(false) }; }
impl FinishFailGuard {
    /// Claim the finish-error injection until this guard drops.
    pub fn new() -> Self {
        assert!(
            FINISH_FAIL.with(|failed| !failed.replace(true)),
            "segmented finish failure is already armed"
        );
        Self(PhantomData)
    }
}
impl Default for FinishFailGuard {
    fn default() -> Self {
        Self::new()
    }
}
impl Drop for FinishFailGuard {
    fn drop(&mut self) {
        FINISH_FAIL.with(|failed| failed.set(false));
    }
}
pub(crate) fn finish_failed() -> bool {
    FINISH_FAIL.with(Cell::get)
}

/// Read the live indexed journal records of frozen generations, including
/// tombstones. This checks actual encoded GSNs rather than only manifest ranges.
pub fn frozen_record_gsns<K, T, C, H>(map: &super::SegMap<K, T, C, H>) -> crate::DbResult<Vec<u64>>
where
    K: crate::Key + std::hash::Hash + Eq + Send + Sync + 'static,
    C: crate::Codec<T>,
    H: crate::TypedWriteHook<K, T>,
{
    use zerocopy::FromBytes;
    let core = map.core();
    let view = core.view();
    let mut gsns = Vec::new();
    for generation in &view.frozen {
        for (hash, _, loc) in generation.snapshot_range(0, u64::MAX, core.seed) {
            let entry = generation.read_entry(hash, &loc.loc)?;
            let header = crate::entry::EntryHeader::read_from_bytes(&entry[..16])
                .map_err(|_| crate::DbError::Internal("invalid fault-fixture entry header"))?;
            gsns.push(header.sequence());
        }
    }
    Ok(gsns)
}

/// Tree counterpart of [`flush_active`] for the shared crash scenario.
pub fn tree_flush_active<K, T, C, H>(map: &super::SegTree<K, T, C, H>) -> crate::DbResult<()>
where
    K: crate::Key + std::hash::Hash + Eq + Send + Sync + 'static,
    C: crate::Codec<T>,
    H: crate::TypedWriteHook<K, T>,
{
    map.core().view().active.durable_flush()
}

/// Tree counterpart of [`generation_ranges`] for the shared crash scenario.
pub fn tree_generation_ranges<K, T, C, H>(
    map: &super::SegTree<K, T, C, H>,
) -> Vec<(u64, usize, u64, u64)>
where
    K: crate::Key + std::hash::Hash + Eq + Send + Sync + 'static,
    C: crate::Codec<T>,
    H: crate::TypedWriteHook<K, T>,
{
    let view = map.core().view();
    std::iter::once(&view.active)
        .chain(view.frozen.iter())
        .map(|g| (g.id(), g.shard_count(), g.min_gsn(), g.max_gsn()))
        .collect()
}

/// Tree counterpart of [`frozen_record_gsns`] for the shared crash scenario.
pub fn tree_frozen_record_gsns<K, T, C, H>(
    map: &super::SegTree<K, T, C, H>,
) -> crate::DbResult<Vec<u64>>
where
    K: crate::Key + std::hash::Hash + Eq + Send + Sync + 'static,
    C: crate::Codec<T>,
    H: crate::TypedWriteHook<K, T>,
{
    use zerocopy::FromBytes;
    let core = map.core();
    let view = core.view();
    let mut gsns = Vec::new();
    for generation in &view.frozen {
        for (hash, _, loc) in generation.snapshot_range(0, u64::MAX, core.seed) {
            let entry = generation.read_entry(hash, &loc.loc)?;
            let header = crate::entry::EntryHeader::read_from_bytes(&entry[..16])
                .map_err(|_| crate::DbError::Internal("invalid fault-fixture entry header"))?;
            gsns.push(header.sequence());
        }
    }
    Ok(gsns)
}

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn worker_scoped_isolation_allows_foreign_thread_startup() {
        let _pause = WorkerPauseGuard::new();
        assert!(worker_paused());
        std::thread::spawn(|| {
            let dir = tempfile::tempdir().unwrap();
            let core = super::super::testkit::open_core_with_worker(
                dir.path(),
                super::super::SegConfig::test(),
            );
            assert!(
                core.worker_running(),
                "foreign caller must start its normal worker"
            );
        })
        .join()
        .unwrap();
    }
    #[test]
    fn finish_scoped_isolation_does_not_fail_foreign_caller() {
        let _fail = FinishFailGuard::new();
        assert!(finish_failed());
        std::thread::spawn(|| {
            use crate::txn::participant::TxParticipant;
            let dir = tempfile::tempdir().unwrap();
            let map: super::super::SegMap<
                super::super::testkit::TestKey,
                String,
                super::super::testkit::TextCodec,
            > = super::super::SegMap::open_with(
                dir.path(),
                super::super::testkit::meta(),
                super::super::SegConfig::test(),
                super::super::testkit::TextCodec,
                super::super::core::OpenOptions {
                    worker: false,
                    ..super::super::core::OpenOptions::production()
                },
            )
            .unwrap();
            let held = map.lock_shards(&[]).unwrap();
            held.finish(
                &mut Vec::new(),
                &mut crate::watch::WatchWakeBatch::default(),
            )
            .expect("foreign caller must finish normally");
            assert!(
                !finish_failed(),
                "foreign caller must not inherit finish injection"
            );
        })
        .join()
        .unwrap();
    }
    #[test]
    fn worker_and_finish_scoped_panic_reset() {
        assert!(
            std::panic::catch_unwind(|| {
                let _pause = WorkerPauseGuard::new();
                let _fail = FinishFailGuard::new();
                assert!(worker_paused());
                assert!(finish_failed());
                panic!("reset scoped controls");
            })
            .is_err()
        );
        assert!(!worker_paused());
        assert!(!finish_failed());
        let _pause = WorkerPauseGuard::new();
        let _fail = FinishFailGuard::new();
    }
}