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}