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}