@statewalker/webrun-http-browser 0.6.5 → 0.7.0

package/dist/ws/client.d.ts

@@ -0,0 +1,73 @@
+import { type WsTimers } from "./frames.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;
+}
+/**
+ * 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 declare function createWebSocketClass(connect: WebSocketConnector, options?: WebSocketClassOptions): PortWebSocketClass;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/ws/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/ws/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAa9E,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAEpG,MAAM,WAAW,qBAAqB;IACpC,iGAAiG;IACjG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,KAAK,QAAQ,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;AAEhD,qGAAqG;AACrG,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,QAAQ,CAAC;IACjB,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAClD,OAAO,EAAE,QAAQ,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,eAAe,GAAG,IAAI,GAAG,IAAI,CAAC;IACpE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,6DAA6D;IAC7D,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,aAAa,CAAC;IACtE,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;CACpB;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,qBAA0B,GAClC,kBAAkB,CAsNpB"}

package/dist/ws/frames.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 declare const WS_PORT_PROTOCOL_VERSION = 2;
+/** Default heartbeat period of the client, in ms. */
+export declare const DEFAULT_HEARTBEAT_MS = 10000;
+/** How long a side waits for the echo of its close frame, in ms. */
+export declare const DEFAULT_CLOSE_TIMEOUT_MS = 5000;
+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 declare const defaultTimers: WsTimers;
+/** Recovers a frame from a message's data, or `undefined` for anything else. */
+export declare function readFrame(data: unknown): WsFrame | undefined;
+/** Posts `frame`, transferring a message's `ArrayBuffer`. */
+export declare function postFrame(port: MessagePort, frame: WsFrame): void;
+/** The size a message counts for in `bufferedAmount`: UTF-8 bytes, or the buffer's length. */
+export declare function messageSize(data: string | ArrayBuffer): number;
+/** The UTF-8 length of `text`, without encoding it. */
+export declare function utf8Length(text: string): number;
+//# sourceMappingURL=frames.d.ts.map

package/dist/ws/frames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.d.ts","sourceRoot":"","sources":["../../src/ws/frames.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,qDAAqD;AACrD,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C,oEAAoE;AACpE,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C,MAAM,MAAM,OAAO,GACf;IAAE,CAAC,EAAE,GAAG,CAAC;IAAC,CAAC,EAAE,MAAM,GAAG,WAAW,CAAA;CAAE,GACnC;IAAE,CAAC,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,CAAC,EAAE,GAAG,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACtB;IAAE,CAAC,EAAE,GAAG,CAAA;CAAE,GACV;IAAE,CAAC,EAAE,GAAG,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1B;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,UAAU,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAChD,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,WAAW,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACjD,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;CAClC;AAED,eAAO,MAAM,aAAa,EAAE,QAK3B,CAAC;AAEF,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CA2B5D;AAED,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAGjE;AAED,8FAA8F;AAC9F,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAE9D;AAED,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAe/C"}

package/dist/ws/index.d.ts

@@ -0,0 +1,6 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/ws/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ws/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,wBAAwB,EACxB,KAAK,OAAO,EACZ,KAAK,QAAQ,GACd,MAAM,aAAa,CAAC;AACrB,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACvE,cAAc,cAAc,CAAC"}

package/dist/ws/server.d.ts

