@statewalker/webrun-http-browser 0.6.4 → 0.7.0

package/dist/link/errors.d.ts

@@ -0,0 +1,2 @@
+export declare function errorMessage(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/link/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/link/errors.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnD"}

package/dist/link/http-link.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The version of the HTTP-over-`MessagePort` protocol this package speaks,
+ * sent in every hand-shake that sets up a link. Version 1 was this package's
+ * 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.
+ */
+export declare const HTTP_LINK_PROTOCOL = "webrun-http-link/2";
+export interface HttpLinkOptions {
+    /**
+     * Per-stream inactivity timeout in ms (webrun-rpc's): a stream with no chunk
+     * in either direction for that long fails. Unset — the default — means
+     * none: a slow consumer is throttled, never failed.
+     */
+    streamTimeout?: number;
+}
+/** The calling end of a link: sends requests, gets responses. */
+export interface HttpLink {
+    /** Sends `request` and resolves with the response, whose body streams. */
+    send(request: Request): Promise<Response>;
+    /**
+     * Requests whose response has not finished yet: still waiting for the head,
+     * or with a body still streaming.
+     */
+    readonly inflight: number;
+    /** Resolves when `inflight` falls to 0. */
+    whenIdle(): Promise<void>;
+    /**
+     * Closes the link. Requests in flight fail with `reason` (default: the link
+     * was closed) instead of hanging.
+     */
+    close(reason?: Error): Promise<void>;
+    readonly closed: boolean;
+}
+/**
+ * Why a request failed when its link went away under it: the far side (the
+ * handler, or the ServiceWorker) was lost. The request may or may not have
+ * been applied.
+ */
+export declare class LinkLostError extends Error {
+    constructor(message?: string);
+}
+/** Opens the calling end of a link on `port` (one port per link). */
+export declare function connectHttpLink(port: MessagePort, { streamTimeout }?: HttpLinkOptions): Promise<HttpLink>;
+/**
+ * Serves `handler` on the answering end of a link. Resolves with a teardown
+ * that abandons the requests still running (their handlers see the
+ * cancellation) and releases the port.
+ */
+export declare function serveHttpLink(port: MessagePort, handler: (request: Request) => Response | Promise<Response>, { streamTimeout }?: HttpLinkOptions): Promise<() => Promise<void>>;
+/**
+ * Wraps a `send` so the link knows its requests in flight (for draining and
+ * load-based routing) and can fail them all at once when it is closed.
+ */
+export declare function trackedLink(send: (request: Request) => Promise<Response>, release: () => Promise<void> | void): HttpLink;
+//# sourceMappingURL=http-link.d.ts.map

package/dist/link/http-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-link.d.ts","sourceRoot":"","sources":["../../src/link/http-link.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,iEAAiE;AACjE,MAAM,WAAW,QAAQ;IACvB,0EAA0E;IAC1E,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2CAA2C;IAC3C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAO,SAAuD,EAGzE;CACF;AASD,qEAAqE;AACrE,wBAAsB,eAAe,CACnC,IAAI,EAAE,WAAW,EACjB,EAAE,aAAa,EAAE,GAAE,eAAoB,GACtC,OAAO,CAAC,QAAQ,CAAC,CAcnB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,EAC3D,EAAE,aAAa,EAAE,GAAE,eAAoB,GACtC,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAiB9B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAC7C,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAClC,QAAQ,CAuEV"}

package/dist/link/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./http-link.js";
+export { holdLock, locksAvailable, newLockName, watchLock } from "./locks.js";
+export { PortRendezvous } from "./rendezvous.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/link/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/link/locks.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Liveness through Web Locks.
+ *
+ * A `MessagePort` never reports that the other side died, but a Web Lock
+ * does: a lock held by a page, a worker or a ServiceWorker is released by the
+ * browser the moment that context goes away, and a request waiting for it is
+ * granted then. So each side that must notice the other's death holds a lock
+ * of its own and watches the other's:
+ *
+ * - a handler holds an owner lock; the ServiceWorker watches it, and fails the
+ *   handler's requests in flight when it is granted (the tab closed, the
+ *   worker was terminated);
+ * - the ServiceWorker holds a router lock; handlers watch it, and fail their
+ *   calls through it when it is granted (the browser stopped the worker).
+ *
+ * Every function here degrades to a no-op where `navigator.locks` is missing.
+ */
+export declare function locksAvailable(): boolean;
+/** A fresh lock name: `<prefix>:<uuid>`. */
+export declare function newLockName(prefix: string): string;
+/**
+ * Takes the lock `name` and holds it until the returned release is called or
+ * this context dies. Resolves once the lock is held; with no Web Locks,
+ * resolves at once.
+ */
+export declare function holdLock(name: string): Promise<() => void>;
+/**
+ * Calls `onLost` once the lock `name` is granted to this context — that is,
+ * once whoever holds it is gone — and releases it at once. Returns a function
+ * that stops watching. With no Web Locks, never calls `onLost`.
+ */
+export declare function watchLock(name: string, onLost: () => void): () => void;
+/**
+ * The names of the locks held right now in this origin, or `undefined` where
+ * that cannot be asked. A backup for `watchLock`: a grant can be late, a query
+ * cannot.
+ */
+export declare function heldLockNames(): Promise<Set<string> | undefined>;
+//# sourceMappingURL=locks.d.ts.map

