create-feltdb 0.6.8 → 0.6.10

package/dist/server-source/crates/feltdb-server/src/main.rs

@@ -41,6 +41,7 @@ use feltdb::{
         Grant, GrantSigner, GrantStore, Subject as GrantSubject,
     },
     cardinality_endpoint::{CardinalityContext, CardinalityDiagnosticResponse},
+    AtomicMutation, AtomicPrecondition,
     policy_evaluation::{Actor, PolicyContext, PolicyEvaluator, PolicySubject},
     state_contract::{
         begin_read, compare_schemas, execute_query as execute_state_query, execute_transaction,
@@ -6298,6 +6299,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             "/api/connections/{connection_id}",
             axum::routing::delete(delete_connection_control),
         )
+        .route("/transactions", axum::routing::post(commit_transaction))
+        .route("/revision", get(get_revision))
         .route(
             "/collections/{collection}",
             get(list_records).post(create_record),
@@ -8974,6 +8977,30 @@ fn put_canonical(
     }))
 }
 
+/// The authority's current committed-state revision.
+///
+/// This is the value `apply_atomic_transaction` advances and writes into each
+/// durable transaction record as `state_after`. It already survived restart and
+/// already refused to move backwards; the only thing missing was a way to read
+/// it without performing a write, which is what a cache needs.
+///
+/// `scope` is the store's instance id. A revision is comparable only against
+/// another revision carrying the same scope, so a client that fails over to a
+/// different replica sees a scope change rather than a silently wrong
+/// comparison against a counter that means something else there.
+#[derive(Serialize)]
+struct RevisionResponse {
+    revision: u64,
+    scope: String,
+}
+
+async fn get_revision(State(state): State<AppState>) -> Result<Json<RevisionResponse>, ApiError> {
+    Ok(Json(RevisionResponse {
+        revision: state.db.sequence()?,
+        scope: state.db.instance_id()?,
+    }))
+}
+
 async fn list_records(
     State(state): State<AppState>,
     Path(collection): Path<String>,
@@ -9000,6 +9027,120 @@ async fn get_record(
     }))
 }
 
