✨ (mail): Añade cola de envío persistente

Nueva feature `queue`, con `pagetop-seaorm` y `pagetop-cron`: los
correos se guardan ya compuestos en la tabla `mail_queue` y el trabajo
`mail.queue` los envía por lotes, con reintentos de espera creciente y
reserva por fila para varias instancias (entrega «al menos una vez»).

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

View file

@ -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());
}
}