✨ (mail): Añade la extensión pagetop-mail
Envío de correo con lettre: plantillas con diseño y versión en texto, adjuntos, transporte configurable y vista previa de mensajes.
This commit is contained in:
parent
b3a7d40930
commit
ce9635f9a8
25 changed files with 3508 additions and 0 deletions
141
extensions/pagetop-mail/src/attachment.rs
Normal file
141
extensions/pagetop-mail/src/attachment.rs
Normal file
|
|
@ -0,0 +1,141 @@
|
|||
//! Archivos adjuntos e imágenes incrustadas ([`Attachment`]).
|
||||
|
||||
use pagetop::prelude::*;
|
||||
|
||||
use crate::MailError;
|
||||
|
||||
use lettre::message::SinglePart;
|
||||
use lettre::message::header::ContentType;
|
||||
|
||||
use std::fmt;
|
||||
use std::path::Path;
|
||||
use std::sync::Arc;
|
||||
|
||||
/// Archivo adjunto a un correo, o recurso incrustado en su HTML.
|
||||
///
|
||||
/// Un adjunto tiene un nombre de archivo, un contenido y un tipo MIME. Si no se indica el tipo, se
|
||||
/// deduce de la extensión del nombre (`informe.pdf` -> `application/pdf`) y, si no se reconoce, se
|
||||
/// usa `application/octet-stream`.
|
||||
///
|
||||
/// Con [`with_content_id()`](Self::with_content_id) el adjunto pasa a ser un recurso **incrustado**
|
||||
/// (*inline*), típicamente una imagen que el HTML del correo muestra con `src="cid:..."`. Sólo se
|
||||
/// incrustan si el correo tiene HTML; si no, se envían como adjuntos normales.
|
||||
///
|
||||
/// El contenido se comparte al clonar el adjunto, sin copiarlo.
|
||||
///
|
||||
/// # Ejemplos
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// # use pagetop::prelude::*;
|
||||
/// # use pagetop_mail::prelude::*;
|
||||
/// # async fn example(pdf: Vec<u8>, png: Vec<u8>) -> Result<(), MailError> {
|
||||
/// // Un PDF generado por la aplicación.
|
||||
/// let report = Attachment::new("informe.pdf", pdf);
|
||||
///
|
||||
/// // Un archivo del disco, con el nombre del archivo.
|
||||
/// let terms = Attachment::from_path("docs/condiciones.pdf").await?;
|
||||
///
|
||||
/// // Un logotipo que el HTML muestra con <img src="cid:logo">.
|
||||
/// let logo = Attachment::new("logo.png", png).with_content_id("logo");
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
/// ```
|
||||
#[derive(Clone, Getters)]
|
||||
pub struct Attachment {
|
||||
/// Nombre del archivo, tal como lo verá el destinatario.
|
||||
filename: String,
|
||||
/// Tipo MIME del contenido.
|
||||
content_type: String,
|
||||
/// Identificador del recurso incrustado, si lo es.
|
||||
content_id: Option<String>,
|
||||
#[getters(skip)]
|
||||
body: Arc<[u8]>,
|
||||
}
|
||||
|
||||
impl Attachment {
|
||||
/// Crea un adjunto con el nombre de archivo y el contenido dados.
|
||||
pub fn new(filename: impl Into<String>, body: impl Into<Vec<u8>>) -> Self {
|
||||
let filename = filename.into();
|
||||
let content_type = mime_guess::from_path(&filename)
|
||||
.first_or_octet_stream()
|
||||
.essence_str()
|
||||
.to_owned();
|
||||
Attachment {
|
||||
filename,
|
||||
content_type,
|
||||
content_id: None,
|
||||
body: Arc::from(body.into()),
|
||||
}
|
||||
}
|
||||
|
||||
/// Crea un adjunto leyendo un archivo del disco. El nombre del adjunto es el del archivo.
|
||||
///
|
||||
/// Falla con [`MailError::ReadAttachment`] si no se puede leer el archivo.
|
||||
pub async fn from_path(path: impl AsRef<Path>) -> Result<Self, MailError> {
|
||||
let path = path.as_ref();
|
||||
let body = tokio::fs::read(path)
|
||||
.await
|
||||
.map_err(|source| MailError::ReadAttachment {
|
||||
path: path.to_path_buf(),
|
||||
source,
|
||||
})?;
|
||||
let filename = path
|
||||
.file_name()
|
||||
.map(|name| name.to_string_lossy().into_owned())
|
||||
.unwrap_or_default();
|
||||
Ok(Attachment::new(filename, body))
|
||||
}
|
||||
|
||||
/// Contenido del adjunto.
|
||||
pub fn body(&self) -> &[u8] {
|
||||
&self.body
|
||||
}
|
||||
|
||||
/// Indica si es un recurso incrustado en el HTML del correo.
|
||||
pub fn is_inline(&self) -> bool {
|
||||
self.content_id.is_some()
|
||||
}
|
||||
|
||||
// Convierte el adjunto en una parte del mensaje. Los recursos incrustados sólo se incrustan si
|
||||
// `inline` es `true` (el correo tiene HTML).
|
||||
pub(crate) fn to_part(&self, inline: bool) -> Result<SinglePart, MailError> {
|
||||
let content_type = ContentType::parse(&self.content_type)
|
||||
.map_err(|_| MailError::InvalidContentType(self.content_type.clone()))?;
|
||||
let attachment = match self.content_id() {
|
||||
Some(id) if inline => lettre::message::Attachment::new_inline(id.clone()),
|
||||
_ => lettre::message::Attachment::new(self.filename.clone()),
|
||||
};
|
||||
Ok(attachment.body(self.body.to_vec(), content_type))
|
||||
}
|
||||
}
|
||||
|
||||
// Muestra el tamaño del contenido en lugar de sus bytes.
|
||||
impl fmt::Debug for Attachment {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
f.debug_struct("Attachment")
|
||||
.field("filename", &self.filename)
|
||||
.field("content_type", &self.content_type)
|
||||
.field("content_id", &self.content_id)
|
||||
.field("body_len", &self.body.len())
|
||||
.finish()
|
||||
}
|
||||
}
|
||||
|
||||
#[builder_impl]
|
||||
impl Attachment {
|
||||
// **< Attachment BUILDER >*********************************************************************
|
||||
|
||||
/// Cambia el tipo MIME deducido del nombre del archivo (p. ej. `"text/csv; charset=utf-8"`).
|
||||
/// Si no es válido, el envío falla con [`MailError::InvalidContentType`].
|
||||
pub fn with_content_type(mut self, content_type: impl Into<String>) -> Self {
|
||||
self.content_type = content_type.into();
|
||||
self
|
||||
}
|
||||
|
||||
/// Incrusta el adjunto en el HTML del correo con el identificador dado, que el HTML usa como
|
||||
/// `cid:<identificador>` (p. ej. `img src="cid:logo"`).
|
||||
pub fn with_content_id(mut self, content_id: impl Into<String>) -> Self {
|
||||
self.content_id = Some(content_id.into());
|
||||
self
|
||||
}
|
||||
}
|
||||
171
extensions/pagetop-mail/src/config.rs
Normal file
171
extensions/pagetop-mail/src/config.rs
Normal file
|
|
@ -0,0 +1,171 @@
|
|||
//! Ajustes de configuración de `pagetop-mail`.
|
||||
//!
|
||||
//! Ejemplo:
|
||||
//!
|
||||
//! ```toml
|
||||
//! [mail]
|
||||
//! transport = "smtp"
|
||||
//! from = "Mi Aplicación <no-reply@example.com>"
|
||||
//! base_url = "https://example.com"
|
||||
//!
|
||||
//! [mail.smtp]
|
||||
//! host = "smtp.example.com"
|
||||
//! security = "starttls"
|
||||
//! username = "no-reply@example.com"
|
||||
//! password = "secreto"
|
||||
//! ```
|
||||
//!
|
||||
//! Uso:
|
||||
//!
|
||||
//! ```rust,no_run
|
||||
//! use pagetop_mail::config;
|
||||
//!
|
||||
//! assert_eq!(config::SETTINGS.smtp.host, "smtp.example.com");
|
||||
//! ```
|
||||
//!
|
||||
//! Todas las opciones, con su valor por defecto, se documentan en [`MailSettings`] y sus
|
||||
//! subsecciones ([`SmtpSettings`], [`SendmailSettings`] y [`FileSettings`]).
|
||||
//!
|
||||
//! Consulta [`pagetop::config`] para ver cómo PageTop lee los archivos de configuración y aplica
|
||||
//! los valores a los ajustes.
|
||||
|
||||
use pagetop::prelude::*;
|
||||
|
||||
use serde::Deserialize;
|
||||
|
||||
/// Ajustes de la sección `[mail]`, cargados al arrancar la aplicación.
|
||||
pub static SETTINGS: LazySettings<MailSettings> = LazySettings::new();
|
||||
|
||||
/// Sección **`[mail]`** de la configuración.
|
||||
#[settings(section = "mail")]
|
||||
pub struct MailSettings {
|
||||
/// Cómo se entregan los correos. Por defecto se escriben en las trazas sin enviarlos
|
||||
/// ([`MailTransport::Log`]), para que una aplicación sin configurar no envíe correo real.
|
||||
pub transport: MailTransport,
|
||||
/// Remitente por defecto, para los correos que no indican uno propio. Admite la dirección sola
|
||||
/// (`"no-reply@example.com"`) o con nombre (`"Mi Aplicación <no-reply@example.com>"`). Sin
|
||||
/// valor, cada correo debe indicar su remitente.
|
||||
pub from: Option<String>,
|
||||
/// Dirección de respuesta por defecto, para los correos que no indican una propia.
|
||||
pub reply_to: Option<String>,
|
||||
/// Si se indica, todos los correos se entregan **sólo** a esta dirección en lugar de a sus
|
||||
/// destinatarios, que se conservan en las cabeceras (`To`, `Cc`). Pensado para entornos de
|
||||
/// pruebas o preproducción con datos reales.
|
||||
pub redirect_to: Option<String>,
|
||||
/// URL pública de la aplicación (p. ej. `"https://example.com"`), para construir los enlaces
|
||||
/// absolutos de los correos con [`absolute_url()`](crate::absolute_url). Debe empezar por
|
||||
/// `http://` o `https://`, o la aplicación no arranca. Sin valor, se usa la dirección y el
|
||||
/// puerto de escucha del servidor (`http://localhost:8080`), que sólo sirve en desarrollo.
|
||||
pub base_url: Option<String>,
|
||||
/// Ofrece en `/mail/preview` las vistas previas de los correos que declaran las extensiones
|
||||
/// (ver [`preview`](crate::preview)). Sólo para desarrollo: muestra las plantillas a cualquiera
|
||||
/// que conozca la ruta.
|
||||
#[default = false]
|
||||
pub previews: bool,
|
||||
|
||||
/// Servidor SMTP, en la subsección `[mail.smtp]`.
|
||||
pub smtp: SmtpSettings,
|
||||
|
||||
/// Programa *sendmail*, en la subsección `[mail.sendmail]`.
|
||||
pub sendmail: SendmailSettings,
|
||||
|
||||
/// Archivos de correo, en la subsección `[mail.file]`.
|
||||
pub file: FileSettings,
|
||||
}
|
||||
|
||||
/// Forma de entregar los correos. Usado en [`MailSettings::transport`].
|
||||
#[derive(AutoDefault, Clone, Copy, Debug, Deserialize, Eq, PartialEq)]
|
||||
#[serde(rename_all = "lowercase")]
|
||||
pub enum MailTransport {
|
||||
/// Envía los correos a un servidor SMTP (ver [`SmtpSettings`]).
|
||||
Smtp,
|
||||
/// Entrega los correos al programa *sendmail* local (ver [`SendmailSettings`]).
|
||||
Sendmail,
|
||||
/// Guarda cada correo como un archivo `.eml` en un directorio (ver [`FileSettings`]). Útil en
|
||||
/// desarrollo para abrirlos con un cliente de correo.
|
||||
File,
|
||||
/// No envía nada: escribe en las trazas el remitente, los destinatarios, el asunto y el texto
|
||||
/// de cada correo. Es el valor por defecto. No debe usarse en producción, porque los textos
|
||||
/// pueden incluir enlaces con *tokens* de un solo uso.
|
||||
#[default]
|
||||
Log,
|
||||
/// No envía nada: guarda los correos en memoria para que las pruebas los consulten con
|
||||
/// [`outbox`](crate::outbox).
|
||||
Memory,
|
||||
}
|
||||
|
||||
/// Subsección **`[mail.smtp]`** de la configuración.
|
||||
#[settings]
|
||||
pub struct SmtpSettings {
|
||||
/// Servidor SMTP.
|
||||
#[default = "localhost"]
|
||||
pub host: String,
|
||||
/// Puerto del servidor. Sin valor, el habitual según la seguridad: 465 con
|
||||
/// [`SmtpSecurity::Tls`], 587 con [`SmtpSecurity::StartTls`] y 25 en los demás casos.
|
||||
pub port: Option<u16>,
|
||||
/// Cifrado de la conexión.
|
||||
#[default(SmtpSecurity::StartTls)]
|
||||
pub security: SmtpSecurity,
|
||||
/// Usuario para autenticarse en el servidor. Sin valor, no se autentica.
|
||||
pub username: Option<String>,
|
||||
/// Contraseña del usuario. Conviene guardarla en `config/local.toml`, que no se versiona.
|
||||
pub password: Option<String>,
|
||||
/// Nombre con el que se presenta la aplicación al servidor (`EHLO`). Sin valor, el nombre del
|
||||
/// equipo.
|
||||
pub hello_name: Option<String>,
|
||||
/// Segundos de espera máxima de cada orden al servidor.
|
||||
#[default = 60]
|
||||
pub timeout_secs: u64,
|
||||
/// Número máximo de conexiones abiertas con el servidor, que se reutilizan entre envíos.
|
||||
#[default = 10]
|
||||
pub pool_max_size: u32,
|
||||
/// Acepta certificados no válidos (caducados, autofirmados o de otro servidor). **Peligroso**:
|
||||
/// sólo para servidores de pruebas, nunca en producción.
|
||||
#[default = false]
|
||||
pub accept_invalid_certs: bool,
|
||||
}
|
||||
|
||||
/// Cifrado de la conexión SMTP. Usado en [`SmtpSettings::security`].
|
||||
#[derive(AutoDefault, Clone, Copy, Debug, Deserialize, Eq, PartialEq)]
|
||||
#[serde(rename_all = "lowercase")]
|
||||
pub enum SmtpSecurity {
|
||||
/// Sin cifrado. Sólo para servidores locales o de pruebas (p. ej. Mailpit o MailHog).
|
||||
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).
|
||||
#[default]
|
||||
StartTls,
|
||||
/// Conexión cifrada desde el principio, también llamada SMTPS (puerto 465).
|
||||
Tls,
|
||||
}
|
||||
|
||||
/// Subsección **`[mail.sendmail]`** de la configuración.
|
||||
#[settings]
|
||||
pub struct SendmailSettings {
|
||||
/// Programa que recibe los correos. Sin valor, `sendmail` del `PATH`.
|
||||
pub command: Option<String>,
|
||||
}
|
||||
|
||||
/// Subsección **`[mail.file]`** de la configuración.
|
||||
#[settings]
|
||||
pub struct FileSettings {
|
||||
/// Directorio donde se guardan los correos. Se crea al arrancar si no existe.
|
||||
#[default = "mail"]
|
||||
pub dir: String,
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::{MailSettings, config};
|
||||
|
||||
// `reference.toml` documents every option; with unknown keys rejected, loading it proves that
|
||||
// it only documents keys that exist, with values of the right type.
|
||||
const REFERENCE: &str = include_str!("../../../config/reference.toml");
|
||||
|
||||
#[test]
|
||||
fn reference_toml_documents_only_existing_keys() {
|
||||
config::load_from_str::<MailSettings>(REFERENCE).unwrap();
|
||||
}
|
||||
}
|
||||
345
extensions/pagetop-mail/src/email.rs
Normal file
345
extensions/pagetop-mail/src/email.rs
Normal file
|
|
@ -0,0 +1,345 @@
|
|||
//! Correos electrónicos ([`Email`]).
|
||||
|
||||
use pagetop::prelude::*;
|
||||
|
||||
use crate::{Attachment, MailError, MailTemplate, Mailbox, layout, text, transport};
|
||||
|
||||
use lettre::Message;
|
||||
use lettre::message::{MultiPart, MultiPartBuilder, SinglePart};
|
||||
|
||||
use std::sync::atomic::{AtomicU64, Ordering};
|
||||
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).
|
||||
///
|
||||
/// 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
|
||||
/// [`Attachment`]). El HTML de [`with_html()`](Self::with_html) es sólo el contenido: al enviarlo
|
||||
/// se envuelve en el diseño común de los correos (ver
|
||||
/// [`RenderMailLayout`](crate::RenderMailLayout)).
|
||||
///
|
||||
/// Si sólo tiene HTML, al enviarlo se genera el texto plano a partir de él, porque los filtros de
|
||||
/// correo no deseado penalizan los correos sin texto. Escríbelo con
|
||||
/// [`with_text()`](Self::with_text) sólo si el generado no queda bien.
|
||||
///
|
||||
/// Si no se indica el remitente o la dirección de respuesta se usan los de la configuración
|
||||
/// (`mail.from` y `mail.reply_to`). Las direcciones se validan al enviar.
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// use pagetop::prelude::*;
|
||||
/// use pagetop_mail::prelude::*;
|
||||
///
|
||||
/// async fn send_report(pdf: Vec<u8>) -> Result<(), MailError> {
|
||||
/// Email::new()
|
||||
/// .with_to("Ana Pérez <ana@example.com>")
|
||||
/// .with_cc("contabilidad@example.com")
|
||||
/// .with_subject("Informe mensual")
|
||||
/// .with_text("Adjunto el informe del mes.")
|
||||
/// .with_html(html! {
|
||||
/// p { "Adjunto el " strong { "informe" } " del mes." }
|
||||
/// })
|
||||
/// .with_attachment(Attachment::new("informe.pdf", pdf))
|
||||
/// .send()
|
||||
/// .await
|
||||
/// }
|
||||
/// ```
|
||||
#[derive(AutoDefault, Clone, Debug, Getters)]
|
||||
pub struct Email {
|
||||
/// Remitente, si se ha indicado.
|
||||
from: Option<Mailbox>,
|
||||
/// Dirección de respuesta, si se ha indicado.
|
||||
reply_to: Option<Mailbox>,
|
||||
/// Destinatarios principales.
|
||||
to: Vec<Mailbox>,
|
||||
/// Destinatarios en copia.
|
||||
cc: Vec<Mailbox>,
|
||||
/// Destinatarios en copia oculta.
|
||||
bcc: Vec<Mailbox>,
|
||||
/// Asunto.
|
||||
subject: String,
|
||||
/// Texto plano, si lo tiene.
|
||||
text: Option<String>,
|
||||
/// HTML, si lo tiene: el contenido mientras se compone y el documento completo una vez
|
||||
/// enviado.
|
||||
html: Option<Markup>,
|
||||
#[getters(skip)]
|
||||
html_is_document: bool,
|
||||
/// Archivos adjuntos e imágenes incrustadas.
|
||||
attachments: Vec<Attachment>,
|
||||
#[getters(skip)]
|
||||
langid: Option<&'static LanguageIdentifier>,
|
||||
}
|
||||
|
||||
impl Email {
|
||||
/// Crea un correo vacío.
|
||||
pub fn new() -> Self {
|
||||
Email::default()
|
||||
}
|
||||
|
||||
/// Crea un correo con el asunto, el HTML y el texto de una plantilla, generados en el idioma
|
||||
/// del contexto, que también es el del diseño común del HTML.
|
||||
///
|
||||
/// El contexto puede ser el de la petición en curso, si el destinatario es quien la hace (p.
|
||||
/// ej. al registrarse), o uno creado para el destinatario con
|
||||
/// `Context::default().with_langid(...)`.
|
||||
pub fn from_template(template: &impl MailTemplate, cx: &Context) -> Self {
|
||||
let mut email = Email::new()
|
||||
.with_subject(template.subject(cx))
|
||||
.with_langid(cx);
|
||||
if let Some(html) = template.html(cx) {
|
||||
email.alter_html(html);
|
||||
}
|
||||
if let Some(text) = template.text(cx) {
|
||||
email.alter_text(text);
|
||||
}
|
||||
email
|
||||
}
|
||||
|
||||
/// Idioma del correo: el indicado con [`with_langid()`](Self::with_langid) o, si no, el idioma
|
||||
/// por defecto de la aplicación.
|
||||
pub fn langid(&self) -> &'static LanguageIdentifier {
|
||||
self.langid.unwrap_or_else(Locale::default_langid)
|
||||
}
|
||||
|
||||
/// Envía el correo y espera a que se entregue (al servidor SMTP, a *sendmail*, al archivo...).
|
||||
///
|
||||
/// Falla si alguna dirección o el tipo MIME de algún adjunto no son válidos, si falta el
|
||||
/// remitente o los destinatarios, o si la entrega falla.
|
||||
pub async fn send(self) -> Result<(), MailError> {
|
||||
transport::deliver(self).await
|
||||
}
|
||||
|
||||
/// Envía el correo en segundo plano, sin esperar al resultado. Si falla, se registra el error
|
||||
/// en las trazas.
|
||||
///
|
||||
/// 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.
|
||||
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}");
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// 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.
|
||||
pub(crate) fn prepare(mut self, from: Option<&Mailbox>, reply_to: Option<&Mailbox>) -> Self {
|
||||
if self.from.is_none() {
|
||||
self.from = from.cloned();
|
||||
}
|
||||
if self.reply_to.is_none() {
|
||||
self.reply_to = reply_to.cloned();
|
||||
}
|
||||
if self.text.is_none()
|
||||
&& let Some(html) = &self.html
|
||||
{
|
||||
self.text = Some(text::html_to_text(html.as_str()));
|
||||
}
|
||||
if !self.html_is_document
|
||||
&& let Some(content) = self.html.take()
|
||||
{
|
||||
let cx = Context::default().with_langid(&Locale::Resolved(self.langid()));
|
||||
self.html = Some(layout::render(&cx, &self, &content));
|
||||
self.html_is_document = true;
|
||||
}
|
||||
self
|
||||
}
|
||||
|
||||
// Compone el mensaje MIME:
|
||||
//
|
||||
// - texto y HTML -> multipart/alternative (el texto primero, el preferido al final).
|
||||
// - HTML con imágenes incrustadas -> multipart/related con el HTML y las imágenes.
|
||||
// - con adjuntos -> multipart/mixed con el cuerpo y los adjuntos.
|
||||
pub(crate) fn to_message(&self) -> Result<Message, MailError> {
|
||||
let from = self.from.as_ref().ok_or(MailError::MissingFrom)?;
|
||||
if self.to.is_empty() && self.cc.is_empty() && self.bcc.is_empty() {
|
||||
return Err(MailError::NoRecipients);
|
||||
}
|
||||
|
||||
let from = from.to_lettre()?;
|
||||
let mut builder = Message::builder()
|
||||
.message_id(Some(message_id(from.email.domain())))
|
||||
.from(from)
|
||||
.subject(self.subject.as_str());
|
||||
if let Some(reply_to) = &self.reply_to {
|
||||
builder = builder.reply_to(reply_to.to_lettre()?);
|
||||
}
|
||||
for mailbox in &self.to {
|
||||
builder = builder.to(mailbox.to_lettre()?);
|
||||
}
|
||||
for mailbox in &self.cc {
|
||||
builder = builder.cc(mailbox.to_lettre()?);
|
||||
}
|
||||
for mailbox in &self.bcc {
|
||||
builder = builder.bcc(mailbox.to_lettre()?);
|
||||
}
|
||||
|
||||
let has_html = self.html.is_some();
|
||||
let html = match &self.html {
|
||||
Some(html) => {
|
||||
let part = SinglePart::html(html.as_str().to_owned());
|
||||
let mut inline = self.attachments.iter().filter(|a| a.is_inline()).peekable();
|
||||
if inline.peek().is_some() {
|
||||
let images = inline
|
||||
.map(|attachment| attachment.to_part(true).map(Part::Single))
|
||||
.collect::<Result<Vec<_>, _>>()?;
|
||||
Some(multipart(MultiPart::related(), Part::Single(part), images))
|
||||
} else {
|
||||
Some(Part::Single(part))
|
||||
}
|
||||
}
|
||||
None => None,
|
||||
};
|
||||
let text = self
|
||||
.text
|
||||
.as_ref()
|
||||
.map(|t| Part::Single(SinglePart::plain(t.clone())));
|
||||
let mut body = match (text, html) {
|
||||
(Some(text), Some(html)) => multipart(MultiPart::alternative(), text, vec![html]),
|
||||
(Some(part), None) | (None, Some(part)) => part,
|
||||
(None, None) => Part::Single(SinglePart::plain(String::new())),
|
||||
};
|
||||
|
||||
let attached = self
|
||||
.attachments
|
||||
.iter()
|
||||
.filter(|a| !(has_html && a.is_inline()))
|
||||
.map(|attachment| attachment.to_part(false).map(Part::Single))
|
||||
.collect::<Result<Vec<_>, _>>()?;
|
||||
if !attached.is_empty() {
|
||||
body = multipart(MultiPart::mixed(), body, attached);
|
||||
}
|
||||
|
||||
match body {
|
||||
Part::Single(part) => builder.singlepart(part),
|
||||
Part::Multi(multi) => builder.multipart(multi),
|
||||
}
|
||||
.map_err(MailError::Build)
|
||||
}
|
||||
}
|
||||
|
||||
#[builder_impl]
|
||||
impl Email {
|
||||
// **< Email BUILDER >**************************************************************************
|
||||
|
||||
/// Establece el remitente, en lugar del de la configuración (`mail.from`).
|
||||
pub fn with_from(mut self, from: impl Into<Mailbox>) -> Self {
|
||||
self.from = Some(from.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Establece la dirección de respuesta, en lugar de la de la configuración (`mail.reply_to`).
|
||||
pub fn with_reply_to(mut self, reply_to: impl Into<Mailbox>) -> Self {
|
||||
self.reply_to = Some(reply_to.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Añade un destinatario principal (`To`).
|
||||
pub fn with_to(mut self, to: impl Into<Mailbox>) -> Self {
|
||||
self.to.push(to.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Añade un destinatario en copia (`Cc`).
|
||||
pub fn with_cc(mut self, cc: impl Into<Mailbox>) -> Self {
|
||||
self.cc.push(cc.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Añade un destinatario en copia oculta (`Bcc`), que no ven los demás destinatarios.
|
||||
pub fn with_bcc(mut self, bcc: impl Into<Mailbox>) -> Self {
|
||||
self.bcc.push(bcc.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Establece el asunto.
|
||||
pub fn with_subject(mut self, subject: impl Into<String>) -> Self {
|
||||
self.subject = subject.into();
|
||||
self
|
||||
}
|
||||
|
||||
/// Establece el texto plano.
|
||||
pub fn with_text(mut self, text: impl Into<String>) -> Self {
|
||||
self.text = Some(text.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Establece el contenido HTML, que al enviarse se envuelve en el diseño común de los correos.
|
||||
pub fn with_html(mut self, content: Markup) -> Self {
|
||||
self.html = Some(content);
|
||||
self.html_is_document = false;
|
||||
self
|
||||
}
|
||||
|
||||
/// Establece el documento HTML completo, que se envía tal cual, sin el diseño común. Útil si el
|
||||
/// HTML se genera con otra herramienta.
|
||||
pub fn with_html_document(mut self, document: Markup) -> Self {
|
||||
self.html = Some(document);
|
||||
self.html_is_document = true;
|
||||
self
|
||||
}
|
||||
|
||||
/// Añade un archivo adjunto o una imagen incrustada.
|
||||
pub fn with_attachment(mut self, attachment: Attachment) -> Self {
|
||||
self.attachments.push(attachment);
|
||||
self
|
||||
}
|
||||
|
||||
/// Establece el idioma del correo, que usa el diseño común del HTML.
|
||||
pub fn with_langid(mut self, language: &impl LangId) -> Self {
|
||||
self.langid = Some(language.langid());
|
||||
self
|
||||
}
|
||||
}
|
||||
|
||||
// Genera la cabecera `Message-ID`, que los filtros de correo no deseado penalizan si falta. Sólo
|
||||
// tiene que ser única: la hora, un contador y el proceso lo garantizan sin depender del azar. El
|
||||
// dominio es el del remitente y no el nombre del equipo, que en un contenedor suele ser aleatorio y
|
||||
// también penalizan algunos filtros.
|
||||
fn message_id(domain: &str) -> String {
|
||||
static COUNTER: AtomicU64 = AtomicU64::new(0);
|
||||
let nanos = SystemTime::now()
|
||||
.duration_since(UNIX_EPOCH)
|
||||
.map_or(0, |elapsed| elapsed.as_nanos());
|
||||
let count = COUNTER.fetch_add(1, Ordering::Relaxed);
|
||||
format!("<{nanos:x}.{count:x}.{:x}@{domain}>", std::process::id())
|
||||
}
|
||||
|
||||
// Parte de un mensaje MIME: simple o compuesta por otras partes.
|
||||
enum Part {
|
||||
Single(SinglePart),
|
||||
Multi(MultiPart),
|
||||
}
|
||||
|
||||
// Compone una parte del tipo dado con `first` y el resto de partes, en ese orden.
|
||||
fn multipart(kind: MultiPartBuilder, first: Part, rest: Vec<Part>) -> Part {
|
||||
let mut multi = match first {
|
||||
Part::Single(part) => kind.singlepart(part),
|
||||
Part::Multi(multi) => kind.multipart(multi),
|
||||
};
|
||||
for part in rest {
|
||||
multi = match part {
|
||||
Part::Single(part) => multi.singlepart(part),
|
||||
Part::Multi(part) => multi.multipart(part),
|
||||
};
|
||||
}
|
||||
Part::Multi(multi)
|
||||
}
|
||||
68
extensions/pagetop-mail/src/error.rs
Normal file
68
extensions/pagetop-mail/src/error.rs
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
//! Errores de `pagetop-mail`.
|
||||
|
||||
use std::path::PathBuf;
|
||||
|
||||
/// Errores al configurar el envío de correo o al componer y enviar un correo.
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum MailError {
|
||||
/// Una dirección de correo no es válida.
|
||||
#[error("invalid email address \"{address}\"")]
|
||||
InvalidAddress {
|
||||
/// Dirección tal como se indicó.
|
||||
address: String,
|
||||
/// Motivo del error.
|
||||
#[source]
|
||||
source: lettre::address::AddressError,
|
||||
},
|
||||
/// Un ajuste de la sección `[mail]` no es válido.
|
||||
#[error("invalid mail setting \"{key}\"")]
|
||||
InvalidSetting {
|
||||
/// Clave del ajuste, p. ej. `"mail.from"`.
|
||||
key: &'static str,
|
||||
/// Motivo del error.
|
||||
#[source]
|
||||
source: Box<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),
|
||||
/// 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,
|
||||
/// El correo no tiene ningún destinatario (`To`, `Cc` ni `Bcc`).
|
||||
#[error("email has no recipients")]
|
||||
NoRecipients,
|
||||
/// El tipo de contenido de un adjunto no es un tipo MIME válido.
|
||||
#[error("invalid content type \"{0}\" for attachment")]
|
||||
InvalidContentType(String),
|
||||
/// No se puede leer el archivo de un adjunto.
|
||||
#[error("cannot read attachment \"{path}\"")]
|
||||
ReadAttachment {
|
||||
/// Ruta del archivo.
|
||||
path: PathBuf,
|
||||
/// Error devuelto al leerlo.
|
||||
#[source]
|
||||
source: std::io::Error,
|
||||
},
|
||||
/// No se puede crear el directorio de los archivos de correo (`mail.file.dir`).
|
||||
#[error("cannot create mail directory \"{path}\"")]
|
||||
CreateDir {
|
||||
/// Ruta del directorio.
|
||||
path: PathBuf,
|
||||
/// Error devuelto al crearlo.
|
||||
#[source]
|
||||
source: std::io::Error,
|
||||
},
|
||||
/// No se puede componer el mensaje.
|
||||
#[error("cannot build email message")]
|
||||
Build(#[source] lettre::error::Error),
|
||||
/// Error de conexión, de cifrado o de entrega con el servidor SMTP.
|
||||
#[error("SMTP error")]
|
||||
Smtp(#[source] lettre::transport::smtp::Error),
|
||||
/// Error al entregar el correo al programa *sendmail*.
|
||||
#[error("sendmail error")]
|
||||
Sendmail(#[source] lettre::transport::sendmail::Error),
|
||||
/// Error al guardar el correo como archivo.
|
||||
#[error("cannot write email file")]
|
||||
File(#[source] lettre::transport::file::Error),
|
||||
}
|
||||
151
extensions/pagetop-mail/src/layout.rs
Normal file
151
extensions/pagetop-mail/src/layout.rs
Normal file
|
|
@ -0,0 +1,151 @@
|
|||
//! Diseño común del HTML de los correos y acción [`RenderMailLayout`] para cambiarlo.
|
||||
|
||||
use pagetop::prelude::*;
|
||||
|
||||
use crate::{Email, LOCALES_MAIL};
|
||||
|
||||
use std::ops::ControlFlow;
|
||||
|
||||
/// Tipo de función que genera el documento HTML completo de un correo.
|
||||
///
|
||||
/// Recibe:
|
||||
///
|
||||
/// - `cx`: contexto con el idioma del correo, para traducir los textos del diseño.
|
||||
/// - `email`: el correo, p. ej. para usar su asunto como título del documento.
|
||||
/// - `content`: el contenido HTML del correo, que el diseño debe incluir sin modificar.
|
||||
pub type FnRenderMailLayout = fn(cx: &Context, email: &Email, content: &Markup) -> Markup;
|
||||
|
||||
/// Acción para cambiar el diseño común del HTML de los correos.
|
||||
///
|
||||
/// Todos los correos con contenido HTML ([`Email::with_html()`] o una
|
||||
/// [`MailTemplate`](crate::MailTemplate)) se envuelven al enviarlos en un documento HTML completo:
|
||||
/// cabecera, estilos y pie. El diseño por defecto es sobrio y neutro: un recuadro blanco de hasta
|
||||
/// 600 píxeles de ancho sobre fondo gris, con el nombre de la aplicación al pie.
|
||||
///
|
||||
/// Una aplicación (o una extensión) registra esta acción para dar a **todos** los correos su propia
|
||||
/// imagen, incluidos los que envían otras extensiones como `pagetop-user`. Si hay varias, se aplica
|
||||
/// sólo la de menor peso.
|
||||
///
|
||||
/// Los clientes de correo ignoran las hojas de estilo externas y muchos ignoran también los estilos
|
||||
/// del `<head>`: lo seguro es escribir los estilos en línea (`style="..."`) y maquetar con tablas.
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// use pagetop::prelude::*;
|
||||
/// use pagetop_mail::prelude::*;
|
||||
///
|
||||
/// fn my_layout(cx: &Context, email: &Email, content: &Markup) -> Markup {
|
||||
/// html! {
|
||||
/// (DOCTYPE)
|
||||
/// html lang=(cx.langid().to_string()) {
|
||||
/// head {
|
||||
/// meta charset="utf-8";
|
||||
/// title { (email.subject()) }
|
||||
/// }
|
||||
/// body style="font-family: Georgia, serif;" {
|
||||
/// img src="https://example.com/logo.png" alt="Example" width="120";
|
||||
/// (content)
|
||||
/// }
|
||||
/// }
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// struct MyApp;
|
||||
///
|
||||
/// #[async_trait]
|
||||
/// impl Extension for MyApp {
|
||||
/// fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
/// vec![&pagetop_mail::Mail]
|
||||
/// }
|
||||
///
|
||||
/// fn actions(&self) -> Vec<ActionBox> {
|
||||
/// actions![RenderMailLayout::new(my_layout)]
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// [`Email::with_html()`]: crate::Email::with_html
|
||||
pub struct RenderMailLayout {
|
||||
f: FnRenderMailLayout,
|
||||
weight: Weight,
|
||||
}
|
||||
|
||||
impl ActionDispatcher for RenderMailLayout {
|
||||
fn weight(&self) -> Weight {
|
||||
self.weight
|
||||
}
|
||||
}
|
||||
|
||||
impl RenderMailLayout {
|
||||
/// Registra una función que genera el documento HTML de los correos.
|
||||
pub fn new(f: FnRenderMailLayout) -> Self {
|
||||
RenderMailLayout { f, weight: 0 }
|
||||
}
|
||||
|
||||
/// Opcional. Si varias extensiones registran esta acción, se aplica la de menor peso. Se pueden
|
||||
/// usar valores negativos.
|
||||
pub fn with_weight(mut self, value: Weight) -> Self {
|
||||
self.weight = value;
|
||||
self
|
||||
}
|
||||
}
|
||||
|
||||
// Genera el documento HTML del correo con la acción de menor peso o, sin ninguna, con el diseño por
|
||||
// defecto.
|
||||
pub(crate) fn render(cx: &Context, email: &Email, content: &Markup) -> Markup {
|
||||
let mut document = None;
|
||||
try_dispatch_actions(|action: &RenderMailLayout| {
|
||||
document = Some((action.f)(cx, email, content));
|
||||
ControlFlow::Break(())
|
||||
});
|
||||
document.unwrap_or_else(|| default_layout(cx, email, content))
|
||||
}
|
||||
|
||||
// Estilos en línea del diseño por defecto.
|
||||
const PAGE_STYLE: &str = "margin: 0; padding: 0; background-color: #f4f4f5;";
|
||||
const CARD_STYLE: &str = "max-width: 600px; background-color: #ffffff; border-radius: 6px;";
|
||||
const CONTENT_STYLE: &str = concat!(
|
||||
"font-family: -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; ",
|
||||
"padding: 32px; font-size: 16px; line-height: 1.5; color: #1f2937;"
|
||||
);
|
||||
const FOOTER_STYLE: &str = concat!(
|
||||
"font-family: -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; ",
|
||||
"margin: 16px 0 0; font-size: 12px; color: #6b7280;"
|
||||
);
|
||||
|
||||
fn default_layout(cx: &Context, email: &Email, content: &Markup) -> Markup {
|
||||
html! {
|
||||
(DOCTYPE)
|
||||
html lang=(cx.langid().to_string()) {
|
||||
head {
|
||||
meta charset="utf-8";
|
||||
meta name="viewport" content="width=device-width, initial-scale=1";
|
||||
meta name="color-scheme" content="light";
|
||||
title { (email.subject()) }
|
||||
}
|
||||
body style=(PAGE_STYLE) {
|
||||
table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0"
|
||||
style=(PAGE_STYLE)
|
||||
{
|
||||
tr {
|
||||
td align="center" style="padding: 24px 12px;" {
|
||||
table role="presentation" width="100%" cellpadding="0" cellspacing="0"
|
||||
border="0" style=(CARD_STYLE)
|
||||
{
|
||||
tr {
|
||||
td style=(CONTENT_STYLE) { (content) }
|
||||
}
|
||||
}
|
||||
p style=(FOOTER_STYLE) {
|
||||
(Lc::t("mail_footer", &LOCALES_MAIL)
|
||||
.with_arg("app", &global::SETTINGS.app.name)
|
||||
.using(cx))
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
339
extensions/pagetop-mail/src/lib.rs
Normal file
339
extensions/pagetop-mail/src/lib.rs
Normal file
|
|
@ -0,0 +1,339 @@
|
|||
/*!
|
||||
<div align="center">
|
||||
|
||||
<h1>PageTop Mail</h1>
|
||||
|
||||
<p>Envío de correo electrónico para aplicaciones <strong>PageTop</strong>.</p>
|
||||
|
||||
[](https://docs.rs/pagetop-mail)
|
||||
[](https://crates.io/crates/pagetop-mail)
|
||||
[](https://crates.io/crates/pagetop-mail)
|
||||
[](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/extensions/pagetop-mail#licencia)
|
||||
|
||||
</div>
|
||||
|
||||
Envía correos en texto plano y HTML, con archivos adjuntos e imágenes incrustadas, por SMTP, con el
|
||||
programa *sendmail* o a archivos `.eml`, todo configurado en los archivos TOML de la aplicación.
|
||||
Los correos pueden crearse con plantillas que traducen sus textos al idioma del destinatario, y
|
||||
comparten un diseño HTML común que la aplicación puede cambiar. Para las pruebas, los correos pueden
|
||||
guardarse en memoria en lugar de enviarse.
|
||||
|
||||
## Sobre PageTop
|
||||
|
||||
[PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web
|
||||
clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y
|
||||
configurables, basadas en HTML, CSS y JavaScript.
|
||||
|
||||
## Guía rápida
|
||||
|
||||
**Añade la dependencia** a tu `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
pagetop-mail = "..."
|
||||
```
|
||||
|
||||
**Declara la extensión** en tu aplicación o en la extensión que envíe correos:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
struct MyApp;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for MyApp {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_mail::Mail]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Configura el envío** en la sección `[mail]` (todas las opciones en [`config`]):
|
||||
|
||||
```toml
|
||||
[mail]
|
||||
transport = "smtp"
|
||||
from = "Mi Aplicación <no-reply@example.com>"
|
||||
base_url = "https://example.com"
|
||||
|
||||
[mail.smtp]
|
||||
host = "smtp.example.com"
|
||||
security = "starttls" # "none", "opportunistic", "starttls" o "tls".
|
||||
username = "no-reply@example.com"
|
||||
password = "secreto" # Mejor en config/local.toml, que no se versiona.
|
||||
```
|
||||
|
||||
Sin configurar, los correos se escriben en las trazas en lugar de enviarse (`transport = "log"`),
|
||||
así que una aplicación en desarrollo nunca envía correo real por error. La configuración se valida
|
||||
al arrancar: un ajuste no válido detiene la aplicación con un mensaje que indica el problema.
|
||||
|
||||
**Envía un correo** con [`Email`]:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_mail::prelude::*;
|
||||
|
||||
async fn notify() -> Result<(), MailError> {
|
||||
Email::new()
|
||||
.with_to("Ana Pérez <ana@example.com>")
|
||||
.with_subject("Tu pedido ha salido")
|
||||
.with_text("Tu pedido 1234 ha salido hoy.")
|
||||
.with_html(html! {
|
||||
p { "Tu pedido " strong { "1234" } " ha salido hoy." }
|
||||
})
|
||||
.send()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
[`Email::send()`] espera a que el correo se entregue; [`Email::send_later()`] lo envía en segundo
|
||||
plano y registra en las trazas los errores.
|
||||
|
||||
## Plantillas
|
||||
|
||||
Una [`MailTemplate`] genera el asunto, el HTML y el texto de un correo a partir de sus datos, con
|
||||
los textos traducidos mediante [`Lc`] al idioma del contexto que recibe. Así, cada extensión
|
||||
define sus correos como tipos propios, y el mismo correo se envía a cada destinatario en su idioma:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_mail::prelude::*;
|
||||
# include_locales!(LOCALES_SHOP);
|
||||
struct Welcome {
|
||||
name: String,
|
||||
}
|
||||
|
||||
impl MailTemplate for Welcome {
|
||||
fn subject(&self, cx: &Context) -> String {
|
||||
Lc::t("welcome-subject", &LOCALES_SHOP).lookup(cx).unwrap_or_default()
|
||||
}
|
||||
|
||||
fn html(&self, cx: &Context) -> Option<Markup> {
|
||||
let greeting = Lc::t("welcome-greeting", &LOCALES_SHOP).with_arg("name", self.name.clone());
|
||||
Some(html! {
|
||||
p { (greeting.using(cx)) }
|
||||
p {
|
||||
a href=(absolute_url("/shop")) { (Lc::t("welcome-visit", &LOCALES_SHOP).using(cx)) }
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
async fn welcome(request: HttpRequest) -> Result<(), MailError> {
|
||||
// El contexto de la petición: el correo sale en el idioma de quien se acaba de registrar.
|
||||
let cx = Context::new(request);
|
||||
Email::from_template(&Welcome { name: "Ana".to_string() }, &cx)
|
||||
.with_to("ana@example.com")
|
||||
.send()
|
||||
.await
|
||||
}
|
||||
```
|
||||
|
||||
## Enlaces en los correos
|
||||
|
||||
Los enlaces de un correo deben ser absolutos. [`absolute_url()`] antepone a una ruta la URL pública
|
||||
de la aplicación, que se configura en `mail.base_url`. No se deduce de la petición, porque la
|
||||
cabecera `Host` la elige el cliente y un atacante podría hacer que los enlaces de un correo de
|
||||
recuperación de contraseña apuntaran a su propio servidor.
|
||||
|
||||
## Adjuntos e imágenes incrustadas
|
||||
|
||||
Un [`Attachment`] se crea con un contenido en memoria o leyendo un archivo, y su tipo MIME se deduce
|
||||
del nombre. Con [`Attachment::with_content_id()`] se incrusta en el HTML, que lo muestra con
|
||||
`cid:`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_mail::prelude::*;
|
||||
# async fn example(png: Vec<u8>) -> Result<(), MailError> {
|
||||
Email::new()
|
||||
.with_to("ana@example.com")
|
||||
.with_subject("Informe")
|
||||
.with_html(html! { img src="cid:logo" alt="Logo"; p { "Adjunto el informe." } })
|
||||
.with_attachment(Attachment::new("logo.png", png).with_content_id("logo"))
|
||||
.with_attachment(Attachment::from_path("informes/octubre.pdf").await?)
|
||||
.send()
|
||||
.await
|
||||
# }
|
||||
```
|
||||
|
||||
## Diseño común del HTML
|
||||
|
||||
El HTML de los correos es sólo su contenido: al enviarlos se envuelve en un documento con un diseño
|
||||
sobrio y neutro. La aplicación puede darle su propia imagen a **todos** los correos, incluidos los
|
||||
de otras extensiones, registrando la acción [`RenderMailLayout`].
|
||||
|
||||
## Vistas previas en el navegador
|
||||
|
||||
Con `previews = true` en `[mail]` (sólo en desarrollo), `/mail/preview` lista los correos que las
|
||||
extensiones declaran con la acción [`DeclareMailPreviews`], y muestra cada uno con datos de ejemplo:
|
||||
cabeceras, HTML con el diseño común, texto plano y adjuntos, sin enviar nada. Ver [`preview`].
|
||||
|
||||
## Texto plano automático
|
||||
|
||||
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.
|
||||
|
||||
## Transportes
|
||||
|
||||
Se elige en `mail.transport`:
|
||||
|
||||
| Valor | Uso |
|
||||
|--------------|-----------------------------------------------------------------------------|
|
||||
| `"smtp"` | Producción. Servidor SMTP con conexiones reutilizables y cifrado TLS. |
|
||||
| `"sendmail"` | Producción, con un servidor de correo local (Postfix, Exim...). |
|
||||
| `"file"` | Desarrollo. Guarda cada correo como `.eml` para abrirlo con un cliente. |
|
||||
| `"log"` | Por defecto. Escribe los correos en las trazas, sin enviarlos. |
|
||||
| `"memory"` | Pruebas. Guarda los correos en memoria para comprobarlos con [`outbox`]. |
|
||||
|
||||
En entornos de pruebas con datos reales, `mail.redirect_to` entrega todos los correos a una sola
|
||||
dirección, sin cambiar sus cabeceras.
|
||||
|
||||
Para probar el envío SMTP en desarrollo sin enviar correo real, un servidor como
|
||||
[Mailpit](https://mailpit.axllent.org) recoge los correos y los muestra en el navegador:
|
||||
|
||||
```toml
|
||||
[mail]
|
||||
transport = "smtp"
|
||||
|
||||
[mail.smtp]
|
||||
host = "localhost"
|
||||
port = 1025
|
||||
security = "none"
|
||||
```
|
||||
*/
|
||||
|
||||
#![doc(
|
||||
html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/assets/favicon.ico"
|
||||
)]
|
||||
|
||||
use pagetop::prelude::*;
|
||||
|
||||
use std::sync::LazyLock;
|
||||
|
||||
pub mod config;
|
||||
|
||||
mod error;
|
||||
pub use error::MailError;
|
||||
|
||||
mod mailbox;
|
||||
pub use mailbox::Mailbox;
|
||||
|
||||
mod attachment;
|
||||
pub use attachment::Attachment;
|
||||
|
||||
mod template;
|
||||
pub use template::MailTemplate;
|
||||
|
||||
mod layout;
|
||||
pub use layout::{FnRenderMailLayout, RenderMailLayout};
|
||||
|
||||
mod email;
|
||||
pub use email::Email;
|
||||
|
||||
pub mod outbox;
|
||||
|
||||
pub mod preview;
|
||||
pub use preview::{DeclareMailPreviews, MailPreviews};
|
||||
|
||||
mod text;
|
||||
|
||||
mod transport;
|
||||
|
||||
include_locales!(LOCALES_MAIL);
|
||||
|
||||
/// Prelude de `pagetop-mail`.
|
||||
pub mod prelude {
|
||||
pub use crate::absolute_url;
|
||||
pub use crate::{Attachment, Email, MailError, MailTemplate, Mailbox};
|
||||
pub use crate::{DeclareMailPreviews, MailPreviews, RenderMailLayout};
|
||||
}
|
||||
|
||||
/// Implementa la extensión `pagetop-mail`.
|
||||
pub struct Mail;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Mail {
|
||||
fn name(&self) -> Lc {
|
||||
Lc::t("extension_name", &LOCALES_MAIL)
|
||||
}
|
||||
|
||||
fn description(&self) -> Lc {
|
||||
Lc::t("extension_description", &LOCALES_MAIL)
|
||||
}
|
||||
|
||||
fn settings(&self) -> Option<&'static dyn LoadSettings> {
|
||||
Some(&config::SETTINGS)
|
||||
}
|
||||
|
||||
async fn initialize(&self) -> Result<(), BoxError> {
|
||||
// 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();
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
if !config::SETTINGS.previews {
|
||||
return router;
|
||||
}
|
||||
router
|
||||
.route(preview::PREVIEW_PATH, web::get(preview::list_get))
|
||||
.route(
|
||||
&util::join!(preview::PREVIEW_PATH, "/{key}"),
|
||||
web::get(preview::preview_get),
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
/// Devuelve la URL absoluta de una ruta de la aplicación, para los enlaces de los correos.
|
||||
///
|
||||
/// Antepone a la ruta la URL pública configurada en `mail.base_url` o, si no hay ninguna, la
|
||||
/// dirección y el puerto de escucha del servidor (sólo útil en desarrollo). Una ruta que ya es una
|
||||
/// URL externa (`https://...`) se devuelve sin cambios.
|
||||
///
|
||||
/// Si la ruta debe conservar el idioma de la petición en curso, constrúyela con
|
||||
/// [`Context::route()`].
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// # use pagetop::prelude::*;
|
||||
/// # use pagetop_mail::prelude::*;
|
||||
/// // Con `base_url = "https://example.com"`.
|
||||
/// assert_eq!(absolute_url("/user/verify"), "https://example.com/user/verify");
|
||||
/// ```
|
||||
pub fn absolute_url(path: impl Into<RoutePath>) -> String {
|
||||
let path = path.into().to_string();
|
||||
if util::url_looks_external(&path) {
|
||||
return path;
|
||||
}
|
||||
if path.starts_with('/') {
|
||||
util::join!(base_url(), path)
|
||||
} else {
|
||||
util::join!(base_url(), "/", path)
|
||||
}
|
||||
}
|
||||
|
||||
// URL pública de la aplicación, sin la barra final.
|
||||
fn base_url() -> &'static str {
|
||||
static BASE_URL: LazyLock<String> = LazyLock::new(|| {
|
||||
match config::SETTINGS
|
||||
.base_url
|
||||
.as_deref()
|
||||
.and_then(util::non_blank)
|
||||
{
|
||||
Some(url) => url.trim_end_matches('/').to_owned(),
|
||||
None => {
|
||||
let server = &global::SETTINGS.server;
|
||||
util::join!(
|
||||
"http://",
|
||||
&server.bind_address,
|
||||
":",
|
||||
server.bind_port.to_string()
|
||||
)
|
||||
}
|
||||
}
|
||||
});
|
||||
&BASE_URL
|
||||
}
|
||||
20
extensions/pagetop-mail/src/locale/en-US/extension.ftl
Normal file
20
extensions/pagetop-mail/src/locale/en-US/extension.ftl
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
extension_name = Mail
|
||||
extension_description = Sends emails over SMTP, sendmail or files, with templates, HTML and attachments.
|
||||
|
||||
mail_footer = Message sent by { $app }.
|
||||
|
||||
# **< Email previews >**
|
||||
|
||||
preview_title = Email previews
|
||||
preview_empty = No extension declares email previews.
|
||||
preview_back = Back to the list
|
||||
preview_from = From
|
||||
preview_reply_to = Reply to
|
||||
preview_to = To
|
||||
preview_cc = Cc
|
||||
preview_bcc = Bcc
|
||||
preview_subject = Subject
|
||||
preview_attachments = Attachments
|
||||
preview_html = HTML
|
||||
preview_text = Plain text
|
||||
preview_none = None
|
||||
20
extensions/pagetop-mail/src/locale/es-ES/extension.ftl
Normal file
20
extensions/pagetop-mail/src/locale/es-ES/extension.ftl
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
extension_name = Correo electrónico
|
||||
extension_description = Envía correos por SMTP, sendmail o archivos, con plantillas, HTML y adjuntos.
|
||||
|
||||
mail_footer = Mensaje enviado por { $app }.
|
||||
|
||||
# **< Vistas previas de correos >**
|
||||
|
||||
preview_title = Vistas previas de correos
|
||||
preview_empty = Ninguna extensión declara vistas previas de correos.
|
||||
preview_back = Volver a la lista
|
||||
preview_from = Remitente
|
||||
preview_reply_to = Responder a
|
||||
preview_to = Para
|
||||
preview_cc = Cc
|
||||
preview_bcc = Cco
|
||||
preview_subject = Asunto
|
||||
preview_attachments = Adjuntos
|
||||
preview_html = HTML
|
||||
preview_text = Texto plano
|
||||
preview_none = Ninguno
|
||||
138
extensions/pagetop-mail/src/mailbox.rs
Normal file
138
extensions/pagetop-mail/src/mailbox.rs
Normal file
|
|
@ -0,0 +1,138 @@
|
|||
//! Direcciones de correo con nombre opcional ([`Mailbox`]).
|
||||
|
||||
use pagetop::prelude::*;
|
||||
|
||||
use crate::MailError;
|
||||
|
||||
use std::fmt;
|
||||
|
||||
/// Dirección de correo, con el nombre opcional de su titular.
|
||||
///
|
||||
/// Se crea a partir de una cadena con la dirección sola (`"ana@example.com"`) o con nombre
|
||||
/// (`"Ana Pérez <ana@example.com>"`, o con el nombre entre comillas), o de una tupla
|
||||
/// `(nombre, dirección)`. Ésta última es la forma segura cuando el nombre procede de datos de
|
||||
/// usuario, porque puede contener comas, comillas u otros caracteres especiales.
|
||||
///
|
||||
/// La dirección no se valida al crearla, sino al enviar el correo, que falla con
|
||||
/// [`MailError::InvalidAddress`] si no es válida.
|
||||
///
|
||||
/// # Ejemplos
|
||||
///
|
||||
/// ```rust
|
||||
/// # use pagetop_mail::prelude::*;
|
||||
/// let ana = Mailbox::from("Ana Pérez <ana@example.com>");
|
||||
/// assert_eq!(ana.name(), Some(&"Ana Pérez".to_string()));
|
||||
/// assert_eq!(ana.address(), "ana@example.com");
|
||||
///
|
||||
/// let luis = Mailbox::from(("Luis, el de soporte", "luis@example.com"));
|
||||
/// assert_eq!(luis.name(), Some(&"Luis, el de soporte".to_string()));
|
||||
///
|
||||
/// let anon = Mailbox::from("no-reply@example.com");
|
||||
/// assert_eq!(anon.name(), None);
|
||||
/// ```
|
||||
#[derive(AutoDefault, Clone, Debug, Eq, Getters, PartialEq)]
|
||||
pub struct Mailbox {
|
||||
/// Nombre del titular, si lo tiene.
|
||||
name: Option<String>,
|
||||
/// Dirección de correo.
|
||||
address: String,
|
||||
}
|
||||
|
||||
impl Mailbox {
|
||||
/// Crea una dirección de correo sin nombre.
|
||||
pub fn new(address: impl Into<String>) -> Self {
|
||||
Mailbox {
|
||||
name: None,
|
||||
address: address.into().trim().to_owned(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Crea una dirección de correo con el nombre de su titular. Un nombre vacío equivale a no
|
||||
/// indicarlo, y los caracteres de control del nombre (saltos de línea, tabuladores...) se
|
||||
/// cambian por espacios.
|
||||
pub fn with_name(name: impl Into<String>, address: impl Into<String>) -> Self {
|
||||
// `lettre` provoca un `panic!` al componer una cabecera con un nombre que tenga caracteres
|
||||
// de control, y el nombre puede proceder de datos de usuario.
|
||||
let name: String = name
|
||||
.into()
|
||||
.chars()
|
||||
.map(|c| if c.is_control() { ' ' } else { c })
|
||||
.collect();
|
||||
Mailbox {
|
||||
name: util::non_blank(&name).map(str::to_owned),
|
||||
..Mailbox::new(address)
|
||||
}
|
||||
}
|
||||
|
||||
/// Comprueba que la dirección sea válida, con el mismo criterio que se aplica al enviar.
|
||||
///
|
||||
/// Sirve para validar una dirección al recibirla (p. ej. de un formulario), antes de guardarla.
|
||||
/// Falla con [`MailError::InvalidAddress`] si no es válida.
|
||||
///
|
||||
/// ```rust
|
||||
/// # use pagetop_mail::prelude::*;
|
||||
/// assert!(Mailbox::new("ana@example.com").validate().is_ok());
|
||||
/// assert!(Mailbox::new("ana.example.com").validate().is_err());
|
||||
/// ```
|
||||
pub fn validate(&self) -> Result<(), MailError> {
|
||||
self.to_lettre().map(drop)
|
||||
}
|
||||
|
||||
// Convierte la dirección al tipo de `lettre`, validándola.
|
||||
pub(crate) fn to_lettre(&self) -> Result<lettre::message::Mailbox, MailError> {
|
||||
let address = self.address.parse::<lettre::Address>().map_err(|source| {
|
||||
MailError::InvalidAddress {
|
||||
address: self.address.clone(),
|
||||
source,
|
||||
}
|
||||
})?;
|
||||
Ok(lettre::message::Mailbox::new(self.name.clone(), address))
|
||||
}
|
||||
}
|
||||
|
||||
impl From<&str> for Mailbox {
|
||||
fn from(value: &str) -> Self {
|
||||
let value = value.trim();
|
||||
// "Nombre <dirección>": la dirección es lo que va entre los últimos `<` y `>`.
|
||||
if let Some(rest) = value.strip_suffix('>')
|
||||
&& let Some((name, address)) = rest.rsplit_once('<')
|
||||
{
|
||||
let name = name.trim();
|
||||
let name = name
|
||||
.strip_prefix('"')
|
||||
.and_then(|n| n.strip_suffix('"'))
|
||||
.unwrap_or(name);
|
||||
return Mailbox::with_name(name, address);
|
||||
}
|
||||
Mailbox::new(value)
|
||||
}
|
||||
}
|
||||
|
||||
impl From<String> for Mailbox {
|
||||
fn from(value: String) -> Self {
|
||||
Mailbox::from(value.as_str())
|
||||
}
|
||||
}
|
||||
|
||||
impl From<&String> for Mailbox {
|
||||
fn from(value: &String) -> Self {
|
||||
Mailbox::from(value.as_str())
|
||||
}
|
||||
}
|
||||
|
||||
impl<N: Into<String>, A: Into<String>> From<(N, A)> for Mailbox {
|
||||
fn from((name, address): (N, A)) -> Self {
|
||||
Mailbox::with_name(name, address)
|
||||
}
|
||||
}
|
||||
|
||||
/// Muestra la dirección como `Nombre <dirección>`, o sólo la dirección si no tiene nombre. Es una
|
||||
/// representación para trazas y pruebas, no la codificación de las cabeceras del correo.
|
||||
impl fmt::Display for Mailbox {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
match &self.name {
|
||||
Some(name) => write!(f, "{name} <{}>", self.address),
|
||||
None => f.write_str(&self.address),
|
||||
}
|
||||
}
|
||||
}
|
||||
87
extensions/pagetop-mail/src/outbox.rs
Normal file
87
extensions/pagetop-mail/src/outbox.rs
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
//! Correos guardados en memoria por el transporte `"memory"`, para comprobarlos en las pruebas.
|
||||
//!
|
||||
//! Con `transport = "memory"` en la sección `[mail]` de la configuración de pruebas, los correos no
|
||||
//! se envían: se guardan aquí, ya completos (con el remitente por defecto y el documento HTML con
|
||||
//! el diseño común), y las pruebas los recogen con [`take()`] o [`take_to()`].
|
||||
//!
|
||||
//! Los correos se acumulan mientras nadie los recoja, así que este transporte no debe usarse fuera
|
||||
//! de las pruebas.
|
||||
//!
|
||||
//! # Ejemplo
|
||||
//!
|
||||
//! ```rust,no_run
|
||||
//! use pagetop::prelude::*;
|
||||
//! use pagetop_mail::prelude::*;
|
||||
//! use pagetop_mail::outbox;
|
||||
//!
|
||||
//! #[pagetop::test]
|
||||
//! async fn sends_welcome_email() {
|
||||
//! // ... ejecuta lo que debe enviar el correo a ana@example.com ...
|
||||
//!
|
||||
//! let sent = outbox::take_to("ana@example.com");
|
||||
//! assert_eq!(sent.len(), 1);
|
||||
//! assert_eq!(sent[0].email().subject(), "Bienvenida");
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! 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.
|
||||
|
||||
use pagetop::prelude::*;
|
||||
|
||||
use crate::Email;
|
||||
|
||||
use std::sync::{Mutex, MutexGuard, PoisonError};
|
||||
|
||||
static OUTBOX: Mutex<Vec<SentEmail>> = Mutex::new(Vec::new());
|
||||
|
||||
/// Correo guardado por el transporte `"memory"`.
|
||||
#[derive(Clone, Debug, Getters)]
|
||||
pub struct SentEmail {
|
||||
/// El correo tal como se envió, con el remitente y la dirección de respuesta por defecto ya
|
||||
/// aplicados, y el documento HTML completo.
|
||||
email: Email,
|
||||
/// Direcciones a las que se entregó (todas, incluidas las de `Cc` y `Bcc`, o sólo la de
|
||||
/// `mail.redirect_to` si está configurada).
|
||||
envelope_to: Vec<String>,
|
||||
/// Mensaje completo en formato RFC 5322, con cabeceras y partes codificadas.
|
||||
raw: String,
|
||||
}
|
||||
|
||||
impl SentEmail {
|
||||
/// Indica si el correo se entregó a la dirección dada (sin distinguir mayúsculas).
|
||||
pub fn is_delivered_to(&self, address: &str) -> bool {
|
||||
self.envelope_to
|
||||
.iter()
|
||||
.any(|to| to.eq_ignore_ascii_case(address.trim()))
|
||||
}
|
||||
}
|
||||
|
||||
/// Recoge todos los correos guardados, en el orden en que se enviaron.
|
||||
pub fn take() -> Vec<SentEmail> {
|
||||
std::mem::take(&mut *lock())
|
||||
}
|
||||
|
||||
/// Recoge los correos entregados a la dirección dada, en el orden en que se enviaron, y deja los
|
||||
/// demás.
|
||||
pub fn take_to(address: &str) -> Vec<SentEmail> {
|
||||
let mut outbox = lock();
|
||||
let (taken, kept) = outbox
|
||||
.drain(..)
|
||||
.partition(|sent: &SentEmail| sent.is_delivered_to(address));
|
||||
*outbox = kept;
|
||||
taken
|
||||
}
|
||||
|
||||
pub(crate) fn push(email: Email, envelope_to: Vec<String>, raw: Vec<u8>) {
|
||||
lock().push(SentEmail {
|
||||
email,
|
||||
envelope_to,
|
||||
raw: String::from_utf8_lossy(&raw).into_owned(),
|
||||
});
|
||||
}
|
||||
|
||||
// Una prueba que falla con el bloqueo tomado no debe impedir que las demás sigan usándolo.
|
||||
fn lock() -> MutexGuard<'static, Vec<SentEmail>> {
|
||||
OUTBOX.lock().unwrap_or_else(PoisonError::into_inner)
|
||||
}
|
||||
248
extensions/pagetop-mail/src/preview.rs
Normal file
248
extensions/pagetop-mail/src/preview.rs
Normal file
|
|
@ -0,0 +1,248 @@
|
|||
//! Vistas previas de los correos en el navegador ([`DeclareMailPreviews`]).
|
||||
//!
|
||||
//! Con `previews = true` en la sección `[mail]`, la aplicación ofrece en [`PREVIEW_PATH`] la lista
|
||||
//! de los correos que declaran las extensiones, y una página para cada uno con sus cabeceras, el
|
||||
//! HTML tal como se enviaría (con el diseño común), su texto plano y sus adjuntos. Así se diseñan y
|
||||
//! revisan los correos sin enviarlos.
|
||||
//!
|
||||
//! Las vistas previas usan datos de ejemplo y no envían nada, pero muestran las plantillas a
|
||||
//! cualquiera que conozca la ruta: **actívalas sólo en desarrollo**.
|
||||
//!
|
||||
//! Cada vista previa se genera con el contexto de la petición, así que se puede ver en otro idioma
|
||||
//! añadiendo `?lang=` a la ruta (p. ej. `/mail/preview/user.password_reset?lang=en-US`), si la
|
||||
//! negociación de idioma lo permite.
|
||||
|
||||
use pagetop::prelude::*;
|
||||
|
||||
use crate::{Email, LOCALES_MAIL, transport};
|
||||
|
||||
/// Ruta de la lista de vistas previas. Cada correo se ve en `{PREVIEW_PATH}/{clave}`.
|
||||
pub const PREVIEW_PATH: &str = "/mail/preview";
|
||||
|
||||
/// Tipo de función que genera un correo de ejemplo para su vista previa.
|
||||
///
|
||||
/// Recibe el contexto de la petición, con su idioma, y devuelve el correo como se enviaría, con
|
||||
/// datos de ejemplo. Para que la vista previa siga el idioma de la petición, el correo debe crearse
|
||||
/// con [`Email::from_template()`] o indicar el idioma con [`Email::with_langid()`].
|
||||
pub type FnMailPreview = fn(cx: &Context) -> Email;
|
||||
|
||||
/// Tipo de función que declara vistas previas en un [`MailPreviews`].
|
||||
pub type FnDeclareMailPreviews = fn(previews: &mut MailPreviews);
|
||||
|
||||
/// Vistas previas declaradas por las extensiones. Ver [`DeclareMailPreviews`].
|
||||
#[derive(AutoDefault)]
|
||||
pub struct MailPreviews {
|
||||
previews: Vec<MailPreview>,
|
||||
}
|
||||
|
||||
struct MailPreview {
|
||||
key: &'static str,
|
||||
title: Lc,
|
||||
build: FnMailPreview,
|
||||
}
|
||||
|
||||
impl MailPreviews {
|
||||
/// Añade la vista previa de un correo.
|
||||
///
|
||||
/// - `key`: identificador único, que forma parte de la ruta (p. ej. `"shop.order_shipped"`).
|
||||
/// Conviene empezarlo por el nombre de la extensión.
|
||||
/// - `title`: título descriptivo para la lista.
|
||||
/// - `build`: función que genera el correo con datos de ejemplo.
|
||||
pub fn add(&mut self, key: &'static str, title: Lc, build: FnMailPreview) {
|
||||
self.previews.push(MailPreview { key, title, build });
|
||||
}
|
||||
|
||||
// Recoge las vistas previas de todas las extensiones, ordenadas por su clave.
|
||||
fn collect() -> Self {
|
||||
let mut previews = MailPreviews::default();
|
||||
dispatch_actions(|action: &DeclareMailPreviews| (action.f)(&mut previews));
|
||||
previews.previews.sort_by_key(|preview| preview.key);
|
||||
previews
|
||||
}
|
||||
}
|
||||
|
||||
/// Acción para declarar vistas previas de correos.
|
||||
///
|
||||
/// Cada extensión que envía correos puede registrar esta acción para que sus correos se puedan
|
||||
/// revisar en el navegador con datos de ejemplo (ver la [documentación del módulo](self)).
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// use pagetop::prelude::*;
|
||||
/// use pagetop_mail::prelude::*;
|
||||
///
|
||||
/// fn order_shipped(cx: &Context) -> Email {
|
||||
/// Email::new()
|
||||
/// .with_to("cliente@example.com")
|
||||
/// .with_subject("Tu pedido ha salido")
|
||||
/// .with_html(html! { p { "Tu pedido " strong { "1234" } " ha salido hoy." } })
|
||||
/// .with_langid(cx)
|
||||
/// }
|
||||
///
|
||||
/// fn declare_previews(previews: &mut MailPreviews) {
|
||||
/// previews.add("shop.order_shipped", Lc::n("Pedido enviado"), order_shipped);
|
||||
/// }
|
||||
///
|
||||
/// struct Shop;
|
||||
///
|
||||
/// #[async_trait]
|
||||
/// impl Extension for Shop {
|
||||
/// fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
/// vec![&pagetop_mail::Mail]
|
||||
/// }
|
||||
///
|
||||
/// fn actions(&self) -> Vec<ActionBox> {
|
||||
/// actions![DeclareMailPreviews::new(declare_previews)]
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
pub struct DeclareMailPreviews {
|
||||
f: FnDeclareMailPreviews,
|
||||
weight: Weight,
|
||||
}
|
||||
|
||||
impl ActionDispatcher for DeclareMailPreviews {
|
||||
fn weight(&self) -> Weight {
|
||||
self.weight
|
||||
}
|
||||
}
|
||||
|
||||
impl DeclareMailPreviews {
|
||||
/// Registra una función que declara vistas previas.
|
||||
pub fn new(f: FnDeclareMailPreviews) -> Self {
|
||||
DeclareMailPreviews { f, weight: 0 }
|
||||
}
|
||||
|
||||
/// Opcional. Las acciones de menor peso se aplican antes. Se pueden usar valores negativos.
|
||||
pub fn with_weight(mut self, value: Weight) -> Self {
|
||||
self.weight = value;
|
||||
self
|
||||
}
|
||||
}
|
||||
|
||||
// **< Handlers >***********************************************************************************
|
||||
|
||||
// GET {PREVIEW_PATH} - Lista de las vistas previas.
|
||||
pub(crate) async fn list_get(request: HttpRequest) -> Result<Markup, ErrorPage> {
|
||||
Page::new(request)
|
||||
.with_title(Lc::t("preview_title", &LOCALES_MAIL))
|
||||
.with_child(Html::with(|cx| {
|
||||
let previews = MailPreviews::collect();
|
||||
html! {
|
||||
h1 { (Lc::t("preview_title", &LOCALES_MAIL).using(cx)) }
|
||||
@if previews.previews.is_empty() {
|
||||
p { (Lc::t("preview_empty", &LOCALES_MAIL).using(cx)) }
|
||||
} @else {
|
||||
ul {
|
||||
@for preview in &previews.previews {
|
||||
li {
|
||||
a href=(cx.route(preview_path(preview.key))) {
|
||||
(preview.title.using(cx))
|
||||
}
|
||||
" "
|
||||
code { (preview.key) }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
// GET {PREVIEW_PATH}/{key} - Vista previa de un correo.
|
||||
pub(crate) async fn preview_get(
|
||||
request: HttpRequest,
|
||||
web::Path(key): web::Path<String>,
|
||||
) -> Result<Markup, ErrorPage> {
|
||||
let previews = MailPreviews::collect();
|
||||
let Some(preview) = previews.previews.iter().find(|p| p.key == key) else {
|
||||
return Err(ErrorPage::NotFound(Some(request)));
|
||||
};
|
||||
let cx = Context::new(request.clone());
|
||||
let email = transport::prepare_preview((preview.build)(&cx));
|
||||
let title = preview.title.clone();
|
||||
Page::new(request)
|
||||
.with_title(title.clone())
|
||||
.with_child(Html::with(move |cx| render_preview(cx, &title, &email)))
|
||||
.render()
|
||||
.await
|
||||
}
|
||||
|
||||
fn preview_path(key: &str) -> String {
|
||||
util::join!(PREVIEW_PATH, "/", key)
|
||||
}
|
||||
|
||||
fn render_preview(cx: &mut Context, title: &Lc, email: &Email) -> Markup {
|
||||
let none = Lc::t("preview_none", &LOCALES_MAIL);
|
||||
let list = |mailboxes: &[crate::Mailbox]| {
|
||||
let mut list = String::new();
|
||||
for mailbox in mailboxes {
|
||||
if !list.is_empty() {
|
||||
list.push_str(", ");
|
||||
}
|
||||
list.push_str(&mailbox.to_string());
|
||||
}
|
||||
list
|
||||
};
|
||||
let headers = [
|
||||
("preview_from", email.from().map(ToString::to_string)),
|
||||
(
|
||||
"preview_reply_to",
|
||||
email.reply_to().map(ToString::to_string),
|
||||
),
|
||||
("preview_to", Some(list(email.to()))),
|
||||
("preview_cc", Some(list(email.cc()))),
|
||||
("preview_bcc", Some(list(email.bcc()))),
|
||||
("preview_subject", Some(email.subject().to_owned())),
|
||||
];
|
||||
html! {
|
||||
p { a href=(cx.route(PREVIEW_PATH)) { (Lc::t("preview_back", &LOCALES_MAIL).using(cx)) } }
|
||||
h1 { (title.using(cx)) }
|
||||
dl {
|
||||
@for (label, value) in headers {
|
||||
dt { (Lc::t(label, &LOCALES_MAIL).using(cx)) }
|
||||
dd {
|
||||
@match value.filter(|v| !v.is_empty()) {
|
||||
Some(value) => (value),
|
||||
None => em { (none.using(cx)) },
|
||||
}
|
||||
}
|
||||
}
|
||||
dt { (Lc::t("preview_attachments", &LOCALES_MAIL).using(cx)) }
|
||||
dd {
|
||||
@if email.attachments().is_empty() {
|
||||
em { (none.using(cx)) }
|
||||
} @else {
|
||||
ul {
|
||||
@for attachment in email.attachments() {
|
||||
li {
|
||||
(attachment.filename()) " (" (attachment.content_type()) ", "
|
||||
(attachment.body().len()) " B"
|
||||
@if let Some(id) = attachment.content_id() {
|
||||
", cid:" (id)
|
||||
}
|
||||
")"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@if let Some(html) = email.html() {
|
||||
h2 { (Lc::t("preview_html", &LOCALES_MAIL).using(cx)) }
|
||||
// `sandbox` vacío aísla el correo: sin scripts, sin formularios y sin navegar desde él.
|
||||
iframe
|
||||
title=[Lc::t("preview_html", &LOCALES_MAIL).lookup(cx)]
|
||||
srcdoc=(html.as_str())
|
||||
sandbox=""
|
||||
style="width: 100%; height: 640px; border: 1px solid #d1d5db;" {}
|
||||
}
|
||||
@if let Some(text) = email.text() {
|
||||
h2 { (Lc::t("preview_text", &LOCALES_MAIL).using(cx)) }
|
||||
pre style="white-space: pre-wrap;" { (text) }
|
||||
}
|
||||
}
|
||||
}
|
||||
85
extensions/pagetop-mail/src/template.rs
Normal file
85
extensions/pagetop-mail/src/template.rs
Normal file
|
|
@ -0,0 +1,85 @@
|
|||
//! Plantillas de correo ([`MailTemplate`]).
|
||||
|
||||
use pagetop::prelude::*;
|
||||
|
||||
/// Plantilla de correo: asunto, contenido HTML y texto plano generados a partir de unos datos.
|
||||
///
|
||||
/// Una plantilla es un tipo propio con los datos que necesita el correo (nombre del destinatario,
|
||||
/// enlaces, importes...). Sus métodos reciben un [`Context`] con el idioma del destinatario, así
|
||||
/// que los textos se escriben con [`Lc`] y el HTML con [`html!`], igual que en un componente, y
|
||||
/// las fechas se formatean con los métodos de [`Contextual`].
|
||||
///
|
||||
/// El correo se crea con [`Email::from_template()`](crate::Email::from_template), que llama a los
|
||||
/// tres métodos. El HTML es sólo el **contenido**: al enviarlo se envuelve en el diseño común de
|
||||
/// los correos (ver [`RenderMailLayout`](crate::RenderMailLayout)). El texto plano es opcional: si
|
||||
/// la plantilla sólo genera HTML, al enviar el correo se obtiene a partir de él. Escríbelo sólo si
|
||||
/// el generado no queda bien.
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// use pagetop::prelude::*;
|
||||
/// use pagetop_mail::prelude::*;
|
||||
///
|
||||
/// include_locales!(LOCALES_SHOP);
|
||||
///
|
||||
/// struct OrderShipped {
|
||||
/// customer: String,
|
||||
/// order: u32,
|
||||
/// tracking_url: String,
|
||||
/// }
|
||||
///
|
||||
/// impl MailTemplate for OrderShipped {
|
||||
/// fn subject(&self, cx: &Context) -> String {
|
||||
/// Lc::t("mail-shipped-subject", &LOCALES_SHOP)
|
||||
/// .with_arg("order", self.order.to_string())
|
||||
/// .lookup(cx)
|
||||
/// .unwrap_or_default()
|
||||
/// }
|
||||
///
|
||||
/// fn html(&self, cx: &Context) -> Option<Markup> {
|
||||
/// let greeting =
|
||||
/// Lc::t("mail-greeting", &LOCALES_SHOP).with_arg("name", self.customer.clone());
|
||||
/// let track = Lc::t("mail-track", &LOCALES_SHOP);
|
||||
/// Some(html! {
|
||||
/// p { (greeting.using(cx)) }
|
||||
/// p { a href=(self.tracking_url) { (track.using(cx)) } }
|
||||
/// })
|
||||
/// }
|
||||
///
|
||||
/// fn text(&self, cx: &Context) -> Option<String> {
|
||||
/// let greeting = Lc::t("mail-greeting", &LOCALES_SHOP)
|
||||
/// .with_arg("name", self.customer.clone())
|
||||
/// .lookup(cx)
|
||||
/// .unwrap_or_default();
|
||||
/// Some(util::join!(greeting, "\n\n", &self.tracking_url))
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// async fn notify(language: &impl LangId) -> Result<(), MailError> {
|
||||
/// let template = OrderShipped {
|
||||
/// customer: "Ana".to_string(),
|
||||
/// order: 1234,
|
||||
/// tracking_url: absolute_url("/orders/1234"),
|
||||
/// };
|
||||
/// let cx = Context::default().with_langid(language);
|
||||
/// Email::from_template(&template, &cx)
|
||||
/// .with_to("ana@example.com")
|
||||
/// .send()
|
||||
/// .await
|
||||
/// }
|
||||
/// ```
|
||||
pub trait MailTemplate {
|
||||
/// Asunto del correo, en el idioma del contexto.
|
||||
fn subject(&self, cx: &Context) -> String;
|
||||
|
||||
/// Contenido HTML del correo, sin el documento que lo envuelve. Por defecto, ninguno.
|
||||
fn html(&self, _cx: &Context) -> Option<Markup> {
|
||||
None
|
||||
}
|
||||
|
||||
/// Texto plano del correo. Por defecto, ninguno: al enviarlo se genera a partir del HTML.
|
||||
fn text(&self, _cx: &Context) -> Option<String> {
|
||||
None
|
||||
}
|
||||
}
|
||||
402
extensions/pagetop-mail/src/text.rs
Normal file
402
extensions/pagetop-mail/src/text.rs
Normal file
|
|
@ -0,0 +1,402 @@
|
|||
// Conversión del HTML de un correo en su texto plano alternativo.
|
||||
//
|
||||
// No es un intérprete HTML completo: basta para el HTML de los correos, que normalmente sale de
|
||||
// `html!` y está bien formado. Los bloques (párrafos, encabezados, listas, filas de tabla...) se
|
||||
// separan con saltos de línea, los elementos de lista se marcan con "- ", los enlaces añaden su
|
||||
// dirección entre paréntesis y las imágenes su texto alternativo. Se descartan `head`, `title`,
|
||||
// `style` y `script`, y los comentarios.
|
||||
|
||||
// Elementos que separan párrafos (una línea en blanco) y que separan líneas.
|
||||
const PARAGRAPHS: &[&str] = &[
|
||||
"p",
|
||||
"h1",
|
||||
"h2",
|
||||
"h3",
|
||||
"h4",
|
||||
"h5",
|
||||
"h6",
|
||||
"ul",
|
||||
"ol",
|
||||
"table",
|
||||
"blockquote",
|
||||
"pre",
|
||||
"dl",
|
||||
];
|
||||
const LINES: &[&str] = &[
|
||||
"div", "tr", "li", "dt", "dd", "section", "article", "header", "footer", "body", "html",
|
||||
];
|
||||
// Elementos cuyo contenido no es texto del correo.
|
||||
const SKIPPED: &[&str] = &["head", "title", "style", "script"];
|
||||
|
||||
pub(crate) fn html_to_text(html: &str) -> String {
|
||||
let mut text = Text::default();
|
||||
let mut links: Vec<(usize, Option<String>)> = Vec::new();
|
||||
let mut pre = 0usize;
|
||||
let mut rest = html;
|
||||
|
||||
while let Some(start) = rest.find('<') {
|
||||
text.push(&decode(&rest[..start]), pre > 0);
|
||||
rest = &rest[start..];
|
||||
|
||||
if let Some(comment) = rest.strip_prefix("<!--") {
|
||||
rest = comment.find("-->").map_or("", |end| &comment[end + 3..]);
|
||||
continue;
|
||||
}
|
||||
let Some(tag) = Tag::parse(rest) else {
|
||||
// Un `<` que no abre una etiqueta es texto.
|
||||
text.push("<", pre > 0);
|
||||
rest = &rest[1..];
|
||||
continue;
|
||||
};
|
||||
rest = &rest[tag.len..];
|
||||
|
||||
if !tag.closing && SKIPPED.contains(&tag.name.as_str()) {
|
||||
let close = ["</", &tag.name].concat();
|
||||
rest = match find_ignore_case(rest, &close) {
|
||||
Some(pos) => {
|
||||
let after = &rest[pos..];
|
||||
after.find('>').map_or("", |gt| &after[gt + 1..])
|
||||
}
|
||||
None => "",
|
||||
};
|
||||
continue;
|
||||
}
|
||||
|
||||
match (tag.name.as_str(), tag.closing) {
|
||||
("br", _) => text.line_break(),
|
||||
("hr", _) => {
|
||||
text.block(2);
|
||||
text.emit("----");
|
||||
text.block(2);
|
||||
}
|
||||
("li", false) => {
|
||||
text.block(1);
|
||||
text.emit("- ");
|
||||
}
|
||||
("td" | "th", true) => text.space(),
|
||||
("img", _) => {
|
||||
if let Some(alt) = tag.attr("alt").filter(|alt| !alt.trim().is_empty()) {
|
||||
text.push(&alt, false);
|
||||
}
|
||||
}
|
||||
("a", false) => links.push((text.len(), tag.attr("href"))),
|
||||
("a", true) => {
|
||||
if let Some((start, Some(href))) = links.pop() {
|
||||
let label = text.since(start).trim().to_owned();
|
||||
let target = href.strip_prefix("mailto:").unwrap_or(&href);
|
||||
let is_link = !(href.is_empty()
|
||||
|| href.starts_with('#')
|
||||
|| href.starts_with("cid:")
|
||||
|| href.starts_with("javascript:"));
|
||||
if is_link && label != target && label != href {
|
||||
text.emit_inline(&["(", target, ")"].concat());
|
||||
}
|
||||
}
|
||||
}
|
||||
("pre", closing) => {
|
||||
text.block(2);
|
||||
if closing {
|
||||
pre = pre.saturating_sub(1);
|
||||
} else {
|
||||
pre += 1;
|
||||
}
|
||||
}
|
||||
(name, _) if PARAGRAPHS.contains(&name) => text.block(2),
|
||||
(name, _) if LINES.contains(&name) => text.block(1),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
text.push(&decode(rest), pre > 0);
|
||||
text.finish()
|
||||
}
|
||||
|
||||
// Texto en construcción, con los separadores pendientes hasta que llegue más texto: así no quedan
|
||||
// espacios ni saltos de línea sobrantes al principio, al final o entre bloques.
|
||||
#[derive(Default)]
|
||||
struct Text {
|
||||
buf: String,
|
||||
newlines: usize,
|
||||
space: bool,
|
||||
}
|
||||
|
||||
impl Text {
|
||||
fn len(&self) -> usize {
|
||||
self.buf.len()
|
||||
}
|
||||
|
||||
fn since(&self, start: usize) -> &str {
|
||||
self.buf.get(start..).unwrap_or_default()
|
||||
}
|
||||
|
||||
// Añade texto. Fuera de `pre` cualquier secuencia de espacios en blanco cuenta como un espacio.
|
||||
fn push(&mut self, s: &str, preformatted: bool) {
|
||||
if preformatted {
|
||||
if !s.is_empty() {
|
||||
self.flush();
|
||||
self.buf.push_str(s);
|
||||
}
|
||||
return;
|
||||
}
|
||||
for c in s.chars() {
|
||||
if c.is_whitespace() {
|
||||
self.space();
|
||||
} else {
|
||||
self.flush();
|
||||
self.buf.push(c);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Añade un texto tal cual, tras los separadores pendientes.
|
||||
fn emit(&mut self, s: &str) {
|
||||
self.flush();
|
||||
self.buf.push_str(s);
|
||||
}
|
||||
|
||||
// Añade un texto separado por un espacio de lo anterior en la misma línea.
|
||||
fn emit_inline(&mut self, s: &str) {
|
||||
self.space();
|
||||
self.emit(s);
|
||||
}
|
||||
|
||||
fn space(&mut self) {
|
||||
if self.newlines == 0 {
|
||||
self.space = true;
|
||||
}
|
||||
}
|
||||
|
||||
fn line_break(&mut self) {
|
||||
self.newlines = (self.newlines + 1).min(2);
|
||||
self.space = false;
|
||||
}
|
||||
|
||||
fn block(&mut self, newlines: usize) {
|
||||
self.newlines = self.newlines.max(newlines);
|
||||
self.space = false;
|
||||
}
|
||||
|
||||
fn flush(&mut self) {
|
||||
if !self.buf.is_empty() {
|
||||
if self.newlines > 0 {
|
||||
let trimmed = self.buf.trim_end_matches(' ').len();
|
||||
self.buf.truncate(trimmed);
|
||||
for _ in 0..self.newlines {
|
||||
self.buf.push('\n');
|
||||
}
|
||||
} else if self.space && !self.buf.ends_with([' ', '\n']) {
|
||||
self.buf.push(' ');
|
||||
}
|
||||
}
|
||||
self.newlines = 0;
|
||||
self.space = false;
|
||||
}
|
||||
|
||||
fn finish(self) -> String {
|
||||
let mut out = String::with_capacity(self.buf.len());
|
||||
for line in self.buf.lines() {
|
||||
out.push_str(line.trim_end());
|
||||
out.push('\n');
|
||||
}
|
||||
out.trim().to_owned()
|
||||
}
|
||||
}
|
||||
|
||||
// Etiqueta HTML leída al principio de un texto que empieza por `<`.
|
||||
struct Tag<'a> {
|
||||
name: String,
|
||||
closing: bool,
|
||||
attrs: &'a str,
|
||||
// Longitud de la etiqueta completa, de `<` a `>`.
|
||||
len: usize,
|
||||
}
|
||||
|
||||
impl<'a> Tag<'a> {
|
||||
fn parse(s: &'a str) -> Option<Self> {
|
||||
let body = s.strip_prefix('<')?;
|
||||
let (closing, body) = match body.strip_prefix('/') {
|
||||
Some(body) => (true, body),
|
||||
None => (false, body),
|
||||
};
|
||||
// `<!DOCTYPE ...>` y similares se leen como etiquetas sin nombre conocido.
|
||||
let first = body.chars().next()?;
|
||||
if !(first.is_ascii_alphabetic() || first == '!') {
|
||||
return None;
|
||||
}
|
||||
// Busca el `>` final fuera de los valores entre comillas.
|
||||
let mut quote = None;
|
||||
let mut end = None;
|
||||
for (i, c) in body.char_indices() {
|
||||
match (quote, c) {
|
||||
(Some(q), c) if c == q => quote = None,
|
||||
(None, '"' | '\'') => quote = Some(c),
|
||||
(None, '>') => {
|
||||
end = Some(i);
|
||||
break;
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
let end = end?;
|
||||
let inner = body[..end].trim_end_matches('/');
|
||||
let name_len = inner
|
||||
.find(|c: char| c.is_whitespace())
|
||||
.unwrap_or(inner.len());
|
||||
Some(Tag {
|
||||
name: inner[..name_len].to_ascii_lowercase(),
|
||||
closing,
|
||||
attrs: &inner[name_len..],
|
||||
len: s.len() - body.len() + end + 1,
|
||||
})
|
||||
}
|
||||
|
||||
// Valor del atributo `name`, ya decodificado.
|
||||
fn attr(&self, name: &str) -> Option<String> {
|
||||
let mut rest = self.attrs;
|
||||
loop {
|
||||
rest = rest.trim_start();
|
||||
if rest.is_empty() {
|
||||
return None;
|
||||
}
|
||||
let key_len = rest
|
||||
.find(|c: char| c == '=' || c.is_whitespace())
|
||||
.unwrap_or(rest.len());
|
||||
let key = &rest[..key_len];
|
||||
rest = rest[key_len..].trim_start();
|
||||
let value = match rest.strip_prefix('=') {
|
||||
Some(after) => {
|
||||
let after = after.trim_start();
|
||||
let (value, next) = match after.chars().next() {
|
||||
Some(q @ ('"' | '\'')) => {
|
||||
let inner = &after[1..];
|
||||
let end = inner.find(q).unwrap_or(inner.len());
|
||||
(&inner[..end], inner.get(end + 1..).unwrap_or_default())
|
||||
}
|
||||
_ => {
|
||||
let end = after.find(char::is_whitespace).unwrap_or(after.len());
|
||||
(&after[..end], &after[end..])
|
||||
}
|
||||
};
|
||||
rest = next;
|
||||
value
|
||||
}
|
||||
None => "",
|
||||
};
|
||||
if key.eq_ignore_ascii_case(name) {
|
||||
return Some(decode(value));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Posición de `needle` en `haystack` sin distinguir mayúsculas (ASCII).
|
||||
fn find_ignore_case(haystack: &str, needle: &str) -> Option<usize> {
|
||||
haystack
|
||||
.to_ascii_lowercase()
|
||||
.find(&needle.to_ascii_lowercase())
|
||||
}
|
||||
|
||||
// Decodifica las entidades HTML habituales y las numéricas; deja tal cual las desconocidas.
|
||||
fn decode(s: &str) -> String {
|
||||
if !s.contains('&') {
|
||||
return s.to_owned();
|
||||
}
|
||||
let mut out = String::with_capacity(s.len());
|
||||
let mut rest = s;
|
||||
while let Some(amp) = rest.find('&') {
|
||||
out.push_str(&rest[..amp]);
|
||||
rest = &rest[amp..];
|
||||
let decoded = rest.find(';').filter(|&end| end <= 10).and_then(|end| {
|
||||
let entity = &rest[1..end];
|
||||
let c = match entity {
|
||||
"amp" => Some('&'),
|
||||
"lt" => Some('<'),
|
||||
"gt" => Some('>'),
|
||||
"quot" => Some('"'),
|
||||
"apos" => Some('\''),
|
||||
"nbsp" => Some(' '),
|
||||
_ => entity.strip_prefix('#').and_then(|num| {
|
||||
let code = match num.strip_prefix(['x', 'X']) {
|
||||
Some(hex) => u32::from_str_radix(hex, 16).ok(),
|
||||
None => num.parse().ok(),
|
||||
};
|
||||
code.and_then(char::from_u32)
|
||||
}),
|
||||
};
|
||||
c.map(|c| (c, end))
|
||||
});
|
||||
match decoded {
|
||||
Some((c, end)) => {
|
||||
out.push(c);
|
||||
rest = &rest[end + 1..];
|
||||
}
|
||||
None => {
|
||||
out.push('&');
|
||||
rest = &rest[1..];
|
||||
}
|
||||
}
|
||||
}
|
||||
out.push_str(rest);
|
||||
out
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::html_to_text;
|
||||
|
||||
#[test]
|
||||
fn blocks_lists_and_line_breaks_become_lines() {
|
||||
let html = "<h1>Title</h1><p>Hello <strong>Ana</strong>,<br>welcome.</p>\
|
||||
<ul><li>One</li><li>Two</li></ul><p>Bye</p>";
|
||||
assert_eq!(
|
||||
html_to_text(html),
|
||||
"Title\n\nHello Ana,\nwelcome.\n\n- One\n- Two\n\nBye"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn whitespace_is_collapsed_outside_pre() {
|
||||
let html = "<p> Lots of\n\n space </p><pre> keep\n this</pre>";
|
||||
assert_eq!(html_to_text(html), "Lots of space\n\n keep\n this");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn links_show_their_target_unless_it_is_the_label() {
|
||||
let html = r##"<p><a href="https://x.com/a?b=1&c=2">Open</a></p>
|
||||
<p><a href="https://x.com">https://x.com</a></p>
|
||||
<p><a href="mailto:ana@example.com">ana@example.com</a></p>
|
||||
<p><a href="mailto:ana@example.com">Write to Ana</a></p>
|
||||
<p><a href="#top">Top</a></p>"##;
|
||||
assert_eq!(
|
||||
html_to_text(html),
|
||||
"Open (https://x.com/a?b=1&c=2)\n\nhttps://x.com\n\nana@example.com\n\n\
|
||||
Write to Ana (ana@example.com)\n\nTop"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn entities_are_decoded() {
|
||||
assert_eq!(
|
||||
html_to_text("<p>a & b <c> "d" 'e' ©</p>"),
|
||||
"a & b <c> \"d\" 'e' ©"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn head_styles_scripts_and_comments_are_dropped() {
|
||||
let html = "<!DOCTYPE html><html><head><title>T</title><style>p{}</style></head>\
|
||||
<body><!-- hidden --><script>x()</script><p>Visible</p></body></html>";
|
||||
assert_eq!(html_to_text(html), "Visible");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn tables_and_images_keep_their_text() {
|
||||
let html = r#"<table><tr><td>A</td><td>B</td></tr><tr><td>C</td><td>D</td></tr></table>
|
||||
<p><img src="cid:logo" alt="Logo"> <img src="x.png" alt=""></p>"#;
|
||||
assert_eq!(html_to_text(html), "A B\nC D\n\nLogo");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn stray_less_than_is_text() {
|
||||
assert_eq!(html_to_text("<p>1 < 2</p>"), "1 < 2");
|
||||
}
|
||||
}
|
||||
251
extensions/pagetop-mail/src/transport.rs
Normal file
251
extensions/pagetop-mail/src/transport.rs
Normal file
|
|
@ -0,0 +1,251 @@
|
|||
// Entrega de los correos con el transporte configurado en `[mail]`.
|
||||
|
||||
use pagetop::prelude::*;
|
||||
|
||||
use crate::config::{self, MailTransport, SmtpSecurity, SmtpSettings};
|
||||
use crate::{Email, MailError, Mailbox, outbox};
|
||||
|
||||
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,
|
||||
Tokio1Executor,
|
||||
};
|
||||
|
||||
use std::path::PathBuf;
|
||||
use std::sync::OnceLock;
|
||||
|
||||
// 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,
|
||||
from: Option<Mailbox>,
|
||||
reply_to: Option<Mailbox>,
|
||||
redirect_to: Option<Address>,
|
||||
}
|
||||
|
||||
enum Transport {
|
||||
Smtp(AsyncSmtpTransport<Tokio1Executor>),
|
||||
Sendmail(AsyncSendmailTransport<Tokio1Executor>),
|
||||
File(AsyncFileTransport<Tokio1Executor>),
|
||||
Log,
|
||||
Memory,
|
||||
}
|
||||
|
||||
// Devuelve el transporte, construyéndolo en el primer uso. `Mail::initialize()` lo construye al
|
||||
// arrancar para detener la aplicación si los ajustes no son válidos; fuera de una aplicación (p.
|
||||
// ej. en pruebas) se construye en el primer envío.
|
||||
pub(crate) fn mailer() -> Result<&'static Mailer, MailError> {
|
||||
if let Some(mailer) = MAILER.get() {
|
||||
return Ok(mailer);
|
||||
}
|
||||
let mailer = Mailer::from_settings()?;
|
||||
// Si otro hilo se adelanta, se queda el suyo y se descarta éste.
|
||||
Ok(MAILER.get_or_init(|| mailer))
|
||||
}
|
||||
|
||||
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());
|
||||
let message = email.to_message()?;
|
||||
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(),
|
||||
};
|
||||
let raw = message.formatted();
|
||||
|
||||
match &mailer.transport {
|
||||
Transport::Smtp(smtp) => {
|
||||
smtp.send_raw(&envelope, &raw)
|
||||
.await
|
||||
.map_err(MailError::Smtp)?;
|
||||
}
|
||||
Transport::Sendmail(sendmail) => {
|
||||
sendmail
|
||||
.send_raw(&envelope, &raw)
|
||||
.await
|
||||
.map_err(MailError::Sendmail)?;
|
||||
}
|
||||
Transport::File(file) => {
|
||||
file.send_raw(&envelope, &raw)
|
||||
.await
|
||||
.map_err(MailError::File)?;
|
||||
}
|
||||
Transport::Log => {
|
||||
let body = email
|
||||
.text()
|
||||
.cloned()
|
||||
.or_else(|| email.html().map(|html| html.as_str().to_owned()))
|
||||
.unwrap_or_default();
|
||||
trace::info!(
|
||||
"Email not delivered (mail.transport = \"log\")\n\
|
||||
From: {}\nTo: {}\nSubject: {}\n\n{}",
|
||||
email.from().map(ToString::to_string).unwrap_or_default(),
|
||||
recipients(&envelope).join(", "),
|
||||
email.subject(),
|
||||
body
|
||||
);
|
||||
}
|
||||
Transport::Memory => {
|
||||
outbox::push(email, recipients(&envelope), raw);
|
||||
}
|
||||
}
|
||||
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.
|
||||
pub(crate) fn prepare_preview(email: Email) -> Email {
|
||||
let mailer = mailer().ok();
|
||||
email.prepare(
|
||||
mailer.and_then(|m| m.from.as_ref()),
|
||||
mailer.and_then(|m| m.reply_to.as_ref()),
|
||||
)
|
||||
}
|
||||
|
||||
// Direcciones a las que se entrega el correo.
|
||||
fn recipients(envelope: &Envelope) -> Vec<String> {
|
||||
envelope.to().iter().map(ToString::to_string).collect()
|
||||
}
|
||||
|
||||
impl Mailer {
|
||||
fn from_settings() -> Result<Self, MailError> {
|
||||
let settings = &*config::SETTINGS;
|
||||
let transport = match settings.transport {
|
||||
MailTransport::Smtp => Transport::Smtp(smtp_transport(&settings.smtp)?),
|
||||
MailTransport::Sendmail => Transport::Sendmail(match &settings.sendmail.command {
|
||||
Some(command) => AsyncSendmailTransport::new_with_command(command),
|
||||
None => AsyncSendmailTransport::new(),
|
||||
}),
|
||||
MailTransport::File => {
|
||||
let dir = PathBuf::from(&settings.file.dir);
|
||||
std::fs::create_dir_all(&dir).map_err(|source| MailError::CreateDir {
|
||||
path: dir.clone(),
|
||||
source,
|
||||
})?;
|
||||
Transport::File(AsyncFileTransport::new(dir))
|
||||
}
|
||||
MailTransport::Log => Transport::Log,
|
||||
MailTransport::Memory => Transport::Memory,
|
||||
};
|
||||
let redirect_to = match settings.redirect_to.as_deref().and_then(util::non_blank) {
|
||||
Some(address) => Some(address.parse::<Address>().map_err(|source| {
|
||||
invalid_setting(
|
||||
"mail.redirect_to",
|
||||
MailError::InvalidAddress {
|
||||
address: address.to_owned(),
|
||||
source,
|
||||
},
|
||||
)
|
||||
})?),
|
||||
None => None,
|
||||
};
|
||||
if let Some(url) = settings.base_url.as_deref().and_then(util::non_blank)
|
||||
&& !(url.starts_with("http://") || url.starts_with("https://"))
|
||||
{
|
||||
return Err(invalid_setting(
|
||||
"mail.base_url",
|
||||
MailError::InvalidUrl(url.to_owned()),
|
||||
));
|
||||
}
|
||||
Ok(Mailer {
|
||||
transport,
|
||||
from: setting_mailbox("mail.from", settings.from.as_deref())?,
|
||||
reply_to: setting_mailbox("mail.reply_to", settings.reply_to.as_deref())?,
|
||||
redirect_to,
|
||||
})
|
||||
}
|
||||
|
||||
// Avisa en las trazas de los ajustes que conviene revisar.
|
||||
pub(crate) fn log_startup(&self) {
|
||||
let settings = &*config::SETTINGS;
|
||||
match self.transport {
|
||||
Transport::Log => trace::warn!(
|
||||
"mail.transport is \"log\": emails are written to the log, not delivered"
|
||||
),
|
||||
Transport::Memory => trace::warn!(
|
||||
"mail.transport is \"memory\": emails are kept in memory, not delivered \
|
||||
(tests only)"
|
||||
),
|
||||
Transport::Smtp(_) | Transport::Sendmail(_) | Transport::File(_) => {
|
||||
if self.from.is_none() {
|
||||
trace::warn!("mail.from is not set: every email must set its own sender");
|
||||
}
|
||||
if settings
|
||||
.base_url
|
||||
.as_deref()
|
||||
.and_then(util::non_blank)
|
||||
.is_none()
|
||||
{
|
||||
trace::warn!(
|
||||
"mail.base_url is not set: links in emails point to {}",
|
||||
crate::base_url()
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
if settings.previews {
|
||||
trace::warn!(
|
||||
"mail.previews is enabled: email previews are public at {} (development only)",
|
||||
crate::preview::PREVIEW_PATH
|
||||
);
|
||||
}
|
||||
if let Some(address) = &self.redirect_to {
|
||||
trace::warn!("mail.redirect_to is set: all emails are delivered only to {address}");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn smtp_transport(smtp: &SmtpSettings) -> Result<AsyncSmtpTransport<Tokio1Executor>, MailError> {
|
||||
let tls_parameters = || {
|
||||
TlsParameters::builder(smtp.host.clone())
|
||||
.dangerous_accept_invalid_certs(smtp.accept_invalid_certs)
|
||||
.build()
|
||||
.map_err(|err| invalid_setting("mail.smtp", MailError::Smtp(err)))
|
||||
};
|
||||
let (tls, default_port) = match smtp.security {
|
||||
SmtpSecurity::None => (Tls::None, 25),
|
||||
SmtpSecurity::Opportunistic => (Tls::Opportunistic(tls_parameters()?), 25),
|
||||
SmtpSecurity::StartTls => (Tls::Required(tls_parameters()?), 587),
|
||||
SmtpSecurity::Tls => (Tls::Wrapper(tls_parameters()?), 465),
|
||||
};
|
||||
let mut builder = AsyncSmtpTransport::<Tokio1Executor>::builder_dangerous(&smtp.host)
|
||||
.port(smtp.port.unwrap_or(default_port))
|
||||
.tls(tls)
|
||||
.timeout(Some(std::time::Duration::from_secs(smtp.timeout_secs)))
|
||||
.pool_config(PoolConfig::new().max_size(smtp.pool_max_size));
|
||||
if let Some(username) = smtp.username.as_deref().and_then(util::non_blank) {
|
||||
builder = builder.credentials(Credentials::new(
|
||||
username.to_owned(),
|
||||
smtp.password.clone().unwrap_or_default(),
|
||||
));
|
||||
}
|
||||
if let Some(name) = smtp.hello_name.as_deref().and_then(util::non_blank) {
|
||||
builder = builder.hello_name(ClientId::Domain(name.to_owned()));
|
||||
}
|
||||
Ok(builder.build())
|
||||
}
|
||||
|
||||
// Lee una dirección de los ajustes, comprobando que sea válida.
|
||||
fn setting_mailbox(key: &'static str, value: Option<&str>) -> Result<Option<Mailbox>, MailError> {
|
||||
let Some(value) = value.and_then(util::non_blank) else {
|
||||
return Ok(None);
|
||||
};
|
||||
let mailbox = Mailbox::from(value);
|
||||
mailbox
|
||||
.to_lettre()
|
||||
.map_err(|err| invalid_setting(key, err))?;
|
||||
Ok(Some(mailbox))
|
||||
}
|
||||
|
||||
fn invalid_setting(key: &'static str, source: MailError) -> MailError {
|
||||
MailError::InvalidSetting {
|
||||
key,
|
||||
source: Box::new(source),
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue