Skip to main content

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}