@takosjp/yurucommu-core 3.3.0 → 3.4.0

package/src/backend/routes/realtime/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Realtime stream routes.
+ *
+ *   GET  /api/realtime/config   capability probe ({ available }) — clients
+ *                               gate their fallback polling on this
+ *   POST /api/realtime/ticket   mint a one-time short-lived WS ticket
+ *   GET  /api/realtime/socket   browser WebSocket upgrade -> per-user stream
+ *
+ * Two upgrade auth paths, both terminating in the worker BEFORE the DO is
+ * reached (the DO binding is the trust boundary):
+ *   - session: the same-origin browser sends its session cookie; the /api/*
+ *     middleware resolved the actor already.
+ *   - ticket: a cross-origin or bearer-auth client (the browser WebSocket API
+ *     cannot set an Authorization header) first POSTs /ticket over the normal
+ *     authenticated fetch path, then connects with ?actor=&ticket=. The ticket
+ *     is minted inside — and re-verified + consumed by — the target user's own
+ *     stream DO, so it is single-use, expires in ~60s, and never carries the
+ *     raw session credential in a URL.
+ */
+
+import { Hono } from "hono";
+import type { Env, Variables } from "../../types.ts";
+import {
+  getRealtimeHub,
+  isRealtimeAvailable,
+} from "../../runtime/realtime-hub.ts";
+
+const realtime = new Hono<{ Bindings: Env; Variables: Variables }>();
+
+realtime.get("/config", (c) => {
+  return c.json({ available: isRealtimeAvailable(c.env) });
+});
+
+realtime.post("/ticket", async (c) => {
+  const actor = c.get("actor");
+  if (!actor) return c.json({ error: "unauthorized" }, 401);
+  if (!isRealtimeAvailable(c.env)) {
+    return c.json({ error: "realtime_unavailable" }, 503);
+  }
+  const ticket = await getRealtimeHub(c.env).mintTicket(actor.ap_id);
+  if (!ticket) return c.json({ error: "ticket_mint_failed" }, 500);
+  return c.json({ ticket, actor_ap_id: actor.ap_id });
+});
+
+realtime.get("/socket", async (c) => {
+  if (!isRealtimeAvailable(c.env)) {
+    return c.json({ error: "realtime_unavailable" }, 503);
+  }
+  const hub = getRealtimeHub(c.env);
+
+  const sessionActor = c.get("actor");
+  if (sessionActor) {
+    return hub.upgrade(c.req.raw, sessionActor.ap_id, "session");
+  }
+
+  const actorParam = c.req.query("actor")?.trim();
+  const ticket = c.req.query("ticket")?.trim();
+  if (actorParam && ticket) {
+    // The actor param only selects WHICH stream DO verifies the ticket; a
+    // forged actor value fails inside that DO (it never minted the ticket).
+    return hub.upgrade(c.req.raw, actorParam, "ticket", ticket);
+  }
+
+  return c.json({ error: "unauthorized" }, 401);
+});
+
+export default realtime;

package/src/backend/routes/rtc/index.ts

