@statewalker/webrun-http-browser 0.9.0 → 0.12.1

package/src/sw/sw-http-adapter.ts

@@ -22,6 +22,7 @@ import {
   type AttachReply,
   DETACH_CALL,
   DRAIN_CALL,
+  headerPairs,
   KEEPALIVE_MESSAGE,
   NEED_LINKS_CALL,
   type NeedLinksParams,
@@ -35,8 +36,23 @@ import { resolveWorkerUrl } from "./worker-url.js";
 export interface SwHttpAdapterOptions {
   /** The first path segment under the scope that this page's handlers serve. */
   key: string;
+  /** The worker's scope. Default: the folder of `serviceWorkerUrl`, or `registration`'s scope. */
   scope?: string;
   serviceWorkerUrl?: string;
+  /**
+   * How the browser loads the worker script: `"module"` for an ES-module worker (one that
+   * `import`s `startHttpDispatcher` from this package's `sw.js`), `"classic"` — the default — for
+   * one that `importScripts` `sw-worker.js`. A script registered again with another type than
+   * its registration's fails to update, so this must match how the page registers it.
+   */
+  type?: WorkerType;
+  /**
+   * A registration the page made itself, for a worker it registers its own way (its own script,
+   * scope or type). The adapter then registers nothing, and `stop()` leaves the registration in
+   * place: it is not the adapter's to remove. `scope` defaults to the registration's, and
+   * `type` is not used.
+   */
+  registration?: ServiceWorkerRegistration;
   /**
    * Upper bound, in ms, for `start()`'s wait for the worker to activate, take
    * control of the page and answer the handshake. `start()` rejects with a
@@ -145,7 +161,10 @@ export class SwHttpAdapter {
   }
 
   get scope(): string {
-    return this.options.scope ?? new URL("./", this.serviceWorkerUrl).pathname;
+    if (this.options.scope) return this.options.scope;
+    const registration = this.options.registration;
+    if (registration) return new URL(registration.scope).pathname;
+    return new URL("./", this.serviceWorkerUrl).pathname;
   }
 
   /**
@@ -157,6 +176,9 @@ export class SwHttpAdapter {
    * sits next to it).
    */
   get rootUrl(): URL {
+    const registration = this.options.registration;
+    if (registration && !this.options.serviceWorkerUrl)
+      return new URL(this.scope, registration.scope);
     const base = this.options.serviceWorkerUrl ? this.serviceWorkerUrl : import.meta.url;
     return new URL(this.scope, base);
   }
@@ -183,9 +205,12 @@ export class SwHttpAdapter {
   async start(): Promise<void> {
     if (!this._registrationPromise) {
       this._registrationPromise = (async () => {
-        const registration = await navigator.serviceWorker.register(this.serviceWorkerUrl, {
-          scope: this.scope,
-        });
+        const registration =
+          this.options.registration ??
+          (await navigator.serviceWorker.register(this.serviceWorkerUrl, {
+            scope: this.scope,
+            ...(this.options.type ? { type: this.options.type } : {}),
+          }));
         this._registration = registration;
         const stopListening = handleChannelCalls(
           navigator.serviceWorker,
@@ -238,7 +263,7 @@ export class SwHttpAdapter {
     return this._registrationPromise;
   }
 
-  /** Detaches every link, and unregisters the worker. */
+  /** Detaches every link, and unregisters the worker (unless the page passed its `registration`). */
   async stop(): Promise<void> {
     for (const cleanup of this._cleanup.splice(0)) cleanup();
     for (const worker of [...this._workers]) await worker.detach().catch(() => {});
@@ -255,7 +280,7 @@ export class SwHttpAdapter {
     this._registration = undefined;
     this._registrationPromise = undefined;
     try {
-      await registration?.unregister();
+      if (!this.options.registration) await registration?.unregister();
     } catch (error) {
       console.log("Service Worker unregistration failed: ", error);
     }
@@ -343,12 +368,13 @@ export class SwHttpAdapter {
   /**
    * Opens the transport of a socket to the handler `url` routes to: a handler
    * of this page directly, any other through the ServiceWorker. Resolves once
-   * the handler accepted. An arrow function, so it can be handed around:
-   * `createWebSocketClass(adapter.connectWebSocket)`.
+   * the handler accepted. The handler sees `headers` on the upgrade request. An arrow function,
+   * so it can be handed around: `createWebSocketClass(adapter.connectWebSocket)`.
    */
   connectWebSocket = async (
     url: string | URL,
     protocols: string[] = [],
+    headers?: HeadersInit,
   ): Promise<WebSocketConnection> => {
     const httpUrl = new URL(`${url}`, globalThis.location?.href);
     if (httpUrl.protocol === "ws:") httpUrl.protocol = "http:";
@@ -356,7 +382,7 @@ export class SwHttpAdapter {
     const local = this._findHandler(`${httpUrl}`);
     if (local) {
       // A handler in this very page needs no ServiceWorker.
-      const result = await serveWebSocketUpgrade(local, { url: `${httpUrl}`, protocols });
+      const result = await serveWebSocketUpgrade(local, { url: `${httpUrl}`, protocols, headers });
       if (!result.ok) throw new Error(result.message);
       return { port: result.port, protocol: result.protocol };
     }
@@ -365,7 +391,7 @@ export class SwHttpAdapter {
       this._callTimeout(),
       this._worker(),
       WS_CONNECT_CALL,
-      { url: `${httpUrl}`, protocols },
+      { url: `${httpUrl}`, protocols, headers: headerPairs(headers) },
     );
   };
 

package/src/sw/worker-service.ts

@@ -30,8 +30,15 @@ export interface WorkerHttpService {
    * with `LinkLostError` rather than hanging, and the next waits for a link.
    */
   fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
-  /** Opens the transport of a socket to the handler `url` routes to. */
-  connectWebSocket(url: string | URL, protocols?: string[]): Promise<WebSocketConnection>;
+  /**
+   * Opens the transport of a socket to the handler `url` routes to. The handler sees `headers`
+   * on the upgrade request (cookies, origin, the routing a host needs), as with `ws-connect`.
+   */
+  connectWebSocket(
+    url: string | URL,
+    protocols?: string[],
+    headers?: HeadersInit,
+  ): Promise<WebSocketConnection>;
   /** A WHATWG `WebSocket` class over `connectWebSocket`. */
   readonly WebSocket: PortWebSocketClass;
   /** Whether the worker has a live link. */
@@ -110,11 +117,11 @@ export function serveHttpInWorker(
   scope.addEventListener("message", onMessage);
 
   const baseUrl = () => (globalThis as { location?: { href: string } }).location?.href;
-  const connectWebSocket = (url: string | URL, protocols: string[] = []) => {
+  const connectWebSocket = (url: string | URL, protocols: string[] = [], headers?: HeadersInit) => {
     const httpUrl = new URL(`${url}`, baseUrl());
     if (httpUrl.protocol === "ws:") httpUrl.protocol = "http:";
     else if (httpUrl.protocol === "wss:") httpUrl.protocol = "https:";
-    return endpoint.connectWebSocket(`${httpUrl}`, protocols);
+    return endpoint.connectWebSocket(`${httpUrl}`, protocols, headers);
   };
   let WebSocketClass: PortWebSocketClass | undefined;
 

package/src/ws/server.ts

@@ -1,4 +1,11 @@
-import { DEFAULT_HEARTBEAT_MS, utf8Length, type WsFrame, type WsTimers } from "./frames.js";
+import {
+  DEFAULT_HEARTBEAT_MS,
+  messageSize,
+  postFrame,
+  utf8Length,
+  type WsFrame,
+  type WsTimers,
+} from "./frames.js";
 import {
   CLOSED,
   CLOSING,
@@ -15,8 +22,35 @@ export interface ServerWebSocketOptions {
   /** 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. */
+  /** How long `close()` waits for the client's echo, in ms. Default 5 s; `Infinity` for ever. */
   closeTimeoutMs?: number;
+  /**
+   * When the heartbeat watch starts: `"open"` (the default) at once, so a client that never
+   * pings is closed with 1006 after three default periods; `"first-ping"` with the client's
+   * first ping, so a peer that does not ping at all (the other end of a pair kept in the same
+   * realm, say) is never closed for it. Once pings have started, both close a socket whose
+   * pings stop. Under `"first-ping"` a peer that never pings is never found dead.
+   */
+  watch?: "open" | "first-ping";
+  /**
+   * Which heartbeat period the watch keeps: `"follow"` (the default) the one each ping
+   * announces, `"first"` the first ping's. A client announces a longer period when its page
+   * turns hidden (browsers throttle hidden pages' timers), and a closing tab turns hidden on its
+   * way out: following it notices a dead tab only after three of the longer periods.
+   */
+  heartbeatPeriod?: "follow" | "first";
+  /** Lets `send()` before `accept()`; the frames wait in the port until the peer reads. */
+  sendBeforeAccept?: boolean;
+  /**
+   * Delivers the messages that arrive after `close()` until the peer's close frame does (they
+   * were in flight), as workerd does. By default they are dropped, as browsers do.
+   */
+  deliverWhileClosing?: boolean;
+  /**
+   * The code `close()` sends when given none. Default 1000. 1005 ("no status code") is what a
+   * close frame without a code reads as on the other end, as `close()` does on workerd.
+   */
+  defaultCloseCode?: number;
 }
 
 /**
@@ -31,7 +65,8 @@ export interface ServerWebSocketOptions {
  *   `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.
+ *   terminated worker), the socket closes with 1006. With `watch: "first-ping"`
+ *   the watch starts only once the client pings.
  */
 export class ServerWebSocket extends PortSocketCore {
   static readonly CONNECTING = CONNECTING;
@@ -41,19 +76,25 @@ export class ServerWebSocket extends PortSocketCore {
 
   readonly url: string;
   readonly protocol: string;
+  private _binaryType: "blob" | "arraybuffer" = "arraybuffer";
+  private readonly _options: ServerWebSocketOptions;
   private _accepted = false;
+  private _detached = false;
   private _queue: Array<Extract<WsFrame, { t: "m" | "c" }>> = [];
   private _heartbeatMs = DEFAULT_HEARTBEAT_MS;
   private _lastPing = Date.now();
+  /** Whether a ping (with a period a timer takes) arrived already. */
+  private _pinged = false;
   private _watch: unknown;
 
   constructor(port: MessagePort, options: ServerWebSocketOptions = {}) {
     super({ timers: options.timers, closeTimeoutMs: options.closeTimeoutMs });
+    this._options = options;
     this.url = options.url ?? "";
     this.protocol = options.protocol ?? "";
     this._attach(port);
     this._state = OPEN;
-    this._watchHeartbeat();
+    if (options.watch !== "first-ping") this._watchHeartbeat();
   }
 
   /** Whether `accept()` was called. */
@@ -61,22 +102,111 @@ export class ServerWebSocket extends PortSocketCore {
     return this._accepted;
   }
 
+  /** How binary messages arrive: `ArrayBuffer`s (the default) or `Blob`s. Other values are ignored. */
+  get binaryType(): "blob" | "arraybuffer" {
+    return this._binaryType;
+  }
+  set binaryType(value: "blob" | "arraybuffer") {
+    if (value === "blob" || value === "arraybuffer") this._binaryType = value;
+  }
+
+  /**
+   * Hands this end's transport to another holder before it was accepted: the port to give the
+   * client (a pair's end returned in a 101, say), with the frames that reached this end first
+   * delivered ahead of the rest. This end is closed then, with no event, and answers nothing.
+   */
+  detach(): MessagePort {
+    const port = this._port;
+    if (!port || this._accepted || this._state !== OPEN) {
+      throw new DOMException(
+        "Only an open end that was not accepted can be detached.",
+        "InvalidStateError",
+      );
+    }
+    this._detached = true;
+    this._port = undefined;
+    port.onmessage = null;
+    // Acks the peer still owes this end (it sent before being detached) are not the new
+    // holder's to count: they are absorbed on the way.
+    let owed = this.bufferedAmount;
+    this._state = CLOSED;
+    this._onClosed();
+    this._wakeDrainWaiters();
+    const queued = this._queue.splice(0);
+    if (queued.length === 0 && owed === 0) return port;
+    // The queued frames first, then the rest, both ways, through a channel of its own: frames
+    // pass as they are (kinds this version does not know included), and the relay ends once
+    // each way carried a close frame, or either port closes.
+    const relay = new MessageChannel();
+    const holder = relay.port2;
+    const closing = new Set<"in" | "out">();
+    const end = () => {
+      port.onmessage = null;
+      holder.onmessage = null;
+      port.close();
+      holder.close();
+    };
+    const sawClose = (way: "in" | "out") => {
+      closing.add(way);
+      if (closing.size === 2) end();
+    };
+    for (const frame of queued) {
+      postFrame(holder, frame);
+      if (frame.t === "c") closing.add("in");
+    }
+    holder.onmessage = (event) => {
+      port.postMessage(event.data, transferables(event.data));
+      if ((event.data as { t?: unknown } | null)?.t === "c") sawClose("out");
+    };
+    port.onmessage = (event) => {
+      const data = event.data as { t?: unknown; n?: unknown } | null;
+      if (data?.t === "a" && typeof data.n === "number" && owed > 0) {
+        const absorbed = Math.min(owed, data.n);
+        owed -= absorbed;
+        if (data.n > absorbed) holder.postMessage({ t: "a", n: data.n - absorbed });
+        return;
+      }
+      holder.postMessage(event.data, transferables(event.data));
+      if (data?.t === "c") sawClose("in");
+    };
+    // A side that dies without a close frame: where the platform tells (MessagePort's "close").
+    port.addEventListener?.("close", end);
+    holder.addEventListener?.("close", end);
+    return relay.port1;
+  }
+
   /** Starts delivering events, the queued ones first. */
   accept(): void {
+    if (this._detached) {
+      throw new DOMException("This end was detached; it cannot be accepted.", "InvalidStateError");
+    }
     if (this._accepted) return;
     this._accepted = true;
-    for (const frame of this._queue.splice(0)) super._deliver(frame);
+    for (const frame of this._queue.splice(0)) this._deliver(frame);
   }
 
   send(data: string | ArrayBuffer | ArrayBufferView): void {
-    if (!this._accepted) {
+    if (this._detached) {
+      throw new DOMException("This end was detached; it cannot send.", "InvalidStateError");
+    }
+    if (!this._accepted && !this._options.sendBeforeAccept) {
       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)) {
+  close(code?: number, reason = ""): void {
+    this.checkClose(code, reason);
+    this._startClose(code ?? this._options.defaultCloseCode ?? 1000, reason);
+  }
+
+  /**
+   * Refuses a `close()` the endpoint may not make: by default a code outside RFC 6455 §7.4's
+   * sendable ones, or a reason over 123 bytes. A subclass with another platform's rules
+   * overrides it.
+   */
+  protected checkClose(code: number | undefined, reason: string): void {
+    if (code !== undefined && !isSendableCloseCode(code)) {
       throw new DOMException(
         `${code} is not a close code an endpoint may send.`,
         "InvalidAccessError",
@@ -85,7 +215,6 @@ export class ServerWebSocket extends PortSocketCore {
     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 {
@@ -93,17 +222,37 @@ export class ServerWebSocket extends PortSocketCore {
       this._queue.push(frame);
       return;
     }
+    if (frame.t === "m" && this._state === CLOSING && this._options.deliverWhileClosing) {
+      this._dispatchMessage(frame.d);
+      this._consumed(messageSize(frame.d));
+      return;
+    }
     super._deliver(frame);
   }
 
   protected _dispatchMessage(data: string | ArrayBuffer): void {
-    this.dispatchEvent(new MessageEvent("message", { data }));
+    const delivered =
+      typeof data !== "string" && this._binaryType === "blob" ? new Blob([data]) : data;
+    this.dispatchEvent(new MessageEvent("message", { data: delivered }));
   }
 
   protected override _onPing(hb: number): void {
     this._post({ t: "q" });
     this._lastPing = Date.now();
-    if (hb !== this._heartbeatMs) {
+    if (this._state === CLOSED) return; // defensive: a closed socket's port receives nothing
+    const keep = this._options.heartbeatPeriod === "first" && this._pinged;
+    // A period no timer takes (2^31 - 1 ms and over: a client that turned its heartbeat off,
+    // as cellb's does with `heartbeatMs: 0`) is no heartbeat at all: the watch stops, unless the
+    // first period is the one kept.
+    if (!(hb > 0 && hb < 2 ** 31 - 1)) {
+      if (!keep && this._watch !== undefined) {
+        this._timers.clearInterval(this._watch);
+        this._watch = undefined;
+      }
+      return;
+    }
+    this._pinged = true;
+    if (!keep && (this._watch === undefined || hb !== this._heartbeatMs)) {
       this._heartbeatMs = hb;
       this._watchHeartbeat();
     }
@@ -130,3 +279,9 @@ function isSendableCloseCode(code: number): boolean {
   if (code >= 3000 && code <= 4999) return true;
   return code >= 1000 && code <= 1014 && code !== 1004 && code !== 1005 && code !== 1006;
 }
+
+/** The buffers a relayed frame carries, to transfer rather than copy. */
+function transferables(data: unknown): Transferable[] {
+  const d = (data as { d?: unknown } | null)?.d;
+  return d instanceof ArrayBuffer ? [d] : [];
+}

package/src/ws/socket-core.ts

@@ -43,7 +43,10 @@ export function newCloseEvent(init: WsCloseEventInit): Event {
 
 export interface PortSocketOptions {
   timers?: WsTimers;
-  /** How long to wait for the echo of a close frame before giving up with 1006. */
+  /**
+   * How long to wait for the echo of a close frame before giving up with 1006. `Infinity` waits
+   * for as long as it takes.
+   */
   closeTimeoutMs?: number;
 }
 
@@ -182,6 +185,8 @@ export abstract class PortSocketCore extends EventTarget {
     if (this._state === CLOSING || this._state === CLOSED) return;
     this._state = CLOSING;
     this._post({ t: "c", code, reason });
+    // A timer cannot take Infinity (it would fire at once): no timer is waiting forever.
+    if (!Number.isFinite(this._closeTimeoutMs)) return;
     this._closeTimer = this._timers.setTimeout(
       () => this._finish(1006, "", false),
       this._closeTimeoutMs,
@@ -218,7 +223,7 @@ export abstract class PortSocketCore extends EventTarget {
     this.dispatchEvent(newCloseEvent({ code, reason, wasClean }));
   }
 
-  private _wakeDrainWaiters(): void {
+  protected _wakeDrainWaiters(): void {
     if (this._drainWaiters.length === 0) return;
     const closed = this._state === CLOSED;
     this._drainWaiters = this._drainWaiters.filter(({ limit, resolve }) => {

package/src/ws/upgrade.ts

@@ -23,7 +23,11 @@ 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...). */
+  /**
+   * More headers for the handler to see (what a `route` function picks by, origin...). They are
+   * the caller's word: nothing checks them, so a handler trusts a `cookie` or an `authorization`
+   * here no more than its caller. `sec-websocket-protocol` comes from `protocols` only.
+   */
   headers?: HeadersInit;
 }
 
@@ -43,6 +47,9 @@ export function newWebSocketUpgradeRequest(
   all.set("connection", "Upgrade");
   all.set("sec-websocket-version", "13");
   if (!all.has("sec-websocket-key")) all.set("sec-websocket-key", randomKey());
+  // `protocols` alone says which subprotocols are asked for: a header of the caller's could
+  // name one the handler then picks, and the upgrade refuses as "not requested".
+  all.delete("sec-websocket-protocol");
   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);
@@ -117,6 +124,18 @@ export function upgradeWebSocket(
   const protocol = options.protocol ?? "";
   const channel = new MessageChannel();
   const socket = new ServerWebSocket(channel.port1, { ...options, url: request.url, protocol });
+  const response = webSocketUpgradeResponse(channel.port2, protocol);
+  Object.defineProperty(response, "webSocket", { value: socket, configurable: true });
+  return { socket, response };
+}
+
+/**
+ * A 101 for a socket whose server end the handler runs itself, on the other end of `port`
+ * (a server of its own over this package's frames, say): what `upgradeWebSocket` returns, minus
+ * the `ServerWebSocket`. The host hands `port` to the caller as it would for `upgradeWebSocket`
+ * (`takePort`), and `protocol` (`""` for none) is the subprotocol picked.
+ */
+export function webSocketUpgradeResponse(port: MessagePort, protocol = ""): Response {
   const response = new Response(null, {
     status: 200,
     headers: protocol ? { "sec-websocket-protocol": protocol } : {},
@@ -124,10 +143,9 @@ export function upgradeWebSocket(
   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 },
+    [UPGRADE]: { value: { port, protocol }, configurable: true, writable: true },
   });
-  return { socket, response };
+  return response;
 }
 
 /**