capy-mail 0.10.0

Conventional SMTP mail, typed templates, and mail notifications for Capy.
Documentation
use crate::{Envelope, Mail, MailError, MailResult, Mailbox, Mailer, QueueableMail};
use capy_jobs::{Job, JobContext, JobDispatch, JobError, JobResult, Jobs, Queue};
use serde::{Deserialize, Serialize};
use std::time::Instant;

// Render once when enqueueing. The durable snapshot is not tied to application Rust
// types/templates at execution time. Version 1 is a framework compatibility surface.
#[derive(Serialize, Deserialize)]
struct MailDelivery {
    message_type: String,
    message_id: String,
    from: Mailbox,
    to: Vec<Mailbox>,
    cc: Vec<Mailbox>,
    bcc: Vec<Mailbox>,
    reply_to: Option<Mailbox>,
    subject: String,
    text: Option<String>,
    html: Option<String>,
    headers: Vec<(String, String)>,
}
impl MailDelivery {
    fn prepare(mailer: &Mailer, name: &str, mail: Mail) -> MailResult<Self> {
        if !mail.attachments.is_empty() {
            return Err(MailError::Attachment);
        }
        let prepared = mailer.prepare(name, mail.clone(), None)?;
        Ok(Self {
            message_type: name.into(),
            message_id: prepared.message_id().into(),
            from: mail.from.unwrap_or_else(|| mailer.from.clone()),
            to: mail.to,
            cc: mail.cc,
            bcc: mail.bcc,
            reply_to: mail.reply_to,
            subject: mail.subject,
            text: mail.text,
            html: mail.html,
            headers: mail.headers,
        })
    }
    async fn deliver(self, mailer: Mailer, ctx: JobContext) -> JobResult {
        let mail = Mail {
            from: Some(self.from),
            to: self.to,
            cc: self.cc,
            bcc: self.bcc,
            reply_to: self.reply_to,
            subject: self.subject,
            text: self.text,
            html: self.html,
            headers: self.headers,
            attachments: Vec::new(),
        };
        mailer
            .send_rendered(
                &self.message_type,
                Ok(mail),
                Some(self.message_id),
                Some(&ctx.job_id),
            )
            .await
            .map(|_| ())
            .map_err(job_error)
    }
}
impl Job for MailDelivery {
    const NAME: &'static str = "capy.mail.deliver";
    const MAX_ATTEMPTS: u32 = 5;
    async fn handle(self, ctx: JobContext) -> JobResult {
        let mailer = ctx
            .service::<Mailer>()
            .map_err(|_| JobError::permanent("Mail service is not registered"))?;
        self.deliver((*mailer).clone(), ctx).await
    }
}
fn job_error(error: MailError) -> JobError {
    let summary = format!("Mail delivery failed: {}", error.category());
    if error.retryable() {
        JobError::retry(summary)
    } else {
        JobError::permanent(summary)
    }
}
/// Add the framework's versioned delivery job using a shared transport policy.
/// `App::mail` does this automatically when Jobs is enabled. Standalone workers/tests
/// can call this explicitly. Duplicate registration is rejected by normal Jobs checks.
pub fn register_jobs(jobs: Jobs, mailer: Mailer) -> Jobs {
    jobs.register_with::<MailDelivery, _, _>(move |job, ctx| job.deliver(mailer.clone(), ctx))
}
pub(crate) enum QueueTarget<'a> {
    Pool(&'a Queue),
    Transaction(capy_jobs::TransactionalQueue<'a>),
}

impl Mailer {
    /// Queue explicitly non-secret content on the configured mail queue.
    /// Text/HTML/address snapshots are stored in plaintext; attachments are rejected.
    pub async fn queue<M: QueueableMail>(
        &self,
        ctx: &impl JobDispatch,
        envelope: Envelope<M>,
    ) -> MailResult<String> {
        let queue = ctx
            .jobs()
            .queue(self.settings.queue.clone())
            .map_err(|_| MailError::Configuration)?;
        self.queue_on(&queue, envelope).await
    }
    /// Queue on an explicitly selected logical queue.
    pub async fn queue_on<M: QueueableMail>(
        &self,
        queue: &Queue,
        envelope: Envelope<M>,
    ) -> MailResult<String> {
        self.queue_rendered(
            QueueTarget::Pool(queue),
            M::NAME,
            envelope.content.render()?.to(envelope.recipient),
        )
        .await
    }
    /// Atomically enqueue on the configured mail queue using the native transaction.
    /// The queued event is insertion intent; the transaction may still roll back.
    pub async fn queue_in<M: QueueableMail>(
        &self,
        transaction: &sea_orm::DatabaseTransaction,
        envelope: Envelope<M>,
    ) -> MailResult<String> {
        let queue = capy_jobs::TransactionalQueue::new(transaction)
            .queue(self.settings.queue.clone())
            .map_err(|_| MailError::Configuration)?;
        self.queue_rendered(
            QueueTarget::Transaction(queue),
            M::NAME,
            envelope.content.render()?.to(envelope.recipient),
        )
        .await
    }
    pub(crate) async fn queue_rendered(
        &self,
        target: QueueTarget<'_>,
        name: &str,
        mail: Mail,
    ) -> MailResult<String> {
        crate::validate_name(name)?;
        let start = Instant::now();
        let result = async {
            let job = MailDelivery::prepare(self, name, mail)?;
            match target {
                QueueTarget::Pool(queue) => queue.dispatch(job).await,
                QueueTarget::Transaction(queue) => queue.dispatch(job).await,
            }
            .map_err(|_| MailError::Queue)
        }
        .await;
        self.emit(
            if result.is_ok() {
                "mail.queued"
            } else {
                "mail.failed"
            },
            name,
            start.elapsed(),
            result.as_ref().ok().map(String::as_str),
            result.as_ref().err().copied(),
        );
        result
    }
}
/// Validate the automatic framework registration offline, without constructing a transport.
pub fn validate_jobs(jobs: Jobs) -> capy_core::Result<()> {
    jobs.register::<MailDelivery>().validate()
}