@pramen/server 0.0.57 → 0.0.59

package/dist/durable-object.d.ts

@@ -38,10 +38,11 @@ export declare class PramenDOBase extends DurableObject<DoEnv> {
     /** Live subscriptions per socket — held IN MEMORY, not in the WS attachment. The
      * attachment is capped at ~2 KB by workerd, and 64 subs (each with arbitrary input
      * JSON + a read-set + digest) blow past that well before MAX_SUBSCRIPTIONS. The
-     * tradeoff: this map is lost on DO hibernation/eviction, so a woken socket has no
-     * entry and is treated as having no active subscriptions — acceptable because the
-     * client replays its subscriptions on (re)connect. Keyed by the WebSocket object;
-     * cleaned up in webSocketClose. */
+     * tradeoff: this map is lost on DO hibernation/eviction. That is NOT self-healing —
+     * a hibernated socket stays OPEN, so the client sees no close, never replays, and
+     * every push to it is silently dropped forever. `subscribed` on the attachment is the
+     * one bit that survives to detect it; `subsFor` turns that into a close, and the close
+     * into a replay. Keyed by the WebSocket object; cleaned up in webSocketClose. */
     private readonly subsBySocket;
     constructor(ctx: DurableObjectState, env: DoEnv, app: PramenApp);
     private ensureMigrated;
@@ -96,6 +97,13 @@ export declare class PramenDOBase extends DurableObject<DoEnv> {
      * replays them on reconnect. */
     private getSubs;
     private setSubs;
+    /** This socket's subscriptions, or `null` if they were lost to hibernation.
+     *
+     * The two states the in-memory map cannot tell apart: a socket that has subscribed to
+     * nothing, and a socket whose subscriptions the map lost. Both read as an empty list;
+     * only the first is harmless. The attachment's `subscribed` bit is what survives
+     * hibernation, so it is what separates them. */
+    private subsFor;
     private send;
 }
 /** Produce the concrete, app-bound Durable Object class. A DO is constructed by the

package/dist/durable-object.js

@@ -34,6 +34,9 @@ const MAX_SUBSCRIPTIONS = 64;
 /** WebSocket close code for an auth failure (RFC 6455 leaves 4000-4999 to the app;
  * 4401 mirrors HTTP 401). Sent when a socket's token has expired since upgrade. */
 const WS_CLOSE_UNAUTHORIZED = 4401;
+/** Application close code for "this socket's subscriptions did not survive hibernation".
+ * Sent so the client reconnects and replays them — which it already does on any close. */
+const WS_CLOSE_RESUBSCRIBE = 4410;
 export class PramenDOBase extends DurableObject {
     app;
     acl;
@@ -59,10 +62,11 @@ export class PramenDOBase extends DurableObject {
     /** Live subscriptions per socket — held IN MEMORY, not in the WS attachment. The
      * attachment is capped at ~2 KB by workerd, and 64 subs (each with arbitrary input
      * JSON + a read-set + digest) blow past that well before MAX_SUBSCRIPTIONS. The
-     * tradeoff: this map is lost on DO hibernation/eviction, so a woken socket has no
-     * entry and is treated as having no active subscriptions — acceptable because the
-     * client replays its subscriptions on (re)connect. Keyed by the WebSocket object;
-     * cleaned up in webSocketClose. */
+     * tradeoff: this map is lost on DO hibernation/eviction. That is NOT self-healing —
+     * a hibernated socket stays OPEN, so the client sees no close, never replays, and
+     * every push to it is silently dropped forever. `subscribed` on the attachment is the
+     * one bit that survives to detect it; `subsFor` turns that into a close, and the close
+     * into a replay. Keyed by the WebSocket object; cleaned up in webSocketClose. */
     subsBySocket = new Map();
     constructor(ctx, env, app) {
         super(ctx, env);
@@ -291,6 +295,21 @@ export class PramenDOBase extends DurableObject {
         // frame and close 4401 so the client re-auths. Synthetic identities carry no exp.
         if (this.isExpired(att.identity))
             return this.rejectExpired(ws, msg.id);
+        // A woken socket whose subscriptions the map lost cannot be repaired one frame at a
+        // time: every id an `unsubscribe` or a re-`subscribe` names refers to a subscription
+        // this instance has never seen, and letting one through would repopulate the map —
+        // making the socket look healthy while the rest of its subscriptions stay zombies.
+        // Close it instead and let the client replay the whole set. A one-shot `call`
+        // depends on none of that, so it is answered normally.
+        if (msg.type !== "call" && att.subscribed && !this.subsBySocket.has(ws)) {
+            try {
+                ws.close(WS_CLOSE_RESUBSCRIBE, "resubscribe");
+            }
+            catch {
+                /* already closing */
+            }
+            return;
+        }
         await this.ensureMigrated();
         switch (msg.type) {
             case "subscribe":
@@ -380,7 +399,20 @@ export class PramenDOBase extends DurableObject {
                     this.subsBySocket.delete(ws);
                     continue;
                 }
-                const subs = this.getSubs(ws);
+                const subs = this.subsFor(ws, att);
+                // Lost to hibernation. Closing is the fix, not a fallback: the client replays
+                // every subscription on `open`, and re-running them there returns the state this
+                // broadcast was carrying anyway. Pushing on would push to nobody.
+                if (subs === null) {
+                    try {
+                        ws.close(WS_CLOSE_RESUBSCRIBE, "resubscribe");
+                    }
+                    catch {
+                        /* already closing */
+                    }
+                    this.subsBySocket.delete(ws);
+                    continue;
+                }
                 let dirty = false;
                 for (const sub of subs) {
                     if (!sub.tables.some((t) => written.has(t)))
@@ -604,6 +636,27 @@ export class PramenDOBase extends DurableObject {
     }
     setSubs(ws, subs) {
         this.subsBySocket.set(ws, subs);
+        // Keep the durable marker in step, and only when it actually flips — an attachment
+        // write per subscription update would be churn for nothing.
+        const att = this.getAttachment(ws);
+        const subscribed = subs.length > 0;
+        if ((att.subscribed ?? false) !== subscribed)
+            this.setAttachment(ws, { ...att, subscribed });
+    }
+    /** This socket's subscriptions, or `null` if they were lost to hibernation.
+     *
+     * The two states the in-memory map cannot tell apart: a socket that has subscribed to
+     * nothing, and a socket whose subscriptions the map lost. Both read as an empty list;
+     * only the first is harmless. The attachment's `subscribed` bit is what survives
+     * hibernation, so it is what separates them. */
+    subsFor(ws, att) {
+        const subs = this.subsBySocket.get(ws);
+        // An ABSENT entry is the signal, not an empty one: the upgrade seeds every socket
+        // with `[]`, so "no entry" can only mean this instance never saw this socket — it
+        // was accepted by an instance that has since been evicted.
+        if (subs)
+            return subs;
+        return att.subscribed ? null : [];
     }
     send(ws, msg) {
         ws.send(JSON.stringify(msg));

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export { signToken, verifyToken, isUsableSecret, resolveSecret, MIN_TOKEN_SECRET
 export { HmacStrategy, JwksStrategy, type VerifyStrategy, type VerifyOptions } from "./auth";
 export type { ExpiringToken } from "./runtime/token";
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
-export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+export { Mail, CloudflareEmailAdapter, MailgunAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
 export type { MailMessage, MailAddress, MailAdapter, SendEmailBinding } from "./runtime/mail";
 export { Queue, CloudflareQueueAdapter, MemoryQueueAdapter, createQueue, discoverQueueBindings } from "./runtime/queue";
 export type { QueueAdapter, QueueProducerBinding, QueueSendOptions, QueueSendRequest, QueueBatchOptions, QueueContentType } from "./runtime/queue";

package/dist/index.js

@@ -26,7 +26,7 @@ export { signToken, verifyToken, isUsableSecret, resolveSecret, MIN_TOKEN_SECRET
 // token with the same JWKS cache (and its key-rotation handling) the Worker uses.
 export { HmacStrategy, JwksStrategy } from "./auth";
 // --- mail (ctx.mail) ---
-export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+export { Mail, CloudflareEmailAdapter, MailgunAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
 // --- queue (ctx.queue — Cloudflare Queues) ---
 export { Queue, CloudflareQueueAdapter, MemoryQueueAdapter, createQueue, discoverQueueBindings } from "./runtime/queue";
 export { routeQueue, dispatchQueueBatch } from "./runtime/queue-consumer";

package/dist/runtime/mail.d.ts

@@ -47,6 +47,33 @@ export declare class CloudflareEmailAdapter implements MailAdapter {
         from: MailAddress;
     }): Promise<void>;
 }
+/** Mailgun — an HTTP transport, for when Cloudflare Email Sending cannot be used.
+ *
+ * Worth the key for one reason: Cloudflare will only send from a domain that is a zone
+ * in the same account, and some accounts additionally refuse any recipient that is not a
+ * verified destination in Email Routing ("destination address is not a verified
+ * address"). That is workable for a handful of operators and hopeless for real users.
+ * Mailgun asks the domain be verified once, then delivers to anyone.
+ *
+ * A non-2xx THROWS, deliberately: `ctx.mail.send` is normally called from a task, and a
+ * throw is what makes the outbox retry and then dead-letter visibly. Swallowing the
+ * status would turn a bounced sign-in link into silence. The response body rides along
+ * in the message because Mailgun's 400s are specific and worth reading ("not a valid
+ * address", "domain not found"); the key never does. */
+export declare class MailgunAdapter implements MailAdapter {
+    private readonly apiKey;
+    private readonly domain;
+    /** `https://api.eu.mailgun.net` for an EU-region account; the two are separate
+     * deployments and a key from one 401s against the other. */
+    private readonly apiBase;
+    constructor(apiKey: string, domain: string, 
+    /** `https://api.eu.mailgun.net` for an EU-region account; the two are separate
+     * deployments and a key from one 401s against the other. */
+    apiBase?: string);
+    send(message: MailMessage & {
+        from: MailAddress;
+    }): Promise<void>;
+}
 /** Dev/test transport: stash the message in KV under `mail:<recipient>` so an e2e suite
  * (or a dashboard) can read the "inbox" instead of really sending. */
 export declare class KvMailAdapter implements MailAdapter {
@@ -73,9 +100,14 @@ export declare class UnconfiguredMailAdapter implements MailAdapter {
     send(): Promise<void>;
 }
 /** Build `ctx.mail` from the environment:
- *  - `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
+ *  - `MAILGUN_API_KEY` + `MAILGUN_DOMAIN` + `MAIL_FROM` → Mailgun (real send).
+ *  - else `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
  *  - else `MAIL_CAPTURE=true` → capture (KV inbox if a Kv is given, else in-memory) with
  *    a synthetic dev sender — an EXPLICIT dev opt-in, never the production default.
  *  - else → fail closed: a `send` throws (so a missing-MAIL_FROM prod doesn't silently
- *    stash security emails in KV). */
+ *    stash security emails in KV).
+ *
+ * Mailgun outranks the binding on purpose. The binding tends to be present because the
+ * infrastructure declares it, whereas an API key is only ever there because somebody put
+ * it there — so when both exist, the key is the newer decision. */
 export declare function createMail(env: EnvBag, kv?: Kv): Mail;

package/dist/runtime/mail.js

@@ -5,10 +5,15 @@
 //
 //   await ctx.mail.send({ to: "u@x.com", subject: "Welcome", text: "…" });
 //
-// On Cloudflare the transport is Cloudflare Email Sending (the `send_email`/`EMAIL`
-// binding, no API keys). With no verified sender configured (local/dev), mail is
-// captured instead of sent — to KV (so an e2e/dashboard can read the "inbox") or
-// in-memory — so handlers work unchanged off-platform.
+// Two real transports. Cloudflare Email Sending (the `send_email`/`EMAIL` binding) needs
+// no API keys, but it can only send FROM a domain that is a zone in the same account,
+// and on some accounts only TO addresses verified in Email Routing — which rules it out
+// whenever the recipients are ordinary people. Mailgun is the way out of both: an HTTP
+// API, any recipient, at the cost of a key. Configure it and it wins.
+//
+// With neither configured (local/dev), mail is captured instead of sent — to KV (so an
+// e2e/dashboard can read the "inbox") or in-memory — so handlers work unchanged
+// off-platform.
 /** The `ctx.mail` facade: resolves the sender, validates, and delegates to the adapter. */
 export class Mail {
     adapter;
@@ -49,6 +54,60 @@ export class CloudflareEmailAdapter {
         });
     }
 }
+/** Mailgun — an HTTP transport, for when Cloudflare Email Sending cannot be used.
+ *
+ * Worth the key for one reason: Cloudflare will only send from a domain that is a zone
+ * in the same account, and some accounts additionally refuse any recipient that is not a
+ * verified destination in Email Routing ("destination address is not a verified
+ * address"). That is workable for a handful of operators and hopeless for real users.
+ * Mailgun asks the domain be verified once, then delivers to anyone.
+ *
+ * A non-2xx THROWS, deliberately: `ctx.mail.send` is normally called from a task, and a
+ * throw is what makes the outbox retry and then dead-letter visibly. Swallowing the
+ * status would turn a bounced sign-in link into silence. The response body rides along
+ * in the message because Mailgun's 400s are specific and worth reading ("not a valid
+ * address", "domain not found"); the key never does. */
+export class MailgunAdapter {
+    apiKey;
+    domain;
+    apiBase;
+    constructor(apiKey, domain, 
+    /** `https://api.eu.mailgun.net` for an EU-region account; the two are separate
+     * deployments and a key from one 401s against the other. */
+    apiBase = "https://api.mailgun.net") {
+        this.apiKey = apiKey;
+        this.domain = domain;
+        this.apiBase = apiBase;
+    }
+    async send(message) {
+        const body = new URLSearchParams();
+        body.set("from", message.from.name ? `${message.from.name} <${message.from.email}>` : message.from.email);
+        for (const to of Array.isArray(message.to) ? message.to : [message.to])
+            body.append("to", to);
+        body.set("subject", message.subject);
+        if (message.text)
+            body.set("text", message.text);
+        if (message.html)
+            body.set("html", message.html);
+        if (message.replyTo) {
+            const r = message.replyTo;
+            body.set("h:Reply-To", typeof r === "string" ? r : r.name ? `${r.name} <${r.email}>` : r.email);
+        }
+        const res = await fetch(`${this.apiBase.replace(/\/+$/, "")}/v3/${encodeURIComponent(this.domain)}/messages`, {
+            method: "POST",
+            headers: {
+                // `api` is the literal username Mailgun expects; the key is the password.
+                authorization: `Basic ${btoa(`api:${this.apiKey}`)}`,
+                "content-type": "application/x-www-form-urlencoded",
+            },
+            body,
+        });
+        if (!res.ok) {
+            const detail = await res.text().catch(() => "");
+            throw new Error(`mailgun: send failed (${res.status})${detail ? ` — ${detail.slice(0, 300)}` : ""}`);
+        }
+    }
+}
 /** Dev/test transport: stash the message in KV under `mail:<recipient>` so an e2e suite
  * (or a dashboard) can read the "inbox" instead of really sending. */
 export class KvMailAdapter {
@@ -76,21 +135,35 @@ export class MemoryMailAdapter {
  * instead of delivering them. Mirrors how files fail closed without FILES_SECRET. */
 export class UnconfiguredMailAdapter {
     async send() {
-        throw new Error("ctx.mail: no transport configured — set MAIL_FROM (with the EMAIL binding) to send, " +
-            "or MAIL_CAPTURE=true to capture in dev.");
+        throw new Error("ctx.mail: no transport configured — set MAIL_FROM with either the EMAIL binding " +
+            "or MAILGUN_API_KEY + MAILGUN_DOMAIN to send, or MAIL_CAPTURE=true to capture in dev.");
     }
 }
 /** Build `ctx.mail` from the environment:
- *  - `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
+ *  - `MAILGUN_API_KEY` + `MAILGUN_DOMAIN` + `MAIL_FROM` → Mailgun (real send).
+ *  - else `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
  *  - else `MAIL_CAPTURE=true` → capture (KV inbox if a Kv is given, else in-memory) with
  *    a synthetic dev sender — an EXPLICIT dev opt-in, never the production default.
  *  - else → fail closed: a `send` throws (so a missing-MAIL_FROM prod doesn't silently
- *    stash security emails in KV). */
+ *    stash security emails in KV).
+ *
+ * Mailgun outranks the binding on purpose. The binding tends to be present because the
+ * infrastructure declares it, whereas an API key is only ever there because somebody put
+ * it there — so when both exist, the key is the newer decision. */
 export function createMail(env, kv) {
     const binding = env.EMAIL;
     const fromAddr = typeof env.MAIL_FROM === "string" && env.MAIL_FROM ? env.MAIL_FROM : undefined;
+    const str = (k) => typeof env[k] === "string" && env[k] ? env[k] : undefined;
+    const name = typeof env.MAIL_FROM_NAME === "string" ? env.MAIL_FROM_NAME : undefined;
+    const mailgunKey = str("MAILGUN_API_KEY");
+    const mailgunDomain = str("MAILGUN_DOMAIN");
+    if (mailgunKey && mailgunDomain && fromAddr) {
+        return new Mail(new MailgunAdapter(mailgunKey, mailgunDomain, str("MAILGUN_API_BASE")), {
+            email: fromAddr,
+            name,
+        });
+    }
     if (binding && fromAddr) {
-        const name = typeof env.MAIL_FROM_NAME === "string" ? env.MAIL_FROM_NAME : undefined;
         return new Mail(new CloudflareEmailAdapter(binding), { email: fromAddr, name });
     }
     if (env.MAIL_CAPTURE === "true") {

package/dist/runtime/protocol.d.ts

@@ -29,7 +29,10 @@ export type ServerMsg = {
     id: string;
     error: string;
 };
-/** A live subscription, persisted on the socket so it survives DO hibernation. */
+/** A live subscription. Held in the DO's memory, NOT on the socket — the attachment is
+ * capped at ~2 KB and a full set of these blows past it. Only a one-bit `subscribed`
+ * marker rides the attachment, which is enough for the DO to notice the loss and close
+ * the socket so the client replays. */
 export interface Subscription {
     id: string;
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.57",
+  "version": "0.0.59",
   "description": "pramen server runtime \u2014 schema, ACL, ORM, live queries, files, and the createPramen(app) factory for Cloudflare Workers + Durable Objects.",
   "license": "MIT",
   "repository": {

package/src/durable-object.ts

@@ -48,6 +48,11 @@ interface SocketAttachment {
   /** Partition fixed at connect time (read from x-pramen-partition at upgrade);
    * survives hibernation via the attachment, like `tenant`. */
   partition: string;
+  /** Whether this socket had any live subscription. One bit, not the list — the list is
+   * far too big for the attachment, but this is enough to tell "subscribed to nothing"
+   * apart from "subscriptions lost to hibernation", which otherwise look identical and
+   * silently kill every push on the socket. See `subsFor`. */
+  subscribed?: boolean;
 }
 
 export interface DoEnv {
@@ -71,6 +76,10 @@ const MAX_SUBSCRIPTIONS = 64;
  * 4401 mirrors HTTP 401). Sent when a socket's token has expired since upgrade. */
 const WS_CLOSE_UNAUTHORIZED = 4401;
 
+/** Application close code for "this socket's subscriptions did not survive hibernation".
+ * Sent so the client reconnects and replays them — which it already does on any close. */
+const WS_CLOSE_RESUBSCRIBE = 4410;
+
 export class PramenDOBase extends DurableObject<DoEnv> {
   private readonly app: PramenApp;
   private readonly acl: CompiledAcl;
@@ -96,10 +105,11 @@ export class PramenDOBase extends DurableObject<DoEnv> {
   /** Live subscriptions per socket — held IN MEMORY, not in the WS attachment. The
    * attachment is capped at ~2 KB by workerd, and 64 subs (each with arbitrary input
    * JSON + a read-set + digest) blow past that well before MAX_SUBSCRIPTIONS. The
-   * tradeoff: this map is lost on DO hibernation/eviction, so a woken socket has no
-   * entry and is treated as having no active subscriptions — acceptable because the
-   * client replays its subscriptions on (re)connect. Keyed by the WebSocket object;
-   * cleaned up in webSocketClose. */
+   * tradeoff: this map is lost on DO hibernation/eviction. That is NOT self-healing —
+   * a hibernated socket stays OPEN, so the client sees no close, never replays, and
+   * every push to it is silently dropped forever. `subscribed` on the attachment is the
+   * one bit that survives to detect it; `subsFor` turns that into a close, and the close
+   * into a replay. Keyed by the WebSocket object; cleaned up in webSocketClose. */
   private readonly subsBySocket = new Map<WebSocket, Subscription[]>();
 
   constructor(ctx: DurableObjectState, env: DoEnv, app: PramenApp) {
@@ -355,6 +365,21 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     // frame and close 4401 so the client re-auths. Synthetic identities carry no exp.
     if (this.isExpired(att.identity)) return this.rejectExpired(ws, msg.id);
 
+    // A woken socket whose subscriptions the map lost cannot be repaired one frame at a
+    // time: every id an `unsubscribe` or a re-`subscribe` names refers to a subscription
+    // this instance has never seen, and letting one through would repopulate the map —
+    // making the socket look healthy while the rest of its subscriptions stay zombies.
+    // Close it instead and let the client replay the whole set. A one-shot `call`
+    // depends on none of that, so it is answered normally.
+    if (msg.type !== "call" && att.subscribed && !this.subsBySocket.has(ws)) {
+      try {
+        ws.close(WS_CLOSE_RESUBSCRIBE, "resubscribe");
+      } catch {
+        /* already closing */
+      }
+      return;
+    }
+
     await this.ensureMigrated();
 
     switch (msg.type) {
@@ -445,7 +470,19 @@ export class PramenDOBase extends DurableObject<DoEnv> {
           this.subsBySocket.delete(ws);
           continue;
         }
-        const subs = this.getSubs(ws);
+        const subs = this.subsFor(ws, att);
+        // Lost to hibernation. Closing is the fix, not a fallback: the client replays
+        // every subscription on `open`, and re-running them there returns the state this
+        // broadcast was carrying anyway. Pushing on would push to nobody.
+        if (subs === null) {
+          try {
+            ws.close(WS_CLOSE_RESUBSCRIBE, "resubscribe");
+          } catch {
+            /* already closing */
+          }
+          this.subsBySocket.delete(ws);
+          continue;
+        }
         let dirty = false;
         for (const sub of subs) {
           if (!sub.tables.some((t) => written.has(t))) continue;
@@ -680,6 +717,26 @@ export class PramenDOBase extends DurableObject<DoEnv> {
 
   private setSubs(ws: WebSocket, subs: Subscription[]): void {
     this.subsBySocket.set(ws, subs);
+    // Keep the durable marker in step, and only when it actually flips — an attachment
+    // write per subscription update would be churn for nothing.
+    const att = this.getAttachment(ws);
+    const subscribed = subs.length > 0;
+    if ((att.subscribed ?? false) !== subscribed) this.setAttachment(ws, { ...att, subscribed });
+  }
+
+  /** This socket's subscriptions, or `null` if they were lost to hibernation.
+   *
+   * The two states the in-memory map cannot tell apart: a socket that has subscribed to
+   * nothing, and a socket whose subscriptions the map lost. Both read as an empty list;
+   * only the first is harmless. The attachment's `subscribed` bit is what survives
+   * hibernation, so it is what separates them. */
+  private subsFor(ws: WebSocket, att: SocketAttachment): Subscription[] | null {
+    const subs = this.subsBySocket.get(ws);
+    // An ABSENT entry is the signal, not an empty one: the upgrade seeds every socket
+    // with `[]`, so "no entry" can only mean this instance never saw this socket — it
+    // was accepted by an instance that has since been evicted.
+    if (subs) return subs;
+    return att.subscribed ? null : [];
   }
 
   private send(ws: WebSocket, msg: ServerMsg): void {

package/src/index.ts

@@ -95,7 +95,7 @@ export type { ExpiringToken } from "./runtime/token";
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
 
 // --- mail (ctx.mail) ---
-export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+export { Mail, CloudflareEmailAdapter, MailgunAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
 export type { MailMessage, MailAddress, MailAdapter, SendEmailBinding } from "./runtime/mail";
 
 // --- queue (ctx.queue — Cloudflare Queues) ---

package/src/runtime/mail.ts

@@ -5,10 +5,15 @@
 //
 //   await ctx.mail.send({ to: "u@x.com", subject: "Welcome", text: "…" });
 //
-// On Cloudflare the transport is Cloudflare Email Sending (the `send_email`/`EMAIL`
-// binding, no API keys). With no verified sender configured (local/dev), mail is
-// captured instead of sent — to KV (so an e2e/dashboard can read the "inbox") or
-// in-memory — so handlers work unchanged off-platform.
+// Two real transports. Cloudflare Email Sending (the `send_email`/`EMAIL` binding) needs
+// no API keys, but it can only send FROM a domain that is a zone in the same account,
+// and on some accounts only TO addresses verified in Email Routing — which rules it out
+// whenever the recipients are ordinary people. Mailgun is the way out of both: an HTTP
+// API, any recipient, at the cost of a key. Configure it and it wins.
+//
+// With neither configured (local/dev), mail is captured instead of sent — to KV (so an
+// e2e/dashboard can read the "inbox") or in-memory — so handlers work unchanged
+// off-platform.
 
 import type { Kv } from "./kv";
 import type { EnvBag } from "../sdk/handlers";
@@ -83,6 +88,56 @@ export class CloudflareEmailAdapter implements MailAdapter {
   }
 }
 
+/** Mailgun — an HTTP transport, for when Cloudflare Email Sending cannot be used.
+ *
+ * Worth the key for one reason: Cloudflare will only send from a domain that is a zone
+ * in the same account, and some accounts additionally refuse any recipient that is not a
+ * verified destination in Email Routing ("destination address is not a verified
+ * address"). That is workable for a handful of operators and hopeless for real users.
+ * Mailgun asks the domain be verified once, then delivers to anyone.
+ *
+ * A non-2xx THROWS, deliberately: `ctx.mail.send` is normally called from a task, and a
+ * throw is what makes the outbox retry and then dead-letter visibly. Swallowing the
+ * status would turn a bounced sign-in link into silence. The response body rides along
+ * in the message because Mailgun's 400s are specific and worth reading ("not a valid
+ * address", "domain not found"); the key never does. */
+export class MailgunAdapter implements MailAdapter {
+  constructor(
+    private readonly apiKey: string,
+    private readonly domain: string,
+    /** `https://api.eu.mailgun.net` for an EU-region account; the two are separate
+     * deployments and a key from one 401s against the other. */
+    private readonly apiBase: string = "https://api.mailgun.net",
+  ) {}
+
+  async send(message: MailMessage & { from: MailAddress }): Promise<void> {
+    const body = new URLSearchParams();
+    body.set("from", message.from.name ? `${message.from.name} <${message.from.email}>` : message.from.email);
+    for (const to of Array.isArray(message.to) ? message.to : [message.to]) body.append("to", to);
+    body.set("subject", message.subject);
+    if (message.text) body.set("text", message.text);
+    if (message.html) body.set("html", message.html);
+    if (message.replyTo) {
+      const r = message.replyTo;
+      body.set("h:Reply-To", typeof r === "string" ? r : r.name ? `${r.name} <${r.email}>` : r.email);
+    }
+
+    const res = await fetch(`${this.apiBase.replace(/\/+$/, "")}/v3/${encodeURIComponent(this.domain)}/messages`, {
+      method: "POST",
+      headers: {
+        // `api` is the literal username Mailgun expects; the key is the password.
+        authorization: `Basic ${btoa(`api:${this.apiKey}`)}`,
+        "content-type": "application/x-www-form-urlencoded",
+      },
+      body,
+    });
+    if (!res.ok) {
+      const detail = await res.text().catch(() => "");
+      throw new Error(`mailgun: send failed (${res.status})${detail ? ` — ${detail.slice(0, 300)}` : ""}`);
+    }
+  }
+}
+
 /** Dev/test transport: stash the message in KV under `mail:<recipient>` so an e2e suite
  * (or a dashboard) can read the "inbox" instead of really sending. */
 export class KvMailAdapter implements MailAdapter {
@@ -109,23 +164,39 @@ export class MemoryMailAdapter implements MailAdapter {
 export class UnconfiguredMailAdapter implements MailAdapter {
   async send(): Promise<void> {
     throw new Error(
-      "ctx.mail: no transport configured — set MAIL_FROM (with the EMAIL binding) to send, " +
-        "or MAIL_CAPTURE=true to capture in dev.",
+      "ctx.mail: no transport configured — set MAIL_FROM with either the EMAIL binding " +
+        "or MAILGUN_API_KEY + MAILGUN_DOMAIN to send, or MAIL_CAPTURE=true to capture in dev.",
     );
   }
 }
 
 /** Build `ctx.mail` from the environment:
- *  - `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
+ *  - `MAILGUN_API_KEY` + `MAILGUN_DOMAIN` + `MAIL_FROM` → Mailgun (real send).
+ *  - else `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
  *  - else `MAIL_CAPTURE=true` → capture (KV inbox if a Kv is given, else in-memory) with
  *    a synthetic dev sender — an EXPLICIT dev opt-in, never the production default.
  *  - else → fail closed: a `send` throws (so a missing-MAIL_FROM prod doesn't silently
- *    stash security emails in KV). */
+ *    stash security emails in KV).
+ *
+ * Mailgun outranks the binding on purpose. The binding tends to be present because the
+ * infrastructure declares it, whereas an API key is only ever there because somebody put
+ * it there — so when both exist, the key is the newer decision. */
 export function createMail(env: EnvBag, kv?: Kv): Mail {
   const binding = env.EMAIL as SendEmailBinding | undefined;
   const fromAddr = typeof env.MAIL_FROM === "string" && env.MAIL_FROM ? env.MAIL_FROM : undefined;
+  const str = (k: string): string | undefined =>
+    typeof env[k] === "string" && (env[k] as string) ? (env[k] as string) : undefined;
+  const name = typeof env.MAIL_FROM_NAME === "string" ? env.MAIL_FROM_NAME : undefined;
+
+  const mailgunKey = str("MAILGUN_API_KEY");
+  const mailgunDomain = str("MAILGUN_DOMAIN");
+  if (mailgunKey && mailgunDomain && fromAddr) {
+    return new Mail(new MailgunAdapter(mailgunKey, mailgunDomain, str("MAILGUN_API_BASE")), {
+      email: fromAddr,
+      name,
+    });
+  }
   if (binding && fromAddr) {
-    const name = typeof env.MAIL_FROM_NAME === "string" ? env.MAIL_FROM_NAME : undefined;
     return new Mail(new CloudflareEmailAdapter(binding), { email: fromAddr, name });
   }
   if (env.MAIL_CAPTURE === "true") {

package/src/runtime/protocol.ts

@@ -36,7 +36,10 @@ export type ServerMsg =
   | { type: "result"; id: string; result: unknown }
   | { type: "error"; id: string; error: string };
 
-/** A live subscription, persisted on the socket so it survives DO hibernation. */
+/** A live subscription. Held in the DO's memory, NOT on the socket — the attachment is
+ * capped at ~2 KB and a full set of these blows past it. Only a one-bit `subscribed`
+ * marker rides the attachment, which is enough for the DO to notice the loss and close
+ * the socket so the client replays. */
 export interface Subscription {
   id: string;
   name: string;