hecks 2.9.0 → 3.0.1

data/rust/host/src/web/newsletter.rs

@@ -0,0 +1,310 @@
+use super::newsletter_send::{site_url, unsubscribe_token, unsubscribe_token_matches, unsubscribe_url};
+use super::{instances_for, last_refusal, respond};
+use crate::auth;
+use crate::dispatch;
+use crate::ir::{ir, newsletter_provider, NewsletterProvider};
+use crate::journal::LineageConfig;
+use crate::lambda_client::LambdaInvoker;
+use crate::resend::{Email, Mailer};
+use serde_json::{json, Value};
+use std::collections::HashMap;
+use std::path::Path;
+use std::sync::OnceLock;
+use tokio::sync::Mutex;
+use tokio_postgres::Client;
+
+mod cooldown;
+#[cfg(test)]
+mod tests;
+
+// Guest-facing subscribe/confirm/unsubscribe routes, plus the admin listing.
+// Served here (not passed to Ruby) so a signed link still resolves without one.
+pub(super) async fn newsletter_route(
+    method: &str,
+    path: &str,
+    query: &HashMap<String, String>,
+    raw_body: &str,
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> Option<Value> {
+    // The chapter that declares `provides "newsletter"` names the verbs
+    // and the subscribing aggregate; a domain that attaches none serves
+    // none of these routes.
+    let provider = ir().and_then(newsletter_provider)?;
+    match (method, path) {
+        ("POST", "/newsletter/subscribers") => Some(newsletter_subscribe_route(&provider, raw_body, client, wasm_path, config, invoker).await),
+        ("GET", "/newsletter/subscribers") => Some(newsletter_subscribers_list_route(&provider, client, wasm_path).await),
+        ("GET", "/newsletter/subscribers/confirm") => Some(newsletter_confirm_route(&provider, query, client, wasm_path, config, invoker).await),
+        ("GET", "/newsletter/subscribers/unsubscribe") => Some(newsletter_unsubscribe_route(&provider, query, client, wasm_path, config, invoker).await),
+        _ => None,
+    }
+}
+
+// Called twice by the two-step signup form: first without a name (Subscribe),
+// then with one (AddName).
+async fn newsletter_subscribe_route(
+    provider: &NewsletterProvider,
+    raw_body: &str,
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> Value {
+    let body: Value = match serde_json::from_str(raw_body) {
+        Ok(v) => v,
+        Err(e) => return respond(400, "application/json", &json!({"error": format!("invalid JSON: {e}")}).to_string()),
+    };
+    let Some(email) = body.get("email").and_then(|v| v.as_str()) else {
+        return respond(400, "application/json", &json!({"error": "email"}).to_string());
+    };
+    let first_name = body.get("first_name").and_then(|v| v.as_str()).filter(|s| !s.is_empty());
+    let last_name = body.get("last_name").and_then(|v| v.as_str()).filter(|s| !s.is_empty());
+
+    let read = match dispatch::read(client, wasm_path).await {
+        Ok(r) => r,
+        Err(e) => return respond(500, "text/plain", &format!("{e:#}")),
+    };
+    let existing = instances_for(&read, &provider.instance_prefix()).iter().any(|(id, _)| id == email);
+
+    if existing {
+        if let (Some(first), Some(last)) = (first_name, last_name) {
+            let facts = json!({"first_name": {"value": first}, "last_name": {"value": last}});
+            if let Err(e) = dispatch::handle_routed(client, wasm_path, &provider.add_name, json!(email), facts, None, config, invoker).await {
+                return respond(500, "text/plain", &format!("{e:#}"));
+            }
+        }
+    } else {
+        let mut facts = json!({"email": {"value": email}});
+        if let Some(first) = first_name {
+            facts["first_name"] = json!({"value": first});
+        }
+        if let Some(last) = last_name {
+            facts["last_name"] = json!({"value": last});
+        }
+        let outcome = match dispatch::handle_facts(client, wasm_path, &provider.subscribe, facts, None, config, invoker).await {
+            Ok(o) => o,
+            Err(e) => return respond(500, "text/plain", &format!("{e:#}")),
+        };
+        if !outcome.accepted {
+            return respond(422, "application/json", &last_refusal(&outcome.result).to_string());
+        }
+        send_confirmation(email).await;
+    }
+
+    // Confirm is not dispatched here: a new subscriber stays `pending`
+    // until they follow the confirm link (the route below). This route only
+    // reports where the subscriber ended up.
+    let read = match dispatch::read(client, wasm_path).await {
+        Ok(r) => r,
+        Err(e) => return respond(500, "text/plain", &format!("{e:#}")),
+    };
+    let subscribers = instances_for(&read, &provider.instance_prefix());
+    let Some((_, subscriber)) = subscribers.iter().find(|(id, _)| id == email) else {
+        return respond(500, "text/plain", "subscriber vanished immediately after being written");
+    };
+    let status = subscriber.get("status").and_then(|v| v.as_str()).unwrap_or("pending");
+    respond(200, "application/json", &json!({"email": email, "status": status}).to_string())
+}
+
+// Reads directly off `instances`, not `dispatch::query`: Subscriber lives
+// under the Newsletter chapter, not `config.domain`, so the qualified
+// question name would not resolve there.
+async fn newsletter_subscribers_list_route(provider: &NewsletterProvider, client: &Mutex<Client>, wasm_path: &Path) -> Value {
+    let read = match dispatch::read(client, wasm_path).await {
+        Ok(r) => r,
+        Err(e) => return respond(500, "text/plain", &format!("{e:#}")),
+    };
+    let mut subscribers: Vec<Value> = instances_for(&read, &provider.instance_prefix())
+        .into_iter()
+        .map(|(email, s)| {
+            json!({
+                "email": email,
+                "status": s.get("status"),
+                "first_name": s.get("first_name").and_then(|v| v.get("value")),
+                "last_name": s.get("last_name").and_then(|v| v.get("value")),
+            })
+        })
+        .collect();
+    subscribers.sort_by(|a, b| a["email"].as_str().unwrap_or("").cmp(b["email"].as_str().unwrap_or("")));
+    respond(200, "application/json", &json!(subscribers).to_string())
+}
+
+const CONFIRM_PURPOSE: &str = "newsletter-confirm";
+const CONFIRM_TTL_SECS: u64 = 14 * 24 * 60 * 60;
+
+// SESSION_SECRET; unset means no confirm link can be signed and none is sent.
+fn confirm_secret() -> Option<String> {
+    std::env::var("SESSION_SECRET").ok().filter(|s| !s.is_empty())
+}
+
+fn confirm_token(secret: &str, email: &str) -> String {
+    auth::purpose_token(secret, CONFIRM_PURPOSE, json!({ "email": email }), CONFIRM_TTL_SECS)
+}
+
+fn confirm_token_matches(secret: &str, token: &str, email: &str) -> bool {
+    auth::verify_purpose_token(secret, CONFIRM_PURPOSE, token)
+        .and_then(|claims| claims.get("email").and_then(|v| v.as_str()).map(|signed| signed == email))
+        .unwrap_or(false)
+}
+
+// Percent-encodes the address so a '+' in the local part survives the URL.
+fn confirm_url(site_url: &str, email: &str, token: &str) -> String {
+    let mut url = reqwest::Url::parse(&format!("{site_url}/newsletter-confirmed.html")).unwrap_or_else(|_| reqwest::Url::parse("http://invalid.invalid/").unwrap());
+    url.query_pairs_mut().append_pair("email", email).append_pair("token", token);
+    url.to_string()
+}
+
+// Per-process only (not shared across instances); see `ConfirmationCooldown`.
+fn confirmation_cooldown() -> &'static cooldown::ConfirmationCooldown {
+    static COOLDOWN: OnceLock<cooldown::ConfirmationCooldown> = OnceLock::new();
+    COOLDOWN.get_or_init(|| cooldown::ConfirmationCooldown::new(cooldown::WINDOW, cooldown::CAPACITY))
+}
+
+fn confirmation_body(confirm_url: &str) -> String {
+    format!(
+        "Please confirm your newsletter subscription by opening this link:\n\n{confirm_url}\n\nIf you didn't ask for this, you can ignore this email and nothing will be sent to you.\n"
+    )
+}
+
+// Best-effort: failures are swallowed (subscriber stays `pending`) so a
+// flaky mail provider never surfaces as a signup error. Cooldown-gated so
+// the form can't be used to flood an address with repeat confirmations.
+pub(super) async fn send_confirmation(email: &str) {
+    let Some(secret) = confirm_secret() else {
+        eprintln!("newsletter: SESSION_SECRET is not set, so no confirmation link can be signed; the subscriber stays pending");
+        return;
+    };
+    let mailer = match Mailer::from_env() {
+        Ok(Some(mailer)) => mailer,
+        Ok(None) => {
+            eprintln!("newsletter: email delivery is not configured (RESEND_API_KEY and RESEND_FROM), so the confirmation was not sent");
+            return;
+        }
+        Err(e) => {
+            eprintln!("newsletter: {e}");
+            return;
+        }
+    };
+    if !confirmation_cooldown().try_acquire(email) {
+        eprintln!("newsletter: a confirmation was already emailed to this address in the last 10 minutes, so none was sent; the subscriber stays pending");
+        return;
+    }
+    let site = site_url();
+    let link = confirm_url(&site, email, &confirm_token(&secret, email));
+    let unsubscribe = unsubscribe_url(&site, email, &unsubscribe_token(&secret, email));
+    let delivery = mailer
+        .deliver(&Email { to: email, subject: "Confirm your newsletter subscription", body: &confirmation_body(&link), unsubscribe_url: Some(&unsubscribe) })
+        .await;
+    if !delivery.ok {
+        eprintln!("newsletter: the confirmation email was not delivered: {}", delivery.reason.unwrap_or_default());
+    }
+}
+
+// Only mails when the address is now `pending`; an already-confirmed or
+// unsubscribed registrant is left alone.
+pub(super) async fn send_confirmation_if_pending(email: &str, client: &Mutex<Client>, wasm_path: &Path) {
+    let Some(provider) = ir().and_then(newsletter_provider) else {
+        return;
+    };
+    let Ok(read) = dispatch::read(client, wasm_path).await else {
+        return;
+    };
+    let pending = instances_for(&read, &provider.instance_prefix())
+        .iter()
+        .any(|(id, subscriber)| id == email && subscriber.get("status").and_then(|v| v.as_str()) == Some("pending"));
+    if pending {
+        send_confirmation(email).await;
+    }
+}
+
+// The token must have been minted for this exact address (`confirm_token`);
+// a missing, wrong or expired one refuses before any subscriber is touched.
+// Idempotent: dispatches Confirm only while still `pending`, so a double
+// click or link-prefetch lands on the same success response, not a 422.
+async fn newsletter_confirm_route(provider: &NewsletterProvider, query: &HashMap<String, String>, client: &Mutex<Client>, wasm_path: &Path, config: &LineageConfig, invoker: &dyn LambdaInvoker) -> Value {
+    let Some(email) = query.get("email") else {
+        return respond(400, "application/json", &json!({"error": "email"}).to_string());
+    };
+    let signed = match (confirm_secret(), query.get("token")) {
+        (Some(secret), Some(token)) => confirm_token_matches(&secret, token, email),
+        _ => false,
+    };
+    if !signed {
+        return respond(403, "application/json", &json!({"error": "this confirmation link is invalid or has expired"}).to_string());
+    }
+
+    let read = match dispatch::read(client, wasm_path).await {
+        Ok(r) => r,
+        Err(e) => return respond(500, "text/plain", &format!("{e:#}")),
+    };
+    let subscribers = instances_for(&read, &provider.instance_prefix());
+    let Some((_, subscriber)) = subscribers.iter().find(|(id, _)| id == email) else {
+        return respond(404, "application/json", &json!({"error": "no such subscriber"}).to_string());
+    };
+
+    if subscriber.get("status").and_then(|v| v.as_str()) == Some("pending") {
+        if let Err(e) = dispatch::handle_routed(client, wasm_path, &provider.confirm, json!(email), json!({}), None, config, invoker).await {
+            return respond(500, "text/plain", &format!("{e:#}"));
+        }
+    }
+
+    let read = match dispatch::read(client, wasm_path).await {
+        Ok(r) => r,
+        Err(e) => return respond(500, "text/plain", &format!("{e:#}")),
+    };
+    let subscribers = instances_for(&read, &provider.instance_prefix());
+    let status = subscribers.iter().find(|(id, _)| id == email).and_then(|(_, s)| s.get("status")).and_then(|v| v.as_str()).unwrap_or("pending");
+    respond(200, "application/json", &json!({"email": email, "status": status}).to_string())
+}
+
+// 400 with no address; 403 for a missing, wrong, other-address or expired
+// token, or no secret to check against. Otherwise Ok(email).
+fn unsubscribe_authorized<'a>(secret: Option<&str>, query: &'a HashMap<String, String>) -> Result<&'a str, Value> {
+    let Some(email) = query.get("email") else {
+        return Err(respond(400, "application/json", &json!({"error": "email"}).to_string()));
+    };
+    let signed = match (secret, query.get("token")) {
+        (Some(secret), Some(token)) => unsubscribe_token_matches(secret, token, email),
+        _ => false,
+    };
+    if signed {
+        Ok(email)
+    } else {
+        Err(respond(403, "application/json", &json!({"error": "this unsubscribe link is invalid or has expired"}).to_string()))
+    }
+}
+
+// Same token/idempotency shape as newsletter_confirm_route: Unsubscribe's
+// own `given` accepts a pending or confirmed subscriber, so a repeat click
+// on an already-unsubscribed row lands on the same success response.
+async fn newsletter_unsubscribe_route(provider: &NewsletterProvider, query: &HashMap<String, String>, client: &Mutex<Client>, wasm_path: &Path, config: &LineageConfig, invoker: &dyn LambdaInvoker) -> Value {
+    let email = match unsubscribe_authorized(confirm_secret().as_deref(), query) {
+        Ok(email) => email,
+        Err(refusal) => return refusal,
+    };
+
+    let read = match dispatch::read(client, wasm_path).await {
+        Ok(r) => r,
+        Err(e) => return respond(500, "text/plain", &format!("{e:#}")),
+    };
+    let subscribers = instances_for(&read, &provider.instance_prefix());
+    let Some((_, subscriber)) = subscribers.iter().find(|(id, _)| id == email) else {
+        return respond(404, "application/json", &json!({"error": "no such subscriber"}).to_string());
+    };
+
+    if subscriber.get("status").and_then(|v| v.as_str()) != Some("unsubscribed") {
+        if let Err(e) = dispatch::handle_routed(client, wasm_path, &provider.unsubscribe, json!(email), json!({}), None, config, invoker).await {
+            return respond(500, "text/plain", &format!("{e:#}"));
+        }
+    }
+
+    let read = match dispatch::read(client, wasm_path).await {
+        Ok(r) => r,
+        Err(e) => return respond(500, "text/plain", &format!("{e:#}")),
+    };
+    let subscribers = instances_for(&read, &provider.instance_prefix());
+    let status = subscribers.iter().find(|(id, _)| id == email).and_then(|(_, s)| s.get("status")).and_then(|v| v.as_str()).unwrap_or("pending");
+    respond(200, "application/json", &json!({"email": email, "status": status}).to_string())
+}