package/dist/link/locks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locks.d.ts","sourceRoot":"","sources":["../../src/link/locks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAeH,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED,4CAA4C;AAC5C,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAgBhE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAYtE;AAED;;;;GAIG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,CAStE"}

package/dist/link/rendezvous.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Matches replies to requests by id, for the control messages that hand
+ * WebSocket ports across: each waiting request has a deadline, and all of a
+ * peer's waiting requests can be failed at once when the peer is lost.
+ */
+export declare class PortRendezvous<T> {
+    private readonly _prefix;
+    private readonly _waiting;
+    private _counter;
+    constructor(_prefix?: string);
+    /** A fresh id for a request. */
+    newId(): string;
+    get size(): number;
+    /** Waits for the reply to `id`, failing after `timeoutMs`. */
+    wait(id: string, timeoutMs: number, describe?: string): Promise<T>;
+    /** Delivers the reply to `id`. `false` when nobody waits for it (it timed out). */
+    settle(id: string, value: T): boolean;
+    fail(id: string, error: Error): void;
+    failAll(error: Error): void;
+}
+//# sourceMappingURL=rendezvous.d.ts.map

package/dist/link/rendezvous.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rendezvous.d.ts","sourceRoot":"","sources":["../../src/link/rendezvous.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,cAAc,CAAC,CAAC;IAWf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAVpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAOrB;IACJ,OAAO,CAAC,QAAQ,CAAK;IAErB,YAA6B,OAAO,SAAM,EAAI;IAE9C,gCAAgC;IAChC,KAAK,IAAI,MAAM,CAEd;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,8DAA8D;IAC9D,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,SAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAQtE;IAED,mFAAmF;IACnF,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAOpC;IAED,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAMnC;IAED,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAE1B;CACF"}

package/dist/relay/index-sw.d.ts

@@ -62,8 +62,18 @@ export interface RelayServiceWorkerOptions {
     } & MountSpec>;
     /** Paths the relay never claims. Checked before the table. */
     exclude?: (url: URL) => boolean;
-    /** Refuse a registration from the wrong client. Default: everyone may. */
-    canRegister?: (client: Client, key: string) => boolean | Promise<boolean>;
+    /**
+     * Refuse a registration from the wrong client. Default: everyone may.
+     *
+     * `path` is where the registrant asks to be mounted (`undefined` for the
+     * `/~<key>/` addressing), so a host can vet where a key lands, not only who
+     * takes it: on an origin whose name is not a secret, a page could otherwise
+     * 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>;
+    /** Per-stream inactivity timeout of the links to services, in ms. Default none. */
+    streamTimeout?: 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. */

