@fuzdev/fuz_app 0.23.0 → 0.25.0

package/dist/actions/socket.svelte.js

@@ -5,16 +5,29 @@
  * Drop into any SvelteKit frontend as the underlying connection for
  * `FrontendWebsocketTransport`. Handles auto-reconnect with exponential
  * backoff, respects `WS_CLOSE_SESSION_REVOKED` (no reconnect loop after the
- * server revokes auth), and exposes reactive status for UI indicators.
+ * server revokes auth), exposes reactive status for UI indicators, and ships
+ * three correctness primitives default-on:
  *
- * First cut: no message queue, no heartbeat. Those live in consumer-specific
- * wrappers today (see zzz's `Socket` Cell); extract into fuz_app when two
- * independent consumers motivate the shape.
+ * - {@link FrontendWebsocketClient.request} — promise-based JSON-RPC with
+ *   auto-assigned ids and a pending-id map. Intercepts responses on the
+ *   message path so request/response correlation is transport-level rather
+ *   than re-invented per consumer.
+ * - **Durable queue** — `request()` calls made while disconnected buffer up
+ *   to {@link DEFAULT_QUEUE_MAX_SIZE} requests and flush on reopen. Overflow
+ *   rejects with `queue_overflow`. Raw {@link FrontendWebsocketClient.send}
+ *   is drop-on-disconnect (fire-and-forget notifications want that).
+ * - **Activity-aware heartbeat** — idles fire a shared `heartbeat` request;
+ *   receive-silence past {@link DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT} closes
+ *   with {@link WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT} and lets auto-reconnect
+ *   pick back up.
  *
  * @module
  */
 import { BROWSER } from 'esm-env';
-import { WS_CLOSE_SESSION_REVOKED } from './transports.js';
+import { JSONRPC_VERSION } from '../http/jsonrpc.js';
+import { WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT, WS_CLOSE_SESSION_REVOKED } from './transports.js';
+import { CANCEL_METHOD } from './cancel.js';
+import { HEARTBEAT_METHOD } from './heartbeat.js';
 /** Default WebSocket close code (normal closure). */
 export const DEFAULT_CLOSE_CODE = 1000;
 /** Base reconnect delay in ms. */
@@ -23,6 +36,12 @@ export const DEFAULT_RECONNECT_DELAY = 1000;
 export const DEFAULT_RECONNECT_DELAY_MAX = 10000;
 /** Exponential backoff factor: delay = base * factor^(attempt-1). */
 export const DEFAULT_BACKOFF_FACTOR = 1.5;
+/** Idle interval before sending a heartbeat (ms). */
+export const DEFAULT_HEARTBEAT_INTERVAL = 30_000;
+/** Max receive silence before closing with {@link WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT} (ms). */
+export const DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT = 60_000;
+/** Default bound on buffered requests while disconnected. Overflow rejects. */
+export const DEFAULT_QUEUE_MAX_SIZE = 100;
 /**
  * Reactive WebSocket client implementing `WebsocketConnection`.
  *
@@ -40,7 +59,20 @@ export class FrontendWebsocketClient {
     #reconnect_delay;
     #reconnect_delay_max;
     #backoff_factor;
+    #heartbeat_enabled;
+    #heartbeat_interval;
+    #heartbeat_receive_timeout;
+    #queue_enabled;
+    #queue_max_size;
     #log;
+    #next_request_id = 0;
+    #pending = new Map();
+    #queue = [];
+    #heartbeat_timer = null;
+    /** Epoch ms of the last outgoing send — used by the heartbeat activity check. */
+    #last_send_time = null;
+    /** Epoch ms of the last incoming message — used by the heartbeat activity check. */
+    #last_receive_time = null;
     ws = $state.raw(null);
     status = $state.raw('initial');
     reconnect_count = $state.raw(0);
@@ -77,6 +109,16 @@ export class FrontendWebsocketClient {
         this.#reconnect_delay = config.delay ?? DEFAULT_RECONNECT_DELAY;
         this.#reconnect_delay_max = config.delay_max ?? DEFAULT_RECONNECT_DELAY_MAX;
         this.#backoff_factor = config.factor ?? DEFAULT_BACKOFF_FACTOR;
+        const heartbeat = options.heartbeat;
+        this.#heartbeat_enabled = heartbeat !== false;
+        const heartbeat_config = typeof heartbeat === 'object' ? heartbeat : {};
+        this.#heartbeat_interval = heartbeat_config.interval ?? DEFAULT_HEARTBEAT_INTERVAL;
+        this.#heartbeat_receive_timeout =
+            heartbeat_config.receive_timeout ?? DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT;
+        const queue = options.queue;
+        this.#queue_enabled = queue !== false;
+        const queue_config = typeof queue === 'object' ? queue : {};
+        this.#queue_max_size = queue_config.max_size ?? DEFAULT_QUEUE_MAX_SIZE;
         this.#log = options.log ?? null;
     }
     /**
@@ -184,10 +226,12 @@ export class FrontendWebsocketClient {
      */
     disconnect(code = DEFAULT_CLOSE_CODE) {
         this.#cancel_reconnect();
+        this.#cancel_heartbeat();
         this.#teardown(code);
         this.status = 'closed';
         this.reconnect_count = 0;
         this.current_reconnect_delay = 0;
+        this.#reject_all('client disconnected');
     }
     /** Explicit-resource-management hook — supports `using client = new FrontendWebsocketClient(url)`. */
     [Symbol.dispose]() {
@@ -199,6 +243,7 @@ export class FrontendWebsocketClient {
         try {
             this.ws.send(JSON.stringify(data));
             this.last_send_error = null;
+            this.#last_send_time = Date.now();
             return true;
         }
         catch (error) {
@@ -207,6 +252,101 @@ export class FrontendWebsocketClient {
             return false;
         }
     }
+    /**
+     * Promise-based JSON-RPC over the socket. Auto-assigns a monotonic request
+     * id (or uses an explicit one supplied via `options.id` — used by
+     * `FrontendWebsocketTransport` which delegates to this method and has its
+     * own peer-minted UUID), tracks the pending promise, and resolves when the
+     * server sends a matching response (or rejects on error frame, socket
+     * close, or aborted signal).
+     *
+     * Callers supplying an explicit `options.id` are responsible for
+     * uniqueness — the pending map is keyed by id, and a duplicate silently
+     * overwrites the prior entry. Auto-minted ids are monotonic and never
+     * collide with themselves or with peer-minted UUIDs (the types differ:
+     * integer vs string).
+     *
+     * While the socket is disconnected, the request is buffered in a bounded
+     * queue (default-on, `DEFAULT_QUEUE_MAX_SIZE`) and flushed on reopen. Pass
+     * `{queue: false}` to reject immediately when disconnected — used
+     * internally by the heartbeat, which must not fight the queue for the
+     * disconnect-detection slot.
+     *
+     * On `AbortSignal` fire: rejects the local promise *and* sends the shared
+     * `cancel` notification (`CANCEL_METHOD`) so the server-side dispatcher
+     * can abort the matching handler's `ctx.signal`. Suppressed for
+     * queued-but-never-sent (server doesn't know about it) and
+     * response-beat-cancel races.
+     */
+    request(method, params = {}, options = {}) {
+        return new Promise((resolve, reject) => {
+            const resolve_typed = resolve;
+            const reject_typed = reject;
+            if (this.#revoked) {
+                reject_typed(new Error('[socket] session revoked'));
+                return;
+            }
+            const { signal = null } = options;
+            if (signal?.aborted) {
+                reject_typed(this.#build_abort_error(method));
+                return;
+            }
+            const id = options.id ?? ++this.#next_request_id;
+            const frame = { jsonrpc: JSONRPC_VERSION, id, method, params };
+            // Bind the signal listener up-front so `#detach_signal` can find it by
+            // reference regardless of which settlement path runs (inline send,
+            // queued flush, close-time reject).
+            let pending = null;
+            const signal_handler = signal
+                ? () => {
+                    if (!pending)
+                        return;
+                    // `Map.delete` returns true iff the entry existed — which
+                    // is our signal that the frame was actually written to
+                    // the socket (pending-only tracks in-flight). If it was
+                    // only queued (never sent), the server doesn't know
+                    // about it and doesn't need a cancel. If the response
+                    // beat the abort, `#handle_message` already deleted the
+                    // entry and detached this listener, so this closure
+                    // never runs in that race.
+                    const was_in_flight = this.#pending.delete(id);
+                    this.#drop_queued(id);
+                    this.#detach_signal(pending);
+                    pending = null;
+                    reject_typed(this.#build_abort_error(method));
+                    if (was_in_flight)
+                        this.#send_cancel(id);
+                }
+                : null;
+            if (signal && signal_handler)
+                signal.addEventListener('abort', signal_handler);
+            pending = { method, resolve: resolve_typed, reject: reject_typed, signal, signal_handler };
+            const should_queue = options.queue !== false && this.#queue_enabled;
+            if (this.connected && this.ws) {
+                const sent = this.send(frame);
+                if (sent) {
+                    this.#pending.set(id, pending);
+                    return;
+                }
+                // Send failed mid-connected (serialization, buffer full). Requeue if
+                // the queue is on, otherwise reject — this socket is in an odd
+                // state but the caller asked for non-durable semantics.
+                if (should_queue) {
+                    this.#enqueue({ ...pending, id, frame });
+                    return;
+                }
+                this.#detach_signal(pending);
+                reject_typed(new Error(`[socket] send failed for ${method}`));
+                return;
+            }
+            if (should_queue) {
+                this.#enqueue({ ...pending, id, frame });
+                return;
+            }
+            this.#detach_signal(pending);
+            reject_typed(new Error(`[socket] not connected (method=${method})`));
+        });
+    }
     add_message_handler(handler) {
         this.#message_handlers.add(handler);
         return () => this.#message_handlers.delete(handler);
@@ -215,6 +355,137 @@ export class FrontendWebsocketClient {
         this.#error_handlers.add(handler);
         return () => this.#error_handlers.delete(handler);
     }
+    #build_abort_error(method) {
+        return new Error(`[socket] request aborted (method=${method})`);
+    }
+    /**
+     * Fire-and-forget cancel notification to the server. The dispatcher
+     * looks up the matching pending handler's per-request `AbortController`
+     * and aborts it; unknown ids no-op. Drops silently when disconnected —
+     * the server's own socket-close path will abort any in-flight handlers.
+     */
+    #send_cancel(request_id) {
+        this.send({
+            jsonrpc: JSONRPC_VERSION,
+            method: CANCEL_METHOD,
+            params: { request_id },
+        });
+    }
+    #detach_signal(pending) {
+        if (pending.signal && pending.signal_handler) {
+            pending.signal.removeEventListener('abort', pending.signal_handler);
+        }
+    }
+    #enqueue(queued) {
+        if (this.#queue.length >= this.#queue_max_size) {
+            this.#detach_signal(queued);
+            queued.reject(new Error(`[socket] request queue overflow (method=${queued.method}, max=${this.#queue_max_size})`));
+            return;
+        }
+        this.#queue.push(queued);
+    }
+    #drop_queued(id) {
+        const index = this.#queue.findIndex((q) => q.id === id);
+        if (index !== -1)
+            this.#queue.splice(index, 1);
+    }
+    #flush_queue() {
+        if (!this.connected || !this.ws)
+            return;
+        const queued = this.#queue;
+        this.#queue = [];
+        for (const q of queued) {
+            if (q.signal?.aborted) {
+                this.#detach_signal(q);
+                q.reject(this.#build_abort_error(q.method));
+                continue;
+            }
+            const sent = this.send(q.frame);
+            if (sent) {
+                this.#pending.set(q.id, {
+                    method: q.method,
+                    resolve: q.resolve,
+                    reject: q.reject,
+                    signal: q.signal,
+                    signal_handler: q.signal_handler,
+                });
+            }
+            else {
+                this.#detach_signal(q);
+                q.reject(new Error(`[socket] queued request send failed (method=${q.method})`));
+            }
+        }
+    }
+    #reject_all(reason) {
+        const pending = this.#pending;
+        this.#pending = new Map();
+        for (const [id, p] of pending) {
+            this.#detach_signal(p);
+            p.reject(new Error(`[socket] ${reason} (method=${p.method}, id=${id})`));
+        }
+        const queued = this.#queue;
+        this.#queue = [];
+        for (const q of queued) {
+            this.#detach_signal(q);
+            q.reject(new Error(`[socket] ${reason} (method=${q.method})`));
+        }
+    }
+    #reject_pending_only(reason) {
+        // Socket closed but auto-reconnect will try again — pending requests were
+        // in flight on the old socket so we can't correlate them after reopen;
+        // queued requests haven't been sent yet and stay buffered for the flush.
+        const pending = this.#pending;
+        this.#pending = new Map();
+        for (const [id, p] of pending) {
+            this.#detach_signal(p);
+            p.reject(new Error(`[socket] ${reason} (method=${p.method}, id=${id})`));
+        }
+    }
+    #start_heartbeat() {
+        this.#cancel_heartbeat();
+        if (!this.#heartbeat_enabled)
+            return;
+        const now = Date.now();
+        this.#last_send_time = now;
+        this.#last_receive_time = now;
+        // Run the check at half the interval so any event-loop blockage pauses
+        // the timer itself; a dead-because-blocked socket is close enough to
+        // dead-because-unresponsive that closing is arguably correct.
+        const tick = Math.max(100, Math.floor(this.#heartbeat_interval / 2));
+        this.#heartbeat_timer = setInterval(() => this.#heartbeat_tick(), tick);
+    }
+    #cancel_heartbeat() {
+        if (this.#heartbeat_timer !== null) {
+            clearInterval(this.#heartbeat_timer);
+            this.#heartbeat_timer = null;
+        }
+    }
+    #heartbeat_tick() {
+        if (!this.connected || !this.ws)
+            return;
+        const now = Date.now();
+        const last_receive = this.#last_receive_time ?? now;
+        if (now - last_receive >= this.#heartbeat_receive_timeout) {
+            this.#log?.info(`[socket] receive timeout (${now - last_receive}ms) — closing ${WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT}`);
+            try {
+                this.ws.close(WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT, 'client heartbeat timeout');
+            }
+            catch (error) {
+                this.#log?.error('[socket] heartbeat timeout close failed:', error);
+            }
+            return;
+        }
+        const last_activity = Math.max(this.#last_send_time ?? 0, last_receive);
+        if (now - last_activity >= this.#heartbeat_interval) {
+            // Fire-and-forget the heartbeat. If it fails (network, serialization),
+            // receive-silence detection above will close the socket on the next
+            // tick. No queue — the heartbeat is the thing that tells us the
+            // queue needs flushing, it must not fight the queue for the slot.
+            void this.request(HEARTBEAT_METHOD, {}, { queue: false }).catch((error) => {
+                this.#log?.debug('[socket] heartbeat request failed:', error);
+            });
+        }
+    }
     #teardown(close_code) {
         if (!this.ws)
             return;
@@ -222,6 +493,7 @@ export class FrontendWebsocketClient {
         this.ws.removeEventListener('close', this.#handle_close);
         this.ws.removeEventListener('error', this.#handle_error);
         this.ws.removeEventListener('message', this.#handle_message);
+        this.#cancel_heartbeat();
         if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) {
             try {
                 this.ws.close(close_code);
@@ -230,8 +502,10 @@ export class FrontendWebsocketClient {
                 this.#log?.error('[socket] close failed:', error);
             }
             // Listeners are gone, so `#handle_close` won't fire for this close —
-            // record it here so the client-initiated close is still observable.
+            // record it here so the client-initiated close is still observable,
+            // and reject any pending requests that can never resolve now.
             this.#record_close(close_code, '');
+            this.#reject_pending_only(`socket torn down (code ${close_code})`);
         }
         this.ws = null;
     }
@@ -267,12 +541,16 @@ export class FrontendWebsocketClient {
         this.current_reconnect_delay = 0;
         this.last_connect_time = Date.now();
         this.#cancel_reconnect();
+        this.#start_heartbeat();
+        // Flush buffered requests before anyone else can observe the open state.
+        this.#flush_queue();
     };
     #handle_close = (event) => {
         // Drop the dead-socket reference so consumers reading `client.ws` never
         // see a CLOSED WebSocket during the reconnect window.
         this.ws = null;
         this.#record_close(event.code, event.reason);
+        this.#cancel_heartbeat();
         // Session revocation is terminal — reconnecting would 401 in a loop.
         if (event.code === WS_CLOSE_SESSION_REVOKED) {
             this.#revoked = true;
@@ -280,8 +558,12 @@ export class FrontendWebsocketClient {
             this.#cancel_reconnect();
             this.reconnect_count = 0;
             this.current_reconnect_delay = 0;
+            this.#reject_all('session revoked');
             return;
         }
+        // Pending in-flight requests can't be correlated post-reconnect; reject
+        // them. Queue stays so the flush on reopen replays unsent work.
+        this.#reject_pending_only(`connection closed (code ${event.code})`);
         // Let `#schedule_reconnect` set `status: 'reconnecting'` directly to avoid
         // a transient `'closed'` flicker; only set `'closed'` when reconnect is off.
         if (this.#auto_reconnect) {
@@ -289,6 +571,7 @@ export class FrontendWebsocketClient {
         }
         else {
             this.status = 'closed';
+            this.#reject_all('connection closed, auto-reconnect disabled');
         }
     };
     #handle_error = (event) => {
@@ -304,6 +587,39 @@ export class FrontendWebsocketClient {
         // Browsers fire `close` after error; reconnect logic lives there.
     };
     #handle_message = (event) => {
+        this.#last_receive_time = Date.now();
+        // Intercept JSON-RPC responses for pending `request()` calls. Parse
+        // defensively — if the frame isn't valid JSON or isn't a response, fall
+        // through to the registered message handlers (which still see every
+        // notification, plus any stray response we don't own).
+        let json;
+        try {
+            json = JSON.parse(String(event.data));
+        }
+        catch {
+            json = undefined;
+        }
+        if (typeof json === 'object' &&
+            json !== null &&
+            'id' in json &&
+            ('result' in json || 'error' in json)) {
+            const id = json.id;
+            if (id !== null) {
+                const pending = this.#pending.get(id);
+                if (pending) {
+                    this.#pending.delete(id);
+                    this.#detach_signal(pending);
+                    if ('error' in json && json.error) {
+                        const err = json.error;
+                        pending.reject(new Error(`[rpc ${pending.method} #${id}] ${err.code ?? '?'} ${err.message ?? 'unknown error'}`));
+                    }
+                    else {
+                        pending.resolve(json.result);
+                    }
+                    return;
+                }
+            }
+        }
         for (const handler of this.#message_handlers) {
             try {
                 handler(event);

package/dist/actions/transports.d.ts

@@ -10,13 +10,28 @@ import { z } from 'zod';
 import type { JsonrpcMessageFromClientToServer, JsonrpcMessageFromServerToClient, JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
 /** WebSocket close code for session revocation. */
 export declare const WS_CLOSE_SESSION_REVOKED = 4001;
+/** WebSocket close code — client timed out waiting for a response. */
+export declare const WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT = 4002;
+/** WebSocket close code — server timed out with no incoming activity. */
+export declare const WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT = 4003;
 export declare const TransportName: z.ZodString;
 export type TransportName = z.infer<typeof TransportName>;
+/**
+ * Per-call options accepted by every transport's `send`. Optional and
+ * extensible — adding a field is non-breaking. Today: an `AbortSignal`
+ * for cancellation that bottoms out at `FrontendWebsocketClient.request`
+ * (which sends the shared `cancel` notification on abort) and at
+ * `fetch({signal})` for HTTP. Backend transport receives the option but
+ * has no per-call abort surface to honor.
+ */
+export interface TransportSendOptions {
+    signal?: AbortSignal;
+}
 export interface Transport {
     transport_name: TransportName;
-    send(message: JsonrpcRequest): Promise<JsonrpcResponseOrError>;
-    send(message: JsonrpcNotification): Promise<JsonrpcErrorResponse | null>;
-    send(message: JsonrpcMessageFromClientToServer): Promise<JsonrpcMessageFromServerToClient | null>;
+    send(message: JsonrpcRequest, options?: TransportSendOptions): Promise<JsonrpcResponseOrError>;
+    send(message: JsonrpcNotification, options?: TransportSendOptions): Promise<JsonrpcErrorResponse | null>;
+    send(message: JsonrpcMessageFromClientToServer, options?: TransportSendOptions): Promise<JsonrpcMessageFromServerToClient | null>;
     is_ready: () => boolean;
     dispose?: () => void;
 }

package/dist/actions/transports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transports.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EACX,gCAAgC,EAChC,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAE5B,mDAAmD;AACnD,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAK7C,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,MAAM,WAAW,SAAS;IACzB,cAAc,EAAE,aAAa,CAAC;IAE9B,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/D,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IACzE,IAAI,CAAC,OAAO,EAAE,gCAAgC,GAAG,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC,CAAC;IAClG,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,qBAAa,UAAU;;IAItB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAQ;IAE/B;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAS9C,qBAAqB,CAAC,cAAc,EAAE,aAAa,GAAG,IAAI;IAM1D;;;;;OAKG;IACH,aAAa,CAAC,cAAc,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;IAO/D,QAAQ,IAAI,OAAO,GAAG,IAAI;IAM1B,qBAAqB,IAAI,SAAS,GAAG,IAAI;IAIzC,0BAA0B,IAAI,aAAa,GAAG,IAAI;IAIlD,qBAAqB,CAAC,cAAc,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;CAqDtE"}
+{"version":3,"file":"transports.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EACX,gCAAgC,EAChC,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAE5B,mDAAmD;AACnD,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,sEAAsE;AACtE,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD,yEAAyE;AACzE,eAAO,MAAM,iCAAiC,OAAO,CAAC;AAKtD,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACzB,cAAc,EAAE,aAAa,CAAC;IAE9B,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/F,IAAI,CACH,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IACxC,IAAI,CACH,OAAO,EAAE,gCAAgC,EACzC,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC,CAAC;IACpD,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,qBAAa,UAAU;;IAItB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAQ;IAE/B;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAS9C,qBAAqB,CAAC,cAAc,EAAE,aAAa,GAAG,IAAI;IAM1D;;;;;OAKG;IACH,aAAa,CAAC,cAAc,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;IAO/D,QAAQ,IAAI,OAAO,GAAG,IAAI;IAM1B,qBAAqB,IAAI,SAAS,GAAG,IAAI;IAIzC,0BAA0B,IAAI,aAAa,GAAG,IAAI;IAIlD,qBAAqB,CAAC,cAAc,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;CAqDtE"}

package/dist/actions/transports.js

@@ -9,6 +9,10 @@
 import { z } from 'zod';
 /** WebSocket close code for session revocation. */
 export const WS_CLOSE_SESSION_REVOKED = 4001;
+/** WebSocket close code — client timed out waiting for a response. */
+export const WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT = 4002;
+/** WebSocket close code — server timed out with no incoming activity. */
+export const WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT = 4003;
 // TODO figure out the symmetry of frontend and backend transports (none/partial/full?) --
 // we may also need orthogonal abstractions to clarify the transport role
 export const TransportName = z.string(); // not branded for convenience, will just error at runtime, the schema is just for docs atm

package/dist/actions/transports_http.d.ts

@@ -4,13 +4,13 @@
  * @module
  */
 import type { JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
-import type { Transport } from './transports.js';
+import type { Transport, TransportSendOptions } from './transports.js';
 export declare class FrontendHttpTransport implements Transport {
     #private;
     readonly transport_name: "frontend_http_rpc";
     constructor(url: string, headers?: Record<string, string>, has_side_effects?: (method: string) => boolean);
-    send(message: JsonrpcRequest): Promise<JsonrpcResponseOrError>;
-    send(message: JsonrpcNotification): Promise<JsonrpcErrorResponse | null>;
+    send(message: JsonrpcRequest, options?: TransportSendOptions): Promise<JsonrpcResponseOrError>;
+    send(message: JsonrpcNotification, options?: TransportSendOptions): Promise<JsonrpcErrorResponse | null>;
     is_ready(): boolean;
 }
 //# sourceMappingURL=transports_http.d.ts.map

package/dist/actions/transports_http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transports_http.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAE/C,qBAAa,qBAAsB,YAAW,SAAS;;IACtD,QAAQ,CAAC,cAAc,EAAG,mBAAmB,CAAU;gBAOtD,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO;IAOzC,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAuE9E,QAAQ,IAAI,OAAO;CAGnB"}
+{"version":3,"file":"transports_http.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,SAAS,EAAE,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAErE,qBAAa,qBAAsB,YAAW,SAAS;;IACtD,QAAQ,CAAC,cAAc,EAAG,mBAAmB,CAAU;gBAOtD,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO;IAOzC,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAyEvC,QAAQ,IAAI,OAAO;CAGnB"}

package/dist/actions/transports_http.js

@@ -16,7 +16,8 @@ export class FrontendHttpTransport {
         this.#headers = headers ?? { 'content-type': 'application/json', accept: 'application/json' };
         this.#has_side_effects = has_side_effects;
     }
-    async send(message) {
+    async send(message, options) {
+        const signal = options?.signal;
         try {
             let response;
             if (this.#has_side_effects && !this.#has_side_effects(message.method) && 'id' in message) {
@@ -31,6 +32,7 @@ export class FrontendHttpTransport {
                 response = await fetch(`${this.#url}${separator}${search_params.toString()}`, {
                     method: 'GET',
                     headers: this.#headers,
+                    signal,
                 });
             }
             else {
@@ -38,8 +40,7 @@ export class FrontendHttpTransport {
                     method: 'POST',
                     headers: this.#headers,
                     body: JSON.stringify(message),
-                    // TODO
-                    // signal: AbortSignal.timeout(REQUEST_TIMEOUT),
+                    signal,
                 });
             }
             const result = await response.json();

package/dist/actions/transports_ws.d.ts

@@ -1,10 +1,18 @@
 /**
- * WebSocket transport — sends JSON-RPC messages via WebSocket with request tracking.
+ * Frontend WebSocket transport — thin adapter over `WebsocketRpcConnection`.
+ *
+ * Delegates request/response correlation, the durable queue, the heartbeat,
+ * and `AbortSignal`-driven cancel to the underlying connection (the
+ * canonical implementation is `FrontendWebsocketClient`). The transport's
+ * own job is the `Transport` contract: route inbound server-pushed
+ * messages into `peer.receive` and translate the connection's
+ * `Promise<R>`/`ThrownJsonrpcError` shape into `JsonrpcResponseOrError`
+ * envelopes. No parallel pending-request map.
  *
  * @module
  */
-import type { JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
-import type { Transport } from './transports.js';
+import type { JsonrpcNotification, JsonrpcRequest, JsonrpcRequestId, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
+import type { Transport, TransportSendOptions } from './transports.js';
 /**
  * Minimal interface for a WebSocket connection, decoupled from the concrete Socket Cell.
  */
@@ -14,12 +22,31 @@ export interface WebsocketConnection {
     add_message_handler: (handler: (event: MessageEvent) => void) => () => void;
     add_error_handler: (handler: (event: Event) => void) => () => void;
 }
+/**
+ * RPC-capable WebSocket connection — a `WebsocketConnection` that also
+ * handles request/response correlation with timeout, queue,
+ * `AbortSignal` cancel, and explicit-id support. Required by
+ * `FrontendWebsocketTransport` so it can delegate the pending-map
+ * bookkeeping to one canonical implementation
+ * (`FrontendWebsocketClient`) instead of running a parallel one.
+ *
+ * Consumer wrappers around `FrontendWebsocketClient` (e.g. zzz's
+ * `Socket`) implement this by adding a one-line delegate to the
+ * underlying client's `request`.
+ */
+export interface WebsocketRpcConnection extends WebsocketConnection {
+    request: (method: string, params: unknown, options?: {
+        signal?: AbortSignal;
+        queue?: boolean;
+        id?: JsonrpcRequestId;
+    }) => Promise<unknown>;
+}
 export declare class FrontendWebsocketTransport implements Transport {
     #private;
     readonly transport_name: "frontend_websocket_rpc";
-    constructor(connection: WebsocketConnection, receive: (data: unknown) => Promise<unknown>, request_timeout_ms?: number);
-    send(message: JsonrpcRequest): Promise<JsonrpcResponseOrError>;
-    send(message: JsonrpcNotification): Promise<JsonrpcErrorResponse | null>;
+    constructor(connection: WebsocketRpcConnection, receive: (data: unknown) => Promise<unknown>);
+    send(message: JsonrpcRequest, options?: TransportSendOptions): Promise<JsonrpcResponseOrError>;
+    send(message: JsonrpcNotification, options?: TransportSendOptions): Promise<JsonrpcErrorResponse | null>;
     is_ready(): boolean;
     dispose(): void;
 }

package/dist/actions/transports_ws.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transports_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAI/C;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAC5E,iBAAiB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CACnE;AAED,qBAAa,0BAA2B,YAAW,SAAS;;IAC3D,QAAQ,CAAC,cAAc,EAAG,wBAAwB,CAAU;gBAS3D,UAAU,EAAE,mBAAmB,EAC/B,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,EAC5C,kBAAkB,CAAC,EAAE,MAAM;IAkCtB,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA8C9E,QAAQ,IAAI,OAAO;IAInB,OAAO,IAAI,IAAI;CAUf"}
+{"version":3,"file":"transports_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,SAAS,EAAE,oBAAoB,EAAC,MAAM,iBAAiB,CAAC;AAIrE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAC5E,iBAAiB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CACnE;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IAClE,OAAO,EAAE,CACR,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE;QAAC,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,EAAE,CAAC,EAAE,gBAAgB,CAAA;KAAC,KACpE,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAED,qBAAa,0BAA2B,YAAW,SAAS;;IAC3D,QAAQ,CAAC,cAAc,EAAG,wBAAwB,CAAU;gBAOhD,UAAU,EAAE,sBAAsB,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC;IAyBtF,IAAI,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,sBAAsB,CAAC;IAC5B,IAAI,CACT,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAoDvC,QAAQ,IAAI,OAAO;IAInB,OAAO,IAAI,IAAI;CAUf"}