@statewalker/webrun-http-browser 0.3.2 → 0.3.4

package/src/core/registry.ts

@@ -0,0 +1,54 @@
+export type CleanupAction = () => unknown;
+
+interface CleanupFn {
+  (skip?: boolean): unknown;
+  action: CleanupAction;
+}
+
+export interface Registry {
+  register(action: CleanupAction): CleanupFn;
+  unregister(action: CleanupAction): void;
+  clear(): void;
+}
+
+export type NewRegistryResult = [
+  register: Registry["register"],
+  clear: Registry["clear"],
+  unregister: Registry["unregister"],
+] &
+  Registry;
+
+export function newRegistry(onError: (error: unknown) => void = console.error): NewRegistryResult {
+  let counter = 0;
+  const registrations: Record<number, CleanupFn> = {};
+
+  const register: Registry["register"] = (action) => {
+    const id = counter++;
+    const fn: CleanupFn = Object.assign(
+      (skip?: boolean) => {
+        try {
+          delete registrations[id];
+          return skip ? undefined : action();
+        } catch (error) {
+          onError(error);
+        }
+      },
+      { action },
+    );
+    registrations[id] = fn;
+    return fn;
+  };
+
+  const unregister: Registry["unregister"] = (action) => {
+    for (const r of Object.values(registrations)) {
+      if (r.action === action) r(true);
+    }
+  };
+
+  const clear: Registry["clear"] = () => {
+    for (const r of Object.values(registrations)) r();
+  };
+
+  const tuple = [register, clear, unregister] as NewRegistryResult;
+  return Object.assign(tuple, { register, clear, unregister });
+}

package/src/http/http-send-recieve.ts

@@ -0,0 +1,81 @@
+import {
+  type HttpHandler,
+  newHttpClientStub,
+  newHttpServerStub,
+  type SerializedHttpEnvelope,
+  type SerializedHttpRequest,
+  type SerializedHttpResponse,
+} from "@statewalker/webrun-http-streams";
+import { handleStreams, sendStream } from "../core/data-channels.js";
+import type { MessageTarget } from "../core/message-target.js";
+
+type AnyEnvelope = SerializedHttpEnvelope<SerializedHttpRequest | SerializedHttpResponse>;
+
+async function* httpToIterator(
+  envelopeOrPromise: AnyEnvelope | Promise<AnyEnvelope>,
+): AsyncGenerator<Uint8Array, void, unknown> {
+  const { options, content } = await envelopeOrPromise;
+  const encoder = new TextEncoder();
+  yield encoder.encode(JSON.stringify(options));
+  yield* content;
+}
+
+async function httpFromIterator<Options>(
+  iterable: AsyncIterable<Uint8Array> | Promise<AsyncIterable<Uint8Array>>,
+): Promise<SerializedHttpEnvelope<Options>> {
+  const it = (await iterable)[Symbol.asyncIterator]();
+  const { done, value } = await it.next();
+  let options = {} as Options;
+  if (!done && value) {
+    const str = new TextDecoder().decode(value);
+    options = JSON.parse(str) as Options;
+  }
+  const content: AsyncIterable<Uint8Array> = {
+    [Symbol.asyncIterator]() {
+      return it;
+    },
+  };
+  return { options, content };
+}
+
+/**
+ * @deprecated For new code, prefer the `MessagePort`-based stack from
+ * `@statewalker/webrun-http-port`. Once a `MessagePort` is established between
+ * page and worker, `httpServe(port, handler)` provides equivalent semantics
+ * with `callBidi` multiplexing, full-duplex streaming, and `AbortSignal`.
+ * This helper remains for existing ServiceWorker setups that still consume the
+ * `MessageTarget` surface; it will be reimplemented on top of
+ * `webrun-http-port` in a follow-up release.
+ */
+export function handleHttpRequests(
+  communicationPort: MessageTarget,
+  handler: HttpHandler,
+): () => void {
+  const serverStub = newHttpServerStub(handler);
+  return handleStreams<Uint8Array>(communicationPort, async (it) => {
+    const envelope = await httpFromIterator<SerializedHttpRequest>(it);
+    const response = await serverStub(envelope);
+    return httpToIterator(response);
+  });
+}
+
+/**
+ * @deprecated For new code, prefer the `MessagePort`-based stack from
+ * `@statewalker/webrun-http-port/fetch`. Once the page and SW share a
+ * `MessagePort`, `fetchOverPort(port, request)` provides the same
+ * `Request → Response` semantics with multiplexing via `callBidi`, JSONL
+ * envelope framing, and native `AbortSignal` support. This helper remains for
+ * existing ServiceWorker setups; it will be reimplemented on top of
+ * `webrun-http-port` in a follow-up release.
+ */
+export async function sendHttpRequest(
+  communicationPort: MessageTarget,
+  request: Request,
+): Promise<Response> {
+  const clientStub = newHttpClientStub(async (req) => {
+    return await httpFromIterator<SerializedHttpResponse>(
+      sendStream<Uint8Array>(communicationPort, httpToIterator(req)),
+    );
+  });
+  return await clientStub(request);
+}

