@feltdb/core 0.8.4 → 0.8.6

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

@@ -0,0 +1,392 @@
+//! Durable format versioning: FeltDB must fail closed when the durable meaning
+//! of its own data is unknown.
+//!
+//! The production invariant this file exists to enforce:
+//!
+//! > **A durable database must never silently discard persisted information
+//! > because the running FeltDB understands a different durable format.**
+//!
+//! Before this, a database written before revisions became resource-scoped
+//! opened cleanly and reported no history at all. The records were still on
+//! disk; every path that read them deserialized into the current shape and
+//! discarded what failed. The database looked healthy and had lost its history
+//! from the application's point of view. That is failing *open*.
+//!
+//! See `docs/architecture/durable-format-versioning.md`.
+
+use feltdb::state_model::StateStore;
+use feltdb::{
+    inspect_durable_format, DurableFormat, FeltDb, FlowError, FormatCompatibility,
+    DURABLE_FORMAT_VERSION,
+};
+use serde_json::{json, Value};
+use std::io::Write;
+use std::path::Path;
+use std::sync::Arc;
+use tempfile::TempDir;
+
+/// Write a durable log by hand, one JSON record per line.
+fn write_log(path: &Path, records: &[Value]) {
+    let mut file = std::fs::File::create(path).unwrap();
+    for record in records {
+        writeln!(file, "{}", serde_json::to_string(record).unwrap()).unwrap();
+    }
+}
+
+/// A data row as the log stores it.
+fn data_row(key: &str, value: Value) -> Value {
+    let capability = key.split_once(':').map(|(c, _)| c).unwrap_or("default");
+    json!({
+        "capability": capability,
+        "key": key,
+        "rust_type": "serde_json::value::Value",
+        "value": value,
+        "unix_ms": 1,
+        "content_hash": null,
+        "flow_ref": null,
+        "deleted": false,
+        "operation": null
+    })
+}
+
+/// A revision record in the pre-resource-scoped shape: content-only identity,
+/// no resource, no sequence.
+fn legacy_revision(id: &str, content: &str, parent: Option<&str>) -> Value {
+    json!({
+        "capability": "state",
+        "key": format!("state:revision:{id}"),
+        "rust_type": "feltdb::state_model::StateRevision",
+        "value": {
+            "id": id,
+            "content": content,
+            "parent_id": parent,
+            "authority": "before-the-model",
+            "timestamp_ms": 0,
+            "metadata": {}
+        },
+        "unix_ms": 1,
+        "content_hash": null,
+        "flow_ref": null,
+        "deleted": false,
+        "operation": null
+    })
+}
+
+/// A real legacy database: application state **and** revision history.
+fn legacy_database(path: &Path) {
+    write_log(
+        path,
+        &[
+            data_row("tasks:1", json!({"title": "B"})),
+            data_row("tasks:2", json!({"title": "C"})),
+            legacy_revision("aaa", r#"{"title":"A"}"#, None),
+            legacy_revision("bbb", r#"{"title":"B"}"#, Some("aaa")),
+        ],
+    );
+}
+
+// ---------------------------------------------------------------------------
+// The regression that matters
+// ---------------------------------------------------------------------------
+
+/// **The #307 U2 failure, encoded.**
+///
+/// A database written before revisions belonged to a resource must not open as
+/// though it were healthy and empty of history.
+///
+/// This is the most important test in the change; the implementation details
+/// are secondary to it.
+#[test]
+fn pre_306_database_does_not_open_as_empty_history() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("legacy.log");
+    legacy_database(&path);
+    let before = std::fs::read(&path).unwrap();
+
+    // 1. An explicit compatibility result, from a read-only examination.
+    let compatibility = inspect_durable_format(&path).unwrap();
+    let FormatCompatibility::Incompatible(incompatibility) = compatibility else {
+        panic!("the legacy format must be reported incompatible, got {compatibility:?}");
+    };
+    assert_eq!(incompatibility.found, DurableFormat::Unversioned);
+    assert_eq!(incompatibility.required, DURABLE_FORMAT_VERSION);
+    assert!(
+        incompatibility.reason.contains("resource"),
+        "the reason names the actual problem: {}",
+        incompatibility.reason
+    );
+    assert!(
+        !incompatibility.action.is_empty(),
+        "the operator is told what to do"
+    );
+
+    // 2. The open is refused, rather than succeeding with nothing to show.
+    match FeltDb::open(&path) {
+        Err(FlowError::IncompatibleFormat(reported)) => {
+            assert_eq!(*reported, incompatibility, "open agrees with the probe");
+            let rendered = FlowError::IncompatibleFormat(reported).to_string();
+            assert!(rendered.contains("INCOMPATIBLE_DURABLE_FORMAT"));
+            assert!(rendered.contains("No data was read or modified"));
+        }
+        Err(other) => panic!("wrong error: {other}"),
+        Ok(_) => panic!("the legacy database opened — this is the defect"),
+    }
+
+    // 3. Nothing was touched.
+    assert_eq!(
+        std::fs::read(&path).unwrap(),
+        before,
+        "a refused open must not modify a single byte"
+    );
+}
+
+/// Lossless migration is refused rather than attempted, and the reason is a
+/// property of the data rather than a shortage of effort.
+///
+/// A legacy revision recorded `id`, `content`, `parent_id`, `authority`,
+/// `timestamp_ms` and `metadata`. It did **not** record which resource it was a
+/// revision of — that absence is the finding the resource-scoped model was
+/// adopted to fix. So which history each legacy revision belongs to cannot be
+/// recovered from the data, and any migration would have to invent it.
+///
+/// Inventing it would produce a database that looks migrated and is wrong,
+/// which is worse than one that refuses.
+#[test]
+fn migration_is_refused_because_the_resource_was_never_recorded() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("legacy.log");
+    legacy_database(&path);
+
+    let FormatCompatibility::Incompatible(incompatibility) = inspect_durable_format(&path).unwrap()
+    else {
+        panic!("expected incompatible");
+    };
+    assert!(
+        incompatibility
+            .reason
+            .contains("cannot be migrated without inventing information"),
+        "the refusal explains why migration is not merely unimplemented: {}",
+        incompatibility.reason
+    );
+
+    // The legacy records are still readable as bytes by anything that
+    // understands them — nothing was deleted in the name of tidiness.
+    let text = std::fs::read_to_string(&path).unwrap();
+    assert!(text.contains("state:revision:aaa"));
+    assert!(text.contains("state:revision:bbb"));
+}
+
+// ---------------------------------------------------------------------------
+// Symmetry: no build silently interprets a format it does not understand
+// ---------------------------------------------------------------------------
+
+/// **Downgrade protection.** A database from a newer FeltDB is refused.
+///
+/// The invariant is symmetric, and this is the half a rollback hits: an
+/// operator reverting a deployment must not have the older build reinterpret
+/// data written by the newer one.
+#[test]
+fn a_newer_durable_format_is_refused() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("future.log");
+    write_log(
+        &path,
+        &[
+            json!({"record_type": "feltdb.format.v1", "format_version": DURABLE_FORMAT_VERSION + 1}),
+            data_row("tasks:1", json!({"title": "from the future"})),
+        ],
+    );
+    let before = std::fs::read(&path).unwrap();
+
+    let FormatCompatibility::Incompatible(incompatibility) = inspect_durable_format(&path).unwrap()
+    else {
+        panic!("a newer format must be refused");
+    };
+    assert_eq!(
+        incompatibility.found,
+        DurableFormat::Versioned(DURABLE_FORMAT_VERSION + 1)
+    );
+    assert!(incompatibility.reason.contains("newer"));
+
+    assert!(matches!(
+        FeltDb::open(&path),
+        Err(FlowError::IncompatibleFormat(_))
+    ));
+    assert_eq!(std::fs::read(&path).unwrap(), before, "untouched");
+}
+
+/// An older declared format is refused too, so the check is a version
+/// comparison rather than a special case for one legacy shape.
+#[test]
+fn an_older_declared_format_is_refused() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("old.log");
+    write_log(
+        &path,
+        &[json!({"record_type": "feltdb.format.v1", "format_version": 1})],
+    );
+    let FormatCompatibility::Incompatible(incompatibility) = inspect_durable_format(&path).unwrap()
+    else {
+        panic!("an older format must be refused");
+    };
+    assert_eq!(incompatibility.found, DurableFormat::Versioned(1));
+    assert!(matches!(
+        FeltDb::open(&path),
+        Err(FlowError::IncompatibleFormat(_))
+    ));
+}
+
+// ---------------------------------------------------------------------------
+// What must keep working
+// ---------------------------------------------------------------------------
+
+/// A new database states its format, and reopening it is compatible.
+#[test]
+fn a_new_database_declares_its_format() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("new.log");
+    let db = FeltDb::open(&path).unwrap();
+    db.insert("tasks:1", json!({"n": 1})).unwrap();
+
+    let text = std::fs::read_to_string(&path).unwrap();
+    let first = text.lines().next().unwrap();
+    let record: Value = serde_json::from_str(first).unwrap();
+    assert_eq!(record["record_type"], json!("feltdb.format.v1"));
+    assert_eq!(record["format_version"], json!(DURABLE_FORMAT_VERSION));
+
+    drop(db);
+    assert_eq!(
+        inspect_durable_format(&path).unwrap(),
+        FormatCompatibility::Compatible(DurableFormat::Versioned(DURABLE_FORMAT_VERSION))
+    );
+    let reopened = FeltDb::open(&path).unwrap();
+    let value: Value = reopened.get("tasks:1").unwrap().unwrap();
+    assert_eq!(value["n"], json!(1));
+}
+
+/// A database that predates format versioning but holds nothing whose meaning
+/// changed opens normally.
+///
+/// The refusal is targeted at data whose interpretation actually differs, not
+/// at every database that lacks a version record. Refusing those would make the
+/// safety check an upgrade wall.
+#[test]
+fn an_unversioned_database_without_legacy_revisions_still_opens() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("plain.log");
+    write_log(
+        &path,
+        &[
+            data_row("tasks:1", json!({"title": "A"})),
+            data_row("tasks:2", json!({"title": "B"})),
+        ],
+    );
+
+    assert_eq!(
+        inspect_durable_format(&path).unwrap(),
+        FormatCompatibility::Compatible(DurableFormat::Unversioned)
+    );
+    let db = FeltDb::open(&path).unwrap();
+    let value: Value = db.get("tasks:1").unwrap().unwrap();
+    assert_eq!(value["title"], json!("A"));
+}
+
+/// Compaction rewrites the log with the format stated in its header, so a
+/// compacted database is self-describing too.
+#[test]
+fn a_compacted_log_declares_its_format() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("compacted.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    db.insert("tasks:1", json!({"n": 0})).unwrap();
+    db.update("tasks:1", json!({"n": 1})).unwrap();
+
+    let versions = db.operation_versions().unwrap();
+    db.acknowledge_peer_versions("peer-1".to_string(), versions)
+        .unwrap();
+    db.compact_operation_log(&["peer-1".to_string()]).unwrap();
+    drop(db);
+
+    assert_eq!(
+        inspect_durable_format(&path).unwrap(),
+        FormatCompatibility::Compatible(DurableFormat::Versioned(DURABLE_FORMAT_VERSION))
+    );
+    let reopened = Arc::new(FeltDb::open(&path).unwrap());
+    let store = StateStore::with_feltdb(reopened.clone()).unwrap();
+    assert_eq!(
+        store.history_of("tasks:1").len(),
+        2,
+        "history survived compaction and reopen"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Snapshots
+// ---------------------------------------------------------------------------
+
+/// A snapshot carries its own format, and one from another format is refused.
+///
+/// Snapshots are durable interchange artifacts, not merely protocol values:
+/// they carry whole rows, revisions included. Leaving that path unversioned
+/// would have reopened the same hole the on-disk version closes.
+#[test]
+fn a_snapshot_from_another_format_is_refused() {
+    let directory = TempDir::new().unwrap();
+    let source = Arc::new(FeltDb::open(directory.path().join("source.log")).unwrap());
+    source.insert("tasks:1", json!({"n": 0})).unwrap();
+    source.update("tasks:1", json!({"n": 1})).unwrap();
+
+    let snapshot = source.export_snapshot().unwrap();
+    assert_eq!(snapshot.format_version, DURABLE_FORMAT_VERSION);
+
+    // A matching snapshot installs, history included.
+    let target = Arc::new(FeltDb::open(directory.path().join("target.log")).unwrap());
+    target.install_snapshot(snapshot.clone()).unwrap();
+    let store = StateStore::with_feltdb(target.clone()).unwrap();
+    assert_eq!(store.history_of("tasks:1").len(), 2);
+
+    // One claiming another format does not.
+    let mut foreign = snapshot.clone();
+    foreign.format_version = DURABLE_FORMAT_VERSION + 1;
+    let other = Arc::new(FeltDb::open(directory.path().join("other.log")).unwrap());
+    assert!(matches!(
+        other.install_snapshot(foreign),
+        Err(FlowError::IncompatibleFormat(_))
+    ));
+
+    // And neither does one serialized before snapshots carried a version.
+    let mut unversioned = snapshot;
+    unversioned.format_version = 0;
+    assert!(matches!(
+        other.install_snapshot(unversioned),
+        Err(FlowError::IncompatibleFormat(_))
+    ));
+}
+
+// ---------------------------------------------------------------------------
+// The server boundary
+// ---------------------------------------------------------------------------
+
+/// An incompatible database cannot reach a running server, so it cannot be
+/// advertised as healthy.
+///
+/// This is the one health interaction in scope: `/health` is not redesigned
+/// here, and does not need to be, because the database never opens. The check
+/// is that the failure is a returned error a caller must handle — not a panic,
+/// and not a degraded-but-running database.
+#[test]
+fn an_incompatible_database_cannot_be_opened_by_a_service() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("legacy.log");
+    legacy_database(&path);
+
+    let outcome = FeltDb::open(&path);
+    assert!(
+        outcome.is_err(),
+        "startup fails closed rather than serving an empty history"
+    );
+    // The error is actionable enough to put in a startup log.
+    let message = outcome.err().unwrap().to_string();
+    assert!(message.contains("INCOMPATIBLE_DURABLE_FORMAT"));
+    assert!(message.contains("format version"));
+}