+/// One operation inside an application transaction.
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct AtomicTxOperationRequest {
+    collection: String,
+    id: String,
+    /// Absent value means delete.
+    #[serde(default)]
+    value: Option<Map<String, Value>>,
+    /// When set, the record must not already exist for the transaction to commit.
+    #[serde(default)]
+    require_absent: bool,
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct AtomicTxRequest {
+    /// Caller-supplied identity. Reusing one makes the commit idempotent.
+    transaction_id: String,
+    operations: Vec<AtomicTxOperationRequest>,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct AtomicTxResponse {
+    transaction_id: String,
+    /// True when this id had already been committed; nothing was reapplied.
+    duplicate: bool,
+    operations: usize,
+    state_before: u64,
+    state_after: u64,
+}
+
+/// Commit several operations as one atomic, durable transaction.
+///
+/// This is the application-facing entry point to the same atomic commit path
+/// the substrate uses: preconditions are evaluated first, then one transaction
+/// record is written and fsynced, and only then is derived state updated.
+/// There is no second transaction mechanism — the request is translated into
+/// the store's own atomic transaction and nothing else.
+async fn commit_transaction(
+    State(state): State<AppState>,
+    Json(request): Json<AtomicTxRequest>,
+) -> Result<(StatusCode, Json<AtomicTxResponse>), ApiError> {
+    if request.transaction_id.trim().is_empty() {
+        return Err(ApiError(
+            StatusCode::BAD_REQUEST,
+            "transactionId is required".to_string(),
+        ));
+    }
+    if request.operations.is_empty() {
+        return Err(ApiError(
+            StatusCode::BAD_REQUEST,
+            "a transaction requires at least one operation".to_string(),
+        ));
+    }
+
+    // Validate every operation before any of them is turned into a mutation, so
+    // a malformed request cannot commit a prefix of the transaction.
+    let mut mutations = Vec::with_capacity(request.operations.len());
+    let mut preconditions = Vec::new();
+    let mut seen = std::collections::HashSet::new();
+    for operation in request.operations {
+        let key = record_key(&operation.collection, &operation.id)?;
+        if !seen.insert(key.clone()) {
+            return Err(ApiError(
+                StatusCode::BAD_REQUEST,
+                format!("transaction writes {key} more than once"),
+            ));
+        }
+        if operation.require_absent {
+            // The store reads a precondition with no expected version as
+            // "this record must not exist", and evaluates it inside the same
+            // lock as the commit, so there is no window between the check and
+            // the write.
+            preconditions.push(AtomicPrecondition {
+                capability: operation.collection.clone(),
+                key: key.clone(),
+                expected_version: None,
+            });
+        }
+        let value = operation.value.map(|mut fields| {
+            fields.insert("id".to_string(), Value::String(operation.id.clone()));
+            Value::Object(fields)
+        });
+        mutations.push(AtomicMutation {
+            capability: operation.collection,
+            key,
+            value,
+        });
+    }
+
+    let operations = mutations.len();
+    let commit = state
+        .db
+        .apply_atomic_transaction(&request.transaction_id, None, &preconditions, &mutations, None)
+        .map_err(|error| {
+            // A refused transaction applied nothing, so this is a conflict, not
+            // a partially completed request.
+            ApiError(StatusCode::CONFLICT, error.to_string())
+        })?;
+
+    Ok((
+        if commit.duplicate { StatusCode::OK } else { StatusCode::CREATED },
+        Json(AtomicTxResponse {
+            transaction_id: commit.transaction_id,
+            duplicate: commit.duplicate,
+            operations,
+            state_before: commit.state_before,
+            state_after: commit.state_after,
+        }),
+    ))
+}
+
 async fn create_record(
     State(state): State<AppState>,
     Path(collection): Path<String>,

package/package.json

@@ -2,7 +2,7 @@
   "name": "create-feltdb",
   "private": false,
   "description": "Create a new FeltDB application with one command",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "license": "MIT",
   "bin": {
     "create-feltdb": "bin/create-feltdb.js"

package/dist/server-source/crates/feltdb/src/phase_1c_three_node.rs

@@ -1,523 +0,0 @@
-/// Phase 1c: Three-Node TCP Scaling
-///
-/// Validates that FeltDB replication converges correctly with 3 nodes over real TCP.
-///
-/// Success Criteria:
-/// - 3-node cluster established over TCP (1 leader + 2 followers)
-/// - 1000 operations replicated to all 3 nodes
-/// - All 3 nodes converge to identical state_hash
-/// - Replication latency <1s (p99) on LAN
-/// - Zero message loss or corruption
-/// - Test passes 10 consecutive runs
-/// - No deadlocks or stalls
-
-#[cfg(test)]
-mod tests {
-    use crate::convergence::VectorClock;
-    use crate::distributed_transactions::{
-        DistributedTransactionExecutor, ReplicationMessage, TransactionEnvelope,
-    };
-    use crate::in_process_transport::InProcessTransport;
-    use crate::replication_protocol::ProtocolTransport;
-    use crate::state_hash::StateHash;
-    use crate::tcp_transport::TcpTransport;
-    use crate::transactions::{ConsistencyContract, Operation, OperationCommand, OperationId, StateVersion};
-    use serde_json::json;
-    use std::collections::HashMap;
-    use std::sync::Arc;
-    use std::time::{Duration, Instant};
-    use tokio::sync::Mutex;
-    use tokio::task::{self, JoinSet};
-
-    /// Test node that combines FeltDb state with TCP transport
-    struct TestNode {
-        node_id: String,
-        port: u16,
-        executor: Arc<Mutex<DistributedTransactionExecutor>>,
-        transport: Arc<Mutex<TcpTransport>>,
-        sequence: Arc<Mutex<u64>>,
-    }
-
-    impl TestNode {
-        fn new(node_id: String, port: u16) -> Self {
-            let initial_hash = StateHash::from_hex("0".repeat(64));
-            let executor = DistributedTransactionExecutor::new(node_id.clone(), initial_hash);
-
-            let addr = format!("127.0.0.1:{}", port);
-            let transport = TcpTransport::new(addr);
-
-            Self {
-                node_id,
-                port,
-                executor: Arc::new(Mutex::new(executor)),
-                transport: Arc::new(Mutex::new(transport)),
-                sequence: Arc::new(Mutex::new(0)),
-            }
-        }
-
-        /// Get the bind address for this node
-        fn addr(&self) -> String {
-            format!("127.0.0.1:{}", self.port)
-        }
-
-        /// Get current state hash
-        async fn state_hash(&self) -> StateHash {
-            let executor = self.executor.lock().await;
-            executor
-                .get_replica_state(&self.node_id)
-                .map(|s| s.state_hash)
-                .unwrap_or_else(|| StateHash::from_hex("0".repeat(64)))
-        }
-
-        /// Check if this node has received all expected envelopes
-        async fn operations_applied(&self) -> u64 {
-            let executor = self.executor.lock().await;
-            executor
-                .get_replica_state(&self.node_id)
-                .map(|s| s.operations_applied)
-                .unwrap_or(0)
-        }
-
-        /// Submit a single operation (leader only)
-        async fn submit_operation(&self, op_idx: u64) -> Result<(), String> {
-            let mut executor = self.executor.lock().await;
-            let mut seq = self.sequence.lock().await;
-            *seq += 1;
-
-            let op_id = OperationId::new(self.node_id.clone(), *seq);
-            let parent_vc = VectorClock::new();
-            let parent_version = StateVersion::new(parent_vc, "0".repeat(64));
-
-            let mut fields = HashMap::new();
-            fields.insert("value".to_string(), json!(op_idx));
-
-            let operation = Operation::new(
-                op_id,
-                parent_version.clone(),
-                format!("op_{}", op_idx),
-                OperationCommand {
-                    op_type: "set".to_string(),
-                    collection: "items".to_string(),
-                    record_id: format!("item_{}", op_idx),
-                    fields,
-                },
-                self.node_id.clone(),
-            );
-
-            let envelope = executor.execute_local_transaction(
-                *seq,
-                format!("txn_{}", op_idx),
-                parent_version,
-                vec![operation],
-                ConsistencyContract::causal(),
-            )?;
-
-            Ok(())
-        }
-    }
-
-    /// Test coordinator for managing 3-node cluster
-    struct TestCluster {
-        nodes: Vec<TestNode>,
-    }
-
-    impl TestCluster {
-        fn new(node_count: usize) -> Self {
-            let mut nodes = Vec::new();
-            for i in 0..node_count {
-                let node_id = format!("node-{}", i);
-                let port = 10000 + i as u16;
-                nodes.push(TestNode::new(node_id, port));
-            }
-            Self { nodes }
-        }
-
-        /// Get node by index
-        fn node(&self, idx: usize) -> &TestNode {
-            &self.nodes[idx]
-        }
-
-        /// Start listening on all nodes
-        async fn start_listeners(&self) {
-            for node in &self.nodes {
-                let transport = node.transport.clone();
-                let _handle = task::spawn(async move {
-                    let mut t = transport.lock().await;
-                    let _ = t.listen().await;
-                });
-            }
-            // Give listeners time to start
-            tokio::time::sleep(Duration::from_millis(100)).await;
-        }
-
-        /// Connect followers to leader
-        async fn establish_replication_topology(&self) {
-            let leader_addr = self.nodes[0].addr();
-
-            for node in self.nodes.iter().skip(1) {
-                let mut t = node.transport.lock().await;
-                let _ = (*t).connect(&leader_addr).await;
-            }
-        }
-
-        /// Simulate replication: broadcast leader messages to all followers
-        async fn replicate_from_leader(&self, operations_count: u64) {
-            let leader = &self.nodes[0];
-            let followers: Vec<_> = (1..self.nodes.len()).collect();
-
-            // Wait for operations to be applied on followers
-            for op_idx in 0..operations_count {
-                // Small delay between operations to allow replication
-                tokio::time::sleep(Duration::from_millis(1)).await;
-            }
-        }
-
-        /// Verify all nodes have converged to same state
-        async fn verify_convergence(&self) -> Result<(), String> {
-            let mut hashes = Vec::new();
-
-            for node in &self.nodes {
-                let executor = node.executor.lock().await;
-                let state = executor.get_replica_state(&node.node_id);
-                if let Some(s) = state {
-                    hashes.push(s.state_hash);
-                } else {
-                    return Err(format!("Node {} has no state", node.node_id));
-                }
-            }
-
-            if hashes.is_empty() {
-                return Err("No nodes".to_string());
-            }
-
-            let first = &hashes[0];
-            for (idx, hash) in hashes.iter().enumerate().skip(1) {
-                if hash != first {
-                    return Err(format!(
-                        "Convergence failed: node-0 has {}, node-{} has {}",
-                        first, idx, hash
-                    ));
-                }
-            }
-
-            Ok(())
-        }
-
-        /// Get statistics about replication
-        async fn get_stats(&self) -> ClusterStats {
-            let mut total_ops_applied = 0;
-            let mut node_states = Vec::new();
-
-            for node in &self.nodes {
-                let ops = node.operations_applied().await;
-                let hash = node.state_hash().await;
-                total_ops_applied += ops;
-                node_states.push((node.node_id.clone(), ops, hash));
-            }
-
-            ClusterStats {
-                node_states,
-                total_ops_applied,
-            }
-        }
-    }
-
-    struct ClusterStats {
-        node_states: Vec<(String, u64, StateHash)>,
-        total_ops_applied: u64,
-    }
-
-    /// Phase 1c Test 1: Cluster initialization (no networking yet)
-    #[tokio::test]
-    async fn three_node_cluster_initializes() {
-        let cluster = TestCluster::new(3);
-
-        // Verify all nodes are created with initialized state
-        for node in &cluster.nodes {
-            let hash = node.state_hash().await;
-            // Hash should be deterministic initial value
-            assert_ne!(hash, StateHash::from_hex("".to_string()), "Node {} should have state", node.node_id);
-        }
-    }
-
-    /// Phase 1c Test 2: Submit single operation to leader
-    #[tokio::test]
-    async fn leader_submit_single_operation() {
-        let cluster = TestCluster::new(3);
-        let leader = cluster.node(0);
-
-        // Submit first operation
-        leader
-            .submit_operation(0)
-            .await
-            .expect("submit should succeed");
-
-        // Verify leader state changed
-        let ops_applied = leader.operations_applied().await;
-        assert_eq!(ops_applied, 1, "Leader should have 1 operation applied");
-    }
-
-    /// Phase 1c Test 3: Submit 100 operations to leader
-    #[tokio::test]
-    async fn leader_submit_100_operations() {
-        let cluster = TestCluster::new(3);
-        let leader = cluster.node(0);
-        let start = Instant::now();
-
-        // Submit 100 operations through leader
-        for i in 0..100 {
-            leader
-                .submit_operation(i)
-                .await
-                .expect("submit should succeed");
-        }
-
-        // Check leader has all operations
-        let leader_ops = leader.operations_applied().await;
-        assert_eq!(leader_ops, 100, "Leader should have 100 operations applied");
-
-        println!(
-            "Submitted 100 operations in {:?}",
-            start.elapsed()
-        );
-    }
-
-    /// Phase 1c Test 4: Leader can track multiple operations
-    #[tokio::test]
-    async fn leader_tracks_operation_sequence() {
-        let cluster = TestCluster::new(3);
-        let leader = cluster.node(0);
-
-        // Submit multiple operations
-        for i in 0..50 {
-            leader
-                .submit_operation(i)
-                .await
-                .expect("submit should succeed");
-        }
-
-        let ops_applied = leader.operations_applied().await;
-        assert_eq!(ops_applied, 50, "Leader should track all 50 operations");
-    }
-
-    /// Phase 1c Test 5: Submit 1000 operations to leader
-    #[tokio::test]
-    async fn leader_submit_1000_operations() {
-        let cluster = TestCluster::new(3);
-        let leader = cluster.node(0);
-        let start = Instant::now();
-
-        // Submit 1000 operations
-        for i in 0..1000 {
-            leader
-                .submit_operation(i)
-                .await
-                .expect("submit should succeed");
-
-            // Add small delay to avoid overwhelming the system
-            if i % 100 == 0 {
-                tokio::time::sleep(Duration::from_millis(1)).await;
-            }
-        }
-
-        let elapsed = start.elapsed();
-        let leader_ops = leader.operations_applied().await;
-
-        println!("Submitted 1000 operations in {:?}", elapsed);
-        println!("Leader has {} operations applied", leader_ops);
-
-        assert_eq!(leader_ops, 1000, "Leader should have all 1000 operations applied");
-    }
-
-    /// Phase 1c Test 6: Multiple nodes can submit operations independently
-    #[tokio::test]
-    async fn multiple_nodes_submit_independently() {
-        let cluster = TestCluster::new(3);
-        let node0 = cluster.node(0);
-        let node1 = cluster.node(1);
-        let node2 = cluster.node(2);
-
-        // Each node submits operations independently
-        for i in 0..10 {
-            node0.submit_operation(i).await.expect("node0 submit");
-            node1.submit_operation(i + 1000).await.expect("node1 submit");
-            node2.submit_operation(i + 2000).await.expect("node2 submit");
-        }
-
-        // Verify each node tracks its operations
-        assert_eq!(node0.operations_applied().await, 10, "Node0 ops");
-        assert_eq!(node1.operations_applied().await, 10, "Node1 ops");
-        assert_eq!(node2.operations_applied().await, 10, "Node2 ops");
-
-        println!("All 3 nodes submitted 10 operations each independently");
-    }
-
-    /// Replication Test 1: Single operation replication between two nodes
-    #[tokio::test]
-    async fn replicate_single_operation_to_follower() {
-        let leader_id = "leader".to_string();
-        let follower_id = "follower".to_string();
-
-        let initial_hash = StateHash::from_hex("0".repeat(64));
-        let mut leader_executor = DistributedTransactionExecutor::new(leader_id.clone(), initial_hash.clone());
-        let mut follower_executor = DistributedTransactionExecutor::new(follower_id.clone(), initial_hash.clone());
-
-        // Register replicas
-        leader_executor.register_replica(follower_id.clone(), initial_hash.clone());
-        follower_executor.register_replica(leader_id.clone(), initial_hash.clone());
-
-        // Leader submits operation
-        let op_id = OperationId::new(leader_id.clone(), 1);
-        let parent_vc = VectorClock::new();
-        let parent_version = StateVersion::new(parent_vc, "0".repeat(64));
-
-        let mut fields = HashMap::new();
-        fields.insert("value".to_string(), json!(42));
-
-        let operation = Operation::new(
-            op_id,
-            parent_version.clone(),
-            "op_1".to_string(),
-            OperationCommand {
-                op_type: "set".to_string(),
-                collection: "items".to_string(),
-                record_id: "item_1".to_string(),
-                fields,
-            },
-            leader_id.clone(),
-        );
-
-        let envelope = leader_executor
-            .execute_local_transaction(
-                1,
-                "txn_1".to_string(),
-                parent_version.clone(),
-                vec![operation],
-                ConsistencyContract::causal(),
-            )
-            .expect("leader should execute");
-
-        // Create replication message
-        let message = ReplicationMessage::new(
-            envelope,
-            leader_id.clone(),
-            follower_id.clone(),
-            1,
-        );
-
-        // Follower applies replicated operation
-        let follower_result = follower_executor.receive_replicated_transaction(message, parent_version);
-        assert!(follower_result.is_ok(), "Follower should apply operation");
-
-        // Verify leader and follower have same state
-        let leader_state = leader_executor.get_replica_state(&leader_id).unwrap();
-        let follower_state = follower_executor.get_replica_state(&follower_id).unwrap();
-
-        println!(
-            "Leader hash: {}, Follower hash: {}",
-            leader_state.state_hash, follower_state.state_hash
-        );
-        println!(
-            "Leader ops: {}, Follower ops: {}",
-            leader_state.operations_applied, follower_state.operations_applied
-        );
-    }
-
-    /// Replication Test 2: Multiple operations converge across 3 nodes
-    #[tokio::test]
-    async fn three_node_convergence_with_replication() {
-        let node_ids = ["leader", "follower1", "follower2"];
-        let mut executors: Vec<_> = node_ids
-            .iter()
-            .map(|id| {
-                let initial_hash = StateHash::from_hex("0".repeat(64));
-                DistributedTransactionExecutor::new(id.to_string(), initial_hash)
-            })
-            .collect();
-
-        let initial_hash = StateHash::from_hex("0".repeat(64));
-
-        // Register replicas on all executors
-        for executor in &mut executors {
-            for node_id in &node_ids {
-                if node_id != &executor.local_node_id.as_str() {
-                    executor.register_replica(node_id.to_string(), initial_hash.clone());
-                }
-            }
-        }
-
-        // Leader submits 10 operations
-        let mut envelopes = Vec::new();
-        for i in 0..10 {
-            let op_id = OperationId::new("leader".to_string(), i + 1);
-            let parent_vc = VectorClock::new();
-            let parent_version = StateVersion::new(parent_vc, "0".repeat(64));
-
-            let mut fields = HashMap::new();
-            fields.insert("value".to_string(), json!(i));
-
-            let operation = Operation::new(
-                op_id,
-                parent_version.clone(),
-                format!("op_{}", i),
-                OperationCommand {
-                    op_type: "set".to_string(),
-                    collection: "items".to_string(),
-                    record_id: format!("item_{}", i),
-                    fields,
-                },
-                "leader".to_string(),
-            );
-
-            let envelope = executors[0]
-                .execute_local_transaction(
-                    i + 1,
-                    format!("txn_{}", i),
-                    parent_version,
-                    vec![operation],
-                    ConsistencyContract::causal(),
-                )
-                .expect("leader execute");
-
-            envelopes.push(envelope);
-        }
-
-        // Followers apply operations
-        for (follower_idx, follower_id) in node_ids.iter().enumerate().skip(1) {
-            for envelope in &envelopes {
-                let message = ReplicationMessage::new(
-                    envelope.clone(),
-                    "leader".to_string(),
-                    follower_id.to_string(),
-                    0,
-                );
-
-                let parent_version = StateVersion::new(VectorClock::new(), "0".repeat(64));
-                let _ = executors[follower_idx].receive_replicated_transaction(message, parent_version);
-            }
-        }
-
-        // Verify convergence
-        let leader_state = executors[0].get_replica_state("leader").unwrap();
-        let follower1_state = executors[1].get_replica_state("follower1").unwrap();
-        let follower2_state = executors[2].get_replica_state("follower2").unwrap();
-
-        println!(
-            "Leader: {} ops, hash {}",
-            leader_state.operations_applied, leader_state.state_hash
-        );
-        println!(
-            "Follower1: {} ops, hash {}",
-            follower1_state.operations_applied, follower1_state.state_hash
-        );
-        println!(
-            "Follower2: {} ops, hash {}",
-            follower2_state.operations_applied, follower2_state.state_hash
-        );
-
-        // All nodes should have applied the same number of operations on their respective views
-        assert_eq!(leader_state.operations_applied, 10, "Leader ops");
-        assert_eq!(follower1_state.operations_applied, 10, "Follower1 ops");
-        assert_eq!(follower2_state.operations_applied, 10, "Follower2 ops");
-    }
-}