@statewalker/webrun-http-browser 0.6.4 → 0.7.0

package/src/sw/worker-service.ts

@@ -0,0 +1,133 @@
+import { holdLock, locksAvailable, newLockName } from "../link/locks.js";
+import {
+  createWebSocketClass,
+  type PortWebSocketClass,
+  type WebSocketClassOptions,
+  type WebSocketConnection,
+} from "../ws/client.js";
+import {
+  type FetchHandler,
+  HandlerEndpoint,
+  type HandlerEndpointOptions,
+} from "./handler-endpoint.js";
+import { WORKER_HELLO, type WorkerControlMessage } from "./protocol.js";
+
+export interface ServeHttpInWorkerOptions
+  extends Omit<HandlerEndpointOptions, "requestRelink" | "keepAlive"> {
+  /** Where the page's messages arrive. Default `globalThis` (the worker's scope). */
+  scope?: Pick<EventTarget, "addEventListener" | "removeEventListener">;
+  /** Options of the `WebSocket` class (`service.WebSocket`). */
+  webSocket?: WebSocketClassOptions;
+}
+
+/** What a worker serving HTTP can do besides serving. */
+export interface WorkerHttpService {
+  /**
+   * Fetches through the ServiceWorker's router: a url under its scope reaches
+   * the handler it routes to (another worker, a page), any other the network.
+   * Needs no `fetch` event, so it works whether or not this worker is
+   * controlled; a call that is in flight when the ServiceWorker dies fails
+   * with `LinkLostError` rather than hanging, and the next waits for a link.
+   */
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+  /** Opens the transport of a socket to the handler `url` routes to. */
+  connectWebSocket(url: string | URL, protocols?: string[]): Promise<WebSocketConnection>;
+  /** A WHATWG `WebSocket` class over `connectWebSocket`. */
+  readonly WebSocket: PortWebSocketClass;
+  /** Whether the worker has a live link. */
+  readonly linked: boolean;
+  /** Stops serving; requests in flight fail. */
+  close(): Promise<void>;
+}
+
+/**
+ * Serves `handler` from a Dedicated Worker, on the links the page attaches
+ * with `adapter.attachWorker(worker)`:
+ *
+ * ```ts
+ * // worker.ts
+ * const service = serveHttpInWorker(async (request) => new Response("hi"));
+ * ```
+ *
+ * The worker holds an owner lock while it lives, so the ServiceWorker notices
+ * at once when it is terminated. It watches the ServiceWorker's router lock,
+ * and asks its page to attach it again when its links died and a call waits.
+ * While calls through the router are in flight it asks its page every 20 s to
+ * keep the ServiceWorker awake — only a message to the ServiceWorker object
+ * counts as an event, and a worker cannot post one.
+ */
+export function serveHttpInWorker(
+  handler: FetchHandler,
+  options: ServeHttpInWorkerOptions = {},
+): WorkerHttpService {
+  const scope = options.scope ?? (globalThis as unknown as EventTarget);
+  const ownerLock = newLockName("webrun-http-owner");
+  const held = holdLock(ownerLock);
+  const controls = new Set<MessagePort>();
+  const tellPages = (message: WorkerControlMessage) => {
+    for (const control of controls) control.postMessage(message);
+  };
+  const endpoint = new HandlerEndpoint(handler, {
+    ...options,
+    requestRelink: () => tellPages({ type: "relink" }),
+    keepAlive: () => tellPages({ type: "keepalive" }),
+  });
+
+  const onMessage = (event: Event) => {
+    const { data, ports } = event as MessageEvent;
+    if ((data as { type?: unknown } | null)?.type !== WORKER_HELLO) return;
+    const control = ports?.[0];
+    if (!control) return;
+    controls.add(control);
+    control.onmessage = (message) => {
+      const msg = message.data as WorkerControlMessage;
+      if (msg?.type === "link") {
+        const [down, ctl, up] = message.ports;
+        if (down) void endpoint.link(msg.key, { down, ctl, up }, msg.routerLock);
+      } else if (msg?.type === "unlink") {
+        void endpoint.unlink(msg.key);
+      }
+    };
+    void held.then(() =>
+      control.postMessage({
+        type: "ready",
+        ownerLock: locksAvailable() ? ownerLock : undefined,
+      } satisfies WorkerControlMessage),
+    );
+  };
+  scope.addEventListener("message", onMessage);
+
+  const baseUrl = () => (globalThis as { location?: { href: string } }).location?.href;
+  const connectWebSocket = (url: string | URL, protocols: string[] = []) => {
+    const httpUrl = new URL(`${url}`, baseUrl());
+    if (httpUrl.protocol === "ws:") httpUrl.protocol = "http:";
+    else if (httpUrl.protocol === "wss:") httpUrl.protocol = "https:";
+    return endpoint.connectWebSocket(`${httpUrl}`, protocols);
+  };
+  let WebSocketClass: PortWebSocketClass | undefined;
+
+  return {
+    fetch(input, init) {
+      const request =
+        input instanceof Request && init === undefined
+          ? input
+          : new Request(input instanceof Request ? input : new URL(`${input}`, baseUrl()), init);
+      return endpoint.fetch(request);
+    },
+    connectWebSocket,
+    get WebSocket() {
+      WebSocketClass ??= createWebSocketClass(connectWebSocket, options.webSocket);
+      return WebSocketClass;
+    },
+    get linked() {
+      return endpoint.linked;
+    },
+    async close() {
+      scope.removeEventListener("message", onMessage);
+      await endpoint.close();
+      for (const control of controls) control.close();
+      controls.clear();
+      (await held)();
+    },
+  };
+}

