@statewalker/webrun-http-browser 0.4.2 → 0.5.0

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/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;

package/src/relay/index.ts

@@ -1,19 +1,38 @@
 import type { HttpHandler } from "@statewalker/webrun-http-streams";
+import { serializeError } from "@statewalker/webrun-streams";
 import { callChannel, handleChannelCalls } from "../core/data-calls.js";
 import type { MessageTarget } from "../core/message-target.js";
 import { newRegistry } from "../core/registry.js";
+import {
+  awaitActiveServiceWorker,
+  DEFAULT_SERVICE_WORKER_TIMEOUT,
+} from "../core/service-worker-control.js";
 import { handleHttpRequests, sendHttpRequest } from "../http/http-send-recieve.js";
 
 export * from "./split-service-url.js";
 
+/**
+ * The URL of this module, kept in a variable on purpose. Bundlers (Vite
+ * among them) rewrite every literal `new URL("<path>", import.meta.url)` into
+ * an emitted asset at build time, before tree-shaking — so the defaults below
+ * made every Vite consumer of this entry emit a dead copy of the package's
+ * own `dist/index.js` (`"../"` resolves to the package, hence to its `main`).
+ * Resolving against a variable is the same URL at run time and invisible to
+ * that transform.
+ */
+const moduleUrl: string = import.meta.url;
+
 /**
  * Returns a MessagePort that transparently bridges messages to/from the
- * ServiceWorker controlling this page.
+ * page's ServiceWorker: the one controlling the page, or — when the page is
+ * not controlled (a hard reload, or a page Firefox left uncontrolled) — the
+ * active worker of `registration`, which answers messages all the same.
  */
-export function newServiceWorkerPort(): MessagePort {
+export function newServiceWorkerPort(registration?: ServiceWorkerRegistration): MessagePort {
   const channel = new MessageChannel();
   channel.port1.onmessage = (event) => {
-    navigator.serviceWorker.controller?.postMessage(event.data, [...event.ports]);
+    const worker = navigator.serviceWorker.controller ?? registration?.active;
+    worker?.postMessage(event.data, [...event.ports]);
   };
   navigator.serviceWorker.addEventListener("message", (event) => {
     channel.port1.postMessage(event.data, [...event.ports]);
@@ -25,51 +44,38 @@ export interface InitServiceWorkerOptions {
   swUrl: string;
   scopeUrl?: string;
   type?: WorkerType;
+  /**
+   * Upper bound, in ms, for the wait for the worker to activate; past it the
+   * promise rejects with a `ServiceWorkerControlError`. Default
+   * `DEFAULT_SERVICE_WORKER_TIMEOUT` (30 s).
+   */
+  timeout?: number;
 }
 
 /**
- * Registers a ServiceWorker and resolves once it's activated and controlling the page.
+ * Registers a ServiceWorker and resolves with it once it is activated: the
+ * worker controlling the page, or the registration's active worker when the
+ * page is not controlled. Messaging works either way, which is all the relay
+ * needs; nothing here waits for control, because an uncontrolled page (hard
+ * reload; Firefox) may never get it. Rejects with a
+ * `ServiceWorkerControlError` if activation takes longer than `timeout`.
  */
-export async function initServiceWorker({
+export async function initServiceWorker(options: InitServiceWorkerOptions): Promise<ServiceWorker> {
+  return (await registerServiceWorker(options)).worker;
+}
+
+async function registerServiceWorker({
   swUrl,
   scopeUrl,
   type,
-}: InitServiceWorkerOptions): Promise<ServiceWorker> {
-  await navigator.serviceWorker.register(swUrl, { type, scope: scopeUrl });
-  const worker = await getServiceWorkerController();
-  await awaitServiceWorkerActivation(worker);
-  return worker;
-}
-
-function getServiceWorkerController(): Promise<ServiceWorker> {
-  return new Promise((resolve) => {
-    const container = navigator.serviceWorker;
-    if (container.controller) {
-      resolve(container.controller);
-      return;
-    }
-    const onChange = () => {
-      if (!container.controller) return;
-      resolve(container.controller);
-      container.removeEventListener("controllerchange", onChange);
-    };
-    container.addEventListener("controllerchange", onChange);
-  });
-}
-
-function awaitServiceWorkerActivation(worker: ServiceWorker): Promise<void> {
-  return new Promise((resolve) => {
-    if (worker.state === "activated") {
-      resolve();
-      return;
-    }
-    const onStateChange = () => {
-      if (worker.state !== "activated") return;
-      worker.removeEventListener("statechange", onStateChange);
-      resolve();
-    };
-    worker.addEventListener("statechange", onStateChange);
-  });
+  timeout = DEFAULT_SERVICE_WORKER_TIMEOUT,
+}: InitServiceWorkerOptions): Promise<{
+  registration: ServiceWorkerRegistration;
+  worker: ServiceWorker;
+}> {
+  const registration = await navigator.serviceWorker.register(swUrl, { type, scope: scopeUrl });
+  const active = await awaitActiveServiceWorker(registration, { timeout });
+  return { registration, worker: navigator.serviceWorker.controller ?? active };
 }
 
 export interface ServiceOptions {
@@ -111,16 +117,21 @@ export async function callHttpService(
 export interface RelayWindowHandlerOptions {
   swUrl?: string;
   scopeUrl?: string;
+  /** Passed to `initServiceWorker`: how long to wait for the relay worker to activate. */
+  timeout?: number;
 }
 
 /**
  * Returns a `window.onmessage` handler for use inside the relay iframe:
  * it accepts a CONNECT message, starts the relay ServiceWorker, and bridges
- * the parent's MessagePort with the SW.
+ * the parent's MessagePort with the SW. If the worker cannot be started, every
+ * call the parent makes on that port is answered with the error, so the
+ * parent's `initHttpService` / `callHttpService` reject instead of waiting.
  */
 export function getRelayWindowMessageHandler({
-  swUrl = `${new URL("./index-sw.js", import.meta.url)}`,
-  scopeUrl = `${new URL("../", import.meta.url)}`,
+  swUrl = `${new URL("./index-sw.js", moduleUrl)}`,
+  scopeUrl = `${new URL("../", moduleUrl)}`,
+  timeout,
 }: RelayWindowHandlerOptions = {}): (ev: MessageEvent) => Promise<void> {
   let externalPort: MessagePort | undefined;
   return async (ev) => {
@@ -132,8 +143,15 @@ export function getRelayWindowMessageHandler({
       return;
     }
     externalPort = newExternalPort;
-    await initServiceWorker({ swUrl, scopeUrl });
-    const serviceWorkerPort = newServiceWorkerPort();
+    let registration: ServiceWorkerRegistration;
+    try {
+      ({ registration } = await registerServiceWorker({ swUrl, scopeUrl, timeout }));
+    } catch (error) {
+      const serialized = serializeError(error);
+      externalPort.onmessage = (event) => event.ports[0]?.postMessage({ error: serialized });
+      throw error;
+    }
+    const serviceWorkerPort = newServiceWorkerPort(registration);
     serviceWorkerPort.onmessage = (event) => {
       externalPort?.postMessage(event.data, [...event.ports]);
     };
@@ -160,7 +178,7 @@ export interface RemoteRelayChannel {
  * returns the port to be used with `initHttpService` / `callHttpService`.
  */
 export async function newRemoteRelayChannel({
-  baseUrl = new URL("../public-relay/", import.meta.url),
+  baseUrl = new URL("../public-relay/", moduleUrl),
   url = new URL("relay.html", baseUrl),
   container = document.body,
 }: RemoteRelayChannelOptions = {}): Promise<RemoteRelayChannel> {

package/src/sw/sw-dispatcher.ts

@@ -1,12 +1,32 @@
 import { get, set } from "idb-keyval";
 import { callChannel, handleChannelCalls } from "../core/data-calls.js";
+import { withDeadline } from "../core/deadline.js";
 import { newRegistry } from "../core/registry.js";
+import {
+  awaitServiceWorkerControl,
+  DEFAULT_SERVICE_WORKER_TIMEOUT,
+  handleClaimRequests,
+  ServiceWorkerControlError,
+} from "../core/service-worker-control.js";
 
 export interface SwPortHandlerOptions {
   key: string;
   scope?: string;
   serviceWorkerUrl?: string;
   bindPort: (port: MessagePort) => void | Promise<void>;
+  /**
+   * 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
+   * `ServiceWorkerControlError` past it instead of waiting forever.
+   * Default `DEFAULT_SERVICE_WORKER_TIMEOUT` (30 s).
+   */
+  timeout?: number;
+  /**
+   * If the page is still uncontrolled once the worker is active — after a
+   * hard reload, say — and the worker does not take it over when asked,
+   * reload the page once instead of rejecting. Default `false`.
+   */
+  reloadIfUncontrolled?: boolean;
 }
 
 interface ChannelInfo {
@@ -84,6 +104,15 @@ export class SwPortHandler {
     return { key: this.key };
   }
 
+  /**
+   * Registers the worker and waits until it is activated and controls this
+   * page, then opens the port to it. The page must be controlled, because
+   * only a controlled page's `fetch()` reaches the worker. When the page
+   * loaded uncontrolled (a hard reload does that), the worker is asked to
+   * claim it. Rejects with a `ServiceWorkerControlError` when that fails or
+   * `timeout` passes (`reason` says which step); a later `start()` tries
+   * again.
+   */
   async start(): Promise<void> {
     if (!this._registrationPromise) {
       this._registrationPromise = (async () => {
@@ -97,20 +126,44 @@ export class SwPortHandler {
         });
         register(() => registration.unregister());
 
-        register(
-          handleChannelCalls(
-            navigator.serviceWorker,
-            "UPDATE_COMMUNICATION_PORT",
-            async (_event, _params, port: MessagePort) => {
-              await this._setCommunicationPort(port);
-              return this._getRegistrationInfo();
-            },
-          ),
+        const stopListening = handleChannelCalls(
+          navigator.serviceWorker,
+          "UPDATE_COMMUNICATION_PORT",
+          async (_event, _params, port: MessagePort) => {
+            await this._setCommunicationPort(port);
+            return this._getRegistrationInfo();
+          },
         );
-
-        this._serviceWorker = await getServiceWorkerController();
-        await awaitServiceWorkerActivation(this._serviceWorker);
-        await this._updateCommunicationChannel();
+        register(stopListening);
+
+        const timeout = this.options.timeout ?? DEFAULT_SERVICE_WORKER_TIMEOUT;
+        const deadline = Date.now() + timeout;
+        try {
+          this._serviceWorker = await awaitServiceWorkerControl(registration, {
+            timeout,
+            reloadIfUncontrolled: this.options.reloadIfUncontrolled,
+          });
+          await withDeadline(
+            deadline,
+            this._updateCommunicationChannel(),
+            () =>
+              new ServiceWorkerControlError(
+                "unresponsive",
+                `ServiceWorker "${this._serviceWorker?.scriptURL}" controls this page but did ` +
+                  `not answer the UPDATE_COMMUNICATION_PORT handshake within ${timeout} ms. ` +
+                  "Check that the worker script runs this package's same-origin dispatcher " +
+                  "(it importScripts `sw-worker.js`, or calls `startHttpDispatcher`).",
+              ),
+          );
+        } catch (error) {
+          // Forget this attempt so a later start() retries. Stop listening,
+          // but keep the registration: the worker is fine — it is this page
+          // that is not controlled, and other pages may be using the worker.
+          stopListening();
+          this._cleanupRegistrations = undefined;
+          this._registrationPromise = undefined;
+          throw error;
+        }
       })();
     }
     return this._registrationPromise;
@@ -129,37 +182,6 @@ export class SwPortHandler {
   }
 }
 
-function getServiceWorkerController(): Promise<ServiceWorker> {
-  return new Promise((resolve) => {
-    const container = navigator.serviceWorker;
-    if (container.controller) {
-      resolve(container.controller);
-      return;
-    }
-    const onChange = () => {
-      if (!container.controller) return;
-      resolve(container.controller);
-      container.removeEventListener("controllerchange", onChange);
-    };
-    container.addEventListener("controllerchange", onChange);
-  });
-}
-
-function awaitServiceWorkerActivation(worker: ServiceWorker): Promise<void> {
-  return new Promise((resolve) => {
-    if (worker.state === "activated") {
-      resolve();
-      return;
-    }
-    const onStateChange = () => {
-      if (worker.state !== "activated") return;
-      worker.removeEventListener("statechange", onStateChange);
-      resolve();
-    };
-    worker.addEventListener("statechange", onStateChange);
-  });
-}
-
 export interface SwPortDispatcherOptions {
   self: ServiceWorkerGlobalScope;
   log?: (...args: unknown[]) => void;
@@ -221,7 +243,8 @@ export class SwPortDispatcher {
   }
 
   start(): void {
-    this._cleanup = handleChannelCalls(
+    const stopClaims = handleClaimRequests(this.self);
+    const stopPortUpdates = handleChannelCalls(
       this.self,
       "UPDATE_COMMUNICATION_PORT",
       async (event, channelInfo, port: MessagePort) => {
@@ -232,6 +255,10 @@ export class SwPortDispatcher {
         return { ...(channelInfo as ChannelInfo) };
       },
     );
+    this._cleanup = () => {
+      stopClaims();
+      stopPortUpdates();
+    };
 
     this.self.addEventListener("install", (event) => {
       this.log("Skip waiting on install.", event);