@spinajs/http-socket-client 0.0.0-stage → 3.0.1

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# @spinajs/http-socket-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Client for `@spinajs/http-socket`, for browsers and Node. It handles the connection state, reconnects with backoff, and offers commands with timeouts and cancellation, server events, stream replies with flow control, and typed contracts. Its only dependencies are `socket.io-client` and `@spinajs/http-socket-common`, which it re-exports.
+
+A runnable server and client are in [`packages/http-socket-example`](../http-socket-example).
+
+Full documentation, including outbox stores and every extension point: [`docs/http-socket-client`](../../docs/http-socket-client/README.md).
+
+## Connect
+
+```ts
+import { SocketClient } from '@spinajs/http-socket-client';
+
+const client = new SocketClient({
+  url: 'https://app.example.com',
+  clientId: storedClientId, // stable per install; generated when omitted
+  auth: async () => ({ token: await tokens.current() }), // asked on every (re)connect
+  reconnect: { minMs: 500, maxMs: 30_000, jitter: 0.3 }, // the defaults
+  defaultTimeoutMs: 15_000, // the default
+});
+```
+
+`storedClientId` and `tokens` stand for your own code. Other options: `path` (socket.io endpoint, `/socket.io` by default), `connectTimeoutMs` (20 s), `io` (passed to `socket.io-client`; reconnection, `autoConnect`, `forceNew`, `retries` and `auth` stay owned by the client) and `onListenerError`.
+
+- The client connects on its own unless `autoConnect: false`.
+- `client.state` is `'connecting' | 'online' | 'offline' | 'closed'`, and `client.on('state', (state, previous) => ...)` reports every change.
+- `disconnect()` goes offline until `connect()`. `close()` is final: it rejects everything pending, except durable commands the server already answered (see Durable commands). It returns a promise; see below.
+
+**Reconnect.** The client retries with exponential backoff and jitter, and asks `auth()` again on every attempt. It stops in these cases:
+
+| Server answer | Lifecycle event |
+|---|---|
+| `unauthenticated` | `auth_required` |
+| `version_mismatch` | `incompatible` |
+| any other refusal with `retryable: false`, except `internal`, which is retried (`forbidden` for a foreign origin, `invalid_argument` ...) | `refused` |
+
+`connect()` tries again. A `sys.shutdown { retryAfterMs }` notice delays the next attempt. A `sys.disconnect` whose reason is a non-retryable error code (the server sends `unauthenticated` for a revoked credential) stops the client in the same way.
+
+## Commands
+
+```ts
+const doc = await client.command<OpenResult>('docs.open', { id }, { timeoutMs: 5_000, signal, whenOffline: 'wait' });
+```
+
+- `timeoutMs` covers the whole call. The server gets the remaining time as `deadline`.
+- `whenOffline: 'fail'` (the default) rejects at once with `unavailable`. `'wait'` holds the command until the client is online or the timeout passes.
+- Aborting `signal` sends `cancel`; the server's handler sees its own signal fire.
+- A drop in the middle of a command rejects it with a retryable `unavailable`. Plain commands are never sent twice.
+- Every rejection is a `SocketException` with `code`, `message`, `retryable` and, when the server sent them, `retryAfterMs`, `details` and `errorId`. Trust `retryable` and `retryAfterMs` when deciding to retry.
+
+## Events
+
+```ts
+const off = client.on<Committed>('docs.committed', (payload) => apply(payload));
+client.emit('docs.cursor', { x, y }); // fire-and-forget; false and dropped when not online
+```
+
+The lifecycle names (`state`, `auth_required`, `incompatible`, `refused`, `acked`, `failed`, `held`) are routed to the client's own listeners, so a server event with one of these names never reaches `on()`.
+
+## Durable commands
+
+```ts
+import { SocketClient } from '@spinajs/http-socket-client';
+import { IndexedDbOutboxStore } from '@spinajs/http-socket-client/browser'; // Node: FileOutboxStore from '/node'
+
+const client = new SocketClient({ url, clientId: storedClientId, outbox: new IndexedDbOutboxStore('app') });
+client.on('acked', ({ entry, result }) => {});
+client.on('failed', ({ entry, error }) => {}); // refused for good; the entry waits in the store's failed list
+await client.durable('docs.edit', { id, op }, { key: opId }).catch(() => undefined);
+```
+
+- The command is written to the outbox before it is sent, then sent in order, up to `durable.window` (16) at once, each with `after` set to the previous unacknowledged command. It carries no deadline. The server command must be `idempotent`. With `ordered: 'client'` it waits in the server's queue behind its predecessor; without it, the server only checks that the predecessor has completed and otherwise answers a retryable `unavailable`, which parks it until the predecessor's answer, then sends it again. Either way it runs after its predecessor, whatever its queue position.
+- After any drop everything unacknowledged is sent again, and so is a command unanswered for `durable.ackTimeoutMs` (60 s). Retryable errors are retried with the reconnect backoff.
+- `unauthenticated` keeps the queue and emits `held`; nothing is sent until the connection comes online again.
+- The key is your `key` (1 to 256 printable ASCII characters, not starting with `${clientId}:`) or a generated `${clientId}:<nonce>`.
+- Any `outbox` option, an explicit `MemoryOutboxStore` included, requires an explicit `clientId` stored by the app (the constructor throws a `RangeError` otherwise): a new random id after a reload would break exactly-once and ordering. Without the option, the default `MemoryOutboxStore` is used; it does not survive a reload.
+- `durable()` rejects when the server refuses the command for good and when the client closes before the server answered it (the entry stays in the outbox). A command the server already answered settles with that answer once the outbox has applied it, also after `close()`. Attach a `catch` or follow `acked` / `failed`.
+- `acked` and `failed` fire in send order, also for entries resumed from the outbox after a reload. The exception is `close()`: a command the server answered settles after the close, while an earlier one still unanswered is rejected and reported by the next client.
+- `await client.close()` before you open the next client or store on the same outbox, and keep your `acked` / `failed` listeners until it resolves. It resolves once the outbox has no write of this client in flight and every answered command has been reported. An answered command whose write lands after the close is reported only there: a resumed entry has no caller, and its `acked` is its only report. A `FileOutboxStore` opened on the same file while the old one still writes would overwrite that file from a stale copy, dropping new entries and bringing back removed ones.
+- `FileOutboxStore` keeps payloads as JSON, so its `add` (and `durable()`) rejects with a `TypeError` a payload that a JSON round trip would change: `Uint8Array`, `Buffer`, `ArrayBuffer`, `Date`, `Map`, `Set`, class instances, `NaN`/`Infinity`, `undefined` inside an array. Nothing is written. Encode such values yourself (bytes as base64, dates as ISO strings). An `undefined` property is allowed: the wire drops it too. `IndexedDbOutboxStore` and `MemoryOutboxStore` keep binary.
+
+## Streams
+
+```ts
+for await (const frame of client.stream<SnapshotFrame>('docs.snapshot', { docId }, { credits: 8 })) {
+  apply(frame);
+  if (cancelled) break; // sends cancel; the server generator's finally runs
+}
+```
+
+- `stream()` returns an async iterator. The request goes out on the first `next()`. Calls to `next()` must not overlap.
+- **Flow control.**
+  - `credits` (default `DEFAULT_STREAM_CREDITS`, 8) is the most chunks that are ever in flight or buffered.
+  - The client grants more as you read, in batches of at least half the window.
+  - It must not exceed the server's `http.socket.streams.maxCredits` (64 by default). The server also refuses a window that, with what is granted but not yet used, goes over it.
+- **Timeouts.** `timeoutMs` bounds the wait for the reply, and then each wait in `next()` for the next frame. A consumer that is slow to call `next()` is never timed out. The server ends a stream that gets no credit for its `streams.stallTimeoutMs`.
+- **Failures.** On a server `fail`, a dropped connection (`unavailable`, retryable) or a closed client, the chunks already received are delivered first, then the iterator throws. Aborting `signal` drops buffered chunks, cancels the stream and throws `cancelled`.
+- **Mismatches.** `stream()` on a command that answers a plain result throws `failed_precondition`, and so does `command()` on a stream command.
+- **Resume.** The library does not resume streams. Put the position in the payload (for example `fromChunk`) and start a new stream after a retryable failure; with `whenOffline: 'wait'` it waits for the reconnect. `loadSnapshot` in [`packages/http-socket-example/src/client.ts`](../http-socket-example/src/client.ts) is a complete example.
+
+## Typed contracts
+
+One contract module, shared by the server and the client, types names and payloads:
+
+```ts
+import { defineContract } from '@spinajs/http-socket-client';
+
+export type DocsContract = {
+  commands: {
+    'docs.open': [{ id: string }, { title: string }];
+    'docs.snapshot': [{ docId: string; fromChunk?: number }, AsyncIterable<SnapshotFrame>];
+  };
+  events: { 'docs.committed': { seq: number } };
+  clientEvents: { 'docs.cursor': { x: number; y: number } };
+};
+
+export const docsContract = defineContract<DocsContract>();
+
+const docs = client.typed(docsContract);
+const opened = await docs.command('docs.open', { id: 'a' }); // { title: string }
+for await (const frame of docs.stream('docs.snapshot', { docId: 'a' })) {
+} // frame: SnapshotFrame
+docs.on('docs.committed', ({ seq }) => {});
+```
+
+Declare contracts with `type`, not `interface`. A stream command declares its result as `AsyncIterable<Item>`. The server side imports `defineContract` and the contract types from `@spinajs/http-socket-common` (or `@spinajs/http-socket`, which re-exports it); [`packages/http-socket-example/src/contract.ts`](../http-socket-example/src/contract.ts) is shared by both sides.
+
+## Binary
+
+`Uint8Array`, `ArrayBuffer` and `Buffer` anywhere in a payload travel as binary attachments and count toward the server's `maxPayloadBytes` by byte length. Binary results arrive as an `ArrayBuffer` in browsers and as a `Buffer` in Node; `new Uint8Array(result)` reads both.

