create-feltdb 0.5.5 → 0.5.7

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

@@ -0,0 +1,461 @@
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use std::collections::HashMap;
+use std::sync::{Arc, RwLock};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// Transaction status for idempotency and recovery.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum TransactionStatus {
+    /// Transaction status is unknown (may be in-flight or lost).
+    Unknown,
+    /// Transaction successfully committed.
+    Committed,
+    /// Transaction was rejected (validation failure).
+    Rejected,
+    /// Transaction conflicted (concurrent write or version mismatch).
+    Conflicted,
+}
+
+/// Record of a transaction for idempotency and recovery.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TransactionRecord {
+    /// Unique transaction ID.
+    pub transaction_id: String,
+
+    /// Current status of the transaction.
+    pub status: TransactionStatus,
+
+    /// Hash of the payload for idempotency checking.
+    /// Same ID + same payload = retry is safe
+    /// Same ID + different payload = conflict
+    pub payload_hash: String,
+
+    /// State version after transaction (if committed).
+    pub state_version: u64,
+
+    /// When this transaction was recorded.
+    pub recorded_at: u64,
+
+    /// When the transaction was committed (if successful).
+    pub committed_at: Option<u64>,
+
+    /// Reason for rejection or conflict (if applicable).
+    pub error: Option<String>,
+}
+
+/// Request to check transaction status.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TransactionStatusRequest {
+    pub transaction_id: String,
+    pub payload_hash: Option<String>,
+}
+
+/// Response with transaction status.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TransactionStatusResponse {
+    pub transaction_id: String,
+    pub status: TransactionStatus,
+    pub payload_hash: String,
+    pub state_version: u64,
+    pub committed_at: Option<u64>,
+    pub error: Option<String>,
+}
+
+/// Recoverable transaction store.
+#[derive(Clone)]
+pub struct TransactionRecoveryStore {
+    records: Arc<RwLock<HashMap<String, TransactionRecord>>>,
+}
+
+impl TransactionRecoveryStore {
+    /// Creates a new recovery store.
+    pub fn new() -> Self {
+        Self {
+            records: Arc::new(RwLock::new(HashMap::new())),
+        }
+    }
+
+    /// Records a transaction being processed.
+    pub fn record_unknown(
+        &self,
+        transaction_id: String,
+        payload_hash: String,
+    ) -> Result<(), String> {
+        let mut records = self
+            .records
+            .write()
+            .map_err(|_| "store lock poisoned".to_string())?;
+
+        let id = transaction_id.clone();
+        records.insert(
+            transaction_id,
+            TransactionRecord {
+                transaction_id: id,
+                status: TransactionStatus::Unknown,
+                payload_hash,
+                state_version: 0,
+                recorded_at: now(),
+                committed_at: None,
+                error: None,
+            },
+        );
+
+        Ok(())
+    }
+
+    /// Records a successful commit.
+    pub fn record_committed(
+        &self,
+        transaction_id: String,
+        payload_hash: String,
+        state_version: u64,
+    ) -> Result<(), String> {
+        let mut records = self
+            .records
+            .write()
+            .map_err(|_| "store lock poisoned".to_string())?;
+
+        let txn_id = transaction_id.clone();
+        records.insert(
+            txn_id.clone(),
+            TransactionRecord {
+                transaction_id: txn_id,
+                status: TransactionStatus::Committed,
+                payload_hash,
+                state_version,
+                recorded_at: now(),
+                committed_at: Some(now()),
+                error: None,
+            },
+        );
+
+        Ok(())
+    }
+
+    /// Records a rejection.
+    pub fn record_rejected(
+        &self,
+        transaction_id: String,
+        payload_hash: String,
+        error: String,
+    ) -> Result<(), String> {
+        let mut records = self
+            .records
+            .write()
+            .map_err(|_| "store lock poisoned".to_string())?;
+
+        let id = transaction_id.clone();
+        records.insert(
+            id.clone(),
+            TransactionRecord {
+                transaction_id: id,
+                status: TransactionStatus::Rejected,
+                payload_hash,
+                state_version: 0,
+                recorded_at: now(),
+                committed_at: None,
+                error: Some(error),
+            },
+        );
+
+        Ok(())
+    }
+
+    /// Records a conflict.
+    pub fn record_conflicted(
+        &self,
+        transaction_id: String,
+        payload_hash: String,
+        error: String,
+    ) -> Result<(), String> {
+        let mut records = self
+            .records
+            .write()
+            .map_err(|_| "store lock poisoned".to_string())?;
+
+        let id = transaction_id.clone();
+        records.insert(
+            id.clone(),
+            TransactionRecord {
+                transaction_id: id,
+                status: TransactionStatus::Conflicted,
+                payload_hash,
+                state_version: 0,
+                recorded_at: now(),
+                committed_at: None,
+                error: Some(error),
+            },
+        );
+
+        Ok(())
+    }
+
+    /// Gets transaction status.
+    pub fn get_status(&self, transaction_id: &str) -> Result<TransactionStatusResponse, String> {
+        let records = self
+            .records
+            .read()
+            .map_err(|_| "store lock poisoned".to_string())?;
+
+        let record = records
+            .get(transaction_id)
+            .ok_or(format!("transaction not found: {}", transaction_id))?;
+
+        Ok(TransactionStatusResponse {
+            transaction_id: record.transaction_id.clone(),
+            status: record.status,
+            payload_hash: record.payload_hash.clone(),
+            state_version: record.state_version,
+            committed_at: record.committed_at,
+            error: record.error.clone(),
+        })
+    }
+
+    /// Checks if a retry is safe (idempotent).
+    pub fn is_retry_safe(&self, transaction_id: &str, payload_hash: &str) -> Result<bool, String> {
+        let records = self
+            .records
+            .read()
+            .map_err(|_| "store lock poisoned".to_string())?;
+
+        let record = records.get(transaction_id);
+
+        match record {
+            None => Ok(true), // Unknown transaction - safe to retry
+            Some(r) => {
+                // Same payload = safe to retry
+                if r.payload_hash == payload_hash {
+                    Ok(r.status == TransactionStatus::Committed || r.status == TransactionStatus::Unknown)
+                } else {
+                    // Different payload = conflict
+                    Ok(false)
+                }
+            }
+        }
+    }
+
+    /// Clears old transaction records (for cleanup).
+    pub fn cleanup_before(&self, cutoff_time: u64) -> Result<usize, String> {
+        let mut records = self
+            .records
+            .write()
+            .map_err(|_| "store lock poisoned".to_string())?;
+
+        let before_len = records.len();
+        records.retain(|_, r| r.recorded_at >= cutoff_time);
+        let after_len = records.len();
+
+        Ok(before_len - after_len)
+    }
+}
+
+impl Default for TransactionRecoveryStore {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Computes payload hash for transaction idempotency.
+pub fn compute_payload_hash(payload: &[u8]) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(payload);
+    format!("{:x}", hasher.finalize())
+}
+
+fn now() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn test_payload_hash() -> String {
+        compute_payload_hash(b"test payload")
+    }
+
+    #[test]
+    fn record_and_retrieve_committed_transaction() {
+        let store = TransactionRecoveryStore::new();
+
+        store
+            .record_committed("txn_123".into(), test_payload_hash(), 42)
+            .expect("record failed");
+
+        let status = store.get_status("txn_123").expect("get failed");
+        assert_eq!(status.status, TransactionStatus::Committed);
+        assert_eq!(status.state_version, 42);
+    }
+
+    #[test]
+    fn unknown_transaction_not_found() {
+        let store = TransactionRecoveryStore::new();
+
+        let result = store.get_status("txn_unknown");
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn same_payload_is_safe_to_retry() {
+        let store = TransactionRecoveryStore::new();
+        let hash = test_payload_hash();
+
+        store
+            .record_committed("txn_123".into(), hash.clone(), 42)
+            .expect("record failed");
+
+        let is_safe = store.is_retry_safe("txn_123", &hash).expect("check failed");
+        assert!(is_safe);
+    }
+
+    #[test]
+    fn different_payload_is_conflict() {
+        let store = TransactionRecoveryStore::new();
+        let hash1 = test_payload_hash();
+        let hash2 = compute_payload_hash(b"different payload");
+
+        store
+            .record_committed("txn_123".into(), hash1, 42)
+            .expect("record failed");
+
+        let is_safe = store.is_retry_safe("txn_123", &hash2).expect("check failed");
+        assert!(!is_safe);
+    }
+
+    #[test]
+    fn unknown_transaction_is_safe_to_retry() {
+        let store = TransactionRecoveryStore::new();
+        let hash = test_payload_hash();
+
+        let is_safe = store.is_retry_safe("txn_unknown", &hash).expect("check failed");
+        assert!(is_safe);
+    }
+
+    #[test]
+    fn rejected_transaction_with_same_payload_is_not_safe() {
+        let store = TransactionRecoveryStore::new();
+        let hash = test_payload_hash();
+
+        store
+            .record_rejected("txn_123".into(), hash.clone(), "validation error".into())
+            .expect("record failed");
+
+        let is_safe = store.is_retry_safe("txn_123", &hash).expect("check failed");
+        assert!(!is_safe);
+    }
+
+    #[test]
+    fn conflicted_transaction_with_same_payload_is_not_safe() {
+        let store = TransactionRecoveryStore::new();
+        let hash = test_payload_hash();
+
+        store
+            .record_conflicted("txn_123".into(), hash.clone(), "version mismatch".into())
+            .expect("record failed");
+
+        let is_safe = store.is_retry_safe("txn_123", &hash).expect("check failed");
+        assert!(!is_safe);
+    }
+
+    #[test]
+    fn record_unknown_transaction() {
+        let store = TransactionRecoveryStore::new();
+        let hash = test_payload_hash();
+
+        store
+            .record_unknown("txn_123".into(), hash)
+            .expect("record failed");
+
+        let status = store.get_status("txn_123").expect("get failed");
+        assert_eq!(status.status, TransactionStatus::Unknown);
+    }
+
+    #[test]
+    fn record_rejected_transaction() {
+        let store = TransactionRecoveryStore::new();
+        let hash = test_payload_hash();
+
+        store
+            .record_rejected(
+                "txn_123".into(),
+                hash,
+                "required field missing".into(),
+            )
+            .expect("record failed");
+
+        let status = store.get_status("txn_123").expect("get failed");
+        assert_eq!(status.status, TransactionStatus::Rejected);
+        assert!(status.error.is_some());
+    }
+
+    #[test]
+    fn record_conflicted_transaction() {
+        let store = TransactionRecoveryStore::new();
+        let hash = test_payload_hash();
+
+        store
+            .record_conflicted("txn_123".into(), hash, "concurrent write".into())
+            .expect("record failed");
+
+        let status = store.get_status("txn_123").expect("get failed");
+        assert_eq!(status.status, TransactionStatus::Conflicted);
+    }
+
+    #[test]
+    fn cleanup_removes_old_records() {
+        let store = TransactionRecoveryStore::new();
+        let hash = test_payload_hash();
+        let old_time = now() - 86400; // 1 day ago
+
+        store
+            .record_committed("txn_old".into(), hash.clone(), 1)
+            .expect("record failed");
+
+        // Manually insert an old record (normally would be done by recovery mechanism)
+        {
+            let mut records = store.records.write().unwrap();
+            if let Some(r) = records.get_mut("txn_old") {
+                r.recorded_at = old_time;
+            }
+        }
+
+        let cutoff = now() - 3600; // 1 hour ago
+        let deleted = store.cleanup_before(cutoff).expect("cleanup failed");
+        assert_eq!(deleted, 1);
+
+        // Old record should be gone
+        assert!(store.get_status("txn_old").is_err());
+    }
+
+    #[test]
+    fn payload_hash_is_deterministic() {
+        let hash1 = compute_payload_hash(b"test payload");
+        let hash2 = compute_payload_hash(b"test payload");
+        assert_eq!(hash1, hash2);
+
+        let hash3 = compute_payload_hash(b"different");
+        assert_ne!(hash1, hash3);
+    }
+
+    #[test]
+    fn transaction_record_includes_timestamps() {
+        let store = TransactionRecoveryStore::new();
+        let hash = test_payload_hash();
+
+        let before = now();
+        store
+            .record_committed("txn_123".into(), hash, 42)
+            .expect("record failed");
+        let after = now();
+
+        let status = store.get_status("txn_123").expect("get failed");
+        assert!(status.committed_at.is_some());
+        let committed = status.committed_at.unwrap();
+        assert!(committed >= before && committed <= after + 1);
+    }
+}

package/package.json

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