inbuxa/ihasmail-inbuxa
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Push by subscription: hold no upstream connection per tab

Browse Source 
A signed-in tab held two sockets: the browser's, and one from ihasmail to
Stalwart carrying that tab's push stream. The upstream one was most of what a
tab cost, and the only reason Stalwart's connection limit applied to ihasmail
at all.

RFC 8620 section 7.2 defines the other push transport: a PushSubscription,
where the server POSTs StateChange objects to a URL the client registers.
Stalwart 0.16.20 implements it. ihasmail now registers one subscription per
account at sign-in, and when Stalwart POSTs a change, fans it out to that
account's open tabs over the browser-facing streams it already holds. A tab
opens on the relay as before and is moved to fan-out the moment its account
verifies -- the upstream request is ended, the browser stream is untouched,
and nothing keeps a reference to what was torn down. After that there is no
upstream connection at all. The shapes are the RFC's; nothing here is taken
from any other client.

Measured at a 256 MiB cap over a private plain-HTTP route, against a real
Stalwart with 6,144 accounts verifying during the ramp and no failures:

                                 tabs   client   Stalwart   system  KiB/tab
  raw relay (before)            5,000     48.2       46.4     94.6
  push by subscription          6,144     33.3        4.8     38.0
  a direct-to-server client   12,389      4.8       53.8     58.6

Descriptors per tab: one, the browser's. Stalwart pays 4.8 KiB per tab and
holds no connection for it, so its per-listener connection limit no longer
applies to ihasmail. What remains per tab on the client is Node's cost for a
held HTTP/1.1 connection.

PUSH_URL is the https origin Stalwart can reach ihasmail at. The RFC requires
https and Stalwart enforces it, so Stalwart must trust that certificate: a
public TLS front already does; a private segment needs an internal CA in
Stalwart's trust store. An account whose subscription cannot be verified
stays on the relay, so nothing breaks -- only the saving needs the
certificate. PUSH_MODE=relay disables the subscription path entirely.

