✨ (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:
Manuel Cillero 2026-10-31 00:49:46 +01:00
parent 86d9f0e213
commit 4c8eee3585
18 changed files with 1488 additions and 60 deletions

View file

@ -15,8 +15,18 @@ rust-version.workspace = true
license.workspace = true
authors.workspace = true
[package.metadata.docs.rs]
# Documenta también la API de la cola de envío (`Email::queue()`, `MailError::Queue`).
features = ["queue"]
[features]
# Cola de envío persistente en la base de datos, con reintentos y envío por lotes.
queue = ["dep:pagetop-cron", "dep:pagetop-seaorm"]
[dependencies]
pagetop.workspace = true
pagetop-cron = { workspace = true, optional = true }
pagetop-seaorm = { workspace = true, optional = true }
mime_guess.workspace = true
serde.workspace = true
thiserror.workspace = true
@ -33,3 +43,10 @@ features = [
"file-transport",
"tokio1-native-tls",
]
[dev-dependencies]
pagetop-seaorm = { workspace = true, features = ["sqlite"] }
[[test]]
name = "queue"
required-features = ["queue"]

View file

@ -175,6 +175,41 @@ cabeceras, HTML con el diseño común, texto plano y adjuntos, sin enviar nada.
Si un correo sólo tiene HTML, al enviarlo se genera su texto plano a partir del contenido: bloques
separados por líneas, listas con guiones, y la dirección de cada enlace entre paréntesis.
## Cola de envío
Con la *feature* `queue`, los correos se guardan en una cola en la base de datos (con
`pagetop-seaorm`) y el trabajo `mail.queue` de `pagetop-cron` los envía por lotes:
```toml
[dependencies]
pagetop-mail = { version = "...", features = ["queue"] }
```
La cola usa la base de datos que la aplicación configura en `[database]` para `pagetop-seaorm`, con
la *feature* de su motor (`postgres`, `mysql` o `sqlite`), y crea en ella la tabla `mail_queue` al
arrancar. La tabla guarda cada mensaje completo y sin cifrar hasta entregarlo, o durante
`keep_failed_days` si falla: puede contener datos personales y enlaces de un solo uso, también en
las copias de seguridad de la base de datos.
- `Email::send_later()` guarda el correo y lo intenta enseguida. Si falla por un error temporal,
queda en la cola y se reintenta más tarde, también tras un reinicio.
- `Email::queue()` sólo lo guarda: cada ejecución del trabajo envía, uno tras otro, como mucho
`batch_size` correos, para que los envíos masivos no sobrecarguen el equipo ni el servidor de
correo.
La espera entre reintentos se duplica en cada intento; un rechazo definitivo del servidor (SMTP
5xx) o el último intento dejan el correo como fallido. Si el servidor no responde, el lote se
interrumpe y los demás correos esperan a la siguiente ejecución, sin gastar intentos. Los ajustes
van en `[mail.queue]`, y el ritmo, en la programación del trabajo:
```toml
[mail.queue]
batch_size = 50
[cron.jobs."mail.queue"]
schedule = "@delay 30s" # 30 s después de terminar cada lote (por defecto, 1 minuto).
```
## Transportes
Se elige en `mail.transport`:

View file

@ -6,3 +6,15 @@ transport = "memory"
from = "PageTop Tests <tests@example.com>"
base_url = "https://example.com/"
previews = true
# Lotes pequeños para comprobar en las pruebas de la cola (`--features queue`) que cada ejecución
# envía como mucho `batch_size` correos.
[mail.queue]
batch_size = 2
# Base de datos de las pruebas de la cola: SQLite en memoria, nueva en cada ejecución, con una sola
# conexión para que todas las consultas la compartan. Sin la feature `queue` no se usa.
[database]
db_type = "sqlite"
db_name = "mail-tests?mode=memory"
max_pool_size = 1

View file

@ -24,7 +24,8 @@
//! ```
//!
//! Todas las opciones, con su valor por defecto, se documentan en [`MailSettings`] y sus
//! subsecciones ([`SmtpSettings`], [`SendmailSettings`] y [`FileSettings`]).
//! subsecciones ([`SmtpSettings`], [`SendmailSettings`], [`FileSettings`] y [`QueueSettings`]). Un
//! valor fuera del rango que indica cada opción impide arrancar la aplicación.
//!
//! Consulta [`pagetop::config`] para ver cómo PageTop lee los archivos de configuración y aplica
//! los valores a los ajustes.
@ -64,6 +65,44 @@ pub struct MailSettings {
/// que conozca la ruta.
#[default = false]
pub previews: bool,
/// Tiempo máximo de cada entrega completa, en segundos (entre 1 y 86400), incluida la espera de
/// su turno de envío. Pasado ese tiempo, la entrega falla con [`MailError::Timeout`]. Es una
/// red de seguridad: *sendmail* y los archivos no tienen límite propio, y en SMTP
/// [`timeout_secs`] limita cada orden al servidor, no la entrega entera.
///
/// **Se recomienda el valor predeterminado, 300 (5 minutos).**
///
/// - **Reducirlo** (p. ej. a 60 o 120) sirve con un servidor de correo cercano y rápido y sin
/// adjuntos grandes: los fallos se detectan antes y, en una avalancha, los correos que
/// esperan turno fallan antes en lugar de acumularse. Pero debe superar con holgura el doble
/// de [`timeout_secs`] (se avisa al arrancar si no), o fallarán envíos lentos pero correctos;
/// y cuanto más corto, más correos que el servidor sí acepta se dan por fallidos y, con la
/// cola de envío, se entregan dos veces.
/// - **Aumentarlo** sólo con servidores muy lentos o adjuntos grandes por conexiones lentas:
/// cada correo retiene su turno durante más tiempo y, con la cola de envío, un correo cuya
/// entrega se interrumpe (p. ej. porque la aplicación cae) tarda más en reintentarse, porque
/// su reserva dura el triple de este tiempo.
///
/// [`MailError::Timeout`]: crate::MailError::Timeout
/// [`timeout_secs`]: SmtpSettings::timeout_secs
#[default = 300]
pub delivery_timeout_secs: u64,
/// Número máximo de correos que pueden esperar su turno de envío **por cada envío simultáneo**
/// ([`SmtpSettings::pool_max_size`], [`SendmailSettings::max_concurrent`] o
/// [`FileSettings::max_concurrent`]). Con todos los turnos de espera ocupados, la entrega falla
/// enseguida, sin empezar, con [`MailError::Overloaded`](crate::MailError::Overloaded); con la
/// *feature* `queue`, los correos de [`send_later()`](crate::Email::send_later) quedan entonces
/// en la cola de envío. Con 0, ningún correo espera: sólo se entregan los que encuentran un
/// envío libre.
///
/// **No se recomiendan valores mayores que el predeterminado.** Cada correo en espera retiene
/// en memoria el mensaje completo, adjuntos incluidos, y la espera cuenta dentro del tiempo
/// máximo de cada entrega ([`delivery_timeout_secs`](Self::delivery_timeout_secs)): con más
/// correos esperando, los últimos agotan ese tiempo antes de empezar y fallan igualmente,
/// después de haber ocupado la memoria. Con poca memoria, o con correos con adjuntos grandes,
/// conviene reducirlo.
#[default = 100]
pub max_waiting: u32,
/// Servidor SMTP, en la subsección `[mail.smtp]`.
pub smtp: SmtpSettings,
@ -73,6 +112,9 @@ pub struct MailSettings {
/// Archivos de correo, en la subsección `[mail.file]`.
pub file: FileSettings,
/// Cola de envío, en la subsección `[mail.queue]`. Sólo se usa con la *feature* `queue`.
pub queue: QueueSettings,
}
/// Forma de entregar los correos. Usado en [`MailSettings::transport`].
@ -115,10 +157,26 @@ pub struct SmtpSettings {
/// Nombre con el que se presenta la aplicación al servidor (`EHLO`). Sin valor, el nombre del
/// equipo.
pub hello_name: Option<String>,
/// Segundos de espera máxima de cada orden al servidor.
/// Segundos de espera máxima de cada intento de conexión y de cada orden al servidor. Cada
/// entrega completa tiene además un tiempo máximo
/// ([`mail.delivery_timeout_secs`](MailSettings::delivery_timeout_secs)), pasado el cual falla
/// con [`MailError::Timeout`](crate::MailError::Timeout).
///
/// Con [`SmtpSecurity::Tls`] no cubre el saludo TLS inicial: si el servidor acepta la conexión
/// y no responde, el envío falla al agotar ese tiempo máximo, pero sigue ocupando uno de los
/// envíos simultáneos ([`pool_max_size`](Self::pool_max_size)) hasta que el sistema da la
/// conexión por perdida, o hasta reiniciar si el servidor la mantiene abierta. Si el servidor
/// lo admite, [`SmtpSecurity::StartTls`] no tiene este problema.
#[default = 60]
pub timeout_secs: u64,
/// Número máximo de conexiones abiertas con el servidor, que se reutilizan entre envíos.
/// Número máximo de envíos simultáneos al servidor (al menos uno), y de conexiones que se
/// conservan abiertas para reutilizarlas. Los correos que llegan con todos los envíos en curso
/// esperan su turno sin ocupar un hilo, pero la espera cuenta dentro del tiempo máximo de cada
/// entrega ([`mail.delivery_timeout_secs`](MailSettings::delivery_timeout_secs)).
///
/// Por cada envío simultáneo esperan turno como mucho
/// [`mail.max_waiting`](MailSettings::max_waiting) correos; con más, la entrega falla enseguida
/// con [`MailError::Overloaded`](crate::MailError::Overloaded), para no acumularlos en memoria.
#[default = 10]
pub pool_max_size: u32,
/// Acepta certificados no válidos (caducados, autofirmados o de otro servidor). **Peligroso**:
@ -135,8 +193,8 @@ pub enum SmtpSecurity {
None,
/// Cifra con `STARTTLS` si el servidor lo ofrece y, si no, envía sin cifrar.
Opportunistic,
/// Exige `STARTTLS`: empieza sin cifrar y cifra antes de autenticarse. Es el valor por
/// defecto (puerto 587).
/// Exige `STARTTLS`: empieza sin cifrar y cifra antes de autenticarse. Es el valor por defecto
/// (puerto 587).
#[default]
StartTls,
/// Conexión cifrada desde el principio, también llamada SMTPS (puerto 465).
@ -148,6 +206,22 @@ pub enum SmtpSecurity {
pub struct SendmailSettings {
/// Programa que recibe los correos. Sin valor, `sendmail` del `PATH`.
pub command: Option<String>,
/// Número máximo de correos que se entregan a la vez (al menos uno). Cada entrega abre un
/// proceso *sendmail*, y los correos que llegan con todas en curso esperan su turno, como mucho
/// [`mail.max_waiting`](MailSettings::max_waiting) por cada entrega simultánea; con más, la
/// entrega falla enseguida con [`MailError::Overloaded`](crate::MailError::Overloaded).
///
/// **No se recomiendan valores mayores que el predeterminado.** Con un servidor de correo
/// local, *sendmail* sólo deja el correo en su cola, que lo acepta en milisegundos, así que más
/// procesos a la vez apenas aceleran el envío. En cambio, en una avalancha de correos se abren
/// otros tantos procesos, que compiten por la memoria y la CPU con la aplicación, y crece en la
/// misma proporción el número de correos que pueden esperar turno en memoria.
///
/// Si el programa no tiene cola propia y envía cada correo a un servidor remoto (p. ej. `msmtp`
/// o `ssmtp`), cada proceso mantiene abierta una conexión con ese servidor: no conviene superar
/// su límite de conexiones simultáneas, o rechazará los correos que lo excedan.
#[default = 10]
pub max_concurrent: u32,
}
/// Subsección **`[mail.file]`** de la configuración.
@ -156,6 +230,60 @@ pub struct FileSettings {
/// Directorio donde se guardan los correos. Se crea al arrancar si no existe.
#[default = "mail"]
pub dir: String,
/// Número máximo de correos que se guardan a la vez (al menos uno). Los correos que llegan con
/// todos en curso esperan su turno, como mucho [`mail.max_waiting`](MailSettings::max_waiting)
/// por cada uno; con más, la entrega falla enseguida con
/// [`MailError::Overloaded`](crate::MailError::Overloaded).
///
/// **No se recomiendan valores mayores que el predeterminado.** Cada archivo se escribe en un
/// hilo del *pool* de bloqueo de Tokio, que comparten otras tareas de la aplicación (p. ej. el
/// cálculo de contraseñas al iniciar sesión), y más escrituras a la vez sobre el mismo disco
/// apenas aceleran el guardado. En una avalancha de correos, ocuparían más hilos de ese *pool*
/// y crecería en la misma proporción el número de correos que pueden esperar turno en memoria.
#[default = 10]
pub max_concurrent: u32,
}
/// Subsección **`[mail.queue]`** de la configuración.
///
/// Sólo se usa con la *feature* `queue` (ver [`Email::queue()`](crate::Email)). El ritmo de envío
/// no se configura aquí: es la programación del trabajo `mail.queue` de `pagetop-cron`, que por
/// defecto se ejecuta un minuto después de terminar la ejecución anterior y se cambia en
/// `[cron.jobs."mail.queue"]`.
#[settings]
pub struct QueueSettings {
/// Número máximo de correos que envía cada ejecución del trabajo `mail.queue`, uno tras otro
/// (al menos uno). Limita la carga del equipo y del servidor de correo en los envíos masivos.
#[default = 50]
pub batch_size: u32,
/// Número máximo de intentos de cada correo, contando el primero. Agotados, o ante un rechazo
/// definitivo del servidor (SMTP 5xx), el correo queda como fallido. Con 0 se intenta una vez.
#[default = 5]
pub max_attempts: u32,
/// Segundos de espera tras el primer fallo temporal. La espera se duplica en cada intento
/// fallido (60, 120, 240... con el valor por defecto), hasta
/// [`max_retry_secs`](Self::max_retry_secs).
#[default = 60]
pub retry_base_secs: u64,
/// Espera máxima entre dos intentos, en segundos (entre 1 y 31536000, un año).
///
/// **Se recomienda el valor predeterminado, 86400 (un día).** Con los demás valores por defecto
/// no se llega a alcanzar (la mayor espera es de 8 minutos); sólo limita las esperas cuando se
/// aumentan [`max_attempts`](Self::max_attempts) o [`retry_base_secs`](Self::retry_base_secs).
///
/// - **Reducirlo** hace que los correos se reintenten antes tras una caída larga del servidor
/// de correo, a costa de más intentos (y más trabajo para la aplicación y el servidor)
/// mientras dura; con muchos intentos, el correo puede darse por fallido antes de que el
/// servidor se recupere.
/// - **Aumentarlo** reparte los intentos a lo largo de más tiempo, pero un correo puede llegar
/// con días de retraso, cuando quizá ya no sirve (p. ej. un enlace de recuperación de
/// contraseña ya caducado).
#[default = 86_400]
pub max_retry_secs: u64,
/// Días que se conservan los correos fallidos antes de borrarlos. Con 0 no se borran. Los
/// enviados se borran en cuanto se entregan, porque pueden contener enlaces de un solo uso.
#[default = 30]
pub keep_failed_days: u32,
}
#[cfg(test)]

View file

@ -12,9 +12,10 @@ use std::time::{SystemTime, UNIX_EPOCH};
/// Correo electrónico listo para enviar.
///
/// Se compone con los métodos `with_*()` y se envía con [`send()`](Self::send), que espera a que
/// el servidor lo acepte, o con [`send_later()`](Self::send_later), que lo envía en segundo plano.
/// También puede crearse a partir de una plantilla con [`from_template()`](Self::from_template).
/// Se compone con los métodos `with_*()` y se envía con [`send()`](Self::send), que espera a que el
/// servidor lo acepte, o con [`send_later()`](Self::send_later), que lo envía en segundo plano. Con
/// la *feature* `queue`, `queue()` lo guarda en la cola de envío para el siguiente lote. También
/// puede crearse a partir de una plantilla con [`from_template()`](Self::from_template).
///
/// Un correo puede tener texto plano, HTML o ambos (los clientes de correo muestran el que
/// prefieran), además de archivos adjuntos y de imágenes incrustadas en el HTML (ver
@ -65,8 +66,7 @@ pub struct Email {
subject: String,
/// Texto plano, si lo tiene.
text: Option<String>,
/// HTML, si lo tiene: el contenido mientras se compone y el documento completo una vez
/// enviado.
/// HTML, si lo tiene: el contenido mientras se compone y el documento completo una vez enviado.
html: Option<Markup>,
#[getters(skip)]
html_is_document: bool,
@ -111,7 +111,9 @@ impl Email {
///
/// Falla si alguna dirección o el tipo MIME de algún adjunto no son válidos, si falta el
/// remitente (salvo con `transport = "log"`, que sólo escribe el correo en las trazas) o los
/// destinatarios, o si la entrega falla.
/// destinatarios, si la entrega falla o no termina en el tiempo máximo
/// (`mail.delivery_timeout_secs`, [`MailError::Timeout`]), o si ya hay demasiados correos
/// esperando turno ([`MailError::Overloaded`]).
pub async fn send(self) -> Result<(), MailError> {
transport::deliver(self).await
}
@ -121,24 +123,77 @@ impl Email {
///
/// La respuesta de la petición no espera al servidor de correo, y su tiempo no revela si el
/// correo se ha enviado (p. ej., si existe la cuenta para la que se pide recuperar la
/// contraseña). A cambio, los correos pendientes se pierden si la aplicación se detiene antes
/// de enviarlos, y no se reintentan si fallan.
/// contraseña).
///
/// Sin la *feature* `queue`, los correos pendientes se pierden si la aplicación se detiene
/// antes de enviarlos, y no se reintentan si fallan. Con ella, el correo se guarda primero en
/// la cola de envío y se intenta enseguida, sin esperar al trabajo que la vacía: si falla por
/// un error temporal, queda en la cola para reintentarlo (ver `queue()`). Si no se puede
/// guardar en la cola, se envía igualmente sin ella y se avisa en las trazas.
///
/// Si llegan más correos de los que el servidor despacha y ya hay demasiados esperando turno
/// ([`MailError::Overloaded`]), sin la *feature* `queue` el correo se descarta, y con ella
/// queda en la cola para el siguiente lote.
pub fn send_later(self) {
tokio::spawn(async move {
let subject = self.subject.clone();
if let Err(err) = self.send().await {
let mut message = err.to_string();
let mut source = std::error::Error::source(&err);
while let Some(cause) = source {
message.push_str(": ");
message.push_str(&cause.to_string());
source = cause.source();
}
trace::error!("Cannot send email \"{subject}\": {message}");
#[cfg(feature = "queue")]
let result = crate::queue::send_later(self).await;
#[cfg(not(feature = "queue"))]
let result = self.send().await;
if let Err(err) = result {
trace::error!("Cannot send email \"{subject}\": {}", err.describe());
}
});
}
/// Guarda el correo en la cola de envío, que lo envía en el siguiente lote. Requiere la
/// *feature* `queue`.
///
/// Pensado para los envíos masivos (avisos a todos los usuarios, informes periódicos...): el
/// trabajo `mail.queue` de `pagetop-cron` envía en cada ejecución, uno tras otro, como mucho
/// `mail.queue.batch_size` correos, así que muchos correos no sobrecargan el equipo ni el
/// servidor de correo. Para los que no pueden esperar al siguiente lote, como los de
/// recuperación de contraseña, usa [`send_later()`](Self::send_later).
///
/// El correo se completa y se compone al guardarlo, con el diseño común y en su idioma. Falla
/// aquí por los mismos motivos que [`send()`](Self::send) antes de la entrega (direcciones o
/// tipos MIME de los adjuntos no válidos, sin remitente o sin destinatarios), o si no se puede
/// guardar en la base de datos. Ya en la cola, un fallo temporal se reintenta con una espera
/// creciente, y un rechazo definitivo del servidor (SMTP 5xx) o el último intento fallido lo
/// dejan como fallido. Los correos guardados sobreviven a un reinicio.
///
/// La entrega es *al menos una vez*: si la aplicación se detiene justo después de que el
/// servidor acepte un correo y antes de anotarlo como enviado, se volverá a enviar. Lo mismo
/// ocurre si el servidor lo acepta pero tarda tanto en confirmarlo que se agota el tiempo
/// máximo de la entrega ([`MailError::Timeout`]), o si se cancela el trabajo a mitad de una
/// entrega (por su `timeout_secs` en `[cron.jobs."mail.queue"]` o por el tiempo máximo de
/// espera al detener la aplicación).
///
/// Con `transport = "log"` no se usa la cola: el correo se escribe enseguida en las trazas.
///
/// # Ejemplo
///
/// ```rust,no_run
/// # use pagetop::prelude::*;
/// # use pagetop_mail::prelude::*;
/// async fn notify_all(addresses: Vec<String>) -> Result<(), MailError> {
/// for address in addresses {
/// Email::new()
/// .with_to(address)
/// .with_subject("Parada programada")
/// .with_text("El servicio se detendrá el sábado de 8:00 a 10:00.")
/// .queue()
/// .await?;
/// }
/// Ok(())
/// }
/// ```
#[cfg(feature = "queue")]
pub async fn queue(self) -> Result<(), MailError> {
crate::queue::push(self).await
}
// Completa el correo antes de enviarlo: remitente y dirección de respuesta por defecto, el
// texto plano a partir del HTML si no tiene, y el documento HTML con el diseño común. El texto
// se genera antes del diseño para que no incluya su pie.

View file

@ -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
}
}

View file

@ -174,6 +174,41 @@ cabeceras, HTML con el diseño común, texto plano y adjuntos, sin enviar nada.
Si un correo sólo tiene HTML, al enviarlo se genera su texto plano a partir del contenido: bloques
separados por líneas, listas con guiones, y la dirección de cada enlace entre paréntesis.
## Cola de envío
Con la *feature* `queue`, los correos se guardan en una cola en la base de datos (con
`pagetop-seaorm`) y el trabajo `mail.queue` de `pagetop-cron` los envía por lotes:
```toml
[dependencies]
pagetop-mail = { version = "...", features = ["queue"] }
```
La cola usa la base de datos que la aplicación configura en `[database]` para `pagetop-seaorm`, con
la *feature* de su motor (`postgres`, `mysql` o `sqlite`), y crea en ella la tabla `mail_queue` al
arrancar. La tabla guarda cada mensaje completo y sin cifrar hasta entregarlo, o durante
`keep_failed_days` si falla: puede contener datos personales y enlaces de un solo uso, también en
las copias de seguridad de la base de datos.
- [`Email::send_later()`] guarda el correo y lo intenta enseguida. Si falla por un error temporal,
queda en la cola y se reintenta más tarde, también tras un reinicio.
- `Email::queue()` sólo lo guarda: cada ejecución del trabajo envía, uno tras otro, como mucho
`batch_size` correos, para que los envíos masivos no sobrecarguen el equipo ni el servidor de
correo.
La espera entre reintentos se duplica en cada intento; un rechazo definitivo del servidor (SMTP
5xx) o el último intento dejan el correo como fallido. Si el servidor no responde, el lote se
interrumpe y los demás correos esperan a la siguiente ejecución, sin gastar intentos. Los ajustes
van en `[mail.queue]`, y el ritmo, en la programación del trabajo:
```toml
[mail.queue]
batch_size = 50
[cron.jobs."mail.queue"]
schedule = "@delay 30s" # 30 s después de terminar cada lote (por defecto, 1 minuto).
```
## Transportes
Se elige en `mail.transport`:
@ -203,6 +238,7 @@ security = "none"
```
*/
#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc(
html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/assets/favicon.ico"
)]
@ -240,6 +276,9 @@ mod text;
mod transport;
#[cfg(feature = "queue")]
mod queue;
include_locales!(LOCALES_MAIL);
/// Prelude de `pagetop-mail`.
@ -262,6 +301,16 @@ impl Extension for Mail {
Lc::t("extension_description", &LOCALES_MAIL)
}
#[cfg(feature = "queue")]
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_seaorm::SeaORM, &pagetop_cron::Cron]
}
#[cfg(feature = "queue")]
fn actions(&self) -> Vec<ActionBox> {
actions![pagetop_cron::DeclareCronJobs::new(queue::declare_jobs)]
}
fn settings(&self) -> Option<&'static dyn LoadSettings> {
Some(&config::SETTINGS)
}
@ -270,6 +319,8 @@ impl Extension for Mail {
// Construir el transporte al arrancar valida los ajustes; preparar la aplicación varias
// veces en el mismo proceso (las pruebas lo hacen) reutiliza el ya construido.
transport::mailer()?.log_startup();
#[cfg(feature = "queue")]
queue::install().await?;
Ok(())
}

View file

@ -3,6 +3,8 @@ extension_description = Sends emails over SMTP, sendmail or files, with template
mail_footer = Message sent by { $app }.
queue_job_title = Send queued emails
# **< Email previews >**
preview_title = Email previews

View file

@ -3,6 +3,8 @@ extension_description = Envía correos por SMTP, sendmail o archivos, con planti
mail_footer = Mensaje enviado por { $app }.
queue_job_title = Enviar los correos de la cola
# **< Vistas previas de correos >**
preview_title = Vistas previas de correos

View file

@ -26,6 +26,11 @@
//!
//! Las pruebas de un mismo binario se ejecutan en paralelo y comparten estos correos: con
//! [`take_to()`] cada prueba recoge sólo los de sus destinatarios, sin llevarse los de otras.
//!
//! Con la *feature* `queue`, los correos de `Email::queue()` sólo llegan aquí cuando se ejecuta el
//! trabajo que vacía la cola. En las pruebas no se ejecuta solo: hay que lanzarlo con
//! `pagetop_cron::run_now("mail.queue")`. Los de [`Email::send_later()`] no esperan al trabajo,
//! pero llegan en segundo plano, como sin la cola.
use pagetop::prelude::*;
@ -85,3 +90,24 @@ pub(crate) fn push(email: Email, envelope_to: Vec<String>, raw: Vec<u8>) {
fn lock() -> MutexGuard<'static, Vec<SentEmail>> {
OUTBOX.lock().unwrap_or_else(PoisonError::into_inner)
}
// Correos completos de la cola de envío pendientes de entregar con este transporte, por su
// identificador en la cola. La cola sólo guarda el mensaje compuesto, y las pruebas necesitan el
// correo completo para consultarlo con `SentEmail::email()`.
#[cfg(feature = "queue")]
static QUEUED: Mutex<Vec<(i32, Email)>> = Mutex::new(Vec::new());
#[cfg(feature = "queue")]
pub(crate) fn hold(id: i32, email: Email) {
QUEUED
.lock()
.unwrap_or_else(PoisonError::into_inner)
.push((id, email));
}
#[cfg(feature = "queue")]
pub(crate) fn release(id: i32) -> Option<Email> {
let mut queued = QUEUED.lock().unwrap_or_else(PoisonError::into_inner);
let index = queued.iter().position(|(queued_id, _)| *queued_id == id)?;
Some(queued.swap_remove(index).1)
}

View file

@ -0,0 +1,398 @@
// Cola de envío persistente (*feature* `queue`).
//
// Los correos se guardan ya compuestos en la tabla `mail_queue`, y el trabajo `mail.queue` de
// `pagetop-cron` los envía por lotes. Una fila enviada se borra; una fallida se conserva con su
// último error. Para que varias instancias de la aplicación no envíen el mismo correo, cada una
// reserva la fila (`locked_until`) con una sentencia condicionada a que nadie la tenga reservada.
use pagetop::prelude::*;
use pagetop_cron::prelude::*;
use pagetop_seaorm::db::query::Expr;
use pagetop_seaorm::db::{
ColumnTrait, Condition, DbErr, EntityTrait, QueryFilter, QueryOrder, QuerySelect, Set, dbconn,
};
use pagetop_seaorm::install_migrations;
use crate::transport::{self, Composed};
use crate::{Email, LOCALES_MAIL, MailError, config, outbox};
use lettre::Address;
use lettre::address::Envelope;
mod entity;
mod migration;
use entity::{ActiveModel, Column, Entity, Model};
const JOB_KEY: &str = "mail.queue";
// Espera máxima admitida en `mail.queue.max_retry_secs`: un año.
const MAX_RETRY_SECS: u64 = 31_536_000;
// Comprueba los ajustes de `[mail.queue]` que tienen un rango limitado.
pub(crate) fn check_settings() -> Result<(), MailError> {
let queue = &config::SETTINGS.queue;
transport::check_range(
"mail.queue.batch_size",
queue.batch_size.into(),
1,
u32::MAX.into(),
)?;
transport::check_range(
"mail.queue.max_retry_secs",
queue.max_retry_secs,
1,
MAX_RETRY_SECS,
)
}
pub(crate) async fn install() -> Result<(), BoxError> {
install_migrations!(m20261028_000001_create_mail_queue)?;
Ok(())
}
pub(crate) fn declare_jobs(jobs: &mut CronJobs) {
jobs.add(
Job::new(
JOB_KEY,
Schedule::fixed_delay(Duration::minutes(1)),
process,
)
.with_title(Lc::t("queue_job_title", &LOCALES_MAIL)),
);
}
// `Email::queue()`: guarda el correo para el siguiente lote.
pub(crate) async fn push(email: Email) -> Result<(), MailError> {
let mailer = transport::mailer()?;
if mailer.is_log() {
return transport::log(mailer, email);
}
store(mailer, transport::compose(mailer, email)?).await
}
// `Email::send_later()`: guarda el correo ya reservado y lo intenta enseguida. Los errores de la
// entrega se anotan en la cola y en las trazas, y sólo devuelve los anteriores, salvo si no puede
// guardarlo: entonces lo entrega sin la cola y devuelve también los de la entrega.
pub(crate) async fn send_later(email: Email) -> Result<(), MailError> {
let mailer = transport::mailer()?;
if mailer.is_log() {
return transport::log(mailer, email);
}
let composed = transport::compose(mailer, email)?;
// Sin plaza para entregarlo (demasiados correos esperando turno), queda para el siguiente lote
// en lugar de esperar en memoria.
let Ok(ticket) = mailer.ticket() else {
trace::warn!(
"Too many emails waiting to be delivered, email \"{}\" left in the mail queue",
composed.email.subject()
);
return store(mailer, composed).await;
};
let Composed {
email,
envelope,
raw,
} = composed;
let subject = email.subject().to_owned();
let id = match insert(&envelope, &subject, raw.clone(), true).await {
Ok(id) => id,
Err(err) => {
trace::warn!(
"Cannot store email \"{subject}\" in the mail queue, sending it without the queue: \
{err}"
);
return transport::deliver_raw(mailer, ticket, &envelope, raw, Some(email)).await;
}
};
let result = transport::deliver_raw(mailer, ticket, &envelope, raw, Some(email)).await;
finish(id, &subject, 1, result).await;
Ok(())
}
// Guarda el correo compuesto para el siguiente lote.
async fn store(mailer: &transport::Mailer, composed: Composed) -> Result<(), MailError> {
let Composed {
email,
envelope,
raw,
} = composed;
let id = insert(&envelope, email.subject(), raw, false)
.await
.map_err(MailError::Queue)?;
if mailer.is_memory() {
outbox::hold(id, email);
}
Ok(())
}
// Ejecución del trabajo `mail.queue`: envía, uno tras otro, hasta `batch_size` correos pendientes.
// Un fallo del transporte (servidor que no responde...) interrumpe el lote: los demás correos
// fallarían igual tras esperar cada uno su tiempo máximo, así que esperan a la siguiente ejecución
// sin gastar intentos. También lo interrumpe que no haya plaza para entregar (demasiados correos de
// `send_later()` esperando turno), antes de reservar la fila.
async fn process(cx: JobContext) -> JobResult {
let mailer = transport::mailer()?;
give_up_exhausted().await?;
// Sólo los identificadores: cada mensaje se lee al reservarlo, para no tener en memoria a la
// vez los de todo el lote, que pueden llevar adjuntos.
let now = Utc::now();
let pending: Vec<(i32, i32)> = Entity::find()
.select_only()
.column(Column::Id)
.column(Column::Attempts)
.filter(Column::FailedAt.is_null())
.filter(Column::Attempts.lt(max_attempts()))
.filter(Column::NextAttemptAt.lte(now))
.filter(unlocked(now))
.order_by_asc(Column::NextAttemptAt)
.order_by_asc(Column::Id)
.limit(u64::from(config::SETTINGS.queue.batch_size))
.into_tuple()
.all(dbconn())
.await?;
for (id, attempts) in pending {
if cx.is_stopping() {
break;
}
let Ok(ticket) = mailer.ticket() else {
trace::warn!("Mail queue batch stopped: too many emails waiting to be delivered");
break;
};
if !claim(id, attempts).await? {
continue;
}
let Some(row) = Entity::find_by_id(id).one(dbconn()).await? else {
continue;
};
let email = outbox::release(id);
let result = match envelope(&row) {
Ok(envelope) => {
transport::deliver_raw(mailer, ticket, &envelope, row.message, email).await
}
Err(err) => Err(err),
};
let halt = matches!(&result, Err(err) if err.is_transport_failure());
finish(id, &row.subject, row.attempts, result).await;
if halt {
trace::warn!("Mail queue batch stopped: the transport is failing");
break;
}
}
purge_failed().await?;
Ok(())
}
// Guarda el correo compuesto y devuelve su identificador. Con `locked`, ya reservado y con el
// primer intento contado, para enviarlo enseguida sin que lo tome un lote.
async fn insert(
envelope: &Envelope,
subject: &str,
message: Vec<u8>,
locked: bool,
) -> Result<i32, DbErr> {
let now = Utc::now();
let mut envelope_to = String::new();
for address in envelope.to() {
if !envelope_to.is_empty() {
envelope_to.push('\n');
}
envelope_to.push_str(address.as_ref());
}
let row = ActiveModel {
envelope_from: Set(envelope.from().map(ToString::to_string)),
envelope_to: Set(envelope_to),
subject: Set(subject.to_owned()),
message: Set(message),
attempts: Set(i32::from(locked)),
next_attempt_at: Set(now),
locked_until: Set(locked.then(|| lock_until(now))),
last_error: Set(None),
failed_at: Set(None),
created_at: Set(now),
updated_at: Set(now),
..Default::default()
};
// Con `Entity::insert()` y no `ActiveModel::insert()`, que leería de vuelta la fila entera,
// mensaje incluido.
Ok(Entity::insert(row).exec(dbconn()).await?.last_insert_id)
}
// Reserva la fila y cuenta el intento, sólo si sigue igual que al leerla: si otro proceso se
// adelanta, no afecta a ninguna fila y el correo se deja para él.
async fn claim(id: i32, attempts: i32) -> Result<bool, DbErr> {
let now = Utc::now();
let result = Entity::update_many()
.col_expr(Column::LockedUntil, Expr::value(lock_until(now)))
.col_expr(Column::Attempts, Expr::value(attempts + 1))
.col_expr(Column::UpdatedAt, Expr::value(now))
.filter(Column::Id.eq(id))
.filter(Column::Attempts.eq(attempts))
.filter(Column::FailedAt.is_null())
.filter(unlocked(now))
.exec(dbconn())
.await?;
Ok(result.rows_affected == 1)
}
// Anota el resultado del intento número `attempts`: borra el correo enviado, o lo deja para
// reintentarlo más tarde o como fallido. Si no se puede anotar, el correo enviado se volverá a
// enviar al caducar la reserva.
async fn finish(id: i32, subject: &str, attempts: i32, result: Result<(), MailError>) {
let update = match result {
Ok(()) => Entity::delete_by_id(id).exec(dbconn()).await.map(|_| ()),
Err(err) => {
let now = Utc::now();
let message = err.describe();
let mut update = Entity::update_many()
.col_expr(Column::LockedUntil, Expr::value(None::<DateTime<Utc>>))
.col_expr(Column::UpdatedAt, Expr::value(now));
if err.is_permanent() || attempts >= max_attempts() {
trace::error!(
"Cannot send email \"{subject}\" (attempt {attempts}), giving up: {message}"
);
update = update.col_expr(Column::FailedAt, Expr::value(now));
} else {
let queue = &config::SETTINGS.queue;
let retry_at =
now + retry_delay(queue.retry_base_secs, queue.max_retry_secs, attempts);
trace::warn!(
"Cannot send email \"{subject}\" (attempt {attempts}), retrying at \
{retry_at}: {message}"
);
update = update.col_expr(Column::NextAttemptAt, Expr::value(retry_at));
}
// Si el envío tardó más que la reserva, otro proceso puede haber tomado ya la fila y
// contado otro intento: entonces el resultado es suyo y éste se descarta.
update
.col_expr(Column::LastError, Expr::value(message))
.filter(Column::Id.eq(id))
.filter(Column::Attempts.eq(attempts))
.exec(dbconn())
.await
.map(|_| ())
}
};
if let Err(err) = update {
trace::error!(
"Cannot update email \"{subject}\" in the mail queue, it may be sent again: {err}"
);
}
}
// Da por fallidos los correos sin intentos pendientes que no están reservados: el último intento se
// interrumpió (el proceso cayó a mitad de envío) o se redujo `mail.queue.max_attempts`.
async fn give_up_exhausted() -> Result<(), DbErr> {
let now = Utc::now();
Entity::update_many()
.col_expr(Column::FailedAt, Expr::value(now))
.col_expr(Column::LockedUntil, Expr::value(None::<DateTime<Utc>>))
.col_expr(Column::LastError, Expr::value("no attempts left"))
.col_expr(Column::UpdatedAt, Expr::value(now))
.filter(Column::FailedAt.is_null())
.filter(Column::Attempts.gte(max_attempts()))
.filter(unlocked(now))
.exec(dbconn())
.await?;
Ok(())
}
// Borra los correos fallidos más antiguos que `mail.queue.keep_failed_days`. Con 0, o con tantos
// días que la fecha límite no se puede representar, no borra ninguno.
async fn purge_failed() -> Result<(), DbErr> {
let days = config::SETTINGS.queue.keep_failed_days;
if days == 0 {
return Ok(());
}
let Some(before) = Utc::now().checked_sub_signed(Duration::days(i64::from(days))) else {
return Ok(());
};
Entity::delete_many()
.filter(Column::FailedAt.lt(before))
.exec(dbconn())
.await?;
Ok(())
}
// Filas sin reservar o con la reserva caducada.
fn unlocked(now: DateTime<Utc>) -> Condition {
Condition::any()
.add(Column::LockedUntil.is_null())
.add(Column::LockedUntil.lt(now))
}
// Fin de la reserva de una fila mientras se envía; pasado, si el proceso cayó a mitad de envío,
// otro puede volver a enviarla. Dura el triple del tiempo máximo de una entrega (15 minutos por
// defecto), para que nadie tome la fila mientras su envío sigue en curso: en SMTP, al agotarse ese
// tiempo sólo se deja de esperar, y el envío puede seguir hasta fallar por su cuenta.
fn lock_until(now: DateTime<Utc>) -> DateTime<Utc> {
let secs = config::SETTINGS.delivery_timeout_secs.saturating_mul(3);
now + Duration::seconds(i64::try_from(secs).unwrap_or(i64::MAX))
}
fn max_attempts() -> i32 {
i32::try_from(config::SETTINGS.queue.max_attempts.max(1)).unwrap_or(i32::MAX)
}
// Espera antes del siguiente intento tras `attempts` intentos fallidos: `base_secs`, el doble en
// cada uno, hasta `max_secs` y nunca más de un año.
fn retry_delay(base_secs: u64, max_secs: u64, attempts: i32) -> Duration {
let doublings = u32::try_from(attempts.saturating_sub(1))
.unwrap_or(0)
.min(32);
let secs = base_secs
.saturating_mul(1 << doublings)
.min(max_secs.min(MAX_RETRY_SECS));
Duration::seconds(i64::try_from(secs).unwrap_or(i64::MAX))
}
// Reconstruye el sobre guardado.
fn envelope(row: &Model) -> Result<Envelope, MailError> {
let from = row.envelope_from.as_deref().map(address).transpose()?;
let to = row
.envelope_to
.lines()
.map(address)
.collect::<Result<Vec<_>, _>>()?;
Envelope::new(from, to).map_err(MailError::Build)
}
fn address(value: &str) -> Result<Address, MailError> {
value.parse().map_err(|source| MailError::InvalidAddress {
address: value.to_owned(),
source,
})
}
#[cfg(test)]
mod tests {
use super::{Duration, MailError, address, retry_delay};
#[test]
fn transport_failures_stop_the_batch_but_rejected_emails_do_not() {
assert!(MailError::Timeout(300).is_transport_failure());
assert!(MailError::Interrupted.is_transport_failure());
assert!(MailError::Overloaded.is_transport_failure());
let invalid = address("not an address").unwrap_err();
assert!(invalid.is_permanent());
assert!(!invalid.is_transport_failure());
}
#[test]
fn retry_delay_doubles_after_each_attempt_up_to_the_maximum() {
const DAY: u64 = 86_400;
assert_eq!(retry_delay(60, DAY, 1), Duration::seconds(60));
assert_eq!(retry_delay(60, DAY, 2), Duration::seconds(120));
assert_eq!(retry_delay(60, DAY, 4), Duration::seconds(480));
assert_eq!(retry_delay(60, DAY, 20), Duration::days(1));
assert_eq!(retry_delay(u64::MAX, DAY, 1000), Duration::days(1));
assert_eq!(retry_delay(60, DAY, 0), Duration::seconds(60));
assert_eq!(retry_delay(60, 300, 4), Duration::seconds(300));
assert_eq!(retry_delay(u64::MAX, u64::MAX, 1), Duration::days(365));
}
}

View file

@ -0,0 +1,29 @@
// Entidad de la tabla `mail_queue`: un correo pendiente de entregar o fallido.
use pagetop_seaorm::db::*;
#[derive(Clone, Debug, DeriveEntityModel, PartialEq)]
#[sea_orm(table_name = "mail_queue")]
pub struct Model {
#[sea_orm(primary_key)]
pub id: i32,
pub envelope_from: Option<String>,
// Destinatarios del sobre, uno por línea.
pub envelope_to: String,
pub subject: String,
// Mensaje compuesto en formato RFC 5322.
pub message: Vec<u8>,
pub attempts: i32,
pub next_attempt_at: DateTimeUtc,
// Reserva de quien lo está enviando; pasada la fecha, otro proceso puede volver a enviarlo.
pub locked_until: Option<DateTimeUtc>,
pub last_error: Option<String>,
pub failed_at: Option<DateTimeUtc>,
pub created_at: DateTimeUtc,
pub updated_at: DateTimeUtc,
}
#[derive(Clone, Copy, Debug, DeriveRelation, EnumIter)]
pub enum Relation {}
impl ActiveModelBehavior for ActiveModel {}

View file

@ -0,0 +1 @@
pub mod m20261028_000001_create_mail_queue;

View file

@ -0,0 +1,68 @@
use pagetop_seaorm::migration::*;
use sea_orm::DbBackend;
pub struct Migration;
#[pagetop::async_trait]
impl MigrationTrait for Migration {
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
// En MySQL, `BLOB` admite sólo 64 KB, menos que muchos correos con adjuntos.
let message = if manager.get_database_backend() == DbBackend::MySql {
ColumnDef::new(MailQueue::Message)
.custom(Alias::new("longblob"))
.not_null()
.take()
} else {
blob(MailQueue::Message)
};
manager
.create_table(
table_auto(MailQueue::Table)
.col(pk_auto(MailQueue::Id))
.col(string_null(MailQueue::EnvelopeFrom))
.col(text(MailQueue::EnvelopeTo))
.col(text(MailQueue::Subject))
.col(message)
.col(integer(MailQueue::Attempts).default(0))
.col(timestamp(MailQueue::NextAttemptAt).default(Expr::current_timestamp()))
.col(timestamp_null(MailQueue::LockedUntil))
.col(text_null(MailQueue::LastError))
.col(timestamp_null(MailQueue::FailedAt))
.to_owned(),
)
.await?;
// Cada lote busca los correos cuyo próximo intento ya ha llegado.
manager
.create_index(
Index::create()
.name("idx_mail_queue_next_attempt_at")
.table(MailQueue::Table)
.col(MailQueue::NextAttemptAt)
.if_not_exists()
.to_owned(),
)
.await
}
async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
manager
.drop_table(Table::drop().table(MailQueue::Table).to_owned())
.await
}
}
#[derive(DeriveIden)]
pub enum MailQueue {
Table,
Id,
EnvelopeFrom,
EnvelopeTo,
Subject,
Message,
Attempts,
NextAttemptAt,
LockedUntil,
LastError,
FailedAt,
}

View file

@ -5,31 +5,42 @@ use pagetop::prelude::*;
use crate::config::{self, MailTransport, SmtpSecurity, SmtpSettings};
use crate::{Email, MailError, Mailbox, outbox};
use lettre::Transport as _;
use lettre::address::Envelope;
use lettre::transport::smtp::PoolConfig;
use lettre::transport::smtp::authentication::Credentials;
use lettre::transport::smtp::client::{Tls, TlsParameters};
use lettre::transport::smtp::extension::ClientId;
use lettre::{
Address, AsyncFileTransport, AsyncSendmailTransport, AsyncSmtpTransport, AsyncTransport,
Address, AsyncFileTransport, AsyncSendmailTransport, AsyncTransport, SmtpTransport,
Tokio1Executor,
};
use std::path::PathBuf;
use std::sync::OnceLock;
use tokio::sync::{Semaphore, SemaphorePermit};
// Transporte y direcciones por defecto, construidos una sola vez a partir de los ajustes.
static MAILER: OnceLock<Mailer> = OnceLock::new();
pub(crate) struct Mailer {
transport: Transport,
// Turnos de envío: como mucho tantas entregas a la vez.
slots: Semaphore,
// Plazas para las entregas en curso o que esperan turno.
tickets: Semaphore,
from: Option<Mailbox>,
reply_to: Option<Mailbox>,
redirect_to: Option<Address>,
}
// Plaza para una entrega, obtenida con `Mailer::ticket()`.
pub(crate) type Ticket = SemaphorePermit<'static>;
enum Transport {
Smtp(AsyncSmtpTransport<Tokio1Executor>),
// El transporte SMTP síncrono, no el asíncrono: ver `deliver_raw()`.
Smtp(SmtpTransport),
Sendmail(AsyncSendmailTransport<Tokio1Executor>),
File(AsyncFileTransport<Tokio1Executor>),
Log,
@ -50,45 +61,146 @@ pub(crate) fn mailer() -> Result<&'static Mailer, MailError> {
pub(crate) async fn deliver(email: Email) -> Result<(), MailError> {
let mailer = mailer()?;
let email = email.prepare(mailer.from.as_ref(), mailer.reply_to.as_ref());
// Escribirlo en las trazas no necesita remitente: así una aplicación sin configurar muestra sus
// correos aunque no tenga `mail.from`.
if let Transport::Log = mailer.transport {
return log_email(&email, mailer.redirect_to.as_ref());
if mailer.is_log() {
return log(mailer, email);
}
let ticket = mailer.ticket()?;
let Composed {
email,
envelope,
raw,
} = compose(mailer, email)?;
deliver_raw(mailer, ticket, &envelope, raw, Some(email)).await
}
// Correo ya completo y compuesto, listo para entregarlo o guardarlo en la cola de envío.
pub(crate) struct Composed {
// El correo completo, con las direcciones por defecto y el documento HTML con el diseño común.
pub(crate) email: Email,
// El sobre con los destinatarios originales: `mail.redirect_to` se aplica al entregarlo.
pub(crate) envelope: Envelope,
// El mensaje en formato RFC 5322.
pub(crate) raw: Vec<u8>,
}
pub(crate) fn compose(mailer: &Mailer, email: Email) -> Result<Composed, MailError> {
let email = email.prepare(mailer.from.as_ref(), mailer.reply_to.as_ref());
let message = email.to_message()?;
Ok(Composed {
envelope: message.envelope().clone(),
raw: message.formatted(),
email,
})
}
// Entrega un mensaje ya compuesto, con la plaza obtenida antes con `Mailer::ticket()`. Espera su
// turno de envío sin ocupar un hilo. El transporte "memory" guarda también el correo completo, si
// se conoce, para que las pruebas lo consulten.
//
// SMTP usa el transporte síncrono de `lettre` en un hilo de `spawn_blocking`, porque el asíncrono
// (0.11) sólo aplica `mail.smtp.timeout_secs` a la conexión TCP: un servidor que deja de responder
// colgaría el envío para siempre. El síncrono lo aplica a cada lectura y escritura, y como un hilo
// no se cancela, cada envío termina o falla (salvo en el saludo TLS, ver `within_time_limit()`), y
// `lettre` descarta la conexión que falla: nunca vuelve a su *pool* una conexión a medio enviar,
// cuyas respuestas quedarían desfasadas.
pub(crate) async fn deliver_raw(
mailer: &'static Mailer,
_ticket: Ticket,
envelope: &Envelope,
raw: Vec<u8>,
email: Option<Email>,
) -> Result<(), MailError> {
// Sólo "memory" usa el correo completo. Los demás lo liberan antes de esperar turno: sus
// adjuntos también van en el mensaje compuesto, y cada correo en espera los tendría dos veces.
let email = email.filter(|_| matches!(mailer.transport, Transport::Memory));
let redirected;
let envelope = match &mailer.redirect_to {
Some(address) => Envelope::new(message.envelope().from().cloned(), vec![address.clone()])
.map_err(MailError::Build)?,
None => message.envelope().clone(),
Some(address) => {
redirected = Envelope::new(envelope.from().cloned(), vec![address.clone()])
.map_err(MailError::Build)?;
&redirected
}
None => envelope,
};
let raw = message.formatted();
match &mailer.transport {
Transport::Smtp(smtp) => {
smtp.send_raw(&envelope, &raw)
let (smtp, envelope) = (smtp.clone(), envelope.clone());
// Cada envío en curso ocupa un hilo del *pool* de bloqueo de Tokio, que comparten otras
// tareas (p. ej. el cálculo de contraseñas): sin turnos, una avalancha de correos con
// el servidor lento lo agotaría. El turno pasa al hilo para liberarse cuando termina el
// envío, no cuando se deja de esperarlo.
let delivery = async move {
let slot = mailer.slot().await;
tokio::task::spawn_blocking(move || {
let _slot = slot;
smtp.send_raw(&envelope, &raw)
})
.await
.map_err(MailError::Smtp)?;
};
match within_time_limit(delivery).await? {
Ok(result) => result.map_err(MailError::Smtp)?,
Err(err) if err.is_panic() => std::panic::resume_unwind(err.into_panic()),
Err(_) => return Err(MailError::Interrupted),
};
}
Transport::Sendmail(sendmail) => {
sendmail
.send_raw(&envelope, &raw)
.await
.map_err(MailError::Sendmail)?;
within_time_limit(async {
let _slot = mailer.slot().await;
sendmail.send_raw(envelope, &raw).await
})
.await?
.map_err(MailError::Sendmail)?;
}
Transport::File(file) => {
file.send_raw(&envelope, &raw)
.await
.map_err(MailError::File)?;
within_time_limit(async {
let _slot = mailer.slot().await;
file.send_raw(envelope, &raw).await
})
.await?
.map_err(MailError::File)?;
}
Transport::Memory => {
outbox::push(email, recipients(&envelope), raw);
}
Transport::Log => unreachable!("log transport is handled before building the message"),
Transport::Memory => match email {
Some(email) => outbox::push(email, recipients(envelope), raw),
None => trace::warn!(
"Email for {} not kept in memory: it was queued by another process or before a \
restart",
recipients(envelope).join(", ")
),
},
// Sólo llega aquí un correo que se guardó en la cola con otro transporte.
Transport::Log => trace::info!(
"Email not delivered (mail.transport = \"log\")\nTo: {}\n\n{}",
recipients(envelope).join(", "),
String::from_utf8_lossy(&raw)
),
}
Ok(())
}
// Limita el tiempo de una entrega completa, como red de seguridad: la espera del turno de envío,
// *sendmail* y los archivos no tienen límite propio, y en SMTP `mail.smtp.timeout_secs` no cubre el
// saludo TLS con `security = "tls"`, que `lettre` hace antes de fijar los límites del *socket*.
//
// Cancelar *sendmail* es seguro (`lettre` mata el proceso). En SMTP sólo se deja de esperar: el
// hilo sigue hasta terminar o fallar por su cuenta, y si termina, el correo se habrá entregado
// aunque aquí se haya dado por fallido (la cola lo reintentará: entrega «al menos una vez»). En el
// saludo TLS, sin límite, el hilo sigue hasta que el sistema da la conexión por perdida, o para
// siempre si el servidor la mantiene viva sin responder, y retiene su turno mientras tanto.
async fn within_time_limit<T>(delivery: impl Future<Output = T>) -> Result<T, MailError> {
let secs = config::SETTINGS.delivery_timeout_secs;
tokio::time::timeout(std::time::Duration::from_secs(secs), delivery)
.await
.map_err(|_| MailError::Timeout(secs))
}
// Completa el correo y lo escribe en las trazas. No necesita remitente: así una aplicación sin
// configurar muestra sus correos aunque no tenga `mail.from`.
pub(crate) fn log(mailer: &Mailer, email: Email) -> Result<(), MailError> {
let email = email.prepare(mailer.from.as_ref(), mailer.reply_to.as_ref());
log_email(&email, mailer.redirect_to.as_ref())
}
// Escribe el correo en las trazas en lugar de enviarlo (`transport = "log"`). Valida las
// direcciones igual que al enviar, salvo que falte el remitente.
fn log_email(email: &Email, redirect_to: Option<&Address>) -> Result<(), MailError> {
@ -121,8 +233,8 @@ fn log_email(email: &Email, redirect_to: Option<&Address>) -> Result<(), MailErr
Ok(())
}
// Completa un correo como si se fuera a enviar, para mostrar su vista previa. Si los ajustes no
// son válidos (la aplicación no habría arrancado), se muestra sin las direcciones por defecto.
// Completa un correo como si se fuera a enviar, para mostrar su vista previa. Si los ajustes no son
// válidos (la aplicación no habría arrancado), se muestra sin las direcciones por defecto.
pub(crate) fn prepare_preview(email: Email) -> Email {
let mailer = mailer().ok();
email.prepare(
@ -137,8 +249,55 @@ fn recipients(envelope: &Envelope) -> Vec<String> {
}
impl Mailer {
// Indica si los correos sólo se escriben en las trazas (`transport = "log"`).
pub(crate) fn is_log(&self) -> bool {
matches!(self.transport, Transport::Log)
}
// Reserva una plaza para entregar un correo. Si ya esperan turno `mail.max_waiting` entregas
// por cada envío simultáneo, falla enseguida con `MailError::Overloaded`: en una avalancha de
// correos que el servidor no despacha a tiempo, acumularlos en memoria sólo retrasaría el
// colapso, y cada uno acabaría fallando igualmente por tiempo agotado.
pub(crate) fn ticket(&'static self) -> Result<Ticket, MailError> {
self.tickets
.try_acquire()
.map_err(|_| MailError::Overloaded)
}
// Espera un turno de envío.
async fn slot(&self) -> SemaphorePermit<'_> {
self.slots
.acquire()
.await
.expect("mail delivery slots are never closed")
}
// Indica si los correos se guardan en memoria para las pruebas (`transport = "memory"`).
#[cfg(feature = "queue")]
pub(crate) fn is_memory(&self) -> bool {
matches!(self.transport, Transport::Memory)
}
fn from_settings() -> Result<Self, MailError> {
let settings = &*config::SETTINGS;
check_range(
"mail.delivery_timeout_secs",
settings.delivery_timeout_secs,
1,
86_400,
)?;
#[cfg(feature = "queue")]
crate::queue::check_settings()?;
let slots = match settings.transport {
MailTransport::Smtp => slots("mail.smtp.pool_max_size", settings.smtp.pool_max_size)?,
MailTransport::Sendmail => slots(
"mail.sendmail.max_concurrent",
settings.sendmail.max_concurrent,
)?,
MailTransport::File => slots("mail.file.max_concurrent", settings.file.max_concurrent)?,
// Sin turnos: se entregan al momento.
MailTransport::Log | MailTransport::Memory => 1,
};
let transport = match settings.transport {
MailTransport::Smtp => Transport::Smtp(smtp_transport(&settings.smtp)?),
MailTransport::Sendmail => Transport::Sendmail(match &settings.sendmail.command {
@ -178,6 +337,8 @@ impl Mailer {
}
Ok(Mailer {
transport,
slots: Semaphore::new(slots),
tickets: Semaphore::new(tickets(slots, settings.max_waiting)),
from: setting_mailbox("mail.from", settings.from.as_deref())?,
reply_to: setting_mailbox("mail.reply_to", settings.reply_to.as_deref())?,
redirect_to,
@ -196,6 +357,15 @@ impl Mailer {
(tests only)"
),
Transport::Smtp(_) | Transport::Sendmail(_) | Transport::File(_) => {
if matches!(self.transport, Transport::Smtp(_))
&& settings.delivery_timeout_secs
<= settings.smtp.timeout_secs.saturating_mul(2)
{
trace::warn!(
"mail.delivery_timeout_secs should be well above twice \
mail.smtp.timeout_secs: slow but valid deliveries may fail"
);
}
if self.from.is_none() {
trace::warn!("mail.from is not set: every email must set its own sender");
}
@ -224,7 +394,23 @@ impl Mailer {
}
}
fn smtp_transport(smtp: &SmtpSettings) -> Result<AsyncSmtpTransport<Tokio1Executor>, MailError> {
// Envíos simultáneos según el ajuste `key`, que debe ser al menos uno.
fn slots(key: &'static str, setting: u32) -> Result<usize, MailError> {
check_range(key, setting.into(), 1, u32::MAX.into())?;
Ok(usize::try_from(setting)
.unwrap_or(usize::MAX)
.min(Semaphore::MAX_PERMITS))
}
// Plazas para las entregas: las que caben en curso y las que pueden esperar turno.
fn tickets(slots: usize, max_waiting: u32) -> usize {
let waiting = usize::try_from(max_waiting).unwrap_or(usize::MAX);
slots
.saturating_mul(waiting.saturating_add(1))
.min(Semaphore::MAX_PERMITS)
}
fn smtp_transport(smtp: &SmtpSettings) -> Result<SmtpTransport, MailError> {
let tls_parameters = || {
TlsParameters::builder(smtp.host.clone())
.dangerous_accept_invalid_certs(smtp.accept_invalid_certs)
@ -237,7 +423,7 @@ fn smtp_transport(smtp: &SmtpSettings) -> Result<AsyncSmtpTransport<Tokio1Execut
SmtpSecurity::StartTls => (Tls::Required(tls_parameters()?), 587),
SmtpSecurity::Tls => (Tls::Wrapper(tls_parameters()?), 465),
};
let mut builder = AsyncSmtpTransport::<Tokio1Executor>::builder_dangerous(&smtp.host)
let mut builder = SmtpTransport::builder_dangerous(&smtp.host)
.port(smtp.port.unwrap_or(default_port))
.tls(tls)
.timeout(Some(std::time::Duration::from_secs(smtp.timeout_secs)))
@ -266,9 +452,42 @@ fn setting_mailbox(key: &'static str, value: Option<&str>) -> Result<Option<Mail
Ok(Some(mailbox))
}
// Comprueba que un ajuste numérico esté entre `min` y `max`, ambos incluidos.
pub(crate) fn check_range(
key: &'static str,
value: u64,
min: u64,
max: u64,
) -> Result<(), MailError> {
if (min..=max).contains(&value) {
return Ok(());
}
Err(invalid_setting(
key,
MailError::OutOfRange { value, min, max },
))
}
fn invalid_setting(key: &'static str, source: MailError) -> MailError {
MailError::InvalidSetting {
key,
source: Box::new(source),
}
}
#[cfg(test)]
mod tests {
use super::check_range;
#[test]
fn out_of_range_settings_name_the_key_and_the_range() {
let err = check_range("mail.delivery_timeout_secs", 0, 1, 86_400).unwrap_err();
assert_eq!(
err.describe(),
"invalid mail setting \"mail.delivery_timeout_secs\": 0 is not between 1 and 86400"
);
assert!(check_range("mail.delivery_timeout_secs", 1, 1, 86_400).is_ok());
assert!(check_range("mail.delivery_timeout_secs", 86_400, 1, 86_400).is_ok());
assert!(check_range("mail.delivery_timeout_secs", 86_401, 1, 86_400).is_err());
}
}

View file

@ -0,0 +1,200 @@
// Needs the `queue` feature. `config/common.toml` gives these tests an in-memory SQLite database
// with a single connection, the memory transport and `batch_size = 2`. The scheduler never starts
// in tests, so the queue only runs through `run_now()`.
//
// Every scenario shares the same queue table and batches pick the oldest emails first, so they run
// one after another in a single test (and a single runtime, which also keeps the database
// connection alive).
use pagetop::prelude::*;
use pagetop_mail::outbox;
use pagetop_mail::prelude::*;
use pagetop_seaorm::db::sea_orm::Statement;
use pagetop_seaorm::db::{ConnectionTrait, dbconn, execute};
const JOB: &str = "mail.queue";
struct TestApp;
#[async_trait]
impl Extension for TestApp {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_mail::Mail]
}
}
fn email(to: &str, subject: &str) -> Email {
Email::new()
.with_to(to)
.with_subject(subject)
.with_text("Queued email")
}
async fn run_job() {
let run = pagetop_cron::run_now(JOB).await.unwrap();
assert!(
run.outcome().is_success(),
"{JOB} failed: {:?}",
run.outcome()
);
}
async fn count(condition: &str) -> i64 {
let conn = dbconn();
let sql = format!("SELECT COUNT(*) AS n FROM mail_queue WHERE {condition}");
let row = conn
.query_one(Statement::from_string(conn.get_database_backend(), sql))
.await
.unwrap()
.unwrap();
row.try_get("", "n").unwrap()
}
async fn update(set: &str, subject: &str) {
execute(format!(
"UPDATE mail_queue SET {set} WHERE subject = '{subject}'"
))
.await
.unwrap();
}
fn subjects(to: &str) -> Vec<String> {
outbox::take_to(to)
.iter()
.map(|sent| sent.email().subject().to_owned())
.collect()
}
#[pagetop::test]
async fn queue_sends_in_batches_and_gives_up() {
Application::prepare(&TestApp).await;
queued_emails_wait_for_the_job_and_go_in_batches().await;
send_later_delivers_at_once_and_leaves_nothing_queued().await;
reserved_emails_wait_until_the_reservation_expires().await;
permanent_errors_fail_at_the_first_attempt().await;
emails_without_attempts_left_fail_and_are_purged_later().await;
}
async fn queued_emails_wait_for_the_job_and_go_in_batches() {
let to = "batch@example.com";
for n in 1..=3 {
email(to, &format!("Batch {n}")).queue().await.unwrap();
}
assert!(
subjects(to).is_empty(),
"queued emails must wait for the job"
);
assert_eq!(count("subject LIKE 'Batch %'").await, 3);
run_job().await;
assert_eq!(
subjects(to),
["Batch 1", "Batch 2"],
"one batch, oldest first"
);
assert_eq!(
count("subject LIKE 'Batch %'").await,
1,
"sent emails are deleted"
);
run_job().await;
let sent = outbox::take_to(to);
assert_eq!(sent.len(), 1);
assert_eq!(sent[0].email().subject(), "Batch 3");
assert!(sent[0].raw().contains("Subject: Batch 3"));
assert_eq!(count("subject LIKE 'Batch %'").await, 0);
}
async fn send_later_delivers_at_once_and_leaves_nothing_queued() {
let to = "later@example.com";
email(to, "Later").send_later();
let mut sent = Vec::new();
for _ in 0..100 {
sent.extend(subjects(to));
if !sent.is_empty() && count("subject = 'Later'").await == 0 {
break;
}
tokio::time::sleep(std::time::Duration::from_millis(50)).await;
}
assert_eq!(sent, ["Later"], "send_later() must not wait for the job");
assert_eq!(
count("subject = 'Later'").await,
0,
"the sent email must leave the queue"
);
}
async fn reserved_emails_wait_until_the_reservation_expires() {
let to = "reserved@example.com";
email(to, "Reserved").queue().await.unwrap();
update("locked_until = '2099-01-01 00:00:00'", "Reserved").await;
run_job().await;
assert!(subjects(to).is_empty(), "another process is sending it");
update("locked_until = '2000-01-01 00:00:00'", "Reserved").await;
run_job().await;
assert_eq!(
subjects(to),
["Reserved"],
"an expired reservation is released"
);
}
async fn permanent_errors_fail_at_the_first_attempt() {
let to = "invalid@example.com";
email(to, "Invalid").queue().await.unwrap();
// A stored envelope that is no longer valid cannot be fixed by retrying.
update("envelope_to = 'not an address'", "Invalid").await;
run_job().await;
assert!(subjects(to).is_empty());
assert_eq!(
count(
"subject = 'Invalid' AND attempts = 1 AND failed_at IS NOT NULL \
AND locked_until IS NULL AND last_error LIKE 'invalid email address%'"
)
.await,
1,
"a permanent error gives up without retrying"
);
}
async fn emails_without_attempts_left_fail_and_are_purged_later() {
let to = "exhausted@example.com";
email(to, "Exhausted").queue().await.unwrap();
// The default `max_attempts` is 5: the last attempt was interrupted before it finished.
update(
"attempts = 5, locked_until = '2000-01-01 00:00:00'",
"Exhausted",
)
.await;
run_job().await;
assert!(subjects(to).is_empty(), "no attempts left");
assert_eq!(
count(
"subject = 'Exhausted' AND failed_at IS NOT NULL AND last_error = 'no attempts left'"
)
.await,
1
);
// Failed emails are kept for `keep_failed_days` (30 by default).
run_job().await;
assert_eq!(
count("subject = 'Exhausted'").await,
1,
"recent failures are kept"
);
update("failed_at = '2000-01-01 00:00:00'", "Exhausted").await;
run_job().await;
assert_eq!(
count("subject = 'Exhausted'").await,
0,
"old failures are purged"
);
}