realtimeclipboard 0.3.0

package/src/transport/relay.js

@@ -0,0 +1,423 @@
+/**
+ * The relay connection: protocol, liveness, and which transport carries it.
+ *
+ * Everything above this file (main.js, and through it the whole app) sees one
+ * interface — connect / send / close / isOpen / setFrameHandler — and never
+ * learns how the bytes actually leave the machine. That boundary was designed
+ * in from the start (PRD §4.3, docs/ARCHITECTURE.md §3) against the risk that
+ * the deployed relay would not pass WebSocket upgrades. It turned out to be
+ * needed for a different reason: the *client's* network.
+ *
+ * On a managed corporate network — the primary deployment context (PRD §5.4) —
+ * a TLS-inspecting proxy may refuse the HTTP Upgrade that a WebSocket needs, or
+ * accept the connection and then swallow it, leaving a socket that never opens
+ * and never closes. So the transport is not a build-time decision:
+ *
+ *   1. Try WebSocket. Give it NET.PROBE_MS to become usable.
+ *   2. Two consecutive attempts that never become usable is a policy, not a
+ *      flaky moment — switch to SSE+POST, which is plain HTTP and needs no
+ *      Upgrade, and say so out loud.
+ *   3. If that is blocked too, keep alternating rather than giving up on one:
+ *      a network that refuses both is a different problem, and the user is told
+ *      exactly that instead of watching "Reconnecting" forever.
+ *
+ * The choice is remembered (storage.js), so someone behind that proxy pays the
+ * probe once rather than on every load, and re-probes when the memory expires
+ * or they move to another network.
+ *
+ * The two channels live in ws.js and sse.js and implement one contract. All the
+ * protocol handling, heartbeat and backoff is here, once, for both.
+ */
+
+import { RELAY_URL, NET, TRANSPORT } from "../core/config.js";
+import { emit, EV } from "../core/bus.js";
+import * as state from "../core/state.js";
+import * as storage from "../core/storage.js";
+import * as proto from "./protocol.js";
+import * as wsChannel from "./ws.js";
+import * as sseChannel from "./sse.js";
+
+const CHANNELS = {
+  [TRANSPORT.WS]:  wsChannel,
+  [TRANSPORT.SSE]: sseChannel,
+};
+const OTHER = {
+  [TRANSPORT.WS]:  TRANSPORT.SSE,
+  [TRANSPORT.SSE]: TRANSPORT.WS,
+};
+
+/** What the status bar appends. The default transport needs no announcement. */
+const NOTE = {
+  [TRANSPORT.WS]:  "",
+  [TRANSPORT.SSE]: "HTTP fallback",
+};
+
+/** Non-transport frames are handed up; the caller decrypts. */
+let onFrame = () => {};
+export const setFrameHandler = fn => { onFrame = fn; };
+
+let channel = null;
+let session = null;              // {roomHash, intent, url, name}
+let wantOpen = false;
+let opened = false;              // has the CURRENT attempt become usable?
+let mode = TRANSPORT.WS;
+let announced = null;            // last transport reported on the bus
+let stuck = false;               // both transports have failed; cleared by any success
+let unsupported = false;         // the relay is reachable but predates the fallback
+let forced = null;               // a transport the user pinned by hand; null = auto
+let failures = { [TRANSPORT.WS]: 0, [TRANSPORT.SSE]: 0 };
+let backoff = NET.BACKOFF_MIN_MS;
+let heartbeat = null;
+let probe = null;
+let pingSentAt = 0;
+
+/**
+ * Which attempt is the current one.
+ *
+ * Rejoining, rotating the key and recovering from a collision all close the
+ * connection and open a new one — while a reconnect timer from the old one may
+ * still be pending. Without a generation to compare against, that timer wakes
+ * up, sees `wantOpen`, and opens a second connection alongside the live one:
+ * the user is in the room twice, sees their own clips echoed back, and one of
+ * the two sockets is unreachable by anything. Every callback and timer below
+ * captures this and does nothing if it has moved on.
+ */
+let epoch = 0;
+
+/** Which transport is live right now. For the UI and for debugging. */
+export const transport = () => mode;
+
+/**
+ * `auth` is a locked session's admission token (core/crypto.js `deriveLocked`).
+ * It is HKDF output, not the PIN and not the key — the relay can check that two
+ * peers agree without being able to reverse it into either. Absent for open
+ * sessions, and a relay that predates it ignores the parameter.
+ */
+export function connect({ roomHash, intent = "join", url = RELAY_URL, name = "", auth = null }) {
+  channel?.close(1000);            // a second connect() replaces, never stacks
+  session = { roomHash, intent, url, name, auth };
+  wantOpen = true;
+  forced = storage.loadTransportChoice();
+  failures = { [TRANSPORT.WS]: 0, [TRANSPORT.SSE]: 0 };
+  backoff = NET.BACKOFF_MIN_MS;
+  mode = preferred();
+  start();
+}
+
+export function send(obj) {
+  return channel?.send(obj) ?? false;
+}
+
+export function close() {
+  wantOpen = false;
+  epoch++;                         // anything still pending belongs to a dead session
+  stopTimers();
+  channel?.close(1000);
+  channel = null;
+}
+
+export const isOpen = () => channel?.isOpen() === true;
+
+/* ------------------------------------------------------------------
+   transport selection
+------------------------------------------------------------------- */
+
+/**
+ * Where to start.
+ *
+ * A hand-picked transport wins outright, and never expires — it is an
+ * instruction, not a measurement. Failing over would undo it, so a forced
+ * transport keeps retrying itself and the status bar says it is locked.
+ *
+ * Failing that, a remembered choice: on a network that blocks WebSockets,
+ * re-probing costs NET.PROBE_MS of "Connecting…" on every single load and the
+ * answer is the same every time. storage.js expires that memory on its own, so
+ * moving off that network re-probes rather than pinning the user to the slower
+ * transport forever.
+ */
+function preferred() {
+  if (forced && CHANNELS[forced]?.available()) return forced;
+  const remembered = storage.loadTransport();
+  if (remembered && CHANNELS[remembered]?.available()) return remembered;
+  return wsChannel.available() ? TRANSPORT.WS : TRANSPORT.SSE;
+}
+
+/**
+ * Pin the transport, or hand it back to the app.
+ *
+ * Exists because "it works but it is on the slow one" and "it should be on the
+ * slow one and is not" both need an answer a user can act on, and because
+ * reproducing a blocked network to test the fallback otherwise means finding a
+ * blocked network. `null` means auto.
+ */
+export function setTransport(choice) {
+  const next = choice === TRANSPORT.WS || choice === TRANSPORT.SSE ? choice : null;
+  if (next === forced) return;
+
+  forced = next;
+  storage.saveTransportChoice(forced);
+  announced = null;                // the lock changed; the UI needs to hear it
+
+  if (!wantOpen || !session) return announce();
+
+  // Reconnect now rather than at the next drop: the point of choosing is to
+  // see the choice take effect.
+  channel?.close(1000);
+  channel = null;
+  stopTimers();
+  epoch++;
+  stuck = false;
+  failures = { [TRANSPORT.WS]: 0, [TRANSPORT.SSE]: 0 };
+  backoff = NET.BACKOFF_MIN_MS;
+  mode = preferred();
+  announce();
+  start();
+}
+
+export const transportChoice = () => forced;
+
+function switchTransport() {
+  // A forced transport does not fail over. Someone asked for this one
+  // specifically, and silently moving them off it is exactly the behaviour the
+  // switch was added to be able to override.
+  if (forced) return;
+
+  const next = OTHER[mode];
+  if (!CHANNELS[next].available()) return;
+
+  mode = next;
+  failures[next] = 0;
+  backoff = NET.BACKOFF_MIN_MS;    // the switch is a fresh start, not a retry
+
+  // Loud, never silent — the same rule the file layer follows when a P2P
+  // transfer falls back to the relay (FR-7.6). The fallback is slower and the
+  // user is entitled to know which pipe their clipboard is going down.
+  emit(EV.TOAST, next === TRANSPORT.SSE
+    ? "WebSocket blocked — switched to the HTTP fallback"
+    : "Retrying the WebSocket connection");
+}
+
+/** Neither transport is getting through: that is a network problem, not lag. */
+function blocked() {
+  return failures[TRANSPORT.WS] >= NET.SWITCH_AFTER
+      && failures[TRANSPORT.SSE] >= NET.SWITCH_AFTER;
+}
+
+function announce() {
+  const key = `${stuck ? `blocked:${unsupported}` : mode}:${forced}`;
+  if (key === announced) return;   // don't re-raise a banner on every reconnect
+  announced = key;
+  emit(EV.TRANSPORT, {
+    mode: stuck ? null : mode,
+    label: CHANNELS[mode].LABEL,
+    blocked: stuck,
+    // What the picker in the status bar shows as selected. `mode` is what is
+    // actually carrying frames right now; this is what the user asked for, and
+    // on auto they are not the same question.
+    forced,
+    // "the relay is old" and "the network is blocking us" present identically
+    // and have opposite fixes, so the UI is given the difference rather than a
+    // single sentence that has to cover both.
+    unsupported,
+  });
+}
+
+/* ------------------------------------------------------------------
+   one attempt
+------------------------------------------------------------------- */
+
+function start() {
+  stopTimers();
+  opened = false;
+  state.setConnection("connecting", detail());
+
+  const gen = ++epoch;
+  const current = fn => (...args) => { if (gen === epoch) fn(...args); };
+
+  channel = CHANNELS[mode].create({
+    url: session.url,
+    roomHash: session.roomHash,
+    auth: session.auth,
+    onOpen: current(up),
+    onFrame: current(handle),
+    onDown: current(down),
+  });
+
+  // A blocked transport does not always fail — it hangs. An intercepting proxy
+  // can accept the connection, drop the Upgrade (or buffer the event stream)
+  // and then do nothing at all, with no error to react to. Without this timer
+  // the app sits on "Connecting…" indefinitely and the fallback never runs,
+  // which is the whole failure this file exists to handle.
+  probe = setTimeout(() => {
+    if (opened || gen !== epoch) return;
+    channel?.close(4000);          // deliberate: the channel will not call down()
+    channel = null;
+    down({ code: 4000, reason: "no response" });
+  }, NET.PROBE_MS);
+}
+
+function up() {
+  clearTimeout(probe);
+  probe = null;
+
+  opened = true;
+  stuck = false;
+  unsupported = false;
+  idRetries = 0;
+  backoff = NET.BACKOFF_MIN_MS;
+  failures[mode] = 0;
+
+  // Only an automatic success is evidence. A forced transport working proves
+  // nothing about what this network allows — it proves someone clicked it — and
+  // recording it would mean pinning HTTP once left "Automatic" choosing HTTP
+  // for the next twelve hours, which is the opposite of handing control back.
+  if (!forced) storage.saveTransport(mode);
+
+  state.setConnection("connected", detail());
+  announce();
+
+  send(proto.hello(session.intent, state.get().originId, session.name));
+
+  heartbeat = setInterval(() => {
+    pingSentAt = performance.now();
+    send(proto.ping());
+  }, NET.HEARTBEAT_MS);
+}
+
+function down({ code, reason }) {
+  stopTimers();
+  channel = null;
+  if (mode === TRANSPORT.SSE) unsupported = reason === sseChannel.NO_FALLBACK;
+
+  if (!wantOpen) return state.setConnection("idle");
+
+  if (opened) {
+    // Always rejoin: a reconnect is never a "create", or a transient drop would
+    // look like a key collision and needlessly rotate the user's key.
+    session = { ...session, intent: "join" };
+  } else {
+    failures[mode] += 1;
+  }
+
+  // 1012 = "service restart". Every push to main redeploys the relay and closes
+  // every live socket with this code (OI-13) — observed for real during the M0
+  // idle test. It is a planned, short outage rather than a fault, so reset the
+  // backoff and come back promptly instead of treating it like a flaky network
+  // and waiting out a doubled delay.
+  if (code === 1012) backoff = NET.BACKOFF_MIN_MS;
+
+  // Read before switching: switchTransport() zeroes the incoming transport's
+  // counter, so asking afterwards always says "not blocked" and the user would
+  // never be told that nothing at all is getting through.
+  if (!opened && failures[mode] >= NET.SWITCH_AFTER) {
+    if (blocked()) {
+      stuck = true;
+      storage.saveTransport(null);   // neither works; don't pin the next load to one
+    }
+    switchTransport();
+  }
+
+  // Jitter keeps a restart from producing a synchronised reconnect stampede
+  // from every client at the same instant.
+  const wait = Math.round(backoff * (0.8 + Math.random() * 0.4));
+  backoff = Math.min(backoff * 2, NET.BACKOFF_MAX_MS);
+
+  announce();
+
+  if (stuck) {
+    state.setConnection("offline", "relay unreachable");
+  } else {
+    state.setConnection("reconnecting",
+      code === 1012 ? "relay restarting" : detail(`${(wait / 1000).toFixed(1)}s`));
+  }
+
+  const gen = epoch;
+  setTimeout(() => { if (wantOpen && gen === epoch) start(); }, wait);
+}
+
+function stopTimers() {
+  clearInterval(heartbeat);
+  clearTimeout(probe);
+  heartbeat = probe = null;
+}
+
+/**
+ * Status-bar text: whatever the state wants to say, plus the transport.
+ *
+ * "locked" is not decoration. A pinned transport does not fail over, so a user
+ * who pinned WebSocket on a network that blocks it would otherwise watch an
+ * endless reconnect with no hint that they are the reason.
+ */
+const detail = (extra = "") =>
+  [extra, NOTE[mode], forced ? "locked" : ""].filter(Boolean).join(" · ");
+
+/* ------------------------------------------------------------------
+   protocol
+------------------------------------------------------------------- */
+
+let idRetries = 0;
+
+/**
+ * Our own id is still held — by the connection we just closed.
+ *
+ * A rejoin, a key rotation or a collision recovery reconnects within
+ * milliseconds, and the relay only drops a peer once it *notices* the old
+ * transport is gone. Reconnect faster than that and we meet our own ghost: the
+ * relay keeps us under a provisional id, while the files layer goes on
+ * addressing frames to our originId — so transfers to this device quietly stop
+ * resolving. Ask again a moment later, by which time the ghost has been reaped.
+ */
+function reclaimIdentity() {
+  if (idRetries >= 3) return emit(EV.TOAST, proto.ERRORS.PEER_ID_TAKEN);
+  const gen = epoch;
+  const attempt = ++idRetries;
+  setTimeout(() => {
+    if (!isOpen() || gen !== epoch) return;
+    send(proto.hello("join", state.get().originId, session.name));
+  }, 600 * attempt);
+}
+
+function handle(msg) {
+  switch (msg.t) {
+    case proto.T.WELCOME:
+      state.setInstance(msg.instance);
+      if (msg.you) state.get().peerId = msg.you;
+      state.setPeers(msg.peers ?? 1, msg.list ?? []);
+      // `existing > 0` on a create means the generated key is taken (OI-2).
+      if (session.intent === "create" && msg.existing > 0) {
+        emit(EV.KEY_COLLISION, { existing: msg.existing });
+        return;
+      }
+      // A room's last clip is replayed to late joiners, so a device that
+      // arrives mid-session is immediately in sync (FR-3.3).
+      if (msg.last) onFrame(msg.last);
+
+      // What the room looked like at the moment we arrived. main.js needs both
+      // halves and can infer neither: a locked session plants its beacon only
+      // into a room that is empty AND has no retained clip, because the beacon
+      // is a clip and would otherwise overwrite the very thing the line above
+      // exists to deliver. Emitted after the replay so a listener that reacts
+      // to it cannot race the last clip.
+      emit(EV.ROOM_STATE, { existing: msg.existing ?? 0, hasLast: msg.last != null });
+      break;
+
+    case proto.T.PEERS:
+      state.setPeers(msg.count, msg.list ?? []);
+      break;
+
+    case proto.T.PONG:
+      emit(EV.CONN_STATE, {
+        state: "connected",
+        detail: detail(`${Math.round(performance.now() - pingSentAt)} ms`),
+      });
+      break;
+
+    case proto.T.ERROR:
+      if (msg.code === "PEER_ID_TAKEN") return reclaimIdentity();
+      emit(EV.TOAST, proto.ERRORS[msg.code] || `Relay error: ${msg.code}`);
+      break;
+
+    default:
+      onFrame(msg);
+  }
+}

