✨ (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
2
Cargo.lock
generated
2
Cargo.lock
generated
|
|
@ -2236,6 +2236,8 @@ dependencies = [
|
|||
"lettre",
|
||||
"mime_guess",
|
||||
"pagetop",
|
||||
"pagetop-cron",
|
||||
"pagetop-seaorm",
|
||||
"serde",
|
||||
"thiserror",
|
||||
"tokio",
|
||||
|
|
|
|||
|
|
@ -116,23 +116,44 @@ max_pool_size = 5 # Número máximo de conexiones simultáneas
|
|||
# **< pagetop-mail >********************************************************************************
|
||||
|
||||
[mail]
|
||||
transport = "log" # Entrega de los correos:
|
||||
transport = "log" # Entrega de los correos:
|
||||
# "smtp" -> servidor SMTP ([mail.smtp]).
|
||||
# "sendmail" -> programa sendmail local ([mail.sendmail]).
|
||||
# "file" -> un archivo .eml por correo ([mail.file]).
|
||||
# "log" -> se escriben en las trazas, sin enviarlos.
|
||||
# "memory" -> se guardan en memoria (sólo pruebas).
|
||||
#from = "Mi Aplicación <no-reply@example.com>"
|
||||
#from = "Mi Aplicación <no-reply@example.com>"
|
||||
# Remitente por defecto, con o sin nombre. Sin valor, cada
|
||||
# correo debe indicar el suyo para enviarse (salvo con "log").
|
||||
# Los de pagetop-user no lo indican: configúralo siempre.
|
||||
#reply_to = "soporte@example.com" # Dirección de respuesta por defecto.
|
||||
#redirect_to = "pruebas@example.com" # Entrega todos los correos sólo a esta dirección, sin
|
||||
#reply_to = "soporte@example.com"
|
||||
# Dirección de respuesta por defecto.
|
||||
#redirect_to = "pruebas@example.com"
|
||||
# Entrega todos los correos sólo a esta dirección, sin
|
||||
# cambiar sus cabeceras (entornos de pruebas o preproducción).
|
||||
#base_url = "https://example.com" # URL pública para los enlaces de los correos. Sin valor,
|
||||
#base_url = "https://example.com"
|
||||
# URL pública para los enlaces de los correos. Sin valor,
|
||||
# http://{bind_address}:{bind_port} (sólo para desarrollo).
|
||||
previews = false # Vistas previas de los correos en /mail/preview. Sólo en
|
||||
previews = false # Vistas previas de los correos en /mail/preview. Sólo en
|
||||
# desarrollo: cualquiera que conozca la ruta las ve.
|
||||
delivery_timeout_secs = 300 # Tiempo máximo de cada entrega, en segundos (1 a 86400),
|
||||
# incluida la espera de turno. Recomendado: 300. Reducirlo (60
|
||||
# o 120) con un servidor cercano y rápido detecta antes los
|
||||
# fallos, pero debe superar con holgura 2 x timeout_secs de
|
||||
# [mail.smtp], y da por fallidos más correos que un servidor
|
||||
# lento sí acepta (con la cola, se entregan por duplicado).
|
||||
# Aumentarlo sólo con servidores muy lentos o adjuntos grandes:
|
||||
# los correos retienen su turno más tiempo y, con la cola, una
|
||||
# entrega interrumpida espera el triple de este tiempo para
|
||||
# reintentarse.
|
||||
max_waiting = 100 # Correos que pueden esperar turno por cada envío simultáneo
|
||||
# (pool_max_size o max_concurrent); con más, la entrega falla
|
||||
# enseguida (con la feature "queue", send_later() los deja en
|
||||
# la cola). 0 -> ninguno espera. No se recomiendan valores
|
||||
# mayores: cada correo en espera ocupa memoria con sus
|
||||
# adjuntos, y la espera cuenta en delivery_timeout_secs, así
|
||||
# que los últimos fallarían igualmente. Con poca memoria o
|
||||
# adjuntos grandes, conviene reducirlo.
|
||||
|
||||
[mail.smtp] # Servidor SMTP (transport = "smtp").
|
||||
host = "localhost" # Servidor.
|
||||
|
|
@ -146,15 +167,53 @@ security = "starttls" # Cifrado de la conexión:
|
|||
#username = "no-reply@example.com" # Usuario. Sin valor, no se autentica.
|
||||
#password = "secreto" # Contraseña. Mejor en config/local.toml (no se versiona).
|
||||
#hello_name = "example.com" # Nombre para EHLO. Sin valor, el nombre del equipo.
|
||||
timeout_secs = 60 # Espera máxima de cada orden al servidor, en segundos.
|
||||
pool_max_size = 10 # Conexiones abiertas como máximo, reutilizadas entre envíos.
|
||||
timeout_secs = 60 # Espera máxima de cada orden al servidor, en segundos. Cada
|
||||
# entrega tiene además delivery_timeout_secs de [mail]. Con
|
||||
# security = "tls" no cubre el saludo TLS: un servidor que no
|
||||
# responde ahí retiene un envío simultáneo. Si el servidor lo
|
||||
# admite, es preferible security = "starttls".
|
||||
pool_max_size = 10 # Envíos simultáneos como máximo (los demás esperan turno, y
|
||||
# la espera cuenta en delivery_timeout_secs), y conexiones que
|
||||
# se conservan para reutilizarlas. Por cada envío esperan como
|
||||
# mucho max_waiting correos; con más, falla enseguida.
|
||||
accept_invalid_certs = false # Acepta certificados no válidos. PELIGROSO: sólo pruebas.
|
||||
|
||||
[mail.sendmail] # Programa sendmail (transport = "sendmail").
|
||||
#command = "/usr/sbin/sendmail" # Programa. Sin valor, "sendmail" del PATH.
|
||||
#command = "/usr/sbin/sendmail" # Programa. Sin valor, "sendmail" del PATH.
|
||||
max_concurrent = 10 # Correos que se entregan a la vez, cada uno con su proceso
|
||||
# sendmail; los demás esperan turno (max_waiting por entrega
|
||||
# como mucho; con más, la entrega falla enseguida). Con un
|
||||
# servidor de correo local no se recomiendan valores mayores:
|
||||
# apenas aceleran el envío, porque acepta cada correo al
|
||||
# momento, y en una avalancha multiplican los procesos que
|
||||
# compiten con la aplicación por memoria y CPU, y los correos
|
||||
# en espera. Si el programa envía cada correo a un servidor
|
||||
# remoto (msmtp, ssmtp), no superar el límite de conexiones
|
||||
# simultáneas de ese servidor.
|
||||
|
||||
[mail.file] # Archivos de correo (transport = "file").
|
||||
dir = "mail" # Directorio de los archivos .eml. Se crea si no existe.
|
||||
dir = "mail" # Directorio de los archivos .eml. Se crea si no existe.
|
||||
max_concurrent = 10 # Correos que se guardan a la vez; los demás esperan turno
|
||||
# (max_waiting por cada uno como mucho; con más, la entrega
|
||||
# falla enseguida). No se recomiendan valores mayores: apenas
|
||||
# aceleran el guardado en el mismo disco, y en una avalancha
|
||||
# ocupan más hilos de la aplicación, compartidos con otras
|
||||
# tareas (p. ej. el cálculo de contraseñas), y más correos en
|
||||
# espera.
|
||||
|
||||
[mail.queue] # Cola de envío (sólo con la feature "queue"). El ritmo es el
|
||||
# del trabajo "mail.queue" en [cron.jobs."mail.queue"].
|
||||
batch_size = 50 # Correos como máximo en cada ejecución, uno tras otro.
|
||||
max_attempts = 5 # Intentos de cada correo, contando el primero.
|
||||
retry_base_secs = 60 # Espera tras el primer fallo; se duplica en cada intento,
|
||||
# hasta max_retry_secs.
|
||||
max_retry_secs = 86400 # Espera máxima entre dos intentos (1 a 31536000, un año).
|
||||
# Recomendado: 86400 (un día); con los demás valores por
|
||||
# defecto no se alcanza. Reducirlo reintenta antes tras una
|
||||
# caída larga, con más intentos mientras dura; aumentarlo
|
||||
# puede entregar correos con días de retraso, cuando quizá ya
|
||||
# no sirven (enlaces caducados).
|
||||
keep_failed_days = 30 # Días que se conservan los fallidos (0 = siempre).
|
||||
|
||||
|
||||
# **< pagetop-cron >********************************************************************************
|
||||
|
|
|
|||
|
|
@ -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"]
|
||||
|
|
|
|||
|
|
@ -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`:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)]
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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(())
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
}
|
||||
|
|
|
|||
398
extensions/pagetop-mail/src/queue.rs
Normal file
398
extensions/pagetop-mail/src/queue.rs
Normal 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));
|
||||
}
|
||||
}
|
||||
29
extensions/pagetop-mail/src/queue/entity.rs
Normal file
29
extensions/pagetop-mail/src/queue/entity.rs
Normal 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 {}
|
||||
1
extensions/pagetop-mail/src/queue/migration.rs
Normal file
1
extensions/pagetop-mail/src/queue/migration.rs
Normal file
|
|
@ -0,0 +1 @@
|
|||
pub mod m20261028_000001_create_mail_queue;
|
||||
|
|
@ -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,
|
||||
}
|
||||
|
|
@ -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());
|
||||
}
|
||||
}
|
||||
|
|
|
|||
200
extensions/pagetop-mail/tests/queue.rs
Normal file
200
extensions/pagetop-mail/tests/queue.rs
Normal 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"
|
||||
);
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue