@statewalker/webrun-http-browser 0.10.0 → 0.12.2

package/dist/ws/frames.d.ts

@@ -63,6 +63,11 @@ export declare function readFrame(data: unknown): WsFrame | undefined;
 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. */
+/**
+ * The UTF-8 length of `text`, as `TextEncoder` would encode it (a lone surrogate counts as the 3
+ * bytes of U+FFFD). Every message is measured on both ends (`bufferedAmount` and the byte acks), so
+ * this runs natively: `encodeInto` a reused buffer, a chunk at a time, never splitting a surrogate
+ * pair across two chunks. A loop over the characters in JavaScript took about 30 times as long.
+ */
 export declare function utf8Length(text: string): number;
 //# sourceMappingURL=frames.d.ts.map

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

@@ -1 +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"}
+{"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;AAOD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAW/C"}

package/dist/ws/server.d.ts

@@ -6,8 +6,35 @@ export interface ServerWebSocketOptions {
     /** 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. */
+    /** How long `close()` waits for the client's echo, in ms. Default 5 s; `Infinity` for ever. */
     closeTimeoutMs?: number;
+    /**
+     * When the heartbeat watch starts: `"open"` (the default) at once, so a client that never
+     * pings is closed with 1006 after three default periods; `"first-ping"` with the client's
+     * first ping, so a peer that does not ping at all (the other end of a pair kept in the same
+     * realm, say) is never closed for it. Once pings have started, both close a socket whose
+     * pings stop. Under `"first-ping"` a peer that never pings is never found dead.
+     */
+    watch?: "open" | "first-ping";
+    /**
+     * Which heartbeat period the watch keeps: `"follow"` (the default) the one each ping
+     * announces, `"first"` the first ping's. A client announces a longer period when its page
+     * turns hidden (browsers throttle hidden pages' timers), and a closing tab turns hidden on its
+     * way out: following it notices a dead tab only after three of the longer periods.
+     */
+    heartbeatPeriod?: "follow" | "first";
+    /** Lets `send()` before `accept()`; the frames wait in the port until the peer reads. */
+    sendBeforeAccept?: boolean;
+    /**
+     * Delivers the messages that arrive after `close()` until the peer's close frame does (they
+     * were in flight), as workerd does. By default they are dropped, as browsers do.
+     */
+    deliverWhileClosing?: boolean;
+    /**
+     * The code `close()` sends when given none. Default 1000. 1005 ("no status code") is what a
+     * close frame without a code reads as on the other end, as `close()` does on workerd.
+     */
+    defaultCloseCode?: number;
 }
 /**
  * The server end of a socket over a `MessagePort`: what a handler gets from
@@ -21,7 +48,8 @@ export interface ServerWebSocketOptions {
  *   `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.
+ *   terminated worker), the socket closes with 1006. With `watch: "first-ping"`
+ *   the watch starts only once the client pings.
  */
 export declare class ServerWebSocket extends PortSocketCore {
     static readonly CONNECTING = 0;
@@ -30,18 +58,38 @@ export declare class ServerWebSocket extends PortSocketCore {
     static readonly CLOSED = 3;
     readonly url: string;
     readonly protocol: string;
+    private _binaryType;
+    private readonly _options;
     private _accepted;
+    private _detached;
     private _queue;
     private _heartbeatMs;
     private _lastPing;
+    /** Whether a ping (with a period a timer takes) arrived already. */
+    private _pinged;
     private _watch;
     constructor(port: MessagePort, options?: ServerWebSocketOptions);
     /** Whether `accept()` was called. */
     get accepted(): boolean;
+    /** How binary messages arrive: `ArrayBuffer`s (the default) or `Blob`s. Other values are ignored. */
+    get binaryType(): "blob" | "arraybuffer";
+    set binaryType(value: "blob" | "arraybuffer");
+    /**
+     * Hands this end's transport to another holder before it was accepted: the port to give the
+     * client (a pair's end returned in a 101, say), with the frames that reached this end first
+     * delivered ahead of the rest. This end is closed then, with no event, and answers nothing.
+     */
+    detach(): MessagePort;
     /** Starts delivering events, the queued ones first. */
     accept(): void;
     send(data: string | ArrayBuffer | ArrayBufferView): void;
     close(code?: number, reason?: string): void;
+    /**
+     * Refuses a `close()` the endpoint may not make: by default a code outside RFC 6455 §7.4's
+     * sendable ones, or a reason over 123 bytes. A subclass with another platform's rules
+     * overrides it.
+     */
+    protected checkClose(code: number | undefined, reason: string): void;
     protected _deliver(frame: Extract<WsFrame, {
         t: "m" | "c";
     }>): void;

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

@@ -1 +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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/ws/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,OAAO,EACZ,KAAK,QAAQ,EACd,MAAM,aAAa,CAAC;AACrB,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,+FAA+F;IAC/F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC9B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IACrC,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;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,WAAW,CAAyC;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAiD;IAC/D,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,SAAS,CAAc;IAC/B,oEAAoE;IACpE,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAU;IAExB,YAAY,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE,sBAA2B,EAQlE;IAED,qCAAqC;IACrC,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,qGAAqG;IACrG,IAAI,UAAU,IAAI,MAAM,GAAG,aAAa,CAEvC;IACD,IAAI,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,EAE3C;IAED;;;;OAIG;IACH,MAAM,IAAI,WAAW,CA0DpB;IAED,uDAAuD;IACvD,MAAM,IAAI,IAAI,CAOb;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,eAAe,GAAG,IAAI,CAQvD;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,IAAI,CAGtC;IAED;;;;OAIG;IACH,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAUnE;IAED,UAAmB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE;QAAE,CAAC,EAAE,GAAG,GAAG,GAAG,CAAA;KAAE,CAAC,GAAG,IAAI,CAW3E;IAED,SAAS,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAI3D;IAED,UAAmB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAoB3C;IAED,UAAmB,SAAS,IAAI,IAAI,CAGnC;IAED,OAAO,CAAC,eAAe;CAQxB"}

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

@@ -22,7 +22,10 @@ export declare class WsCloseEvent extends Event {
 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. */
+    /**
+     * How long to wait for the echo of a close frame before giving up with 1006. `Infinity` waits
+     * for as long as it takes.
+     */
     closeTimeoutMs?: number;
 }
 /**
@@ -80,7 +83,7 @@ export declare abstract class PortSocketCore extends EventTarget {
     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;
+    protected _wakeDrainWaiters(): void;
 }
 /** Copies `data` into a fresh `ArrayBuffer`: `send()` must never detach the caller's buffer. */
 export declare function toArrayBuffer(data: ArrayBuffer | ArrayBufferView): ArrayBuffer;

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

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

@@ -18,7 +18,11 @@ 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...). */
+    /**
+     * More headers for the handler to see (what a `route` function picks by, origin...). They are
+     * the caller's word: nothing checks them, so a handler trusts a `cookie` or an `authorization`
+     * here no more than its caller. `sec-websocket-protocol` comes from `protocols` only.
+     */
     headers?: HeadersInit;
 }
 /**
@@ -63,6 +67,13 @@ interface PendingUpgrade {
  * hands it to the caller.
  */
 export declare function upgradeWebSocket(request: Request, options?: UpgradeWebSocketOptions): WebSocketUpgrade;
+/**
+ * A 101 for a socket whose server end the handler runs itself, on the other end of `port`
+ * (a server of its own over this package's frames, say): what `upgradeWebSocket` returns, minus
+ * the `ServerWebSocket`. The host hands `port` to the caller as it would for `upgradeWebSocket`
+ * (`takePort`), and `protocol` (`""` for none) is the subprotocol picked.
+ */
+export declare function webSocketUpgradeResponse(port: MessagePort, protocol?: string): Response;
 /**
  * The port to hand to the caller, for a response from `upgradeWebSocket`.
  * Taken once: a second call returns `undefined`.

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

@@ -1 +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"}
+{"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;;;;OAIG;IACH,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,CAeT;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,CAOlB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,SAAK,GAAG,QAAQ,CAWnF;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,6 +1,6 @@
 {
   "name": "@statewalker/webrun-http-browser",
-  "version": "0.10.0",
+  "version": "0.12.2",
   "private": false,
   "type": "module",
   "description": "ServiceWorker-based HTTP and WebSocket server for browsers: handlers in pages and Dedicated Workers, same-origin and relay modes, streams with backpressure",
@@ -58,9 +58,9 @@
   ],
   "dependencies": {
     "idb-keyval": "^6.3.0",
-    "@statewalker/webrun-rpc": "^0.8.0",
-    "@statewalker/webrun-streams": "^0.2.3",
-    "@statewalker/webrun-http-streams": "^0.4.0"
+    "@statewalker/webrun-http-streams": "^0.4.0",
+    "@statewalker/webrun-rpc": "^0.10.0",
+    "@statewalker/webrun-streams": "^0.2.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",
@@ -80,6 +80,7 @@
   "scripts": {
     "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
     "test": "vitest run",
+    "bench": "vitest run --config vitest.bench.config.ts && echo \"all benchmarks passed\"",
     "test:browser": "pnpm run build && vitest run --config vitest.browser.config.ts",
     "lint": "biome check src tests",
     "serve": "http-server -p 5173 -c-1 -s .",

package/src/core/index.ts

@@ -8,3 +8,4 @@ export * from "./data-channels.js";
 export * from "./message-target.js";
 export * from "./registry.js";
 export * from "./service-worker-control.js";
+export type { FetchEventLike, ServiceWorkerClientLike, ServiceWorkerScope } from "./sw-scope.js";

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

@@ -2,6 +2,7 @@
 
 import { callChannel, handleChannelCalls } from "./data-calls.js";
 import { withDeadline } from "./deadline.js";
+import type { ServiceWorkerScope } from "./sw-scope.js";
 
 /**
  * How long, by default, the page waits for its ServiceWorker to activate and
@@ -167,9 +168,10 @@ export async function awaitServiceWorkerControl(
  * `clients.claim()`, which takes over every uncontrolled client in scope.
  * Returns a function that stops answering.
  */
-export function handleClaimRequests(self: ServiceWorkerGlobalScope): () => void {
-  return handleChannelCalls(self, CLAIM_CALL, (event) => {
-    const claimed = self.clients.claim().then(() => true);
+export function handleClaimRequests(self: ServiceWorkerScope): () => void {
+  const sw = self as unknown as ServiceWorkerGlobalScope;
+  return handleChannelCalls(sw, CLAIM_CALL, (event) => {
+    const claimed = sw.clients.claim().then(() => true);
     (event as unknown as Partial<ExtendableMessageEvent>).waitUntil?.(claimed);
     return claimed;
   });

package/src/core/sw-scope.ts

@@ -0,0 +1,27 @@
+/**
+ * A ServiceWorker's global scope, as this package's API takes it: structurally, so that code
+ * importing the package's declarations compiles with the DOM lib alone. TypeScript's
+ * `ServiceWorkerGlobalScope` is in the WebWorker lib, which a page's or a library's
+ * compilation does not load. A ServiceWorker's `self` is one.
+ */
+export interface ServiceWorkerScope extends EventTarget {
+  readonly location: { readonly href: string; readonly origin: string };
+  readonly registration?: { readonly scope: string };
+  readonly clients: unknown;
+  skipWaiting(): Promise<void>;
+}
+
+/** A ServiceWorker's `fetch` event, structurally (see `ServiceWorkerScope`). */
+export interface FetchEventLike extends Event {
+  readonly request: Request;
+  respondWith(response: Response | PromiseLike<Response>): void;
+}
+
+/**
+ * A ServiceWorker's client (a page or a worker it controls), structurally (see
+ * `ServiceWorkerScope`). A `Client` is one.
+ */
+export interface ServiceWorkerClientLike {
+  readonly id: string;
+  readonly url: string;
+}

package/src/link/http-link.ts

@@ -8,8 +8,11 @@ import { asyncDisposable } from "./async-dispose.js";
  * own `handleStreams` / `sendStream` (no backpressure); version 2 is
  * webrun-rpc's `connect` / `serve` over `overPipe` with webrun-http-streams'
  * `fetchOverDuplex` / `serveFetchOverDuplex`: one port per link, calls
- * multiplexed on it, each call a stream with a one-chunk window in both
- * directions, and cancellation that reaches the handler.
+ * multiplexed on it, each call a stream with backpressure in both
+ * directions, and cancellation that reaches the handler. A call's port with a
+ * window (`HttpLinkOptions.window`) pipelines its chunks where both ends speak
+ * it, and goes one confirmed chunk at a time otherwise, so the window needs
+ * no new version.
  */
 export const HTTP_LINK_PROTOCOL = "webrun-http-link/2";
 
@@ -34,8 +37,21 @@ export interface HttpLinkOptions {
    * reads the upload afterwards keeps it as long as it keeps reading.
    */
   requestIdleMs?: number;
+  /**
+   * The calling end only: the flow-control window, in bytes, that every
+   * request's port asks for (webrun-rpc's `window`; default 256 KiB). On it,
+   * request and response bodies are pipelined: chunks leave without waiting
+   * for a confirmation each, and a reader that stops holds about one window
+   * of them. `0` turns the window off: one confirmed chunk at a time, the
+   * envelopes of a link with no window. An answering end of an older version
+   * falls back to that by itself.
+   */
+  window?: number;
 }
 
+/** The calling end's default `HttpLinkOptions.window`: 256 KiB. */
+const DEFAULT_HTTP_LINK_WINDOW = 256 * 1024;
+
 /** The calling end of a link: sends requests, gets responses. */
 export interface HttpLink {
   /** Sends `request` and resolves with the response, whose body streams. */
@@ -77,10 +93,10 @@ const LINK_CLOSE = "webrun-http:link-close";
 /** Opens the calling end of a link on `port` (one port per link). */
 export async function connectHttpLink(
   port: MessagePort,
-  { streamTimeout, maxPorts }: HttpLinkOptions = {},
+  { streamTimeout, maxPorts, window = DEFAULT_HTTP_LINK_WINDOW }: HttpLinkOptions = {},
 ): Promise<HttpLink> {
   const { call, close } = await connect({
-    mux: overPipe(port, { codec: structuredCodec, side: "initiator", maxPorts }),
+    mux: overPipe(port, { codec: structuredCodec, side: "initiator", maxPorts, window }),
     timeout: streamTimeout,
   });
   return trackedLink(

package/src/relay/index-sw.ts

@@ -3,6 +3,7 @@ import { get, set } from "idb-keyval";
 import { callChannel, handleChannelCalls, withTransfer } from "../core/data-calls.js";
 import { newRegistry } from "../core/registry.js";
 import { handleClaimRequests } from "../core/service-worker-control.js";
+import type { ServiceWorkerClientLike, ServiceWorkerScope } from "../core/sw-scope.js";
 import { HTTP_LINK_PROTOCOL } from "../link/http-link.js";
 import { WS_CONNECT_CALL } from "../sw/protocol.js";
 import type { WebSocketConnection } from "../ws/client.js";
@@ -137,9 +138,18 @@ export interface RelayServiceWorkerOptions {
    * mount an allowed key at `/index.html` and outrank `/` on longest-prefix.
    * Also consulted for `UNREGISTER`, with the path the key is mounted at.
    */
-  canRegister?: (client: Client, key: string, path?: string) => boolean | Promise<boolean>;
+  canRegister?: (
+    client: ServiceWorkerClientLike,
+    key: string,
+    path?: string,
+  ) => boolean | Promise<boolean>;
   /** Per-stream inactivity timeout of the links to services, in ms. Default none. */
   streamTimeout?: number;
+  /**
+   * The window, in bytes, of the links to services: `HttpLinkOptions.window`.
+   * Default 256 KiB; 0 turns it off.
+   */
+  window?: number;
   /** Default `"last-wins"`, the behaviour before this option existed. */
   takeover?: "first-wins" | "last-wins";
   /** Stamp headers on responses the relay makes. Not applied to network fetches. */
@@ -171,9 +181,11 @@ export function mayRegister(args: {
  * channel calls used by the page-side relay client.
  */
 export function startRelayServiceWorker(
-  self: ServiceWorkerGlobalScope,
+  scope: ServiceWorkerScope,
   options: RelayServiceWorkerOptions = {},
 ): () => void {
+  // Typed structurally in the signature so the declarations need no WebWorker lib.
+  const self = scope as unknown as ServiceWorkerGlobalScope;
   const [register, clear] = newRegistry();
   const mounts = newMountTable({ exclude: options.exclude });
   // The keys the HOST declared. Kept so a page's REGISTER/UNREGISTER cannot
@@ -339,6 +351,7 @@ export function startRelayServiceWorker(
       if (!reply) throw HttpError.errorForbidden(params);
       const response = await sendOverConnection(channel.port1, reply, request, {
         streamTimeout: options.streamTimeout,
+        window: options.window,
       });
       return options.decorateResponse?.(response, request) ?? response;
     } catch (error) {

package/src/relay/index.ts

@@ -180,7 +180,7 @@ export async function initHttpService(
  */
 export async function callHttpService(
   request: Request,
-  { key, port, streamTimeout }: ServiceOptions,
+  { key, port, streamTimeout, window }: ServiceOptions,
 ): Promise<Response> {
   const channel = new MessageChannel();
   const reply = await callChannel<boolean | ConnectReply>(
@@ -193,7 +193,7 @@ export async function callHttpService(
     channel.port1.close();
     throw new Error(`No service with key "${key}"`);
   }
-  return await sendOverConnection(channel.port1, reply, request, { streamTimeout });
+  return await sendOverConnection(channel.port1, reply, request, { streamTimeout, window });
 }
 
 /**

package/src/relay-worker.ts

@@ -15,6 +15,7 @@
  * import.
  */
 
+export type { ServiceWorkerClientLike, ServiceWorkerScope } from "./core/sw-scope.js";
 export type { RelayServiceWorkerOptions } from "./relay/index-sw.js";
 export { startRelayServiceWorker } from "./relay/index-sw.js";
 export type { MountSpec } from "./relay/mount-table.js";

package/src/sw/handler-endpoint.ts

@@ -10,7 +10,7 @@ import { watchLock } from "../link/locks.js";
 import { PortRendezvous } from "../link/rendezvous.js";
 import type { WebSocketConnection } from "../ws/client.js";
 import { serveWebSocketUpgrade } from "../ws/upgrade.js";
-import type { ControlMessage } from "./protocol.js";
+import { type ControlMessage, headerPairs } from "./protocol.js";
 
 export type FetchHandler = (request: Request) => Response | Promise<Response>;
 
@@ -142,8 +142,15 @@ export class HandlerEndpoint {
     return await (link.up as HttpLink).send(request);
   }
 
-  /** Opens a socket to the handler `url` routes to, through the ServiceWorker. */
-  async connectWebSocket(url: string, protocols: string[] = []): Promise<WebSocketConnection> {
+  /**
+   * Opens a socket to the handler `url` routes to, through the ServiceWorker. The handler sees
+   * `headers` on the upgrade request, and so does a `route` function choosing it.
+   */
+  async connectWebSocket(
+    url: string,
+    protocols: string[] = [],
+    headers?: HeadersInit,
+  ): Promise<WebSocketConnection> {
     const link = await this._linkWith("ctl");
     const id = this._sockets.newId();
     const answer = this._sockets.wait(
@@ -151,7 +158,13 @@ export class HandlerEndpoint {
       this.options.wsConnectTimeoutMs ?? 15_000,
       `the socket request for ${url}`,
     );
-    link.ctl?.postMessage({ t: "ws-open", id, url, protocols } satisfies ControlMessage);
+    link.ctl?.postMessage({
+      t: "ws-open",
+      id,
+      url,
+      protocols,
+      headers: headerPairs(headers),
+    } satisfies ControlMessage);
     return await answer;
   }