@@ -0,0 +1,53 @@
+import { type WsFrame, type WsTimers } from "./frames.js";
+import { PortSocketCore } from "./socket-core.js";
+export interface ServerWebSocketOptions {
+    /** The url the client asked for. */
+    url?: string;
+    /** The subprotocol the server picked, `""` for none. */
+    protocol?: string;
+    timers?: WsTimers;
+    /** How long `close()` waits for the client's echo, in ms. Default 5 s. */
+    closeTimeoutMs?: number;
+}
+/**
+ * The server end of a socket over a `MessagePort`: what a handler gets from
+ * `upgradeWebSocket` and talks to.
+ *
+ * - Events are delivered only after `accept()`; frames that arrive earlier are
+ *   queued. Pings are answered even before `accept()`, so a slow handler does
+ *   not look like a dead one.
+ * - Messages arrive as strings or `ArrayBuffer`s.
+ * - `bufferedAmount` counts what the client has not consumed yet, and
+ *   `whenDrained(limit)` waits for it to fall: the backpressure a producer
+ *   applies.
+ * - When the client's pings stop for three heartbeat periods (a closed tab, a
+ *   terminated worker), the socket closes with 1006.
+ */
+export declare class ServerWebSocket extends PortSocketCore {
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSING = 2;
+    static readonly CLOSED = 3;
+    readonly url: string;
+    readonly protocol: string;
+    private _accepted;
+    private _queue;
+    private _heartbeatMs;
+    private _lastPing;
+    private _watch;
+    constructor(port: MessagePort, options?: ServerWebSocketOptions);
+    /** Whether `accept()` was called. */
+    get accepted(): boolean;
+    /** Starts delivering events, the queued ones first. */
+    accept(): void;
+    send(data: string | ArrayBuffer | ArrayBufferView): void;
+    close(code?: number, reason?: string): void;
+    protected _deliver(frame: Extract<WsFrame, {
+        t: "m" | "c";
+    }>): void;
+    protected _dispatchMessage(data: string | ArrayBuffer): void;
+    protected _onPing(hb: number): void;
+    protected _onClosed(): void;
+    private _watchHeartbeat;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/ws/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/ws/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAML,cAAc,EAEf,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAgB,SAAQ,cAAc;IACjD,MAAM,CAAC,QAAQ,CAAC,UAAU,KAAc;IACxC,MAAM,CAAC,QAAQ,CAAC,IAAI,KAAQ;IAC5B,MAAM,CAAC,QAAQ,CAAC,OAAO,KAAW;IAClC,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAU;IAEhC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAiD;IAC/D,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,MAAM,CAAU;IAExB,YAAY,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE,sBAA2B,EAOlE;IAED,qCAAqC;IACrC,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,uDAAuD;IACvD,MAAM,IAAI,IAAI,CAIb;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,eAAe,GAAG,IAAI,CAKvD;IAED,KAAK,CAAC,IAAI,SAAO,EAAE,MAAM,SAAK,GAAG,IAAI,CAWpC;IAED,UAAmB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE;QAAE,CAAC,EAAE,GAAG,GAAG,GAAG,CAAA;KAAE,CAAC,GAAG,IAAI,CAM3E;IAED,SAAS,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAE3D;IAED,UAAmB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAO3C;IAED,UAAmB,SAAS,IAAI,IAAI,CAGnC;IAED,OAAO,CAAC,eAAe;CAQxB"}

package/dist/ws/socket-core.d.ts

@@ -0,0 +1,91 @@
+import { type WsFrame, type WsTimers } from "./frames.js";
+export declare const CONNECTING = 0;
+export declare const OPEN = 1;
+export declare const CLOSING = 2;
+export declare const CLOSED = 3;
+export interface WsCloseEventInit extends EventInit {
+    code?: number;
+    reason?: string;
+    wasClean?: boolean;
+}
+/**
+ * A `CloseEvent` for runtimes that have none: Node 22 has `Event` and
+ * `MessageEvent` as globals, but not `CloseEvent`.
+ */
+export declare class WsCloseEvent extends Event {
+    readonly code: number;
+    readonly reason: string;
+    readonly wasClean: boolean;
+    constructor(type: string, init?: WsCloseEventInit);
+}
+/** A `close` event: the platform's `CloseEvent` where there is one. */
+export declare function newCloseEvent(init: WsCloseEventInit): Event;
+export interface PortSocketOptions {
+    timers?: WsTimers;
+    /** How long to wait for the echo of a close frame before giving up with 1006. */
+    closeTimeoutMs?: number;
+}
+/**
+ * What both ends of a socket over a `MessagePort` share: the frames, the close
+ * handshake, and the byte accounting behind `bufferedAmount`.
+ *
+ * Not exported from the package: the two ends are `createWebSocketClass`'s
+ * class and `ServerWebSocket`.
+ */
+export declare abstract class PortSocketCore extends EventTarget {
+    protected _port?: MessagePort;
+    protected _state: number;
+    protected readonly _timers: WsTimers;
+    protected readonly _closeTimeoutMs: number;
+    /** Bytes sent and not yet acknowledged by the peer, plus those still being prepared. */
+    private _inFlight;
+    /** Bytes of messages "sent" after the socket started closing: counted, never sent. */
+    private _discarded;
+    private _toAck;
+    private _ackScheduled;
+    private _closeTimer;
+    private _drainWaiters;
+    constructor(options?: PortSocketOptions);
+    get readyState(): number;
+    /**
+     * Bytes queued by `send()` that the peer has not consumed yet. A peer
+     * acknowledges what it has dispatched, so this falls as the other side reads.
+     */
+    get bufferedAmount(): number;
+    /**
+     * Resolves once `bufferedAmount` is at most `limit` (default 0), or the
+     * socket is closed. The backpressure a producer applies:
+     * `if (socket.bufferedAmount > HIGH) await socket.whenDrained(LOW)`.
+     */
+    whenDrained(limit?: number): Promise<void>;
+    protected _attach(port: MessagePort): void;
+    protected _onFrame(frame: WsFrame): void;
+    /** A message or close frame the socket is ready to act on. */
+    protected _deliver(frame: Extract<WsFrame, {
+        t: "m" | "c";
+    }>): void;
+    protected abstract _dispatchMessage(data: string | ArrayBuffer): void;
+    protected _onPing(_hb: number): void;
+    protected _onPong(): void;
+    protected _onClosed(): void;
+    /** Acknowledge consumed bytes, coalescing the acks of one turn into one frame. */
+    protected _consumed(bytes: number): void;
+    /** Reserves `bytes` in `bufferedAmount` for a message still being prepared (a Blob). */
+    protected _reserve(bytes: number): void;
+    /** Sends one message whose bytes were reserved with `_reserve` (or `reserved = false`). */
+    protected _sendData(data: string | ArrayBuffer, reserved?: boolean): void;
+    protected _post(frame: WsFrame): void;
+    /** Starts the close handshake. */
+    protected _startClose(code: number, reason: string): void;
+    protected _onCloseFrame(code: number, reason: string): void;
+    /** The socket is closed: release the port and tell the listeners. */
+    protected _finish(code: number, reason: string, wasClean: boolean, error?: boolean): void;
+    private _wakeDrainWaiters;
+}
+/** Copies `data` into a fresh `ArrayBuffer`: `send()` must never detach the caller's buffer. */
+export declare function toArrayBuffer(data: ArrayBuffer | ArrayBufferView): ArrayBuffer;
+export declare function isBinary(data: unknown): data is ArrayBuffer | ArrayBufferView;
+export declare function isBlob(data: unknown): data is Blob;
+/** Valid close codes for an application to send: 1000, or 3000–4999. */
+export declare function isApplicationCloseCode(code: number): boolean;
+//# sourceMappingURL=socket-core.d.ts.map

package/dist/ws/socket-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-core.d.ts","sourceRoot":"","sources":["../../src/ws/socket-core.ts"],"names":[],"mappings":"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"}

package/dist/ws/upgrade.d.ts

@@ -0,0 +1,93 @@
+import { ServerWebSocket, type ServerWebSocketOptions } from "./server.js";
+/**
+ * The upgrade, as an HTTP exchange: a `GET` with `Upgrade: websocket` goes to
+ * an ordinary `(Request) => Response` handler, and a `101` answer carrying a
+ * server socket means accepted. Anything else is a refusal, with its status.
+ *
+ * FORBIDDEN HEADERS. A browser drops `Upgrade`, `Connection` and every
+ * `Sec-*` header from a `new Request()`. The upgrade request therefore carries
+ * its headers as an own `headers` property, a standalone `Headers` that keeps
+ * them, so handler code reads `request.headers.get("upgrade")` as usual.
+ *
+ * NO 101 IN A `Response`. The constructor refuses statuses below 200, so the
+ * response `upgradeWebSocket` returns reports 101 through an own `status`
+ * property; the port that goes back to the caller is found with `takePort`.
+ */
+/** The request header carrying the client's version of the frame protocol. */
+export declare const WS_VERSION_HEADER = "x-webrun-ws-version";
+export interface WebSocketUpgradeInit {
+    /** Requested subprotocols, in order of preference. */
+    protocols?: string[];
+    /** More headers for the handler to see (cookies, origin, authorization...). */
+    headers?: HeadersInit;
+}
+/**
+ * The `GET` a handler sees for `new WebSocket(url, protocols)`. A `ws:` or
+ * `wss:` url is given as `http:` or `https:`, as a server sees it.
+ */
+export declare function newWebSocketUpgradeRequest(url: string | URL, { protocols, headers }?: WebSocketUpgradeInit): Request;
+/**
+ * Re-attaches `headers` to `request` as its own `headers` property, keeping
+ * the forbidden ones a browser dropped. Returns `request`.
+ */
+export declare function withHeaders(request: Request, headers: Headers): Request;
+/** Whether `request` asks for a WebSocket. */
+export declare function isWebSocketUpgrade(request: Request): boolean;
+/** The subprotocols `request` asks for, in order of preference. */
+export declare function requestedProtocols(request: Request): string[];
+export interface UpgradeWebSocketOptions extends Omit<ServerWebSocketOptions, "url"> {
+}
+export interface WebSocketUpgrade {
+    /** The server end. Call `accept()`, then listen and send. */
+    socket: ServerWebSocket;
+    /** Return it from the handler: status 101. */
+    response: Response;
+}
+interface PendingUpgrade {
+    port: MessagePort;
+    protocol: string;
+}
+/**
+ * Accepts a WebSocket upgrade in a handler:
+ *
+ * ```ts
+ * if (isWebSocketUpgrade(request)) {
+ *   const { socket, response } = upgradeWebSocket(request, { protocol: "v1" });
+ *   socket.accept();
+ *   socket.addEventListener("message", (event) => socket.send(event.data));
+ *   return response;
+ * }
+ * ```
+ *
+ * The host takes the client's port from the response with `takePort` and
+ * hands it to the caller.
+ */
+export declare function upgradeWebSocket(request: Request, options?: UpgradeWebSocketOptions): WebSocketUpgrade;
+/**
+ * The port to hand to the caller, for a response from `upgradeWebSocket`.
+ * Taken once: a second call returns `undefined`.
+ */
+export declare function takePort(response: Response): MessagePort | undefined;
+/** `takePort`, with the subprotocol the server picked. */
+export declare function takeUpgrade(response: Response): PendingUpgrade | undefined;
+export type WebSocketUpgradeResult = {
+    ok: true;
+    port: MessagePort;
+    protocol: string;
+} | {
+    ok: false;
+    status: number;
+    message: string;
+};
+export interface ServeWebSocketUpgradeInit extends WebSocketUpgradeInit {
+    url: string;
+}
+/**
+ * Runs an upgrade through `handler`, as a host does when a caller asks for a
+ * socket: builds the upgrade request, calls the handler, and either takes the
+ * port of a `101` or reports the refusal. A subprotocol the caller did not ask
+ * for is a refusal, as in the standard.
+ */
+export declare function serveWebSocketUpgrade(handler: (request: Request) => Response | Promise<Response>, { url, protocols, headers }: ServeWebSocketUpgradeInit): Promise<WebSocketUpgradeResult>;
+export {};
+//# sourceMappingURL=upgrade.d.ts.map

package/dist/ws/upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/ws/upgrade.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE3E;;;;;;;;;;;;;GAaG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAEvD,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,EAAE,SAAc,EAAE,OAAO,EAAE,GAAE,oBAAyB,GACrD,OAAO,CAYT;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAGvE;AAED,8CAA8C;AAC9C,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,CAO7D;AAED,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,sBAAsB,EAAE,KAAK,CAAC;CAAG;AAEvF,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,MAAM,EAAE,eAAe,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAWD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CAelB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAEpE;AAED,0DAA0D;AAC1D,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,GAAG,SAAS,CAK1E;AAED,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,yBAA0B,SAAQ,oBAAoB;IACrE,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,EAC3D,EAAE,GAAG,EAAE,SAAc,EAAE,OAAO,EAAE,EAAE,yBAAyB,GAC1D,OAAO,CAAC,sBAAsB,CAAC,CA4BjC"}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@statewalker/webrun-http-browser",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
-  "description": "ServiceWorker-based HTTP server for browsers, with relay and same-origin dispatch modes",
+  "description": "ServiceWorker-based HTTP and WebSocket server for browsers: handlers in pages and Dedicated Workers, same-origin and relay modes, streams with backpressure",
   "bugs": {
     "url": "https://github.com/statewalker/webrun-wire/issues"
   },
@@ -40,6 +40,11 @@
       "types": "./dist/relay-worker.d.ts",
       "import": "./dist/relay-worker.js"
     },
+    "./worker": {
+      "source": "./src/worker.ts",
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js"
+    },
     "./sw-worker": {
       "default": "./dist/sw-worker.js"
     }
@@ -53,9 +58,9 @@
   ],
   "dependencies": {
     "idb-keyval": "^6.3.0",
-    "@statewalker/webrun-http-streams": "^0.2.5",
-    "@statewalker/webrun-streams": "^0.2.2",
-    "@statewalker/webrun-rpc": "^0.4.3"
+    "@statewalker/webrun-http-streams": "^0.3.0",
+    "@statewalker/webrun-rpc": "^0.5.0",
+    "@statewalker/webrun-streams": "^0.2.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",

package/src/core/data-calls.ts

@@ -1,4 +1,5 @@
 import { deserializeError, serializeError } from "@statewalker/webrun-streams";
+import { withDeadline } from "./deadline.js";
 import type { MessageSink, MessageSource } from "./message-target.js";
 
 export type ChannelCallHandler = (
@@ -7,6 +8,34 @@ export type ChannelCallHandler = (
   ...transfers: MessagePort[]
 ) => unknown;
 
+const TRANSFER = Symbol.for("webrun-http-browser:transfer");
+
+interface TransferResult {
+  [TRANSFER]: true;
+  value: unknown;
+  transfer: Transferable[];
+}
+
+/**
+ * A channel call's result that carries transferables, a `MessagePort` say:
+ * return `withTransfer({ port }, [port])` from a `handleChannelCalls` handler
+ * and `callChannel` resolves with `{ port }`.
+ */
+export function withTransfer<T>(value: T, transfer: Transferable[]): T {
+  return { [TRANSFER]: true, value, transfer } as unknown as T;
+}
+
+function isTransferResult(value: unknown): value is TransferResult {
+  return typeof value === "object" && value !== null && TRANSFER in value;
+}
+
+/** Splits a handler's result into the value to post and its transfer list. */
+export function unwrapTransfer(result: unknown): { value: unknown; transfer: Transferable[] } {
+  return isTransferResult(result)
+    ? { value: result.value, transfer: result.transfer }
+    : { value: result, transfer: [] };
+}
+
 export function callChannel<T = unknown>(
   target: MessageSink,
   callType: string,
@@ -33,14 +62,35 @@ export function handleChannelCalls(
     if (!event.data || event.data.type !== callType) return;
     const [port, ...transfers] = event.ports ?? [];
     const response: { result?: unknown; error?: unknown } = {};
+    let transfer: Transferable[] = [];
     try {
-      response.result = await handler(event, event.data.params, ...transfers);
+      const result = await handler(event, event.data.params, ...transfers);
+      ({ value: response.result, transfer } = unwrapTransfer(result));
     } catch (error) {
       response.error = serializeError(error);
     }
-    port?.postMessage(response);
+    port?.postMessage(response, transfer);
   };
   target.addEventListener("message", listener);
   target.start?.();
   return () => target.removeEventListener("message", listener);
 }
+
+/**
+ * `callChannel`, failing after `ms` instead of waiting for ever: a peer that
+ * died (a ServiceWorker stopped mid-call) or that does not know `callType` (an
+ * older version) never answers.
+ */
+export function callChannelWithin<T = unknown>(
+  ms: number,
+  target: MessageSink,
+  callType: string,
+  params: unknown,
+  ...transfers: Transferable[]
+): Promise<T> {
+  return withDeadline(
+    Date.now() + ms,
+    callChannel<T>(target, callType, params, ...transfers),
+    () => new Error(`No answer to ${callType} within ${ms} ms`),
+  );
+}

package/src/core/service-worker-control.ts

@@ -26,8 +26,14 @@ export const CLAIM_CALL = "CLAIM";
  * - `uncontrolled`: the worker is active but the page is not controlled by it.
  * - `unresponsive`: the page is controlled, but the worker did not answer the
  *   adapter's handshake in time.
+ * - `incompatible`: the worker answered, but runs another version of this
+ *   package's link protocol.
  */
-export type ServiceWorkerControlFailure = "activation-timeout" | "uncontrolled" | "unresponsive";
+export type ServiceWorkerControlFailure =
+  | "activation-timeout"
+  | "uncontrolled"
+  | "unresponsive"
+  | "incompatible";
 
 /**
  * Why a page could not get a working ServiceWorker. `reason` says which wait

package/src/index.ts

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

package/src/link/errors.ts

@@ -0,0 +1,3 @@
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}