@feltdb/core 0.5.7 → 0.6.1

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

@@ -0,0 +1,413 @@
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+/// Engine version for FeltDB.
+pub const ENGINE_VERSION: &str = "0.2.0";
+
+/// API protocol version for compatibility tracking.
+pub const PROTOCOL_VERSION: u32 = 1;
+
+/// Storage format identifier.
+pub const STORAGE_FORMAT: &str = "feltdb-v2";
+
+/// Environment type.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum Environment {
+    Dev,
+    Staging,
+    Prod,
+}
+
+/// Health status for subsystems.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum HealthStatus {
+    Healthy,
+    Degraded,
+    Unhealthy,
+}
+
+impl HealthStatus {
+    pub fn is_healthy(&self) -> bool {
+        *self == HealthStatus::Healthy
+    }
+}
+
+/// Recovery status and health.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RecoveryStatus {
+    /// Overall recovery system health.
+    pub status: HealthStatus,
+
+    /// Transaction recovery health.
+    pub transaction_recovery: HealthStatus,
+
+    /// Durable operation recovery health.
+    pub durable_operations: HealthStatus,
+
+    /// Last recovery check timestamp (unix seconds).
+    pub last_check_at: u64,
+
+    /// Details about any issues (empty if healthy).
+    pub issues: Vec<String>,
+
+    /// Metrics: count of operations awaiting recovery.
+    pub pending_recovery_count: usize,
+
+    /// Metrics: count of failed recovery attempts (recent).
+    pub failed_recovery_attempts: usize,
+}
+
+impl RecoveryStatus {
+    pub fn is_healthy(&self) -> bool {
+        self.status.is_healthy()
+    }
+}
+
+/// Diagnostic information about server health and status.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiagnosticsReport {
+    /// FeltDB engine version.
+    pub engine_version: String,
+
+    /// Git commit hash of this deployment.
+    pub server_commit: String,
+
+    /// API protocol version.
+    pub protocol_version: u32,
+
+    /// Storage format identifier.
+    pub storage_format: String,
+
+    /// Deployment environment.
+    pub environment: Environment,
+
+    /// Overall server health status.
+    pub status: HealthStatus,
+
+    /// Recovery system status and health.
+    pub recovery: RecoveryStatus,
+
+    /// Uptime in seconds since server start.
+    pub uptime_seconds: u64,
+
+    /// Timestamp of this report (unix seconds).
+    pub reported_at: u64,
+
+    /// Optional detailed metrics by subsystem.
+    pub subsystems: HashMap<String, SubsystemMetrics>,
+}
+
+/// Metrics for a single subsystem.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SubsystemMetrics {
+    pub name: String,
+    pub status: HealthStatus,
+    pub request_count: u64,
+    pub error_count: u64,
+    pub avg_latency_ms: f64,
+    pub details: HashMap<String, serde_json::Value>,
+}
+
+/// Diagnostics collector and reporter.
+pub struct DiagnosticsCollector {
+    engine_version: String,
+    server_commit: String,
+    protocol_version: u32,
+    storage_format: String,
+    environment: Environment,
+    start_time: u64,
+}
+
+impl DiagnosticsCollector {
+    /// Creates a new diagnostics collector.
+    pub fn new(
+        server_commit: String,
+        environment: Environment,
+    ) -> Self {
+        Self {
+            engine_version: ENGINE_VERSION.to_string(),
+            server_commit,
+            protocol_version: PROTOCOL_VERSION,
+            storage_format: STORAGE_FORMAT.to_string(),
+            environment,
+            start_time: now(),
+        }
+    }
+
+    /// Generates a diagnostics report.
+    pub fn collect_report(
+        &self,
+        recovery_status: RecoveryStatus,
+    ) -> DiagnosticsReport {
+        let uptime = now() - self.start_time;
+        let overall_status = if recovery_status.status.is_healthy() {
+            HealthStatus::Healthy
+        } else {
+            HealthStatus::Degraded
+        };
+
+        DiagnosticsReport {
+            engine_version: self.engine_version.clone(),
+            server_commit: self.server_commit.clone(),
+            protocol_version: self.protocol_version,
+            storage_format: self.storage_format.clone(),
+            environment: self.environment,
+            status: overall_status,
+            recovery: recovery_status,
+            uptime_seconds: uptime,
+            reported_at: now(),
+            subsystems: HashMap::new(),
+        }
+    }
+
+    /// Adds subsystem metrics to the report.
+    pub fn add_subsystem_metrics(
+        report: &mut DiagnosticsReport,
+        name: String,
+        status: HealthStatus,
+        request_count: u64,
+        error_count: u64,
+        avg_latency_ms: f64,
+        details: HashMap<String, serde_json::Value>,
+    ) {
+        report.subsystems.insert(
+            name.clone(),
+            SubsystemMetrics {
+                name,
+                status,
+                request_count,
+                error_count,
+                avg_latency_ms,
+                details,
+            },
+        );
+    }
+}
+
+impl Default for RecoveryStatus {
+    fn default() -> Self {
+        Self {
+            status: HealthStatus::Healthy,
+            transaction_recovery: HealthStatus::Healthy,
+            durable_operations: HealthStatus::Healthy,
+            last_check_at: now(),
+            issues: vec![],
+            pending_recovery_count: 0,
+            failed_recovery_attempts: 0,
+        }
+    }
+}
+
+/// Builder for RecoveryStatus for easy construction.
+pub struct RecoveryStatusBuilder {
+    status: HealthStatus,
+    transaction_recovery: HealthStatus,
+    durable_operations: HealthStatus,
+    issues: Vec<String>,
+    pending_recovery_count: usize,
+    failed_recovery_attempts: usize,
+}
+
+impl RecoveryStatusBuilder {
+    pub fn new() -> Self {
+        Self {
+            status: HealthStatus::Healthy,
+            transaction_recovery: HealthStatus::Healthy,
+            durable_operations: HealthStatus::Healthy,
+            issues: vec![],
+            pending_recovery_count: 0,
+            failed_recovery_attempts: 0,
+        }
+    }
+
+    pub fn with_transaction_recovery(mut self, status: HealthStatus) -> Self {
+        self.transaction_recovery = status;
+        self
+    }
+
+    pub fn with_durable_operations(mut self, status: HealthStatus) -> Self {
+        self.durable_operations = status;
+        self
+    }
+
+    pub fn with_issue(mut self, issue: String) -> Self {
+        self.issues.push(issue);
+        if self.status == HealthStatus::Healthy {
+            self.status = HealthStatus::Degraded;
+        }
+        self
+    }
+
+    pub fn with_pending_recovery_count(mut self, count: usize) -> Self {
+        self.pending_recovery_count = count;
+        self
+    }
+
+    pub fn with_failed_attempts(mut self, count: usize) -> Self {
+        self.failed_recovery_attempts = count;
+        self
+    }
+
+    pub fn build(mut self) -> RecoveryStatus {
+        // Determine overall status from subsystems
+        if self.transaction_recovery != HealthStatus::Healthy
+            || self.durable_operations != HealthStatus::Healthy
+        {
+            self.status = HealthStatus::Degraded;
+        }
+
+        RecoveryStatus {
+            status: self.status,
+            transaction_recovery: self.transaction_recovery,
+            durable_operations: self.durable_operations,
+            last_check_at: now(),
+            issues: self.issues,
+            pending_recovery_count: self.pending_recovery_count,
+            failed_recovery_attempts: self.failed_recovery_attempts,
+        }
+    }
+}
+
+impl Default for RecoveryStatusBuilder {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+fn now() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn create_diagnostics_collector() {
+        let collector = DiagnosticsCollector::new(
+            "abc123def456".to_string(),
+            Environment::Prod,
+        );
+
+        assert_eq!(collector.engine_version, ENGINE_VERSION);
+        assert_eq!(collector.protocol_version, PROTOCOL_VERSION);
+        assert_eq!(collector.storage_format, STORAGE_FORMAT);
+        assert_eq!(collector.environment, Environment::Prod);
+    }
+
+    #[test]
+    fn collect_report_includes_uptime() {
+        let collector = DiagnosticsCollector::new(
+            "abc123def456".to_string(),
+            Environment::Staging,
+        );
+
+        let recovery_status = RecoveryStatus::default();
+        let report = collector.collect_report(recovery_status);
+
+        assert_eq!(report.engine_version, ENGINE_VERSION);
+        let _uptime = report.uptime_seconds;
+    }
+
+    #[test]
+    fn recovery_status_builder() {
+        let recovery = RecoveryStatusBuilder::new()
+            .with_transaction_recovery(HealthStatus::Healthy)
+            .with_durable_operations(HealthStatus::Degraded)
+            .with_issue("durable operations slow".to_string())
+            .with_pending_recovery_count(5)
+            .build();
+
+        assert_eq!(recovery.transaction_recovery, HealthStatus::Healthy);
+        assert_eq!(recovery.durable_operations, HealthStatus::Degraded);
+        assert_eq!(recovery.status, HealthStatus::Degraded);
+        assert_eq!(recovery.pending_recovery_count, 5);
+        assert!(recovery.issues.contains(&"durable operations slow".to_string()));
+    }
+
+    #[test]
+    fn health_status_propagates_to_overall() {
+        let recovery = RecoveryStatusBuilder::new()
+            .with_transaction_recovery(HealthStatus::Unhealthy)
+            .build();
+
+        assert_eq!(recovery.status, HealthStatus::Degraded);
+    }
+
+    #[test]
+    fn environment_serialization() {
+        let envs = vec![
+            Environment::Dev,
+            Environment::Staging,
+            Environment::Prod,
+        ];
+
+        for env in envs {
+            let json = serde_json::to_string(&env).expect("serialize failed");
+            let deserialized: Environment =
+                serde_json::from_str(&json).expect("deserialize failed");
+            assert_eq!(env, deserialized);
+        }
+    }
+
+    #[test]
+    fn diagnostics_report_serialization() {
+        let collector = DiagnosticsCollector::new(
+            "abc123def456".to_string(),
+            Environment::Prod,
+        );
+
+        let recovery_status = RecoveryStatusBuilder::new()
+            .with_pending_recovery_count(3)
+            .build();
+
+        let report = collector.collect_report(recovery_status);
+        let json = serde_json::to_string(&report).expect("serialize failed");
+        let deserialized: DiagnosticsReport =
+            serde_json::from_str(&json).expect("deserialize failed");
+
+        assert_eq!(deserialized.engine_version, report.engine_version);
+        assert_eq!(deserialized.server_commit, report.server_commit);
+        assert_eq!(deserialized.recovery.pending_recovery_count, 3);
+    }
+
+    #[test]
+    fn add_subsystem_metrics() {
+        let collector = DiagnosticsCollector::new(
+            "abc123def456".to_string(),
+            Environment::Dev,
+        );
+
+        let mut report = collector.collect_report(RecoveryStatus::default());
+        let mut details = HashMap::new();
+        details.insert("cached_items".to_string(), serde_json::json!(1024));
+
+        DiagnosticsCollector::add_subsystem_metrics(
+            &mut report,
+            "cache".to_string(),
+            HealthStatus::Healthy,
+            10000,
+            5,
+            1.2,
+            details,
+        );
+
+        assert!(report.subsystems.contains_key("cache"));
+        let cache_metrics = &report.subsystems["cache"];
+        assert_eq!(cache_metrics.request_count, 10000);
+        assert_eq!(cache_metrics.error_count, 5);
+        assert_eq!(cache_metrics.avg_latency_ms, 1.2);
+    }
+
+    #[test]
+    fn default_recovery_status_is_healthy() {
+        let recovery = RecoveryStatus::default();
+        assert_eq!(recovery.status, HealthStatus::Healthy);
+        assert!(recovery.is_healthy());
+    }
+}