@pithy-sh/core 0.13.0 → 0.14.0

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);
+}

package/src/presence/frames.ts

@@ -0,0 +1,153 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { ErrorBody } from "../error/wire";
+import type { SocketVersions } from "../http/subprotocol";
+import { PresenceActivity } from "./names";
+
+/**
+ * **Every frame on a presence room socket, as the Zod schema it is sent and parsed with.**
+ *
+ * Pure: zod and core's leaf modules. A browser imports it to type the socket, and the AsyncAPI document
+ * reads the same schemas through the declaring capability's `sockets`, so the document and the Durable
+ * Object cannot disagree.
+ *
+ * **How a client reads a frame, stated once** (`docs/SOCKETS.md`). A field added to a frame later is
+ * optional. A client ignores a `type` and a key it does not know. A change no client could ignore is a new
+ * subprotocol, and the Worker keeps serving the one before it.
+ *
+ * **The keepalive is plain text**, the one exception to JSON: a client sends `ping`, the Worker answers
+ * `pong`. The only JSON frame a client sends is `set_activity`.
+ */
+
+/** The subprotocols a room serves. There is no unversioned room: a ticket can only arrive in the offer. */
+export const PRESENCE_ROOM_VERSIONS: SocketVersions = { current: "pithy.presence.v1", previous: null };
+
+/** Which door a participant came in by. */
+export const PresenceOrigin = z
+  .enum(["control-plane", "session"])
+  .describe(
+    "Which door the participant came in by: `control-plane`, a management client such as the dashboard, or `session`, a signed-in user of the app.",
+  );
+export type PresenceOrigin = z.infer<typeof PresenceOrigin>;
+
+/** Who a participant is, as the minting door states it. */
+export const PresenceParticipantRef = z
+  .string()
+  .min(1)
+  .max(128)
+  .describe(
+    "Who the participant is. A management client's own opaque reference, which it chose; or the signed-in user's id, which the Worker chose.",
+  );
+
+/** The longest participant name, in UTF-16 code units — what zod's `.max` counts. */
+export const PRESENCE_PARTICIPANT_NAME_MAX = 80;
+
+/** How the others see a participant. */
+export const PresenceParticipantName = z
+  .string()
+  .trim()
+  .min(1)
+  .max(PRESENCE_PARTICIPANT_NAME_MAX)
+  .describe("How the other participants see this one. A label, never an identity — `ref` and `origin` are that.");
+
+/** One participant in a room. */
+export const PresenceParticipant = z
+  .object({
+    id: z
+      .string()
+      .uuid()
+      .describe("This participant's id in the room — one per socket, so one person in two tabs is two participants."),
+    ref: PresenceParticipantRef,
+    name: PresenceParticipantName,
+    origin: PresenceOrigin,
+    activity: PresenceActivity.describe("What they are doing now, one of the room kind's declared activities."),
+    joinedAt: z.iso.datetime().describe("When this socket joined, ISO-8601."),
+  })
+  .describe("One participant in a presence room: one open socket.");
+export type PresenceParticipant = z.infer<typeof PresenceParticipant>;
+
+/** The first frame on every room socket. */
+export const PresenceRoomInitFrame = z
+  .object({
+    type: z.literal("init").describe("Always `init`."),
+    self: z.string().uuid().describe("This socket's own participant id, so a client can find itself in the list."),
+    participants: z
+      .array(PresenceParticipant)
+      .describe("Everyone in the room now, this socket included, in the order they joined."),
+  })
+  .describe("Who is in the room, sent once as soon as the socket opens.");
+export type PresenceRoomInitFrame = z.infer<typeof PresenceRoomInitFrame>;
+
+/** Someone joined. */
+export const PresenceJoinedFrame = z
+  .object({
+    type: z.literal("joined").describe("Always `joined`."),
+    participant: PresenceParticipant.describe("Who joined."),
+  })
+  .describe("Another participant joined the room.");
+export type PresenceJoinedFrame = z.infer<typeof PresenceJoinedFrame>;
+
+/** Someone left, or their socket dropped. */
+export const PresenceLeftFrame = z
+  .object({
+    type: z.literal("left").describe("Always `left`."),
+    participantId: z.string().uuid().describe("The participant who left."),
+  })
+  .describe("Another participant left the room, or their socket dropped.");
+export type PresenceLeftFrame = z.infer<typeof PresenceLeftFrame>;
+
+/** Someone changed what they are doing. */
+export const PresenceActivityFrame = z
+  .object({
+    type: z.literal("activity").describe("Always `activity`."),
+    participantId: z.string().uuid().describe("The participant whose activity changed."),
+    activity: PresenceActivity.describe("What they are doing now."),
+  })
+  .describe("Another participant announced a different activity.");
+export type PresenceActivityFrame = z.infer<typeof PresenceActivityFrame>;
+
+/** A frame the room could not accept. */
+export const PresenceRoomErrorFrame = z
+  .object({
+    type: z.literal("error").describe("Always `error`."),
+    error: ErrorBody.shape.error,
+  })
+  .describe(
+    "The room could not accept a frame — not one it reads, an activity the room kind does not declare, or past the size limit. The error is the one an HTTP response would carry.",
+  );
+export type PresenceRoomErrorFrame = z.infer<typeof PresenceRoomErrorFrame>;
+
+/** Every JSON frame the Worker sends on a room socket. `pong` is the plain-text exception. */
+export const PresenceRoomServerFrame = z
+  .discriminatedUnion("type", [
+    PresenceRoomInitFrame,
+    PresenceJoinedFrame,
+    PresenceLeftFrame,
+    PresenceActivityFrame,
+    PresenceRoomErrorFrame,
+  ])
+  .describe("A JSON frame the Worker sends on a presence room socket.");
+export type PresenceRoomServerFrame = z.infer<typeof PresenceRoomServerFrame>;
+
+/** Announce a different activity. */
+export const PresenceSetActivityFrame = z
+  .object({
+    type: z.literal("set_activity").describe("Always `set_activity`."),
+    activity: PresenceActivity.describe("What this participant is doing now. One of the room kind's declared values."),
+  })
+  .describe("Announce what this participant is doing now.");
+export type PresenceSetActivityFrame = z.infer<typeof PresenceSetActivityFrame>;
+
+/** Every JSON frame a client may send on a room socket. `ping` is the plain-text exception. */
+export const PresenceRoomClientFrame = z
+  .discriminatedUnion("type", [PresenceSetActivityFrame])
+  .describe("A JSON frame a client sends on a presence room socket.");
+export type PresenceRoomClientFrame = z.infer<typeof PresenceRoomClientFrame>;
+
+/** The keepalive a client sends, as plain text. */
+export const PresenceRoomPing = z.literal("ping").describe("The plain-text keepalive a client sends.");
+
+/** The Worker's answer to `ping`, as plain text. */
+export const PresenceRoomPong = z.literal("pong").describe("The plain-text answer to `ping`.");

