@feltdb/core 0.13.0 → 0.16.0

package/dist/create/server-source/crates/feltdb/tests/operational_health_contract.rs

@@ -1,278 +0,0 @@
-//! Operational health.
-//!
-//! Everything from the format work onward proved what FeltDB *does*. This file
-//! asks a different question:
-//!
-//! > **Can an operator reliably tell what FeltDB knows about itself?**
-//!
-//! The rule the whole surface is built on:
-//!
-//! > **Health can expose a proven fact. It cannot create a stronger
-//! > guarantee.**
-//!
-//! So `DatabaseHealth` reports the durable format an open accepted and whether
-//! replay discarded an incomplete final append, and nothing else. There is no
-//! replication health, no backup freshness and no durability claim, because
-//! none of those has an operational contract yet and inventing one here would
-//! reintroduce exactly the defect this replaces: a reassuring label that
-//! observes nothing.
-//!
-//! See `docs/architecture/operational-health.md`.
-
-use feltdb::{
-    inspect_durable_format, DatabaseHealth, DurableFormat, FeltDb, FlowError, LogRecovery,
-    StorageHealth, DURABLE_FORMAT_VERSION,
-};
-use serde_json::{json, Value};
-use std::io::Write;
-use std::path::Path;
-use tempfile::TempDir;
-
-fn three_writes(path: &Path) -> Vec<u8> {
-    let db = FeltDb::open(path).unwrap();
-    for n in 0..3 {
-        db.insert(&format!("tasks:{n}"), json!({ "n": n })).unwrap();
-    }
-    drop(db);
-    std::fs::read(path).unwrap()
-}
-
-// ---------------------------------------------------------------------------
-// The five questions health has to answer
-// ---------------------------------------------------------------------------
-
-/// **A clean startup reports clean.**
-#[test]
-fn a_clean_open_reports_clean_storage() {
-    let directory = TempDir::new().unwrap();
-    let path = directory.path().join("clean.log");
-    three_writes(&path);
-
-    let db = FeltDb::open(&path).unwrap();
-    let health = db.health();
-
-    assert_eq!(health.storage, StorageHealth::Clean);
-    assert_eq!(health.recovery, LogRecovery::Clean);
-    assert_eq!(
-        health.durable_format,
-        DurableFormat::Versioned(DURABLE_FORMAT_VERSION)
-    );
-    assert!(health.is_nominal());
-    assert_eq!(health.storage.label(), "clean");
-}
-
-/// **The regression that matters.** A database that discarded a torn tail must
-/// not report the same health as one that replayed cleanly.
-///
-/// This is the operational consequence of the corruption work: the distinction
-/// between a clean open and a recovered one was established there, and it is
-/// worth nothing to an operator unless it reaches them.
-#[test]
-fn a_recovered_open_does_not_report_the_same_health_as_a_clean_one() {
-    let directory = TempDir::new().unwrap();
-    let clean_path = directory.path().join("clean.log");
-    let torn_path = directory.path().join("torn.log");
-    let full = three_writes(&clean_path);
-
-    // The same database, with its final append cut short.
-    std::fs::write(&torn_path, &full[..full.len() - 30]).unwrap();
-
-    let clean = FeltDb::open(&clean_path).unwrap().health();
-    let torn = FeltDb::open(&torn_path).unwrap().health();
-
-    assert_ne!(
-        clean, torn,
-        "a database that lost its last write must not look identical to one that did not"
-    );
-    assert!(clean.is_nominal());
-    assert!(!torn.is_nominal(), "recovered is not nominal");
-    assert_ne!(clean.storage.label(), torn.storage.label());
-
-    match torn.storage {
-        StorageHealth::RecoveredIncompleteWrite {
-            byte_offset,
-            discarded_bytes,
-        } => {
-            assert!(byte_offset > 0, "the operator is told where");
-            assert!(discarded_bytes > 0, "and how much");
-        }
-        other => panic!("expected a reported recovery, got {other:?}"),
-    }
-
-    // And it says so in words an operator can act on.
-    let described = torn.storage.to_string();
-    assert!(described.contains("incomplete append"));
-    assert!(described.contains("last write did not land"));
-}
-
-/// **A corrupt database does not become healthy.** It does not open at all.
-///
-/// The ambiguity being removed here is "healthy process, unhealthy database":
-/// there is no state in which a server is serving a database whose durable log
-/// failed to replay.
-#[test]
-fn a_corrupt_database_never_reaches_a_health_report() {
-    let directory = TempDir::new().unwrap();
-    let path = directory.path().join("corrupt.log");
-    three_writes(&path);
-
-    let mut file = std::fs::OpenOptions::new()
-        .append(true)
-        .open(&path)
-        .unwrap();
-    writeln!(file, "this is not json at all").unwrap();
-    drop(file);
-
-    match FeltDb::open(&path) {
-        Err(FlowError::CorruptLogLine(_)) => {}
-        Err(other) => panic!("wrong error: {other}"),
-        Ok(_) => panic!("a corrupt database opened and could have reported health"),
-    }
-}
-
-/// **An incompatible database stays refused**, so a running server cannot be
-/// advertising one.
-#[test]
-fn an_incompatible_database_never_reaches_a_health_report() {
-    let directory = TempDir::new().unwrap();
-    let path = directory.path().join("future.log");
-    std::fs::write(
-        &path,
-        format!(
-            "{}\n",
-            json!({
-                "record_type": "feltdb.format.v1",
-                "format_version": DURABLE_FORMAT_VERSION + 1
-            })
-        ),
-    )
-    .unwrap();
-
-    assert!(!inspect_durable_format(&path).unwrap().is_compatible());
-    assert!(matches!(
-        FeltDb::open(&path),
-        Err(FlowError::IncompatibleFormat(_))
-    ));
-}
-
-/// Health survives the thing it describes: reopening a repaired log reports
-/// clean again, because the condition is genuinely gone.
-///
-/// A status that stayed degraded forever would be as useless as one that never
-/// was.
-#[test]
-fn health_reflects_the_current_open_not_the_database_s_past() {
-    let directory = TempDir::new().unwrap();
-    let path = directory.path().join("repaired.log");
-    let full = three_writes(&path);
-    std::fs::write(&path, &full[..full.len() - 30]).unwrap();
-
-    let recovered = FeltDb::open(&path).unwrap();
-    assert!(!recovered.health().is_nominal());
-    drop(recovered);
-
-    let reopened = FeltDb::open(&path).unwrap();
-    assert!(
-        reopened.health().is_nominal(),
-        "the incomplete append is gone, so the condition is too"
-    );
-}
-
-/// A database with no torn tail but written before format versioning is
-/// reported as what it is, rather than as an error or as current.
-#[test]
-fn an_unversioned_database_reports_its_actual_format() {
-    let directory = TempDir::new().unwrap();
-    let path = directory.path().join("unversioned.log");
-    std::fs::write(
-        &path,
-        format!(
-            "{}\n",
-            json!({
-                "capability": "tasks", "key": "tasks:1",
-                "rust_type": "serde_json::value::Value", "value": {"n": 1},
-                "unix_ms": 1, "content_hash": null, "flow_ref": null,
-                "deleted": false, "operation": null
-            })
-        ),
-    )
-    .unwrap();
-
-    let health = FeltDb::open(&path).unwrap().health();
-    assert_eq!(health.durable_format, DurableFormat::Unversioned);
-    assert!(health.is_nominal(), "unversioned is not unhealthy");
-}
-
-// ---------------------------------------------------------------------------
-// What health deliberately does not say
-// ---------------------------------------------------------------------------
-
-/// **Health does not manufacture a guarantee the database does not have.**
-///
-/// The defect being replaced was `storage: "durable"` — a string constant that
-/// inspected nothing and asserted the one property still unproven. The
-/// replacement is a small closed set of observed conditions, and every label in
-/// it names what was seen rather than what would be reassuring.
-///
-/// In particular nothing here claims durability against power loss, which
-/// remains unproven; nothing claims the database is replicated, backed up, or
-/// within any capacity; and there is no "probably fine".
-#[test]
-fn health_reports_only_conditions_that_were_observed() {
-    let directory = TempDir::new().unwrap();
-    let clean = directory.path().join("a.log");
-    let torn = directory.path().join("b.log");
-    let full = three_writes(&clean);
-    std::fs::write(&torn, &full[..full.len() - 30]).unwrap();
-
-    let labels: Vec<&str> = [&clean, &torn]
-        .iter()
-        .map(|path| FeltDb::open(path).unwrap().health().storage.label())
-        .collect();
-
-    // Exactly two conditions, both naming an observation.
-    assert_eq!(labels, vec!["clean", "recovered-incomplete-write"]);
-    for label in &labels {
-        assert!(
-            !label.contains("durable") && !label.contains("healthy"),
-            "'{label}' would assert more than was observed"
-        );
-    }
-}
-
-/// The health value is derived from the recovery the open recorded, not from
-/// anything a caller can set.
-#[test]
-fn health_is_derived_from_the_open_rather_than_configured() {
-    let directory = TempDir::new().unwrap();
-    let path = directory.path().join("derived.log");
-    let full = three_writes(&path);
-    std::fs::write(&path, &full[..full.len() - 30]).unwrap();
-
-    let db = FeltDb::open(&path).unwrap();
-    let health: DatabaseHealth = db.health();
-
-    // The two agree because one is computed from the other.
-    match (&health.recovery, &health.storage) {
-        (
-            LogRecovery::RecoveredTornTail {
-                byte_offset: recovered_at,
-                discarded_bytes: recovered_bytes,
-            },
-            StorageHealth::RecoveredIncompleteWrite {
-                byte_offset,
-                discarded_bytes,
-            },
-        ) => {
-            assert_eq!(recovered_at, byte_offset);
-            assert_eq!(recovered_bytes, discarded_bytes);
-        }
-        other => panic!("recovery and storage disagree: {other:?}"),
-    }
-
-    // Writing more does not change what the open found.
-    db.insert("tasks:9", json!({"n": 9})).unwrap();
-    assert_eq!(db.health(), health);
-    let value: Value = db.get("tasks:9").unwrap().unwrap();
-    assert_eq!(value["n"], json!(9), "and the database is fully usable");
-}

