From 4c8eee3585d906895e22dbf56787de10d15af182 Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Sat, 31 Oct 2026 00:49:46 +0100 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20(mail):=20A=C3=B1ade=20cola=20de=20?= =?UTF-8?q?env=C3=ADo=20persistente?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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]`. --- Cargo.lock | 2 + config/reference.toml | 79 +++- extensions/pagetop-mail/Cargo.toml | 17 + extensions/pagetop-mail/README.md | 35 ++ extensions/pagetop-mail/config/common.toml | 12 + extensions/pagetop-mail/src/config.rs | 138 +++++- extensions/pagetop-mail/src/email.rs | 89 +++- extensions/pagetop-mail/src/error.rs | 124 ++++++ extensions/pagetop-mail/src/lib.rs | 51 +++ .../src/locale/en-US/extension.ftl | 2 + .../src/locale/es-ES/extension.ftl | 2 + extensions/pagetop-mail/src/outbox.rs | 26 ++ extensions/pagetop-mail/src/queue.rs | 398 ++++++++++++++++++ extensions/pagetop-mail/src/queue/entity.rs | 29 ++ .../pagetop-mail/src/queue/migration.rs | 1 + .../m20261028_000001_create_mail_queue.rs | 68 +++ extensions/pagetop-mail/src/transport.rs | 275 ++++++++++-- extensions/pagetop-mail/tests/queue.rs | 200 +++++++++ 18 files changed, 1488 insertions(+), 60 deletions(-) create mode 100644 extensions/pagetop-mail/src/queue.rs create mode 100644 extensions/pagetop-mail/src/queue/entity.rs create mode 100644 extensions/pagetop-mail/src/queue/migration.rs create mode 100644 extensions/pagetop-mail/src/queue/migration/m20261028_000001_create_mail_queue.rs create mode 100644 extensions/pagetop-mail/tests/queue.rs diff --git a/Cargo.lock b/Cargo.lock index 2b9dabd1..7fdeb445 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2236,6 +2236,8 @@ dependencies = [ "lettre", "mime_guess", "pagetop", + "pagetop-cron", + "pagetop-seaorm", "serde", "thiserror", "tokio", diff --git a/config/reference.toml b/config/reference.toml index 668de457..83a18a76 100644 --- a/config/reference.toml +++ b/config/reference.toml @@ -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 " +#from = "Mi Aplicación " # 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 >******************************************************************************** diff --git a/extensions/pagetop-mail/Cargo.toml b/extensions/pagetop-mail/Cargo.toml index 621b3100..7d70e8e5 100644 --- a/extensions/pagetop-mail/Cargo.toml +++ b/extensions/pagetop-mail/Cargo.toml @@ -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"] diff --git a/extensions/pagetop-mail/README.md b/extensions/pagetop-mail/README.md index 2062ceba..cd07d953 100644 --- a/extensions/pagetop-mail/README.md +++ b/extensions/pagetop-mail/README.md @@ -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`: diff --git a/extensions/pagetop-mail/config/common.toml b/extensions/pagetop-mail/config/common.toml index b0b160dc..3b5c5ded 100644 --- a/extensions/pagetop-mail/config/common.toml +++ b/extensions/pagetop-mail/config/common.toml @@ -6,3 +6,15 @@ transport = "memory" from = "PageTop Tests " 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 diff --git a/extensions/pagetop-mail/src/config.rs b/extensions/pagetop-mail/src/config.rs index 62cd91fe..6bfa81e3 100644 --- a/extensions/pagetop-mail/src/config.rs +++ b/extensions/pagetop-mail/src/config.rs @@ -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, - /// 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, + /// 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)] diff --git a/extensions/pagetop-mail/src/email.rs b/extensions/pagetop-mail/src/email.rs index 4702d8c9..7d316e6c 100644 --- a/extensions/pagetop-mail/src/email.rs +++ b/extensions/pagetop-mail/src/email.rs @@ -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, - /// 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, #[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) -> 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. diff --git a/extensions/pagetop-mail/src/error.rs b/extensions/pagetop-mail/src/error.rs index cd4bf144..a96ff804 100644 --- a/extensions/pagetop-mail/src/error.rs +++ b/extensions/pagetop-mail/src/error.rs @@ -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 + } } diff --git a/extensions/pagetop-mail/src/lib.rs b/extensions/pagetop-mail/src/lib.rs index 123068ac..f2dbd05f 100644 --- a/extensions/pagetop-mail/src/lib.rs +++ b/extensions/pagetop-mail/src/lib.rs @@ -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 { + vec![&pagetop_seaorm::SeaORM, &pagetop_cron::Cron] + } + + #[cfg(feature = "queue")] + fn actions(&self) -> Vec { + 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(()) } diff --git a/extensions/pagetop-mail/src/locale/en-US/extension.ftl b/extensions/pagetop-mail/src/locale/en-US/extension.ftl index 752d5ffd..c64a8a39 100644 --- a/extensions/pagetop-mail/src/locale/en-US/extension.ftl +++ b/extensions/pagetop-mail/src/locale/en-US/extension.ftl @@ -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 diff --git a/extensions/pagetop-mail/src/locale/es-ES/extension.ftl b/extensions/pagetop-mail/src/locale/es-ES/extension.ftl index b2ae5514..627f0dd0 100644 --- a/extensions/pagetop-mail/src/locale/es-ES/extension.ftl +++ b/extensions/pagetop-mail/src/locale/es-ES/extension.ftl @@ -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 diff --git a/extensions/pagetop-mail/src/outbox.rs b/extensions/pagetop-mail/src/outbox.rs index 4091dcf6..19611530 100644 --- a/extensions/pagetop-mail/src/outbox.rs +++ b/extensions/pagetop-mail/src/outbox.rs @@ -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, raw: Vec) { fn lock() -> MutexGuard<'static, Vec> { 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> = 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 { + 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) +} diff --git a/extensions/pagetop-mail/src/queue.rs b/extensions/pagetop-mail/src/queue.rs new file mode 100644 index 00000000..11365b83 --- /dev/null +++ b/extensions/pagetop-mail/src/queue.rs @@ -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, + locked: bool, +) -> Result { + 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 { + 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::>)) + .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::>)) + .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) -> 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) -> DateTime { + 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 { + let from = row.envelope_from.as_deref().map(address).transpose()?; + let to = row + .envelope_to + .lines() + .map(address) + .collect::, _>>()?; + Envelope::new(from, to).map_err(MailError::Build) +} + +fn address(value: &str) -> Result { + 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)); + } +} diff --git a/extensions/pagetop-mail/src/queue/entity.rs b/extensions/pagetop-mail/src/queue/entity.rs new file mode 100644 index 00000000..593ad9b0 --- /dev/null +++ b/extensions/pagetop-mail/src/queue/entity.rs @@ -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, + // Destinatarios del sobre, uno por línea. + pub envelope_to: String, + pub subject: String, + // Mensaje compuesto en formato RFC 5322. + pub message: Vec, + 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, + pub last_error: Option, + pub failed_at: Option, + pub created_at: DateTimeUtc, + pub updated_at: DateTimeUtc, +} + +#[derive(Clone, Copy, Debug, DeriveRelation, EnumIter)] +pub enum Relation {} + +impl ActiveModelBehavior for ActiveModel {} diff --git a/extensions/pagetop-mail/src/queue/migration.rs b/extensions/pagetop-mail/src/queue/migration.rs new file mode 100644 index 00000000..12068e00 --- /dev/null +++ b/extensions/pagetop-mail/src/queue/migration.rs @@ -0,0 +1 @@ +pub mod m20261028_000001_create_mail_queue; diff --git a/extensions/pagetop-mail/src/queue/migration/m20261028_000001_create_mail_queue.rs b/extensions/pagetop-mail/src/queue/migration/m20261028_000001_create_mail_queue.rs new file mode 100644 index 00000000..a66f4438 --- /dev/null +++ b/extensions/pagetop-mail/src/queue/migration/m20261028_000001_create_mail_queue.rs @@ -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, +} diff --git a/extensions/pagetop-mail/src/transport.rs b/extensions/pagetop-mail/src/transport.rs index 55fc68ef..3537c969 100644 --- a/extensions/pagetop-mail/src/transport.rs +++ b/extensions/pagetop-mail/src/transport.rs @@ -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 = 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, reply_to: Option, redirect_to: Option
, } +// Plaza para una entrega, obtenida con `Mailer::ticket()`. +pub(crate) type Ticket = SemaphorePermit<'static>; + enum Transport { - Smtp(AsyncSmtpTransport), + // El transporte SMTP síncrono, no el asíncrono: ver `deliver_raw()`. + Smtp(SmtpTransport), Sendmail(AsyncSendmailTransport), File(AsyncFileTransport), 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, +} + +pub(crate) fn compose(mailer: &Mailer, email: Email) -> Result { + 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, + email: Option, +) -> 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(delivery: impl Future) -> Result { + 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 { } 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 { + 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 { 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, MailError> { +// Envíos simultáneos según el ajuste `key`, que debe ser al menos uno. +fn slots(key: &'static str, setting: u32) -> Result { + 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 { 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 (Tls::Required(tls_parameters()?), 587), SmtpSecurity::Tls => (Tls::Wrapper(tls_parameters()?), 465), }; - let mut builder = AsyncSmtpTransport::::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 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()); + } +} diff --git a/extensions/pagetop-mail/tests/queue.rs b/extensions/pagetop-mail/tests/queue.rs new file mode 100644 index 00000000..9c84149c --- /dev/null +++ b/extensions/pagetop-mail/tests/queue.rs @@ -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 { + 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 { + 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" + ); +}