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

@ -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`: