✨ (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

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

View file

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

View file

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