package/dist/relay/index-sw.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index-sw.d.ts","sourceRoot":"","sources":["../../src/relay/index-sw.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAiB,MAAM,kBAAkB,CAAC;AAGlF,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAM5E;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,SAAS,CAUpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,EACvB,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GACxC,IAAI,CAON;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GACxC,IAAI,CAGN;AAED,MAAM,WAAW,yBAAyB;IACxC,uEAAuE;IACvE,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IAC5C,8DAA8D;IAC9D,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;IAChC,0EAA0E;IAC1E,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1E,uEAAuE;IACvE,QAAQ,CAAC,EAAE,YAAY,GAAG,WAAW,CAAC;IACtC,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,KAAK,QAAQ,CAAC;CACvE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,YAAY,GAAG,WAAW,CAAC;CACtC,GAAG,OAAO,CAIV;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,wBAAwB,EAC9B,OAAO,GAAE,yBAA8B,GACtC,MAAM,IAAI,CAwJZ"}
+{"version":3,"file":"index-sw.d.ts","sourceRoot":"","sources":["../../src/relay/index-sw.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAiB,MAAM,kBAAkB,CAAC;AAGlF,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAM5E;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,SAAS,CAUpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,EACvB,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GACxC,IAAI,CAON;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GACxC,IAAI,CAGN;AAED,MAAM,WAAW,yBAAyB;IACxC,uEAAuE;IACvE,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IAC5C,8DAA8D;IAC9D,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;IAChC;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzF,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,YAAY,GAAG,WAAW,CAAC;IACtC,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,KAAK,QAAQ,CAAC;CACvE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,YAAY,GAAG,WAAW,CAAC;CACtC,GAAG,OAAO,CAIV;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,wBAAwB,EAC9B,OAAO,GAAE,yBAA8B,GACtC,MAAM,IAAI,CAmNZ"}

package/dist/relay/index.d.ts

@@ -1,5 +1,7 @@
 import type { HttpHandler } from "@statewalker/webrun-http-streams";
 import type { MessageTarget } from "../core/message-target.js";
+import { type HttpLinkOptions } from "../link/http-link.js";
+import { type PortWebSocketClass, type WebSocketClassOptions, type WebSocketConnection } from "../ws/client.js";
 export * from "./split-service-url.js";
 /**
  * Returns a MessagePort that transparently bridges messages to/from the
@@ -28,7 +30,7 @@ export interface InitServiceWorkerOptions {
  * `ServiceWorkerControlError` if activation takes longer than `timeout`.
  */
 export declare function initServiceWorker(options: InitServiceWorkerOptions): Promise<ServiceWorker>;
-export interface ServiceOptions {
+export interface ServiceOptions extends HttpLinkOptions {
     key: string;
     /**
      * Where this service is mounted on the relay origin, e.g. `/` or `/peers/`.
@@ -38,15 +40,60 @@ export interface ServiceOptions {
     port: MessageTarget;
 }
 /**
- * Registers `handler` as the server for the given service `key` on the relay.
- * Returns a cleanup function that unregisters the service.
+ * What a service answers to a `CONNECT` that speaks `HTTP_LINK_PROTOCOL`. A
+ * service of version 1 answers `true` instead, and the caller then falls back
+ * to version 1's transport: both ends of a call must speak the same one, and
+ * the relay, the caller and the service may each run another version.
  */
-export declare function initHttpService(handler: HttpHandler, { key, path, port }: ServiceOptions): Promise<() => void>;
+export interface ConnectReply {
+    accepted: true;
+    wire: string;
+}
+/** A `CONNECT` asking a service for a socket. */
+export interface WebSocketConnectParams {
+    type: "ws";
+    key: string;
+    url: string;
+    protocols?: string[];
+    headers?: [string, string][];
+}
+/**
+ * Serves a service's side of one `CONNECT`: an HTTP link on `callPort`, or a
+ * WebSocket upgrade run through `handler`.
+ */
+export declare function answerConnect(handler: HttpHandler, data: unknown, callPort: MessagePort | undefined, options?: HttpLinkOptions): Promise<unknown>;
+/**
+ * Registers `handler` as the server for the given service `key` on the relay:
+ * it answers HTTP requests and WebSocket upgrades. Returns a function that
+ * unregisters the service; its promise settles once the relay acknowledged.
+ */
+export declare function initHttpService(handler: HttpHandler, { key, path, port, streamTimeout }: ServiceOptions): Promise<() => Promise<void>>;
 /**
  * Sends a `Request` to the service registered under `key` on the relay and
- * resolves with the corresponding `Response`.
+ * resolves with the corresponding `Response`, whose body streams with
+ * backpressure.
+ */
+export declare function callHttpService(request: Request, { key, port, streamTimeout }: ServiceOptions): Promise<Response>;
+/**
+ * Sends `request` on a port a service accepted with `reply`: over an HTTP link
+ * when the service speaks `HTTP_LINK_PROTOCOL`, over version 1's transport
+ * when it answered `true`. The link is closed once the response is done.
  */
-export declare function callHttpService(request: Request, { key, port }: ServiceOptions): Promise<Response>;
+export declare function sendOverConnection(port: MessagePort, reply: boolean | ConnectReply, request: Request, options?: HttpLinkOptions): Promise<Response>;
+/**
+ * Opens the transport of a socket to the service registered under `key` on
+ * the relay: the service runs the upgrade through its handler, and the
+ * socket's port comes back through the relay. After that, the socket runs
+ * between the caller and the service directly.
+ */
+export declare function callWebSocketService(url: string | URL, protocols: string[], { key, port, timeout }: Pick<ServiceOptions, "key" | "port"> & {
+    timeout?: number;
+}): Promise<WebSocketConnection>;
+/**
+ * A WHATWG `WebSocket` class whose sockets reach the service registered under
+ * `key` on the relay.
+ */
+export declare function relayWebSocketClass(service: Pick<ServiceOptions, "key" | "port">, options?: WebSocketClassOptions): PortWebSocketClass;
 export interface RelayWindowHandlerOptions {
     swUrl?: string;
     scopeUrl?: string;
@@ -86,8 +133,19 @@ export interface RegisterConnectionsHandlerOptions {
     key: string;
     /** Where this service is mounted; see `ServiceOptions.path`. */
     path?: string;
-    handler: (event: MessageEvent, data: unknown, port: MessagePort) => boolean | Promise<boolean>;
+    /**
+     * Answers one `CONNECT`. Its result is the reply; wrap a result carrying a
+     * port in `withTransfer`.
+     */
+    handler: (event: MessageEvent, data: unknown, port: MessagePort) => unknown | Promise<unknown>;
     communicationPort: MessageTarget;
 }
-export declare function registerConnectionsHandler({ key, path, handler, communicationPort, }: RegisterConnectionsHandlerOptions): Promise<() => void>;
+/**
+ * Registers `key` on the relay and answers its `CONNECT`s with `handler`.
+ * Resolves with a function that unregisters it. That function's promise
+ * settles once the relay acknowledged the `UNREGISTER`, so a caller can stop
+ * its services and only then close the connection: closing first tore the
+ * ports down before the message landed, and left the mount behind.
+ */
+export declare function registerConnectionsHandler({ key, path, handler, communicationPort, }: RegisterConnectionsHandlerOptions): Promise<() => Promise<void>>;
 //# sourceMappingURL=index.d.ts.map

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

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