@statewalker/webrun-http-browser 0.6.4 → 0.7.0

package/src/sw/index.ts

@@ -1,2 +1,7 @@
+export * from "./handler-endpoint.js";
+export * from "./handler-table.js";
 export * from "./http-sw-dispatcher.js";
 export * from "./sw-dispatcher.js";
+export * from "./sw-http-adapter.js";
+export * from "./sw-websocket.js";
+export * from "./worker-service.js";

package/src/sw/protocol.ts

@@ -0,0 +1,103 @@
+/**
+ * The messages between pages, Dedicated Workers and the same-origin
+ * ServiceWorker. Internal: the shapes may change between versions, which is
+ * why every hand-shake carries `HTTP_LINK_PROTOCOL`.
+ *
+ * THREE PORTS PER HANDLER LINK. A page makes the channels and hands one end of
+ * each to the handler (itself, or a worker) and the other to the
+ * ServiceWorker; after that it carries nothing:
+ *
+ * - `down`: ServiceWorker → handler, the requests the handler serves;
+ * - `ctl`: a raw port next to them, for what HTTP over a stream cannot carry,
+ *   transferred `MessagePort`s (WebSocket hand-over);
+ * - `up` (workers only): handler → ServiceWorker, the requests the handler
+ *   sends through the router (to other handlers).
+ */
+
+/** Page → ServiceWorker: attach a handler link. The name is the one version 1 used. */
+export const ATTACH_CALL = "UPDATE_COMMUNICATION_PORT";
+/** Page → ServiceWorker: remove a handler link now. */
+export const DETACH_CALL = "webrun-http:detach";
+/** Page → ServiceWorker: stop routing to a link, let its requests finish, then remove it. */
+export const DRAIN_CALL = "webrun-http:drain";
+/** Page → ServiceWorker: open a WebSocket to a handler. */
+export const WS_CONNECT_CALL = "webrun-http:ws-connect";
+/** ServiceWorker → pages: attach your links again (the ServiceWorker restarted). */
+export const NEED_LINKS_CALL = "webrun-http:need-links";
+/**
+ * Page → ServiceWorker, plain messages (no reply). A message to the
+ * ServiceWorker object is an event: it starts a stopped worker and resets its
+ * idle timer. Port messages do neither.
+ */
+export const WAKE_MESSAGE = "webrun-http:wake";
+export const KEEPALIVE_MESSAGE = "webrun-http:keepalive";
+
+export interface AttachParams {
+  /** `HTTP_LINK_PROTOCOL`; absent from version 1 pages. */
+  wire?: string;
+  key: string;
+  /** The handler slot. Attaching an id that is attached already replaces it. */
+  id?: string;
+  /** Token of this attachment, named by `drain` / `detach`. */
+  owner?: string;
+  /** A Web Lock the handler holds while it lives. */
+  ownerLock?: string;
+  /** Whatever the host wants a `route` function to see. */
+  meta?: unknown;
+  /** Which ports follow `down` in the transfer list, in this order. */
+  ctl?: boolean;
+  up?: boolean;
+}
+
+export interface AttachReply {
+  /** `HTTP_LINK_PROTOCOL`: proves the worker speaks it. */
+  accepted: string;
+  /** The Web Lock the ServiceWorker holds while it lives; absent without Web Locks. */
+  routerLock?: string;
+}
+
+export interface DrainParams {
+  key: string;
+  id: string;
+  owner: string;
+  /** How long requests in flight may run before the link is closed anyway. */
+  ms?: number;
+}
+
+export interface NeedLinksParams {
+  /** Links made for this router are alive; only the others need attaching again. */
+  routerLock?: string;
+}
+
+/** The `ctl` port's messages. */
+export type ControlMessage =
+  // ServiceWorker → handler: a caller asks for a socket.
+  | {
+      t: "ws-connect";
+      id: string;
+      url: string;
+      protocols: string[];
+      headers?: [string, string][];
+    }
+  // handler → ServiceWorker: the answer (`port` is transferred).
+  | { 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-opened"; id: string; protocol: string; port: MessagePort }
+  | { t: "ws-failed"; id: string; message: string };
+
+/** Page ↔ worker: what `attachWorker` and `serveHttpInWorker` exchange. */
+export const WORKER_HELLO = "webrun-http:worker-hello";
+
+export type WorkerControlMessage =
+  // worker → page, once: the worker serves, and holds this owner lock.
+  | { type: "ready"; ownerLock?: string }
+  // page → worker: a fresh link (ports: down, ctl, up).
+  | { type: "link"; key: string; routerLock?: string }
+  // page → worker: drop the links of this key.
+  | { type: "unlink"; key: string }
+  // worker → page: my links are dead and a call waits; attach me again.
+  | { type: "relink" }
+  // worker → page: a call is in flight; keep the ServiceWorker awake.
+  | { type: "keepalive" };

package/src/sw/sw-dispatcher.ts

@@ -8,6 +8,7 @@ import {
   handleClaimRequests,
   ServiceWorkerControlError,
 } from "../core/service-worker-control.js";
+import { resolveWorkerUrl } from "./worker-url.js";
 
 export interface SwPortHandlerOptions {
   key: string;
@@ -44,6 +45,7 @@ export class SwPortHandler {
   private _serviceWorkerUrl?: string;
   private _serviceWorker?: ServiceWorker;
   private _registrationPromise?: Promise<void>;
+  private _registration?: ServiceWorkerRegistration;
   private _cleanupRegistrations?: () => void;
 
   constructor(options: SwPortHandlerOptions) {
@@ -65,7 +67,7 @@ export class SwPortHandler {
    * own url when one is given, not against this module's: a bundle that is
    * not an ES module (an IIFE, Theia's frontend) has no `import.meta.url`, and
    * `new URL(scope, undefined)` threw `Invalid URL` there. Only without a
-   * worker url does the module's location decide (its default `index-sw.js`
+   * worker url does the module's location decide (its default `sw-worker.js`
    * sits next to it).
    */
   get rootUrl(): URL {
@@ -82,7 +84,7 @@ export class SwPortHandler {
           // 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);
+        : new URL("./sw-worker.js", this.rootUrl);
       this._serviceWorkerUrl = `${url}`;
     }
     return this._serviceWorkerUrl;
@@ -133,7 +135,7 @@ export class SwPortHandler {
         const registration = await navigator.serviceWorker.register(this.serviceWorkerUrl, {
           scope: this.scope,
         });
-        register(() => registration.unregister());
+        this._registration = registration;
 
         const stopListening = handleChannelCalls(
           navigator.serviceWorker,
@@ -170,6 +172,7 @@ export class SwPortHandler {
           // that is not controlled, and other pages may be using the worker.
           stopListening();
           this._cleanupRegistrations = undefined;
+          this._registration = undefined;
           this._registrationPromise = undefined;
           throw error;
         }
@@ -180,13 +183,12 @@ export class SwPortHandler {
 
   async stop(): Promise<void> {
     this._cleanupRegistrations?.();
-    const registrations = await navigator.serviceWorker.getRegistrations();
-    for (const registration of registrations) {
-      try {
-        await registration.unregister();
-      } catch (error) {
-        console.log("Service Worker registration failed: ", error);
-      }
+    const registration = this._registration;
+    this._registration = undefined;
+    try {
+      await registration?.unregister();
+    } catch (error) {
+      console.log("Service Worker unregistration failed: ", error);
     }
   }
 }
@@ -346,23 +348,3 @@ 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 },
-    );
-  }
-}