@statewalker/webrun-http-browser 0.3.4 → 0.5.0

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 {
@@ -47,7 +67,12 @@ export class SwPortHandler {
   get serviceWorkerUrl(): string {
     if (!this._serviceWorkerUrl) {
       const url = this.options.serviceWorkerUrl
-        ? new URL(this.options.serviceWorkerUrl)
+        ? // A worker url is relative to the document that registers it, so it
+          // is resolved against `location.href` like any other url a page
+          // writes. Without the base, the root-relative form callers actually
+          // use — `"/sw-worker.js"` — threw a bare `Invalid URL` naming
+          // neither the option nor the value.
+          resolveWorkerUrl(this.options.serviceWorkerUrl)
         : new URL("./index-sw.js", this.rootUrl);
       this._serviceWorkerUrl = `${url}`;
     }
@@ -79,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 () => {
@@ -92,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;
@@ -124,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;
@@ -216,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) => {
@@ -227,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);
@@ -305,3 +337,23 @@ export class SwPortDispatcher {
     return index;
   }
 }
+
+/**
+ * Resolve a `serviceWorkerUrl` option the way a page would: relative to the
+ * current document. Absolute urls pass through untouched. A url that cannot
+ * be resolved is reported with the option name and the offending value,
+ * because the raw `TypeError: Failed to construct 'URL': Invalid URL` says
+ * neither.
+ */
+function resolveWorkerUrl(serviceWorkerUrl: string): URL {
+  const base = globalThis.location?.href;
+  try {
+    return new URL(serviceWorkerUrl, base);
+  } catch (error) {
+    throw new Error(
+      `Invalid serviceWorkerUrl: ${JSON.stringify(serviceWorkerUrl)}` +
+        (base ? ` (relative to ${base})` : " (no document to resolve it against)"),
+      { cause: error },
+    );
+  }
+}