@pithy-sh/core 0.12.0 → 0.14.0

package/src/presence/declaration.ts

@@ -0,0 +1,283 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context } from "hono";
+import type { BindingSpecInput } from "../capability/bindings";
+import type { PithyHonoEnv } from "../capability/capability";
+import { remedy } from "../cli/command";
+import { ControlPlaneScope } from "../controlPlane/scope/scope";
+import { InternalError } from "../error/pithyError";
+import { PRESENCE_PARTICIPANT_NAME_MAX } from "./frames";
+import { PresenceActivity, PresenceRoomKindName } from "./names";
+
+/**
+ * **Presence rooms: who else has a record open, live, from the adopter's own Worker.**
+ *
+ * A capability declares the room kinds it serves beside its admin routes, on {@link Capability.presence}: a
+ * name (`support.thread`), the control-plane scope that reads the record (`support:threads:read`), and the
+ * activities a participant may announce (`viewing`, `replying`). A room is one kind plus one record id, and
+ * it lives in one hibernating Durable Object, `PresenceRoom`, that holds nothing but who is in it.
+ *
+ * Joining takes a **ticket**, because a browser's `WebSocket` sets no headers and so cannot carry either the
+ * control-plane token or, cross-origin, a session cookie. A ticket is minted by one of two routes — the
+ * control-plane one behind the kind's scope, or the capability's own session one behind its own read
+ * permission — and presented once, in the subprotocol offer, within 60 seconds.
+ *
+ * **Presence adds no scope of its own.** Anyone who may read a record may see who else has it open, so the
+ * room kind names the scope that already reads the record and the session gate the capability already has.
+ *
+ * This module is pure: zod, types and constants. The routes are in `./http/routes.ts`, the Durable Object in
+ * `./durableObject.ts`, and nothing here imports either.
+ */
+
+/** The Durable Object binding every room lives behind. One namespace for every room kind in a Worker. */
+export const PRESENCE_ROOMS_BINDING = "PRESENCE_ROOMS";
+
+/** The class that backs {@link PRESENCE_ROOMS_BINDING}, and the module the Worker's entry re-exports it from. */
+export const PRESENCE_ROOM_CLASS = "PresenceRoom";
+
+/** Its own module, never a package entry point, so `pithy.config.ts` can load the capability in Node. */
+export const PRESENCE_ROOM_MODULE = "@pithy-sh/core/src/presence/durableObject";
+
+/**
+ * The binding a capability that declares room kinds requires. `defineCapability` adds it, so a capability
+ * never spells it; a kit capability's `pithy.manifest.json` names it exactly as written here, which is what
+ * `pithy add` and `pithy upgrade` wire through the Durable Object path (#428).
+ */
+export const PRESENCE_ROOMS_BINDING_SPEC: BindingSpecInput = {
+  type: "durable_object",
+  name: PRESENCE_ROOMS_BINDING,
+  className: PRESENCE_ROOM_CLASS,
+  classModule: PRESENCE_ROOM_MODULE,
+};
+
+/**
+ * The secret tickets are signed with: one per Worker environment, generated, never typed. A capability that
+ * declares room kinds declares this name in its `@pithy-sh/secrets` registry with {@link
+ * PRESENCE_TICKET_KEY_ENTRY} and reads it through `secretsStore`, and its manifest lists it under
+ * `devSecrets` so `pithy add` mints the local value. The name is the join key, so every capability that
+ * declares rooms in one Worker signs and verifies with the one key.
+ */
+export const PRESENCE_TICKET_KEY_SECRET = "presence-ticket-key";
+
+/**
+ * The registry entry for {@link PRESENCE_TICKET_KEY_SECRET}, in the shape `defineSecretRegistry` takes. Its
+ * value is arbitrary — nothing outside the Worker has to agree with it — so it is `devValue: "random"`, and
+ * rotatable because {@link PresenceTicketKey} accepts every version still honored.
+ */
+export const PRESENCE_TICKET_KEY_ENTRY = {
+  backend: "d1",
+  scope: "environment",
+  rotatable: true,
+  valueType: "text",
+  devValue: "random",
+} as const;
+
+/** How long a minted ticket is honored, in seconds. Long enough to open a socket, short enough to be useless later. */
+export const PRESENCE_TICKET_TTL_SECONDS = 60;
+
+/** The participant cap a room kind gets when it declares none. */
+export const DEFAULT_PRESENCE_PARTICIPANTS = 25;
+
+/** The most participants any room kind may declare. A room is one Durable Object, and every frame fans out to all of them. */
+export const MAX_PRESENCE_PARTICIPANTS = 100;
+
+/** The largest frame a room accepts from a client, in bytes. The one frame a client sends is an activity name. */
+export const PRESENCE_MAX_FRAME_BYTES = 1024;
+
+/** The most activities one room kind may declare. */
+export const MAX_PRESENCE_ACTIVITIES = 16;
+
+/** What the session gate grants: the participant's display name, or the user id when it names none. */
+export interface PresenceSessionGrant {
+  /**
+   * How other participants see this user. Trimmed and cut to 80 characters; the user id when it is missing
+   * or blank, so a gate can pass a stored display name through as it is.
+   */
+  readonly name?: string;
+}
+
+/**
+ * The name a session participant joins under: the gate's, trimmed and cut to fit, or the user id when the
+ * gate names none or a blank one. Always a name a ticket accepts — a display name is the user's own data, and
+ * one too long or empty must not lock them out of every room.
+ */
+export function sessionParticipantName(name: string | undefined, userId: string): string {
+  return fitName(name ?? "") || fitName(userId) || "Participant";
+}
+
+/** Trim, then cut to {@link PRESENCE_PARTICIPANT_NAME_MAX} code units without splitting a character. */
+function fitName(raw: string): string {
+  let fitted = "";
+  for (const char of raw.trim()) {
+    if (fitted.length + char.length > PRESENCE_PARTICIPANT_NAME_MAX) break;
+    fitted += char;
+  }
+  return fitted.trim();
+}
+
+/**
+ * The capability's own permission for reading one record, for a signed-in user of the app. Answer a grant
+ * to admit, `null` to refuse. `c.var.auth` is already set when it runs; it is the capability's job to say
+ * whether that user may read `recordId`, exactly as its own read route would.
+ */
+export type PresenceSessionGate = (
+  c: Context<PithyHonoEnv>,
+  recordId: string,
+) => PresenceSessionGrant | null | Promise<PresenceSessionGrant | null>;
+
+/** One room kind a capability serves. */
+export interface PresenceRoomKind {
+  /** The kind's name — `support.thread`. Its first segment must be the declaring capability's name. */
+  readonly kind: string;
+  /** The control-plane scope that reads the record. A management client joins with exactly this scope. */
+  readonly scope: string;
+  /** The activities a participant may announce. The first is what a participant starts as. */
+  readonly activities: readonly [string, ...string[]];
+  /** The participant cap. Defaults to {@link DEFAULT_PRESENCE_PARTICIPANTS}, at most {@link MAX_PRESENCE_PARTICIPANTS}. */
+  readonly maxParticipants?: number;
+  /**
+   * Who of the app's own signed-in users may join: the capability's read permission for the record. Absent,
+   * the kind admits management clients only and the session ticket route refuses it.
+   */
+  readonly session?: PresenceSessionGate;
+}
+
+/**
+ * The secret tickets are signed with: the value, every value still honored during a rotation (the first
+ * signs), or a resolver reading it from the Worker env per request — which is the only form a secret read
+ * through `@pithy-sh/secrets` can take, since `env` exists only per request.
+ */
+export type PresenceTicketKey =
+  | string
+  | readonly string[]
+  | ((env: Record<string, unknown>) => string | readonly string[] | Promise<string | readonly string[]>);
+
+/** A capability's presence declaration — see {@link Capability.presence}. */
+export interface PresenceDeclaration {
+  /**
+   * Where this capability mounts its presence routes: `{basePath}/presence/tickets` and
+   * `{basePath}/presence/rooms/:kind/:recordId`. The capability's own resolved `basePath`, never its default.
+   */
+  readonly basePath: string;
+  /** The room kinds it serves. */
+  readonly rooms: readonly PresenceRoomKind[];
+  /** The ticket signing key — {@link PRESENCE_TICKET_KEY_SECRET}, read through the capability's own secrets reader. */
+  readonly ticketKey: PresenceTicketKey;
+}
+
+/** The session ticket route, under a capability's base path. */
+export function presenceTicketPath(basePath: string): string {
+  return `${basePath}/presence/tickets`;
+}
+
+/** The socket route, under a capability's base path, as Hono registers it. */
+export function presenceSocketPath(basePath: string): string {
+  return `${basePath}/presence/rooms/:kind/:recordId`;
+}
+
+/** The socket path for one room, ready to open. */
+export function presenceRoomPath(basePath: string, kind: string, recordId: string): string {
+  return `${basePath}/presence/rooms/${encodeURIComponent(kind)}/${encodeURIComponent(recordId)}`;
+}
+
+/** The participant cap a room kind runs with. */
+export function participantCap(room: PresenceRoomKind): number {
+  return room.maxParticipants ?? DEFAULT_PRESENCE_PARTICIPANTS;
+}
+
+/** One of the capability's own admin routes, as far as the scope rule reads it: its method and the scope it requires. */
+export interface PresenceGatingRoute {
+  method: string;
+  scope: string | null;
+}
+
+/**
+ * Refuse a declaration no room could be served from, where it is written and naming the capability: a kind
+ * outside the capability's own name, a duplicate, a scope that is not one, an activity that is not one, a
+ * cap out of range. A declaration that reached a request would be refused there, by a caller, in a way only
+ * the operator can fix.
+ *
+ * **A room kind's scope is one the capability's own admin routes already require, and only `GET`s require
+ * it** — compared against `adminRoutes`, the same artifact `capabilityHealthSources` polices health keys
+ * with, and for the same reason. `pithy dashboard connect` offers the scopes it reads off `adminRoutes`, so
+ * a scope no route requires — one of presence's own, a near-miss, another capability's — is never offered
+ * and never in the default grant, and the room is unjoinable from every management client with no error to
+ * say why. And a scope that also gates a write would make joining a room need a mutation grant, which
+ * inverts the read rule `grant.ts` applies.
+ */
+export function assertPresenceDeclaration(
+  capability: string,
+  presence: PresenceDeclaration,
+  adminRoutes: readonly PresenceGatingRoute[],
+): void {
+  const refuse = (detail: string): never => {
+    throw new InternalError({
+      message: `${capability} declares presence rooms this Worker cannot serve.`,
+      action: `Fix the presence declaration on the ${capability} capability.`,
+      detail,
+    });
+  };
+  if (!presence.basePath.startsWith("/") || presence.basePath.endsWith("/")) {
+    refuse(`presence basePath "${presence.basePath}" must start with "/" and not end with one`);
+  }
+  const seen = new Set<string>();
+  for (const room of presence.rooms) {
+    if (!PresenceRoomKindName.safeParse(room.kind).success) refuse(`room kind "${room.kind}" is not a kind name`);
+    if (!room.kind.startsWith(`${capability}.`)) {
+      refuse(
+        `room kind "${room.kind}" must start with "${capability}." — a capability declares kinds under its own name`,
+      );
+    }
+    if (seen.has(room.kind)) refuse(`room kind "${room.kind}" is declared twice`);
+    seen.add(room.kind);
+    if (!ControlPlaneScope.safeParse(room.scope).success)
+      refuse(`room kind "${room.kind}" scope "${room.scope}" is not a scope`);
+    // Inherited, never invented: the scope a room joins with is one this capability already gates a read with.
+    const gating = adminRoutes.filter((route) => route.scope === room.scope);
+    if (gating.length === 0) {
+      refuse(
+        `room kind "${room.kind}" scope "${room.scope}": no admin route of ${capability} requires it, so no grant would ever offer it`,
+      );
+    }
+    const write = gating.find((route) => route.method !== "GET");
+    if (write) {
+      refuse(
+        `room kind "${room.kind}" scope "${room.scope}" gates a ${write.method}; a room joins with a read scope, one only GET routes require`,
+      );
+    }
+    if (room.activities.length === 0 || room.activities.length > MAX_PRESENCE_ACTIVITIES) {
+      refuse(
+        `room kind "${room.kind}" declares ${room.activities.length} activities; it needs 1 to ${MAX_PRESENCE_ACTIVITIES}`,
+      );
+    }
+    if (new Set(room.activities).size !== room.activities.length) {
+      refuse(`room kind "${room.kind}" declares an activity twice`);
+    }
+    for (const activity of room.activities) {
+      if (!PresenceActivity.safeParse(activity).success)
+        refuse(`room kind "${room.kind}" activity "${activity}" is not one word`);
+    }
+    const cap = participantCap(room);
+    if (!Number.isInteger(cap) || cap < 1 || cap > MAX_PRESENCE_PARTICIPANTS) {
+      refuse(`room kind "${room.kind}" maxParticipants ${cap} is outside 1 to ${MAX_PRESENCE_PARTICIPANTS}`);
+    }
+  }
+}
+
+/**
+ * The ticket signing keys, resolved and non-empty — the first signs, every one verifies. A blank entry is
+ * dropped rather than tried, since WebCrypto refuses a zero-length key with an error that names nothing.
+ */
+export async function resolveTicketKeys(key: PresenceTicketKey, env: Record<string, unknown>): Promise<string[]> {
+  const resolved = typeof key === "function" ? await key(env) : key;
+  const keys = (typeof resolved === "string" ? [resolved] : [...resolved]).filter((value) => value.length > 0);
+  if (keys.length === 0) {
+    throw new InternalError({
+      message: "Presence is not available right now.",
+      action: `Set ${PRESENCE_TICKET_KEY_SECRET}. ${remedy("secrets provision", {}, { runtime: true }).say((command) => `${command} mints it for each environment.`)}`,
+      detail: `${PRESENCE_TICKET_KEY_SECRET} resolved to no usable value`,
+    });
+  }
+  return keys;
+}