package/src/sw/worker-url.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+export 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 },
+    );
+  }
+}

package/src/sw-worker.ts

@@ -1,7 +1,12 @@
 /// <reference lib="webworker" />
 
-import { startHttpDispatcher } from "./sw/http-sw-dispatcher.js";
+import { type SwHttpDispatcherOptions, startHttpDispatcher } from "./sw/http-sw-dispatcher.js";
 
-declare const self: ServiceWorkerGlobalScope;
+declare const self: ServiceWorkerGlobalScope & {
+  HTTP_DISPATCHER_OPTIONS?: Omit<SwHttpDispatcherOptions, "self">;
+};
 
-startHttpDispatcher({ self, log: console.log });
+// OPTIONS FROM A GLOBAL, as `relay-sw.js` takes `RELAY_OPTIONS`: this bundle is
+// loaded by `importScripts` from a host's own worker script, which runs first
+// and can set them (a `route` function, timeouts). Absent, the defaults.
+startHttpDispatcher({ log: console.log, ...self.HTTP_DISPATCHER_OPTIONS, self });

package/src/sw.ts

@@ -1 +1,3 @@
+export * from "./link/index.js";
 export * from "./sw/index.js";
+export * from "./ws/index.js";

package/src/worker.ts

@@ -0,0 +1,9 @@
+/**
+ * For Dedicated Workers that serve HTTP and WebSockets through the
+ * same-origin ServiceWorker: `serveHttpInWorker`, and the WebSocket helpers a
+ * handler needs (`upgradeWebSocket`, `isWebSocketUpgrade`...).
+ */
+export * from "./link/http-link.js";
+export type { FetchHandler, HandlerEndpointOptions } from "./sw/handler-endpoint.js";
+export * from "./sw/worker-service.js";
+export * from "./ws/index.js";

package/src/ws/client.ts