package/dist/create/server-source/crates/feltdb/tests/pr34_query_collection.rs

@@ -1,234 +0,0 @@
-//! PR34 — bounded query execution without collection materialization.
-//!
-//! `FeltDb::query_collection` is the state-access primitive the bounded query
-//! surface executes on. These tests pin the two properties the query path
-//! depends on: it observes every live record of a collection in record-key
-//! order, and it clones only the records its predicate retains.
-
-use feltdb::{query_execution_diagnostics, FeltDb, StoredRow};
-use serde_json::json;
-use std::sync::{Mutex, MutexGuard, OnceLock};
-use tempfile::TempDir;
-
-/// The read counters are process-global, and the test binary runs its tests in
-/// threads of one process, so a counter assertion is only meaningful while no
-/// other test in this file is reading a collection.
-fn exclusive() -> MutexGuard<'static, ()> {
-    static SERIAL: OnceLock<Mutex<()>> = OnceLock::new();
-    SERIAL
-        .get_or_init(|| Mutex::new(()))
-        .lock()
-        .unwrap_or_else(|poisoned| poisoned.into_inner())
-}
-
-fn seeded(records: usize) -> (TempDir, FeltDb) {
-    let directory = TempDir::new().expect("temp dir");
-    let db = FeltDb::open(directory.path().join("pr34.log")).expect("open db");
-    for index in 0..records {
-        db.insert(
-            &format!("items:record-{index:05}"),
-            json!({ "tenant": format!("tenant-{}", index % 4), "n": index }),
-        )
-        .expect("insert");
-    }
-    (directory, db)
-}
-
-#[test]
-fn scan_returns_only_matching_records() {
-    let _serial = exclusive();
-    let (_directory, db) = seeded(40);
-
-    let matches = db
-        .query_collection("items", None, |row| {
-            row.value.get("tenant") == Some(&json!("tenant-1"))
-        })
-        .expect("scan");
-
-    assert_eq!(matches.len(), 10, "one quarter of the collection matches");
-    assert!(matches
-        .iter()
-        .all(|row| row.value.get("tenant") == Some(&json!("tenant-1"))));
-}
-
-#[test]
-fn scan_of_an_empty_or_unknown_collection_is_empty() {
-    let _serial = exclusive();
-    let (_directory, db) = seeded(0);
-
-    assert!(db
-        .query_collection("items", None, |_| true)
-        .expect("scan")
-        .is_empty());
-    assert!(db
-        .query_collection("no-such-collection", None, |_| true)
-        .expect("scan")
-        .is_empty());
-}
-
-#[test]
-fn scan_visits_records_in_record_key_order() {
-    let _serial = exclusive();
-    let (_directory, db) = seeded(16);
-
-    let keys: Vec<String> = db
-        .query_collection("items", None, |_| true)
-        .expect("scan")
-        .iter()
-        .map(|row: &StoredRow| row.key.clone())
-        .collect();
-    let mut sorted = keys.clone();
-    sorted.sort();
-
-    assert_eq!(keys, sorted, "traversal follows the collection's key order");
-}
-
-#[test]
-fn a_limit_stops_the_traversal_once_it_is_satisfied() {
-    let _serial = exclusive();
-    let (_directory, db) = seeded(500);
-
-    let mut visited = 0usize;
-    let matches = db
-        .query_collection("items", Some(5), |_| {
-            visited += 1;
-            true
-        })
-        .expect("scan");
-
-    assert_eq!(matches.len(), 5, "the limit bounds the result");
-    assert_eq!(
-        visited, 5,
-        "a satisfied limit stops the traversal instead of walking the collection"
-    );
-}
-
-#[test]
-fn a_scan_clones_only_the_records_it_retains() {
-    let _serial = exclusive();
-    let (_directory, db) = seeded(2_000);
-
-    let before = query_execution_diagnostics::counters();
-    let matches = db
-        .query_collection("items", None, |row| row.value.get("n") == Some(&json!(7)))
-        .expect("scan");
-    let after = query_execution_diagnostics::counters();
-
-    assert_eq!(matches.len(), 1);
-    assert_eq!(
-        after.full_collection_materializations, before.full_collection_materializations,
-        "a scan must not fall back to full collection materialization"
-    );
-    assert_eq!(
-        after.scan_records_visited - before.scan_records_visited,
-        2_000,
-        "the predicate observes every record, borrowed"
-    );
-    assert_eq!(
-        after.scan_records_materialized - before.scan_records_materialized,
-        1,
-        "only the matching record is cloned"
-    );
-}
-
-#[test]
-fn full_materialization_is_still_counted_for_readers_that_ask_for_it() {
-    let _serial = exclusive();
-    let (_directory, db) = seeded(32);
-
-    let before = query_execution_diagnostics::counters();
-    let rows = db.list_collection("items").expect("list");
-    let after = query_execution_diagnostics::counters();
-
-    assert_eq!(rows.len(), 32);
-    assert_eq!(
-        after.full_collection_materializations - before.full_collection_materializations,
-        1
-    );
-    assert_eq!(
-        after.full_collection_records_cloned - before.full_collection_records_cloned,
-        32,
-        "listing a collection clones every record in it"
-    );
-}
-
-#[test]
-fn a_scan_result_survives_concurrent_mutation() {
-    let _serial = exclusive();
-    let (_directory, db) = seeded(200);
-
-    let matches = db
-        .query_collection("items", None, |row| {
-            row.value.get("tenant") == Some(&json!("tenant-0"))
-        })
-        .expect("scan");
-
-    // The scan returns owned records, so mutation after the lock is released
-    // cannot invalidate or rewrite what the caller already holds.
-    for index in 0..200 {
-        db.delete(&format!("items:record-{index:05}"))
-            .expect("delete");
-    }
-
-    assert_eq!(matches.len(), 50);
-    assert!(matches
-        .iter()
-        .all(|row| row.value.get("tenant") == Some(&json!("tenant-0"))));
-    assert!(db
-        .query_collection("items", None, |_| true)
-        .expect("scan")
-        .is_empty());
-}
-
-/// PR35 addition: the indexed execution must not reach the materializing path.
-///
-/// PR34's claim was that a bounded query never enters `list_collection`. PR35
-/// adds a second execution, and an optimization that quietly fell back into a
-/// whole-collection clone would satisfy every correctness test in this
-/// repository while undoing the thing PR34 established. So the property is
-/// re-asserted against the execution that did not exist when it was first
-/// proved: indexed execution materializes nothing, and does not scan either.
-#[test]
-fn an_indexed_query_neither_materializes_nor_scans_the_collection() {
-    let _serial = exclusive();
-    let (_directory, db) = seeded(400);
-    db.create_equality_index("items", "tenant")
-        .expect("declare index");
-
-    let before = query_execution_diagnostics::counters();
-    let tenant = json!("tenant-1");
-    let matches = db
-        .query_collection_by_equality("items", &[("tenant", &tenant)], |row| {
-            row.value.get("tenant") == Some(&json!("tenant-1"))
-        })
-        .expect("indexed query")
-        .expect("the field is indexed");
-    let after = query_execution_diagnostics::counters();
-
-    assert_eq!(matches.len(), 100, "one quarter of the collection matches");
-    assert_eq!(
-        after.full_collection_materializations - before.full_collection_materializations,
-        0,
-        "indexed execution must not enter the full-collection materialization path",
-    );
-    assert_eq!(
-        after.collection_scans - before.collection_scans,
-        0,
-        "indexed execution is not a scan",
-    );
-    assert_eq!(
-        after.scan_records_visited - before.scan_records_visited,
-        0,
-        "and therefore visits no record by traversal",
-    );
-    assert_eq!(
-        after.queries_indexed - before.queries_indexed,
-        1,
-        "the query is attributed to the indexed execution",
-    );
-    assert_eq!(
-        after.records_predicate_evaluated - before.records_predicate_evaluated,
-        100,
-        "the predicate runs against the candidate set, not the collection",
-    );
-}