/api/push/:token accepts only a JSON body under 64 KiB for a known 32-byte
token, answers 200 or 404, and echoes nothing. /api/health reports how many
accounts are verified, pending or failed and how many tabs are on each path.
This commit is contained in:
jcoffey-dev
2026-09-06 13:30:34 -07:00
parent f569f2cc7a
commit 2c47c0851c
4 changed files with 384 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
server/src/push.ts
+204
View File
@@ -0,0 +1,204 @@
/**
* Push by subscription: hold no upstream connection per tab.
*
* Today every signed-in tab holds a Server-Sent Events stream to ihasmail,
* and ihasmail holds a matching stream to Stalwart behind it. The upstream
* one is most of what a tab costs -- measured, 81 KiB of TLS state plus the
* request objects -- and it is also the only reason Stalwart's connection
* limit applies to ihasmail at all.
*
* RFC 8620 §7.2 defines the other transport: a PushSubscription, where the
* server POSTs StateChange objects to a URL the client registers. Stalwart
* implements it. So ihasmail registers one subscription per *account*, and
* when Stalwart POSTs a change, fans it out to that account's open tabs over
* the browser-facing streams it already holds. Nothing is held upstream.
*
* Nothing here is taken from any other client's implementation; the shapes
* are the RFC's.
*
* The subscription URL must be https and Stalwart must trust its
* certificate -- the RFC requires the scheme and Stalwart enforces it. Where
* that is not the case the subscription never verifies, and the account
* stays on the per-tab relay it uses today. Both paths coexist; the
* transition loses no events, because a tab opened before verification keeps
* its own relay for its whole life.
*/
import { randomBytes } from "node:crypto";
import type { ServerResponse } from "node:http";
import { config } from "./config.js";
import { absoluteUpstream, getUpstreamSession, upstreamFor } from "./upstream.js";
const USING = ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"];
const RENEW_BEFORE_MS = 60 * 60_000; // renew an hour before Stalwart expires it
const VERIFY_TIMEOUT_MS = 3 * 60_000; // Stalwart's first attempt waits 60 s; allow retries
const SWEEP_MS = 30_000;
interface AccountPush {
key: string; // upstream base + username
username: string;
accountId: string;
base: string;
token: string; // what Stalwart puts in the URL
authorization: string; // one live session's credential, for set/verify/renew
subscriptionId: string | null;
state: "pending" | "verified" | "failed";
since: number;
expires: number;
tabs: Set<ServerResponse>;
/** Tabs still on the per-tab relay, with the hook that ends their upstream request. */
relays: Map<ServerResponse, () => void>;
}
const byKey = new Map<string, AccountPush>();
const byToken = new Map<string, AccountPush>();
let sweeper: NodeJS.Timeout | null = null;
export function pushEnabled(): boolean {
return config.pushMode === "subscribe" && !!config.pushUrl;
}
function keyFor(base: string, username: string) { return `${base} ${username}`; }
async function jmap(entry: AccountPush, calls: unknown[]) {
const upstream = await getUpstreamSession(entry.key, entry.authorization, entry.base);
const res = await fetch(absoluteUpstream(upstream.apiUrl, upstream.baseUrl), {
method: "POST",
headers: { authorization: entry.authorization, "content-type": "application/json", accept: "application/json" },
body: JSON.stringify({ using: USING, methodCalls: calls }),
signal: AbortSignal.timeout(config.upstreamTimeout),
});
if (!res.ok) throw new Error(`upstream ${res.status}`);
return (await res.json()) as { methodResponses: [string, Record<string, unknown>, string][] };
}
async function subscribe(entry: AccountPush) {
const url = `${config.pushUrl!.replace(/\/$/, "")}${config.basePath}/api/push/${entry.token}`;
const r = await jmap(entry, [["PushSubscription/set", {
create: { s: { deviceClientId: `ihasmail-${entry.token.slice(0, 8)}`, url,
types: ["Email", "Mailbox", "Thread", "Identity", "EmailSubmission", "VacationResponse"] } },
}, "0"]]);
const created = (r.methodResponses[0]?.[1] as { created?: Record<string, { id: string; expires?: string }> }).created?.s;
if (!created) throw new Error("subscription not created");
entry.subscriptionId = created.id;
entry.expires = created.expires ? Date.parse(created.expires) : Date.now() + 7 * 86_400_000;
}
async function verify(entry: AccountPush, code: string) {
await jmap(entry, [["PushSubscription/set", { update: { [entry.subscriptionId!]: { verificationCode: code } } }, "0"]]);
entry.state = "verified";
// Every tab of this account that has been holding its own upstream stream
// can now let go of it: the subscription is live, so Stalwart will POST the
// same changes here. The browser-facing stream is untouched. Done in this
// order there is no gap -- at worst a change lands twice, which is harmless.
let moved = 0;
for (const [out, dropUpstream] of entry.relays) {
entry.relays.delete(out);
if (out.destroyed) continue;
dropUpstream(); entry.tabs.add(out); moved++;
}
console.log(`[ihasmail] push: subscription verified for ${entry.username}` + (moved ? `, ${moved} tab(s) moved off the relay` : ""));
}
async function unsubscribe(entry: AccountPush) {
if (entry.subscriptionId) {
try { await jmap(entry, [["PushSubscription/set", { destroy: [entry.subscriptionId] }, "0"]]); } catch { /* best effort */ }
}
byKey.delete(entry.key); byToken.delete(entry.token);
}
/**
* Start (or refresh) the account's subscription. Called at sign-in, so that
* by the time the browser opens its stream the verification is usually
* already in flight, and called again by attach() as a safety net.
*/
export function prepare(username: string, accountId: string, authorization: string): AccountPush | null {
if (!pushEnabled()) return null;
const base = upstreamFor(username);
const key = keyFor(base, username);
let entry = byKey.get(key);
if (!entry) {
entry = { key, username, accountId, base, token: randomBytes(32).toString("base64url"),
authorization, subscriptionId: null, state: "pending", since: Date.now(), expires: 0, tabs: new Set(), relays: new Map() };
byKey.set(key, entry); byToken.set(entry.token, entry);
subscribe(entry).catch((err) => {
entry!.state = "failed";
console.warn(`[ihasmail] push: subscribe failed for ${username}: ${(err as Error).message}; relay in use`);
});
startSweeper();
} else {
entry.authorization = authorization; // keep a live credential for renewals
}
return entry;
}
/**
* Called when a tab opens. Returns the account's push entry if the tab can
* be served by fan-out right now, or null if it must hold its own relay.
*/
export function attach(username: string, accountId: string, authorization: string, out: ServerResponse): AccountPush | null {
const entry = prepare(username, accountId, authorization);
if (!entry || entry.state !== "verified") return null;
entry.tabs.add(out);
out.on("close", () => { entry.tabs.delete(out); });
return entry;
}
/**
* A tab that had to start on the relay registers here with the hook that
* ends its upstream request, so verify() can move it to fan-out later.
*/
export function attachRelay(username: string, out: ServerResponse, dropUpstream: () => void): void {
if (!pushEnabled()) return;
const entry = byKey.get(keyFor(upstreamFor(username), username));
if (!entry) return;
entry.relays.set(out, dropUpstream);
out.on("close", () => { entry.relays.delete(out); });
}
/** Stalwart's POST. Returns an HTTP status. */
export async function receive(token: string, body: unknown): Promise<number> {
const entry = byToken.get(token);
if (!entry) return 404;
const msg = body as { "@type"?: string; verificationCode?: string; changed?: unknown };
if (msg["@type"] === "PushVerification" && typeof msg.verificationCode === "string") {
try { await verify(entry, msg.verificationCode); return 200; }
catch (err) { console.warn(`[ihasmail] push: verify failed: ${(err as Error).message}`); return 500; }
}
if (msg["@type"] === "StateChange") {
const frame = `event: state\ndata: ${JSON.stringify(msg)}\n\n`;
for (const out of entry.tabs) { if (!out.destroyed) out.write(frame); }
return 200;
}
return 400;
}
/** One shared timer for every tab: keep-alives, renewals, and cleanup. */
function startSweeper() {
if (sweeper) return;
sweeper = setInterval(() => {
const now = Date.now();
for (const entry of [...byKey.values()]) {
for (const out of entry.tabs) { if (out.destroyed) entry.tabs.delete(out); else out.write(": ping\n\n"); }
if (entry.state === "pending" && now - entry.since > VERIFY_TIMEOUT_MS) {
entry.state = "failed";
console.warn(`[ihasmail] push: no verification for ${entry.username} within ${VERIFY_TIMEOUT_MS / 1000}s; relay in use`);
}
if (entry.state === "verified" && entry.expires - now < RENEW_BEFORE_MS) {
entry.state = "pending"; entry.since = now;
subscribe(entry).catch(() => { entry.state = "failed"; });
}
if (entry.tabs.size === 0 && (entry.state === "failed" || now - entry.since > 10 * 60_000)) {
void unsubscribe(entry);
}
}
if (byKey.size === 0 && sweeper) { clearInterval(sweeper); sweeper = null; }
}, SWEEP_MS);
sweeper.unref();
}
/** For /api/health: how many accounts are on each path. */
export function pushStatus() {
let verified = 0, pending = 0, failed = 0, tabs = 0, relays = 0;
for (const e of byKey.values()) { tabs += e.tabs.size; relays += e.relays.size; if (e.state === "verified") verified++; else if (e.state === "pending") pending++; else failed++; }
return { mode: pushEnabled() ? "subscribe" : "relay", accounts: { verified, pending, failed }, tabs: { fanout: tabs, relay: relays } };
}