package/src/transport/sse.js

@@ -0,0 +1,244 @@
+/**
+ * SSE + POST channel — the fallback for networks that will not pass WebSockets.
+ *
+ * This is PRD §4.3 R3, fallback 1, and PRD §5.4: a TLS-inspecting corporate
+ * proxy may accept the TCP connection on 443 and then quietly refuse (or worse,
+ * silently swallow) the HTTP Upgrade that a WebSocket needs. Server-Sent Events
+ * are an ordinary long-lived `GET` returning `text/event-stream`, and sends are
+ * an ordinary `POST` — no Upgrade anywhere, so what gets through a proxy is a
+ * plain HTTP response body.
+ *
+ * It implements exactly the contract in transport/ws.js, carries exactly the
+ * envelopes in transport/protocol.js, and relay.js cannot tell which of the two
+ * it is holding beyond the label it prints.
+ *
+ * Two things SSE does not give us for free, handled here:
+ *
+ *   1. It is one-directional. Upstream frames go out as POSTs to /pub, which
+ *      costs one extra round trip per send versus a WebSocket. Sends are
+ *      coalesced (see flush) so a burst — trickle-ICE candidates, file chunks,
+ *      cursor moves — becomes one request rather than thirty.
+ *
+ *      Worth knowing if you ever self-host behind HTTP/1.1: a browser allows
+ *      six connections per host there, and an event stream holds one of them
+ *      open for as long as the tab lives — so half a dozen tabs on the same
+ *      relay can starve each other. Over HTTP/2, which is what any modern host
+ *      (and Cloudflare, which fronts this one) serves, they are multiplexed
+ *      onto one connection and the limit does not apply.
+ *
+ *   2. It has no connection identity. The stream is the session, so the relay
+ *      issues a `sid` on the welcome frame and every POST names it. Without
+ *      that, a POST has no way to say which of eight peers in the room it came
+ *      from — the relay can only trust the connection a frame arrived on
+ *      (see main.py `_forward`), and for this transport that connection is the
+ *      stream, not the POST.
+ */
+
+import { NET } from "../core/config.js";
+import * as proto from "./protocol.js";
+
+export const LABEL = "HTTP stream";
+
+/**
+ * The relay answered, but not on /sse — it is running a build from before the
+ * fallback existed.
+ *
+ * Worth telling apart from a blocked network, because it looks identical from
+ * here and the fix is the opposite one. It is also the likeliest way to meet
+ * this path: deploy the frontend ahead of the relay and every client that falls
+ * back lands on a route that is not there yet.
+ */
+export const NO_FALLBACK = "relay has no fallback endpoint";
+
+export const available = () =>
+  typeof EventSource !== "undefined" && typeof fetch === "function";
+
+/** How long to wait before retrying a POST that failed to reach the relay. */
+const RETRY_MS = 400;
+
+/** A POST that never answers must not wedge the outbox behind it. */
+const POST_TIMEOUT_MS = 15_000;
+
+export function create({ url, roomHash, auth = null, onOpen, onFrame, onDown }) {
+  const base = url.replace(/^ws/i, "http").replace(/\/+$/, "");
+
+  let sid = null;          // issued by the relay on `welcome`; null until then
+  let done = false;
+  let outbox = [];         // serialised frames queued but not yet in flight
+  let inflight = false;
+  let retried = false;
+  let retryTimer = null;
+
+  const finish = (code, reason) => {
+    if (done) return;
+    done = true;
+    clearTimeout(retryTimer);
+    try { es.close(); } catch { /* already gone */ }
+    onDown({ code, reason });
+  };
+
+  // `?a=` — a locked session's admission token, checked at join on both
+  // transports so the fallback is not the lenient way in (see transport/ws.js).
+  const es = new EventSource(
+    `${base}/sse/${roomHash}${auth ? `?a=${encodeURIComponent(auth)}` : ""}`);
+
+  es.onmessage = e => {
+    const msg = proto.parse(e.data);
+
+    // The welcome frame doubles as the handshake for this transport. Note that
+    // "open" here means *the welcome arrived*, not "the GET was accepted": a
+    // proxy that buffers the response body accepts the request happily and then
+    // delivers nothing, which is indistinguishable from a working stream until
+    // you insist on seeing a frame come out of it. relay.js gives every channel
+    // NET.PROBE_MS to reach this line, so that proxy is caught and fallen back
+    // from like any other block.
+    if (msg.t === proto.T.WELCOME && msg.sid && !sid) {
+      sid = msg.sid;
+      delete msg.sid;      // transport plumbing; the protocol layer never sees it
+      onOpen();
+    }
+
+    onFrame(msg);
+  };
+
+  es.onerror = () => {
+    // EventSource reconnects on its own, and that is precisely what must not
+    // happen: the relay would accept the new stream as a brand-new peer with a
+    // new sid, while we carry on POSTing under the old one — a ghost in the
+    // roster and every send rejected. Reconnection is relay.js's job, with its
+    // backoff and its rejoin, so end the stream here and report it.
+    if (sid) return finish(4001, "stream dropped");
+
+    // Nothing has come back at all, and EventSource will not say why — no
+    // status, no body, and a 404 with no CORS header on it reads in the console
+    // as a cross-origin block. So ask the relay something simpler: if /health
+    // answers, the host is reachable and it is the route that is missing.
+    classify().then(reason => finish(4000, reason));
+  };
+
+  async function classify() {
+    const guard = deadline(5000);
+    try {
+      const res = await fetch(`${base}/health`, { signal: guard.signal });
+      return res.ok ? NO_FALLBACK : `relay error ${res.status}`;
+    } catch {
+      return "stream refused";
+    } finally {
+      guard.clear();
+    }
+  }
+
+  /**
+   * Take the next POST's worth of frames.
+   *
+   * Bounded on both count and bytes so one flush cannot exceed what the relay
+   * accepts in a body — a file transfer on the relay-chunk path (FR-7.6) can
+   * queue hundreds of 32 KB frames in a moment.
+   */
+  function take() {
+    const batch = [];
+    let bytes = 0;
+    while (outbox.length && batch.length < NET.POST_MAX_FRAMES) {
+      const next = outbox[0];
+      if (batch.length && bytes + next.length > NET.POST_MAX_BYTES) break;
+      bytes += next.length;
+      batch.push(outbox.shift());
+    }
+    return batch;
+  }
+
+  async function flush() {
+    if (inflight || done || !sid || !outbox.length) return;
+    inflight = true;
+    const batch = take();
+
+    let res = null;
+    const guard = deadline();
+    try {
+      res = await fetch(`${base}/pub/${roomHash}?sid=${encodeURIComponent(sid)}`, {
+        method: "POST",
+        // text/plain keeps this a CORS "simple request". application/json would
+        // make every single send a preflighted pair — an extra OPTIONS round
+        // trip per clip, on the transport already chosen for being the slower
+        // one. The relay parses the body by shape, not by this header.
+        headers: { "Content-Type": "text/plain;charset=UTF-8" },
+        // One frame per line. JSON.stringify escapes every literal newline, so
+        // a frame can never contain one and the split is unambiguous.
+        body: batch.join("\n"),
+        signal: guard.signal,
+      });
+    } catch {
+      // Did not reach the relay at all. Retry once — a clip the user copied is
+      // worth a second attempt — then drop it rather than build an unbounded
+      // queue of stale frames behind a network that is gone. The stream is what
+      // reports the session dead; a failed POST on its own does not.
+      if (!retried) {
+        retried = true;
+        outbox = batch.concat(outbox);
+        retryTimer = setTimeout(() => { inflight = false; flush(); }, RETRY_MS);
+        return;
+      }
+      retried = false;
+      inflight = false;
+      console.warn(`[realtimeclipboard] dropped ${batch.length} frame(s): relay unreachable`);
+      return flush();
+    } finally {
+      guard.clear();
+    }
+
+    retried = false;
+    inflight = false;
+
+    // The stream backing this sid is gone, so there is nowhere for the relay to
+    // answer even if it accepted the frame. Reopening is the only fix.
+    if (res.status === 404 || res.status === 410) {
+      return finish(4404, "session expired");
+    }
+    // Anything else the relay dislikes (too large, rate limited) it also says
+    // on the stream as a normal error frame, which the UI already surfaces.
+    if (!res.ok) console.warn(`[realtimeclipboard] relay rejected a send: HTTP ${res.status}`);
+
+    if (outbox.length) flush();
+  }
+
+  return {
+    label: LABEL,
+
+    // Usable means "the relay has answered and we know who we are". Before the
+    // welcome there is no sid, so there is nowhere to send.
+    isOpen: () => !done && sid !== null,
+
+    send(obj) {
+      if (done || !sid) return false;
+      outbox.push(JSON.stringify(obj));
+      flush();
+      return true;
+    },
+
+    close() {
+      done = true;
+      clearTimeout(retryTimer);
+      outbox = [];
+      // Ending the stream is what tells the relay we left: it notices the
+      // response body being cancelled and drops us from the roster.
+      try { es.close(); } catch { /* already gone */ }
+    },
+  };
+}
+
+/**
+ * A deadline that stops being armed once the request it guards has finished.
+ *
+ * Deliberately not AbortSignal.timeout(): that cannot be cancelled, so it fires
+ * whether or not the fetch already succeeded, and aborting a settled request
+ * still records it as cancelled. Every POST in a session then shows up red in
+ * the network tab as `net::ERR_ABORTED` — some seconds after it returned 204 —
+ * which is a very convincing way for working code to look broken, and exactly
+ * the sort of false trail this transport does not need another of.
+ */
+function deadline(ms = POST_TIMEOUT_MS) {
+  if (typeof AbortController === "undefined") return { signal: undefined, clear() {} };
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), ms);
+  return { signal: ctrl.signal, clear: () => clearTimeout(timer) };
+}