✨ (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]`.
This commit is contained in:
parent
86d9f0e213
commit
4c8eee3585
18 changed files with 1488 additions and 60 deletions
|
|
@ -3,7 +3,52 @@
|
|||
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}\"")]
|
||||
|
|
@ -26,6 +71,17 @@ pub enum 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,
|
||||
|
|
@ -65,4 +121,72 @@ pub enum MailError {
|
|||
/// 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
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue