✨ (mail): Añade cola de envío persistente
Nueva feature `queue`, con `pagetop-seaorm` y `pagetop-cron`: los correos se guardan ya compuestos en la tabla `mail_queue` y el trabajo `mail.queue` los envía por lotes, con reintentos de espera creciente y reserva por fila para varias instancias (entrega «al menos una vez»). - `Email::queue()` sólo guarda el correo; `send_later()` lo guarda y lo intenta enseguida, o lo deja para el lote si hay demasiados en espera. - SMTP con el transporte síncrono de `lettre` en `spawn_blocking`, con `timeout_secs` en cada lectura y escritura del socket. - Turnos de envío y límites configurables para todos los transportes: envíos simultáneos, correos en espera, tiempo máximo de entrega y espera máxima entre intentos, validados al arrancar. - Nuevos errores `Timeout`, `Overloaded`, `Interrupted`, `OutOfRange` y `Queue`; `MailError` pasa a ser `#[non_exhaustive]`.
This commit is contained in:
parent
86d9f0e213
commit
4c8eee3585
18 changed files with 1488 additions and 60 deletions
|
|
@ -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());
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue