@statewalker/webrun-http-browser 0.6.5 → 0.7.1

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;
@@ -347,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 },
-    );
-  }
-}