@feltdb/core 0.8.3 → 0.8.5

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

@@ -0,0 +1,234 @@
+//! 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",
+    );
+}