@feltdb/core 0.8.5 → 0.8.6

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

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