@fuzdev/fuz_app 0.23.0 → 0.25.0

package/dist/actions/register_action_ws.js

@@ -31,7 +31,12 @@ import { JSONRPC_VERSION } from '../http/jsonrpc.js';
 import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
 import { create_jsonrpc_error_response, create_jsonrpc_error_response_from_thrown, create_jsonrpc_notification, to_jsonrpc_message_id, to_jsonrpc_params, is_jsonrpc_request, } from '../http/jsonrpc_helpers.js';
 import { CREDENTIAL_TYPE_KEY, AUTH_API_TOKEN_ID_KEY } from '../hono_context.js';
+import {} from './action_types.js';
+import { CANCEL_METHOD, CancelNotificationParams } from './cancel.js';
+import { WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT } from './transports.js';
 import { BackendWebsocketTransport } from './transports_ws_backend.js';
+/** Default inactivity window before the server closes a silent socket. */
+export const DEFAULT_SERVER_HEARTBEAT_TIMEOUT = 60_000;
 /**
  * Mount a JSON-RPC WebSocket endpoint that dispatches to the supplied handler
  * map. Per-request context is built from the base + consumer-provided
@@ -51,9 +56,24 @@ import { BackendWebsocketTransport } from './transports_ws_backend.js';
  *   `create_ws_auth_guard` or broadcast on audit events.
  */
 export const register_action_ws = (options) => {
-    const { path, app, upgradeWebSocket, specs, handlers, extend_context, transport = new BackendWebsocketTransport(), artificial_delay = 0, log = new Logger('[ws]'), on_socket_open, on_socket_close, } = options;
-    // Build spec lookup for per-action auth and input validation.
-    const spec_by_method = new Map(specs.map((spec) => [spec.method, spec]));
+    const { path, app, upgradeWebSocket, actions, extend_context, transport = new BackendWebsocketTransport(), heartbeat = true, artificial_delay = 0, log = new Logger('[ws]'), on_socket_open, on_socket_close, } = options;
+    // Fan the unified actions array into the two lookups the dispatcher
+    // consults at message time. Keeping them internal means the composable
+    // `{spec, handler}` tuple remains the only shape consumers name.
+    const spec_by_method = new Map();
+    const handlers = {};
+    for (const action of actions) {
+        spec_by_method.set(action.spec.method, action.spec);
+        if (action.handler)
+            handlers[action.spec.method] = action.handler;
+    }
+    const heartbeat_enabled = heartbeat !== false;
+    const heartbeat_config = typeof heartbeat === 'object' ? heartbeat : {};
+    const heartbeat_timeout = heartbeat_config.timeout ?? DEFAULT_SERVER_HEARTBEAT_TIMEOUT;
+    // Run the checker on timeout/2 so 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 heartbeat_tick_interval = Math.max(100, Math.floor(heartbeat_timeout / 2));
     app.get(path, upgradeWebSocket((c) => {
         // Upgrade-time auth extraction — `require_auth` middleware has already
         // rejected unauthenticated requests, so request_context is guaranteed
@@ -69,12 +89,19 @@ export const register_action_ws = (options) => {
         // `close_sockets_for_token` to tear down just this socket on
         // `token_revoke` without affecting the account's other sockets.
         const api_token_id = c.get(AUTH_API_TOKEN_ID_KEY);
-        // Per-socket abort controller — fires on socket close, threaded into
-        // every in-flight handler's ctx.signal on this connection. A
-        // dedicated per-request controller linked to this is future work;
-        // a single socket-scoped signal is sufficient today since cancel
-        // granularity tracks connection lifetime, not individual requests.
+        // Per-socket abort controller — fires on socket close, chained into
+        // every in-flight handler's per-request controller via
+        // `AbortSignal.any`. Keeping both signals lets the client
+        // cancel-one-request-by-id (via the `cancel` notification) without
+        // tearing down the whole socket.
         const socket_abort_controller = new AbortController();
+        // Per-request controllers keyed by JSON-RPC request id — lets an
+        // incoming `cancel` notification abort just the matching handler.
+        // Populated on request dispatch, cleared in the handler's `finally`
+        // so a late-arriving cancel for a completed id (or a reused id)
+        // can't null-abort a freshly-arrived request. Idempotent: cancel
+        // for unknown ids no-ops.
+        const pending_controllers = new Map();
         // Identity is assembled at upgrade time so `on_socket_close` can
         // still read it after the audit guard tears the transport record
         // down; `BackendWebsocketTransport.#revoke_connection` clears the
@@ -83,6 +110,18 @@ export const register_action_ws = (options) => {
         // Captured on open, consumed on close. Null before onOpen fires or
         // when a consumer never opens (e.g. immediate disconnect).
         let captured_connection_id = null;
+        // Receive-silence watchdog. Seeded to open-time so the first window is
+        // exempt (cold-start grace — avoid killing mid-handshake sockets).
+        // Bumped by onMessage. Any incoming activity counts, not just
+        // heartbeats — chatty clients don't need to send extras.
+        let last_receive_time = 0;
+        let heartbeat_timer = null;
+        const stop_heartbeat_timer = () => {
+            if (heartbeat_timer !== null) {
+                clearInterval(heartbeat_timer);
+                heartbeat_timer = null;
+            }
+        };
         // Socket-scoped notification helper — routes to this socket only,
         // matches the `ctx.notify` semantics exposed to per-message handlers.
         const notify_socket = (ws) => (notify_method, notify_params) => {
@@ -99,6 +138,23 @@ export const register_action_ws = (options) => {
                 const connection_id = transport.add_connection(ws, token_hash, account_id, api_token_id);
                 captured_connection_id = connection_id;
                 log.debug('ws opened', connection_id, event);
+                if (heartbeat_enabled) {
+                    last_receive_time = Date.now();
+                    heartbeat_timer = setInterval(() => {
+                        const now = Date.now();
+                        const silence = now - last_receive_time;
+                        if (silence >= heartbeat_timeout) {
+                            log.info(`heartbeat timeout (${silence}ms) — closing ${WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT}`, connection_id, identity.account_id);
+                            stop_heartbeat_timer();
+                            try {
+                                ws.close(WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT, 'server heartbeat timeout');
+                            }
+                            catch (error) {
+                                log.error('heartbeat timeout close failed:', error);
+                            }
+                        }
+                    }, heartbeat_tick_interval);
+                }
                 if (on_socket_open) {
                     try {
                         await on_socket_open({
@@ -122,6 +178,7 @@ export const register_action_ws = (options) => {
                 }
             },
             onMessage: async (event, ws) => {
+                last_receive_time = Date.now();
                 let json;
                 try {
                     json = JSON.parse(String(event.data)); // eslint-disable-line @typescript-eslint/no-base-to-string
@@ -136,9 +193,26 @@ export const register_action_ws = (options) => {
                     ws.send(JSON.stringify(create_jsonrpc_error_response(null, jsonrpc_error_messages.invalid_request('batch JSON-RPC requests are not supported on WebSocket'))));
                     return;
                 }
-                // Only handle requests (method + id). Notifications (no id) are silenced per JSON-RPC spec.
+                // Notifications (method + no id) — `cancel` is intercepted
+                // for request-scoped cancellation; other notifications are
+                // silenced per JSON-RPC spec (consumer notification handlers
+                // are not a feature yet).
                 if (!is_jsonrpc_request(json)) {
                     if (typeof json === 'object' && json !== null && 'method' in json && !('id' in json)) {
+                        if (json.method === CANCEL_METHOD) {
+                            const parsed = CancelNotificationParams.safeParse(json.params);
+                            if (!parsed.success) {
+                                log.debug('cancel: invalid params, ignoring', parsed.error.issues);
+                                return;
+                            }
+                            const controller = pending_controllers.get(parsed.data.request_id);
+                            if (controller) {
+                                controller.abort();
+                            }
+                            else {
+                                log.debug('cancel: no pending request for id', parsed.data.request_id);
+                            }
+                        }
                         return;
                     }
                     ws.send(JSON.stringify(create_jsonrpc_error_response(to_jsonrpc_message_id(json), jsonrpc_error_messages.invalid_request())));
@@ -184,22 +258,27 @@ export const register_action_ws = (options) => {
                     await wait(artificial_delay);
                 }
                 // Socket-scoped notification — routes to originator only, not
-                // broadcast. Future work: other audiences — account-scoped,
+                // broadcast. Same helper used in `on_socket_open` so both
+                // paths share one code path for send-and-log-on-failure.
+                // Future work: other audiences — account-scoped,
                 // ACL-filtered, broadcast — likely via a transport-level
                 // policy hook.
-                const notify = (notify_method, notify_params) => {
-                    try {
-                        const notification = create_jsonrpc_notification(notify_method, to_jsonrpc_params(notify_params));
-                        ws.send(JSON.stringify(notification));
-                    }
-                    catch (error) {
-                        log.error('notify send failed:', notify_method, error);
-                    }
-                };
+                const notify = notify_socket(ws);
+                // Per-request controller — fires on explicit `cancel` or on
+                // socket close (via the socket_abort_controller chain below).
+                // Registered before dispatch so a cancel arriving mid-handler
+                // finds it; cleared in `finally` so late cancels for a
+                // completed id (or a future request that reuses the id) can't
+                // null-abort the wrong handler.
+                const request_controller = new AbortController();
+                pending_controllers.set(id, request_controller);
                 const base = {
                     request_id: id,
+                    // Populated in `onOpen` before any message can dispatch —
+                    // non-null assertion is safe.
+                    connection_id: captured_connection_id,
                     notify,
-                    signal: socket_abort_controller.signal,
+                    signal: AbortSignal.any([socket_abort_controller.signal, request_controller.signal]),
                 };
                 const ctx = extend_context(base, c);
                 try {
@@ -218,8 +297,12 @@ export const register_action_ws = (options) => {
                     log.error('handler error:', method, error);
                     ws.send(JSON.stringify(create_jsonrpc_error_response_from_thrown(id, error)));
                 }
+                finally {
+                    pending_controllers.delete(id);
+                }
             },
             onClose: async (event, ws) => {
+                stop_heartbeat_timer();
                 socket_abort_controller.abort();
                 if (on_socket_close && captured_connection_id) {
                     try {

package/dist/actions/rpc_client.d.ts

@@ -57,4 +57,14 @@ export interface CreateRpcClientOptions {
  * @returns a Proxy that responds to any method name found in the environment's specs
  */
 export declare const create_rpc_client: (options: CreateRpcClientOptions) => Record<string, (...args: Array<any>) => any>;
+/**
+ * Per-call options accepted by every typed Proxy method. `signal` lets the
+ * caller cancel an in-flight request (sends the shared `cancel` notification
+ * on the WS path, aborts `fetch` on HTTP). `transport_name` overrides the
+ * per-method `transport_for_method` selector for this call.
+ */
+export interface RpcClientCallOptions {
+    signal?: AbortSignal;
+    transport_name?: TransportName;
+}
 //# sourceMappingURL=rpc_client.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;AAM/E,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACtC,aAAa,EAAE,CAAC,IAAI,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,oBAAoB,CAAA;KAAC,KAC5E;QACA,sBAAsB,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;KAC5C,GACD,SAAS,CAAC;CACb;AAED,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,sBAAsB,CAAC;IACpC,kEAAkE;IAClE,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,sBAAsB,KAC7B,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,CAgB7C,CAAC"}
+{"version":3,"file":"rpc_client.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/rpc_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AAOpE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAGnD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;AAM/E,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACtC,aAAa,EAAE,CAAC,IAAI,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,oBAAoB,CAAA;KAAC,KAC5E;QACA,sBAAsB,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;KAC5C,GACD,SAAS,CAAC;CACb;AAED,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,sBAAsB,CAAC;IACpC,kEAAkE;IAClE,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,sBAAsB,KAC7B,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,CAgB7C,CAAC;AA2DF;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,cAAc,CAAC,EAAE,aAAa,CAAC;CAC/B"}

package/dist/actions/rpc_client.js

@@ -11,6 +11,7 @@
  */
 import { create_action_event } from './action_event.js';
 import { is_send_request, is_notification_send, extract_action_result, } from './action_event_helpers.js';
+import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
 /**
  * Creates a Proxy-based API from action specs.
  *
@@ -78,9 +79,19 @@ const create_sync_local_call_method = (environment, spec, actions) => {
 /**
  * Creates an asynchronous local call method.
  * Returns Result for type-safe error handling.
+ *
+ * Local calls don't traverse a transport, so `transport_name` is ignored and
+ * `signal` can only short-circuit before the synchronous handler runs (no
+ * cooperative interrupt mid-handler).
  */
 const create_async_local_call_method = (environment, spec, actions) => {
-    return async (input) => {
+    return async (input, options) => {
+        if (options?.signal?.aborted) {
+            return {
+                ok: false,
+                error: jsonrpc_error_messages.internal_error(`${spec.method} aborted before execution`),
+            };
+        }
         const event = create_action_event(environment, spec, input);
         const action = actions?.add_from_json({
             method: spec.method,
@@ -95,7 +106,7 @@ const create_async_local_call_method = (environment, spec, actions) => {
  * Creates a request/response method that communicates over the network.
  */
 const create_request_response_method = (peer, environment, spec, actions, transport_for_method) => {
-    return async (input) => {
+    return async (input, options) => {
         const event = create_action_event(environment, spec, input);
         const action = actions?.add_from_json({
             method: spec.method,
@@ -113,8 +124,10 @@ const create_request_response_method = (peer, environment, spec, actions, transp
         if (event.data.step !== 'handled') {
             return extract_action_result(event);
         }
-        const transport_name = transport_for_method?.(spec.method);
-        const response = await peer.send(event.data.request, transport_name ? { transport_name } : undefined);
+        const response = await peer.send(event.data.request, {
+            transport_name: options?.transport_name ?? transport_for_method?.(spec.method),
+            signal: options?.signal,
+        });
         event.transition('receive_response');
         // TODO @api shouldn't this happen in the peer like the other method calls?
         event.set_response(response);
@@ -128,7 +141,7 @@ const create_request_response_method = (peer, environment, spec, actions, transp
  * Returns Result<{value: void}> for consistency.
  */
 const create_remote_notification_method = (peer, environment, spec, actions, transport_for_method) => {
-    return async (input) => {
+    return async (input, options) => {
         const event = create_action_event(environment, spec, input);
         const action = actions?.add_from_json({
             method: spec.method,
@@ -139,8 +152,10 @@ const create_remote_notification_method = (peer, environment, spec, actions, tra
         if (!is_notification_send(event.data))
             throw Error(); // TODO @many maybe make this an assertion helper?
         if (event.data.step === 'handled') {
-            const transport_name = transport_for_method?.(spec.method);
-            const send_result = await peer.send(event.data.notification, transport_name ? { transport_name } : undefined);
+            const send_result = await peer.send(event.data.notification, {
+                transport_name: options?.transport_name ?? transport_for_method?.(spec.method),
+                signal: options?.signal,
+            });
             // Check if notification failed to send
             if (send_result !== null) {
                 environment.log?.error('notification send failed:', send_result.error);

package/dist/actions/socket.svelte.d.ts

@@ -5,15 +5,26 @@
  * 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 type { Logger } from '@fuzdev/fuz_util/log.js';
+import { type JsonrpcRequestId } from '../http/jsonrpc.js';
 import type { WebsocketConnection } from './transports_ws.js';
 /** Default WebSocket close code (normal closure). */
 export declare const DEFAULT_CLOSE_CODE = 1000;
@@ -23,6 +34,12 @@ export declare const DEFAULT_RECONNECT_DELAY = 1000;
 export declare const DEFAULT_RECONNECT_DELAY_MAX = 10000;
 /** Exponential backoff factor: delay = base * factor^(attempt-1). */
 export declare const DEFAULT_BACKOFF_FACTOR = 1.5;
+/** Idle interval before sending a heartbeat (ms). */
+export declare const DEFAULT_HEARTBEAT_INTERVAL = 30000;
+/** Max receive silence before closing with {@link WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT} (ms). */
+export declare const DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT = 60000;
+/** Default bound on buffered requests while disconnected. Overflow rejects. */
+export declare const DEFAULT_QUEUE_MAX_SIZE = 100;
 /**
  * Client-side WebSocket status.
  *
@@ -44,12 +61,48 @@ export interface FrontendWebsocketReconnectOptions {
     /** Exponential backoff factor. Defaults to 1.5. */
     factor?: number;
 }
+export interface FrontendWebsocketHeartbeatOptions {
+    /**
+     * Idle duration (ms) after which a heartbeat is sent. Reset by any send or
+     * receive — chatty clients never emit extras. Defaults to
+     * {@link DEFAULT_HEARTBEAT_INTERVAL}.
+     */
+    interval?: number;
+    /**
+     * Receive-silence (ms) after which the client closes the socket with
+     * {@link WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT}, letting auto-reconnect kick
+     * in. Should be a comfortable multiple of {@link interval}. Defaults to
+     * {@link DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT}.
+     */
+    receive_timeout?: number;
+}
+export interface FrontendWebsocketQueueOptions {
+    /**
+     * Maximum number of requests held while the socket is disconnected.
+     * Enqueue past this rejects the new call with a `queue_overflow` error.
+     * Defaults to {@link DEFAULT_QUEUE_MAX_SIZE}.
+     */
+    max_size?: number;
+}
 export interface FrontendWebsocketClientOptions {
     /**
      * Auto-reconnect policy. `false` disables reconnect entirely; `true` or
      * omit for default timing; pass an object to customize.
      */
     reconnect?: boolean | FrontendWebsocketReconnectOptions | null;
+    /**
+     * Activity-aware heartbeat. `true` or omit for defaults; `false` disables
+     * the timer entirely (only do this if the server side is also running
+     * without heartbeat); pass an object to tune `interval` / `receive_timeout`.
+     */
+    heartbeat?: boolean | FrontendWebsocketHeartbeatOptions;
+    /**
+     * Durable queue for {@link FrontendWebsocketClient.request}. `true` or omit
+     * for defaults; `false` disables buffering (requests while disconnected
+     * reject immediately). Raw {@link FrontendWebsocketClient.send} is never
+     * queued — use `request()` for RPC semantics.
+     */
+    queue?: boolean | FrontendWebsocketQueueOptions;
     /** Optional logger for diagnostic messages. */
     log?: Logger | null;
 }
@@ -132,6 +185,37 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
     /** Explicit-resource-management hook — supports `using client = new FrontendWebsocketClient(url)`. */
     [Symbol.dispose](): void;
     send(data: object): boolean;
+    /**
+     * 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<R = unknown>(method: string, params?: unknown, options?: {
+        signal?: AbortSignal;
+        queue?: boolean;
+        id?: JsonrpcRequestId;
+    }): Promise<R>;
     add_message_handler(handler: SocketMessageHandler): () => void;
     add_error_handler(handler: SocketErrorHandler): () => void;
 }

package/dist/actions/socket.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/socket.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,oBAAoB,CAAC;AAE5D,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,kCAAkC;AAClC,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAC5C,8DAA8D;AAC9D,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AACjD,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,QAAQ,CAAC;AAE9F,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AACjE,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAExD,MAAM,WAAW,iCAAiC;IACjD,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,8BAA8B;IAC9C;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,iCAAiC,GAAG,IAAI,CAAC;IAC/D,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,uBAAwB,YAAW,mBAAmB,EAAE,UAAU;;IAQ9E,EAAE,EAAE,SAAS,GAAG,IAAI,CAAoB;IACxC,MAAM,EAAE,YAAY,CAAyB;IAE7C,eAAe,EAAE,MAAM,CAAiB;IACxC,uBAAuB,EAAE,MAAM,CAAiB;IAChD,2EAA2E;IAC3E,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAoB;IACpD,yEAAyE;IACzE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAoB;IAClD,kFAAkF;IAClF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAoB;IAClD,qEAAqE;IACrE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAoB;IACpD;;;;;;;;OAQG;IACH,eAAe,EAAE,KAAK,GAAG,IAAI,CAAoB;IASjD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAyC;gBAExD,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,8BAAmC;IAWrE;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,SAAS,GAAE,OAAO,GAAG,iCAAiC,GAAG,IAAW,GAAG,IAAI;IA4CzF,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED;;;;OAIG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,OAAO,IAAI,IAAI;IA2Bf;;;;OAIG;IACH,UAAU,CAAC,IAAI,GAAE,MAA2B,GAAG,IAAI;IAQnD,sGAAsG;IACtG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAIxB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAa3B,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAK9D,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI;CAiH1D"}
+{"version":3,"file":"socket.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/socket.svelte.ts"],"names":[],"mappings":"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"}