scyph_notify/error.rs
1//! Notification error type definitions for `scyph-notify`.
2//!
3//! Categorizes all possible failures occurring during email compilation, SMTP delivery,
4//! FCM push API calls, template rendering, and missing configuration variables.
5//!
6//! ## Error Hierarchy
7//!
8//! ```text
9//! NotifyError
10//! ├── Configuration – missing or invalid env vars (SMTP_HOST, FCM_PROJECT_ID, etc.)
11//! ├── Template – Tera parse/render error [feature = "email"]
12//! ├── Smtp – lettre SMTP transport error [feature = "email"]
13//! ├── Address – malformed email address string [feature = "email"]
14//! ├── EmailBuild – lettre message construction error [feature = "email"]
15//! ├── FcmHttp – reqwest HTTP transport error [feature = "fcm"]
16//! ├── FcmAuth – GCP OAuth2 token failure [feature = "fcm"]
17//! └── Internal – catch-all internal error
18//! ```
19//!
20//! ## HTTP Mapping
21//!
22//! All `NotifyError` variants convert to HTTP 500 Internal Server Error via the
23//! `From<NotifyError> for AppError` implementation. Notification failures are considered
24//! server-side infrastructure faults rather than client errors.
25
26use scyph_core::AppError;
27
28/// Error type for all notification services and utilities in `scyph-notify`.
29///
30/// Implements `thiserror::Error` for ergonomic display messages and `From` conversions from
31/// underlying library errors (`tera::Error`, `lettre` errors, `reqwest::Error`, `gcp_auth::Error`).
32///
33/// Convert to an Axum-compatible response using `AppError::from(notify_error)`, which produces
34/// an HTTP 500 RFC 7807 problem details response.
35///
36/// # Examples
37///
38/// ```rust
39/// use scyph_notify::NotifyError;
40///
41/// let err = NotifyError::Configuration("SMTP_HOST is not set".into());
42/// assert_eq!(err.to_string(), "Configuration error: SMTP_HOST is not set");
43///
44/// let err = NotifyError::Internal("unexpected state".into());
45/// assert_eq!(err.to_string(), "Notification error: unexpected state");
46/// ```
47#[derive(Debug, thiserror::Error)]
48pub enum NotifyError {
49 /// Missing, empty, or unparseable configuration settings or environment variables (e.g. `SMTP_HOST`, `FCM_PROJECT_ID`).
50 #[error("Configuration error: {0}")]
51 Configuration(String),
52
53 /// Tera template parsing, compilation, or variable context rendering failure.
54 #[cfg(feature = "email")]
55 #[error("Template error: {0}")]
56 Template(#[from] tera::Error),
57
58 /// SMTP transport, connection, authentication, or network transmission failure.
59 #[cfg(feature = "email")]
60 #[error("SMTP email error: {0}")]
61 Smtp(#[from] lettre::transport::smtp::Error),
62
63 /// Email recipient or sender address parsing failure (e.g., malformed email address string).
64 #[cfg(feature = "email")]
65 #[error("Email address error: {0}")]
66 Address(#[from] lettre::address::AddressError),
67
68 /// Email message envelope, header, or body formatting failure during `lettre` message construction.
69 #[cfg(feature = "email")]
70 #[error("Email build error: {0}")]
71 EmailBuild(#[from] lettre::error::Error),
72
73 /// HTTP client transport, connection, or response status error during FCM REST API requests.
74 #[cfg(feature = "fcm")]
75 #[error("FCM HTTP request error: {0}")]
76 FcmHttp(#[from] reqwest::Error),
77
78 /// Service account authentication or OAuth2 access token acquisition failure for Google Cloud FCM API.
79 #[cfg(feature = "fcm")]
80 #[error("FCM authentication error: {0}")]
81 FcmAuth(#[from] gcp_auth::Error),
82
83 /// Internal or generic notification processing error.
84 #[error("Notification error: {0}")]
85 Internal(String),
86}
87
88impl From<NotifyError> for AppError {
89 /// Converts a [`NotifyError`] into an HTTP 500 RFC 7807 [`AppError`] for Axum API responses.
90 fn from(err: NotifyError) -> Self {
91 AppError::internal(err.to_string())
92 }
93}