@statewalker/webrun-http-browser 0.6.4 → 0.7.0

package/src/ws/server.ts

@@ -0,0 +1,132 @@
+import { DEFAULT_HEARTBEAT_MS, utf8Length, type WsFrame, type WsTimers } from "./frames.js";
+import {
+  CLOSED,
+  CLOSING,
+  CONNECTING,
+  isBinary,
+  OPEN,
+  PortSocketCore,
+  toArrayBuffer,
+} from "./socket-core.js";
+
+export interface ServerWebSocketOptions {
+  /** The url the client asked for. */
+  url?: string;
+  /** The subprotocol the server picked, `""` for none. */
+  protocol?: string;
+  timers?: WsTimers;
+  /** How long `close()` waits for the client's echo, in ms. Default 5 s. */
+  closeTimeoutMs?: number;
+}
+
+/**
+ * The server end of a socket over a `MessagePort`: what a handler gets from
+ * `upgradeWebSocket` and talks to.
+ *
+ * - Events are delivered only after `accept()`; frames that arrive earlier are
+ *   queued. Pings are answered even before `accept()`, so a slow handler does
+ *   not look like a dead one.
+ * - Messages arrive as strings or `ArrayBuffer`s.
+ * - `bufferedAmount` counts what the client has not consumed yet, and
+ *   `whenDrained(limit)` waits for it to fall: the backpressure a producer
+ *   applies.
+ * - When the client's pings stop for three heartbeat periods (a closed tab, a
+ *   terminated worker), the socket closes with 1006.
+ */
+export class ServerWebSocket extends PortSocketCore {
+  static readonly CONNECTING = CONNECTING;
+  static readonly OPEN = OPEN;
+  static readonly CLOSING = CLOSING;
+  static readonly CLOSED = CLOSED;
+
+  readonly url: string;
+  readonly protocol: string;
+  private _accepted = false;
+  private _queue: Array<Extract<WsFrame, { t: "m" | "c" }>> = [];
+  private _heartbeatMs = DEFAULT_HEARTBEAT_MS;
+  private _lastPing = Date.now();
+  private _watch: unknown;
+
+  constructor(port: MessagePort, options: ServerWebSocketOptions = {}) {
+    super({ timers: options.timers, closeTimeoutMs: options.closeTimeoutMs });
+    this.url = options.url ?? "";
+    this.protocol = options.protocol ?? "";
+    this._attach(port);
+    this._state = OPEN;
+    this._watchHeartbeat();
+  }
+
+  /** Whether `accept()` was called. */
+  get accepted(): boolean {
+    return this._accepted;
+  }
+
+  /** Starts delivering events, the queued ones first. */
+  accept(): void {
+    if (this._accepted) return;
+    this._accepted = true;
+    for (const frame of this._queue.splice(0)) super._deliver(frame);
+  }
+
+  send(data: string | ArrayBuffer | ArrayBufferView): void {
+    if (!this._accepted) {
+      throw new DOMException("accept() the socket before sending on it.", "InvalidStateError");
+    }
+    this._sendData(isBinary(data) ? toArrayBuffer(data) : String(data));
+  }
+
+  close(code = 1000, reason = ""): void {
+    if (!isSendableCloseCode(code)) {
+      throw new DOMException(
+        `${code} is not a close code an endpoint may send.`,
+        "InvalidAccessError",
+      );
+    }
+    if (utf8Length(reason) > 123) {
+      throw new DOMException("The close reason is longer than 123 bytes.", "SyntaxError");
+    }
+    this._startClose(code, reason);
+  }
+
+  protected override _deliver(frame: Extract<WsFrame, { t: "m" | "c" }>): void {
+    if (!this._accepted) {
+      this._queue.push(frame);
+      return;
+    }
+    super._deliver(frame);
+  }
+
+  protected _dispatchMessage(data: string | ArrayBuffer): void {
+    this.dispatchEvent(new MessageEvent("message", { data }));
+  }
+
+  protected override _onPing(hb: number): void {
+    this._post({ t: "q" });
+    this._lastPing = Date.now();
+    if (hb !== this._heartbeatMs) {
+      this._heartbeatMs = hb;
+      this._watchHeartbeat();
+    }
+  }
+
+  protected override _onClosed(): void {
+    if (this._watch !== undefined) this._timers.clearInterval(this._watch);
+    this._watch = undefined;
+  }
+
+  private _watchHeartbeat(): void {
+    if (this._watch !== undefined) this._timers.clearInterval(this._watch);
+    this._watch = this._timers.setInterval(() => {
+      if (Date.now() - this._lastPing > 3 * this._heartbeatMs) {
+        this._finish(1006, "", false, true);
+      }
+    }, this._heartbeatMs);
+  }
+}
+
+/** Codes an endpoint may put in a close frame (RFC 6455 §7.4). */
+function isSendableCloseCode(code: number): boolean {
+  if (!Number.isInteger(code)) return false;
+  if (code >= 3000 && code <= 4999) return true;
+  return code >= 1000 && code <= 1014 && code !== 1004 && code !== 1005 && code !== 1006;
+}