package/src/presence/durableObject.ts

@@ -0,0 +1,287 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { DurableObject } from "cloudflare:workers";
+import { clientError } from "../error/client";
+import {
+  fromZodError,
+  PithyError,
+  PresenceRoomFullError,
+  PresenceTicketInvalidError,
+  ValidationError,
+} from "../error/pithyError";
+import { negotiateSubprotocol, SUBPROTOCOL_HEADER } from "../http/subprotocol";
+import { PRESENCE_MAX_FRAME_BYTES } from "./declaration";
+import {
+  PRESENCE_ROOM_VERSIONS,
+  type PresenceParticipant,
+  PresenceRoomClientFrame,
+  PresenceRoomPing,
+  PresenceRoomPong,
+  type PresenceRoomServerFrame,
+} from "./frames";
+import {
+  admit,
+  carrySpent,
+  declaresActivity,
+  inheritSpent,
+  PRESENCE_ADMISSION_HEADER,
+  PresenceAdmission,
+  PresenceAttachment,
+  type SpentTicket,
+} from "./room";
+
+/**
+ * **One presence room: who has one record open, and what they are doing.** Addressed by `<kind>:<recordId>`,
+ * so each record has its own object.
+ *
+ * The Hibernation API only: `ctx.acceptWebSocket`, never `ws.accept()`, and no registry of sockets in
+ * memory — the participants are read back from `getWebSockets()`, each from its own attachment, so a room
+ * that hibernates and wakes knows exactly who is in it. Nothing is written to Durable Object storage: the
+ * room holds nothing but who is here, and when the last socket closes it is gone.
+ *
+ * The upgrade is forwarded by the Worker's socket route, which has verified the ticket and states the
+ * admission on {@link PRESENCE_ADMISSION_HEADER}. The room trusts that header — a Durable Object is reached
+ * only through its binding — and decides the two things only it can: whether the ticket is already spent, and
+ * whether the room is full.
+ */
+export class PresenceRoom extends DurableObject<Record<string, unknown>> {
+  /**
+   * Tickets redeemed by sockets that closed while no other socket was left to carry them. Memory, not
+   * storage, and only while the room is empty: the next socket to join takes them into its attachment, and
+   * until one does, {@link awake} keeps the room from hibernating and losing them.
+   */
+  private remembered: SpentTicket[] = [];
+
+  /**
+   * The timer that holds an empty room awake until the last remembered ticket would expire. A Durable Object
+   * with no socket hibernates after about ten seconds idle and loses its memory, which would let a spent
+   * ticket in again; a pending timer is one of the things that stops it. With no timer, an idle object that
+   * cannot hibernate is evicted only after 70 seconds or more — past a 60-second ticket's life. A deploy or a
+   * restart still clears it, and drops every socket with it.
+   */
+  private awake: { until: number; timer: ReturnType<typeof setTimeout> } | null = null;
+
+  override async fetch(request: Request): Promise<Response> {
+    if (request.headers.get("upgrade") !== "websocket") {
+      return new Response("Expected a WebSocket upgrade.", { status: 426 });
+    }
+    try {
+      const admission = this.admission(request);
+      const version = negotiateSubprotocol(request.headers.get(SUBPROTOCOL_HEADER), PRESENCE_ROOM_VERSIONS);
+      if (version === null) throw new ValidationError({ message: "Offer pithy.presence.v1." });
+
+      const now = new Date();
+      const nowSeconds = Math.floor(now.getTime() / 1000);
+      const present = this.attachments();
+      // A socket closing whose close event has not yet run still holds its ticket and what it carries.
+      const leaving = this.leavingAttachments().flatMap((attachment) => [attachment.ticket, ...attachment.spent]);
+      const refusal = admit(admission, present, [...this.remembered, ...leaving], nowSeconds);
+      if (refusal === "spent")
+        throw new PresenceTicketInvalidError({ detail: `ticket ${admission.ticket.id} is spent` });
+      if (refusal === "full") {
+        throw new PresenceRoomFullError({
+          detail: `${admission.kind}/${admission.recordId} at ${admission.maxParticipants}`,
+        });
+      }
+
+      const participant: PresenceParticipant = {
+        id: crypto.randomUUID(),
+        ref: admission.ref,
+        name: admission.name,
+        origin: admission.origin,
+        activity: admission.activities[0] as string,
+        joinedAt: now.toISOString(),
+      };
+      const pair = new WebSocketPair();
+      const [client, server] = [pair[0], pair[1]];
+      this.ctx.acceptWebSocket(server);
+      server.serializeAttachment({
+        participant,
+        version,
+        ticket: admission.ticket,
+        activities: admission.activities,
+        spent: inheritSpent(this.remembered, admission.ticket.id, nowSeconds),
+      } satisfies PresenceAttachment);
+      // On a socket now, which survives hibernation; the room's memory need not hold them, nor stay awake to.
+      this.remembered = [];
+      this.stayAwake(nowSeconds);
+
+      // In the order they joined. The runtime hands sockets back in no promised order.
+      const everyone = [...present.map((attachment) => attachment.participant), participant].sort((a, b) =>
+        a.joinedAt.localeCompare(b.joinedAt),
+      );
+      server.send(render({ type: "init", self: participant.id, participants: everyone }));
+      this.broadcast({ type: "joined", participant }, server);
+
+      // A browser drops a socket whose 101 does not name the subprotocol it chose.
+      return new Response(null, { status: 101, webSocket: client, headers: { [SUBPROTOCOL_HEADER]: version } });
+    } catch (error) {
+      if (!(error instanceof PithyError)) throw error;
+      return Response.json({ error: clientError(error.payload) }, { status: error.payload.status });
+    }
+  }
+
+  /**
+   * One frame from a participant: `ping`, or `set_activity` naming an activity the room kind declares. A frame
+   * past the size limit, one that does not parse, and an undeclared activity are each answered with an error
+   * frame and change nothing.
+   */
+  override async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
+    const attachment = this.attachmentOf(ws);
+    if (!attachment) return;
+    const bytes = typeof message === "string" ? new TextEncoder().encode(message).byteLength : message.byteLength;
+    try {
+      if (bytes > PRESENCE_MAX_FRAME_BYTES) {
+        throw new ValidationError({
+          message: `A frame is at most ${PRESENCE_MAX_FRAME_BYTES} bytes.`,
+          detail: `${bytes} bytes`,
+        });
+      }
+      const text = typeof message === "string" ? message : new TextDecoder().decode(message);
+      if (PresenceRoomPing.safeParse(text).success) {
+        ws.send(PresenceRoomPong.value);
+        return;
+      }
+      let json: unknown;
+      try {
+        json = JSON.parse(text);
+      } catch {
+        throw new ValidationError({ message: "This socket accepts `ping` and JSON frames." });
+      }
+      const parsed = PresenceRoomClientFrame.safeParse(json);
+      if (!parsed.success) throw fromZodError(parsed.error, { message: "This socket accepts `set_activity`." });
+      const frame = parsed.data;
+      if (!declaresActivity(attachment, frame.activity)) {
+        throw new ValidationError({
+          message: `This room's activities are ${attachment.activities.join(", ")}.`,
+          params: { activity: frame.activity },
+        });
+      }
+      if (frame.activity === attachment.participant.activity) return;
+      const participant = { ...attachment.participant, activity: frame.activity };
+      ws.serializeAttachment({ ...attachment, participant } satisfies PresenceAttachment);
+      this.broadcast({ type: "activity", participantId: participant.id, activity: frame.activity }, ws);
+    } catch (error) {
+      if (!(error instanceof PithyError)) throw error;
+      try {
+        ws.send(render({ type: "error", error: clientError(error.payload) }));
+      } catch {
+        // Closing — nothing to answer.
+      }
+    }
+  }
+
+  override async webSocketClose(ws: WebSocket): Promise<void> {
+    this.leave(ws);
+  }
+
+  override async webSocketError(ws: WebSocket): Promise<void> {
+    this.leave(ws);
+  }
+
+  /** A socket leaves: everyone else hears it, and the ticket it spent stays spent. */
+  private leave(ws: WebSocket): void {
+    const closing = this.attachmentOf(ws);
+    if (closing) {
+      const nowSeconds = Math.floor(Date.now() / 1000);
+      const survivors = this.sockets().filter((other) => other !== ws);
+      const [carrier] = survivors;
+      const carried = carrier ? this.attachmentOf(carrier) : undefined;
+      if (carrier && carried) {
+        const spent = carrySpent(carried, closing, nowSeconds);
+        if (spent) carrier.serializeAttachment({ ...carried, spent } satisfies PresenceAttachment);
+      } else {
+        this.remembered = [...this.remembered, closing.ticket, ...closing.spent];
+        this.stayAwake(nowSeconds);
+      }
+      // Cleared before the broadcast, so a second close event for this socket cannot announce it twice.
+      ws.serializeAttachment(null);
+      this.broadcast({ type: "left", participantId: closing.participant.id }, ws);
+    }
+    try {
+      ws.close();
+    } catch {
+      // Already closing.
+    }
+  }
+
+  /**
+   * Hold the room awake until the last remembered ticket would expire, or let it sleep when there is none.
+   * The timer wakes once that has passed and lets go.
+   */
+  private stayAwake(nowSeconds: number): void {
+    this.remembered = this.remembered.filter((ticket) => ticket.exp > nowSeconds);
+    const until = Math.max(0, ...this.remembered.map((ticket) => ticket.exp));
+    if (this.awake && this.remembered.length > 0 && this.awake.until >= until) return;
+    if (this.awake) clearTimeout(this.awake.timer);
+    this.awake = null;
+    if (this.remembered.length === 0) return;
+    const timer = setTimeout(
+      () => {
+        this.awake = null;
+        this.stayAwake(Math.floor(Date.now() / 1000));
+      },
+      (until - nowSeconds + 1) * 1000,
+    );
+    this.awake = { until, timer };
+  }
+
+  /** Send a frame to every participant but one. One dead socket never blocks the rest. */
+  private broadcast(frame: PresenceRoomServerFrame, except: WebSocket): void {
+    const text = render(frame);
+    for (const ws of this.sockets()) {
+      if (ws === except || !this.attachmentOf(ws)) continue;
+      try {
+        ws.send(text);
+      } catch {
+        // A dead socket: its close event removes it.
+      }
+    }
+  }
+
+  /** The open sockets the runtime holds for this room. */
+  private sockets(): WebSocket[] {
+    return this.ctx.getWebSockets().filter((ws) => ws.readyState === WebSocket.OPEN);
+  }
+
+  /** The attachments of sockets the runtime still holds but that are no longer open. */
+  private leavingAttachments(): PresenceAttachment[] {
+    return this.ctx.getWebSockets().flatMap((ws) => {
+      if (ws.readyState === WebSocket.OPEN) return [];
+      const attachment = this.attachmentOf(ws);
+      return attachment ? [attachment] : [];
+    });
+  }
+
+  /** Every participant's attachment, read back from the runtime. */
+  private attachments(): PresenceAttachment[] {
+    return this.sockets().flatMap((ws) => {
+      const attachment = this.attachmentOf(ws);
+      return attachment ? [attachment] : [];
+    });
+  }
+
+  private attachmentOf(ws: WebSocket): PresenceAttachment | undefined {
+    const parsed = PresenceAttachment.safeParse(ws.deserializeAttachment());
+    return parsed.success ? parsed.data : undefined;
+  }
+
+  /** The admission the Worker forwarded. Missing or malformed is a request that did not come through the route. */
+  private admission(request: Request): PresenceAdmission {
+    const raw = request.headers.get(PRESENCE_ADMISSION_HEADER);
+    let json: unknown;
+    try {
+      json = raw === null ? null : JSON.parse(raw);
+    } catch {
+      json = null;
+    }
+    const parsed = PresenceAdmission.safeParse(json);
+    if (!parsed.success) throw new PresenceTicketInvalidError({ detail: "no admission on the forwarded upgrade" });
+    return parsed.data;
+  }
+}
+
+function render(frame: PresenceRoomServerFrame): string {
+  return JSON.stringify(frame);
+}