statewire 0.14.0 → 0.15.0

package/src/host/host.ts

@@ -136,6 +136,7 @@ export type CommandsHost = {
   submit?: (call: CommandsSubmission) => Promise<unknown>;
   /** Registered command names, read live. */
   methods?: () => string[];
+  abort?: () => void;
 };
 
 const commandsHosts = new WeakMap<object, CommandsHost>();
@@ -158,12 +159,15 @@ type QueuedCall = {
 
 type ActiveInvocation = CommandsInvocation & {
   applied: boolean;
+  controller: AbortController;
+  settled: boolean;
   origin?: CommandsSubmission;
 };
 
 type CommandsCell = {
   handlers: Record<string, (...args: never[]) => unknown> | null;
   queue: QueuedCall[];
+  active: Map<ActiveInvocation, QueuedCall>;
   running: boolean;
   listener: CommandsListener | null;
   seq: number;
@@ -178,6 +182,7 @@ const LOCAL_CALLER: StatewireHost.Caller = Object.freeze({
   get clientId(): string {
     throw new Error("statewire: in-process dispatch has no client id");
   },
+  auth: undefined,
   context: null,
   isConnected: true,
 });
@@ -202,6 +207,7 @@ const applyInvocation = (cell: CommandsCell, inv: ActiveInvocation) => {
   if (inv.applied) return;
   inv.applied = true;
   cell.listener?.onApplied(inv);
+  cell.listener?.onCovered?.(inv);
   inv.origin?.onApplied?.();
 };
 
@@ -211,6 +217,9 @@ const settleInvocation = (
   call: QueuedCall,
   settled: Settled,
 ) => {
+  if (inv.settled) return;
+  inv.settled = true;
+  cell.active.delete(inv);
   applyInvocation(cell, inv);
   if (settled.type === "resolved") {
     const outcome: CommandsOutcome =
@@ -229,13 +238,40 @@ const settleInvocation = (
   }
 };
 
+const abortInvocations = (cell: CommandsCell) => {
+  for (const [inv, call] of cell.active) {
+    inv.settled = true;
+    inv.controller.abort();
+    const error = new StatewireSendError({ fate: "crashed", cause: "server" });
+    const outcome: CommandsOutcome = { type: "rejected", error };
+    cell.listener?.onSettle(inv, outcome);
+    inv.origin?.onSettle?.(outcome);
+    call.reject(error);
+  }
+  cell.active.clear();
+};
+
 const isThenable = (value: unknown): value is PromiseLike<unknown> =>
   typeof value === "object" &&
   value !== null &&
   typeof (value as { then?: unknown }).then === "function";
 
+// A command is an own, enumerable, function-valued property — exactly what
+// `Object.keys` shows, so dispatch, `statewire/commands`, and the reserved-
+// namespace guard share one view; prototype-chain names are not commands.
+const handlerOf = (
+  handlers: Record<string, (...args: never[]) => unknown>,
+  method: string,
+): ((...args: never[]) => unknown) | undefined => {
+  if (!Object.prototype.propertyIsEnumerable.call(handlers, method)) {
+    return undefined;
+  }
+  const handler = handlers[method];
+  return typeof handler === "function" ? handler : undefined;
+};
+
 const dispatch = (cell: CommandsCell, call: QueuedCall) => {
-  const handler = cell.handlers![call.method];
+  const handler = handlerOf(cell.handlers!, call.method);
   if (handler === undefined) {
     const error = new StatewireSendError({
       fate: "rejected",
@@ -252,17 +288,22 @@ const dispatch = (cell: CommandsCell, call: QueuedCall) => {
     ts: call.ts,
     seq: ++cell.seq,
     applied: false,
+    controller: new AbortController(),
+    settled: false,
     ...(call.origin !== undefined && { origin: call.origin }),
     ...(call.origin?.clientId !== undefined && {
       clientId: call.origin.clientId,
     }),
   };
+  cell.active.set(inv, call);
   cell.listener?.onStart(inv);
   cell.listener?.onPosted?.(inv);
-  cell.listener?.onCovered?.(inv);
   const ctx: StatewireHost.Ctx = {
     caller: call.origin?.caller ?? LOCAL_CALLER,
-    applied: () => applyInvocation(cell, inv),
+    signal: inv.controller.signal,
+    applied: () => {
+      if (!inv.settled) applyInvocation(cell, inv);
+    },
   };
   try {
     const value = (
@@ -332,6 +373,7 @@ export const useStatewireCommands = <THandlers extends Statewire.Commands>(
     const cell: CommandsCell = {
       handlers: null,
       queue: [],
+      active: new Map(),
       running: false,
       listener: null,
       seq: 0,
@@ -358,10 +400,17 @@ export const useStatewireCommands = <THandlers extends Statewire.Commands>(
         }),
     );
     commandsHosts.set(proxy, {
+      abort: () => abortInvocations(cell),
       setListener: (listener) => {
         cell.listener = listener;
       },
-      methods: () => (cell.handlers ? Object.keys(cell.handlers) : []),
+      methods: () => {
+        const handlers = cell.handlers;
+        if (!handlers) return [];
+        return Object.keys(handlers).filter(
+          (method) => handlerOf(handlers, method) !== undefined,
+        );
+      },
       submit: (origin) =>
         new Promise((resolve, reject) => {
           if (cell.unmounted) {
@@ -394,6 +443,7 @@ export const useStatewireCommands = <THandlers extends Statewire.Commands>(
       }
       queueMicrotask(() => {
         if (!cell.unmounted) return;
+        abortInvocations(cell);
         const queued = cell.queue;
         cell.queue = [];
         for (const call of queued) {

package/src/host/http.ts

@@ -1,7 +1,11 @@
 import type { StatewireHost } from "../host";
 import {
   CLIENT_ID_RE,
+  PRINCIPAL_MISMATCH_MESSAGE,
+  SUBSCRIBER_LIMIT_MESSAGE,
   admitFrame,
+  atSubscriberLimit,
+  authEquals,
   closeConn,
   flush,
   parseFrame,
@@ -10,14 +14,17 @@ import {
   sendTo,
 } from "./socket";
 import type { ParsedFrame, Registration, SocketHostState } from "./socket";
+import { MAX_FRAME_BODY_BYTES } from "../wire/limits";
+import { PROTOCOL_VERSION, VERSION_HEADER } from "../wire/version";
+
+export { MAX_FRAME_BODY_BYTES } from "../wire/limits";
 
 const CLIENT_ID_HEADER = "Statewire-Client-Id";
 const LEASE_HEADER = "Statewire-Lease";
-const VERSION_HEADER = "Statewire-Version";
-const VERSION = "1";
 const encoder = new TextEncoder();
-export const MAX_FRAME_BODY_BYTES = 8 * 1024 * 1024;
-
+const laggardFin = encoder.encode(
+  'data: {"fin":{"reason":"reconnect","code":"client-fell-behind"}}\n\n',
+);
 const readFrameBody = async (request: Request): Promise<string | null> => {
   const declared = request.headers.get("content-length");
   if (declared !== null && Number(declared) > MAX_FRAME_BODY_BYTES) {
@@ -83,30 +90,37 @@ const clientIdResponse = (
 const headersOf = (request: Request): Record<string, string> =>
   Object.fromEntries(request.headers);
 
-const mergedHeaders = (
-  request: Request,
-  extra: Record<string, string>,
-): Record<string, string> => {
-  const headers = headersOf(request);
-  for (const [name, value] of Object.entries(extra)) {
-    headers[name.toLowerCase()] = value;
-  }
-  return headers;
-};
-
 const authorize = async (
   h: SocketHostState,
   headers: Record<string, string>,
-): Promise<Response | null> => {
+): Promise<{ auth: unknown } | { refused: Response }> => {
   try {
-    await h.authorize?.({ headers });
-    return null;
+    return { auth: await h.authorize?.({ headers }) };
   } catch (error) {
-    if (error instanceof Response) return error;
+    if (error instanceof Response) return { refused: error };
     throw error;
   }
 };
 
+const subscriberLimitResponse = (): Response =>
+  Response.json({ detail: SUBSCRIBER_LIMIT_MESSAGE }, { status: 503 });
+
+// No awaits between this check and register: the binding cannot race.
+const principalMismatchResponse = (
+  h: SocketHostState,
+  clientId: string,
+  auth: unknown,
+): Response | null => {
+  const rec = h.clients.get(clientId);
+  if (rec !== undefined && !authEquals(rec.principal, auth)) {
+    return Response.json(
+      { detail: PRINCIPAL_MISMATCH_MESSAGE },
+      { status: 403 },
+    );
+  }
+  return null;
+};
+
 const mintLease = (): string => {
   const bytes = crypto.getRandomValues(new Uint8Array(16));
   return btoa(String.fromCharCode(...bytes))
@@ -118,24 +132,48 @@ const mintLease = (): string => {
 type SseAttachment = {
   body: ReadableStream<Uint8Array>;
   registration: Registration | null;
+  activateBackpressure: () => void;
 };
 
-const attachSse = (h: SocketHostState, clientId: string): SseAttachment => {
+const attachSse = (
+  h: SocketHostState,
+  clientId: string,
+  auth: unknown,
+): SseAttachment => {
   let controller: ReadableStreamDefaultController<Uint8Array>;
   let connection: Registration["connection"] | null = null;
   let open = true;
-  const body = new ReadableStream({
-    start: (next) => {
-      controller = next;
-    },
-    cancel: () => {
-      open = false;
-      connection?.close();
+  let backpressureActive = false;
+  const body = new ReadableStream(
+    {
+      start: (next) => {
+        controller = next;
+      },
+      cancel: () => {
+        open = false;
+        connection?.close();
+      },
     },
-  });
+    { highWaterMark: h.streamQueueSize },
+  );
   const socket = {
     send: (data: string) => {
       if (!open) return;
+      if (
+        backpressureActive &&
+        controller.desiredSize !== null &&
+        controller.desiredSize <= 0
+      ) {
+        open = false;
+        try {
+          controller.enqueue(laggardFin);
+          controller.close();
+        } catch {
+          /* stream already gone */
+        }
+        connection?.close();
+        return;
+      }
       const frame = data === "{}" ? ": ping\n\n" : `data: ${data}\n\n`;
       try {
         controller.enqueue(encoder.encode(frame));
@@ -154,24 +192,32 @@ const attachSse = (h: SocketHostState, clientId: string): SseAttachment => {
       }
     },
   };
-  const registration = register(h, clientId, socket);
+  const registration = register(h, clientId, socket, false, auth);
   connection = registration?.connection ?? null;
   if (!open) connection?.close();
-  return { body, registration };
+  return {
+    body,
+    registration,
+    activateBackpressure: () => {
+      backpressureActive = true;
+    },
+  };
 };
 
 const streamResponse = (
   attachment: SseAttachment,
   lease: string | null,
-): Response =>
-  new Response(attachment.body, {
+): Response => {
+  attachment.activateBackpressure();
+  return new Response(attachment.body, {
     status: 200,
     headers: {
       "Content-Type": "text/event-stream",
-      [VERSION_HEADER]: VERSION,
+      [VERSION_HEADER]: PROTOCOL_VERSION,
       ...(lease !== null && { [LEASE_HEADER]: lease }),
     },
   });
+};
 
 const admitAttachFrame = (
   h: SocketHostState,
@@ -179,7 +225,12 @@ const admitAttachFrame = (
   frame: ParsedFrame,
 ) => {
   if (frame.ctx.length === 0 && frame.cmd.length === 0) return;
-  const admission = admitFrame(h, registration.rec, frame);
+  const admission = admitFrame(
+    h,
+    registration.rec,
+    frame,
+    registration.conn.auth,
+  );
   if (admission.type === "refused") {
     sendTo(h, registration.conn, JSON.stringify(admission.syn));
   }
@@ -189,11 +240,18 @@ const getStream = async (
   h: SocketHostState,
   request: Request,
 ): Promise<Response> => {
-  const refused = await authorize(h, headersOf(request));
-  if (refused !== null) return refused;
+  const authorized = await authorize(h, headersOf(request));
+  if ("refused" in authorized) return authorized.refused;
   const client = clientIdResponse(request);
   if ("response" in client) return client.response;
-  const attachment = attachSse(h, client.clientId);
+  const mismatch = principalMismatchResponse(
+    h,
+    client.clientId,
+    authorized.auth,
+  );
+  if (mismatch !== null) return mismatch;
+  if (atSubscriberLimit(h)) return subscriberLimitResponse();
+  const attachment = attachSse(h, client.clientId, authorized.auth);
   const lease = attachment.registration === null ? null : mintLease();
   if (attachment.registration !== null)
     attachment.registration.conn.lease = lease;
@@ -212,28 +270,32 @@ const postStream = async (
   }
   let body: unknown;
   try {
-    body = JSON.parse(raw);
+    body = raw.trim() ? JSON.parse(raw) : null;
   } catch {
     return Response.json({ detail: "body must be JSON" }, { status: 400 });
   }
   let frame: ParsedFrame;
   try {
-    frame = parseFrameValue(body, true);
+    frame =
+      body === null && !raw.trim()
+        ? { ctx: [], cmd: [] }
+        : parseFrameValue(body);
   } catch (error) {
     if (!(error instanceof Error) || error.name !== "StatewireViolation") {
       throw error;
     }
     return Response.json({ detail: error.message }, { status: 400 });
   }
-  if (frame.headers === null) {
-    return Response.json(
-      { detail: "first frame must carry headers" },
-      { status: 400 },
-    );
-  }
-  const refused = await authorize(h, mergedHeaders(request, frame.headers));
-  if (refused !== null) return refused;
-  const attachment = attachSse(h, client.clientId);
+  const authorized = await authorize(h, headersOf(request));
+  if ("refused" in authorized) return authorized.refused;
+  const mismatch = principalMismatchResponse(
+    h,
+    client.clientId,
+    authorized.auth,
+  );
+  if (mismatch !== null) return mismatch;
+  if (atSubscriberLimit(h)) return subscriberLimitResponse();
+  const attachment = attachSse(h, client.clientId, authorized.auth);
   if (attachment.registration === null) return streamResponse(attachment, null);
   const lease = mintLease();
   attachment.registration.conn.lease = lease;
@@ -272,8 +334,8 @@ const violationResponse = (
   reason: string,
 ) => {
   finClient(h, clientId, {
-    reason: "error",
-    message: `protocol violation: ${reason}`,
+    reason: "protocol-error",
+    message: reason,
   });
   return Response.json({ error: reason }, { status: 400 });
 };
@@ -282,38 +344,42 @@ export const frames = async (
   h: SocketHostState,
   request: Request,
 ): Promise<Response> => {
-  const refused = await authorize(h, headersOf(request));
-  if (refused !== null) return refused;
-  const client = clientIdResponse(request);
-  if ("response" in client) return client.response;
-  const rec = h.clients.get(client.clientId);
   const lease = request.headers.get(LEASE_HEADER);
   // A lease lives and dies with its attach: any live attach of the id accepts.
-  const live =
-    lease !== null &&
-    [...h.conns].some(
-      (conn) =>
-        conn.open && conn.clientId === client.clientId && conn.lease === lease,
-    );
-  if (h.disposed || h.finished !== null || rec === undefined || !live) {
+  const leased =
+    lease === null
+      ? undefined
+      : [...h.conns].find((conn) => conn.open && conn.lease === lease);
+  if (h.disposed || h.finished !== null || leased === undefined) {
     return Response.json({ error: "stale-lease" }, { status: 423 });
   }
+  const clientId = leased.clientId;
+  const rec = h.clients.get(clientId)!;
   const raw = await readFrameBody(request);
   if (raw === null) {
     return Response.json({ error: "frame body too large" }, { status: 413 });
   }
   let frame: ParsedFrame;
   try {
-    frame = parseFrame(raw, false);
+    frame = parseFrame(raw);
   } catch (error) {
     if (!(error instanceof Error) || error.name !== "StatewireViolation") {
       throw error;
     }
-    return violationResponse(h, client.clientId, error.message);
+    return violationResponse(h, clientId, error.message);
+  }
+  if (!leased.open || h.disposed || h.finished !== null) {
+    return Response.json({ error: "stale-lease" }, { status: 423 });
   }
-  const admission = admitFrame(h, rec, frame);
+  const admission = admitFrame(h, rec, frame, leased.auth);
   if (admission.type === "refused") {
-    return Response.json(admission.syn, { status: 409 });
+    const retry = admission.syn.syn.retry;
+    return Response.json(admission.syn, {
+      status: retry === undefined ? 409 : 429,
+      ...(retry !== undefined && {
+        headers: { "Retry-After": String(Math.ceil(retry / 1000)) },
+      }),
+    });
   }
   return Response.json({});
 };