@procedures/client 0.7.0 → 0.8.1

package/src/adapters/websocket/server/transport.ts

@@ -3,9 +3,16 @@
  *
  * Adapts WebSocket connections to unified RPC format.
  * Supports bidirectional streaming and persistent connections.
+ *
+ * The transport runs the `WebSocketServer` of `ws` in its "no server" mode (CLI-3). `upgrade()`
+ * takes the upgrade requests of its path. With the option `server`, the transport attaches
+ * `upgrade()` to that server through one router for each server, so two endpoints of different
+ * paths can share a server. Without it, the owner of the listener gives the upgrades to
+ * `upgrade()`, or mounts `upgradeHandler()` of `@procedures/client/node`.
  */
 
 import type { IncomingMessage } from "http";
+import type { Duplex } from "stream";
 import { WebSocketServer, WebSocket } from "ws";
 import type { ServerTransport, ServerRequest } from "../../../server/types.js";
 import type { Message, ResponseItem, Transport } from "../../../client/types.js";
@@ -19,9 +26,11 @@ import type {
   ConnectionEventHandler,
 } from "./types.js";
 import { withoutInternalKeys } from "../../metadata.js";
-import { checkBrowserRequest, type BrowserGuardOptions } from "../../../server/browser-guard.js";
+import { assertNamedOrigins, checkBrowserRequest, needsNamedOrigin, type BrowserGuardOptions } from "../../../server/browser-guard.js";
 import { optionalMs } from "../../../duration.js";