package/src/presence/http/guard.ts

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MiddlewareHandler } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import { UnauthorizedError } from "../../error/pithyError";
+
+/**
+ * Require a signed-in user of the app, over the `AuthContext` seam. Kept here rather than imported from
+ * `@pithy-sh/auth`, which core may not depend on — and without auth composed `c.var.auth` is null, so the
+ * session ticket route denies rather than stands open.
+ */
+export function requireAuth(): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (!c.var.auth) {
+      throw new UnauthorizedError({
+        message: "Authentication required.",
+        action: "Sign in and retry with a valid session or bearer token.",
+      });
+    }
+    await next();
+  };
+}

package/src/presence/http/responses.ts

@@ -0,0 +1,63 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { ControlPlaneScope } from "../../controlPlane/scope/scope";
+import { PRESENCE_ROOM_VERSIONS } from "../frames";
+import { PresenceActivity, PresenceRecordId, PresenceRoomKindName } from "../names";
+
+/**
+ * A minted presence ticket and where to spend it. Both ticket routes answer it.
+ *
+ * Read across a version boundary like every response schema, so a field added here later is `.optional()`.
+ */
+export const PresenceTicket = z
+  .object({
+    ticket: z
+      .string()
+      .min(1)
+      .describe(
+        "The ticket. Offer it in `Sec-WebSocket-Protocol` as `pithy.ticket.<ticket>`, beside `protocol`. Single use.",
+      ),
+    expiresAt: z.iso.datetime().describe("When the ticket stops being honored, ISO-8601 — 60 seconds after minting."),
+    kind: PresenceRoomKindName.describe("The room kind the ticket admits to."),
+    recordId: PresenceRecordId.describe("The record the room is about."),
+    socketPath: z
+      .string()
+      .min(1)
+      .describe("The path to open the socket at, on this Worker — this room's, already filled in."),
+    protocol: z
+      .literal(PRESENCE_ROOM_VERSIONS.current)
+      .describe("The subprotocol to offer beside the ticket. The Worker answers with it."),
+  })
+  .describe("A single-use, 60-second ticket into one presence room, and where to open the socket with it.");
+export type PresenceTicket = z.infer<typeof PresenceTicket>;
+
+/**
+ * One room kind, as `GET /control-plane/manifest` reports it under the capability that declares it. Built
+ * from the capability's resolved `basePath`, so a client never assumes where a socket is.
+ */
+export const PresenceRoomDescriptor = z
+  .object({
+    kind: PresenceRoomKindName.describe("The room kind — `support.thread`."),
+    scope: ControlPlaneScope.describe(
+      "The scope that reads the record, and so joins its room. A management client mints its ticket with exactly this scope.",
+    ),
+    activities: z
+      .array(PresenceActivity)
+      .min(1)
+      .describe("What a participant may announce. The first is what everyone starts as."),
+    maxParticipants: z.number().int().positive().describe("How many participants the room admits at once."),
+    sessionTicketPath: z
+      .string()
+      .nullable()
+      .describe(
+        "Where a signed-in user of the app mints a ticket for this kind, or null when the kind admits management clients only.",
+      ),
+    socketPath: z
+      .string()
+      .min(1)
+      .describe("The socket route, with `:kind` and `:recordId` to fill in — the path as the Worker mounted it."),
+  })
+  .describe("One presence room kind this capability serves, and how to join one of its rooms.");
+export type PresenceRoomDescriptor = z.infer<typeof PresenceRoomDescriptor>;