Skip to main content

scyph_utils/idempotency/
error.rs

1//! Idempotency error types.
2//!
3//! Defines [`IdempotencyError`] — failures that can occur during idempotency key reservation,
4//! response caching, and cache retrieval operations.
5
6use scyph_core::AppError;
7
8/// Errors encountered during idempotency check and storage operations.
9///
10/// ## HTTP Mapping
11///
12/// | Variant | HTTP Status | Meaning |
13/// |---------|-------------|---------|
14/// | `Redis` | 500 | Infrastructure failure — Redis unavailable or query error |
15/// | `Json` | 500 | Serialization bug — cached value is malformed |
16/// | `Conflict` | 409 | Duplicate in-flight request with the same idempotency key |
17///
18/// ## Conflict Handling
19///
20/// A [`IdempotencyError::Conflict`] response means the exact same request (by idempotency key)
21/// is currently being processed by another handler invocation. The client should wait briefly
22/// and poll or retry. This is a normal operational response, not an infrastructure failure.
23///
24/// # Examples
25///
26/// ```rust
27/// use scyph_utils::idempotency::IdempotencyError;
28///
29/// let err = IdempotencyError::Conflict("key_abc123 is currently in progress".into());
30/// assert!(err.to_string().contains("currently in progress"));
31/// ```
32#[derive(Debug, thiserror::Error)]
33pub enum IdempotencyError {
34    /// Redis database connection or query execution failure.
35    #[error("Redis error: {0}")]
36    Redis(#[from] redis::RedisError),
37
38    /// JSON serialization or deserialization failure.
39    #[error("JSON serialization error: {0}")]
40    Json(#[from] serde_json::Error),
41
42    /// A concurrent request with the same idempotency key is currently in progress.
43    #[error("A request with key '{0}' is currently in progress")]
44    Conflict(String),
45}
46
47impl From<IdempotencyError> for AppError {
48    fn from(err: IdempotencyError) -> Self {
49        match err {
50            IdempotencyError::Conflict(msg) => AppError::Conflict(msg),
51            IdempotencyError::Redis(e) => AppError::internal_from(e, "Redis operation failed"),
52            IdempotencyError::Json(e) => AppError::internal_from(e, "JSON operation failed"),
53        }
54    }
55}