-import { credentialsOf, withoutSecretHeaders } from "../../../server/request-auth.js";
+import { headerNames, requestCredentials, urlParts, withoutSecretHeaders } from "../../../server/request-auth.js";
+import { attachUpgradeTarget, refuseUpgrade } from "./upgrade-router.js";
+import { realClock, type Cancel } from "../../../clock.js";
 import { PROTOCOL_VERSION, protocolVersionOf } from "../../../protocol.js";
 import { TIMER_DEFAULTS } from "../../../timers.js";
 import {
@@ -64,11 +73,25 @@ export class WebSocketServerTransport implements ServerTransport {
 
   private wss: WebSocketServer | null = null;
   private options: Required<
-    Omit<WebSocketServerTransportOptions, "authenticate" | "onConnection" | "allowedOrigins" | "allowedHosts" | "heartbeat" | "reverseRequestTimeout">
+    Omit<
+      WebSocketServerTransportOptions,
+      "server" | "authenticate" | "onConnection" | "allowedOrigins" | "allowedHosts" | "heartbeat" | "reverseRequestTimeout" | "secretHeaders"
+    >
   > & {
+    server: WebSocketServerTransportOptions["server"];
     authenticate?: WebSocketServerTransportOptions["authenticate"];
     onConnection?: WebSocketServerTransportOptions["onConnection"];
   };
+  /** The more headers that carry a secret (CLI-2a) */
+  private readonly secretHeaders: ReadonlySet<string>;
+  /** The function that detaches `upgrade()` from the `server` of the options */
+  private detach: (() => void) | undefined;
+  /** True after `stopIntake()`: a new upgrade gets 503, and a new call gets `UNAVAILABLE` */
+  private intakeStopped = false;
+  /** The functions that `drain()` waits on: each one runs when no call is in flight */
+  private idleWaiters: Array<() => void> = [];
+  /** True: a cookie of an upgrade is trusted only from a named origin, with or without an auth path */
+  private cookiesNamed = false;
   private server: RequestHandler;
   private connections: Set<WebSocket> = new Set();
 
@@ -90,6 +113,12 @@ export class WebSocketServerTransport implements ServerTransport {
    */
   private readonly channels = new Map<string, { incoming: IncomingCalls; outgoing: OutgoingCalls }>();
 
+  /**
+   * The transport of the remote events of each connection: one object for each connection, so the
+   * subscriptions of one connection to the same topics share one call (EVENTS.md).
+   */
+  private readonly eventTransports = new Map<string, Transport>();
+
   /** The browser checks of each connection (see `server/browser-guard.ts`) */
   private readonly guard: BrowserGuardOptions;
 
@@ -97,7 +126,7 @@ export class WebSocketServerTransport implements ServerTransport {
   private connectHandlers: ConnectionEventHandler[] = [];
   private disconnectHandlers: ConnectionEventHandler[] = [];
 
-  constructor(server: RequestHandler, options: WebSocketServerTransportOptions) {
+  constructor(server: RequestHandler, options: WebSocketServerTransportOptions = {}) {
     this.server = server;
     this.options = {
       server: options.server,
@@ -110,6 +139,9 @@ export class WebSocketServerTransport implements ServerTransport {
       highWaterMark: options.highWaterMark ?? 1024 * 1024,
     };
     this.guard = { allowedOrigins: options.allowedOrigins, allowedHosts: options.allowedHosts };
+    // CSRF: a server that reads the cookies of each request needs named origins (CLI-2a)
+    assertNamedOrigins("WebSocketServerTransport", server.ambientCredentials, options.allowedOrigins, "allowedOrigins");
+    this.secretHeaders = headerNames(options.secretHeaders);
     this.reverseRequestTimeoutMs = optionalMs(options.reverseRequestTimeout, "reverseRequestTimeout") ?? TIMER_DEFAULTS.webSocketServer.reverseRequestTimeoutMs;
     this.heartbeat =
       options.heartbeat === false
@@ -143,9 +175,21 @@ export class WebSocketServerTransport implements ServerTransport {
   }
 
   async start(): Promise<void> {
-    // Create WebSocket server
+    this.open();
+  }
+
+  /**
+   * This method creates the WebSocket server at once, and attaches it to the `server` of the
+   * options. `start()` calls it, and `upgradeHandler()` too. A second call does nothing.
+   *
+   * @internal
+   */
+  open(): void {
+    this.intakeStopped = false;
+    if (this.wss) return;
+    // The "no server" mode: upgrade() takes the upgrades of the path, and leaves the others alone
     this.wss = new WebSocketServer({
-      server: this.options.server,
+      noServer: true,
       path: this.options.path,
       perMessageDeflate: this.options.perMessageDeflate,
       maxPayload: this.options.maxPayload,
@@ -157,7 +201,11 @@ export class WebSocketServerTransport implements ServerTransport {
         { req }: { req: IncomingMessage },
         callback: (result: boolean, code?: number, message?: string) => void
       ) => {
-        const guard = checkBrowserRequest(req, this.guard);
+        // The cookies of an upgrade are trusted only from a named origin, when the server or the
+        // authenticate handler can read them (cross-site WebSocket hijacking with cookies)
+        const readsCookies = this.cookiesNamed || this.options.authenticate !== undefined;
+        const ambient = needsNamedOrigin(this.server.ambientCredentials, req.headers, readsCookies);
+        const guard = checkBrowserRequest(req, this.guard, false, ambient);
         if (!guard.ok) {
           callback(false, guard.status, guard.message);
           return;
@@ -179,6 +227,7 @@ export class WebSocketServerTransport implements ServerTransport {
     this.wss.on("connection", (ws: WebSocket, req: IncomingMessage) => {
       this.handleConnection(ws, req);
     });
+    if (this.options.server) this.detach = attachUpgradeTarget(this.options.server, this);
 
     if (this.heartbeat) {
       this.heartbeatTimer = setInterval(() => this.beat(), this.heartbeat.interval);
@@ -194,6 +243,8 @@ export class WebSocketServerTransport implements ServerTransport {
       clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = undefined;
     }
+    this.detach?.();
+    this.detach = undefined;
     if (this.wss) {
       // Stop the requests in progress, so their handlers end (deep dive TRN-15), and fail the
       // calls that the server sent to its clients
@@ -202,6 +253,7 @@ export class WebSocketServerTransport implements ServerTransport {
         channel.outgoing.failAll("Server stopped");
       }
       this.channels.clear();
+      this.callSettled();
 
       // Close all connections
       for (const ws of this.connections) {
@@ -228,6 +280,93 @@ export class WebSocketServerTransport implements ServerTransport {
     return this.wss !== null;
   }
 
+  /**
+   * This method makes the transport trust a cookie of an upgrade only from a named origin, also
+   * without an auth path that reads it. `upgradeHandler()` calls it.
+   *
+   * @internal
+   */
+  nameOriginsForCookies(): void {
+    this.cookiesNamed = true;
+  }
+
+  /** The path of the WebSocket endpoint. */
+  get path(): string {
+    return this.options.path;
+  }
+
+  /** This method gives true when an upgrade request is for the path of this endpoint. */
+  matches(req: IncomingMessage): boolean {
+    return urlParts(req.url).path === this.options.path;
+  }
+
+  /**
+   * This method takes an upgrade request of its path and gives true. The browser checks, the
+   * `authenticate` handler and the handshake of `ws` follow. It gives false for another path, or
+   * before `start()`, and does not touch the socket. After `stopIntake()`, it refuses the upgrade
+   * with 503.
+   */
+  upgrade(req: IncomingMessage, socket: Duplex, head: Buffer): boolean {
+    const wss = this.wss;
+    if (!wss || !this.matches(req)) return false;
+    if (this.intakeStopped) {
+      refuseUpgrade(socket, 503, "The server is stopping");
+      return true;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => wss.emit("connection", ws, req));
+    return true;
+  }
+
+  /**
+   * This method stops the intake: a new upgrade gets 503, and a new call on an open connection gets
+   * the retryable error `UNAVAILABLE`. The calls in flight go on. `start()` accepts again.
+   */
+  stopIntake(): void {
+    this.intakeStopped = true;
+  }
+
+  /** The number of the calls in flight on all connections, open streams too. */
+  inFlight(): number {
+    let count = 0;
+    for (const channel of this.channels.values()) count += channel.incoming.size;
+    return count;
+  }
+
+  /**
+   * This method waits until no call is in flight, until the `deadline` (milliseconds on the
+   * monotonic clock of `performance.now()`), or until the signal aborts.
+   */
+  drain(deadline: number, signal?: AbortSignal): Promise<void> {
+    if (this.inFlight() === 0 || signal?.aborted) return Promise.resolve();
+    return new Promise<void>((resolve) => {
+      let timer: Cancel | undefined;
+      const done = (): void => {
+        timer?.();
+        signal?.removeEventListener("abort", done);
+        const index = this.idleWaiters.indexOf(done);
+        if (index >= 0) this.idleWaiters.splice(index, 1);
+        resolve();
+      };
+      this.idleWaiters.push(done);
+      signal?.addEventListener("abort", done, { once: true });
+      timer = realClock.after(Math.max(0, deadline - realClock.now()), done);
+      timer.unref?.();
+    });
+  }
+
+  /** This method stops the transport: the same as `stop()`. */
+  close(): Promise<void> {
+    return this.stop();
+  }
+
+  /** A call ended: a drain can end when no call is in flight. */
+  private callSettled(): void {
+    if (this.idleWaiters.length === 0 || this.inFlight() > 0) return;
+    const waiters = this.idleWaiters;
+    this.idleWaiters = [];
+    for (const waiter of waiters) waiter();
+  }
+
   /**
    * Handle new WebSocket connection.
    */
@@ -243,10 +382,13 @@ export class WebSocketServerTransport implements ServerTransport {
       connectedAt: new Date(),
       metadata: {
         remoteAddress: req.socket.remoteAddress,
-        headers: withoutSecretHeaders(req.headers as Record<string, unknown>),
+        headers: withoutSecretHeaders(req.headers as Record<string, unknown>, this.secretHeaders),
       },
     };
     this.trackedConnections.set(connectionId, trackedConnection);
+    // The credentials of the upgrade, for each call of the connection: the bearer token of its
+    // Authorization header or of its token query, its cookies, its headers and its query (CLI-2a)
+    const credentials = requestCredentials({ headers: req.headers as Record<string, unknown>, url: req.url }, { tokenQuery: "token" });
 
     // The calls of this connection in the two directions (roadmap R24)
     const isOpen = (): boolean => ws.readyState === WebSocket.OPEN;
@@ -257,7 +399,8 @@ export class WebSocketServerTransport implements ServerTransport {
         send,
         sendWithBackpressure: (frame, signal) => this.sendWithBackpressure(ws, frame, signal),
         isOpen,
-        requestOf: (frame, signal) => this.requestOf(frame, req, connectionId, signal),
+        requestOf: (frame, signal) => this.requestOf(frame, req, connectionId, signal, credentials),
+        onSettled: () => this.callSettled(),
       }),
       outgoing: new OutgoingCalls({
         send,
@@ -303,6 +446,8 @@ export class WebSocketServerTransport implements ServerTransport {
       channel?.incoming.abortAll();
       channel?.outgoing.failAll("WebSocket connection closed");
       this.channels.delete(connectionId);
+      this.callSettled();
+      this.eventTransports.delete(connectionId);
       const conn = this.trackedConnections.get(connectionId);
       if (conn) {
         this.trackedConnections.delete(connectionId);
@@ -329,7 +474,13 @@ export class WebSocketServerTransport implements ServerTransport {
    * The server request of a `request` frame of a connection: the metadata of the frame and of the
    * connection, the signal of the call, and the credentials of the upgrade (roadmap R18).
    */
-  private requestOf(frame: WebSocketMessage, req: IncomingMessage, connectionId: string, signal: AbortSignal): ServerRequest {
+  private requestOf(
+    frame: WebSocketMessage,
+    req: IncomingMessage,
+    connectionId: string,
+    signal: AbortSignal,
+    credentials: ServerRequest["credentials"]
+  ): ServerRequest {
     return {
       id: frame.id,
       method: frame.method!,
@@ -341,11 +492,12 @@ export class WebSocketServerTransport implements ServerTransport {
         connectionId,
         remoteAddress: req.socket.remoteAddress,
         // The upgrade headers without their secrets (roadmap R18)
-        headers: withoutSecretHeaders(req.headers as Record<string, unknown>),
+        headers: withoutSecretHeaders(req.headers as Record<string, unknown>, this.secretHeaders),
       },
       signal,
-      // The credentials of the connection: the bearer token of its upgrade (R18)
-      credentials: credentialsOf(req),
+      // The credentials of the connection: the bearer token of its upgrade (R18), its cookies,
+      // its headers and its query (CLI-2a)
+      credentials,
     };
   }
 
@@ -394,6 +546,11 @@ export class WebSocketServerTransport implements ServerTransport {
     if (!channel) return;
     // A frame of a call that the server sent to this client (roadmap R24)
     if (channel.outgoing.receive(message)) return;
+    // After stopIntake(), a new call goes to another server or comes again later
+    if (this.intakeStopped && message.type === "request") {
+      this.sendError(ws, message.id || "unknown", "The server is stopping", "UNAVAILABLE", true);
+      return;
+    }
     // A frame of a call of the client: a request, a cancel or a credit
     if (channel.incoming.receive(message)) return;
     // A server-response frame of an older client, for a call that no longer exists
@@ -429,7 +586,7 @@ export class WebSocketServerTransport implements ServerTransport {
   /**
    * Send error to client.
    */
-  private sendError(ws: WebSocket, id: string, message: string, code = "INTERNAL_ERROR"): void {
+  private sendError(ws: WebSocket, id: string, message: string, code = "INTERNAL_ERROR", retryable = false): void {
     const errorMessage: WebSocketMessage = {
       id,
       type: "error",
@@ -437,12 +594,12 @@ export class WebSocketServerTransport implements ServerTransport {
         type: "error",
         code,
         message,
-        retryable: false,
+        retryable,
       },
       error: {
         code,
         message,
-        retryable: false,
+        retryable,
       },
     };
 
@@ -552,7 +709,7 @@ export class WebSocketServerTransport implements ServerTransport {
     handler: RemoteEventHandler<T>,
     options: SubscribeOptions = {},
   ): Subscription {
-    return subscribeRemote<T>(this.transportFor(connectionId), topics, handler, options, { resubscribe: false });
+    return subscribeRemote<T>(this.eventTransportFor(connectionId), topics, handler, options, { resubscribe: false });
   }
 
   /**
@@ -564,7 +721,21 @@ export class WebSocketServerTransport implements ServerTransport {
    * @param options - A signal, `onSubscribed`, the metadata of the call
    */
   events<T = unknown>(connectionId: string, topics: string | readonly string[], options: RemoteEventsOptions = {}): AsyncIterable<RemoteEvent<T>> {
-    return remoteEvents<T>(this.transportFor(connectionId), topics, options, { resubscribe: false });
+    return remoteEvents<T>(this.eventTransportFor(connectionId), topics, options, { resubscribe: false });
+  }
+
+  /**
+   * The transport of the remote events of a connection: the same object for each subscription of
+   * a tracked connection. The close of the connection removes it.
+   */
+  private eventTransportFor(connectionId: string): Transport {
+    if (!this.trackedConnections.has(connectionId)) return this.transportFor(connectionId);
+    let transport = this.eventTransports.get(connectionId);
+    if (!transport) {
+      transport = this.transportFor(connectionId);
+      this.eventTransports.set(connectionId, transport);
+    }
+    return transport;
   }
 
   /**

package/src/adapters/websocket/server/types.ts

@@ -29,10 +29,11 @@ export type WebSocketConnectionHandler = (ws: WebSocket, req: IncomingMessage) =
  */
 export interface WebSocketServerTransportOptions extends Omit<BrowserGuardOptions, "allowGet"> {
   /**
-   * HTTP server to attach WebSocket server to.
-   * Required - WebSocket upgrades HTTP connections.
+   * The HTTP server whose upgrade requests the transport takes. The transport takes only the
+   * upgrades of its path, so several endpoints can share one server. Without it, the owner of the
+   * listener gives each upgrade to `upgrade()`, or mounts `upgradeHandler()`.
    */
-  server: HttpServer;
+  server?: HttpServer | undefined;
 
   /**
    * Path for WebSocket connections.
@@ -91,6 +92,13 @@ export interface WebSocketServerTransportOptions extends Omit<BrowserGuardOption
    * @default seconds(30)
    */
   reverseRequestTimeout?: Duration;
+
+  /**
+   * More headers that carry a secret, for example the token header of an application. They go
+   * into the credentials of each call, not into its metadata. `Authorization`,
+   * `Proxy-Authorization`, `Cookie` and `X-Api-Key` are always secret.
+   */
+  secretHeaders?: readonly string[] | undefined;
 }
 
 /**

package/src/adapters/websocket/server/upgrade-router.ts

@@ -0,0 +1,77 @@
+/**
+ * The router of the upgrade requests of one `node:http` server (CLI-3).
+ *
+ * Before, each `WebSocketServerTransport` attached its own `WebSocketServer` of `ws` to the server.
+ * Such a server refuses each upgrade of another path with 400, so a second endpoint on the same
+ * server did not get its upgrades. With this router, each transport of the server is a target of
+ * one router. The router gives an upgrade to the first target that takes it. When no target takes it and no other
+ * listener of the server can take it, the router refuses it with 400, as before.
+ *
+ * This module imports only types of Node.
+ */
+
+import type { IncomingMessage, Server as HttpServer } from "http";
+import type { Duplex } from "stream";
+
+/** A target of the router: it takes an upgrade (true), or leaves it alone (false). */
+export interface UpgradeTarget {
+  upgrade(req: IncomingMessage, socket: Duplex, head: Buffer): boolean;
+}
+
+/** The reason texts of the statuses of a refused upgrade. */
+const STATUS_TEXT: Record<number, string> = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  503: "Service Unavailable",
+};
+
+/**
+ * This function refuses an upgrade: it writes an HTTP response with the status and the message,
+ * then it destroys the socket.
+ */
+export function refuseUpgrade(socket: Duplex, status: number, message?: string): void {
+  if (socket.writable) {
+    const text = STATUS_TEXT[status] ?? "Error";
+    const body = message ?? text;
+    socket.write(
+      `HTTP/1.1 ${status} ${text}\r\nConnection: close\r\nContent-Type: text/plain; charset=utf-8\r\nContent-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`
+    );
+  }
+  socket.destroy();
+}
+
+interface Router {
+  readonly targets: Set<UpgradeTarget>;
+  readonly listener: (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
+}
+
+const routers = new WeakMap<HttpServer, Router>();
+
+/**
+ * This function attaches a target to the upgrades of a server. It gives the function that
+ * detaches it. The router leaves the server when its last target goes.
+ */
+export function attachUpgradeTarget(server: HttpServer, target: UpgradeTarget): () => void {
+  let router = routers.get(server);
+  if (!router) {
+    const targets = new Set<UpgradeTarget>();
+    const listener = (req: IncomingMessage, socket: Duplex, head: Buffer): void => {
+      for (const each of targets) if (each.upgrade(req, socket, head)) return;
+      // Another listener of the server (the upgrade handler of the application) can take it
+      if (server.listenerCount("upgrade") <= 1) refuseUpgrade(socket, 400);
+    };
+    router = { targets, listener };
+    routers.set(server, router);
+    server.on("upgrade", listener);
+  }
+  const current = router;
+  current.targets.add(target);
+  return () => {
+    current.targets.delete(target);
+    if (current.targets.size === 0 && routers.get(server) === current) {
+      server.off("upgrade", current.listener);
+      routers.delete(server);
+    }
+  };
+}

package/src/adapters/websocket/server/upgrade.ts

@@ -0,0 +1,88 @@
+/**
+ * The procedure upgrade handler of WebSocket: an upgrade handler of `node:http` for the "no
+ * server" mode of `ws` (CLI-3).
+ *
+ * `upgradeHandler(server, options)` gives a function `(req, socket, head) => boolean`. The function
+ * takes each upgrade request of its path and gives `true`. It gives `false` for each other path and
+ * does not touch the socket. Thus two endpoints can share one listener, and so can an endpoint and
+ * the WebSocket server of the application. The connections are the connections of
+ * `WebSocketServerTransport`: calls in the two directions, streams with credit and `seq`, events,
+ * the heartbeat and the browser checks. `handler.transport` gives that API.
+ *
+ * The handler also has the stop parts of a service transport: `start()`, `stopIntake()`,
+ * `drain(deadline, signal)`, `inFlight()` and `close()`. It does not make a server and does not
+ * listen: the owner of the listener does that.
+ */
+
+import type { IncomingMessage } from "http";
+import type { Duplex } from "stream";
+import type { RequestHandler } from "../../../server/types.js";
+import type { WebSocketServerTransportOptions } from "./types.js";
+import { WebSocketServerTransport } from "./transport.js";
+
+/** The options of `upgradeHandler`: the options of `WebSocketServerTransport` without `server`. */
+export type UpgradeHandlerOptions = Omit<WebSocketServerTransportOptions, "server">;
+
+/**
+ * The upgrade handler of `upgradeHandler`. A call gives `true` when the handler takes the upgrade
+ * (its path is the path of the endpoint), and `false` for another path. The handler then does not
+ * touch the socket.
+ */
+export interface NodeUpgradeHandler {
+  (req: IncomingMessage, socket: Duplex, head: Buffer): boolean;
+  /** The path of the endpoint. */
+  readonly path: string;
+  /**
+   * The transport of the connections: `broadcast`, `callConnection`, `transportFor`, `subscribe`,
+   * `events`, `onConnect` and the other methods of `WebSocketServerTransport`.
+   */
+  readonly transport: WebSocketServerTransport;
+  /** This method gives true when an upgrade request is for the path of the endpoint. */
+  matches(req: IncomingMessage): boolean;
+  /** This method accepts new upgrades and calls again, after `stopIntake()` or `close()`. */
+  start(): void;
+  /** This method refuses each new upgrade with 503, and each new call with `UNAVAILABLE`. */
+  stopIntake(): void;
+  /**
+   * This method waits until no call is in flight, until the `deadline` (milliseconds on the
+   * monotonic clock of `performance.now()`), or until the signal aborts.
+   */
+  drain(deadline: number, signal?: AbortSignal): Promise<void>;
+  /** The number of the calls in flight on all connections. */
+  inFlight(): number;
+  /** This method closes each connection and the WebSocket server. */
+  close(): Promise<void>;
+}
+
+/**
+ * This function makes a procedure upgrade handler: an upgrade handler of `node:http` that serves
+ * the procedures of `server` over WebSocket at `options.path`.
+ *
+ * @example
+ * ```typescript
+ * const events = upgradeHandler(server, { path: "/ws" });
+ * const live = upgradeHandler(server, { path: "/live" });
+ * http.on("upgrade", (req, socket, head) => {
+ *   if (events(req, socket, head) || live(req, socket, head)) return;
+ *   socket.destroy();
+ * });
+ * ```
+ */
+export function upgradeHandler(server: RequestHandler, options: UpgradeHandlerOptions = {}): NodeUpgradeHandler {
+  const { server: _ignored, ...rest } = options as WebSocketServerTransportOptions;
+  const transport = new WebSocketServerTransport(server, rest);
+  // A new face: a cookie is trusted only from a named origin (CSRF)
+  transport.nameOriginsForCookies();
+  transport.open();
+  const handler = ((req: IncomingMessage, socket: Duplex, head: Buffer): boolean => transport.upgrade(req, socket, head)) as NodeUpgradeHandler;
+  return Object.assign(handler, {
+    path: transport.path,
+    transport,
+    matches: (req: IncomingMessage): boolean => transport.matches(req),
+    start: (): void => transport.open(),
+    stopIntake: (): void => transport.stopIntake(),
+    drain: (deadline: number, signal?: AbortSignal): Promise<void> => transport.drain(deadline, signal),
+    inFlight: (): number => transport.inFlight(),
+    close: (): Promise<void> => transport.close(),
+  });
+}

package/src/adapters/websocket/shared/rpc.ts

@@ -317,6 +317,8 @@ export interface IncomingCallsOptions {
   isOpen: () => boolean;
   /** This function makes the server request of a `request` frame: the metadata, the credentials. */
   requestOf: (frame: WebSocketMessage, signal: AbortSignal) => ServerRequest;
+  /** This function runs when the number of calls that run becomes smaller. A drain waits on it. */
+  onSettled?: (() => void) | undefined;
 }
 
 /** The calls that the other side sends on one socket, served by a handler. */
@@ -340,7 +342,7 @@ export class IncomingCalls {
   receive(frame: WebSocketMessage): boolean {
     if (frame.type === "cancel") {
       this.inflight.get(frame.id)?.abort();
-      this.inflight.delete(frame.id);
+      if (this.inflight.delete(frame.id)) this.options.onSettled?.();
       return true;
     }
     if (frame.type === "credit") {
@@ -365,8 +367,10 @@ export class IncomingCalls {
   /** This function aborts each call that runs: the socket closed, or the side stops. */
   abortAll(): void {
     for (const controller of this.inflight.values()) controller.abort();
+    const had = this.inflight.size > 0;
     this.inflight.clear();
     this.credits.clear();
+    if (had) this.options.onSettled?.();
   }
 
   private async serve(frame: WebSocketMessage): Promise<void> {
@@ -395,7 +399,10 @@ export class IncomingCalls {
       this.sendError(frame.id, error instanceof Error ? error.message : "Internal server error", "INTERNAL_ERROR");
     } finally {
       // Delete only this request's entries (deep dive TRN-9)
-      if (this.inflight.get(frame.id) === controller) this.inflight.delete(frame.id);
+      if (this.inflight.get(frame.id) === controller) {
+        this.inflight.delete(frame.id);
+        this.options.onSettled?.();
+      }
       this.credits.delete(frame.id);
     }
   }