Skip to main content

acton_service_core/
error.rs

1//! Driver-independent structured storage errors.
2use std::fmt;
3/// Database operation being performed when the error occurred
4#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
5pub enum DatabaseOperation {
6    /// Establishing a database connection
7    Connect,
8    /// Executing a query
9    Query,
10    /// Inserting records
11    Insert,
12    /// Updating records
13    Update,
14    /// Deleting records
15    Delete,
16    /// Transaction operations (begin, commit, rollback)
17    Transaction,
18    /// Syncing data (e.g., Turso embedded replica sync)
19    Sync,
20    /// Running database migrations
21    Migration,
22    /// Acquiring a connection from the pool
23    PoolAcquire,
24}
25
26impl fmt::Display for DatabaseOperation {
27    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
28        match self {
29            Self::Connect => write!(f, "connect"),
30            Self::Query => write!(f, "query"),
31            Self::Insert => write!(f, "insert"),
32            Self::Update => write!(f, "update"),
33            Self::Delete => write!(f, "delete"),
34            Self::Transaction => write!(f, "transaction"),
35            Self::Sync => write!(f, "sync"),
36            Self::Migration => write!(f, "migration"),
37            Self::PoolAcquire => write!(f, "pool_acquire"),
38        }
39    }
40}
41
42/// Category of database error
43#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
44pub enum DatabaseErrorKind {
45    /// Failed to establish connection
46    ConnectionFailed,
47    /// Record not found
48    NotFound,
49    /// Constraint violation (unique, foreign key, check)
50    ConstraintViolation,
51    /// Query execution failed
52    QueryFailed,
53    /// Transaction failed (begin, commit, or rollback)
54    TransactionFailed,
55    /// Type conversion error
56    TypeConversion,
57    /// Sync operation failed (Turso specific)
58    SyncFailed,
59    /// Configuration error
60    Configuration,
61    /// Operation timed out
62    Timeout,
63    /// Permission denied
64    PermissionDenied,
65    /// Connection pool exhausted
66    PoolExhausted,
67    /// Other/unknown error
68    Other,
69}
70
71impl fmt::Display for DatabaseErrorKind {
72    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
73        match self {
74            Self::ConnectionFailed => write!(f, "connection_failed"),
75            Self::NotFound => write!(f, "not_found"),
76            Self::ConstraintViolation => write!(f, "constraint_violation"),
77            Self::QueryFailed => write!(f, "query_failed"),
78            Self::TransactionFailed => write!(f, "transaction_failed"),
79            Self::TypeConversion => write!(f, "type_conversion"),
80            Self::SyncFailed => write!(f, "sync_failed"),
81            Self::Configuration => write!(f, "configuration"),
82            Self::Timeout => write!(f, "timeout"),
83            Self::PermissionDenied => write!(f, "permission_denied"),
84            Self::PoolExhausted => write!(f, "pool_exhausted"),
85            Self::Other => write!(f, "other"),
86        }
87    }
88}
89
90/// Structured database error with operation context
91#[derive(Debug, Clone, PartialEq, Eq)]
92pub struct DatabaseError {
93    /// The operation being performed when the error occurred
94    pub operation: DatabaseOperation,
95    /// The category of error
96    pub kind: DatabaseErrorKind,
97    /// Human-readable error message
98    pub message: String,
99    /// Additional context (e.g., table name, query fragment)
100    pub context: Option<String>,
101}
102
103impl DatabaseError {
104    /// Create a new database error
105    pub fn new(
106        operation: DatabaseOperation,
107        kind: DatabaseErrorKind,
108        message: impl Into<String>,
109    ) -> Self {
110        Self {
111            operation,
112            kind,
113            message: message.into(),
114            context: None,
115        }
116    }
117
118    /// Create a new database error with context
119    pub fn with_context(
120        operation: DatabaseOperation,
121        kind: DatabaseErrorKind,
122        message: impl Into<String>,
123        context: impl Into<String>,
124    ) -> Self {
125        Self {
126            operation,
127            kind,
128            message: message.into(),
129            context: Some(context.into()),
130        }
131    }
132
133    /// Create a "not found" error
134    pub fn not_found(operation: DatabaseOperation, message: impl Into<String>) -> Self {
135        Self::new(operation, DatabaseErrorKind::NotFound, message)
136    }
137
138    /// Create a connection failed error
139    pub fn connection_failed(message: impl Into<String>) -> Self {
140        Self::new(
141            DatabaseOperation::Connect,
142            DatabaseErrorKind::ConnectionFailed,
143            message,
144        )
145    }
146
147    /// Create a constraint violation error
148    pub fn constraint_violation(operation: DatabaseOperation, message: impl Into<String>) -> Self {
149        Self::new(operation, DatabaseErrorKind::ConstraintViolation, message)
150    }
151
152    /// Create a query failed error
153    pub fn query_failed(message: impl Into<String>) -> Self {
154        Self::new(
155            DatabaseOperation::Query,
156            DatabaseErrorKind::QueryFailed,
157            message,
158        )
159    }
160
161    /// Create a timeout error
162    pub fn timeout(operation: DatabaseOperation, message: impl Into<String>) -> Self {
163        Self::new(operation, DatabaseErrorKind::Timeout, message)
164    }
165
166    /// Create a pool exhausted error
167    pub fn pool_exhausted(message: impl Into<String>) -> Self {
168        Self::new(
169            DatabaseOperation::PoolAcquire,
170            DatabaseErrorKind::PoolExhausted,
171            message,
172        )
173    }
174
175    /// Create a transaction failed error
176    pub fn transaction_failed(message: impl Into<String>) -> Self {
177        Self::new(
178            DatabaseOperation::Transaction,
179            DatabaseErrorKind::TransactionFailed,
180            message,
181        )
182    }
183
184    /// Create a sync failed error (Turso specific)
185    pub fn sync_failed(message: impl Into<String>) -> Self {
186        Self::new(
187            DatabaseOperation::Sync,
188            DatabaseErrorKind::SyncFailed,
189            message,
190        )
191    }
192
193    /// Check if this error is retriable (transient errors that may succeed on retry)
194    pub fn is_retriable(&self) -> bool {
195        matches!(
196            self.kind,
197            DatabaseErrorKind::ConnectionFailed
198                | DatabaseErrorKind::Timeout
199                | DatabaseErrorKind::PoolExhausted
200                | DatabaseErrorKind::SyncFailed
201        )
202    }
203
204    /// Add context to an existing error
205    pub fn add_context(mut self, context: impl Into<String>) -> Self {
206        self.context = Some(context.into());
207        self
208    }
209}
210
211impl fmt::Display for DatabaseError {
212    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
213        write!(
214            f,
215            "Database {} error during {}: {}",
216            self.kind, self.operation, self.message
217        )?;
218        if let Some(ref ctx) = self.context {
219            write!(f, " [context: {}]", ctx)?;
220        }
221        Ok(())
222    }
223}
224
225impl std::error::Error for DatabaseError {}
226
227/// Sanitize a database URL by removing credentials
228pub fn sanitize_url(url: &str) -> String {
229    // Handle standard database URLs like postgres://user:pass@host/db
230    if let Some(at_pos) = url.find('@') {
231        if let Some(scheme_end) = url.find("://") {
232            let scheme = &url[..scheme_end + 3];
233            let after_at = &url[at_pos + 1..];
234            return format!("{}<redacted>@{}", scheme, after_at);
235        }
236    }
237    // Handle Turso URLs like libsql://db-org.turso.io?authToken=xxx
238    if url.contains("authToken=") || url.contains("auth_token=") {
239        let base = url.split('?').next().unwrap_or(url);
240        return format!("{}?<credentials redacted>", base);
241    }
242    url.to_string()
243}
244/// Failure at the storage boundary.
245#[derive(Debug)]
246pub enum StorageError {
247    /// Storage setup or operation failure.
248    Internal(String),
249    /// A structured database failure.
250    Database(DatabaseError),
251    /// An analytical database failure.
252    ClickHouse(String),
253    /// Operating system I/O failure.
254    Io(std::io::Error),
255}
256impl fmt::Display for StorageError {
257    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
258        match self {
259            Self::Internal(message) => write!(f, "Internal server error: {message}"),
260            Self::Database(error) => error.fmt(f),
261            Self::ClickHouse(message) => write!(f, "ClickHouse error: {message}"),
262            Self::Io(error) => write!(f, "I/O error: {error}"),
263        }
264    }
265}
266impl std::error::Error for StorageError {
267    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
268        match self {
269            Self::Database(error) => Some(error),
270            Self::Io(error) => Some(error),
271            _ => None,
272        }
273    }
274}
275impl From<std::io::Error> for StorageError {
276    fn from(error: std::io::Error) -> Self {
277        Self::Io(error)
278    }
279}
280/// Result of a storage operation.
281pub type Result<T> = std::result::Result<T, StorageError>;
282
283impl From<DatabaseError> for StorageError {
284    fn from(error: DatabaseError) -> Self {
285        Self::Database(error)
286    }
287}
288
289#[cfg(test)]
290mod tests {
291    use super::*;
292
293    #[test]
294    fn test_database_error_new() {
295        let err = DatabaseError::new(
296            DatabaseOperation::Query,
297            DatabaseErrorKind::QueryFailed,
298            "Query failed",
299        );
300        assert_eq!(err.operation, DatabaseOperation::Query);
301        assert_eq!(err.kind, DatabaseErrorKind::QueryFailed);
302        assert_eq!(err.message, "Query failed");
303        assert!(err.context.is_none());
304    }
305
306    #[test]
307    fn test_database_error_with_context() {
308        let err = DatabaseError::with_context(
309            DatabaseOperation::Insert,
310            DatabaseErrorKind::ConstraintViolation,
311            "Unique constraint violated",
312            "users.email",
313        );
314        assert_eq!(err.operation, DatabaseOperation::Insert);
315        assert_eq!(err.kind, DatabaseErrorKind::ConstraintViolation);
316        assert_eq!(err.message, "Unique constraint violated");
317        assert_eq!(err.context, Some("users.email".to_string()));
318    }
319
320    #[test]
321    fn test_not_found_convenience() {
322        let err = DatabaseError::not_found(DatabaseOperation::Query, "User not found");
323        assert_eq!(err.operation, DatabaseOperation::Query);
324        assert_eq!(err.kind, DatabaseErrorKind::NotFound);
325        assert_eq!(err.message, "User not found");
326    }
327
328    #[test]
329    fn test_connection_failed_convenience() {
330        let err = DatabaseError::connection_failed("Connection refused");
331        assert_eq!(err.operation, DatabaseOperation::Connect);
332        assert_eq!(err.kind, DatabaseErrorKind::ConnectionFailed);
333        assert_eq!(err.message, "Connection refused");
334    }
335
336    #[test]
337    fn test_constraint_violation_convenience() {
338        let err = DatabaseError::constraint_violation(DatabaseOperation::Update, "FK constraint");
339        assert_eq!(err.operation, DatabaseOperation::Update);
340        assert_eq!(err.kind, DatabaseErrorKind::ConstraintViolation);
341    }
342
343    #[test]
344    fn test_query_failed_convenience() {
345        let err = DatabaseError::query_failed("Syntax error");
346        assert_eq!(err.operation, DatabaseOperation::Query);
347        assert_eq!(err.kind, DatabaseErrorKind::QueryFailed);
348    }
349
350    #[test]
351    fn test_timeout_convenience() {
352        let err = DatabaseError::timeout(DatabaseOperation::Query, "Query timed out");
353        assert_eq!(err.operation, DatabaseOperation::Query);
354        assert_eq!(err.kind, DatabaseErrorKind::Timeout);
355    }
356
357    #[test]
358    fn test_pool_exhausted_convenience() {
359        let err = DatabaseError::pool_exhausted("No connections available");
360        assert_eq!(err.operation, DatabaseOperation::PoolAcquire);
361        assert_eq!(err.kind, DatabaseErrorKind::PoolExhausted);
362    }
363
364    #[test]
365    fn test_transaction_failed_convenience() {
366        let err = DatabaseError::transaction_failed("Commit failed");
367        assert_eq!(err.operation, DatabaseOperation::Transaction);
368        assert_eq!(err.kind, DatabaseErrorKind::TransactionFailed);
369    }
370
371    #[test]
372    fn test_sync_failed_convenience() {
373        let err = DatabaseError::sync_failed("Sync with remote failed");
374        assert_eq!(err.operation, DatabaseOperation::Sync);
375        assert_eq!(err.kind, DatabaseErrorKind::SyncFailed);
376    }
377
378    #[test]
379    fn test_is_retriable_transient_errors() {
380        // Transient errors should be retriable
381        assert!(DatabaseError::connection_failed("refused").is_retriable());
382        assert!(DatabaseError::timeout(DatabaseOperation::Query, "timeout").is_retriable());
383        assert!(DatabaseError::pool_exhausted("exhausted").is_retriable());
384        assert!(DatabaseError::sync_failed("sync error").is_retriable());
385    }
386
387    #[test]
388    fn test_is_retriable_permanent_errors() {
389        // Permanent errors should not be retriable
390        assert!(!DatabaseError::not_found(DatabaseOperation::Query, "not found").is_retriable());
391        assert!(
392            !DatabaseError::constraint_violation(DatabaseOperation::Insert, "unique")
393                .is_retriable()
394        );
395        assert!(!DatabaseError::query_failed("syntax error").is_retriable());
396        assert!(!DatabaseError::transaction_failed("rollback").is_retriable());
397        assert!(!DatabaseError::new(
398            DatabaseOperation::Query,
399            DatabaseErrorKind::PermissionDenied,
400            "denied"
401        )
402        .is_retriable());
403        assert!(!DatabaseError::new(
404            DatabaseOperation::Query,
405            DatabaseErrorKind::TypeConversion,
406            "type error"
407        )
408        .is_retriable());
409        assert!(!DatabaseError::new(
410            DatabaseOperation::Connect,
411            DatabaseErrorKind::Configuration,
412            "bad config"
413        )
414        .is_retriable());
415    }
416
417    #[test]
418    fn test_add_context() {
419        let err = DatabaseError::query_failed("Query failed").add_context("SELECT * FROM users");
420        assert_eq!(err.context, Some("SELECT * FROM users".to_string()));
421    }
422
423    #[test]
424    fn test_display_formatting() {
425        let err = DatabaseError::new(
426            DatabaseOperation::Query,
427            DatabaseErrorKind::QueryFailed,
428            "Syntax error near 'FROM'",
429        );
430        let display = format!("{}", err);
431        assert!(display.contains("query_failed"));
432        assert!(display.contains("query"));
433        assert!(display.contains("Syntax error near 'FROM'"));
434    }
435
436    #[test]
437    fn test_display_formatting_with_context() {
438        let err = DatabaseError::with_context(
439            DatabaseOperation::Insert,
440            DatabaseErrorKind::ConstraintViolation,
441            "Unique constraint violated",
442            "users.email",
443        );
444        let display = format!("{}", err);
445        assert!(display.contains("[context: users.email]"));
446    }
447
448    #[test]
449    fn test_database_operation_display() {
450        assert_eq!(format!("{}", DatabaseOperation::Connect), "connect");
451        assert_eq!(format!("{}", DatabaseOperation::Query), "query");
452        assert_eq!(format!("{}", DatabaseOperation::Insert), "insert");
453        assert_eq!(format!("{}", DatabaseOperation::Update), "update");
454        assert_eq!(format!("{}", DatabaseOperation::Delete), "delete");
455        assert_eq!(format!("{}", DatabaseOperation::Transaction), "transaction");
456        assert_eq!(format!("{}", DatabaseOperation::Sync), "sync");
457        assert_eq!(format!("{}", DatabaseOperation::Migration), "migration");
458        assert_eq!(
459            format!("{}", DatabaseOperation::PoolAcquire),
460            "pool_acquire"
461        );
462    }
463
464    #[test]
465    fn test_database_error_kind_display() {
466        assert_eq!(
467            format!("{}", DatabaseErrorKind::ConnectionFailed),
468            "connection_failed"
469        );
470        assert_eq!(format!("{}", DatabaseErrorKind::NotFound), "not_found");
471        assert_eq!(
472            format!("{}", DatabaseErrorKind::ConstraintViolation),
473            "constraint_violation"
474        );
475        assert_eq!(
476            format!("{}", DatabaseErrorKind::QueryFailed),
477            "query_failed"
478        );
479        assert_eq!(
480            format!("{}", DatabaseErrorKind::TransactionFailed),
481            "transaction_failed"
482        );
483        assert_eq!(
484            format!("{}", DatabaseErrorKind::TypeConversion),
485            "type_conversion"
486        );
487        assert_eq!(format!("{}", DatabaseErrorKind::SyncFailed), "sync_failed");
488        assert_eq!(
489            format!("{}", DatabaseErrorKind::Configuration),
490            "configuration"
491        );
492        assert_eq!(format!("{}", DatabaseErrorKind::Timeout), "timeout");
493        assert_eq!(
494            format!("{}", DatabaseErrorKind::PermissionDenied),
495            "permission_denied"
496        );
497        assert_eq!(
498            format!("{}", DatabaseErrorKind::PoolExhausted),
499            "pool_exhausted"
500        );
501        assert_eq!(format!("{}", DatabaseErrorKind::Other), "other");
502    }
503
504    #[test]
505    fn test_sanitize_url_postgres() {
506        let url = "postgres://admin:secret123@localhost:5432/mydb";
507        let sanitized = sanitize_url(url);
508        assert_eq!(sanitized, "postgres://<redacted>@localhost:5432/mydb");
509        assert!(!sanitized.contains("admin"));
510        assert!(!sanitized.contains("secret123"));
511    }
512
513    #[test]
514    fn test_sanitize_url_turso() {
515        let url = "libsql://my-db-org.turso.io?authToken=eyJ0eXAi";
516        let sanitized = sanitize_url(url);
517        assert_eq!(
518            sanitized,
519            "libsql://my-db-org.turso.io?<credentials redacted>"
520        );
521        assert!(!sanitized.contains("eyJ0eXAi"));
522    }
523
524    #[test]
525    fn test_sanitize_url_no_credentials() {
526        let url = "libsql://localhost:8080";
527        let sanitized = sanitize_url(url);
528        assert_eq!(sanitized, "libsql://localhost:8080");
529    }
530
531    #[test]
532    fn test_database_error_equality() {
533        let err1 = DatabaseError::new(
534            DatabaseOperation::Query,
535            DatabaseErrorKind::NotFound,
536            "Not found",
537        );
538        let err2 = DatabaseError::new(
539            DatabaseOperation::Query,
540            DatabaseErrorKind::NotFound,
541            "Not found",
542        );
543        assert_eq!(err1, err2);
544    }
545
546    #[test]
547    fn test_database_error_clone() {
548        let err = DatabaseError::with_context(
549            DatabaseOperation::Insert,
550            DatabaseErrorKind::ConstraintViolation,
551            "Duplicate key",
552            "users.id",
553        );
554        let cloned = err.clone();
555        assert_eq!(err, cloned);
556    }
557}