data/rust/host/src/web/newsletter_send.rs

@@ -0,0 +1,357 @@
+use super::{active_session_email, instances_for, last_refusal, percent_decode, respond};
+use crate::auth;
+use crate::dispatch;
+use crate::ir::{newsletter_issues_provider, newsletter_provider, NewsletterIssuesProvider, NewsletterProvider};
+use crate::journal::LineageConfig;
+use crate::lambda_client::LambdaInvoker;
+use crate::resend::{Email, Mailer};
+use serde_json::{json, Value};
+use std::collections::HashMap;
+use std::path::Path;
+use tokio::sync::Mutex;
+use tokio_postgres::Client;
+
+// Sending a newsletter issue: POST .../send and .../send-test, gated to
+// Admin/Owner. `newsletter_issues` marks issues sent; `newsletter` holds subscribers.
+
+const UNSUBSCRIBE_TOKEN: &str = "{{UNSUBSCRIBE_URL}}";
+const DEFAULT_SITE_URL: &str = "http://localhost:4321";
+
+// The purpose keys an unsubscribe token apart from a confirm token, so neither
+// verifies as the other. The lifetime is long (two years) because the link sits
+// in emails that are opened months after they were sent.
+pub(super) const UNSUBSCRIBE_PURPOSE: &str = "newsletter-unsubscribe";
+const UNSUBSCRIBE_TTL_SECS: u64 = 730 * 24 * 60 * 60;
+
+#[derive(Debug, PartialEq)]
+pub(super) enum IssueAction {
+    Send,
+    SendTest,
+}
+
+// Matches `POST /newsletter/issues/{slug}/send(-test)`; the slug comes back
+// percent-decoded.
+pub(super) fn issue_action(method: &str, path: &str) -> Option<(String, IssueAction)> {
+    if method != "POST" {
+        return None;
+    }
+    let (slug, action) = path.strip_prefix("/newsletter/issues/")?.split_once('/')?;
+    if slug.is_empty() {
+        return None;
+    }
+    let action = match action {
+        "send" => IssueAction::Send,
+        "send-test" => IssueAction::SendTest,
+        _ => return None,
+    };
+    Some((percent_decode(slug), action))
+}
+
+// `None` when the path doesn't match, or this domain declares neither
+// `newsletter_issues` nor `newsletter`.
+#[allow(clippy::too_many_arguments)]
+pub(super) async fn issue_route(
+    method: &str,
+    path: &str,
+    domain_ir: &Value,
+    raw_body: &str,
+    cookies: &HashMap<String, String>,
+    secret: &str,
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> Option<Value> {
+    let (slug, action) = issue_action(method, path)?;
+    let issues = newsletter_issues_provider(domain_ir)?;
+    let subscribers = newsletter_provider(domain_ir)?;
+
+    let mailer = match authorize(domain_ir, cookies, secret, client).await {
+        Ok(mailer) => mailer,
+        Err(response) => return Some(response),
+    };
+    Some(match action {
+        IssueAction::Send => send_issue(&slug, &issues, &subscribers, &mailer, secret, client, wasm_path, config, invoker).await,
+        IssueAction::SendTest => send_test(raw_body, &mailer, secret).await,
+    })
+}
+
+fn json_error(status: u16, message: &str) -> Value {
+    respond(status, "application/json", &json!({ "error": message }).to_string())
+}
+
+// Every email carries a signed unsubscribe link, so nothing may go out (or
+// be marked sent) without a secret to sign it with.
+fn require_signing_secret(secret: &str) -> Result<(), Value> {
+    if secret.is_empty() {
+        return Err(json_error(503, "unsubscribe links cannot be signed: set SESSION_SECRET"));
+    }
+    Ok(())
+}
+
+// Refuses (before anything is marked sent) when the caller isn't an
+// Admin/Owner, mail isn't configured, or there's no signing secret.
+async fn authorize(domain_ir: &Value, cookies: &HashMap<String, String>, secret: &str, client: &Mutex<Client>) -> Result<Mailer, Value> {
+    let email = active_session_email(domain_ir, cookies, secret, client).await?;
+    match auth::caller_is_admin(client, domain_ir, &email).await {
+        Ok(true) => {}
+        Ok(false) => return Err(json_error(403, "only an Admin or Owner can send the newsletter")),
+        Err(e) => return Err(json_error(500, &format!("members lookup failed: {e}"))),
+    }
+    require_signing_secret(secret)?;
+    match Mailer::from_env() {
+        Ok(Some(mailer)) => Ok(mailer),
+        Ok(None) => Err(json_error(503, "email delivery is not configured: set RESEND_API_KEY and RESEND_FROM")),
+        Err(e) => Err(json_error(500, &e)),
+    }
+}
+
+pub(super) fn site_url() -> String {
+    std::env::var("SITE_URL").unwrap_or_else(|_| DEFAULT_SITE_URL.to_string())
+}
+
+pub(super) fn unsubscribe_token(secret: &str, email: &str) -> String {
+    auth::purpose_token(secret, UNSUBSCRIBE_PURPOSE, json!({ "email": email }), UNSUBSCRIBE_TTL_SECS)
+}
+
+pub(super) fn unsubscribe_token_matches(secret: &str, token: &str, email: &str) -> bool {
+    auth::verify_purpose_token(secret, UNSUBSCRIBE_PURPOSE, token)
+        .and_then(|claims| claims.get("email").and_then(|v| v.as_str()).map(|signed| signed == email))
+        .unwrap_or(false)
+}
+
+// Percent-encodes the address so a '+' in the local part survives the URL.
+pub(super) fn unsubscribe_url(site_url: &str, email: &str, token: &str) -> String {
+    let mut url = reqwest::Url::parse(&format!("{site_url}/newsletter-unsubscribed.html")).unwrap_or_else(|_| reqwest::Url::parse("http://invalid.invalid/").unwrap());
+    url.query_pairs_mut().append_pair("email", email).append_pair("token", token);
+    url.to_string()
+}
+
+fn personalize(body: &str, unsubscribe_url: &str) -> String {
+    body.replace(UNSUBSCRIBE_TOKEN, unsubscribe_url)
+}
+
+// An aggregate field that is a one-attribute value object: `{"value": ...}`.
+fn value_of<'a>(state: &'a Value, field: &str) -> &'a str {
+    state.get(field).and_then(|v| v.get("value")).and_then(|v| v.as_str()).unwrap_or("")
+}
+
+// Every confirmed subscriber's address, alphabetical so a send is repeatable.
+fn confirmed_emails(subscribers: &[(String, Value)]) -> Vec<String> {
+    let mut emails: Vec<String> = subscribers
+        .iter()
+        .filter(|(_, s)| s.get("status").and_then(|v| v.as_str()) == Some("confirmed"))
+        .map(|(email, _)| email.clone())
+        .collect();
+    emails.sort();
+    emails
+}
+
+fn unix_now() -> i64 {
+    std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_secs() as i64).unwrap_or(0)
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn send_issue(
+    slug: &str,
+    issues: &NewsletterIssuesProvider,
+    subscribers: &NewsletterProvider,
+    mailer: &Mailer,
+    secret: &str,
+    client: &Mutex<Client>,
+    wasm_path: &Path,
+    config: &LineageConfig,
+    invoker: &dyn LambdaInvoker,
+) -> Value {
+    let read = match dispatch::read(client, wasm_path).await {
+        Ok(r) => r,
+        Err(e) => return respond(500, "text/plain", &format!("{e:#}")),
+    };
+    let Some((_, issue)) = instances_for(&read, &issues.issue_prefix()).into_iter().find(|(id, _)| id == slug) else {
+        return json_error(404, "no such issue");
+    };
+    let subject = value_of(&issue, "subject").to_string();
+    let body = value_of(&issue, "body").to_string();
+    let recipients = confirmed_emails(&instances_for(&read, &subscribers.instance_prefix()));
+
+    // Marked sent before mailing: a second click then refuses ("only a draft
+    // issue can be sent") instead of mailing everyone twice.
+    match dispatch::handle_routed(client, wasm_path, &issues.send_issue, json!(slug), json!({ "sent_at": { "value": unix_now() } }), None, config, invoker).await {
+        Err(e) => return respond(500, "text/plain", &format!("{e:#}")),
+        Ok(outcome) if !outcome.accepted => return respond(422, "application/json", &last_refusal(&outcome.result).to_string()),
+        Ok(_) => {}
+    }
+
+    let site = site_url();
+    let mut sent = 0;
+    let mut unrecorded = 0;
+    let mut failures: Vec<Value> = Vec::new();
+    for email in &recipients {
+        let unsubscribe = unsubscribe_url(&site, email, &unsubscribe_token(secret, email));
+        let personalized = personalize(&body, &unsubscribe);
+        let delivery = mailer.deliver(&Email { to: email, subject: &subject, body: &personalized, unsubscribe_url: Some(&unsubscribe) }).await;
+        if !delivery.ok {
+            failures.push(json!({ "email": email, "reason": delivery.reason }));
+            continue;
+        }
+        sent += 1;
+
+        let facts = json!({
+            "delivery_id": { "value": format!("{slug}:{email}") },
+            "issue_slug": { "value": slug },
+            "subscriber_email": { "value": email },
+            "message_id": { "value": delivery.message_id.unwrap_or_default() },
+        });
+        match dispatch::handle_facts(client, wasm_path, &issues.record_delivery, facts, None, config, invoker).await {
+            Ok(outcome) if outcome.accepted => {}
+            other => {
+                // The email went out; only its record is missing. Surface it
+                // in the response and the log rather than fail the whole send.
+                unrecorded += 1;
+                eprintln!("newsletter send {slug}: delivered to {email} but could not record it: {}", other.map(|o| last_refusal(&o.result).to_string()).unwrap_or_else(|e| format!("{e:#}")));
+            }
+        }
+    }
+
+    respond(200, "application/json", &json!({ "slug": slug, "sent": sent, "failed": failures.len(), "failures": failures, "unrecorded": unrecorded }).to_string())
+}
+
+// Never touches the issue's own state: `Issue.Send` is irreversible, so a
+// test send can't reuse it; it just renders the given subject/body.
+async fn send_test(raw_body: &str, mailer: &Mailer, secret: &str) -> Value {
+    let body: Value = match serde_json::from_str(raw_body) {
+        Ok(v) => v,
+        Err(e) => return json_error(400, &format!("invalid JSON: {e}")),
+    };
+    let field = |name: &str| body.get(name).and_then(|v| v.as_str());
+    let (Some(to), Some(subject), Some(text)) = (field("to"), field("subject"), field("body")) else {
+        return json_error(400, "to, subject and body are required");
+    };
+
+    let unsubscribe = unsubscribe_url(&site_url(), to, &unsubscribe_token(secret, to));
+    let subject = format!("[TEST] {subject}");
+    let delivery = mailer.deliver(&Email { to, subject: &subject, body: &personalize(text, &unsubscribe), unsubscribe_url: Some(&unsubscribe) }).await;
+    if delivery.ok {
+        respond(200, "application/json", &json!({ "to": to }).to_string())
+    } else {
+        respond(502, "application/json", &json!({ "error": "delivery failed", "reason": delivery.reason }).to_string())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn send_and_send_test_are_the_only_issue_routes() {
+        assert_eq!(issue_action("POST", "/newsletter/issues/spring/send"), Some(("spring".to_string(), IssueAction::Send)));
+        assert_eq!(issue_action("POST", "/newsletter/issues/spring/send-test"), Some(("spring".to_string(), IssueAction::SendTest)));
+        assert_eq!(issue_action("GET", "/newsletter/issues/spring/send"), None);
+        assert_eq!(issue_action("POST", "/newsletter/issues/spring/edit"), None);
+        assert_eq!(issue_action("POST", "/newsletter/issues//send"), None);
+        assert_eq!(issue_action("POST", "/newsletter/issues/spring"), None);
+        assert_eq!(issue_action("POST", "/newsletter/subscribers"), None);
+    }
+
+    #[test]
+    fn the_slug_is_percent_decoded() {
+        assert_eq!(issue_action("POST", "/newsletter/issues/spring%20news/send").unwrap().0, "spring news");
+    }
+
+    #[test]
+    fn the_unsubscribe_token_is_replaced_wherever_it_appears() {
+        let out = personalize("<a href=\"{{UNSUBSCRIBE_URL}}\">leave</a> {{UNSUBSCRIBE_URL}}", "https://x/u");
+        assert_eq!(out, "<a href=\"https://x/u\">leave</a> https://x/u");
+    }
+
+    #[test]
+    fn the_unsubscribe_url_carries_the_encoded_address_and_the_token() {
+        assert_eq!(
+            unsubscribe_url("https://example.com", "a+b@example.com", "tok.en"),
+            "https://example.com/newsletter-unsubscribed.html?email=a%2Bb%40example.com&token=tok.en"
+        );
+    }
+
+    #[test]
+    fn a_signed_unsubscribe_url_carries_a_token_that_verifies_for_its_address() {
+        let url = reqwest::Url::parse(&unsubscribe_url("https://example.com", "a+b@example.com", &unsubscribe_token("s3cret-value", "a+b@example.com"))).unwrap();
+        let query: HashMap<String, String> = url.query_pairs().map(|(k, v)| (k.to_string(), v.to_string())).collect();
+        assert_eq!(query["email"], "a+b@example.com");
+        assert!(unsubscribe_token_matches("s3cret-value", &query["token"], &query["email"]));
+    }
+
+    #[test]
+    fn an_unsubscribe_token_verifies_only_for_the_address_it_was_minted_for() {
+        let token = unsubscribe_token("s3cret-value", "a@example.com");
+        assert!(unsubscribe_token_matches("s3cret-value", &token, "a@example.com"));
+        assert!(!unsubscribe_token_matches("s3cret-value", &token, "b@example.com"));
+        assert!(!unsubscribe_token_matches("another-secret", &token, "a@example.com"));
+    }
+
+    #[test]
+    fn an_unsubscribe_token_and_a_confirm_token_are_not_interchangeable() {
+        let unsubscribe = unsubscribe_token("s3cret-value", "a@example.com");
+        let confirm = auth::purpose_token("s3cret-value", "newsletter-confirm", json!({ "email": "a@example.com" }), 60);
+        assert!(auth::verify_purpose_token("s3cret-value", "newsletter-confirm", &unsubscribe).is_none());
+        assert!(!unsubscribe_token_matches("s3cret-value", &confirm, "a@example.com"));
+    }
+
+    #[test]
+    fn an_unsubscribe_token_outlives_the_confirm_window_by_two_years() {
+        let claims = auth::verify_purpose_token("s3cret-value", UNSUBSCRIBE_PURPOSE, &unsubscribe_token("s3cret-value", "a@example.com")).unwrap();
+        let remaining = claims["exp"].as_u64().unwrap() - unix_now() as u64;
+        assert!(remaining > 729 * 24 * 60 * 60 && remaining <= 730 * 24 * 60 * 60);
+    }
+
+    #[test]
+    fn an_expired_or_garbled_unsubscribe_token_is_refused() {
+        let expired = auth::purpose_token("s3cret-value", UNSUBSCRIBE_PURPOSE, json!({ "email": "a@example.com" }), 0);
+        std::thread::sleep(std::time::Duration::from_millis(1100));
+        assert!(!unsubscribe_token_matches("s3cret-value", &expired, "a@example.com"));
+        assert!(!unsubscribe_token_matches("s3cret-value", "not-a-token", "a@example.com"));
+        assert!(!unsubscribe_token_matches("s3cret-value", "", "a@example.com"));
+    }
+
+    #[test]
+    fn a_send_without_a_signing_secret_is_a_503() {
+        assert_eq!(require_signing_secret("").unwrap_err()["statusCode"], 503);
+        assert!(require_signing_secret("s3cret-value").is_ok());
+    }
+
+    #[test]
+    fn only_confirmed_subscribers_are_recipients_in_alphabetical_order() {
+        let subscribers = vec![
+            ("zed@example.com".to_string(), json!({ "status": "confirmed" })),
+            ("pending@example.com".to_string(), json!({ "status": "pending" })),
+            ("amy@example.com".to_string(), json!({ "status": "confirmed" })),
+            ("gone@example.com".to_string(), json!({ "status": "unsubscribed" })),
+        ];
+        assert_eq!(confirmed_emails(&subscribers), vec!["amy@example.com".to_string(), "zed@example.com".to_string()]);
+    }
+
+    #[test]
+    fn value_object_fields_read_through_their_value() {
+        let issue = json!({ "subject": { "value": "Spring" }, "body": { "value": "<p>hi</p>" } });
+        assert_eq!(value_of(&issue, "subject"), "Spring");
+        assert_eq!(value_of(&issue, "missing"), "");
+    }
+
+    #[tokio::test]
+    async fn a_test_send_without_its_fields_is_a_400() {
+        let response = send_test(r#"{"to":"a@b.com"}"#, &Mailer::Mock, "s3cret-value").await;
+        assert_eq!(response["statusCode"], 400);
+    }
+
+    #[tokio::test]
+    async fn a_test_send_goes_to_the_one_address_with_a_test_subject() {
+        let response = send_test(r#"{"to":"a@b.com","subject":"Spring","body":"<p>hi</p>"}"#, &Mailer::Mock, "s3cret-value").await;
+        assert_eq!(response["statusCode"], 200);
+        assert_eq!(serde_json::from_str::<Value>(response["body"].as_str().unwrap()).unwrap(), json!({ "to": "a@b.com" }));
+    }
+
+    #[tokio::test]
+    async fn a_test_send_the_provider_refuses_is_a_502() {
+        let response = send_test(r#"{"to":"bounce@example.com","subject":"Spring","body":"x"}"#, &Mailer::Mock, "s3cret-value").await;
+        assert_eq!(response["statusCode"], 502);
+    }
+}