@feltdb/core 0.4.12 → 0.4.13

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

@@ -0,0 +1,536 @@
+/// Distributed Transactions & Replication
+///
+/// Coordinates transaction execution across multiple nodes:
+/// - TransactionEnvelope: Atomic unit for multi-replica delivery
+/// - ReplicationMessage: Operation streaming between replicas
+/// - ReplicaState: Per-node state tracking with vector clocks
+/// - DistributedExecutor: Orchestrates consistency semantics
+///
+/// Invariant: All replicas converge to identical state_hash for same operations
+
+use crate::convergence::VectorClock;
+use crate::durable_operation_log::OperationLog;
+use crate::state_hash::StateHash;
+use crate::transactions::*;
+use std::collections::HashMap;
+use std::path::PathBuf;
+
+/// Uniquely identifies a transaction envelope
+#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub struct EnvelopeId {
+    pub originating_node: String,
+    pub sequence: u64,
+}
+
+impl EnvelopeId {
+    pub fn new(originating_node: String, sequence: u64) -> Self {
+        Self {
+            originating_node,
+            sequence,
+        }
+    }
+}
+
+/// Atomic unit for multi-replica delivery
+/// Prevents partial delivery of multi-operation transactions
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub struct TransactionEnvelope {
+    pub envelope_id: EnvelopeId,
+    pub transaction_id: String,
+    pub operations: Vec<Operation>,
+    pub consistency_contract: ConsistencyContract,
+    pub originating_node: String,
+    pub vector_clock: VectorClock,
+    pub timestamp_ms: u64,
+}
+
+impl TransactionEnvelope {
+    pub fn new(
+        originating_node: String,
+        sequence: u64,
+        transaction_id: String,
+        operations: Vec<Operation>,
+        consistency_contract: ConsistencyContract,
+    ) -> Self {
+        let mut vc = VectorClock::new();
+        vc.increment(&originating_node);
+
+        let timestamp_ms = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_millis() as u64;
+
+        Self {
+            envelope_id: EnvelopeId::new(originating_node.clone(), sequence),
+            transaction_id,
+            operations,
+            consistency_contract,
+            originating_node,
+            vector_clock: vc,
+            timestamp_ms,
+        }
+    }
+
+    /// Advance vector clock to account for replication delay
+    pub fn advance_clock(&mut self, replica_clock: &VectorClock) {
+        self.vector_clock.merge(replica_clock);
+        self.vector_clock.increment(&self.originating_node);
+    }
+
+    /// Verify envelope integrity (all operations present)
+    pub fn verify_integrity(&self) -> bool {
+        !self.operations.is_empty()
+            && self.transaction_id.len() > 0
+            && self.originating_node.len() > 0
+    }
+}
+
+/// Message format for distributed operation streaming
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub struct ReplicationMessage {
+    pub envelope: TransactionEnvelope,
+    pub from_node: String,
+    pub to_node: String,
+    pub sequence_number: u64,
+}
+
+impl ReplicationMessage {
+    pub fn new(
+        envelope: TransactionEnvelope,
+        from_node: String,
+        to_node: String,
+        sequence_number: u64,
+    ) -> Self {
+        Self {
+            envelope,
+            from_node,
+            to_node,
+            sequence_number,
+        }
+    }
+}
+
+/// State of a replica
+#[derive(Clone, Debug)]
+pub struct ReplicaState {
+    pub node_id: String,
+    pub vector_clock: VectorClock,
+    pub state_hash: StateHash,
+    pub operations_applied: u64,
+    pub last_update_ms: u64,
+}
+
+impl ReplicaState {
+    pub fn new(node_id: String, initial_hash: StateHash) -> Self {
+        Self {
+            node_id,
+            vector_clock: VectorClock::new(),
+            state_hash: initial_hash,
+            operations_applied: 0,
+            last_update_ms: std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_millis() as u64,
+        }
+    }
+
+    /// Update replica state after transaction
+    pub fn apply_transaction(
+        &mut self,
+        envelope: &TransactionEnvelope,
+        new_state_hash: StateHash,
+    ) {
+        self.vector_clock.merge(&envelope.vector_clock);
+        self.vector_clock.increment(&self.node_id);
+        self.state_hash = new_state_hash;
+        self.operations_applied += envelope.operations.len() as u64;
+        self.last_update_ms = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_millis() as u64;
+    }
+
+    /// Causal read: wait for vector clock to advance
+    pub fn wait_for_clock_advance(&self, required_clock: &VectorClock) -> bool {
+        !self.vector_clock.happens_before(required_clock)
+    }
+}
+
+/// Distributed transaction executor with durable operation log support
+///
+/// Durability architecture:
+/// - Operation log is the ONLY durable source of truth
+/// - Dedup set is derived (reconstructed from operation log on startup)
+/// - No separate dedup file (eliminates two-file atomicity problem)
+pub struct DistributedTransactionExecutor {
+    pub local_node_id: String,
+    pub replicas: HashMap<String, ReplicaState>,
+    pub envelopes_seen: std::collections::HashSet<EnvelopeId>,
+    pub transaction_executor: TransactionExecutor,
+    pub operation_log: Option<OperationLog>,
+}
+
+impl DistributedTransactionExecutor {
+    /// Create a new distributed executor without durable persistence
+    pub fn new(node_id: String, initial_state_hash: StateHash) -> Self {
+        let mut replicas = HashMap::new();
+        replicas.insert(
+            node_id.clone(),
+            ReplicaState::new(node_id.clone(), initial_state_hash),
+        );
+
+        Self {
+            local_node_id: node_id.clone(),
+            replicas,
+            envelopes_seen: std::collections::HashSet::new(),
+            transaction_executor: TransactionExecutor::new(node_id),
+            operation_log: None,
+        }
+    }
+
+    /// Create a new distributed executor with durable operation log
+    ///
+    /// Note: dedup set is NOT persisted separately. It is reconstructed deterministically
+    /// from the operation log on startup, eliminating atomicity issues.
+    pub fn with_log(
+        node_id: String,
+        initial_state_hash: StateHash,
+        log_path: Option<PathBuf>,
+    ) -> Result<Self, std::io::Error> {
+        let mut replicas = HashMap::new();
+        replicas.insert(
+            node_id.clone(),
+            ReplicaState::new(node_id.clone(), initial_state_hash),
+        );
+
+        let operation_log = if let Some(path) = &log_path {
+            Some(OperationLog::new(path)?)
+        } else {
+            None
+        };
+
+        Ok(Self {
+            local_node_id: node_id.clone(),
+            replicas,
+            envelopes_seen: std::collections::HashSet::new(),
+            transaction_executor: TransactionExecutor::new(node_id),
+            operation_log,
+        })
+    }
+
+    /// Register a replica (peer node)
+    pub fn register_replica(&mut self, node_id: String, initial_state_hash: StateHash) {
+        self.replicas.insert(
+            node_id.clone(),
+            ReplicaState::new(node_id, initial_state_hash),
+        );
+    }
+
+    /// Execute transaction locally and prepare for replication
+    /// Ordering: execute → persist → update state → record dedup
+    pub fn execute_local_transaction(
+        &mut self,
+        sequence: u64,
+        transaction_id: String,
+        parent_version: StateVersion,
+        operations: Vec<Operation>,
+        consistency_contract: ConsistencyContract,
+    ) -> Result<TransactionEnvelope, String> {
+        // Step 1: Execute transaction through 14C
+        let transition = self.transaction_executor.execute_transaction(
+            transaction_id.clone(),
+            parent_version,
+            operations.clone(),
+            consistency_contract.clone(),
+        );
+
+        if !transition.is_successful() {
+            return Err("Transaction execution failed".to_string());
+        }
+
+        // Step 2: Create envelope for replication
+        let envelope = TransactionEnvelope::new(
+            self.local_node_id.clone(),
+            sequence,
+            transaction_id,
+            operations,
+            consistency_contract,
+        );
+
+        // Step 3: Durably persist operation to log (with fsync)
+        // This must succeed before we update in-memory state
+        self.persist_envelope(&envelope)?;
+
+        // Step 4: Update local replica state (in-memory)
+        if let Some(local_replica) = self.replicas.get_mut(&self.local_node_id) {
+            let state_hash = StateHash::from_hex(transition.to_version.state_hash.clone());
+            local_replica.apply_transaction(&envelope, state_hash);
+        }
+
+        // Step 5: Record envelope to prevent duplicates (in-memory, derived from log)
+        self.envelopes_seen.insert(envelope.envelope_id.clone());
+
+        Ok(envelope)
+    }
+
+    /// Receive replicated transaction from peer
+    /// Ordering: dedup check → execute → persist → update state
+    pub fn receive_replicated_transaction(
+        &mut self,
+        message: ReplicationMessage,
+        parent_version: StateVersion,
+    ) -> Result<StateHash, String> {
+        // Step 1: Check for duplicate (prevent re-application)
+        if self.envelopes_seen.contains(&message.envelope.envelope_id) {
+            return Err("Duplicate envelope".to_string());
+        }
+
+        // Step 2: Execute transaction through 14C
+        let transition = self.transaction_executor.execute_transaction(
+            message.envelope.transaction_id.clone(),
+            parent_version,
+            message.envelope.operations.clone(),
+            message.envelope.consistency_contract.clone(),
+        );
+
+        if !transition.is_successful() {
+            return Err("Transaction execution failed".to_string());
+        }
+
+        // Step 3: Durably persist operation to log (with fsync)
+        self.persist_envelope(&message.envelope)?;
+
+        // Step 4: Record envelope to prevent duplicates (in-memory)
+        self.envelopes_seen.insert(message.envelope.envelope_id.clone());
+
+        // Step 5: Update this replica's state (receiver updates itself)
+        if let Some(replica) = self.replicas.get_mut(&self.local_node_id) {
+            let state_hash = StateHash::from_hex(transition.to_version.state_hash.clone());
+            replica.apply_transaction(&message.envelope, state_hash);
+        }
+
+        // Return the state hash
+        Ok(StateHash::from_hex(transition.to_version.state_hash))
+    }
+
+    /// Get current state of a replica
+    pub fn get_replica_state(&self, node_id: &str) -> Option<ReplicaState> {
+        self.replicas.get(node_id).cloned()
+    }
+
+    /// Check if replicas have converged to same state
+    pub fn check_convergence(&self) -> bool {
+        if self.replicas.is_empty() {
+            return true;
+        }
+
+        let first_hash = self
+            .replicas
+            .values()
+            .next()
+            .map(|r| r.state_hash.clone());
+
+        if let Some(first) = first_hash {
+            self.replicas.values().all(|r| r.state_hash == first)
+        } else {
+            false
+        }
+    }
+
+    /// Get all replica states
+    pub fn get_all_replicas(&self) -> Vec<ReplicaState> {
+        self.replicas.values().cloned().collect()
+    }
+
+    /// Causal read: wait for specific version
+    pub fn causal_read(&self, required_clock: &VectorClock) -> bool {
+        if let Some(local) = self.replicas.get(&self.local_node_id) {
+            local.wait_for_clock_advance(required_clock)
+        } else {
+            false
+        }
+    }
+
+    /// Get the local node ID
+    pub fn get_local_node_id(&self) -> String {
+        self.local_node_id.clone()
+    }
+
+    /// Load persisted operations from disk and rebuild internal state
+    ///
+    /// Atomicity guarantee:
+    /// - Load operation log (single durable source of truth)
+    /// - Reconstruct dedup set deterministically from envelopes
+    /// - No separate dedup file (no two-file atomicity problem)
+    pub fn load_from_disk(&mut self, log_path: PathBuf) -> Result<usize, std::io::Error> {
+        let log = OperationLog::new(&log_path)?;
+        let envelopes = log.load_all()?;
+
+        // Reconstruct dedup set from loaded envelopes (deterministic, atomic with log)
+        for envelope in &envelopes {
+            self.envelopes_seen.insert(envelope.envelope_id.clone());
+        }
+
+        // Note: Replica state is not rebuilt from log in this initial version
+        // It will be recovered through normal replication when this node rejoins the cluster
+        self.operation_log = Some(log);
+
+        Ok(envelopes.len())
+    }
+
+    /// Persist an envelope to the durable operation log
+    /// Must be called after successful state application but before returning to caller
+    ///
+    /// Note: dedup set is NOT persisted (it's derived from the operation log).
+    fn persist_envelope(&mut self, envelope: &TransactionEnvelope) -> Result<(), String> {
+        if let Some(ref mut log) = self.operation_log {
+            log.append(envelope)
+                .map_err(|e| format!("Failed to persist operation: {}", e))?;
+        }
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_envelope_creation() {
+        let envelope = TransactionEnvelope::new(
+            "node1".to_string(),
+            1,
+            "txn1".to_string(),
+            Vec::new(),
+            ConsistencyContract::causal(),
+        );
+
+        assert_eq!(envelope.originating_node, "node1");
+        assert_eq!(envelope.transaction_id, "txn1");
+        assert_eq!(envelope.envelope_id.sequence, 1);
+    }
+
+    #[test]
+    fn test_envelope_integrity() {
+        let envelope = TransactionEnvelope::new(
+            "node1".to_string(),
+            1,
+            "txn1".to_string(),
+            vec![], // Empty operations
+            ConsistencyContract::causal(),
+        );
+
+        assert!(!envelope.verify_integrity());
+    }
+
+    #[test]
+    fn test_replication_message_creation() {
+        let envelope = TransactionEnvelope::new(
+            "node1".to_string(),
+            1,
+            "txn1".to_string(),
+            Vec::new(),
+            ConsistencyContract::causal(),
+        );
+
+        let msg = ReplicationMessage::new(envelope, "node1".to_string(), "node2".to_string(), 1);
+
+        assert_eq!(msg.from_node, "node1");
+        assert_eq!(msg.to_node, "node2");
+    }
+
+    #[test]
+    fn test_replica_state_creation() {
+        let state = ReplicaState::new("node1".to_string(), StateHash::from_hex("hash0".to_string()));
+
+        assert_eq!(state.node_id, "node1");
+        assert_eq!(state.operations_applied, 0);
+    }
+
+    #[test]
+    fn test_distributed_executor_creation() {
+        let executor = DistributedTransactionExecutor::new(
+            "node1".to_string(),
+            StateHash::from_hex("hash0".to_string()),
+        );
+
+        assert!(executor.replicas.contains_key("node1"));
+    }
+
+    #[test]
+    fn test_register_replica() {
+        let mut executor = DistributedTransactionExecutor::new(
+            "node1".to_string(),
+            StateHash::from_hex("hash0".to_string()),
+        );
+
+        executor.register_replica("node2".to_string(), StateHash::from_hex("hash0".to_string()));
+
+        assert!(executor.replicas.contains_key("node2"));
+    }
+
+    #[test]
+    fn test_convergence_check_empty() {
+        let executor = DistributedTransactionExecutor::new(
+            "node1".to_string(),
+            StateHash::from_hex("hash0".to_string()),
+        );
+
+        // Single replica should be converged
+        assert!(executor.check_convergence());
+    }
+
+    #[test]
+    fn test_convergence_check_multiple_replicas() {
+        let mut executor = DistributedTransactionExecutor::new(
+            "node1".to_string(),
+            StateHash::from_hex("hash0".to_string()),
+        );
+
+        executor.register_replica("node2".to_string(), StateHash::from_hex("hash0".to_string()));
+        executor.register_replica("node3".to_string(), StateHash::from_hex("hash0".to_string()));
+
+        assert!(executor.check_convergence());
+    }
+
+    #[test]
+    fn test_convergence_check_diverged() {
+        let mut executor = DistributedTransactionExecutor::new(
+            "node1".to_string(),
+            StateHash::from_hex("hash0".to_string()),
+        );
+
+        executor.register_replica("node2".to_string(), StateHash::from_hex("hash1".to_string()));
+
+        assert!(!executor.check_convergence());
+    }
+
+    #[test]
+    fn test_causal_read_initial_state() {
+        let executor = DistributedTransactionExecutor::new(
+            "node1".to_string(),
+            StateHash::from_hex("hash0".to_string()),
+        );
+
+        let vc = VectorClock::new();
+        assert!(executor.causal_read(&vc));
+    }
+
+    #[test]
+    fn test_envelope_clock_advance() {
+        let mut envelope = TransactionEnvelope::new(
+            "node1".to_string(),
+            1,
+            "txn1".to_string(),
+            Vec::new(),
+            ConsistencyContract::causal(),
+        );
+
+        let mut other_clock = VectorClock::new();
+        other_clock.increment("node2");
+
+        envelope.advance_clock(&other_clock);
+
+        assert!(envelope.vector_clock.happens_before(&other_clock) == false);
+    }
+}