@feltdb/core 0.13.0 → 0.16.0

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

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