package/src/http/index.ts

@@ -0,0 +1,7 @@
+// HTTP primitives (HttpError, client/server stubs, SerializedHttpRequest/Response
+// types) live in `@statewalker/webrun-http-streams`. Readable-stream helpers and
+// serializable errors come from `@statewalker/webrun-streams`. Re-exported for
+// back-compat so existing imports from this package's main entry keep working.
+export * from "@statewalker/webrun-http-streams";
+export * from "@statewalker/webrun-streams";
+export * from "./http-send-recieve.js";

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./core/index.js";
+export * from "./http/index.js";
+export * from "./relay/index.js";

package/src/relay/index-sw.ts

@@ -0,0 +1,145 @@
+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 { sendHttpRequest } from "../http/http-send-recieve.js";
+import { splitServiceUrl } from "./split-service-url.js";
+
+/**
+ * Boots the relay ServiceWorker: routes fetches shaped `<origin>/~<key>/…` to
+ * the client that registered `key`, and exposes REGISTER/UNREGISTER/CONNECT
+ * channel calls used by the page-side relay client.
+ */
+export function startRelayServiceWorker(self: ServiceWorkerGlobalScope): () => void {
+  const [register, clear] = newRegistry();
+
+  if (typeof self.skipWaiting === "function") {
+    self.addEventListener("install", (e: ExtendableEvent) => {
+      e.waitUntil(self.skipWaiting());
+    });
+  }
+
+  if (self.clients && typeof self.clients.claim === "function") {
+    self.addEventListener("activate", (e: ExtendableEvent) => {
+      e.waitUntil(self.clients.claim());
+    });
+  }
+
+  const clientsRegistry = newClientsRegistry({ self });
+
+  register(
+    handleChannelCalls(self, "REGISTER", async (event, data) => {
+      const source = event.source as Client | null;
+      if (!source) return false;
+      const { key } = data as { key: string };
+      return await clientsRegistry.addClient(key, source);
+    }),
+  );
+  register(
+    handleChannelCalls(self, "UNREGISTER", async (_event, data) => {
+      const { key } = data as { key: string };
+      return await clientsRegistry.removeClient(key);
+    }),
+  );
+  register(
+    handleChannelCalls(self, "CONNECT", async (_event, data, port: MessagePort) => {
+      const { key } = data as { key: string };
+      const client = await clientsRegistry.getClient(key);
+      if (!client) throw new Error(`Target client was not found. Target key: "${key}".`);
+      return await callChannel<boolean>(client, "CONNECT", data, port);
+    }),
+  );
+
+  const fetchListener = (event: FetchEvent) => {
+    const request = event.request;
+    const params = splitServiceUrl(request.url);
+    const { key } = params;
+    if (!key) return;
+
+    event.respondWith(
+      (async (): Promise<Response> => {
+        try {
+          const channel = new MessageChannel();
+          const client = await clientsRegistry.getClient(key);
+          if (!client) throw HttpError.errorResourceGone(params);
+          const data = { type: "http", key };
+          const accepted = await callChannel<boolean>(client, "CONNECT", data, channel.port2);
+          if (!accepted) throw HttpError.errorForbidden(params);
+          return await sendHttpRequest(channel.port1, request);
+        } catch (error) {
+          const httpError = HttpError.fromError(error);
+          const options = httpError.getResponseOptions(params);
+          return new Response(JSON.stringify(options), {
+            status: httpError.status ?? 500,
+            statusText: httpError.statusText ?? "Internal Error",
+            headers: { "Content-Type": "application/json" },
+          });
+        }
+      })(),
+    );
+  };
+  self.addEventListener("fetch", fetchListener);
+  register(() => self.removeEventListener("fetch", fetchListener));
+
+  return clear;
+}
+
+interface ClientsRegistryOptions {
+  self: ServiceWorkerGlobalScope;
+  key?: string;
+}
+
+interface ClientsRegistry {
+  addClient(clientKey: string, client: Client): Promise<boolean>;
+  removeClient(clientKey: string): Promise<boolean>;
+  getClient(clientKey: string): Promise<Client | undefined>;
+}
+
+function newClientsRegistry({ self, key = "clientsIds" }: ClientsRegistryOptions): ClientsRegistry {
+  let _index: Record<string, string> | undefined;
+
+  async function loadClientsIndex(): Promise<Record<string, string>> {
+    if (!_index) {
+      const entries = ((await get<Array<[string, string]>>(key)) ?? []) as Array<[string, string]>;
+      _index = Object.fromEntries(entries);
+    }
+    return _index;
+  }
+
+  async function storeClientsIndex(): Promise<Record<string, string>> {
+    const index = await loadClientsIndex();
+    await set(key, Object.entries(index));
+    return index;
+  }
+
+  async function addClient(clientKey: string, client: Client): Promise<boolean> {
+    const index = await loadClientsIndex();
+    const clientId = client.id;
+    if (index[clientKey] === clientId) return false;
+    index[clientKey] = clientId;
+    await storeClientsIndex();
+    return true;
+  }
+
+  async function removeClient(clientKey: string): Promise<boolean> {
+    const index = await loadClientsIndex();
+    if (!(clientKey in index)) return false;
+    delete index[clientKey];
+    await storeClientsIndex();
+    return true;
+  }
+
+  async function getClient(clientKey: string): Promise<Client | undefined> {
+    const index = await loadClientsIndex();
+    const clientId = index[clientKey];
+    if (!clientId) return undefined;
+    const client = await self.clients.get(clientId);
+    if (!client) {
+      delete index[clientKey];
+      await storeClientsIndex();
+    }
+    return client ?? undefined;
+  }
+
+  return { getClient, addClient, removeClient };
+}

