@feltdb/core 0.12.0 → 0.12.2

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

@@ -0,0 +1,683 @@
+//! The Rust client (`feltdb-client`) against this crate's real server binary: every request goes
+//! over HTTP to a spawned `feltdb-server`, so these tests hold the client and the server to one
+//! wire contract.
+
+use std::{
+    io::{BufRead, BufReader},
+    path::PathBuf,
+    process::{Child, Command, Stdio},
+    time::{Duration, SystemTime, UNIX_EPOCH},
+};
+
+use feltdb_client::{
+    path_segment,
+    wire::{CanonicalQuery, QueryFilter},
+    AppTransaction, BoundedQuery, CasConflict, CasOutcome, CasRequest, Client, Direction, Error,
+    Method, Operation, Precondition, PreconditionFailure, ReadRecord, ReadSet, Transaction,
+};
+use serde_json::{json, Map, Value};
+
+const MASTER_KEY: &str = "rust-client-development-key";
+
+struct Server {
+    child: Child,
+    url: String,
+    directory: PathBuf,
+}
+
+impl Server {
+    fn start(name: &str, extra: &[&str]) -> Self {
+        Self::start_in(directory(name), extra)
+    }
+
+    /// A server requiring authentication, and a key it accepts. The key file is read at startup,
+    /// so the key is issued first.
+    fn start_authenticated(name: &str) -> (Self, String) {
+        let directory = directory(name);
+        let key = issue_key(&directory);
+        (Self::start_in(directory, &["--auth"]), key)
+    }
+
+    fn start_in(directory: PathBuf, extra: &[&str]) -> Self {
+        let data = directory.join("feltdb.log");
+        let mut child = Command::new(env!("CARGO_BIN_EXE_feltdb-server"))
+            .args([
+                "--host",
+                "127.0.0.1",
+                "--port",
+                "0",
+                "--namespace",
+                "rust-client",
+                "--data",
+                data.to_str().unwrap(),
+                "--keys",
+                directory.join("keys.json").to_str().unwrap(),
+                "--audit",
+                directory.join("audit.log").to_str().unwrap(),
+            ])
+            .args(extra)
+            .env("FELTDB_MASTER_KEY", MASTER_KEY)
+            .env(
+                "FELTDB_SESSION_SECRET",
+                "rust-client-session-secret-of-at-least-32-bytes",
+            )
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null())
+            .spawn()
+            .unwrap();
+        let stdout = child.stdout.take().unwrap();
+        let mut lines = BufReader::new(stdout).lines();
+        let url = loop {
+            let line = lines
+                .next()
+                .expect("server exited before readiness")
+                .unwrap();
+            if let Some(rest) = line.split("ready at ").nth(1) {
+                break rest.split_whitespace().next().unwrap().to_owned();
+            }
+        };
+        // Keep draining stdout so the server never blocks on a full pipe.
+        std::thread::spawn(move || lines.for_each(drop));
+        Self {
+            child,
+            url,
+            directory,
+        }
+    }
+
+    fn client(&self) -> Client {
+        Client::builder(&self.url).build().unwrap()
+    }
+}
+
+fn directory(name: &str) -> PathBuf {
+    let directory = std::env::temp_dir().join(format!(
+        "feltdb-rust-client-{name}-{}-{}",
+        std::process::id(),
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos()
+    ));
+    std::fs::create_dir_all(&directory).unwrap();
+    directory
+}
+
+fn issue_key(directory: &std::path::Path) -> String {
+    let output = Command::new(env!("CARGO_BIN_EXE_feltdb-server"))
+        .args([
+            "keys",
+            "create",
+            "--keys",
+            directory.join("keys.json").to_str().unwrap(),
+            "--name",
+            "rust-client",
+            "--namespace",
+            "rust-client",
+            "--scope",
+            "*",
+        ])
+        .env("FELTDB_MASTER_KEY", MASTER_KEY)
+        .output()
+        .unwrap();
+    assert!(output.status.success());
+    String::from_utf8(output.stdout)
+        .unwrap()
+        .trim()
+        .lines()
+        .last()
+        .unwrap()
+        .to_owned()
+}
+
+impl Drop for Server {
+    fn drop(&mut self) {
+        let _ = self.child.kill();
+        let _ = self.child.wait();
+        let _ = std::fs::remove_dir_all(&self.directory);
+    }
+}
+
+fn object(value: Value) -> Map<String, Value> {
+    value.as_object().unwrap().clone()
+}
+
+#[tokio::test]
+async fn records_transactions_and_conflicts_over_the_direct_authority() {
+    let server = Server::start("direct", &[]);
+    let client = server.client();
+
+    // Records.
+    let created = client
+        .create("orders", Some("o-1"), json!({ "status": "pending" }))
+        .await
+        .unwrap();
+    assert_eq!(created.key, "orders:o-1");
+    let again = client
+        .create("orders", Some("o-1"), json!({}))
+        .await
+        .unwrap_err();
+    assert_eq!(again.status(), Some(409));
+    let updated = client
+        .update("orders", "o-1", object(json!({ "total": 5 })))
+        .await
+        .unwrap();
+    assert_eq!(updated.value["status"], "pending");
+    assert_eq!(updated.value["total"], 5);
+    assert_eq!(
+        client.get("orders", "o-1").await.unwrap().unwrap().value["total"],
+        5
+    );
+    assert_eq!(client.get("orders", "missing").await.unwrap(), None);
+    assert_eq!(client.list("orders").await.unwrap().len(), 1);
+
+    // An atomic, idempotent transaction.
+    let ship = Transaction::new("ship-o-2")
+        .operation(Operation::create(
+            "orders",
+            "o-2",
+            json!({ "status": "shipped" }),
+        ))
+        .operation(Operation::create("audit", "a-1", json!({ "order": "o-2" })));
+    let first = client.commit(&ship).await.unwrap();
+    assert!(!first.duplicate);
+    assert_eq!(first.operations, 2);
+    let retry = client.commit(&ship).await.unwrap();
+    assert!(retry.duplicate, "a resubmitted transaction is recognized");
+    assert_eq!(retry.commit_revision, first.commit_revision);
+
+    // The same id with different content is refused, typed.
+    let reused = Transaction::new("ship-o-2").operation(Operation::put(
+        "orders",
+        "o-2",
+        json!({ "status": "lost" }),
+    ));
+    let refused = client.commit(&reused).await.unwrap_err();
+    assert_eq!(refused.code(), Some("IDEMPOTENCY_CONFLICT"));
+
+    // A lost creation race is a structured precondition failure; nothing is written.
+    let race = Transaction::generated()
+        .operation(Operation::create("orders", "o-2", json!({})))
+        .operation(Operation::put("orders", "o-3", json!({})));
+    let lost = client.commit(&race).await.unwrap_err();
+    assert!(lost.is_conflict());
+    assert!(matches!(
+        lost.precondition_failure(),
+        Some(PreconditionFailure::Present { key, .. }) if key == "orders:o-2"
+    ));
+    assert_eq!(client.get("orders", "o-3").await.unwrap(), None);
+
+    // A version fence on a staged write; o-2 was created at version 1.
+    let stale = Transaction::generated()
+        .operation(Operation::put("orders", "o-2", json!({ "status": "x" })).expect_version(7));
+    assert!(matches!(
+        client
+            .commit(&stale)
+            .await
+            .unwrap_err()
+            .precondition_failure(),
+        Some(PreconditionFailure::Version {
+            expected: 7,
+            actual: 1,
+            ..
+        })
+    ));
+    let fresh = Transaction::generated()
+        .operation(
+            Operation::put("orders", "o-2", json!({ "status": "delivered" })).expect_version(1),
+        )
+        .precondition(Precondition::absent("locks", "o-2"));
+    client.commit(&fresh).await.unwrap();
+
+    // Compare-and-set: a lost race is a value.
+    match client
+        .compare_and_set(
+            "orders",
+            "o-2",
+            &CasRequest::new(1, json!({ "status": "late" })),
+        )
+        .await
+        .unwrap()
+    {
+        CasOutcome::Conflict {
+            conflict: CasConflict::Version,
+            current_version,
+            ..
+        } => assert_eq!(current_version, 2),
+        other => panic!("expected a version conflict, got {other:?}"),
+    }
+    assert!(matches!(
+        client
+            .compare_and_set(
+                "orders",
+                "o-2",
+                &CasRequest::new(2, json!({ "status": "returned" }))
+            )
+            .await
+            .unwrap(),
+        CasOutcome::Updated {
+            current_version: 3,
+            ..
+        }
+    ));
+    assert_eq!(
+        client
+            .compare_and_set("orders", "nope", &CasRequest::new(1, json!({})))
+            .await
+            .unwrap(),
+        CasOutcome::NotFound
+    );
+
+    // A read basis fences a transaction on state it did not write.
+    let reads = ReadSet {
+        records: vec![ReadRecord {
+            collection: "orders".into(),
+            id: "o-1".into(),
+        }],
+        predicates: vec![],
+    };
+    let basis = client.read_basis(&reads).await.unwrap();
+    client
+        .update("orders", "o-1", object(json!({ "total": 6 })))
+        .await
+        .unwrap();
+    let fenced = Transaction::generated()
+        .operation(Operation::put("audit", "a-2", json!({})))
+        .fence(basis);
+    assert!(matches!(
+        client
+            .commit(&fenced)
+            .await
+            .unwrap_err()
+            .precondition_failure(),
+        Some(PreconditionFailure::Fence { .. })
+    ));
+
+    client.delete("audit", "a-1").await.unwrap();
+    assert_eq!(
+        client.delete("audit", "a-1").await.unwrap_err().status(),
+        Some(404)
+    );
+    assert!(client.revision().await.unwrap().revision > 0);
+}
+
+#[tokio::test]
+async fn the_bounded_query_pages_in_a_total_order() {
+    let server = Server::start("query", &[]);
+    let client = server.client();
+    let mut transaction = Transaction::new("seed");
+    for index in 0..5 {
+        transaction = transaction.operation(Operation::put(
+            "items",
+            format!("i-{index}"),
+            json!({ "n": index, "kind": if index % 2 == 0 { "even" } else { "odd" } }),
+        ));
+    }
+    client.commit(&transaction).await.unwrap();
+
+    let mut seen = Vec::new();
+    let mut query = BoundedQuery::new("items", 2).order_by("n", Direction::Asc);
+    loop {
+        let page = client.query(&query).await.unwrap();
+        assert!(page.records.len() <= 2);
+        seen.extend(
+            page.records
+                .iter()
+                .map(|record| record["n"].as_i64().unwrap()),
+        );
+        match page.next_cursor {
+            Some(cursor) if !page.exhausted => query = query.after(cursor),
+            _ => break,
+        }
+    }
+    assert_eq!(seen, vec![0, 1, 2, 3, 4]);
+
+    let even = client
+        .query(
+            &BoundedQuery::new("items", 10)
+                .eq("kind", json!("even"))
+                .order_by("n", Direction::Desc),
+        )
+        .await
+        .unwrap();
+    let values: Vec<_> = even
+        .records
+        .iter()
+        .map(|record| record["n"].clone())
+        .collect();
+    assert_eq!(values, vec![json!(4), json!(2), json!(0)]);
+
+    let invalid = client
+        .query(&BoundedQuery::new("items", 10))
+        .await
+        .unwrap_err();
+    assert_eq!(invalid.code(), Some("INVALID_QUERY"));
+}
+
+#[tokio::test]
+async fn the_event_stream_delivers_committed_changes() {
+    let server = Server::start("events", &[]);
+    let client = server.client();
+    let mut events = client.events(None).await.unwrap();
+    client
+        .commit(&Transaction::new("evt").operation(Operation::put("things", "t-1", json!({}))))
+        .await
+        .unwrap();
+    let event = tokio::time::timeout(Duration::from_secs(10), events.next())
+        .await
+        .expect("an event within ten seconds")
+        .expect("the stream is open")
+        .unwrap();
+    assert_eq!(event.event, "state.committed");
+    assert!(event.json::<Value>().unwrap().is_object());
+    assert!(events.last_event_id().is_some());
+}
+
+#[tokio::test]
+async fn an_authenticated_server_refuses_without_a_key_and_serves_with_one() {
+    let (server, key) = Server::start_authenticated("auth");
+    let anonymous = server.client().revision().await.unwrap_err();
+    assert_eq!(anonymous.status(), Some(401));
+    assert!(matches!(anonymous, Error::Api(_)));
+
+    let client = Client::builder(&server.url).token(key).build().unwrap();
+    client
+        .commit(&Transaction::new("authed").operation(Operation::put(
+            "notes",
+            "n-1",
+            json!({ "a": 1 }),
+        )))
+        .await
+        .unwrap();
+    assert!(client.get("notes", "n-1").await.unwrap().is_some());
+}
+
+#[tokio::test]
+async fn the_canonical_application_api() {
+    let server = Server::start("application", &[]);
+    let client = server.client();
+
+    // Provision an application with one collection, through routes this client does not name.
+    let tenant = client
+        .request(
+            Method::POST,
+            "/api/tenants",
+            Some(&json!({ "name": "Rust client" })),
+        )
+        .await
+        .unwrap();
+    let tenant_id = tenant["tenant_id"]
+        .as_str()
+        .or(tenant["id"].as_str())
+        .unwrap();
+    let application = client
+        .request(
+            Method::POST,
+            &format!("/api/tenants/{tenant_id}/applications"),
+            Some(&json!({ "name": "Orders" })),
+        )
+        .await
+        .unwrap();
+    let application_id = application["application_id"]
+        .as_str()
+        .or(application["id"].as_str())
+        .unwrap()
+        .to_owned();
+    let drafts = format!("/api/applications/{application_id}/drafts");
+    let draft = client
+        .request(Method::POST, &drafts, Some(&json!({})))
+        .await
+        .unwrap();
+    let draft_id = draft["draft_id"].as_str().unwrap();
+    let mut manifest = draft["manifest"].clone();
+    manifest["collections"] = json!([{ "name": "Order", "fields": [
+        { "name": "status", "type": "text", "required": true },
+        { "name": "total", "type": "integer", "required": false }
+    ] }]);
+    manifest["policies"] = json!([{ "name": "Order", "resource": "Order",
+        "read": "authenticated", "write": "authenticated", "capabilities": [] }]);
+    let version = draft["version"].as_u64().unwrap().to_string();
+    client
+        .request_with_headers(
+            Method::PUT,
+            &format!("{drafts}/{draft_id}"),
+            &[("if-version", &version)],
+            Some(&json!({ "manifest": manifest })),
+        )
+        .await
+        .unwrap();
+    let revision = client
+        .request(
+            Method::POST,
+            &format!("{drafts}/{draft_id}/commit"),
+            Some(&json!({})),
+        )
+        .await
+        .unwrap();
+    let revision_id = revision["revision_id"].as_str().unwrap();
+    let encoded = path_segment(revision_id);
+    client
+        .request(
+            Method::POST,
+            &format!("/api/applications/{application_id}/revisions/{encoded}/promote"),
+            Some(&json!({ "environment": "production", "reason": "rust client test" })),
+        )
+        .await
+        .unwrap();
+
+    let app = client.application(&application_id);
+    let info = app.discover().await.unwrap();
+    assert_eq!(info.revision_id, revision_id);
+    assert_eq!(info.application_name.as_deref(), Some("Orders"));
+
+    let commit = app
+        .commit(
+            &AppTransaction::new("order-1")
+                .insert("Order", "o-1", json!({ "status": "open", "total": 3 }))
+                .insert("Order", "o-2", json!({ "status": "closed", "total": 9 })),
+        )
+        .await
+        .unwrap();
+    assert!(!commit.result.duplicate);
+    assert!(commit.revision_id.starts_with("revision-"));
+
+    let query: CanonicalQuery =
+        serde_json::from_value(json!({ "collection": "Order", "limit": 10 })).unwrap();
+    let open = CanonicalQuery {
+        filter: Some(QueryFilter::Eq {
+            field: "status".into(),
+            value: json!("open"),
+        }),
+        ..query
+    };
+    let result = app.query(&open).await.unwrap();
+    assert_eq!(result.records.len(), 1);
+    assert_eq!(result.records[0]["total"], 3);
+
+    // An invalid document is refused by the contract, with a code.
+    let invalid = app
+        .commit(&AppTransaction::generated().insert("Order", "o-3", json!({ "total": 1 })))
+        .await
+        .unwrap_err();
+    assert!(invalid.code().is_some(), "{invalid}");
+
+    // A read basis over application state fences a canonical transaction.
+    let basis = app
+        .read_basis(&ReadSet {
+            records: vec![ReadRecord {
+                collection: "Order".into(),
+                id: "o-1".into(),
+            }],
+            predicates: vec![],
+        })
+        .await
+        .unwrap();
+    app.commit(
+        &AppTransaction::generated()
+            .update("Order", "o-2", json!({ "status": "closed", "total": 10 }))
+            .fence(basis.clone()),
+    )
+    .await
+    .unwrap();
+    app.commit(&AppTransaction::generated().update(
+        "Order",
+        "o-1",
+        json!({ "status": "open", "total": 4 }),
+    ))
+    .await
+    .unwrap();
+    let stale = app
+        .commit(
+            &AppTransaction::generated()
+                .update("Order", "o-2", json!({ "status": "closed", "total": 11 }))
+                .fence(basis),
+        )
+        .await
+        .unwrap_err();
+    assert!(stale.is_conflict(), "{stale}");
+
+    let replay = app.replay(None, Some(10)).await.unwrap();
+    assert_eq!(replay.application_id, application_id);
+    assert!(!replay.next_cursor.is_empty());
+}
+
+#[tokio::test]
+async fn the_control_plane_and_versioned_canonical_writes() {
+    let server = Server::start("control", &[]);
+    let client = server.client();
+
+    let health = client.health().await.unwrap();
+    assert_eq!(health.version, env!("CARGO_PKG_VERSION"));
+
+    // Provision through the typed control plane: tenant, application, draft, commit, promote.
+    let control = client.control();
+    let tenant = control.create_tenant("Control").await.unwrap();
+    assert!(control
+        .tenants()
+        .await
+        .unwrap()
+        .iter()
+        .any(|listed| listed.id == tenant.id));
+    let created = control
+        .create_application(&tenant.id, "Inventory")
+        .await
+        .unwrap();
+    let listed = control.applications(&tenant.id).await.unwrap();
+    assert!(listed
+        .iter()
+        .any(|application| application.id == created.id));
+    assert_eq!(
+        control.application(&created.id).await.unwrap().name,
+        "Inventory"
+    );
+
+    let draft = control.create_draft(&created.id, None).await.unwrap();
+    let mut manifest = serde_json::to_value(&draft.manifest).unwrap();
+    manifest["collections"] = json!([{ "name": "Item", "fields": [
+        { "name": "count", "type": "integer", "required": true }
+    ] }]);
+    manifest["policies"] = json!([{ "name": "Item", "resource": "Item",
+        "read": "authenticated", "write": "authenticated", "capabilities": [] }]);
+    let manifest = serde_json::from_value(manifest).unwrap();
+    let updated = control
+        .update_draft(&created.id, &draft.draft_id, draft.version, &manifest)
+        .await
+        .unwrap();
+    // A write at a version already superseded is refused, not applied.
+    let stale = control
+        .update_draft(&created.id, &draft.draft_id, draft.version, &manifest)
+        .await
+        .unwrap_err();
+    assert!(stale.status().is_some(), "{stale}");
+    assert_eq!(
+        control
+            .draft(&created.id, &draft.draft_id)
+            .await
+            .unwrap()
+            .version,
+        updated.version
+    );
+    assert!(
+        control
+            .validate_draft(&created.id, &draft.draft_id)
+            .await
+            .unwrap()
+            .valid
+    );
+    let revision = control
+        .commit_draft(&created.id, &draft.draft_id)
+        .await
+        .unwrap();
+    control
+        .promote(
+            &created.id,
+            &revision.revision_id,
+            &feltdb_client::Promotion::new("production")
+                .reason("rust client test")
+                .expect_current(None),
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        control
+            .revision(&created.id, &revision.revision_id)
+            .await
+            .unwrap()
+            .manifest
+            .collections
+            .len(),
+        1
+    );
+    // An online backup is written on the server's host and described by its manifest.
+    let bundle = server.directory.join("backup");
+    let manifest = control.backup(bundle.to_str().unwrap()).await.unwrap();
+    assert!(manifest["entries"].as_array().is_some(), "{manifest}");
+    assert!(bundle.exists());
+
+    // Per-operation versions: an update or delete at a stale version refuses the transaction.
+    let app = client.application(&created.id);
+    assert_eq!(
+        app.discover().await.unwrap().revision_id,
+        revision.revision_id
+    );
+    let before = app.state_version().await.unwrap();
+    assert_eq!(before.revision_id, revision.revision_id);
+    app.commit(&AppTransaction::generated().insert("Item", "i-1", json!({ "count": 1 })))
+        .await
+        .unwrap();
+    let after = app.state_version().await.unwrap();
+    assert!(after.state_version > before.state_version);
+
+    app.commit(&AppTransaction::generated().update_if_version(
+        "Item",
+        "i-1",
+        json!({ "count": 2 }),
+        1,
+    ))
+    .await
+    .unwrap();
+    let stale = app
+        .commit(&AppTransaction::generated().update_if_version(
+            "Item",
+            "i-1",
+            json!({ "count": 3 }),
+            1,
+        ))
+        .await
+        .unwrap_err();
+    assert!(stale.is_conflict(), "{stale}");
+    assert_eq!(stale.code(), Some("PRECONDITION_FAILED"), "{stale}");
+    // A fenced delete and an insert of the same id: an atomic replace.
+    app.commit(
+        &AppTransaction::generated()
+            .delete_if_version("Item", "i-1", 2)
+            .insert("Item", "i-1", json!({ "count": 9 })),
+    )
+    .await
+    .unwrap();
+    let stale = app
+        .commit(&AppTransaction::generated().delete_if_version("Item", "i-1", 2))
+        .await
+        .unwrap_err();
+    assert!(stale.is_conflict(), "{stale}");
+}

package/dist/create/server-source/crates/feltdb-wasm/Cargo.toml

@@ -2,12 +2,14 @@
 name = "feltdb-wasm"
 version.workspace = true
 edition.workspace = true
+# An application (server) / shipped to npm as @feltdb/wasm, not a library for crates.io.
+publish = false
 
 [lib]
 crate-type = ["cdylib"]
 
 [dependencies]
-feltdb = { path = "../feltdb" }
+feltdb = { path = "../feltdb", features = ["unstable-internals"] }
 wasm-bindgen = "0.2"
 wasm-bindgen-futures = "0.4"
 serde = { version = "1", features = ["derive"] }