Skip to main content

scyph_realtime/
error.rs

1//! Realtime WebSocket broadcaster error types.
2
3use scyph_core::AppError;
4
5/// Error type for real-time Redis pub/sub and WebSocket broadcasting operations.
6///
7/// `RealtimeError` covers the full lifecycle of realtime operations: configuration loading,
8/// Redis connectivity, message serialization, and in-process delivery. It implements
9/// `From<RealtimeError> for AppError` for automatic conversion in Axum handlers.
10///
11/// # Error Mapping
12///
13/// | Variant | HTTP Status (via `AppError`) | Cause |
14/// |---|---|---|
15/// | [`Redis`](Self::Redis) | 500 Internal Server Error | Redis connection/pub/sub failure |
16/// | [`Serialization`](Self::Serialization) | 500 Internal Server Error | JSON encode/decode failure |
17/// | [`Configuration`](Self::Configuration) | 500 Internal Server Error | Missing/invalid env vars |
18/// | [`Delivery`](Self::Delivery) | 500 Internal Server Error | MPSC channel closed |
19/// | [`Internal`](Self::Internal) | 500 Internal Server Error | Unclassified internal error |
20///
21/// # Example
22///
23/// ```rust,ignore
24/// use scyph_realtime::RealtimeError;
25///
26/// async fn send_notification(broadcaster: &RealtimeBroadcaster, user_id: Uuid) -> Result<(), RealtimeError> {
27///     broadcaster.publish("notification.created", user_id, &serde_json::json!({
28///         "message": "You have a new notification"
29///     })).await?;
30///     Ok(())
31/// }
32/// ```
33#[derive(Debug, thiserror::Error)]
34pub enum RealtimeError {
35    /// Redis client, connection, or pub/sub operation error.
36    ///
37    /// Occurs when Redis is unreachable, authentication fails, the Pub/Sub subscription
38    /// drops, or a PUBLISH command fails. The subscriber loop catches this variant and
39    /// automatically retries after `reconnect_interval_secs`.
40    #[error("Redis error: {0}")]
41    Redis(#[from] redis::RedisError),
42
43    /// Event JSON serialization or deserialization failure.
44    ///
45    /// Occurs when a payload cannot be serialized to JSON for publishing, or when an
46    /// incoming Redis message cannot be deserialized into [`RawRealtimeEnvelope`](crate::event::RawRealtimeEnvelope)
47    /// or a typed [`RealtimeEvent<T>`](crate::event::RealtimeEvent).
48    #[error("Serialization error: {0}")]
49    Serialization(#[from] serde_json::Error),
50
51    /// Missing or invalid configuration parameter or environment variable.
52    ///
53    /// Occurs when [`RealtimeConfig::from_env`](crate::config::RealtimeConfig::from_env)
54    /// encounters an unparseable environment variable (e.g., `REALTIME_RECONNECT_INTERVAL_SECS`
55    /// containing a non-numeric value).
56    #[error("Configuration error: {0}")]
57    Configuration(String),
58
59    /// Connection channel delivery failure.
60    ///
61    /// Occurs when an MPSC channel sender returns `Err(SendError)` because the receiver
62    /// has been dropped (i.e., the WebSocket connection closed before the message could
63    /// be delivered). This is distinct from a full buffer, which is silently dropped.
64    #[error("Delivery error: {0}")]
65    Delivery(String),
66
67    /// Generic internal real-time error for unclassified failure paths.
68    #[error("Internal realtime error: {0}")]
69    Internal(String),
70}
71
72impl From<RealtimeError> for AppError {
73    /// Converts a [`RealtimeError`] into an RFC 7807 [`AppError`] response.
74    ///
75    /// All variants map to `500 Internal Server Error` since realtime errors are
76    /// infrastructure-level failures not attributable to client input.
77    fn from(err: RealtimeError) -> Self {
78        AppError::internal(err.to_string())
79    }
80}