@feltdb/core 0.13.0 → 0.15.0

package/dist/create/create.js

@@ -1259,10 +1259,9 @@ main().catch(console.error);
   # FeltDB Server URL (self-hosted or managed runtime)
   VITE_FELTDB_URL=http://localhost:7700
 
-  # Optional credential for authenticated remote browser access
-  VITE_FELTDB_TOKEN=
-  # Legacy alias accepted by older tooling
-  VITE_FELTDB_API_KEY=
+  # Browser code authenticates users with db.auth.signIn() (end-user sessions).
+  # Never put a FeltDB service key (fdb_live_…) in a VITE_ variable: Vite
+  # inlines every VITE_* value into the browser bundle.
 
   # Managed example: https://runtime.your-app.feltdb.com
   VITE_FELTDB_MANAGED_URL=
@@ -1508,7 +1507,7 @@ npm run feltdb:import
 
 ### Self-Hosted
 - \`VITE_FELTDB_URL\`: Docker container URL (default: http://localhost:7700)
-- \`VITE_FELTDB_API_KEY\`: API token for authentication
+- \`FELTDB_TOKEN\`: API key for server-side code only (never a \`VITE_\` variable; browsers use \`db.auth.signIn()\`)
 - \`FELTDB_IMAGE\`: Docker image to use (optional override)
 - \`DOCKER_NETWORK\`: Custom Docker network (optional)
 
@@ -1701,7 +1700,6 @@ Configuration is in \`feltdb.config.json\`:
 Create a \`.env.local\` file (copy from \`.env.example\`):
 
 \`\`\`
-VITE_FELTDB_API_KEY=your_api_key_here
 VITE_FELTDB_URL=http://localhost:7700
 VITE_FELTDB_MANAGED_URL=https://api.feltdb.com
 VITE_FELTDB_MANAGED_APPLICATION_ID=your_application_id

package/dist/create/package-versions.js

@@ -1,4 +1,4 @@
 // One release train keeps generated applications installable. The repository
 // validation script checks these values against every workspace manifest.
-export const FELTDB_PACKAGE_VERSION = '0.13.0';
+export const FELTDB_PACKAGE_VERSION = '0.15.0';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

package/dist/create/server-source/Cargo.lock

@@ -219,9 +219,9 @@ checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
 
 [[package]]
 name = "chacha20"
-version = "0.10.1"
+version = "0.10.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d524456ba66e72eb8b115ff89e01e497f8e6d11d78b70b1aa13c0fbd97540a81"
+checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06"
 dependencies = [
  "cfg-if",
  "cpufeatures 0.3.0",
@@ -494,7 +494,7 @@ checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
 
 [[package]]
 name = "feltdb"
-version = "0.2.2"
+version = "0.3.0"
 dependencies = [
  "async-stream",
  "async-trait",
@@ -513,7 +513,7 @@ dependencies = [
 
 [[package]]
 name = "feltdb-client"
-version = "0.2.2"
+version = "0.3.0"
 dependencies = [
  "feltdb",
  "reqwest",
@@ -526,7 +526,7 @@ dependencies = [
 
 [[package]]
 name = "feltdb-server"
-version = "0.2.2"
+version = "0.3.0"
 dependencies = [
  "argon2",
  "async-stream",
@@ -552,7 +552,7 @@ dependencies = [
 
 [[package]]
 name = "feltdb-wasm"
-version = "0.2.2"
+version = "0.3.0"
 dependencies = [
  "feltdb",
  "getrandom 0.2.17",

package/dist/create/server-source/Cargo.toml

@@ -14,5 +14,5 @@ exclude = [
 resolver = "2"
 
 [workspace.package]
-version = "0.2.2"
+version = "0.3.0"
 edition = "2021"

package/dist/create/server-source/crates/feltdb/src/lib.rs

@@ -1133,6 +1133,48 @@ impl PreconditionFailure {
     }
 }
 
+impl PreconditionFailure {
+    /// The refusal as every transport serializes it: `predicate`, the
+    /// application's `collection` (never a storage namespace), the record `id`,
+    /// its `key` as `collection:id`, and `expected` / `actual` where the
+    /// predicate has them. A fence names the first fenced collection and
+    /// `key: "read-basis"`, with no `id` and no tokens.
+    ///
+    /// `layout` is where the authority addressed the record: the direct route
+    /// keys rows `collection:id` under `collection`; an application namespace
+    /// keys them by id under `namespace:collection`.
+    pub fn public_json(&self, layout: &ReadLayout) -> Value {
+        let mut value = serde_json::to_value(self).unwrap_or(Value::Null);
+        if matches!(self, Self::Fence { .. }) {
+            return value;
+        }
+        let (collection, id) = match layout {
+            ReadLayout::Direct => {
+                let collection = self.collection().to_string();
+                let id = self
+                    .key()
+                    .strip_prefix(&format!("{collection}:"))
+                    .unwrap_or(self.key())
+                    .to_string();
+                (collection, id)
+            }
+            ReadLayout::Namespace(namespace) => (
+                self.collection()
+                    .strip_prefix(&format!("{namespace}:"))
+                    .unwrap_or(self.collection())
+                    .to_string(),
+                self.key().to_string(),
+            ),
+        };
+        if let Some(object) = value.as_object_mut() {
+            object.insert("key".into(), Value::String(format!("{collection}:{id}")));
+            object.insert("collection".into(), Value::String(collection));
+            object.insert("id".into(), Value::String(id));
+        }
+        value
+    }
+}
+
 impl Display for PreconditionFailure {
     fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
         match self {
@@ -3225,6 +3267,20 @@ impl FeltDb {
             .collect()
     }
 
+    /// The original commit of a transaction id, if it committed, exactly as a
+    /// retry of it through `apply_atomic_transaction_*` would report it: the
+    /// original revisions and positions (`duplicate: true`), or
+    /// `TransactionIdPayloadMismatch` when `payload_hash` differs from the one
+    /// the id was committed with. Read-only.
+    pub fn committed_transaction(
+        &self,
+        transaction_id: &str,
+        payload_hash: Option<&str>,
+    ) -> Result<Option<AtomicCommit>> {
+        let inner = self.state();
+        committed_transaction_locked(&inner, transaction_id, payload_hash).transpose()
+    }
+
     pub fn has_applied_transaction(&self, transaction_id: &str) -> Result<bool> {
         Ok(self
             .inner
@@ -3385,41 +3441,10 @@ impl FeltDb {
     ) -> Result<AtomicCommit> {
         let (commit, events) = {
             let mut inner = self.state();
-            if inner.applied_transactions.contains(transaction_id) {
-                if let Some(expected_hash) = payload_hash {
-                    if inner
-                        .transaction_payload_hashes
-                        .get(transaction_id)
-                        .map(String::as_str)
-                        != Some(expected_hash)
-                    {
-                        return Err(FlowError::TransactionIdPayloadMismatch {
-                            transaction_id: transaction_id.to_string(),
-                        });
-                    }
-                }
-                let (base_revision, commit_revision) = inner
-                    .transaction_revisions
-                    .get(transaction_id)
-                    .copied()
-                    .unwrap_or((inner.authority_revision, inner.authority_revision));
-                let (state_before, state_after) = inner
-                    .transaction_history
-                    .iter()
-                    .find(|attribution| attribution.transaction_id == transaction_id)
-                    .map(|attribution| (attribution.state_before, attribution.state_after))
-                    .unwrap_or((inner.sequence, inner.sequence));
-                return Ok(AtomicCommit {
-                    transaction_id: transaction_id.into(),
-                    base_revision,
-                    commit_revision,
-                    status: TransactionStatus::Committed,
-                    state_before,
-                    state_after,
-                    rows: vec![],
-                    duplicate: true,
-                    payload_binding: payload_hash.map(|_| PayloadBinding::Verified),
-                });
+            if let Some(duplicate) =
+                committed_transaction_locked(&inner, transaction_id, payload_hash)
+            {
+                return duplicate;
             }
             // Record preconditions, evaluated before anything is staged and
             // under the same lock the writes take. A caller reads state,
@@ -4167,6 +4192,21 @@ impl FeltDb {
         self.get::<Value>(key)
     }
 
+    /// One live row of a collection by its key, cloned under the state lock.
+    ///
+    /// A keyed lookup, not a scan: callers that know the canonical key of the
+    /// record they need (Durable Work's projection refresh, for one) use this
+    /// rather than a predicate over the whole collection.
+    pub(crate) fn live_row(&self, capability: &str, key: &str) -> Option<StoredRow> {
+        let inner = self.state();
+        inner
+            .rows
+            .get(capability)
+            .and_then(|rows| rows.get(key))
+            .filter(|row| !row.deleted)
+            .cloned()
+    }
+
     /// List the canonical values in one collection/capability namespace.
     ///
     /// This clones the whole collection, so its cost is linear in collection
@@ -6021,6 +6061,57 @@ fn append_event_with(
     Ok(())
 }
 
+/// The answer to a retried transaction id, read under the commit lock.
+///
+/// `None` when the id has not committed. Otherwise the *original* commit's
+/// revisions and positions, never the store's current ones, or
+/// `TransactionIdPayloadMismatch` when a payload hash is given and differs from
+/// the one the id was committed with. Nothing is evaluated and nothing is
+/// applied: a duplicate is answered before any precondition is read.
+fn committed_transaction_locked(
+    inner: &Inner,
+    transaction_id: &str,
+    payload_hash: Option<&str>,
+) -> Option<Result<AtomicCommit>> {
+    if !inner.applied_transactions.contains(transaction_id) {
+        return None;
+    }
+    if let Some(expected_hash) = payload_hash {
+        if inner
+            .transaction_payload_hashes
+            .get(transaction_id)
+            .map(String::as_str)
+            != Some(expected_hash)
+        {
+            return Some(Err(FlowError::TransactionIdPayloadMismatch {
+                transaction_id: transaction_id.to_string(),
+            }));
+        }
+    }
+    let (base_revision, commit_revision) = inner
+        .transaction_revisions
+        .get(transaction_id)
+        .copied()
+        .unwrap_or((inner.authority_revision, inner.authority_revision));
+    let (state_before, state_after) = inner
+        .transaction_history
+        .iter()
+        .find(|attribution| attribution.transaction_id == transaction_id)
+        .map(|attribution| (attribution.state_before, attribution.state_after))
+        .unwrap_or((inner.sequence, inner.sequence));
+    Some(Ok(AtomicCommit {
+        transaction_id: transaction_id.into(),
+        base_revision,
+        commit_revision,
+        status: TransactionStatus::Committed,
+        state_before,
+        state_after,
+        rows: vec![],
+        duplicate: true,
+        payload_binding: payload_hash.map(|_| PayloadBinding::Verified),
+    }))
+}
+
 fn append_transaction(path: &Path, transaction: &TransactionLogRecord) -> Result<()> {
     // A transaction commit fsyncs. This span therefore includes the fsync, which
     // is the point: it is the durability cost of a commit, measured rather than

package/dist/create/server-source/crates/feltdb/src/state_contract.rs

@@ -1061,6 +1061,13 @@ impl StateFailure {
     }
 }
 
+fn idempotency_conflict() -> StateFailure {
+    StateFailure::new(
+        "IDEMPOTENCY_CONFLICT",
+        "transaction ID was already committed with a different canonical payload",
+    )
+}
+
 fn collection<'a>(
     schema: &'a StateSchema,
     name: &str,
@@ -2478,53 +2485,114 @@ fn execute_transaction_with_policies(
         transaction_id
     );
     let payload_hash = format!("sha256:{:x}", Sha256::digest(&canonical));
-    if db
-        .has_applied_transaction(&storage_transaction_id)
-        .map_err(StateFailure::storage)?
-    {
-        if db
-            .applied_transaction_payload_hash(&storage_transaction_id)
-            .map_err(StateFailure::storage)?
-            .as_deref()
-            != Some(payload_hash.as_str())
-        {
-            return Err(StateFailure::new(
-                "IDEMPOTENCY_CONFLICT",
-                "transaction ID was already committed with a different canonical payload",
-            ));
-        }
-        let state = db.sequence().map_err(StateFailure::storage)?;
-        let cursor = db
-            .operation_versions()
-            .map_err(StateFailure::storage)?
-            .into_iter()
-            .collect();
-        let audit = TransactionAudit {
-            transaction_id: transaction_id.clone(),
-            subject: request.authorization.subject.clone(),
-            tenant: request.tenant_id.clone(),
-            application: request.application_id.clone(),
-            revision: request.revision_id.clone(),
-            schema_version: request.schema_version,
-            state_before: state,
-            state_after: state,
-            operations: request.operations.len(),
-            authorization_decisions: vec!["state:write allowed".into()],
-            causal_parent: request.causal_parent,
-            result: "duplicate".into(),
-        };
-        return Ok(TransactionResult {
-            transaction_id,
-            base_revision: db.current_revision().map_err(StateFailure::storage)?,
-            commit_revision: db.current_revision().map_err(StateFailure::storage)?,
-            status: crate::TransactionStatus::Committed,
-            state_before: state,
-            state_after: state,
-            causal_cursor: cursor,
-            duplicate: true,
-            audit,
-        });
+    // A retried id is answered before anything is evaluated against current
+    // state, with the original commit: its revisions and positions, not the
+    // store's current ones. The same answer the commit lock gives a retry that
+    // races past this check.
+    if let Some(result) = committed_result(
+        db,
+        request,
+        &transaction_id,
+        &storage_transaction_id,
+        &payload_hash,
+    )? {
+        return Ok(result);
     }
+    match commit_new_transaction(
+        db,
+        schema,
+        request,
+        uniform_write_policy,
+        collection_write_policies,
+        &transaction_id,
+        &storage_transaction_id,
+        &payload_hash,
+    ) {
+        Ok(result) => Ok(result),
+        // The request was evaluated against state read before the commit
+        // lock. An identical request that committed in between makes this one
+        // its duplicate, and the duplicate -- the original commit -- is the
+        // answer, not the refusal that later state produced (a create that
+        // now "exists", a fence that now "changed").
+        Err(failure) => match committed_result(
+            db,
+            request,
+            &transaction_id,
+            &storage_transaction_id,
+            &payload_hash,
+        )? {
+            Some(result) => Ok(result),
+            None => Err(failure),
+        },
+    }
+}
+
+/// A retried id, answered with the original commit: its revisions and
+/// positions, never the store's current ones. `IDEMPOTENCY_CONFLICT` when the id
+/// committed with a different payload; `None` when it has not committed.
+fn committed_result(
+    db: &FeltDb,
+    request: &TransactionRequest,
+    transaction_id: &str,
+    storage_transaction_id: &str,
+    payload_hash: &str,
+) -> Result<Option<TransactionResult>, StateFailure> {
+    let Some(original) = db
+        .committed_transaction(storage_transaction_id, Some(payload_hash))
+        .map_err(|error| match error {
+            crate::FlowError::TransactionIdPayloadMismatch { .. } => idempotency_conflict(),
+            other => StateFailure::storage(other),
+        })?
+    else {
+        return Ok(None);
+    };
+    let cursor = db
+        .operation_versions()
+        .map_err(StateFailure::storage)?
+        .into_iter()
+        .collect();
+    let audit = TransactionAudit {
+        transaction_id: transaction_id.to_string(),
+        subject: request.authorization.subject.clone(),
+        tenant: request.tenant_id.clone(),
+        application: request.application_id.clone(),
+        revision: request.revision_id.clone(),
+        schema_version: request.schema_version,
+        state_before: original.state_before,
+        state_after: original.state_after,
+        operations: request.operations.len(),
+        authorization_decisions: vec!["state:write allowed".into()],
+        causal_parent: request.causal_parent,
+        result: "duplicate".into(),
+    };
+    Ok(Some(TransactionResult {
+        transaction_id: transaction_id.to_string(),
+        base_revision: original.base_revision,
+        commit_revision: original.commit_revision,
+        status: original.status,
+        state_before: original.state_before,
+        state_after: original.state_after,
+        causal_cursor: cursor,
+        duplicate: true,
+        audit,
+    }))
+}
+
+/// Evaluate and commit a transaction id that has not committed.
+#[allow(clippy::too_many_arguments)]
+fn commit_new_transaction(
+    db: &FeltDb,
+    schema: &StateSchema,
+    request: &TransactionRequest,
+    uniform_write_policy: Option<&PolicySubject>,
+    collection_write_policies: Option<&BTreeMap<String, PolicySubject>>,
+    transaction_id: &str,
+    storage_transaction_id: &str,
+    payload_hash: &str,
+) -> Result<TransactionResult, StateFailure> {
+    let transaction_id = transaction_id.to_string();
+    let storage_transaction_id = storage_transaction_id.to_string();
+    let payload_hash = payload_hash.to_string();
     let namespace = request
         .state_namespace
         .as_deref()
@@ -2753,7 +2821,19 @@ fn execute_transaction_with_policies(
         let value = match operation.kind {
             TransactionOperationKind::Insert => {
                 if existing_value.is_some() {
-                    return Err(StateFailure::new("CONFLICT", "record already exists"));
+                    // A create is conditional on absence: the same structured
+                    // refusal a `requireAbsent` create gets on every route.
+                    let refusal = crate::PreconditionFailure::Present {
+                        collection: capability.clone(),
+                        key: key.clone(),
+                    };
+                    let mut failure =
+                        StateFailure::new("PRECONDITION_FAILED", &refusal.to_string());
+                    failure.transaction = Some(transaction_id.clone());
+                    failure.resource = Some(format!("{}:{}", operation.collection, key));
+                    failure.failure =
+                        Some(refusal.public_json(&crate::ReadLayout::Namespace(namespace.clone())));
+                    return Err(failure);
                 }
                 let mut value = operation.value.clone();
                 match definition {
@@ -2924,12 +3004,18 @@ fn execute_transaction_with_policies(
             // "this deployment is broken", so it is carried through as
             // structure rather than flattened into the message.
             if let FlowError::PreconditionFailed(refusal) = &error {
+                let layout = crate::ReadLayout::Namespace(namespace.clone());
+                let public = refusal.public_json(&layout);
                 let mut failure =
                     StateFailure::new("PRECONDITION_FAILED", &error.to_string());
                 failure.transaction = Some(transaction_id.clone());
                 failure.causal_position = db.sequence().ok();
-                failure.resource = Some(refusal.key().to_string());
-                failure.failure = serde_json::to_value(refusal.as_ref()).ok();
+                failure.resource = public
+                    .get("key")
+                    .and_then(Value::as_str)
+                    .map(str::to_owned)
+                    .or_else(|| Some(refusal.key().to_string()));
+                failure.failure = Some(public);
                 if let PreconditionFailure::Version {
                     expected, actual, ..
                 } = refusal.as_ref()
@@ -2949,6 +3035,21 @@ fn execute_transaction_with_policies(
                 failure.actual = Some(Value::from(*actual));
                 return failure;
             }
+            if let FlowError::TransactionIdPayloadMismatch { .. } = &error {
+                // Two different payloads raced past the check above under one
+                // id; the commit lock admitted the first. Same refusal.
+                let mut failure = idempotency_conflict();
+                failure.transaction = Some(transaction_id.clone());
+                return failure;
+            }
+            if let FlowError::Io(_) | FlowError::Serde(_) = &error {
+                // The commit could not be made durable. Never a lost race and
+                // never a success: the outcome must be treated as unknown and
+                // reconciled by retrying with the same transaction id.
+                let mut failure = StateFailure::new("DURABILITY_FAILURE", &error.to_string());
+                failure.transaction = Some(transaction_id.clone());
+                return failure;
+            }
             let text = error.to_string();
             if text.contains("INVALID_READ_SET:") {
                 // A malformed or foreign basis is a caller error, never a lost race.
@@ -3262,11 +3363,19 @@ mod tests {
         let mut stale = request;
         stale.transaction_id = Some("stale".into());
         stale.causal_parent = Some(0);
+        // A create of a record that exists is refused as a structured presence
+        // precondition, as a `requireAbsent` create is on every other route.
+        let refused = execute_transaction(&db, &schema, &stale, None).unwrap_err();
+        assert_eq!(refused.code, "PRECONDITION_FAILED");
+        let failure = refused.failure.expect("structured failure");
+        assert_eq!(failure["predicate"], "present");
+        assert_eq!(failure["collection"], "incidents");
+        assert_eq!(failure["id"], "one");
+        assert_eq!(failure["key"], "incidents:one");
         assert_eq!(
-            execute_transaction(&db, &schema, &stale, None)
-                .unwrap_err()
-                .code,
-            "CONFLICT"
+            db.export_snapshot().unwrap().rows.len(),
+            2,
+            "nothing written"
         );
     }
     /// A conditional write through the canonical contract has to mean the same