package/src/relay/index.ts

@@ -0,0 +1,261 @@
+import type { HttpHandler } from "@statewalker/webrun-http-streams";
+import { callChannel, handleChannelCalls } from "../core/data-calls.js";
+import type { MessageTarget } from "../core/message-target.js";
+import { newRegistry } from "../core/registry.js";
+import { handleHttpRequests, sendHttpRequest } from "../http/http-send-recieve.js";
+
+export * from "./split-service-url.js";
+
+/**
+ * Returns a MessagePort that transparently bridges messages to/from the
+ * ServiceWorker controlling this page.
+ */
+export function newServiceWorkerPort(): MessagePort {
+  const channel = new MessageChannel();
+  channel.port1.onmessage = (event) => {
+    navigator.serviceWorker.controller?.postMessage(event.data, [...event.ports]);
+  };
+  navigator.serviceWorker.addEventListener("message", (event) => {
+    channel.port1.postMessage(event.data, [...event.ports]);
+  });
+  return channel.port2;
+}
+
+export interface InitServiceWorkerOptions {
+  swUrl: string;
+  scopeUrl?: string;
+  type?: WorkerType;
+}
+
+/**
+ * Registers a ServiceWorker and resolves once it's activated and controlling the page.
+ */
+export async function initServiceWorker({
+  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);
+  });
+}
+
+export interface ServiceOptions {
+  key: string;
+  port: MessageTarget;
+}
+
+/**
+ * Registers `handler` as the server for the given service `key` on the relay.
+ * Returns a cleanup function that unregisters the service.
+ */
+export async function initHttpService(
+  handler: HttpHandler,
+  { key, port }: ServiceOptions,
+): Promise<() => void> {
+  return await registerConnectionsHandler({
+    key,
+    communicationPort: port,
+    handler: async (_event, _data, callPort) => {
+      handleHttpRequests(callPort, handler);
+      return true;
+    },
+  });
+}
+
+/**
+ * Sends a `Request` to the service registered under `key` on the relay and
+ * resolves with the corresponding `Response`.
+ */
+export async function callHttpService(
+  request: Request,
+  { key, port }: ServiceOptions,
+): Promise<Response> {
+  const callPort = await initializeConnection({ key, communicationPort: port });
+  if (!callPort) throw new Error(`No service with key "${key}"`);
+  return await sendHttpRequest(callPort, request);
+}
+
+export interface RelayWindowHandlerOptions {
+  swUrl?: string;
+  scopeUrl?: string;
+}
+
+/**
+ * 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.
+ */
+export function getRelayWindowMessageHandler({
+  swUrl = `${new URL("./index-sw.js", import.meta.url)}`,
+  scopeUrl = `${new URL("../", import.meta.url)}`,
+}: RelayWindowHandlerOptions = {}): (ev: MessageEvent) => Promise<void> {
+  let externalPort: MessagePort | undefined;
+  return async (ev) => {
+    if (ev.data?.type !== "CONNECT") return;
+    const newExternalPort = ev.ports?.[0];
+    if (!newExternalPort) return;
+    if (externalPort) {
+      newExternalPort.close();
+      return;
+    }
+    externalPort = newExternalPort;
+    await initServiceWorker({ swUrl, scopeUrl });
+    const serviceWorkerPort = newServiceWorkerPort();
+    serviceWorkerPort.onmessage = (event) => {
+      externalPort?.postMessage(event.data, [...event.ports]);
+    };
+    externalPort.onmessage = (event) => {
+      serviceWorkerPort.postMessage(event.data, [...event.ports]);
+    };
+  };
+}
+
+export interface RemoteRelayChannelOptions {
+  baseUrl?: URL;
+  url?: URL;
+  container?: HTMLElement;
+}
+
+export interface RemoteRelayChannel {
+  baseUrl: URL;
+  port: MessagePort;
+  close(): void;
+}
+
+/**
+ * Embeds a hidden relay iframe, establishes a MessageChannel with it, and
+ * returns the port to be used with `initHttpService` / `callHttpService`.
+ */
+export async function newRemoteRelayChannel({
+  baseUrl = new URL("../public-relay/", import.meta.url),
+  url = new URL("relay.html", baseUrl),
+  container = document.body,
+}: RemoteRelayChannelOptions = {}): Promise<RemoteRelayChannel> {
+  const messageChannel = new MessageChannel();
+  const { iframe, promise } = newIFrame(url);
+  Object.assign(iframe.style, {
+    position: "fixed",
+    width: "1px",
+    height: "1px",
+    top: "-1000px",
+    left: "-1000px",
+    display: "block",
+    opacity: "0",
+    border: "none",
+    outline: "none",
+  });
+  container.appendChild(iframe);
+  promise.then(() => {
+    iframe.contentWindow?.postMessage({ type: "CONNECT" }, "*", [messageChannel.port1]);
+  });
+  return {
+    baseUrl,
+    port: messageChannel.port2,
+    close: () => {
+      iframe.parentElement?.removeChild(iframe);
+      messageChannel.port1.close();
+      messageChannel.port2.close();
+    },
+  };
+
+  function newIFrame(src: URL): { iframe: HTMLIFrameElement; promise: Promise<HTMLIFrameElement> } {
+    const iframe = document.createElement("iframe");
+    iframe.src = `${src}`;
+    Object.assign(iframe.style, {
+      padding: "0",
+      margin: "0",
+      border: "none",
+      outline: "none",
+      width: "100%",
+      height: "100%",
+    });
+    return {
+      iframe,
+      promise: new Promise<HTMLIFrameElement>((resolve, reject) => {
+        iframe.onerror = () => reject(new Error(`Failed to load ${src}`));
+        iframe.onload = () => resolve(iframe);
+      }),
+    };
+  }
+}
+
+export interface InitializeConnectionOptions {
+  key: string;
+  communicationPort: MessageTarget;
+  [key: string]: unknown;
+}
+
+export async function initializeConnection({
+  key,
+  communicationPort,
+  ...options
+}: InitializeConnectionOptions): Promise<MessagePort | null> {
+  const channel = new MessageChannel();
+  const accepted = await callChannel<boolean>(
+    communicationPort,
+    "CONNECT",
+    { key, ...options },
+    channel.port2,
+  );
+  if (!accepted) {
+    channel.port1.close();
+    channel.port2.close();
+    return null;
+  }
+  return channel.port1;
+}
+
+export interface RegisterConnectionsHandlerOptions {
+  key: string;
+  handler: (event: MessageEvent, data: unknown, port: MessagePort) => boolean | Promise<boolean>;
+  communicationPort: MessageTarget;
+}
+
+export async function registerConnectionsHandler({
+  key,
+  handler,
+  communicationPort,
+}: RegisterConnectionsHandlerOptions): Promise<() => void> {
+  const [register, cleanup] = newRegistry();
+  await callChannel(communicationPort, "REGISTER", { key });
+  register(() => callChannel(communicationPort, "UNREGISTER", { key }));
+  register(
+    handleChannelCalls(communicationPort, "CONNECT", async (event, data, port) => {
+      return await handler(event, data, port);
+    }),
+  );
+  return cleanup;
+}

