@statewalker/webrun-http-browser 0.9.0 → 0.12.1

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

@@ -3,6 +3,7 @@
 import { get, set } from "idb-keyval";
 import { callChannel, handleChannelCalls, withTransfer } from "../core/data-calls.js";
 import { handleClaimRequests } from "../core/service-worker-control.js";
+import type { FetchEventLike, ServiceWorkerScope } from "../core/sw-scope.js";
 import { sendHttpRequest } from "../http/http-send-recieve.js";
 import { errorMessage } from "../link/errors.js";
 import {
@@ -38,9 +39,100 @@ import {
   WS_CONNECT_CALL,
 } from "./protocol.js";
 
+/**
+ * The key a request's url belongs to, or `undefined` when it is none of this dispatcher's (the
+ * request then goes to the network). `scope` is the worker's scope, with its trailing slash.
+ */
+export type KeyFunction = (url: URL, scope: string) => string | undefined;
+
+/**
+ * The default key: the url's first path segment under `scope`, decoded; none outside it, at the
+ * scope itself, or for a segment that does not decode.
+ */
+export function scopeKey(url: URL, scope: string): string | undefined {
+  const href = `${url}`;
+  if (!href.startsWith(scope)) return undefined;
+  const key = href
+    .substring(scope.length)
+    .replace(/[?#].*$/, "")
+    .split("/")[0];
+  if (!key) return undefined;
+  try {
+    return decodeURIComponent(key);
+  } catch {
+    return undefined; // a malformed escape (`%E0`): no key, so the request goes to the network
+  }
+}
+
+/** What went wrong with a request the dispatcher took, for the `failure` option. */
+export interface DispatchFailure {
+  /**
+   * - `"timeout"`: no handler `route` accepts attached within `attachTimeoutMs` (a hand-over,
+   *   or `route` waiting for one handler in particular);
+   * - `"gone"`: the key was served before, and no handler is left (its tab closed);
+   * - `"lost"`: sending to the handler failed: lost while the request was in flight
+   *   (`error` is then a `LinkLostError`), or the stream failed otherwise (a `streamTimeout`, a
+   *   request body that errored). A handler lost once the response head is out fails the body
+   *   instead, and never reaches `failure`.
+   */
+  kind: "timeout" | "gone" | "lost";
+  error?: unknown;
+}
+
 export interface SwHttpDispatcherOptions {
-  self: ServiceWorkerGlobalScope;
+  self: ServiceWorkerScope;
   log?: (...args: unknown[]) => void;
+  /**
+   * Which key a url belongs to. Default `scopeKey`: the first path segment under the scope, and
+   * none outside it. A host with another layout gives its own: a project at the origin's root,
+   * projects under a base path. It decides for `dispatch()` (and so a handler's `service.fetch`),
+   * for sockets, and for `fetch` events of this origin's urls.
+   *
+   * A key it gives a url of another origin serves handlers' `service.fetch` (through
+   * `dispatch()`) and sockets, which this worker brokers whoever opens them (pages of this origin
+   * included). A page's own `fetch` to that origin stays the browser's: `fetch` events for other
+   * origins are left alone, so it goes to the network as it would without the worker.
+   *
+   * It runs synchronously, in the `fetch` listener; it must not throw. A handler registered in a
+   * page (`SwHttpAdapter.register`) serves only urls under its own `baseUrl` (prefix `""` makes
+   * that the scope): a url the function maps to its key from elsewhere reaches the page and gets
+   * a 404 there, where a handler in a worker (`serveHttpInWorker`) takes any url.
+   */
+  key?: KeyFunction;
+  /**
+   * Whether the dispatcher listens to `fetch` events itself. Default `true`. With `false` the
+   * host's own `fetch` listener runs instead: it answers its own routes and hands the rest to
+   * `dispatcher.handleFetch(event)`. For a dispatcher the host constructs (`new
+   * SwHttpDispatcher`): `startHttpDispatcher` refuses it, as nothing could call `handleFetch`
+   * then. The `install`/`activate` handlers (`skipWaiting`, `clients.claim`) stay on either way.
+   */
+  handleFetch?: boolean;
+  /**
+   * The answer to a request the dispatcher took and could not deliver (`DispatchFailure`).
+   * Default: 503 for `"timeout"`, 404 for `"gone"`, a plain-text 502 with the error for
+   * `"lost"`. A host whose callers expect another shape (an error its RPC layer rethrows, say)
+   * answers in it here. If it throws, the default answers.
+   */
+  failure?: (request: Request, failure: DispatchFailure) => Response | Promise<Response>;
+  /**
+   * The headers a socket's upgrade carries to `route` and to its handler, by who asked for it:
+   * `"page"` (a page's `connectWebSocket`, `serviceWorkerWebSocketClass`) or `"handler"` (a
+   * handler's `service.connectWebSocket`). Default: as given. A host whose handlers trust some
+   * headers (routing between its own workers) drops them from pages' sockets here, as it would
+   * from pages' fetches. `from` says which path a socket came by, not whom to trust: any page of
+   * this origin can attach a handler and ask as one.
+   */
+  socketHeaders?: (
+    headers: [string, string][] | undefined,
+    from: "page" | "handler",
+  ) => [string, string][] | undefined;
+  /**
+   * The answer to a navigation under the scope whose key nobody serves (also one taken before
+   * the stored keys are read, after a restart). Default `fetch(request)`, the network. A host
+   * with a page of its own for such urls answers with it here. Other requests nobody serves
+   * always go to the network.
+   */
+  unserved?: (request: Request) => Response | Promise<Response>;
   /**
    * Picks the handler of a request among the live handlers of its key.
    * Default `leastInflightRoute`: the fewest requests in flight, the oldest on
@@ -65,6 +157,11 @@ export interface SwHttpDispatcherOptions {
   wsConnectTimeoutMs?: number;
   /** Per-stream inactivity timeout of the links (webrun-rpc's). Default none. */
   streamTimeout?: number;
+  /**
+   * The window, in bytes, of the links to the handlers: `HttpLinkOptions.window`.
+   * Default 256 KiB; 0 turns it off.
+   */
+  window?: number;
   /**
    * Period of the backup liveness check, in ms: handlers whose owner lock is
    * no longer held are dropped. Default 5 s; 0 turns it off.
@@ -109,7 +206,8 @@ const TIMED_OUT = Symbol("timed-out");
  * (`SwHttpAdapter.register`) or in Dedicated Workers
  * (`SwHttpAdapter.attachWorker` + `serveHttpInWorker`).
  *
- * A url `<scope>/<key>/...` belongs to the handlers of `key`. Of those, the
+ * A url `<scope>/<key>/...` belongs to the handlers of `key` (the `key`
+ * option maps urls to keys some other way). Of those, the
  * `route` option picks one per request. Requests and responses stream with
  * backpressure in both directions, and an aborted fetch reaches the handler
  * as a cancellation (webrun-rpc + webrun-http-streams).
@@ -127,7 +225,9 @@ const TIMED_OUT = Symbol("timed-out");
  * This worker holds a router lock that handlers watch the same way.
  */
 export class SwHttpDispatcher {
-  readonly self: ServiceWorkerGlobalScope;
+  readonly self: ServiceWorkerScope;
+  /** `self`, with the WebWorker lib's types this module compiles with. */
+  private readonly _sw: ServiceWorkerGlobalScope;
   readonly log: (...args: unknown[]) => void;
   readonly options: SwHttpDispatcherOptions;
   readonly table = new HandlerTable<HandlerEntry>();
@@ -151,24 +251,26 @@ export class SwHttpDispatcher {
   constructor(options: SwHttpDispatcherOptions) {
     this.options = options;
     this.self = options.self;
+    this._sw = options.self as unknown as ServiceWorkerGlobalScope;
     this.log = options.log ?? (() => {});
     if (locksAvailable()) this.routerLock = newLockName("webrun-http-router");
   }
 
   get scope(): string {
-    return `${new URL("./", this.self.location.href)}`;
+    // The registration's scope, which the page may have set to another folder than the script's
+    // (`register(url, { scope })`); the script's folder where there is no registration to ask.
+    return this._sw.registration?.scope ?? `${new URL("./", this._sw.location.href)}`;
   }
 
-  /** The key `url` belongs to: its first path segment under the scope. */
+  /** The key `url` belongs to (the `key` option; by default its first path segment under the scope). */
   keyOf(url: string | URL): string | undefined {
-    const href = `${url}`;
-    const scope = this.scope;
-    if (!href.startsWith(scope)) return undefined;
-    const key = href
-      .substring(scope.length)
-      .replace(/[?#].*$/, "")
-      .split("/")[0];
-    return key ? decodeURIComponent(key) : undefined;
+    let parsed: URL;
+    try {
+      parsed = new URL(`${url}`);
+    } catch {
+      return undefined; // not an absolute url: nobody's
+    }
+    return (this.options.key ?? scopeKey)(parsed, this.scope);
   }
 
   /** Whether `key` has ever been served on this worker. */
@@ -182,7 +284,7 @@ export class SwHttpDispatcher {
   }
 
   start(): void {
-    const self = this.self;
+    const self = this._sw;
     if (this.routerLock) this._routerHeld = holdLock(this.routerLock).then(() => {});
     this._restored = this._restoreClaimedKeys();
     const latch = () => {
@@ -212,8 +314,16 @@ export class SwHttpDispatcher {
       }),
       handleChannelCalls(self, WS_CONNECT_CALL, async (event, params) => {
         if (!this._isOwnClient(event)) throw new Error("Only this origin's pages may open sockets");
-        const { url, protocols } = params as { url: string; protocols?: string[] };
-        const connection = await this.connectWebSocket(url, protocols ?? []);
+        const { url, protocols, headers } = params as {
+          url: string;
+          protocols?: string[];
+          headers?: [string, string][];
+        };
+        const connection = await this.connectWebSocket(
+          url,
+          protocols ?? [],
+          this._socketHeaders(headers, "page"),
+        );
         return withTransfer(connection, [connection.port]);
       }),
     );
@@ -240,10 +350,10 @@ export class SwHttpDispatcher {
       this.log("Claim control over all clients.");
       event.waitUntil(self.clients.claim());
     };
-    const onFetch = (event: FetchEvent) => this._onFetch(event);
+    const onFetch = (event: FetchEvent) => void this.handleFetch(event);
     self.addEventListener("install", onInstall);
     self.addEventListener("activate", onActivate);
-    self.addEventListener("fetch", onFetch);
+    if (this.options.handleFetch !== false) self.addEventListener("fetch", onFetch);
     this._cleanup.push(() => {
       self.removeEventListener("install", onInstall);
       self.removeEventListener("activate", onActivate);
@@ -262,38 +372,71 @@ export class SwHttpDispatcher {
 
   /**
    * Answers `request` as a fetch under the scope would be: through the
-   * handler its key routes to. A url outside the scope, or of a key this
-   * worker never served, goes to the network.
+   * handler its key routes to. A url with no key (by default, one outside the
+   * scope), or of a key this worker never served, goes to the network.
    */
   async dispatch(request: Request): Promise<Response> {
     const key = this.keyOf(request.url);
     if (key === undefined) return await fetch(request);
     await this._restored.catch(() => {});
     const entry = await this._acquire(request, key);
-    if (entry === TIMED_OUT) {
-      return new Response(null, {
-        status: 503,
-        statusText: "Service Unavailable (no handler attached in time)",
-      });
-    }
+    if (entry === TIMED_OUT) return await this._failed(request, { kind: "timeout" });
     if (!entry) {
       if (!this.serves(key)) return await fetch(request);
       // Key was served at some point but has no live handler now (its tab
       // closed). 404 rather than the network: a dev server's SPA fallback
       // would serve the app shell for every site url and stale tabs would
       // keep resurrecting registrations.
-      return new Response(null, { status: 404, statusText: "Not Found (no active handler)" });
+      return await this._failed(request, { kind: "gone" });
     }
     try {
       return await entry.link.send(request);
     } catch (error) {
       this.log("[dispatch] failed", key, error);
-      return new Response(errorMessage(error), {
-        status: 502,
-        statusText: "Bad Gateway",
-        headers: { "content-type": "text/plain; charset=utf-8" },
+      return await this._failed(request, { kind: "lost", error });
+    }
+  }
+
+  /**
+   * After `start()`: settles once the keys this worker served before a restart are read back
+   * (whatever the outcome). Until then `serves()` may answer `false` for a key it will serve.
+   */
+  get ready(): Promise<void> {
+    return this._restored.then(
+      () => {},
+      () => {},
+    );
+  }
+
+  private _socketHeaders(
+    headers: [string, string][] | undefined,
+    from: "page" | "handler",
+  ): [string, string][] | undefined {
+    return this.options.socketHeaders ? this.options.socketHeaders(headers, from) : headers;
+  }
+
+  private async _failed(request: Request, failure: DispatchFailure): Promise<Response> {
+    if (this.options.failure) {
+      try {
+        return await this.options.failure(request, failure);
+      } catch (error) {
+        this.log("[dispatch] the failure option threw; answering by default", error);
+      }
+    }
+    if (failure.kind === "timeout") {
+      return new Response(null, {
+        status: 503,
+        statusText: "Service Unavailable (no handler attached in time)",
       });
     }
+    if (failure.kind === "gone") {
+      return new Response(null, { status: 404, statusText: "Not Found (no active handler)" });
+    }
+    return new Response(errorMessage(failure.error), {
+      status: 502,
+      statusText: "Bad Gateway",
+      headers: { "content-type": "text/plain; charset=utf-8" },
+    });
   }
 
   /**
@@ -309,7 +452,7 @@ export class SwHttpDispatcher {
   ): Promise<WebSocketConnection> {
     const request = newWebSocketUpgradeRequest(url, { protocols, headers });
     const key = this.keyOf(request.url);
-    if (key === undefined) throw new Error(`${url} is outside this ServiceWorker's scope`);
+    if (key === undefined) throw new Error(`${url} belongs to no key of this ServiceWorker`);
     await this._restored.catch(() => {});
     const entry = await this._acquire(request, key);
     if (!entry || entry === TIMED_OUT) throw new Error(`No handler serves ${url}`);
@@ -330,23 +473,46 @@ export class SwHttpDispatcher {
     return await answer;
   }
 
-  private _onFetch(event: FetchEvent): void {
-    const request = event.request;
+  /**
+   * Answers `event` if it is the dispatcher's, with `request` (default `event.request`; a host
+   * may pass a rewritten one, with headers it adds). Returns whether it called `respondWith`;
+   * when it did not, the event is the caller's to answer or to leave to the network. For a host
+   * that listens to `fetch` itself (`handleFetch: false`); call it synchronously in the event's
+   * listener, as `respondWith` must be.
+   *
+   * It takes a same-origin request whose key (the `key` option) a handler serves, and also:
+   * - a navigation under the scope whose key nobody serves (answered by `unserved`);
+   * - before the stored keys are read (the first requests after a restart), every request with
+   *   a key, since only then is it known whose it is: one nobody serves gets what it would have
+   *   got after, `unserved` for a navigation and the network for anything else.
+   * So a host with a page of its own for urls nobody serves gives it as `unserved`, rather than
+   * deciding before calling this.
+   */
+  handleFetch(event: FetchEventLike, request: Request = event.request): boolean {
+    // A navigation is told by the event's own request: a rewritten copy is no longer one (`new
+    // Request(navigation, init)` makes its mode "same-origin").
+    const navigation = event.request.mode === "navigate";
+    // Another origin's url (a page's request to a CDN, an API) stays the
+    // browser's even when the key function maps it: such keys serve handlers'
+    // calls and sockets. No key: not ours either. No `respondWith` for those,
+    // so the browser does the request exactly as it would without a worker.
+    if (new URL(request.url).origin !== this._sw.location.origin) return false;
     const key = this.keyOf(request.url);
-    // Outside the scope: not ours. No `respondWith`, so the browser does the
-    // request exactly as it would without a worker.
-    if (key === undefined) return;
+    if (key === undefined) return false;
     if (this._restoreSettled) {
       if (this.serves(key)) {
         event.respondWith(this.dispatch(request));
-      } else if (request.mode === "navigate") {
+        return true;
+      }
+      if (navigation) {
         // A navigation under the scope is answered even when it is nobody's,
         // by passing it through: Firefox can leave a page uncontrolled when
         // its worker did not answer the navigation, and an uncontrolled page's
         // `fetch()` never reaches this worker. Everything else is left alone.
-        event.respondWith(fetch(request));
+        event.respondWith(this._unserved(request));
+        return true;
       }
-      return;
+      return false;
     }
     // Before the stored keys are read there is nothing to decide on, and
     // `respondWith` cannot be called after an await: claim the request, and
@@ -354,10 +520,18 @@ export class SwHttpDispatcher {
     event.respondWith(
       (async () => {
         await this._restored.catch(() => {});
-        if (!this.serves(key)) return await fetch(request);
-        return await this.dispatch(request);
+        if (this.serves(key)) return await this.dispatch(request);
+        // Nobody's: what it would have got once the keys were read, a navigation the
+        // `unserved` answer, anything else the network.
+        return navigation ? await this._unserved(request) : await fetch(request);
       })(),
     );
+    return true;
+  }
+
+  /** What a request the dispatcher took, and no handler serves, gets: `unserved`, or the network. */
+  private async _unserved(request: Request): Promise<Response> {
+    return await (this.options.unserved ?? fetch)(request);
   }
 
   private async _attach(
@@ -395,8 +569,8 @@ export class SwHttpDispatcher {
 
     const ctl = params.ctl ? rest.shift() : undefined;
     const up = params.up ? rest.shift() : undefined;
-    const streamTimeout = this.options.streamTimeout;
-    const link = await connectHttpLink(down, { streamTimeout });
+    const { streamTimeout, window } = this.options;
+    const link = await connectHttpLink(down, { streamTimeout, window });
     const entry = new HandlerEntry(
       params.key,
       params.id ?? clientId ?? crypto.randomUUID(),
@@ -503,29 +677,45 @@ export class SwHttpDispatcher {
     request: Request,
     key: string,
   ): Promise<HandlerEntry | typeof TIMED_OUT | undefined> {
+    const deadline = Date.now() + (this.options.attachTimeoutMs ?? 15_000);
     const picked = await this._pick(request, key);
     if (picked) return picked;
-    if (this.table.all(key).length > 0) {
-      // A hand-over: every handler of the key drains, or `route` declined
-      // them all. Wait for the next owner.
-      const attached = await this.table.waitFor(
-        key,
-        this.options.attachTimeoutMs ?? 15_000,
-        this.table.live(key).length > 0,
-      );
-      return attached ? ((await this._pick(request, key)) ?? TIMED_OUT) : TIMED_OUT;
-    }
-    const vacantUntil = this._vacant.get(key) ?? 0;
-    if (vacantUntil > Date.now()) {
+    if (this.table.all(key).length === 0) {
+      const vacantUntil = this._vacant.get(key) ?? 0;
       // The last handler was drained: wait for the next owner.
-      const attached = await this.table.waitFor(key, vacantUntil - Date.now());
-      return attached ? ((await this._pick(request, key)) ?? TIMED_OUT) : TIMED_OUT;
+      if (vacantUntil > Date.now()) return await this._waitToPick(request, key, vacantUntil);
+      if (!this.serves(key)) return undefined;
+      // Nothing attached for a key this worker served: it may have restarted
+      // and lost its links. Ask the pages for them.
+      await this._askForLinks(key);
+      const relinked = await this._pick(request, key);
+      if (relinked) return relinked;
+      // Nobody came back: the key's handlers are gone.
+      if (this.table.all(key).length === 0) return undefined;
+    }
+    // A hand-over (every handler of the key drains), or `route` declined the
+    // ones there are (it waits for one in particular): wait until a handler
+    // it accepts attaches, not just the next one.
+    return await this._waitToPick(request, key, deadline);
+  }
+
+  /** Waits for attaches until `route` accepts a handler, or `until` passes. */
+  private async _waitToPick(
+    request: Request,
+    key: string,
+    until: number,
+  ): Promise<HandlerEntry | typeof TIMED_OUT> {
+    for (;;) {
+      const left = until - Date.now();
+      if (left <= 0) return TIMED_OUT;
+      // In steps of at most a second: an attach between the last pick and
+      // this wait is then noticed at the next step rather than missed.
+      // A handler that attached since the last pick counts at once; when route
+      // declined the live ones, only a new attach can change its answer.
+      await this.table.waitFor(key, Math.min(left, 1_000), this.table.live(key).length > 0);
+      const picked = await this._pick(request, key);
+      if (picked) return picked;
     }
-    if (!this.serves(key)) return undefined;
-    // Nothing attached for a key this worker served: it may have restarted
-    // and lost its links. Ask the pages for them.
-    await this._askForLinks(key);
-    return await this._pick(request, key);
   }
 
   private async _pick(request: Request, key: string): Promise<HandlerEntry | undefined> {
@@ -533,7 +723,7 @@ export class SwHttpDispatcher {
     // Without Web Locks there is no owner lock: check the page is still there.
     for (const entry of live) {
       if (entry.ownerLock || !entry.clientId) continue;
-      if (!(await this.self.clients.get(entry.clientId))) {
+      if (!(await this._sw.clients.get(entry.clientId))) {
         this._close(entry, new LinkLostError(HANDLER_LOST_MESSAGE));
       }
     }
@@ -561,7 +751,7 @@ export class SwHttpDispatcher {
 
   private async _linkRound(key: string): Promise<void> {
     const timeout = this.options.relinkTimeoutMs ?? 3_000;
-    const windows = await this.self.clients.matchAll({ type: "window", includeUncontrolled: true });
+    const windows = await this._sw.clients.matchAll({ type: "window", includeUncontrolled: true });
     this.log("[need-links]", key, windows.length);
     const params: NeedLinksParams = { routerLock: this.routerLock };
     const pending = new Set(windows);
@@ -625,7 +815,11 @@ export class SwHttpDispatcher {
         return;
       case "ws-open":
         // A handler opens a socket to another handler, through this router.
-        this.connectWebSocket(message.url, message.protocols).then(
+        this.connectWebSocket(
+          message.url,
+          message.protocols,
+          this._socketHeaders(message.headers, "handler"),
+        ).then(
           ({ port, protocol }) =>
             entry.ctl?.postMessage(
               { t: "ws-opened", id: message.id, protocol, port } satisfies ControlMessage,
@@ -646,7 +840,7 @@ export class SwHttpDispatcher {
     const source = event.source as Client | null;
     if (!source?.url) return false;
     try {
-      return new URL(source.url).origin === this.self.location.origin;
+      return new URL(source.url).origin === this._sw.location.origin;
     } catch {
       return false;
     }
@@ -673,6 +867,12 @@ export class SwHttpDispatcher {
  * that stops it.
  */
 export function startHttpDispatcher(options: SwHttpDispatcherOptions): () => void {
+  if (options.handleFetch === false) {
+    throw new Error(
+      "startHttpDispatcher: handleFetch: false needs a dispatcher to call handleFetch on; " +
+        "construct it instead: new SwHttpDispatcher({ self, handleFetch: false }).start()",
+    );
+  }
   const dispatcher = new SwHttpDispatcher(options);
   dispatcher.start();
   return () => {

package/src/sw/index.ts

@@ -1,3 +1,8 @@
+export type {
+  FetchEventLike,
+  ServiceWorkerClientLike,
+  ServiceWorkerScope,
+} from "../core/sw-scope.js";
 export * from "./handler-endpoint.js";
 export * from "./handler-table.js";
 export * from "./http-sw-dispatcher.js";

package/src/sw/protocol.ts

@@ -83,7 +83,7 @@ export type ControlMessage =
   | { t: "ws-accept"; id: string; protocol: string; port: MessagePort }
   | { t: "ws-refuse"; id: string; status: number; message: string }
   // handler → ServiceWorker: the handler itself asks for a socket to another handler.
-  | { t: "ws-open"; id: string; url: string; protocols: string[] }
+  | { t: "ws-open"; id: string; url: string; protocols: string[]; headers?: [string, string][] }
   | { t: "ws-opened"; id: string; protocol: string; port: MessagePort }
   | { t: "ws-failed"; id: string; message: string };
 
@@ -102,3 +102,13 @@ export type WorkerControlMessage =
   | { type: "relink"; seen?: number }
   // worker → page: a call is in flight; keep the ServiceWorker awake.
   | { type: "keepalive" };
+
+/** `headers` as pairs a `postMessage` can carry (a `Headers` object cannot be cloned). */
+export function headerPairs(headers: HeadersInit | undefined): [string, string][] | undefined {
+  if (headers === undefined) return undefined;
+  const pairs: [string, string][] = [];
+  new Headers(headers).forEach((value, name) => {
+    pairs.push([name, value]);
+  });
+  return pairs;
+}

package/src/sw/sw-dispatcher.ts

@@ -8,6 +8,7 @@ import {
   handleClaimRequests,
   ServiceWorkerControlError,
 } from "../core/service-worker-control.js";
+import type { ServiceWorkerScope } from "../core/sw-scope.js";
 import { resolveWorkerUrl } from "./worker-url.js";
 
 export interface SwPortHandlerOptions {
@@ -194,7 +195,7 @@ export class SwPortHandler {
 }
 
 export interface SwPortDispatcherOptions {
-  self: ServiceWorkerGlobalScope;
+  self: ServiceWorkerScope;
   log?: (...args: unknown[]) => void;
 }
 
@@ -203,7 +204,9 @@ export interface SwPortDispatcherOptions {
  * clientId, persisted in IndexedDB so it can reclaim ports across SW restarts.
  */
 export class SwPortDispatcher {
-  readonly self: ServiceWorkerGlobalScope;
+  readonly self: ServiceWorkerScope;
+  /** `self`, with the WebWorker lib's types this module compiles with. */
+  private readonly _sw: ServiceWorkerGlobalScope;
   readonly log: (...args: unknown[]) => void;
   readonly handlersIndex = new Map<string, ChannelInfo>();
   /**
@@ -218,11 +221,14 @@ export class SwPortDispatcher {
 
   constructor({ self, log = () => {} }: SwPortDispatcherOptions) {
     this.self = self;
+    this._sw = self as unknown as ServiceWorkerGlobalScope;
     this.log = log;
   }
 
   get scope(): string {
-    return `${new URL("./", this.self.location.href)}`;
+    // The registration's scope, which the page may have set to another folder than the script's
+    // (`register(url, { scope })`); the script's folder where there is no registration to ask.
+    return this._sw.registration?.scope ?? `${new URL("./", this._sw.location.href)}`;
   }
 
   /**
@@ -236,7 +242,7 @@ export class SwPortDispatcher {
       if (channelInfo.key !== key) continue;
       const clientId = channelInfo.clientId;
       if (!clientId) continue;
-      const client = await this.self.clients.get(clientId);
+      const client = await this._sw.clients.get(clientId);
       if (!client) {
         // Owner tab closed: drop the stale entry and keep scanning for
         // another client that still claims this key.
@@ -254,9 +260,9 @@ export class SwPortDispatcher {
   }
 
   start(): void {
-    const stopClaims = handleClaimRequests(this.self);
+    const stopClaims = handleClaimRequests(this._sw);
     const stopPortUpdates = handleChannelCalls(
-      this.self,
+      this._sw,
       "UPDATE_COMMUNICATION_PORT",
       async (event, channelInfo, port: MessagePort) => {
         const client = event.source as Client | null;
@@ -271,16 +277,16 @@ export class SwPortDispatcher {
       stopPortUpdates();
     };
 
-    this.self.addEventListener("install", (event) => {
+    this._sw.addEventListener("install", (event) => {
       this.log("Skip waiting on install.", event);
-      this.self.skipWaiting();
+      this._sw.skipWaiting();
     });
 
-    this.self.addEventListener("activate", (event) => {
+    this._sw.addEventListener("activate", (event) => {
       this.log("Claim control over all clients.", event);
       event.waitUntil(
         (async () => {
-          await this.self.clients.claim();
+          await this._sw.clients.claim();
           await this._checkActivation();
         })(),
       );
@@ -340,7 +346,7 @@ export class SwPortDispatcher {
     for (const clientId of this.handlersIndex.keys()) ids.add(clientId);
     const index = new Map<string, Client>();
     for (const clientId of ids) {
-      const client = await this.self.clients.get(clientId);
+      const client = await this._sw.clients.get(clientId);
       if (client) index.set(clientId, client);
       else this.handlersIndex.delete(clientId);
     }