package/src/ws/socket-core.ts

@@ -0,0 +1,251 @@
+import {
+  DEFAULT_CLOSE_TIMEOUT_MS,
+  defaultTimers,
+  messageSize,
+  postFrame,
+  readFrame,
+  type WsFrame,
+  type WsTimers,
+} from "./frames.js";
+
+export const CONNECTING = 0;
+export const OPEN = 1;
+export const CLOSING = 2;
+export const CLOSED = 3;
+
+export interface WsCloseEventInit extends EventInit {
+  code?: number;
+  reason?: string;
+  wasClean?: boolean;
+}
+
+/**
+ * A `CloseEvent` for runtimes that have none: Node 22 has `Event` and
+ * `MessageEvent` as globals, but not `CloseEvent`.
+ */
+export class WsCloseEvent extends Event {
+  readonly code: number;
+  readonly reason: string;
+  readonly wasClean: boolean;
+  constructor(type: string, init: WsCloseEventInit = {}) {
+    super(type, init);
+    this.code = init.code ?? 0;
+    this.reason = init.reason ?? "";
+    this.wasClean = init.wasClean ?? false;
+  }
+}
+
+/** A `close` event: the platform's `CloseEvent` where there is one. */
+export function newCloseEvent(init: WsCloseEventInit): Event {
+  const Native = (globalThis as unknown as { CloseEvent?: typeof WsCloseEvent }).CloseEvent;
+  return Native ? new Native("close", init) : new WsCloseEvent("close", init);
+}
+
+export interface PortSocketOptions {
+  timers?: WsTimers;
+  /** How long to wait for the echo of a close frame before giving up with 1006. */
+  closeTimeoutMs?: number;
+}
+
+/**
+ * What both ends of a socket over a `MessagePort` share: the frames, the close
+ * handshake, and the byte accounting behind `bufferedAmount`.
+ *
+ * Not exported from the package: the two ends are `createWebSocketClass`'s
+ * class and `ServerWebSocket`.
+ */
+export abstract class PortSocketCore extends EventTarget {
+  protected _port?: MessagePort;
+  protected _state: number = CONNECTING;
+  protected readonly _timers: WsTimers;
+  protected readonly _closeTimeoutMs: number;
+  /** Bytes sent and not yet acknowledged by the peer, plus those still being prepared. */
+  private _inFlight = 0;
+  /** Bytes of messages "sent" after the socket started closing: counted, never sent. */
+  private _discarded = 0;
+  private _toAck = 0;
+  private _ackScheduled = false;
+  private _closeTimer: unknown;
+  private _drainWaiters: Array<{ limit: number; resolve: () => void }> = [];
+
+  constructor(options: PortSocketOptions = {}) {
+    super();
+    this._timers = options.timers ?? defaultTimers;
+    this._closeTimeoutMs = options.closeTimeoutMs ?? DEFAULT_CLOSE_TIMEOUT_MS;
+  }
+
+  get readyState(): number {
+    return this._state;
+  }
+
+  /**
+   * Bytes queued by `send()` that the peer has not consumed yet. A peer
+   * acknowledges what it has dispatched, so this falls as the other side reads.
+   */
+  get bufferedAmount(): number {
+    return this._inFlight + this._discarded;
+  }
+
+  /**
+   * Resolves once `bufferedAmount` is at most `limit` (default 0), or the
+   * socket is closed. The backpressure a producer applies:
+   * `if (socket.bufferedAmount > HIGH) await socket.whenDrained(LOW)`.
+   */
+  whenDrained(limit = 0): Promise<void> {
+    if (this._state === CLOSED || this._inFlight <= limit) return Promise.resolve();
+    return new Promise((resolve) => this._drainWaiters.push({ limit, resolve }));
+  }
+
+  protected _attach(port: MessagePort): void {
+    this._port = port;
+    port.onmessage = (event) => {
+      const frame = readFrame(event.data);
+      if (frame) this._onFrame(frame);
+    };
+  }
+
+  protected _onFrame(frame: WsFrame): void {
+    switch (frame.t) {
+      case "m":
+      case "c":
+        this._deliver(frame);
+        return;
+      case "a":
+        this._inFlight = Math.max(0, this._inFlight - frame.n);
+        this._wakeDrainWaiters();
+        return;
+      case "p":
+        this._onPing(frame.hb);
+        return;
+      case "q":
+        this._onPong();
+        return;
+    }
+  }
+
+  /** A message or close frame the socket is ready to act on. */
+  protected _deliver(frame: Extract<WsFrame, { t: "m" | "c" }>): void {
+    if (frame.t === "c") {
+      this._onCloseFrame(frame.code, frame.reason);
+      return;
+    }
+    if (this._state !== OPEN) return;
+    this._dispatchMessage(frame.d);
+    this._consumed(messageSize(frame.d));
+  }
+
+  protected abstract _dispatchMessage(data: string | ArrayBuffer): void;
+  protected _onPing(_hb: number): void {}
+  protected _onPong(): void {}
+  protected _onClosed(): void {}
+
+  /** Acknowledge consumed bytes, coalescing the acks of one turn into one frame. */
+  protected _consumed(bytes: number): void {
+    this._toAck += bytes;
+    if (this._ackScheduled) return;
+    this._ackScheduled = true;
+    queueMicrotask(() => {
+      this._ackScheduled = false;
+      const n = this._toAck;
+      this._toAck = 0;
+      if (n > 0 && this._state !== CLOSED) this._post({ t: "a", n });
+    });
+  }
+
+  /** Reserves `bytes` in `bufferedAmount` for a message still being prepared (a Blob). */
+  protected _reserve(bytes: number): void {
+    this._inFlight += bytes;
+  }
+
+  /** Sends one message whose bytes were reserved with `_reserve` (or `reserved = false`). */
+  protected _sendData(data: string | ArrayBuffer, reserved = false): void {
+    const size = messageSize(data);
+    if (this._state !== OPEN) {
+      if (reserved) this._inFlight = Math.max(0, this._inFlight - size);
+      this._discarded += size;
+      return;
+    }
+    if (!reserved) this._inFlight += size;
+    this._post({ t: "m", d: data });
+  }
+
+  protected _post(frame: WsFrame): void {
+    try {
+      if (this._port) postFrame(this._port, frame);
+    } catch {
+      // The port is gone; the heartbeat notices.
+    }
+  }
+
+  /** Starts the close handshake. */
+  protected _startClose(code: number, reason: string): void {
+    if (this._state === CLOSING || this._state === CLOSED) return;
+    this._state = CLOSING;
+    this._post({ t: "c", code, reason });
+    this._closeTimer = this._timers.setTimeout(
+      () => this._finish(1006, "", false),
+      this._closeTimeoutMs,
+    );
+  }
+
+  protected _onCloseFrame(code: number, reason: string): void {
+    if (this._state === CLOSED) return;
+    if (this._state === CLOSING) {
+      // The echo of our own close.
+      this._finish(code, reason, true);
+      return;
+    }
+    this._state = CLOSING;
+    this._post({ t: "c", code, reason });
+    this._finish(code, reason, true);
+  }
+
+  /** The socket is closed: release the port and tell the listeners. */
+  protected _finish(code: number, reason: string, wasClean: boolean, error = false): void {
+    if (this._state === CLOSED) return;
+    this._state = CLOSED;
+    if (this._closeTimer !== undefined) this._timers.clearTimeout(this._closeTimer);
+    this._closeTimer = undefined;
+    this._onClosed();
+    if (this._port) {
+      this._port.onmessage = null;
+      try {
+        this._port.close();
+      } catch {}
+    }
+    this._wakeDrainWaiters();
+    if (error) this.dispatchEvent(new Event("error"));
+    this.dispatchEvent(newCloseEvent({ code, reason, wasClean }));
+  }
+
+  private _wakeDrainWaiters(): void {
+    if (this._drainWaiters.length === 0) return;
+    const closed = this._state === CLOSED;
+    this._drainWaiters = this._drainWaiters.filter(({ limit, resolve }) => {
+      if (!closed && this._inFlight > limit) return true;
+      resolve();
+      return false;
+    });
+  }
+}
+
+/** Copies `data` into a fresh `ArrayBuffer`: `send()` must never detach the caller's buffer. */
+export function toArrayBuffer(data: ArrayBuffer | ArrayBufferView): ArrayBuffer {
+  if (data instanceof ArrayBuffer) return data.slice(0);
+  const copy = new Uint8Array(data.byteLength);
+  copy.set(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+  return copy.buffer;
+}
+
+export function isBinary(data: unknown): data is ArrayBuffer | ArrayBufferView {
+  return data instanceof ArrayBuffer || ArrayBuffer.isView(data);
+}
+
+export function isBlob(data: unknown): data is Blob {
+  return typeof Blob !== "undefined" && data instanceof Blob;
+}
+
+/** Valid close codes for an application to send: 1000, or 3000–4999. */
+export function isApplicationCloseCode(code: number): boolean {
+  return code === 1000 || (code >= 3000 && code <= 4999);
+}

package/src/ws/upgrade.ts

@@ -0,0 +1,200 @@
+import { errorMessage } from "../link/errors.js";
+import { WS_PORT_PROTOCOL_VERSION } from "./frames.js";
+import { ServerWebSocket, type ServerWebSocketOptions } from "./server.js";
+
+/**
+ * The upgrade, as an HTTP exchange: a `GET` with `Upgrade: websocket` goes to
+ * an ordinary `(Request) => Response` handler, and a `101` answer carrying a
+ * server socket means accepted. Anything else is a refusal, with its status.
+ *
+ * FORBIDDEN HEADERS. A browser drops `Upgrade`, `Connection` and every
+ * `Sec-*` header from a `new Request()`. The upgrade request therefore carries
+ * its headers as an own `headers` property, a standalone `Headers` that keeps
+ * them, so handler code reads `request.headers.get("upgrade")` as usual.
+ *
+ * NO 101 IN A `Response`. The constructor refuses statuses below 200, so the
+ * response `upgradeWebSocket` returns reports 101 through an own `status`
+ * property; the port that goes back to the caller is found with `takePort`.
+ */
+
+/** The request header carrying the client's version of the frame protocol. */
+export const WS_VERSION_HEADER = "x-webrun-ws-version";
+
+export interface WebSocketUpgradeInit {
+  /** Requested subprotocols, in order of preference. */
+  protocols?: string[];
+  /** More headers for the handler to see (cookies, origin, authorization...). */
+  headers?: HeadersInit;
+}
+
+/**
+ * The `GET` a handler sees for `new WebSocket(url, protocols)`. A `ws:` or
+ * `wss:` url is given as `http:` or `https:`, as a server sees it.
+ */
+export function newWebSocketUpgradeRequest(
+  url: string | URL,
+  { protocols = [], headers }: WebSocketUpgradeInit = {},
+): Request {
+  const httpUrl = new URL(`${url}`);
+  if (httpUrl.protocol === "ws:") httpUrl.protocol = "http:";
+  else if (httpUrl.protocol === "wss:") httpUrl.protocol = "https:";
+  const all = new Headers(headers);
+  all.set("upgrade", "websocket");
+  all.set("connection", "Upgrade");
+  all.set("sec-websocket-version", "13");
+  if (!all.has("sec-websocket-key")) all.set("sec-websocket-key", randomKey());
+  if (protocols.length > 0) all.set("sec-websocket-protocol", protocols.join(", "));
+  if (!all.has(WS_VERSION_HEADER)) all.set(WS_VERSION_HEADER, `${WS_PORT_PROTOCOL_VERSION}`);
+  return withHeaders(new Request(httpUrl, { method: "GET", headers: all }), all);
+}
+
+/**
+ * Re-attaches `headers` to `request` as its own `headers` property, keeping
+ * the forbidden ones a browser dropped. Returns `request`.
+ */
+export function withHeaders(request: Request, headers: Headers): Request {
+  Object.defineProperty(request, "headers", { value: headers, configurable: true });
+  return request;
+}
+
+/** Whether `request` asks for a WebSocket. */
+export function isWebSocketUpgrade(request: Request): boolean {
+  return request.headers.get("upgrade")?.toLowerCase() === "websocket";
+}
+
+/** The subprotocols `request` asks for, in order of preference. */
+export function requestedProtocols(request: Request): string[] {
+  const header = request.headers.get("sec-websocket-protocol");
+  if (!header) return [];
+  return header
+    .split(",")
+    .map((protocol) => protocol.trim())
+    .filter((protocol) => protocol !== "");
+}
+
+export interface UpgradeWebSocketOptions extends Omit<ServerWebSocketOptions, "url"> {}
+
+export interface WebSocketUpgrade {
+  /** The server end. Call `accept()`, then listen and send. */
+  socket: ServerWebSocket;
+  /** Return it from the handler: status 101. */
+  response: Response;
+}
+
+interface PendingUpgrade {
+  port: MessagePort;
+  protocol: string;
+}
+
+/**
+ * Where a response from `upgradeWebSocket` keeps its port. A registered
+ * symbol, not a module-level `WeakMap`: the handler and the host that takes
+ * the port often run different bundles of this package (a page's adapter from
+ * `dist/sw.js`, its handler code importing `dist/worker.js`), and each bundle
+ * has its own copy of every module.
+ */
+const UPGRADE = Symbol.for("webrun-http-browser:websocket-upgrade");
+
+/**
+ * Accepts a WebSocket upgrade in a handler:
+ *
+ * ```ts
+ * if (isWebSocketUpgrade(request)) {
+ *   const { socket, response } = upgradeWebSocket(request, { protocol: "v1" });
+ *   socket.accept();
+ *   socket.addEventListener("message", (event) => socket.send(event.data));
+ *   return response;
+ * }
+ * ```
+ *
+ * The host takes the client's port from the response with `takePort` and
+ * hands it to the caller.
+ */
+export function upgradeWebSocket(
+  request: Request,
+  options: UpgradeWebSocketOptions = {},
+): WebSocketUpgrade {
+  const protocol = options.protocol ?? "";
+  const channel = new MessageChannel();
+  const socket = new ServerWebSocket(channel.port1, { ...options, url: request.url, protocol });
+  const response = new Response(null, {
+    status: 200,
+    headers: protocol ? { "sec-websocket-protocol": protocol } : {},
+  });
+  Object.defineProperties(response, {
+    status: { value: 101, configurable: true },
+    statusText: { value: "Switching Protocols", configurable: true },
+    webSocket: { value: socket, configurable: true },
+    [UPGRADE]: { value: { port: channel.port2, protocol }, configurable: true, writable: true },
+  });
+  return { socket, response };
+}
+
+/**
+ * The port to hand to the caller, for a response from `upgradeWebSocket`.
+ * Taken once: a second call returns `undefined`.
+ */
+export function takePort(response: Response): MessagePort | undefined {
+  return takeUpgrade(response)?.port;
+}
+
+/** `takePort`, with the subprotocol the server picked. */
+export function takeUpgrade(response: Response): PendingUpgrade | undefined {
+  const holder = response as unknown as Record<symbol, PendingUpgrade | undefined>;
+  const upgrade = holder[UPGRADE];
+  if (upgrade) holder[UPGRADE] = undefined;
+  return upgrade;
+}
+
+export type WebSocketUpgradeResult =
+  | { ok: true; port: MessagePort; protocol: string }
+  | { ok: false; status: number; message: string };
+
+export interface ServeWebSocketUpgradeInit extends WebSocketUpgradeInit {
+  url: string;
+}
+
+/**
+ * Runs an upgrade through `handler`, as a host does when a caller asks for a
+ * socket: builds the upgrade request, calls the handler, and either takes the
+ * port of a `101` or reports the refusal. A subprotocol the caller did not ask
+ * for is a refusal, as in the standard.
+ */
+export async function serveWebSocketUpgrade(
+  handler: (request: Request) => Response | Promise<Response>,
+  { url, protocols = [], headers }: ServeWebSocketUpgradeInit,
+): Promise<WebSocketUpgradeResult> {
+  let response: Response;
+  try {
+    response = await handler(newWebSocketUpgradeRequest(url, { protocols, headers }));
+  } catch (error) {
+    return { ok: false, status: 500, message: errorMessage(error) };
+  }
+  const upgrade = takeUpgrade(response);
+  if (!upgrade || response.status !== 101) {
+    upgrade?.port.close();
+    try {
+      await response.body?.cancel();
+    } catch {}
+    return {
+      ok: false,
+      status: response.status,
+      message: `The server refused the upgrade: ${response.status} ${response.statusText}`.trim(),
+    };
+  }
+  if (upgrade.protocol !== "" && !protocols.includes(upgrade.protocol)) {
+    upgrade.port.close();
+    return {
+      ok: false,
+      status: 400,
+      message: `The server picked the subprotocol '${upgrade.protocol}', which was not requested.`,
+    };
+  }
+  return { ok: true, port: upgrade.port, protocol: upgrade.protocol };
+}
+
+function randomKey(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return btoa(String.fromCharCode(...bytes));
+}