package/lib/cjs/browser.d.ts

@@ -0,0 +1,4 @@
+export * from './index.js';
+export { IndexedDbOutboxStore } from './outbox-indexeddb.js';
+export type { IndexedDbOutboxOptions } from './outbox-indexeddb.js';
+//# sourceMappingURL=browser.d.ts.map

package/lib/cjs/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC"}

package/lib/cjs/browser.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndexedDbOutboxStore = void 0;
+__exportStar(require("./index.js"), exports);
+var outbox_indexeddb_js_1 = require("./outbox-indexeddb.js");
+Object.defineProperty(exports, "IndexedDbOutboxStore", { enumerable: true, get: function () { return outbox_indexeddb_js_1.IndexedDbOutboxStore; } });
+//# sourceMappingURL=browser.js.map

package/lib/cjs/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,6DAA6D;AAApD,2HAAA,oBAAoB,OAAA"}

package/lib/cjs/client.d.ts

@@ -0,0 +1,94 @@
+import { type ContractShape, type SocketContract, type SocketError } from '@spinajs/http-socket-common';
+import { type CommandOptions } from './commands.js';
+import { type AuthProvider, type ConnectionState, type IoOptions } from './connection.js';
+import type { TypedSocketClient } from './contract.js';
+import { type AckedCommand, type DurableCommandOptions, type DurableOptions, type FailedCommand, type HeldCommand } from './durable.js';
+import { type OutboxStore } from './outbox.js';
+import type { ReconnectOptions } from './reconnect.js';
+import { type StreamOptions } from './streams.js';
+export interface SocketClientOptions {
+    /** Server origin; a path in it selects a socket.io namespace. */
+    url: string;
+    /** socket.io endpoint path (socket.io's default: '/socket.io'). */
+    path?: string;
+    /** Asked on every (re)connect; its fields go into the handshake. */
+    auth?: AuthProvider;
+    /** Stable per install, persisted by the app; 1 to MAX_ID_LENGTH printable ASCII characters. Generated when omitted. */
+    clientId?: string;
+    reconnect?: Partial<ReconnectOptions>;
+    defaultTimeoutMs?: number;
+    connectTimeoutMs?: number;
+    autoConnect?: boolean;
+    /** Passed to socket.io-client; reconnection, autoConnect, forceNew, retries and auth stay owned by the client. */
+    io?: IoOptions;
+    /**
+     * Where durable commands wait for their reply. The MemoryOutboxStore default does not survive a reload: browsers pass
+     * IndexedDbOutboxStore ( `/browser` ), Node passes FileOutboxStore ( `/node` ). Requires an explicit `clientId`.
+     */
+    outbox?: OutboxStore;
+    durable?: DurableOptions;
+    onListenerError?: (error: unknown) => void;
+}
+export interface ClientLifecycleEvents {
+    state: (state: ConnectionState, previous: ConnectionState) => void;
+    auth_required: (error: SocketError) => void;
+    incompatible: (error: SocketError) => void;
+    /** The server refused the connection for a reason no retry can fix (forbidden, invalid_argument …); connect() tries again. */
+    refused: (error: SocketError) => void;
+    /** A durable command was acknowledged; also for commands resumed from the outbox after a reload. In send order. */
+    acked: (event: AckedCommand) => void;
+    /** A durable command the server refused for good; it is in the outbox's failed list. In send order. */
+    failed: (event: FailedCommand) => void;
+    /** A durable command was refused as unauthenticated and stays queued; the queue sends nothing until the connection comes online again. */
+    held: (event: HeldCommand) => void;
+}
+export type LifecycleEventName = keyof ClientLifecycleEvents;
+/** Names `on()` routes to client lifecycle listeners; server events with these names are unreachable. */
+export declare const LIFECYCLE_EVENTS: ReadonlySet<string>;
+export type ServerEventListener<T = unknown> = (payload: T) => void;
+export type Unsubscribe = () => void;
+export declare class SocketClient {
+    readonly clientId: string;
+    private readonly connection;
+    private readonly commands;
+    private readonly durableQueue;
+    private readonly streams;
+    private readonly lifecycle;
+    private readonly serverEvents;
+    private controlled;
+    constructor(options: SocketClientOptions);
+    private autoConnect;
+    get state(): ConnectionState;
+    connect(): void;
+    /** Goes offline and stops reconnecting until connect(). */
+    disconnect(): void;
+    /**
+     * Terminal: rejects pending commands and releases the socket. Resolves once the outbox has no write of this
+     * client in flight and every answered durable command has been reported: await it before opening the next
+     * client or store on the same outbox, and keep the `acked` / `failed` listeners until then.
+     * The outbox store is not closed: call `store.close()` yourself to release its lock and connection before reopening the same name.
+     */
+    close(): Promise<void>;
+    /** The same client, typed by a contract shared with the server; no runtime cost. */
+    typed<C extends ContractShape>(_contract: SocketContract<C>): TypedSocketClient<C>;
+    command<R = unknown>(name: string, payload?: unknown, options?: CommandOptions): Promise<R>;
+    /**
+     * Persisted, ordered and retried until the server answers ( spec §6 ); the server command must be idempotent; `ordered: 'client'` is optional, the `after` fence alone orders execution.
+     * With the default MemoryOutboxStore the queue is lost on reload; pass `outbox` ( IndexedDbOutboxStore in browsers, FileOutboxStore in Node ) to keep it.
+     */
+    durable<R = unknown>(name: string, payload?: unknown, options?: DurableCommandOptions): Promise<R>;
+    /**
+     * A stream reply as an async iterator. The request goes out on the first `next()`; at most
+     * `credits` chunks are in flight or buffered; `break` cancels it on the server.
+     */
+    stream<T = unknown>(name: string, payload?: unknown, options?: StreamOptions): AsyncIterableIterator<T>;
+    /** Fire-and-forget event to the server; returns false and drops it when not online. */
+    emit(name: string, payload?: unknown): boolean;
+    on<K extends LifecycleEventName>(event: K, listener: ClientLifecycleEvents[K]): Unsubscribe;
+    on<T = unknown>(event: string, listener: ServerEventListener<T>): Unsubscribe;
+    once<K extends LifecycleEventName>(event: K, listener: ClientLifecycleEvents[K]): Unsubscribe;
+    once<T = unknown>(event: string, listener: ServerEventListener<T>): Unsubscribe;
+    off<K extends LifecycleEventName>(event: K, listener: ClientLifecycleEvents[K]): void;
+    off<T = unknown>(event: string, listener: ServerEventListener<T>): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/lib/cjs/client.d.ts.map

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

package/lib/cjs/client.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketClient = exports.LIFECYCLE_EVENTS = void 0;
+const http_socket_common_1 = require("@spinajs/http-socket-common");
+const commands_js_1 = require("./commands.js");
+const connection_js_1 = require("./connection.js");
+const durable_js_1 = require("./durable.js");
+const emitter_js_1 = require("./emitter.js");
+const ids_js_1 = require("./ids.js");
+const outbox_js_1 = require("./outbox.js");
+const streams_js_1 = require("./streams.js");
+/** Names `on()` routes to client lifecycle listeners; server events with these names are unreachable. */
+exports.LIFECYCLE_EVENTS = new Set(['state', 'auth_required', 'incompatible', 'refused', 'acked', 'failed', 'held']);
+function isLifecycleEvent(event) {
+    return exports.LIFECYCLE_EVENTS.has(event);
+}
+class SocketClient {
+    constructor(options) {
+        // set once the app calls connect(), disconnect() or close(), which then override autoConnect
+        this.controlled = false;
+        const onListenerError = options.onListenerError ?? emitter_js_1.rethrowAsync;
+        // persisted keys are `${clientId}:…`: a fresh random id after a reload would break exactly-once and ordering
+        if (options.outbox !== undefined && options.clientId === undefined) {
+            throw new RangeError('an outbox requires a stable clientId, persisted by the app');
+        }
+        this.clientId = options.clientId ?? (0, ids_js_1.randomId)();
+        this.lifecycle = new emitter_js_1.Emitter(onListenerError);
+        this.serverEvents = new emitter_js_1.Emitter(onListenerError);
+        this.connection = new connection_js_1.Connection({
+            url: options.url,
+            path: options.path,
+            clientId: this.clientId,
+            auth: options.auth,
+            reconnect: options.reconnect,
+            connectTimeoutMs: options.connectTimeoutMs,
+            io: options.io,
+            onListenerError,
+        });
+        try {
+            this.commands = new commands_js_1.CommandDispatcher(this.connection, options.defaultTimeoutMs ?? commands_js_1.DEFAULT_TIMEOUT_MS);
+            this.durableQueue = new durable_js_1.DurableQueue({
+                connection: this.connection,
+                commands: this.commands,
+                store: options.outbox ?? new outbox_js_1.MemoryOutboxStore(),
+                clientId: this.clientId,
+                reconnect: options.reconnect,
+                durable: options.durable,
+                onListenerError,
+            });
+        }
+        catch (error) {
+            // invalid options must not leave a socket behind
+            this.connection.close();
+            throw error;
+        }
+        this.durableQueue.events.on('acked', (event) => this.lifecycle.emit('acked', event));
+        this.durableQueue.events.on('failed', (event) => this.lifecycle.emit('failed', event));
+        this.durableQueue.events.on('held', (event) => this.lifecycle.emit('held', event));
+        this.streams = new streams_js_1.StreamDispatcher(this.connection, () => this.commands.nextId(), options.defaultTimeoutMs ?? commands_js_1.DEFAULT_TIMEOUT_MS);
+        this.connection.events.on('state', (state, previous) => this.lifecycle.emit('state', state, previous));
+        this.connection.events.on('auth_required', (error) => this.lifecycle.emit('auth_required', error));
+        this.connection.events.on('incompatible', (error) => this.lifecycle.emit('incompatible', error));
+        this.connection.events.on('refused', (error) => this.lifecycle.emit('refused', error));
+        this.connection.listen(http_socket_common_1.WIRE_EVENTS.event, (frame) => {
+            if (typeof frame?.name === 'string')
+                this.serverEvents.emit(frame.name, frame.payload);
+        });
+        // a microtask, so listeners attached right after construction still see 'connecting'
+        if (options.autoConnect !== false)
+            queueMicrotask(() => this.autoConnect());
+    }
+    autoConnect() {
+        if (!this.controlled)
+            this.connection.connect();
+    }
+    get state() {
+        return this.connection.state;
+    }
+    connect() {
+        this.controlled = true;
+        this.connection.connect();
+    }
+    /** Goes offline and stops reconnecting until connect(). */
+    disconnect() {
+        this.controlled = true;
+        this.connection.disconnect();
+    }
+    /**
+     * Terminal: rejects pending commands and releases the socket. Resolves once the outbox has no write of this
+     * client in flight and every answered durable command has been reported: await it before opening the next
+     * client or store on the same outbox, and keep the `acked` / `failed` listeners until then.
+     * The outbox store is not closed: call `store.close()` yourself to release its lock and connection before reopening the same name.
+     */
+    close() {
+        this.controlled = true;
+        this.connection.close();
+        return this.durableQueue.close();
+    }
+    /** The same client, typed by a contract shared with the server; no runtime cost. */
+    typed(_contract) {
+        return this;
+    }
+    command(name, payload, options) {
+        return this.commands.execute(name, payload, options);
+    }
+    /**
+     * Persisted, ordered and retried until the server answers ( spec §6 ); the server command must be idempotent; `ordered: 'client'` is optional, the `after` fence alone orders execution.
+     * With the default MemoryOutboxStore the queue is lost on reload; pass `outbox` ( IndexedDbOutboxStore in browsers, FileOutboxStore in Node ) to keep it.
+     */
+    durable(name, payload, options) {
+        return this.durableQueue.submit(name, payload, options);
+    }
+    /**
+     * A stream reply as an async iterator. The request goes out on the first `next()`; at most
+     * `credits` chunks are in flight or buffered; `break` cancels it on the server.
+     */
+    stream(name, payload, options) {
+        return this.streams.stream(name, payload, options);
+    }
+    /** Fire-and-forget event to the server; returns false and drops it when not online. */
+    emit(name, payload) {
+        const frame = { name, payload };
+        return this.connection.send(http_socket_common_1.WIRE_EVENTS.event, frame);
+    }
+    on(event, listener) {
+        return isLifecycleEvent(event) ? this.lifecycle.on(event, listener) : this.serverEvents.on(event, listener);
+    }
+    once(event, listener) {
+        return isLifecycleEvent(event) ? this.lifecycle.once(event, listener) : this.serverEvents.once(event, listener);
+    }
+    off(event, listener) {
+        if (isLifecycleEvent(event))
+            this.lifecycle.off(event, listener);
+        else
+            this.serverEvents.off(event, listener);
+    }
+}
+exports.SocketClient = SocketClient;
+//# sourceMappingURL=client.js.map

package/lib/cjs/client.js.map

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

package/lib/cjs/commands.d.ts

@@ -0,0 +1,30 @@
+import type { Connection } from './connection.js';
+export type WhenOffline = 'fail' | 'wait';
+export interface CommandOptions {
+    /** Budget for the whole call: the wait for a connection (whenOffline 'wait') and for the reply. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    whenOffline?: WhenOffline;
+    /** W3C trace context, carried into the server handler. */
+    traceparent?: string;
+}
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+/** Plain (non-durable) commands: one attempt each, never re-sent. */
+export declare class CommandDispatcher {
+    private readonly connection;
+    private readonly defaultTimeoutMs;
+    private seq;
+    private readonly waiting;
+    private readonly inFlight;
+    constructor(connection: Connection, defaultTimeoutMs?: number);
+    /** Unique per client instance; durable and stream requests take ids from here too. */
+    nextId(): string;
+    execute(name: string, payload: unknown, options?: CommandOptions): Promise<unknown>;
+    private transmit;
+    private onReply;
+    private onState;
+    private succeed;
+    private fail;
+    private finish;
+}
+//# sourceMappingURL=commands.d.ts.map

package/lib/cjs/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/commands.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,iBAAiB,CAAC;AAGnE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B,mGAAmG;IACnG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAuBzC,qEAAqE;AACrE,qBAAa,iBAAiB;IAMhB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAAc,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IALtF,OAAO,CAAC,GAAG,CAAK;IAEhB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IAEtD,YAA6B,UAAU,EAAE,UAAU,EAAmB,gBAAgB,GAAE,MAA2B,EAGlH;IAED,sFAAsF;IAC/E,MAAM,IAAI,MAAM,CAEtB;IAEM,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAwC7F;IAED,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,MAAM;CAQf"}

package/lib/cjs/commands.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandDispatcher = exports.DEFAULT_TIMEOUT_MS = void 0;
+const http_socket_common_1 = require("@spinajs/http-socket-common");
+const timeout_js_1 = require("./timeout.js");
+exports.DEFAULT_TIMEOUT_MS = 15_000;
+const CLOSED = { code: 'unavailable', message: 'the client is closed', retryable: false };
+const OFFLINE = { code: 'unavailable', message: 'the client is offline', retryable: true };
+const STAYED_OFFLINE = { code: 'unavailable', message: 'the client stayed offline until the timeout', retryable: true };
+const CONNECTION_LOST = { code: 'unavailable', message: 'the connection dropped before the reply', retryable: true };
+const NO_REPLY = { code: 'deadline_exceeded', message: 'no reply before the timeout', retryable: true };
+const CANCELLED = { code: 'cancelled', message: 'the command was cancelled', retryable: false };
+const STREAM_REPLY = { code: 'failed_precondition', message: 'the command replies with a stream; use stream()', retryable: false };
+const MALFORMED_REPLY = { code: 'internal', message: 'malformed reply', retryable: false };
+/** Plain (non-durable) commands: one attempt each, never re-sent. */
+class CommandDispatcher {
+    constructor(connection, defaultTimeoutMs = exports.DEFAULT_TIMEOUT_MS) {
+        this.connection = connection;
+        this.defaultTimeoutMs = defaultTimeoutMs;
+        this.seq = 0;
+        // insertion-ordered, so commands held while offline go out in call order
+        this.waiting = new Set();
+        this.inFlight = new Set();
+        (0, timeout_js_1.assertTimeoutMs)('defaultTimeoutMs', defaultTimeoutMs);
+        connection.events.on('state', (state, previous) => this.onState(state, previous));
+    }
+    /** Unique per client instance; durable and stream requests take ids from here too. */
+    nextId() {
+        return (++this.seq).toString(36);
+    }
+    execute(name, payload, options = {}) {
+        const timeoutMs = options.timeoutMs ?? this.defaultTimeoutMs;
+        try {
+            (0, timeout_js_1.assertTimeoutMs)('timeoutMs', timeoutMs);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        if (this.connection.state === 'closed')
+            return rejected(CLOSED);
+        if (options.signal?.aborted)
+            return rejected(CANCELLED);
+        if (!this.connection.connected && (options.whenOffline ?? 'fail') === 'fail')
+            return rejected(OFFLINE);
+        const request = { id: this.nextId(), name, payload };
+        if (options.traceparent !== undefined)
+            request.traceparent = options.traceparent;
+        const signal = options.signal;
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                if (command.sent) {
+                    const cancel = { id: request.id };
+                    this.connection.send(http_socket_common_1.WIRE_EVENTS.cancel, cancel);
+                }
+                this.fail(command, CANCELLED);
+            };
+            const timer = setTimeout(() => this.fail(command, command.sent ? NO_REPLY : STAYED_OFFLINE), timeoutMs);
+            const command = {
+                request,
+                deadlineAt: Date.now() + timeoutMs,
+                sent: false,
+                done: false,
+                resolve,
+                reject,
+                dispose: () => {
+                    clearTimeout(timer);
+                    signal?.removeEventListener('abort', onAbort);
+                },
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            if (this.connection.connected)
+                this.transmit(command);
+            else
+                this.waiting.add(command);
+        });
+    }
+    transmit(command) {
+        this.waiting.delete(command);
+        // relative, so client/server clock skew cannot expire it; the server ignores a deadline <= 0
+        command.request.deadline = Math.max(1, command.deadlineAt - Date.now());
+        command.sent = true;
+        this.inFlight.add(command);
+        const sent = this.connection.request(http_socket_common_1.WIRE_EVENTS.command, command.request, (reply) => this.onReply(command, reply));
+        if (!sent)
+            this.fail(command, CONNECTION_LOST);
+    }
+    onReply(command, reply) {
+        if (typeof reply !== 'object' || reply === null || typeof reply.ok !== 'boolean')
+            return this.fail(command, MALFORMED_REPLY);
+        if (!reply.ok)
+            return this.fail(command, (0, http_socket_common_1.isSocketError)(reply.error) ? reply.error : MALFORMED_REPLY);
+        // a CommandStreamReply: the result follows as stream frames, which only stream() consumes
+        if ('stream' in reply)
+            return this.fail(command, STREAM_REPLY);
+        this.succeed(command, reply.result);
+    }
+    onState(state, previous) {
+        if (state === 'closed') {
+            for (const command of [...this.waiting, ...this.inFlight])
+                this.fail(command, CLOSED);
+            return;
+        }
+        if (previous === 'online')
+            for (const command of [...this.inFlight])
+                this.fail(command, CONNECTION_LOST);
+        if (state === 'online')
+            for (const command of [...this.waiting])
+                this.transmit(command);
+    }
+    succeed(command, value) {
+        if (this.finish(command))
+            command.resolve(value);
+    }
+    fail(command, error) {
+        if (this.finish(command))
+            command.reject(http_socket_common_1.SocketException.fromWire(error));
+    }
+    finish(command) {
+        if (command.done)
+            return false;
+        command.done = true;
+        command.dispose();
+        this.waiting.delete(command);
+        this.inFlight.delete(command);
+        return true;
+    }
+}
+exports.CommandDispatcher = CommandDispatcher;
+function rejected(error) {
+    return Promise.reject(http_socket_common_1.SocketException.fromWire(error));
+}
+//# sourceMappingURL=commands.js.map

package/lib/cjs/commands.js.map

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