@@ -0,0 +1,346 @@
+import { DEFAULT_HEARTBEAT_MS, utf8Length, type WsTimers } from "./frames.js";
+import {
+  CLOSED,
+  CLOSING,
+  CONNECTING,
+  isApplicationCloseCode,
+  isBinary,
+  isBlob,
+  OPEN,
+  PortSocketCore,
+  toArrayBuffer,
+} from "./socket-core.js";
+
+/** What `connect` gives a socket once the server accepted it (the 101). */
+export interface WebSocketConnection {
+  port: MessagePort;
+  /** The subprotocol the server picked, `""` for none. */
+  protocol: string;
+}
+
+/**
+ * Opens the transport of one socket: resolves once the server accepted the
+ * upgrade, rejects when it refused or could not be reached. Where the port
+ * comes from — a ServiceWorker, a relay, a handler in the same page — is the
+ * caller's business.
+ */
+export type WebSocketConnector = (url: string, protocols: string[]) => Promise<WebSocketConnection>;
+
+export interface WebSocketClassOptions {
+  /** Ping period, in ms. Pongs missing for twice that close the socket with 1006. Default 10 s. */
+  heartbeatMs?: number;
+  /** Timer functions; see `WsTimers`. */
+  timers?: WsTimers;
+  /** How long `close()` waits for the server's echo, in ms. Default 5 s. */
+  closeTimeoutMs?: number;
+}
+
+type Listener = ((event: Event) => void) | null;
+
+/** The instance side of the class `createWebSocketClass` returns: the WHATWG `WebSocket` surface. */
+export interface PortWebSocket extends EventTarget {
+  readonly url: string;
+  readonly protocol: string;
+  readonly extensions: string;
+  readonly readyState: number;
+  readonly bufferedAmount: number;
+  binaryType: BinaryType;
+  onopen: Listener;
+  onmessage: ((event: MessageEvent) => void) | null;
+  onerror: Listener;
+  onclose: ((event: CloseEvent) => void) | null;
+  send(data: string | ArrayBufferLike | ArrayBufferView | Blob): void;
+  close(code?: number, reason?: string): void;
+  /** Not in the standard: see `PortSocketCore.whenDrained`. */
+  whenDrained(limit?: number): Promise<void>;
+  readonly CONNECTING: 0;
+  readonly OPEN: 1;
+  readonly CLOSING: 2;
+  readonly CLOSED: 3;
+}
+
+export interface PortWebSocketClass {
+  new (url: string | URL, protocols?: string | string[]): PortWebSocket;
+  readonly CONNECTING: 0;
+  readonly OPEN: 1;
+  readonly CLOSING: 2;
+  readonly CLOSED: 3;
+}
+
+/** RFC 7230 `token`: what a subprotocol name may be. */
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+/**
+ * A WHATWG-compatible `WebSocket` class whose transport is a `MessagePort`
+ * from `connect`. Code written against the browser's `WebSocket` runs on it
+ * unchanged:
+ *
+ * ```ts
+ * const WS = createWebSocketClass(adapter.connectWebSocket);
+ * const ws = new WS(`${baseUrl}chat`, ["v1"]);
+ * ws.onmessage = (event) => console.log(event.data);
+ * ```
+ *
+ * It validates as the standard does (url, scheme, fragment, subprotocol
+ * tokens and duplicates, close codes and reasons), has `binaryType`, the `on*`
+ * handlers next to `addEventListener`, and the close handshake.
+ * `bufferedAmount` is real: the server acknowledges what it consumed.
+ *
+ * The real `globalThis.WebSocket` is left alone; install the class where you
+ * want it.
+ */
+export function createWebSocketClass(
+  connect: WebSocketConnector,
+  options: WebSocketClassOptions = {},
+): PortWebSocketClass {
+  const heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+
+  class WebSocketOverPort extends PortSocketCore implements PortWebSocket {
+    static readonly CONNECTING = CONNECTING as 0;
+    static readonly OPEN = OPEN as 1;
+    static readonly CLOSING = CLOSING as 2;
+    static readonly CLOSED = CLOSED as 3;
+    readonly CONNECTING = CONNECTING as 0;
+    readonly OPEN = OPEN as 1;
+    readonly CLOSING = CLOSING as 2;
+    readonly CLOSED = CLOSED as 3;
+
+    readonly url: string;
+    readonly extensions = "";
+    private _protocol = "";
+    private _binaryType: BinaryType = "blob";
+    private _handlers: Record<string, Listener> = {};
+    private _heartbeat: unknown;
+    /** When the oldest ping still waiting for its pong was sent. */
+    private _unansweredSince?: number;
+    private _onVisibility?: () => void;
+    /** Sends waiting for a Blob ahead of them to be read, so order is kept. */
+    private _chain?: Promise<void>;
+
+    constructor(url: string | URL, protocols: string | string[] = []) {
+      super({ timers: options.timers, closeTimeoutMs: options.closeTimeoutMs });
+      this.url = parseUrl(url);
+      const list = typeof protocols === "string" ? [protocols] : [...protocols];
+      validateProtocols(list);
+      for (const type of ["open", "message", "error", "close"]) {
+        this.addEventListener(type, (event) => this._handlers[type]?.call(this, event));
+      }
+      // Asynchronously, as the platform does: listeners added right after the
+      // constructor must still see `open` or `error`.
+      Promise.resolve()
+        .then(() => connect(this.url, list))
+        .then(
+          (connection) => {
+            try {
+              this._opened(connection, list);
+            } catch {
+              this._failed();
+            }
+          },
+          () => this._failed(),
+        );
+    }
+
+    get protocol(): string {
+      return this._protocol;
+    }
+
+    get binaryType(): BinaryType {
+      return this._binaryType;
+    }
+    set binaryType(value: BinaryType) {
+      // The standard ignores values it does not know.
+      if (value === "blob" || value === "arraybuffer") this._binaryType = value;
+    }
+
+    get onopen(): Listener {
+      return this._handlers.open ?? null;
+    }
+    set onopen(fn: Listener) {
+      this._handlers.open = typeof fn === "function" ? fn : null;
+    }
+    get onmessage(): ((event: MessageEvent) => void) | null {
+      return (this._handlers.message as (event: MessageEvent) => void) ?? null;
+    }
+    set onmessage(fn: ((event: MessageEvent) => void) | null) {
+      this._handlers.message = typeof fn === "function" ? (fn as Listener) : null;
+    }
+    get onerror(): Listener {
+      return this._handlers.error ?? null;
+    }
+    set onerror(fn: Listener) {
+      this._handlers.error = typeof fn === "function" ? fn : null;
+    }
+    get onclose(): ((event: CloseEvent) => void) | null {
+      return (this._handlers.close as (event: CloseEvent) => void) ?? null;
+    }
+    set onclose(fn: ((event: CloseEvent) => void) | null) {
+      this._handlers.close = typeof fn === "function" ? (fn as Listener) : null;
+    }
+
+    send(data: string | ArrayBufferLike | ArrayBufferView | Blob): void {
+      if (this._state === CONNECTING) {
+        throw new DOMException("Still in CONNECTING state.", "InvalidStateError");
+      }
+      if (isBlob(data)) {
+        const size = data.size;
+        if (this._state !== OPEN) {
+          this._sendData(new ArrayBuffer(size));
+          return;
+        }
+        this._reserve(size);
+        this._enqueue(async () => this._sendData(await data.arrayBuffer(), true));
+        return;
+      }
+      const payload = isBinary(data) ? toArrayBuffer(data) : String(data);
+      if (this._chain) this._enqueue(async () => this._sendData(payload));
+      else this._sendData(payload);
+    }
+
+    close(code?: number, reason?: string): void {
+      if (code !== undefined && !isApplicationCloseCode(code)) {
+        throw new DOMException(
+          `The close code must be 1000 or in 3000-4999; ${code} is neither.`,
+          "InvalidAccessError",
+        );
+      }
+      const text = reason ?? "";
+      if (utf8Length(text) > 123) {
+        throw new DOMException("The close reason is longer than 123 bytes.", "SyntaxError");
+      }
+      if (this._state === CLOSING || this._state === CLOSED) return;
+      if (this._state === CONNECTING) {
+        // Fail the connection: `_opened` sees CLOSING and lets the port go.
+        this._state = CLOSING;
+        return;
+      }
+      this._startClose(code ?? 1005, text);
+    }
+
+    protected _dispatchMessage(data: string | ArrayBuffer): void {
+      const value =
+        typeof data === "string" || this._binaryType === "arraybuffer" ? data : new Blob([data]);
+      this.dispatchEvent(
+        new MessageEvent("message", { data: value, origin: new URL(this.url).origin }),
+      );
+    }
+
+    protected _onPong(): void {
+      this._unansweredSince = undefined;
+    }
+
+    protected _onClosed(): void {
+      if (this._heartbeat !== undefined) this._timers.clearInterval(this._heartbeat);
+      this._heartbeat = undefined;
+      if (this._onVisibility) {
+        globalThis.document?.removeEventListener("visibilitychange", this._onVisibility);
+      }
+    }
+
+    private _ping(hb = heartbeatMs): void {
+      this._unansweredSince ??= Date.now();
+      this._post({ t: "p", hb });
+    }
+
+    private _opened(connection: WebSocketConnection, requested: string[]): void {
+      const { port, protocol = "" } = (connection ?? {}) as Partial<WebSocketConnection>;
+      if (!port || typeof port.postMessage !== "function") {
+        this._failed();
+        return;
+      }
+      if (this._state !== CONNECTING) {
+        // Closed while connecting.
+        try {
+          port.postMessage({ t: "c", code: 1006, reason: "" });
+          port.close();
+        } catch {}
+        this._finish(1006, "", false, true);
+        return;
+      }
+      if (protocol !== "" && !requested.includes(protocol)) {
+        port.close();
+        this._failed();
+        return;
+      }
+      this._protocol = protocol;
+      this._attach(port);
+      this._state = OPEN;
+      this._ping();
+      this._heartbeat = this._timers.setInterval(() => {
+        // Only a ping that went unanswered counts. In a background tab this
+        // timer may run once a minute; time alone is no sign of a dead peer.
+        const since = this._unansweredSince;
+        if (since !== undefined && Date.now() - since > 2 * heartbeatMs) {
+          this._finish(1006, "", false, true);
+          return;
+        }
+        this._ping();
+      }, heartbeatMs);
+      // A hidden page's timers are throttled to once a minute (Chromium's
+      // intensive throttling): tell the server to expect pings that rarely,
+      // so it does not take a backgrounded tab for a dead one.
+      const doc = globalThis.document;
+      if (doc) {
+        this._onVisibility = () =>
+          this._ping(
+            doc.visibilityState === "hidden" ? Math.max(heartbeatMs, 70_000) : heartbeatMs,
+          );
+        doc.addEventListener("visibilitychange", this._onVisibility);
+        if (doc.visibilityState === "hidden") this._onVisibility();
+      }
+      this.dispatchEvent(new Event("open"));
+    }
+
+    private _failed(): void {
+      this._state = CLOSING;
+      this._finish(1006, "", false, true);
+    }
+
+    private _enqueue(task: () => Promise<void>): void {
+      const run = (this._chain ?? Promise.resolve()).then(task).catch(() => {});
+      this._chain = run;
+      void run.then(() => {
+        if (this._chain === run) this._chain = undefined;
+      });
+    }
+  }
+
+  return WebSocketOverPort;
+}
+
+function parseUrl(input: string | URL): string {
+  let url: URL;
+  try {
+    url = new URL(`${input}`, globalThis.location?.href);
+  } catch {
+    throw new DOMException(`The URL '${input}' is invalid.`, "SyntaxError");
+  }
+  if (url.protocol === "http:") url.protocol = "ws:";
+  else if (url.protocol === "https:") url.protocol = "wss:";
+  if (url.protocol !== "ws:" && url.protocol !== "wss:") {
+    throw new DOMException(
+      `The URL's scheme must be 'ws', 'wss', 'http' or 'https'; '${url.protocol.slice(0, -1)}' is not allowed.`,
+      "SyntaxError",
+    );
+  }
+  if (url.hash !== "" || `${input}`.includes("#")) {
+    throw new DOMException(
+      `The URL contains a fragment identifier ('${url.hash}'). Fragment identifiers are not allowed in WebSocket URLs.`,
+      "SyntaxError",
+    );
+  }
+  return url.href;
+}
+
+function validateProtocols(protocols: string[]): void {
+  const seen = new Set<string>();
+  for (const protocol of protocols) {
+    if (!TOKEN.test(protocol)) {
+      throw new DOMException(`The subprotocol '${protocol}' is invalid.`, "SyntaxError");
+    }
+    if (seen.has(protocol)) {
+      throw new DOMException(`The subprotocol '${protocol}' is duplicated.`, "SyntaxError");
+    }
+    seen.add(protocol);
+  }
+}

