aura_core/effects/
system.rs

1//! System Effects Trait and Error Types
2//!
3//! This module contains the SystemEffects trait definition and SystemError type
4//! for system-level operations including logging, monitoring, and configuration.
5//! This trait is part of the core effect system and provides foundational
6//! system operations used across all layers.
7//!
8//! # Effect Classification
9//!
10//! - **Category**: Infrastructure Effect
11//! - **Implementation**: `aura-effects` (Layer 3)
12//! - **Usage**: System-level operations (logging, monitoring, configuration)
13//!
14//! This is an infrastructure effect providing generic OS-level system operations
15//! with no Aura-specific semantics. Implementations should provide stateless
16//! handlers for logging, configuration management, and system monitoring.
17
18use async_trait::async_trait;
19use std::collections::HashMap;
20
21/// System effect operations error
22#[derive(Debug, thiserror::Error, serde::Serialize, serde::Deserialize)]
23pub enum SystemError {
24    /// Service is unavailable
25    #[error("System service unavailable")]
26    ServiceUnavailable,
27
28    /// Invalid configuration parameter
29    #[error("Invalid configuration: {key}={value}")]
30    InvalidConfiguration { key: String, value: String },
31
32    /// Operation failed
33    #[error("System operation failed: {message}")]
34    OperationFailed { message: String },
35
36    /// Permission denied
37    #[error("Permission denied for operation: {operation}")]
38    PermissionDenied { operation: String },
39
40    /// Resource not found
41    #[error("Resource not found: {resource}")]
42    ResourceNotFound { resource: String },
43
44    /// Resource exhausted
45    #[error("Resource exhausted: {resource}")]
46    ResourceExhausted { resource: String },
47}
48
49impl From<crate::AuraError> for SystemError {
50    fn from(e: crate::AuraError) -> Self {
51        SystemError::OperationFailed {
52            message: e.to_string(),
53        }
54    }
55}
56
57/// System effects interface for logging, monitoring, and configuration
58///
59/// This trait provides system-level operations for:
60/// - Logging and audit trails
61/// - System monitoring and health checks
62/// - Configuration management
63/// - System metrics and statistics
64/// - Component lifecycle management
65#[async_trait]
66pub trait SystemEffects: Send + Sync {
67    /// Log a message at the specified level
68    async fn log(&self, level: &str, component: &str, message: &str) -> Result<(), SystemError>;
69
70    /// Log a message with additional context
71    async fn log_with_context(
72        &self,
73        level: &str,
74        component: &str,
75        message: &str,
76        context: HashMap<String, String>,
77    ) -> Result<(), SystemError>;
78
79    /// Get system information and status
80    async fn get_system_info(&self) -> Result<HashMap<String, String>, SystemError>;
81
82    /// Set a configuration value
83    async fn set_config(&self, key: &str, value: &str) -> Result<(), SystemError>;
84
85    /// Get a configuration value
86    async fn get_config(&self, key: &str) -> Result<String, SystemError>;
87
88    /// Perform a health check
89    async fn health_check(&self) -> Result<bool, SystemError>;
90
91    /// Get system metrics
92    async fn get_metrics(&self) -> Result<HashMap<String, f64>, SystemError>;
93
94    /// Restart a system component
95    async fn restart_component(&self, component: &str) -> Result<(), SystemError>;
96
97    /// Shutdown the system gracefully
98    async fn shutdown(&self) -> Result<(), SystemError>;
99}
aura_core/effects/system.rs

aura_core/effects/
system.rs
