@statewalker/webrun-http-browser 0.3.4 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-http-browser",
-  "version": "0.3.4",
+  "version": "0.5.0",
   "private": false,
   "type": "module",
   "description": "ServiceWorker-based HTTP server for browsers, with relay and same-origin dispatch modes",
@@ -42,15 +42,19 @@
   ],
   "dependencies": {
     "idb-keyval": "^6.3.0",
-    "@statewalker/webrun-streams": "0.1.1",
-    "@statewalker/webrun-http-streams": "0.2.1"
+    "@statewalker/webrun-http-streams": "0.2.2",
+    "@statewalker/webrun-streams": "0.2.0",
+    "@statewalker/webrun-rpc": "0.4.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.8",
     "@types/node": "^26.2.0",
     "http-server": "^14.1.1",
+    "playwright": "^1.62.1",
     "rimraf": "^6.1.3",
     "rolldown": "^1.2.4",
     "typescript": "^7.0.2",
+    "vite": "^8.2.1",
     "vitest": "^4.1.10"
   },
   "sideEffects": false,
@@ -60,6 +64,7 @@
   "scripts": {
     "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
     "test": "vitest run",
+    "test:browser": "pnpm run build && vitest run --config vitest.browser.config.ts",
     "lint": "biome check src tests",
     "serve": "http-server -p 5173 -c-1 -s .",
     "example:same-origin": "pnpm run build && http-server -p 5173 -c-1 -o /public/index.html .",

package/src/core/data-channels.ts

@@ -125,11 +125,18 @@ export async function* sendStream<T>(
   communicationPort.postMessage({ type: "START_CALL", params }, [messageChannel.port2]);
 
   const channel = newStreamChannel<T>(messageChannel.port1);
+  let drained = false;
   try {
     await channel.start();
     void channel.sendAll(input);
     yield* channel.recieveAll();
+    drained = true;
   } finally {
+    // A caller that stops early — an aborted `fetch`, a cancelled response
+    // body, a `break` — has to TELL the peer. Closing a `MessagePort` does not
+    // notify the other end, so without this the handler on the far side keeps
+    // producing into a port nobody reads, for the life of the page.
+    if (!drained) channel.cancel();
     await channel.close();
   }
 }
@@ -168,26 +175,57 @@ export function handleStreams<T>(
 interface StreamChannel<T> {
   start(): Promise<void>;
   close(): Promise<void>;
+  /** Tell the peer we have stopped reading, so it can release its producer. */
+  cancel(): void;
   recieveAll(): AsyncGenerator<T, void, unknown>;
   sendAll(it: AsyncIterable<T>): Promise<void>;
 }
 
+/** A data chunk, or — with `cancel` — the peer saying it has stopped reading. */
+type StreamMessage<T> = { done?: boolean; value?: T; error?: unknown; cancel?: boolean };
+
 function newStreamChannel<T>(port: MessageTarget): StreamChannel<T> {
-  type DataListener = (msg: { done?: boolean; value?: T; error?: unknown }) => Promise<boolean>;
+  type DataListener = (msg: StreamMessage<T>) => Promise<boolean>;
   let listeners: DataListener[] = [];
   let iterators: AsyncIterable<T>[] = [];
 
-  const notifyAll = async (data: { done?: boolean; value?: T; error?: unknown }) => {
+  const notifyAll = async (data: StreamMessage<T>) => {
     for (const listener of listeners) await listener(data);
   };
 
+  /**
+   * Release whatever we are sending. NOT awaited: `.return()` on an async
+   * generator parked awaiting its own source is queued behind that pending
+   * `next()`, so awaiting it here would block the message handler — and the
+   * chunk that would unblock it can only arrive through that same handler.
+   */
+  const cancelOutgoing = (): void => {
+    for (const it of [...iterators]) {
+      const iterable = it as AsyncIterable<T> & { return?: () => unknown };
+      void Promise.resolve(iterable.return?.()).catch(() => {});
+    }
+  };
+
   const channel = newInvokationChannel({
     port,
-    handler: (data: unknown) => notifyAll(data as { done?: boolean; value?: T; error?: unknown }),
+    handler: (data: unknown) => {
+      const message = data as StreamMessage<T>;
+      if (message?.cancel) {
+        cancelOutgoing();
+        return;
+      }
+      return notifyAll(message);
+    },
   });
 
   const start = () => channel.start();
 
+  const cancel = (): void => {
+    // Best effort by design: the port may already be gone, and a peer that
+    // never hears this is no worse off than before the message existed.
+    void channel.invoke({ cancel: true }).catch(() => {});
+  };
+
   const close = async () => {
     await notifyAll({ done: true });
     for (const it of [...iterators]) {
@@ -220,5 +258,5 @@ function newStreamChannel<T>(port: MessageTarget): StreamChannel<T> {
     );
   }
 
-  return { start, close, recieveAll, sendAll };
+  return { start, close, cancel, recieveAll, sendAll };
 }

package/src/core/deadline.ts

@@ -0,0 +1,31 @@
+/**
+ * Settles like `promise` if it settles before `deadline` (a `Date.now()`
+ * value). Otherwise calls `onTimeout`: an `Error` it returns rejects, any
+ * other value resolves. Internal; not re-exported.
+ */
+export function withDeadline<T, F>(
+  deadline: number,
+  promise: Promise<T>,
+  onTimeout: () => F,
+): Promise<T | (F extends Error ? never : F)> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => {
+        const outcome = onTimeout();
+        if (outcome instanceof Error) reject(outcome);
+        else resolve(outcome as F extends Error ? never : F);
+      },
+      Math.max(0, deadline - Date.now()),
+    );
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}

package/src/core/index.ts

@@ -7,3 +7,4 @@ export * from "./data-calls.js";
 export * from "./data-channels.js";
 export * from "./message-target.js";
 export * from "./registry.js";
+export * from "./service-worker-control.js";

package/src/core/message-target.ts

@@ -1,18 +1,8 @@
-export type MessageListener = (event: MessageEvent) => void | Promise<void>;
-
-/** An object we can listen for `"message"` events on. */
-export interface MessageSource {
-  addEventListener(type: "message", listener: MessageListener): void;
-  removeEventListener(type: "message", listener: MessageListener): void;
-  start?(): void | Promise<void>;
-}
-
-/** An object we can post messages to (with optional transferable list). */
-export interface MessageSink {
-  postMessage(message: unknown, transfer?: Transferable[]): void;
-}
-
-/** Full-duplex message target: both sends and receives. */
-export interface MessageTarget extends MessageSource, MessageSink {
-  close?(): void | Promise<void>;
-}
+// Re-exported from @statewalker/webrun-rpc, which owns the port layer, so this
+// package's five internal importers and its public API are unchanged.
+export type {
+  MessageListener,
+  MessageSink,
+  MessageSource,
+  MessageTarget,
+} from "@statewalker/webrun-rpc";

package/src/core/service-worker-control.ts

@@ -0,0 +1,243 @@
+/// <reference lib="webworker" />
+
+import { callChannel, handleChannelCalls } from "./data-calls.js";
+import { withDeadline } from "./deadline.js";
+
+/**
+ * How long, by default, the page waits for its ServiceWorker to activate and
+ * to take control before giving up. Generous: a first install downloads and
+ * evaluates the worker script, which on a slow link takes seconds.
+ */
+export const DEFAULT_SERVICE_WORKER_TIMEOUT = 30_000;
+
+/**
+ * How long the page waits for `controllerchange` once the worker has
+ * answered the `CLAIM` request. `clients.claim()` resolves only after the
+ * browser has queued that event, so this is a grace period for delivery, not
+ * a second budget.
+ */
+const CLAIM_GRACE_MS = 1_000;
+
+/** Channel call a page sends to ask its ServiceWorker to `clients.claim()` it. */
+export const CLAIM_CALL = "CLAIM";
+
+/**
+ * - `activation-timeout`: the worker did not activate in time.
+ * - `uncontrolled`: the worker is active but the page is not controlled by it.
+ * - `unresponsive`: the page is controlled, but the worker did not answer the
+ *   adapter's handshake in time.
+ */
+export type ServiceWorkerControlFailure = "activation-timeout" | "uncontrolled" | "unresponsive";
+
+/**
+ * Why a page could not get a working ServiceWorker. `reason` says which wait
+ * failed; check it (or `name`) rather than `instanceof`, because each of this
+ * package's bundles carries its own copy of this class.
+ */
+export class ServiceWorkerControlError extends Error {
+  readonly reason: ServiceWorkerControlFailure;
+  constructor(reason: ServiceWorkerControlFailure, message: string) {
+    super(message);
+    this.name = "ServiceWorkerControlError";
+    this.reason = reason;
+  }
+}
+
+export interface AwaitServiceWorkerOptions {
+  /** Upper bound for the whole wait, in ms. Default `DEFAULT_SERVICE_WORKER_TIMEOUT`. */
+  timeout?: number;
+}
+
+export interface AwaitServiceWorkerControlOptions extends AwaitServiceWorkerOptions {
+  /**
+   * When the page is still uncontrolled after asking the worker to claim it,
+   * reload the page once instead of rejecting. A normal reload is a
+   * navigation, and navigations are controlled. Guarded by `sessionStorage`
+   * so it never loops: if the reloaded page is uncontrolled too, it rejects.
+   * Default `false`.
+   */
+  reloadIfUncontrolled?: boolean;
+  /** For tests. Default `navigator.serviceWorker`. */
+  container?: ServiceWorkerContainer;
+}
+
+/**
+ * Resolves with the registration's worker once it is `activated`. Rejects
+ * with a `ServiceWorkerControlError` (`reason: "activation-timeout"`) if that
+ * takes longer than `timeout` — an install that throws or never finishes
+ * would otherwise leave the caller waiting forever.
+ */
+export async function awaitActiveServiceWorker(
+  registration: ServiceWorkerRegistration,
+  { timeout = DEFAULT_SERVICE_WORKER_TIMEOUT }: AwaitServiceWorkerOptions = {},
+): Promise<ServiceWorker> {
+  const deadline = Date.now() + timeout;
+  return await withDeadline(deadline, waitForActivated(registration), () => {
+    const worker = registration.installing ?? registration.waiting ?? registration.active;
+    return new ServiceWorkerControlError(
+      "activation-timeout",
+      `ServiceWorker ${scriptUrl(worker)} (scope ${registration.scope}) did not activate within ` +
+        `${timeout} ms` +
+        (worker ? `; it is "${worker.state}"` : "") +
+        ". Check the worker script for errors during install (DevTools → Application → " +
+        "Service Workers), or raise the `timeout` option.",
+    );
+  });
+}
+
+/**
+ * Resolves with the ServiceWorker that controls this page, once `registration`
+ * has an activated worker and the page is controlled by it.
+ *
+ * A page can stay uncontrolled while its worker is active, and then no
+ * `controllerchange` ever fires on its own:
+ * - a hard reload (Ctrl+Shift+R) bypasses the worker for that load, and the
+ *   worker's `clients.claim()` already ran when it activated;
+ * - Firefox can leave a page loaded while the worker is running uncontrolled.
+ *
+ * So when the page is uncontrolled, this asks the active worker to claim it
+ * again (a `CLAIM` channel call — this package's workers answer it) and waits
+ * for `controllerchange`. Every wait is bounded by `timeout`. If control never
+ * comes it reloads once (`reloadIfUncontrolled`) or rejects with a
+ * `ServiceWorkerControlError` (`reason: "uncontrolled"`) that says what
+ * happened and what to do.
+ */
+export async function awaitServiceWorkerControl(
+  registration: ServiceWorkerRegistration,
+  {
+    timeout = DEFAULT_SERVICE_WORKER_TIMEOUT,
+    reloadIfUncontrolled = false,
+    container = navigator.serviceWorker,
+  }: AwaitServiceWorkerControlOptions = {},
+): Promise<ServiceWorker> {
+  const deadline = Date.now() + timeout;
+  // Listen before anything else, so a `controllerchange` that lands while we
+  // wait for activation is not missed.
+  const controlled = waitForController(container);
+  try {
+    const active = await awaitActiveServiceWorker(registration, { timeout });
+    let controller = container.controller;
+    if (!controller) {
+      controller = await withDeadline(
+        deadline,
+        (async () => {
+          // Answered only once `clients.claim()` has resolved; by then the
+          // browser has queued `controllerchange` — or declined to.
+          await Promise.race([callChannel(active, CLAIM_CALL, {}), controlled.promise]);
+          return await Promise.race([controlled.promise, delay(CLAIM_GRACE_MS, null)]);
+        })(),
+        () => null,
+      );
+    }
+    if (controller) {
+      forgetReload(registration);
+      return controller;
+    }
+    if (reloadIfUncontrolled && markReload(registration)) {
+      location.reload();
+      // The page is going away; settling now would only race the unload.
+      return await new Promise<never>(() => {});
+    }
+    forgetReload(registration);
+    throw new ServiceWorkerControlError(
+      "uncontrolled",
+      `This page is not controlled by its ServiceWorker ${scriptUrl(active)} ` +
+        `(scope ${registration.scope}), although the worker is active, and the worker did not ` +
+        `take control when asked (clients.claim()) within ${timeout} ms. ` +
+        "This happens after a hard reload (Ctrl+Shift+R / Cmd+Shift+R), which bypasses " +
+        "ServiceWorkers for that load, and in Firefox for some pages opened while the worker " +
+        "was already running. Requests from this page would not reach the worker. " +
+        "Reload the page normally, pass `reloadIfUncontrolled: true` to do that automatically, " +
+        "check that the page is inside the worker's scope, and that the worker answers the " +
+        `"${CLAIM_CALL}" request (this package's workers do).`,
+    );
+  } finally {
+    controlled.cancel();
+  }
+}
+
+/**
+ * ServiceWorker side: answers the page's `CLAIM` request with
+ * `clients.claim()`, which takes over every uncontrolled client in scope.
+ * Returns a function that stops answering.
+ */
+export function handleClaimRequests(self: ServiceWorkerGlobalScope): () => void {
+  return handleChannelCalls(self, CLAIM_CALL, (event) => {
+    const claimed = self.clients.claim().then(() => true);
+    (event as unknown as Partial<ExtendableMessageEvent>).waitUntil?.(claimed);
+    return claimed;
+  });
+}
+
+function waitForActivated(registration: ServiceWorkerRegistration): Promise<ServiceWorker> {
+  return new Promise((resolve) => {
+    const watched = new Set<ServiceWorker>();
+    const check = () => {
+      const active = registration.active;
+      if (active?.state === "activated") {
+        registration.removeEventListener("updatefound", watch);
+        for (const worker of watched) worker.removeEventListener("statechange", check);
+        resolve(active);
+        return;
+      }
+      watch();
+    };
+    function watch() {
+      for (const worker of [registration.installing, registration.waiting, registration.active]) {
+        if (!worker || watched.has(worker)) continue;
+        watched.add(worker);
+        worker.addEventListener("statechange", check);
+      }
+    }
+    registration.addEventListener("updatefound", watch);
+    check();
+  });
+}
+
+function waitForController(container: ServiceWorkerContainer): {
+  promise: Promise<ServiceWorker>;
+  cancel: () => void;
+} {
+  let cancel = () => {};
+  const promise = new Promise<ServiceWorker>((resolve) => {
+    const onChange = () => {
+      if (!container.controller) return;
+      cancel();
+      resolve(container.controller);
+    };
+    cancel = () => container.removeEventListener("controllerchange", onChange);
+    container.addEventListener("controllerchange", onChange);
+  });
+  return { promise, cancel };
+}
+
+function delay<T>(ms: number, value: T): Promise<T> {
+  return new Promise((resolve) => setTimeout(() => resolve(value), ms));
+}
+
+function scriptUrl(worker: ServiceWorker | null | undefined): string {
+  return worker?.scriptURL ? `"${worker.scriptURL}"` : "(no worker)";
+}
+
+function reloadKey(registration: ServiceWorkerRegistration): string {
+  return `webrun-http-browser:reloaded-uncontrolled:${registration.scope}`;
+}
+
+/** Records the reload about to happen. `false` if one already happened, or if it cannot be recorded. */
+function markReload(registration: ServiceWorkerRegistration): boolean {
+  try {
+    const key = reloadKey(registration);
+    if (sessionStorage.getItem(key)) return false;
+    sessionStorage.setItem(key, "1");
+    return true;
+  } catch {
+    // No storage, no loop guard: reloading could then repeat forever.
+    return false;
+  }
+}
+
+function forgetReload(registration: ServiceWorkerRegistration): void {
+  try {
+    sessionStorage.removeItem(reloadKey(registration));
+  } catch {}
+}

package/src/http/http-send-recieve.ts

@@ -39,13 +39,21 @@ async function httpFromIterator<Options>(
 }
 
 /**
- * @deprecated For new code, prefer the `MessagePort`-based stack from
- * `@statewalker/webrun-http-port`. Once a `MessagePort` is established between
- * page and worker, `httpServe(port, handler)` provides equivalent semantics
- * with `callBidi` multiplexing, full-duplex streaming, and `AbortSignal`.
- * This helper remains for existing ServiceWorker setups that still consume the
- * `MessageTarget` surface; it will be reimplemented on top of
- * `webrun-http-port` in a follow-up release.
+ * Serve an `HttpHandler` over a `MessageTarget`, using this package's own
+ * `handleStreams` transport.
+ *
+ * @deprecated Prefer the port stack in `@statewalker/webrun-rpc`: open a port
+ * (`multiplexPort` over one pipe, or `transferPortMux` where the platform can
+ * transfer a real `MessagePort`), turn it into a `Duplex` with
+ * `serveDuplexOverPort`, and serve HTTP on that with
+ * `httpServe(handler, options)` from `@statewalker/webrun-http-streams`.
+ *
+ * That path has backpressure; **this one does not.** `sendStream`'s chunk
+ * sender discards the promise it is given, so a fast producer over a slow
+ * consumer accumulates without bound. It also has no per-stream timeout and no
+ * chunking to a transport's message ceiling.
+ *
+ * Kept for existing ServiceWorker setups built on the `MessageTarget` surface.
  */
 export function handleHttpRequests(
   communicationPort: MessageTarget,
@@ -60,13 +68,18 @@ export function handleHttpRequests(
 }
 
 /**
- * @deprecated For new code, prefer the `MessagePort`-based stack from
- * `@statewalker/webrun-http-port/fetch`. Once the page and SW share a
- * `MessagePort`, `fetchOverPort(port, request)` provides the same
- * `Request → Response` semantics with multiplexing via `callBidi`, JSONL
- * envelope framing, and native `AbortSignal` support. This helper remains for
- * existing ServiceWorker setups; it will be reimplemented on top of
- * `webrun-http-port` in a follow-up release.
+ * Ship a `Request` over a `MessageTarget` and await the `Response`, using this
+ * package's own `sendStream` transport.
+ *
+ * @deprecated Prefer the port stack in `@statewalker/webrun-rpc`: open a port
+ * (`multiplexPort` over one pipe, or `transferPortMux` where the platform can
+ * transfer a real `MessagePort`), turn it into a `Duplex` with
+ * `duplexOverPort`, and drive HTTP over it with `httpFetch` from
+ * `@statewalker/webrun-http-streams`.
+ *
+ * Same caveat as {@link handleHttpRequests}: the transport underneath this
+ * helper has no backpressure, no per-stream timeout, and no chunking to a
+ * transport's message ceiling. Kept for existing ServiceWorker setups.
  */
 export async function sendHttpRequest(
   communicationPort: MessageTarget,

package/src/relay/index-sw.ts

@@ -2,6 +2,7 @@ import { HttpError } from "@statewalker/webrun-http-streams";
 import { get, set } from "idb-keyval";
 import { callChannel, handleChannelCalls } from "../core/data-calls.js";
 import { newRegistry } from "../core/registry.js";
+import { handleClaimRequests } from "../core/service-worker-control.js";
 import { sendHttpRequest } from "../http/http-send-recieve.js";
 import { splitServiceUrl } from "./split-service-url.js";
 
@@ -27,6 +28,10 @@ export function startRelayServiceWorker(self: ServiceWorkerGlobalScope): () => v
 
   const clientsRegistry = newClientsRegistry({ self });
 
+  // Pages bridge to `registration.active` when uncontrolled, so they do not
+  // need this; it is here so any page of this origin can ask for control.
+  register(handleClaimRequests(self));
+
   register(
     handleChannelCalls(self, "REGISTER", async (event, data) => {
       const source = event.source as Client | null;