@@ -139,7 +139,11 @@ rtc.get("/api/rtc/calls", async (c) => {
 rtc.get("/api/rtc/calls/:id", async (c) => {
   const actor = c.get("actor");
   if (!actor) return c.json({ error: "unauthorized" }, 401);
-  const call = await getCallSession(c.get("db"), actor.ap_id, c.req.param("id"));
+  const call = await getCallSession(
+    c.get("db"),
+    actor.ap_id,
+    c.req.param("id"),
+  );
   if (!call) return c.json({ error: "not_found" }, 404);
   return c.json({ call });
 });

package/src/backend/runtime/call-hub-core.ts

@@ -98,7 +98,9 @@ export class CallHub {
 
   /** Snapshot of active (non-terminal) calls — used by the DO to persist. */
   activeCalls(): CallRecord[] {
-    return [...this.calls.values()].filter((c) => !isTerminalCallState(c.state));
+    return [...this.calls.values()].filter(
+      (c) => !isTerminalCallState(c.state),
+    );
   }
 
   /** Restore calls from durable storage after DO hibernation. */
@@ -175,7 +177,11 @@ export class CallHub {
         conn.send({ t: "ready" });
         // Re-announce any active calls so a reconnecting tab resyncs.
         for (const call of this.activeCalls()) {
-          conn.send({ t: "call-state", callId: call.callId, state: call.state });
+          conn.send({
+            t: "call-state",
+            callId: call.callId,
+            state: call.state,
+          });
         }
         return;
       case "ping":
@@ -401,7 +407,11 @@ export class CallHub {
     const call = this.calls.get(envelope.callId);
     if (!call || !envelope.sdp) return;
     if (call.state === "ringing") this.transition(call, "connecting");
-    this.port.broadcast({ t: "answer", callId: call.callId, sdp: envelope.sdp });
+    this.port.broadcast({
+      t: "answer",
+      callId: call.callId,
+      sdp: envelope.sdp,
+    });
   }
 
   private onPeerCandidate(envelope: RtcSignalEnvelopeV1): void {

package/src/backend/runtime/realtime-hub.ts

@@ -0,0 +1,257 @@
+/**
+ * IRealtimeHub — the seam that decouples the realtime event stream from the
+ * Durable Object runtime (mirrors `signaling-hub.ts` for calls).
+ *
+ * On Cloudflare it forwards to the per-user `RealtimeStreamDO`
+ * (`idFromName(actorApId)`); on a runtime without the DO binding the hub is a
+ * null object: `emit` is a no-op and upgrades answer 503, so clients detect
+ * the missing capability (`GET /api/realtime/config`) and fall back to their
+ * low-frequency polling loops. Emits are ALWAYS best-effort — a realtime
+ * delivery failure must never fail the REST write that produced it.
+ */
+
+import { gt } from "drizzle-orm";
+import type { Env } from "../types.ts";
+import { notificationPushJobs } from "../../db/index.ts";
+import { computeUnreadSnapshot } from "../lib/unread-counts.ts";
+import { logger } from "../lib/logger.ts";
+
+const log = logger.child({ component: "realtime.hub" });
+
+export interface IRealtimeHub {
+  /** Forward a browser WebSocket upgrade to `actorApId`'s stream (101). */
+  upgrade(
+    request: Request,
+    actorApId: string,
+    auth: "session" | "ticket",
+    ticket?: string,
+  ): Promise<Response>;
+  /** Mint a one-time short-lived WS ticket inside the user's stream DO. */
+  mintTicket(actorApId: string): Promise<string | null>;
+  /** Push one event to `actorApId`'s live sockets (best-effort). */
+  emit(
+    actorApId: string,
+    type: string,
+    data: Record<string, unknown>,
+  ): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Cloudflare: forward to the per-user Durable Object
+// ---------------------------------------------------------------------------
+class CloudflareRealtimeHub implements IRealtimeHub {
+  constructor(private readonly ns: DurableObjectNamespace) {}
+
+  private stub(actorApId: string): DurableObjectStub {
+    return this.ns.get(this.ns.idFromName(actorApId));
+  }
+
+  async upgrade(
+    request: Request,
+    actorApId: string,
+    auth: "session" | "ticket",
+    ticket?: string,
+  ): Promise<Response> {
+    const headers = new Headers(request.headers);
+    headers.set("X-Realtime-Auth", auth);
+    if (ticket) headers.set("X-Realtime-Ticket", ticket);
+    const forwarded = new Request("https://realtime-do/_ws", {
+      method: "GET",
+      headers,
+    });
+    return this.stub(actorApId).fetch(
+      forwarded as unknown as Parameters<DurableObjectStub["fetch"]>[0],
+    ) as unknown as Promise<Response>;
+  }
+
+  async mintTicket(actorApId: string): Promise<string | null> {
+    const response = await this.stub(actorApId).fetch(
+      "https://realtime-do/_ticket",
+      { method: "POST" },
+    );
+    if (!response.ok) return null;
+    const body = (await response.json()) as { ticket?: unknown };
+    return typeof body.ticket === "string" ? body.ticket : null;
+  }
+
+  async emit(
+    actorApId: string,
+    type: string,
+    data: Record<string, unknown>,
+  ): Promise<void> {
+    await this.stub(actorApId).fetch("https://realtime-do/_emit", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ type, data }),
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Null hub (no DO binding): clients fall back to polling
+// ---------------------------------------------------------------------------
+class NullRealtimeHub implements IRealtimeHub {
+  async upgrade(): Promise<Response> {
+    return new Response(
+      JSON.stringify({
+        error: "realtime_unavailable",
+        message: "Realtime streaming requires the Durable Objects runtime.",
+      }),
+      { status: 503, headers: { "Content-Type": "application/json" } },
+    );
+  }
+
+  async mintTicket(): Promise<string | null> {
+    return null;
+  }
+
+  async emit(): Promise<void> {
+    // no-op: clients poll
+  }
+}
+
+const nullHub = new NullRealtimeHub();
+
+/** Resolve the realtime hub for this runtime. */
+export function getRealtimeHub(env: Env): IRealtimeHub {
+  if (env.REALTIME_STREAM) {
+    return new CloudflareRealtimeHub(env.REALTIME_STREAM);
+  }
+  return nullHub;
+}
+
+/** Whether realtime streaming can be served on this runtime. */
+export function isRealtimeAvailable(env: Env): boolean {
+  return Boolean(env.REALTIME_STREAM);
+}
+
+// ---------------------------------------------------------------------------
+// Best-effort emit helpers (producers call these; failures never propagate)
+// ---------------------------------------------------------------------------
+
+export interface RealtimeEmitInput {
+  actorApId: string;
+  type: string;
+  data: Record<string, unknown>;
+}
+
+/** Emit a batch of events, swallowing (but logging) any delivery failure. */
+export async function emitRealtimeBestEffort(
+  env: Env,
+  events: RealtimeEmitInput[],
+): Promise<void> {
+  if (!isRealtimeAvailable(env) || events.length === 0) return;
+  const hub = getRealtimeHub(env);
+  await Promise.all(
+    events.map(async ({ actorApId, type, data }) => {
+      try {
+        await hub.emit(actorApId, type, data);
+      } catch (error) {
+        log.warn("Realtime emit failed", {
+          event: "realtime.emit_failed",
+          type,
+          error,
+        });
+      }
+    }),
+  );
+}
+
+/**
+ * Compute and push the authoritative unread counters for one user. The
+ * counters are always server-derived (the same SQL as the badge endpoints) so
+ * a pushed badge can never drift from what the client would fetch.
+ */
+export async function emitUnreadSnapshot(
+  env: Env,
+  actorApId: string,
+): Promise<void> {
+  if (!isRealtimeAvailable(env)) return;
+  try {
+    const snapshot = await computeUnreadSnapshot(env.DB_INSTANCE, actorApId);
+    await getRealtimeHub(env).emit(actorApId, "unread", {
+      dm: snapshot.dm,
+      community: snapshot.community,
+      talk_total: snapshot.talkTotal,
+      notifications: snapshot.notifications,
+    });
+  } catch (error) {
+    log.warn("Realtime unread emit failed", {
+      event: "realtime.unread_emit_failed",
+      error,
+    });
+  }
+}
+
+/**
+ * Schedule best-effort realtime work after the response is sent. Mirrors the
+ * push-outbox sweep in index.ts: prefer `executionCtx.waitUntil`, fall back to
+ * awaiting inline where no runtime context exists (tests / plain fetch).
+ */
+export async function runRealtimeAfterResponse(
+  c: { executionCtx?: { waitUntil?: (p: Promise<unknown>) => void } },
+  task: () => Promise<void>,
+): Promise<void> {
+  const wrapped = task().catch((error) => {
+    log.warn("Realtime after-response task failed", {
+      event: "realtime.after_response_failed",
+      error,
+    });
+  });
+  try {
+    const ctx = c.executionCtx;
+    if (ctx && typeof ctx.waitUntil === "function") {
+      ctx.waitUntil(wrapped);
+      return;
+    }
+  } catch {
+    // No execution context; await inline below.
+  }
+  await wrapped;
+}
+
+// ---------------------------------------------------------------------------
+// Notification sweep (the same choke points that flush the push outbox)
+// ---------------------------------------------------------------------------
+
+// Every unread inbox insert is captured by the notification_push_jobs DB
+// trigger — the single choke point covering all nine scattered insert sites
+// (follow/like/reply/mention/DM/federation/community fanout). A DB trigger
+// cannot call a Durable Object, so this sweep reads the jobs the trigger
+// wrote and emits `notification.new` + `unread` to each affected user. It is
+// called from the SAME two flush points as `enqueuePendingNotificationPushJobs`
+// (the post-response middleware and the queue-consumer tail).
+//
+// The cursor is per-isolate in-memory, initialized to isolate start so a cold
+// isolate never replays history; a double-emit across isolates is harmless
+// (clients treat both event types idempotently: refetch + set-counter).
+let realtimeSweepCursor = new Date().toISOString();
+
+export async function sweepRealtimeNotifications(env: Env): Promise<void> {
+  if (!isRealtimeAvailable(env)) return;
+  const since = realtimeSweepCursor;
+  const nextCursor = new Date().toISOString();
+  try {
+    const rows = await env.DB_INSTANCE.selectDistinct({
+      actorApId: notificationPushJobs.actorApId,
+    })
+      .from(notificationPushJobs)
+      .where(gt(notificationPushJobs.createdAt, since))
+      .limit(50);
+    realtimeSweepCursor = nextCursor;
+    if (rows.length === 0) return;
+    await Promise.all(
+      rows.map(async ({ actorApId }) => {
+        await emitRealtimeBestEffort(env, [
+          { actorApId, type: "notification.new", data: {} },
+        ]);
+        await emitUnreadSnapshot(env, actorApId);
+      }),
+    );
+  } catch (error) {
+    log.warn("Realtime notification sweep failed", {
+      event: "realtime.sweep_failed",
+      error,
+    });
+  }
+}

package/src/backend/runtime/realtime-stream-do.ts

@@ -0,0 +1,323 @@
+/**
+ * RealtimeStreamDO — per-local-user realtime fanout stream.
+ *
+ * One DO instance per local actor (`idFromName(actorApId)`). It is the single
+ * standing WebSocket the browser keeps open; every live update the client used
+ * to poll for (talk messages, typing, read receipts, notifications, unread
+ * counters) is pushed through it as a `RealtimeEvent`.
+ *
+ * Producers (the worker's REST handlers and queue consumers) POST events to
+ * `/_emit`; the DO assigns a monotonic id, persists the event into a small
+ * ring buffer (so a reconnect can replay the gap across hibernation), and
+ * broadcasts to every connected socket. Deliberately separate from
+ * `CallSignalingDurableObject`: call signaling is ephemeral SDP/ICE with its
+ * own state machine, while this stream is a durable-ordered event feed.
+ *
+ * Auth model: the DO binding is the trust boundary. `/ _ws` upgrades arrive
+ * only via the worker route, which either resolved the session actor or
+ * verified a one-time ticket this DO minted earlier (`/_ticket`); the DO
+ * re-checks ticket upgrades against its own storage so a ticket is
+ * single-use and expires even if the worker is confused.
+ *
+ * Uses Hibernatable WebSockets: idle sockets are evicted from memory and the
+ * ring buffer lives in DO storage, so an idle connected user costs nothing.
+ */
+
+import type {
+  RealtimeEvent,
+  RealtimeServerFrame,
+} from "../../../packages/api/src/types/realtime.ts";
+import { parseRealtimeClientFrame } from "../../../packages/api/src/types/realtime.ts";
+
+// --- Minimal Cloudflare DO + Hibernatable WebSocket surface ----------------
+// (typed file-locally, matching call-signaling-do.ts, so this file does not
+// depend on a specific @cloudflare/workers-types version)
+interface DoWebSocket {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+}
+interface DoStorage {
+  get<T = unknown>(key: string): Promise<T | undefined>;
+  put(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  list<T = unknown>(options?: {
+    prefix?: string;
+    limit?: number;
+    reverse?: boolean;
+  }): Promise<Map<string, T>>;
+}
+interface DoState {
+  acceptWebSocket(ws: DoWebSocket, tags?: string[]): void;
+  getWebSockets(tag?: string): DoWebSocket[];
+  readonly storage: DoStorage;
+}
+declare const WebSocketPair: {
+  new (): { 0: DoWebSocket; 1: DoWebSocket };
+};
+
+const SEQ_KEY = "seq";
+const EVENT_PREFIX = "evt:";
+/** Ring buffer size: how many events a reconnect can replay before `resync`. */
+const EVENT_BUFFER_SIZE = 200;
+const TICKET_PREFIX = "ticket:";
+/** Outstanding one-time tickets per user (multiple tabs may mint at once). */
+const MAX_OUTSTANDING_TICKETS = 8;
+const TICKET_TTL_MS = 60_000;
+
+interface StoredTicket {
+  hash: string;
+  expiresAt: number;
+}
+
+function eventKey(seq: number): string {
+  // Fixed-width key so storage.list({prefix}) returns events in seq order.
+  return `${EVENT_PREFIX}${String(seq).padStart(12, "0")}`;
+}
+
+async function sha256Hex(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(value),
+  );
+  return [...new Uint8Array(digest)]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/** Constant-time hex-string comparison (both inputs are fixed-width hashes). */
+function timingSafeEqualHex(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+export class RealtimeStreamDO {
+  private seqCache: number | null = null;
+
+  constructor(private readonly state: DoState) {}
+
+  async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    switch (url.pathname) {
+      case "/_ws":
+        return this.handleUpgrade(request);
+      case "/_emit":
+        return this.handleEmit(request);
+      case "/_ticket":
+        return this.handleMintTicket(request);
+      case "/_state":
+        return this.handleState();
+      default:
+        return new Response("not found", { status: 404 });
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Ticket mint + verify (one-time, short-lived; stored only as a hash)
+  // -------------------------------------------------------------------------
+  private async handleMintTicket(request: Request): Promise<Response> {
+    if (request.method !== "POST") {
+      return new Response("method not allowed", { status: 405 });
+    }
+    const ticket =
+      crypto.randomUUID().replaceAll("-", "") +
+      crypto.randomUUID().replaceAll("-", "");
+    const hash = await sha256Hex(ticket);
+    const now = Date.now();
+
+    const stored = await this.state.storage.list<StoredTicket>({
+      prefix: TICKET_PREFIX,
+    });
+    // Drop expired tickets; keep the newest few so parallel tabs still work.
+    const live = [...stored.entries()]
+      .filter(([, t]) => t.expiresAt > now)
+      .sort((a, b) => a[1].expiresAt - b[1].expiresAt);
+    for (const [key] of stored) {
+      if (!live.some(([liveKey]) => liveKey === key)) {
+        await this.state.storage.delete(key);
+      }
+    }
+    while (live.length >= MAX_OUTSTANDING_TICKETS) {
+      const [oldestKey] = live.shift()!;
+      await this.state.storage.delete(oldestKey);
+    }
+    await this.state.storage.put(`${TICKET_PREFIX}${hash}`, {
+      hash,
+      expiresAt: now + TICKET_TTL_MS,
+    } satisfies StoredTicket);
+
+    return Response.json({ ticket });
+  }
+
+  private async consumeTicket(ticket: string): Promise<boolean> {
+    const hash = await sha256Hex(ticket);
+    const key = `${TICKET_PREFIX}${hash}`;
+    const stored = await this.state.storage.get<StoredTicket>(key);
+    if (!stored) return false;
+    // Single-use: consume before validating expiry so a replay always misses.
+    await this.state.storage.delete(key);
+    if (stored.expiresAt <= Date.now()) return false;
+    return timingSafeEqualHex(stored.hash, hash);
+  }
+
+  // -------------------------------------------------------------------------
+  // WebSocket upgrade
+  // -------------------------------------------------------------------------
+  private async handleUpgrade(request: Request): Promise<Response> {
+    if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") {
+      return new Response("expected websocket", { status: 426 });
+    }
+    // The worker route either authenticated the session itself (auth=session)
+    // or forwards a ticket this DO minted; re-verify tickets against storage.
+    const authMode = request.headers.get("X-Realtime-Auth");
+    if (authMode === "ticket") {
+      const ticket = request.headers.get("X-Realtime-Ticket") ?? "";
+      if (!ticket || !(await this.consumeTicket(ticket))) {
+        return new Response("invalid ticket", { status: 401 });
+      }
+    } else if (authMode !== "session") {
+      return new Response("unauthorized", { status: 401 });
+    }
+
+    const pair = new WebSocketPair();
+    const client = pair[0];
+    const server = pair[1];
+    this.state.acceptWebSocket(server);
+    return new Response(null, {
+      status: 101,
+      // `webSocket` is a Cloudflare-specific ResponseInit field.
+      webSocket: client,
+    } as unknown as ResponseInit);
+  }
+
+  // -------------------------------------------------------------------------
+  // Event ingest + fanout
+  // -------------------------------------------------------------------------
+  private async handleEmit(request: Request): Promise<Response> {
+    if (request.method !== "POST") {
+      return new Response("method not allowed", { status: 405 });
+    }
+    let body: { type?: unknown; data?: unknown };
+    try {
+      body = (await request.json()) as { type?: unknown; data?: unknown };
+    } catch {
+      return new Response("bad json", { status: 400 });
+    }
+    if (typeof body.type !== "string" || !body.type) {
+      return new Response("bad event", { status: 400 });
+    }
+    const data =
+      body.data && typeof body.data === "object"
+        ? (body.data as Record<string, unknown>)
+        : {};
+
+    const seq = (await this.currentSeq()) + 1;
+    const event: RealtimeEvent = {
+      id: seq,
+      type: body.type as RealtimeEvent["type"],
+      data,
+    };
+    await this.state.storage.put(eventKey(seq), event);
+    await this.state.storage.put(SEQ_KEY, seq);
+    this.seqCache = seq;
+    const pruneSeq = seq - EVENT_BUFFER_SIZE;
+    if (pruneSeq > 0) {
+      await this.state.storage.delete(eventKey(pruneSeq));
+    }
+
+    this.broadcast({ t: "event", event });
+    return Response.json({
+      id: seq,
+      sockets: this.state.getWebSockets().length,
+    });
+  }
+
+  private async handleState(): Promise<Response> {
+    return Response.json({
+      seq: await this.currentSeq(),
+      sockets: this.state.getWebSockets().length,
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Hibernatable WebSocket events
+  // -------------------------------------------------------------------------
+  async webSocketMessage(
+    ws: DoWebSocket,
+    message: string | ArrayBuffer,
+  ): Promise<void> {
+    if (typeof message !== "string") return;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(message);
+    } catch {
+      return;
+    }
+    const frame = parseRealtimeClientFrame(parsed);
+    if (!frame) return;
+
+    switch (frame.t) {
+      case "ping":
+        this.send(ws, { t: "pong" });
+        return;
+      case "pong":
+        return;
+      case "hello": {
+        const seq = await this.currentSeq();
+        if (frame.lastEventId !== undefined && frame.lastEventId < seq) {
+          const oldestBuffered = Math.max(1, seq - EVENT_BUFFER_SIZE + 1);
+          if (frame.lastEventId >= oldestBuffered - 1) {
+            for (let i = frame.lastEventId + 1; i <= seq; i++) {
+              const event = await this.state.storage.get<RealtimeEvent>(
+                eventKey(i),
+              );
+              if (event) this.send(ws, { t: "event", event });
+            }
+          } else {
+            // Gap predates the ring buffer: the client must re-fetch via REST.
+            this.send(ws, { t: "resync" });
+          }
+        }
+        this.send(ws, { t: "hello_ok", lastEventId: seq });
+        return;
+      }
+    }
+  }
+
+  async webSocketClose(ws: DoWebSocket): Promise<void> {
+    try {
+      ws.close();
+    } catch {
+      // already closing
+    }
+  }
+
+  async webSocketError(): Promise<void> {
+    // getWebSockets() excludes the errored socket automatically.
+  }
+
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+  private async currentSeq(): Promise<number> {
+    if (this.seqCache !== null) return this.seqCache;
+    const stored = await this.state.storage.get<number>(SEQ_KEY);
+    this.seqCache = typeof stored === "number" ? stored : 0;
+    return this.seqCache;
+  }
+
+  private broadcast(frame: RealtimeServerFrame): void {
+    for (const ws of this.state.getWebSockets()) this.send(ws, frame);
+  }
+
+  private send(ws: DoWebSocket, frame: RealtimeServerFrame): void {
+    try {
+      ws.send(JSON.stringify(frame));
+    } catch {
+      // socket gone; getWebSockets() will drop it
+    }
+  }
+}