package/src/ws/frames.ts

@@ -0,0 +1,119 @@
+/**
+ * The wire protocol of a WebSocket carried over a `MessagePort`.
+ *
+ * A `MessagePort` is a natural carrier for a WebSocket: messages arrive in
+ * order, and strings and transferable `ArrayBuffer`s cross it as they are. The
+ * protocol on top is these frames, the same in both directions:
+ *
+ * - `m` — one message. An `ArrayBuffer` is transferred, never copied.
+ * - `c` — close. The side that closes first sends it; the other answers with
+ *   its own `c` (the echo), and both are then closed cleanly.
+ * - `p` — ping, client to server, carrying the client's heartbeat period.
+ * - `q` — pong, server to client.
+ * - `a` — ack: the receiver consumed `n` more bytes of messages. This is the
+ *   flow control: what a side has sent and not yet seen acknowledged is its
+ *   `bufferedAmount`, and the server end can wait for it to fall
+ *   (`whenDrained`). Added in version 2; version 1 had no backpressure.
+ *
+ * HEARTBEAT. A `MessagePort` never reports that the other side died, so the
+ * client pings every `hb` ms and closes with 1006 when pongs stop for `2·hb`;
+ * the server closes with 1006 when pings stop for `3·hb`. That is how a socket
+ * notices a closed tab or a terminated worker.
+ *
+ * Unknown frames are ignored, so a later version can add frames a peer of
+ * this version skips.
+ */
+
+/** The version of this frame protocol. Sent in the upgrade hand-shake. */
+export const WS_PORT_PROTOCOL_VERSION = 2;
+
+/** Default heartbeat period of the client, in ms. */
+export const DEFAULT_HEARTBEAT_MS = 10_000;
+
+/** How long a side waits for the echo of its close frame, in ms. */
+export const DEFAULT_CLOSE_TIMEOUT_MS = 5_000;
+
+export type WsFrame =
+  | { t: "m"; d: string | ArrayBuffer }
+  | { t: "c"; code: number; reason: string }
+  | { t: "p"; hb: number }
+  | { t: "q" }
+  | { t: "a"; n: number };
+
+/**
+ * The timer functions a socket uses. On a page's main thread, background
+ * throttling delays timers by up to a minute, which would close healthy
+ * sockets; pass unthrottled ones (worker-timers, say) there.
+ */
+export interface WsTimers {
+  setTimeout(fn: () => void, ms: number): unknown;
+  clearTimeout(id: unknown): void;
+  setInterval(fn: () => void, ms: number): unknown;
+  clearInterval(id: unknown): void;
+}
+
+export const defaultTimers: WsTimers = {
+  setTimeout: (fn, ms) => setTimeout(fn, ms),
+  clearTimeout: (id) => clearTimeout(id as ReturnType<typeof setTimeout>),
+  setInterval: (fn, ms) => setInterval(fn, ms),
+  clearInterval: (id) => clearInterval(id as ReturnType<typeof setInterval>),
+};
+
+/** Recovers a frame from a message's data, or `undefined` for anything else. */
+export function readFrame(data: unknown): WsFrame | undefined {
+  if (typeof data !== "object" || data === null) return undefined;
+  const frame = data as { t?: unknown; d?: unknown; code?: unknown; reason?: unknown };
+  switch (frame.t) {
+    case "m":
+      return typeof frame.d === "string" || frame.d instanceof ArrayBuffer
+        ? (frame as WsFrame)
+        : undefined;
+    case "c":
+      return {
+        t: "c",
+        code: typeof frame.code === "number" ? frame.code : 1005,
+        reason: typeof frame.reason === "string" ? frame.reason : "",
+      };
+    case "p": {
+      const hb = (frame as { hb?: unknown }).hb;
+      return { t: "p", hb: typeof hb === "number" && hb > 0 ? hb : DEFAULT_HEARTBEAT_MS };
+    }
+    case "q":
+      return { t: "q" };
+    case "a": {
+      const n = (frame as { n?: unknown }).n;
+      return typeof n === "number" && n >= 0 ? { t: "a", n } : undefined;
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** Posts `frame`, transferring a message's `ArrayBuffer`. */
+export function postFrame(port: MessagePort, frame: WsFrame): void {
+  if (frame.t === "m" && frame.d instanceof ArrayBuffer) port.postMessage(frame, [frame.d]);
+  else port.postMessage(frame);
+}
+
+/** The size a message counts for in `bufferedAmount`: UTF-8 bytes, or the buffer's length. */
+export function messageSize(data: string | ArrayBuffer): number {
+  return typeof data === "string" ? utf8Length(data) : data.byteLength;
+}
+
+/** The UTF-8 length of `text`, without encoding it. */
+export function utf8Length(text: string): number {
+  let length = 0;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code < 0x80) length += 1;
+    else if (code < 0x800) length += 2;
+    else if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) {
+      const next = text.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        length += 4;
+        i++;
+      } else length += 3;
+    } else length += 3;
+  }
+  return length;
+}

package/src/ws/index.ts

@@ -0,0 +1,11 @@
+export * from "./client.js";
+export {
+  DEFAULT_CLOSE_TIMEOUT_MS,
+  DEFAULT_HEARTBEAT_MS,
+  WS_PORT_PROTOCOL_VERSION,
+  type WsFrame,
+  type WsTimers,
+} from "./frames.js";
+export * from "./server.js";
+export { WsCloseEvent, type WsCloseEventInit } from "./socket-core.js";
+export * from "./upgrade.js";