package/src/relay/split-service-url.ts

@@ -0,0 +1,30 @@
+export interface SplitServiceUrl {
+  url: string;
+  key: string;
+  baseUrl: string;
+  path: string;
+  [extra: string]: unknown;
+}
+
+/**
+ * Splits a URL of the form `<base>/<separator><key>/<path>` into parts.
+ * Example: `https://host/~FS/a/b` → `{ baseUrl: "https://host/~FS/", key: "FS", path: "a/b" }`.
+ */
+export function splitServiceUrl(url: URL | string, separator = "~"): SplitServiceUrl {
+  const str = `${url}`;
+  const idx = str.indexOf(separator);
+  let baseUrl = "";
+  let key = "";
+  let path = "";
+  if (idx >= 0) {
+    baseUrl = str.substring(0, idx + separator.length);
+    str.substring(idx + separator.length).replace(/^([^/]+)/, (match, $1) => {
+      baseUrl += match;
+      if (baseUrl.length < str.length) baseUrl += "/";
+      key = $1;
+      path = str.substring(baseUrl.length);
+      return "";
+    });
+  }
+  return { url: str, key, baseUrl, path };
+}

package/src/relay-sw.ts

@@ -0,0 +1,7 @@
+/// <reference lib="webworker" />
+
+import { startRelayServiceWorker } from "./relay/index-sw.js";
+
+declare const self: ServiceWorkerGlobalScope;
+
+startRelayServiceWorker(self);