create-feltdb 0.4.17 → 0.5.0

package/dist/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.4.17';
+export const FELTDB_PACKAGE_VERSION = '0.5.0';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

package/dist/server-source/Cargo.lock

@@ -524,6 +524,7 @@ dependencies = [
  "tower-http",
  "tracing",
  "tracing-subscriber",
+ "uuid",
 ]
 
 [[package]]
@@ -1904,6 +1905,17 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 
+[[package]]
+name = "uuid"
+version = "1.25.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f053576934f05a761a402421fbbe3d425d9366f75f978806a037b3ca481abecc"
+dependencies = [
+ "getrandom 0.4.3",
+ "js-sys",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "valuable"
 version = "0.1.1"

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

@@ -21,3 +21,4 @@ tokio = { version = "1", features = ["macros", "net", "rt-multi-thread", "signal
 tower-http = { version = "0.6", features = ["cors", "limit", "trace"] }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+uuid = { version = "1.6", features = ["v4"] }

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

@@ -20,6 +20,8 @@ pub mod portable_bundle;
 pub mod principals;
 pub mod providers;
 pub mod releases;
+pub mod request_telemetry;
 pub mod sessions;
 pub mod tenancy;
+pub mod transaction_idempotency;
 pub mod versions;

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

@@ -0,0 +1,381 @@
+use std::sync::{Arc, Mutex};
+use std::time::{Instant, SystemTime};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+/// Request lifecycle telemetry: captures all timing and context for every /v1/ request.
+/// This is the production correctness contract for managed FeltDB concurrency.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RequestTelemetry {
+    pub request_id: String,
+    pub transaction_id: Option<String>,
+    pub application_id: String,
+    pub revision_id: String,
+
+    // Timing breakdown (milliseconds)
+    pub queue_wait_ms: u64,
+    pub lock_wait_ms: u64,
+    pub execution_ms: u64,
+    pub persistence_ms: u64,
+    pub total_ms: u64,
+
+    // Contention signals
+    pub lock_name: String,
+    pub queue_depth: usize,
+    pub max_queue_depth: usize,
+
+    // Cancellation state
+    pub deadline_ms: Option<u64>,
+    pub cancelled: bool,
+
+    // HTTP response
+    pub http_status: u16,
+    pub feltdb_code: String,
+    pub error_message: Option<String>,
+
+    // Resource tracking
+    pub orphaned_tasks: usize,
+    pub timestamp_ms: u64,
+}
+
+impl RequestTelemetry {
+    pub fn new(application_id: String, revision_id: String) -> Self {
+        let now = SystemTime::now()
+            .duration_since(SystemTime::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis() as u64;
+
+        Self {
+            request_id: Uuid::new_v4().to_string(),
+            transaction_id: None,
+            application_id,
+            revision_id,
+            queue_wait_ms: 0,
+            lock_wait_ms: 0,
+            execution_ms: 0,
+            persistence_ms: 0,
+            total_ms: 0,
+            lock_name: String::new(),
+            queue_depth: 0,
+            max_queue_depth: 0,
+            deadline_ms: None,
+            cancelled: false,
+            http_status: 200,
+            feltdb_code: "OK".to_string(),
+            error_message: None,
+            orphaned_tasks: 0,
+            timestamp_ms: now,
+        }
+    }
+
+    pub fn with_transaction_id(mut self, tx_id: String) -> Self {
+        self.transaction_id = Some(tx_id);
+        self
+    }
+}
+
+/// Request telemetry store: thread-safe collection of all request measurements.
+/// Enables production diagnostics without external observability dependency.
+pub struct RequestTelemetryStore {
+    records: Arc<Mutex<Vec<RequestTelemetry>>>,
+    max_capacity: usize,
+}
+
+impl RequestTelemetryStore {
+    pub fn new(max_capacity: usize) -> Self {
+        Self {
+            records: Arc::new(Mutex::new(Vec::with_capacity(max_capacity))),
+            max_capacity,
+        }
+    }
+
+    pub fn record(&self, telemetry: RequestTelemetry) {
+        if let Ok(mut records) = self.records.lock() {
+            records.push(telemetry);
+            // Keep only the most recent records
+            if records.len() > self.max_capacity {
+                let to_remove = records.len() - self.max_capacity;
+                records.drain(0..to_remove);
+            }
+        }
+    }
+
+    pub fn all(&self) -> Vec<RequestTelemetry> {
+        self.records
+            .lock()
+            .map(|r| r.clone())
+            .unwrap_or_default()
+    }
+
+    pub fn recent(&self, count: usize) -> Vec<RequestTelemetry> {
+        self.records
+            .lock()
+            .map(|r| {
+                let start = if r.len() > count { r.len() - count } else { 0 };
+                r[start..].to_vec()
+            })
+            .unwrap_or_default()
+    }
+
+    pub fn by_transaction_id(&self, tx_id: &str) -> Vec<RequestTelemetry> {
+        self.records
+            .lock()
+            .map(|r| r.iter().filter(|t| t.transaction_id.as_deref() == Some(tx_id)).cloned().collect())
+            .unwrap_or_default()
+    }
+
+    pub fn statistics(&self) -> TelemetryStatistics {
+        if let Ok(records) = self.records.lock() {
+            let mut stats = TelemetryStatistics::default();
+            let mut total_latencies = Vec::new();
+            let mut queue_waits = Vec::new();
+            let mut lock_waits = Vec::new();
+            let mut execution_times = Vec::new();
+            let mut persistence_times = Vec::new();
+
+            for telemetry in records.iter() {
+                total_latencies.push(telemetry.total_ms);
+                queue_waits.push(telemetry.queue_wait_ms);
+                lock_waits.push(telemetry.lock_wait_ms);
+                execution_times.push(telemetry.execution_ms);
+                persistence_times.push(telemetry.persistence_ms);
+                stats.total_requests += 1;
+                stats.max_queue_depth = stats.max_queue_depth.max(telemetry.max_queue_depth);
+                stats.total_orphaned_tasks += telemetry.orphaned_tasks;
+
+                match telemetry.http_status {
+                    200..=299 => stats.successful_requests += 1,
+                    400..=499 => stats.client_errors += 1,
+                    500..=599 => stats.server_errors += 1,
+                    _ => {}
+                }
+
+                if telemetry.cancelled {
+                    stats.cancelled_requests += 1;
+                }
+
+                if telemetry.feltdb_code == "CONFLICT" {
+                    stats.conflicts += 1;
+                } else if telemetry.feltdb_code == "TOO_BUSY" {
+                    stats.too_busy_count += 1;
+                }
+            }
+
+            // Calculate percentiles
+            if !total_latencies.is_empty() {
+                total_latencies.sort();
+                stats.latency_p50_ms = calculate_percentile(&total_latencies, 50);
+                stats.latency_p95_ms = calculate_percentile(&total_latencies, 95);
+                stats.latency_p99_ms = calculate_percentile(&total_latencies, 99);
+                stats.latency_max_ms = *total_latencies.last().unwrap_or(&0);
+            }
+
+            if !queue_waits.is_empty() {
+                queue_waits.sort();
+                stats.queue_wait_p99_ms = calculate_percentile(&queue_waits, 99);
+                stats.queue_wait_max_ms = *queue_waits.last().unwrap_or(&0);
+            }
+
+            if !lock_waits.is_empty() {
+                lock_waits.sort();
+                stats.lock_wait_p99_ms = calculate_percentile(&lock_waits, 99);
+                stats.lock_wait_max_ms = *lock_waits.last().unwrap_or(&0);
+            }
+
+            if !execution_times.is_empty() {
+                stats.execution_p99_ms = calculate_percentile(&execution_times, 99);
+            }
+
+            if !persistence_times.is_empty() {
+                stats.persistence_p99_ms = calculate_percentile(&persistence_times, 99);
+            }
+
+            stats
+        } else {
+            TelemetryStatistics::default()
+        }
+    }
+
+    pub fn clear(&self) {
+        if let Ok(mut records) = self.records.lock() {
+            records.clear();
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Default)]
+pub struct TelemetryStatistics {
+    pub total_requests: usize,
+    pub successful_requests: usize,
+    pub client_errors: usize,
+    pub server_errors: usize,
+    pub cancelled_requests: usize,
+    pub conflicts: usize,
+    pub too_busy_count: usize,
+
+    pub latency_p50_ms: u64,
+    pub latency_p95_ms: u64,
+    pub latency_p99_ms: u64,
+    pub latency_max_ms: u64,
+
+    pub queue_wait_p99_ms: u64,
+    pub queue_wait_max_ms: u64,
+
+    pub lock_wait_p99_ms: u64,
+    pub lock_wait_max_ms: u64,
+
+    pub execution_p99_ms: u64,
+    pub persistence_p99_ms: u64,
+
+    pub max_queue_depth: usize,
+    pub total_orphaned_tasks: usize,
+}
+
+fn calculate_percentile(sorted: &[u64], percentile: u32) -> u64 {
+    if sorted.is_empty() {
+        return 0;
+    }
+    let index = ((sorted.len() as u32 * percentile / 100).max(1) - 1) as usize;
+    sorted[index.min(sorted.len() - 1)]
+}
+
+/// Request lifecycle timer: tracks all phases of request execution.
+pub struct RequestTimer {
+    start: Instant,
+    queue_start: Option<Instant>,
+    lock_start: Option<Instant>,
+    execution_start: Option<Instant>,
+    persistence_start: Option<Instant>,
+}
+
+impl RequestTimer {
+    pub fn new() -> Self {
+        Self {
+            start: Instant::now(),
+            queue_start: None,
+            lock_start: None,
+            execution_start: None,
+            persistence_start: None,
+        }
+    }
+
+    pub fn begin_queue_wait(&mut self) {
+        self.queue_start = Some(Instant::now());
+    }
+
+    pub fn end_queue_wait(&mut self) -> u64 {
+        self.queue_start
+            .take()
+            .map(|s| s.elapsed().as_millis() as u64)
+            .unwrap_or(0)
+    }
+
+    pub fn begin_lock_wait(&mut self) {
+        self.lock_start = Some(Instant::now());
+    }
+
+    pub fn end_lock_wait(&mut self) -> u64 {
+        self.lock_start
+            .take()
+            .map(|s| s.elapsed().as_millis() as u64)
+            .unwrap_or(0)
+    }
+
+    pub fn begin_execution(&mut self) {
+        self.execution_start = Some(Instant::now());
+    }
+
+    pub fn end_execution(&mut self) -> u64 {
+        self.execution_start
+            .take()
+            .map(|s| s.elapsed().as_millis() as u64)
+            .unwrap_or(0)
+    }
+
+    pub fn begin_persistence(&mut self) {
+        self.persistence_start = Some(Instant::now());
+    }
+
+    pub fn end_persistence(&mut self) -> u64 {
+        self.persistence_start
+            .take()
+            .map(|s| s.elapsed().as_millis() as u64)
+            .unwrap_or(0)
+    }
+
+    pub fn total_elapsed(&self) -> u64 {
+        self.start.elapsed().as_millis() as u64
+    }
+}
+
+impl Default for RequestTimer {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_telemetry_creation() {
+        let telemetry = RequestTelemetry::new("app-1".to_string(), "rev-1".to_string());
+        assert!(!telemetry.request_id.is_empty());
+        assert_eq!(telemetry.application_id, "app-1");
+        assert_eq!(telemetry.revision_id, "rev-1");
+    }
+
+    #[test]
+    fn test_telemetry_store() {
+        let store = RequestTelemetryStore::new(100);
+        let mut telemetry = RequestTelemetry::new("app".to_string(), "rev".to_string());
+        telemetry.total_ms = 50;
+        telemetry.http_status = 200;
+
+        store.record(telemetry.clone());
+        let all = store.all();
+        assert_eq!(all.len(), 1);
+        assert_eq!(all[0].total_ms, 50);
+    }
+
+    #[test]
+    fn test_timer_lifecycle() {
+        let mut timer = RequestTimer::new();
+
+        timer.begin_queue_wait();
+        std::thread::sleep(Duration::from_millis(10));
+        let queue_ms = timer.end_queue_wait();
+        assert!(queue_ms >= 10);
+
+        timer.begin_lock_wait();
+        std::thread::sleep(Duration::from_millis(5));
+        let lock_ms = timer.end_lock_wait();
+        assert!(lock_ms >= 5);
+
+        let total = timer.total_elapsed();
+        assert!(total >= 15);
+    }
+
+    #[test]
+    fn test_statistics_calculation() {
+        let store = RequestTelemetryStore::new(1000);
+
+        // Record 101 requests with increasing latency
+        for i in 0..101 {
+            let mut telemetry = RequestTelemetry::new("app".to_string(), "rev".to_string());
+            telemetry.total_ms = (i * 10) as u64; // 0, 10, 20, ..., 1000
+            telemetry.http_status = if i % 10 == 0 { 409 } else { 200 };
+            if i % 10 == 0 {
+                telemetry.feltdb_code = "CONFLICT".to_string();
+            }
+            store.record(telemetry);
+        }
+
+        let stats = store.statistics();
+        assert_eq!(stats.total_requests, 101);
+        assert!(stats.latency_p50_ms > 0);
+        assert!(stats.latency_p99_ms > stats.latency_p50_ms);
+        assert_eq!(stats.conflicts, 11);
+    }
+}

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

@@ -0,0 +1,280 @@
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+/// Durable transaction idempotency: prevents re-execution of already-committed transactions.
+/// Every committed transaction is stored with its result. If the client retries with the
+/// same transaction_id + payload hash, the server returns the original result without re-executing.
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CommittedTransaction {
+    pub transaction_id: String,
+    pub transaction_hash: String,
+    pub status: TransactionStatus,
+    pub committed_result: serde_json::Value,
+    pub commit_metadata: CommitMetadata,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub enum TransactionStatus {
+    #[serde(rename = "COMMITTED")]
+    Committed,
+    #[serde(rename = "CONFLICT")]
+    Conflict,
+    #[serde(rename = "VALIDATION_FAILED")]
+    ValidationFailed,
+    #[serde(rename = "INTERNAL_ERROR")]
+    InternalError,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CommitMetadata {
+    pub timestamp_ms: u64,
+    pub revision_id: String,
+    pub application_id: String,
+    pub state_before: u64,
+    pub state_after: u64,
+    pub retry_count: usize,
+}
+
+pub struct TransactionIdempotencyStore {
+    // Map: transaction_id -> list of committed transactions (to detect hash mismatches)
+    store: Arc<Mutex<HashMap<String, Vec<CommittedTransaction>>>>,
+    max_per_transaction: usize,
+}
+
+impl TransactionIdempotencyStore {
+    pub fn new(max_per_transaction: usize) -> Self {
+        Self {
+            store: Arc::new(Mutex::new(HashMap::new())),
+            max_per_transaction,
+        }
+    }
+
+    /// Record a committed transaction for idempotency.
+    /// If the same transaction_id is seen again with the same hash, return the original result.
+    /// If the same transaction_id is seen with a different hash, return CONFLICT.
+    pub fn record_committed(
+        &self,
+        transaction_id: String,
+        transaction_hash: String,
+        status: TransactionStatus,
+        result: serde_json::Value,
+        metadata: CommitMetadata,
+    ) {
+        if let Ok(mut store) = self.store.lock() {
+            let tx_id_clone = transaction_id.clone();
+            let committed = CommittedTransaction {
+                transaction_id,
+                transaction_hash,
+                status,
+                committed_result: result,
+                commit_metadata: metadata,
+            };
+
+            store
+                .entry(tx_id_clone.clone())
+                .or_insert_with(Vec::new)
+                .push(committed);
+
+            // Keep only the most recent attempts
+            if let Some(entries) = store.get_mut(&tx_id_clone) {
+                if entries.len() > self.max_per_transaction {
+                    let to_remove = entries.len() - self.max_per_transaction;
+                    entries.drain(0..to_remove);
+                }
+            }
+        }
+    }
+
+    /// Check if a transaction has been seen before.
+    /// Returns:
+    /// - Some(Ok(result)) if same transaction_id + same hash (idempotent replay)
+    /// - Some(Err("CONFLICT")) if same transaction_id + different hash (reuse with different payload)
+    /// - None if this is a new transaction_id
+    pub fn check_idempotent(
+        &self,
+        transaction_id: &str,
+        transaction_hash: &str,
+    ) -> Option<Result<serde_json::Value, String>> {
+        self.store
+            .lock()
+            .ok()
+            .and_then(|store| store.get(transaction_id).map(|entries| entries.clone()))
+            .and_then(|entries| {
+                if entries.is_empty() {
+                    return None;
+                }
+
+                let first_entry = &entries[0];
+
+                // If hashes match, return the original result
+                if first_entry.transaction_hash == transaction_hash {
+                    return Some(Ok(first_entry.committed_result.clone()));
+                }
+
+                // If hashes differ, it's a conflict (transaction ID reused with different payload)
+                Some(Err(format!(
+                    "Transaction ID {} reused with different payload",
+                    transaction_id
+                )))
+            })
+    }
+
+    /// Get all committed transactions for a transaction_id
+    pub fn get_history(&self, transaction_id: &str) -> Vec<CommittedTransaction> {
+        self.store
+            .lock()
+            .ok()
+            .and_then(|store| store.get(transaction_id).cloned())
+            .unwrap_or_default()
+    }
+
+    /// Clear all idempotency records (for testing)
+    pub fn clear(&self) {
+        if let Ok(mut store) = self.store.lock() {
+            store.clear();
+        }
+    }
+
+    /// Get statistics about idempotency store
+    pub fn statistics(&self) -> IdempotencyStatistics {
+        self.store
+            .lock()
+            .ok()
+            .map(|store| {
+                let total_transactions = store.len();
+                let total_entries = store.values().map(|v| v.len()).sum();
+                let replay_protected = store
+                    .values()
+                    .filter(|entries| !entries.is_empty() && entries[0].status == TransactionStatus::Committed)
+                    .count();
+
+                IdempotencyStatistics {
+                    total_transaction_ids: total_transactions,
+                    total_committed_entries: total_entries,
+                    replay_protected_count: replay_protected,
+                }
+            })
+            .unwrap_or_default()
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Default)]
+pub struct IdempotencyStatistics {
+    pub total_transaction_ids: usize,
+    pub total_committed_entries: usize,
+    pub replay_protected_count: usize,
+}
+
+/// Compute a hash of a transaction request for idempotency detection.
+pub fn hash_transaction_request(request: &serde_json::Value) -> String {
+    let mut hasher = Sha256::new();
+    let json_str = serde_json::to_string(request).unwrap_or_default();
+    hasher.update(json_str.as_bytes());
+    format!("{:x}", hasher.finalize())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_idempotency_store_same_hash() {
+        let store = TransactionIdempotencyStore::new(10);
+        let tx_id = "tx-123".to_string();
+        let tx_hash = "hash-abc".to_string();
+        let result = serde_json::json!({ "status": "committed" });
+
+        store.record_committed(
+            tx_id.clone(),
+            tx_hash.clone(),
+            TransactionStatus::Committed,
+            result.clone(),
+            CommitMetadata {
+                timestamp_ms: 1000,
+                revision_id: "rev-1".to_string(),
+                application_id: "app-1".to_string(),
+                state_before: 1,
+                state_after: 2,
+                retry_count: 0,
+            },
+        );
+
+        // First replay should return the same result
+        let replay = store.check_idempotent(&tx_id, &tx_hash);
+        assert!(replay.is_some());
+        assert!(replay.unwrap().is_ok());
+    }
+
+    #[test]
+    fn test_idempotency_store_different_hash() {
+        let store = TransactionIdempotencyStore::new(10);
+        let tx_id = "tx-456".to_string();
+        let tx_hash_1 = "hash-1".to_string();
+        let tx_hash_2 = "hash-2".to_string();
+        let result = serde_json::json!({ "status": "committed" });
+
+        store.record_committed(
+            tx_id.clone(),
+            tx_hash_1.clone(),
+            TransactionStatus::Committed,
+            result,
+            CommitMetadata {
+                timestamp_ms: 1000,
+                revision_id: "rev-1".to_string(),
+                application_id: "app-1".to_string(),
+                state_before: 1,
+                state_after: 2,
+                retry_count: 0,
+            },
+        );
+
+        // Replay with different hash should fail
+        let replay = store.check_idempotent(&tx_id, &tx_hash_2);
+        assert!(replay.is_some());
+        assert!(replay.unwrap().is_err());
+    }
+
+    #[test]
+    fn test_hash_transaction_request() {
+        let request1 = serde_json::json!({ "id": "test", "value": 123 });
+        let request2 = serde_json::json!({ "id": "test", "value": 123 });
+        let request3 = serde_json::json!({ "id": "test", "value": 456 });
+
+        let hash1 = hash_transaction_request(&request1);
+        let hash2 = hash_transaction_request(&request2);
+        let hash3 = hash_transaction_request(&request3);
+
+        assert_eq!(hash1, hash2); // Same content = same hash
+        assert_ne!(hash1, hash3); // Different content = different hash
+    }
+
+    #[test]
+    fn test_idempotency_statistics() {
+        let store = TransactionIdempotencyStore::new(10);
+
+        for i in 0..5 {
+            store.record_committed(
+                format!("tx-{}", i),
+                "hash-abc".to_string(),
+                TransactionStatus::Committed,
+                serde_json::json!({}),
+                CommitMetadata {
+                    timestamp_ms: 1000,
+                    revision_id: "rev-1".to_string(),
+                    application_id: "app-1".to_string(),
+                    state_before: 1,
+                    state_after: 2,
+                    retry_count: 0,
+                },
+            );
+        }
+
+        let stats = store.statistics();
+        assert_eq!(stats.total_transaction_ids, 5);
+        assert_eq!(stats.total_committed_entries, 5);
+        assert_eq!(stats.replay_protected_count, 5);
+    }
+}

package/package.json

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