pagetop/extensions/pagetop-mail/src/error.rs
Manuel Cillero 4c8eee3585 ✨ (mail): Añade cola de envío persistente
Nueva feature `queue`, con `pagetop-seaorm` y `pagetop-cron`: los
correos se guardan ya compuestos en la tabla `mail_queue` y el trabajo
`mail.queue` los envía por lotes, con reintentos de espera creciente y
reserva por fila para varias instancias (entrega «al menos una vez»).

- `Email::queue()` sólo guarda el correo; `send_later()` lo guarda y lo
  intenta enseguida, o lo deja para el lote si hay demasiados en espera.
- SMTP con el transporte síncrono de `lettre` en `spawn_blocking`, con
  `timeout_secs` en cada lectura y escritura del socket.
- Turnos de envío y límites configurables para todos los transportes:
  envíos simultáneos, correos en espera, tiempo máximo de entrega y
  espera máxima entre intentos, validados al arrancar.
- Nuevos errores `Timeout`, `Overloaded`, `Interrupted`, `OutOfRange` y
  `Queue`; `MailError` pasa a ser `#[non_exhaustive]`.
2026-10-31 00:49:46 +01:00

192 lines
8.1 KiB
Rust

//! Errores de `pagetop-mail`.
use std::path::PathBuf;
/// Errores al configurar el envío de correo o al componer y enviar un correo.
///
/// Los devuelven [`Email::send()`](crate::Email::send) y, con la *feature* `queue`,
/// `Email::queue()`. [`Email::send_later()`](crate::Email::send_later) no devuelve nada: registra
/// sus errores en las trazas. Un ajuste no válido ([`InvalidSetting`](Self::InvalidSetting))
/// detiene la aplicación al arrancar, así que sólo llega a un envío fuera de una aplicación (p. ej.
/// en pruebas que no la preparan).
///
/// El mensaje de cada error (`Display`) describe sólo el error principal; el motivo concreto, como
/// la respuesta del servidor SMTP, está en sus causas, que se recorren con
/// [`source()`](std::error::Error::source).
///
/// # Variantes futuras
///
/// El tipo está marcado con `#[non_exhaustive]`: nuevas versiones pueden añadir variantes sin que
/// sea un cambio incompatible, y algunas sólo existen con una *feature* (`Queue`, con `queue`). Por
/// eso, fuera de este *crate*, un `match` sobre `MailError` debe incluir siempre un brazo comodín
/// (`_`), aunque enumere todas las variantes que conoce. Para tratar sólo algunos casos también
/// sirven `if let` y `matches!`.
///
/// # Ejemplo
///
/// ```rust,no_run
/// use pagetop::prelude::*;
/// use pagetop_mail::prelude::*;
///
/// async fn invite(address: String) -> Result<(), String> {
/// let result = Email::new()
/// .with_to(address.as_str())
/// .with_subject("Invitación")
/// .with_text("Te invitamos a unirte al proyecto.")
/// .send()
/// .await;
/// match result {
/// Ok(()) => Ok(()),
/// // Un error que puede corregir quien escribió la dirección.
/// Err(MailError::InvalidAddress { .. }) => Err(format!("\"{address}\" no es válida")),
/// // El resto, y cualquier variante futura, es un fallo interno.
/// Err(err) => {
/// trace::error!("Cannot send invitation: {err}");
/// Err("No se ha podido enviar la invitación".to_owned())
/// }
/// }
/// }
/// ```
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum MailError {
/// Una dirección de correo no es válida.
#[error("invalid email address \"{address}\"")]
InvalidAddress {
/// Dirección tal como se indicó.
address: String,
/// Motivo del error.
#[source]
source: lettre::address::AddressError,
},
/// Un ajuste de la sección `[mail]` no es válido.
#[error("invalid mail setting \"{key}\"")]
InvalidSetting {
/// Clave del ajuste, p. ej. `"mail.from"`.
key: &'static str,
/// Motivo del error.
#[source]
source: Box<MailError>,
},
/// Una URL no es absoluta (no empieza por `http://` ni `https://`).
#[error("invalid URL \"{0}\": it must start with http:// or https://")]
InvalidUrl(String),
/// Un valor numérico de la configuración está fuera del rango admitido (causa de
/// [`InvalidSetting`](Self::InvalidSetting)).
#[error("{value} is not between {min} and {max}")]
OutOfRange {
/// Valor indicado.
value: u64,
/// Valor mínimo admitido.
min: u64,
/// Valor máximo admitido.
max: u64,
},
/// El correo no indica remitente y no hay uno por defecto (`mail.from`).
#[error("email has no sender: set mail.from or use Email::with_from()")]
MissingFrom,
/// El correo no tiene ningún destinatario (`To`, `Cc` ni `Bcc`).
#[error("email has no recipients")]
NoRecipients,
/// El tipo de contenido de un adjunto no es un tipo MIME válido.
#[error("invalid content type \"{0}\" for attachment")]
InvalidContentType(String),
/// No se puede leer el archivo de un adjunto.
#[error("cannot read attachment \"{path}\"")]
ReadAttachment {
/// Ruta del archivo.
path: PathBuf,
/// Error devuelto al leerlo.
#[source]
source: std::io::Error,
},
/// No se puede crear el directorio de los archivos de correo (`mail.file.dir`).
#[error("cannot create mail directory \"{path}\"")]
CreateDir {
/// Ruta del directorio.
path: PathBuf,
/// Error devuelto al crearlo.
#[source]
source: std::io::Error,
},
/// No se puede componer el mensaje.
#[error("cannot build email message")]
Build(#[source] lettre::error::Error),
/// Error de conexión, de cifrado o de entrega con el servidor SMTP.
#[error("SMTP error")]
Smtp(#[source] lettre::transport::smtp::Error),
/// Error al entregar el correo al programa *sendmail*.
#[error("sendmail error")]
Sendmail(#[source] lettre::transport::sendmail::Error),
/// Error al guardar el correo como archivo.
#[error("cannot write email file")]
File(#[source] lettre::transport::file::Error),
/// La entrega no ha terminado en el tiempo máximo, en segundos
/// ([`MailSettings::delivery_timeout_secs`]): el servidor SMTP o el programa *sendmail* no
/// responden, o el correo esperó su turno de envío todo ese tiempo (ver
/// [`MailSettings::max_waiting`]). Es un fallo temporal; si el envío llegó a empezar, el correo
/// puede haberse entregado igualmente.
///
/// [`MailSettings::delivery_timeout_secs`]: crate::config::MailSettings::delivery_timeout_secs
/// [`MailSettings::max_waiting`]: crate::config::MailSettings::max_waiting
#[error("email delivery did not finish within {0} seconds")]
Timeout(u64),
/// Hay demasiados correos esperando su turno de envío y la entrega se rechaza enseguida, sin
/// empezar, para no acumularlos en memoria: llegan más correos de los que el servidor despacha
/// (ver [`MailSettings::max_waiting`](crate::config::MailSettings::max_waiting)). Es un fallo
/// temporal.
#[error("too many emails waiting to be delivered")]
Overloaded,
/// La entrega no ha llegado a empezar porque la aplicación se está deteniendo. Es un fallo
/// temporal.
#[error("email delivery interrupted: the application is shutting down")]
Interrupted,
/// Error de la base de datos al guardar el correo en la cola de envío (*feature* `queue`).
#[cfg(feature = "queue")]
#[error("cannot store email in the mail queue")]
Queue(#[source] pagetop_seaorm::db::DbErr),
}
impl MailError {
// Indica si el fallo es definitivo y no tiene sentido reintentar el envío: el servidor SMTP
// rechaza el correo (5xx, p. ej. una dirección inexistente) o el sobre guardado en la cola no
// es válido. Los fallos de conexión, de cifrado, los temporales (4xx) y los tiempos agotados se
// pueden reintentar.
#[cfg(feature = "queue")]
pub(crate) fn is_permanent(&self) -> bool {
match self {
MailError::Smtp(err) => err.is_permanent(),
MailError::InvalidAddress { .. } | MailError::Build(_) => true,
_ => false,
}
}
// Indica si el fallo no depende del correo sino del transporte, y afectaría igual a los
// siguientes: no hay respuesta del servidor SMTP (conexión, cifrado, configuración, tiempo
// agotado...), hay demasiados correos esperando turno, o fallan *sendmail* o los archivos. Las
// respuestas del servidor (4xx y 5xx) dependen de cada correo, p. ej. de sus destinatarios.
#[cfg(feature = "queue")]
pub(crate) fn is_transport_failure(&self) -> bool {
match self {
MailError::Smtp(err) => !err.is_transient() && !err.is_permanent(),
MailError::Sendmail(_)
| MailError::File(_)
| MailError::Timeout(_)
| MailError::Overloaded
| MailError::Interrupted => true,
_ => false,
}
}
// Describe el error con todas sus causas, para las trazas.
pub(crate) fn describe(&self) -> String {
let mut message = self.to_string();
let mut source = std::error::Error::source(self);
while let Some(cause) = source {
message.push_str(": ");
message.push_str(&cause.to_string());
source = cause.source();
}
message
}
}