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

package/lib/mjs/connection.js

@@ -0,0 +1,229 @@
+import { io } from 'socket.io-client';
+import { DEFAULT_RETRYABLE, MAX_ID_LENGTH, PROTOCOL_VERSION, SYSTEM_EVENTS, WIRE_EVENTS, isErrorCode, isId, isSocketError } from '@spinajs/http-socket-common';
+import { Emitter } from './emitter.js';
+import { assertTimeoutMs } from './timeout.js';
+import { ReconnectPolicy } from './reconnect.js';
+export const DEFAULT_CONNECT_TIMEOUT_MS = 20_000;
+/**
+ * Sole owner of the socket.io socket: state machine, handshake, reconnect and stop conditions.
+ * Commands, durable commands and streams use it and never touch socket.io directly.
+ */
+export class Connection {
+    constructor(options) {
+        this.options = options;
+        this.current = 'offline';
+        // no automatic attempt may start: before connect(), after disconnect()/close(), after a fatal refusal
+        this.stopped = true;
+        this.attempt = 0;
+        // bumped whenever an attempt is abandoned, so a late auth callback cannot revive it
+        this.attemptId = 0;
+        // the server refuses such a handshake with invalid_argument, which no retry can fix
+        if (!isId(options.clientId)) {
+            throw new RangeError(`clientId must be 1-${MAX_ID_LENGTH} printable ASCII characters`);
+        }
+        this.events = new Emitter(options.onListenerError);
+        this.policy = new ReconnectPolicy(options.reconnect);
+        this.connectTimeoutMs = assertTimeoutMs('connectTimeoutMs', options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS);
+        this.socket = io(options.url, {
+            ...options.io,
+            ...(options.path !== undefined ? { path: options.path } : {}),
+            autoConnect: false,
+            // socket.io's Manager does not retry refused handshakes or server disconnects and cannot
+            // honour retryAfterMs; one policy here covers all of them. Reusing this one Socket keeps its
+            // pid/offset, which connection state recovery needs.
+            reconnection: false,
+            // a Manager multiplexed with another client to the same URL would share its failures and closes
+            forceNew: true,
+            // socket.io's packet retries would re-send commands without idempotency keys
+            retries: 0,
+            auth: (cb) => this.provideAuth(cb),
+        });
+        this.socket.on('connect', () => this.onConnect());
+        this.socket.on('connect_error', (error) => this.onConnectError(error));
+        this.socket.on('disconnect', (reason) => this.onDisconnect(reason));
+        this.socket.on(WIRE_EVENTS.event, (frame) => this.onEventFrame(frame));
+    }
+    get state() {
+        return this.current;
+    }
+    get connected() {
+        return this.current === 'online' && this.socket.connected;
+    }
+    connect() {
+        if (this.current === 'closed')
+            throw new Error('the client is closed');
+        this.stopped = false;
+        this.kickCode = undefined;
+        if (this.current !== 'offline')
+            return;
+        this.retryAfterMs = undefined;
+        this.attempt = 0;
+        this.clearTimers();
+        this.open();
+    }
+    disconnect() {
+        if (this.current === 'closed')
+            return;
+        this.stopped = true;
+        this.abortAttempt();
+        this.setState('offline');
+    }
+    close() {
+        if (this.current === 'closed')
+            return;
+        this.stopped = true;
+        this.setState('closed');
+        this.abortAttempt();
+    }
+    send(event, ...args) {
+        if (!this.connected)
+            return false;
+        this.socket.emit(event, ...args);
+        return true;
+    }
+    request(event, data, onReply) {
+        if (!this.connected)
+            return false;
+        this.socket.emit(event, data, onReply);
+        return true;
+    }
+    listen(event, handler) {
+        this.socket.on(event, handler);
+        return () => {
+            this.socket.off(event, handler);
+        };
+    }
+    open() {
+        this.attemptId++;
+        this.setState('connecting');
+        // a state listener may have closed or stopped the connection
+        if (this.current !== 'connecting' || this.stopped)
+            return;
+        this.connectTimer = setTimeout(() => this.onConnectTimeout(), this.connectTimeoutMs);
+        this.socket.connect();
+    }
+    provideAuth(cb) {
+        const attemptId = this.attemptId;
+        Promise.resolve()
+            .then(() => this.options.auth?.())
+            .then((extra) => {
+            if (attemptId !== this.attemptId)
+                return;
+            const handshake = { ...extra, protocol: PROTOCOL_VERSION, clientId: this.options.clientId };
+            cb(handshake);
+        }, (error) => {
+            if (attemptId !== this.attemptId)
+                return;
+            const reason = error instanceof Error ? error.message : String(error);
+            this.halt('auth_required', { code: 'unauthenticated', message: `auth callback failed: ${reason}`, retryable: false });
+        });
+    }
+    onConnect() {
+        if (this.stopped || this.current === 'closed') {
+            this.socket.disconnect();
+            return;
+        }
+        this.clearTimers();
+        this.attempt = 0;
+        this.retryAfterMs = undefined;
+        this.kickCode = undefined;
+        this.setState('online');
+    }
+    onConnectError(error) {
+        this.clearConnectTimer();
+        if (this.stopped)
+            return;
+        const data = error.data;
+        if (isSocketError(data)) {
+            if (data.code === 'unauthenticated' || data.code === 'version_mismatch' || (data.retryable === false && data.code !== 'internal'))
+                return this.haltFor(data);
+            if (data.retryAfterMs !== undefined)
+                this.retryAfterMs = data.retryAfterMs;
+        }
+        this.scheduleRetry();
+    }
+    onDisconnect(reason) {
+        const kickCode = this.kickCode;
+        this.kickCode = undefined;
+        // socket.io re-sends what it buffered during a drop once it reconnects; only the durable
+        // queue may re-send a command, and only with an idempotency key
+        this.socket.sendBuffer = [];
+        if (this.current === 'closed')
+            return;
+        this.setState('offline');
+        if (this.stopped)
+            return;
+        // a sys.disconnect listener that wanted no reconnect has already called disconnect()
+        if (kickCode !== undefined && reason === 'io server disconnect') {
+            return this.haltFor({ code: kickCode, message: `the server disconnected the client: ${kickCode}`, retryable: false });
+        }
+        this.scheduleRetry();
+    }
+    onEventFrame(frame) {
+        if (frame?.name === SYSTEM_EVENTS.disconnect) {
+            // W1 sends the error code of the kick as the reason
+            const reason = frame.payload?.reason;
+            this.kickCode = isErrorCode(reason) && reason !== 'internal' && !DEFAULT_RETRYABLE[reason] ? reason : undefined;
+            return;
+        }
+        if (frame?.name !== SYSTEM_EVENTS.shutdown)
+            return;
+        const retryAfterMs = frame.payload?.retryAfterMs;
+        if (typeof retryAfterMs === 'number')
+            this.retryAfterMs = retryAfterMs;
+    }
+    onConnectTimeout() {
+        this.connectTimer = undefined;
+        this.abortAttempt();
+        this.scheduleRetry();
+    }
+    haltFor(error) {
+        this.halt(error.code === 'unauthenticated' ? 'auth_required' : error.code === 'version_mismatch' ? 'incompatible' : 'refused', error);
+    }
+    halt(event, error) {
+        this.stopped = true;
+        this.abortAttempt();
+        this.setState('offline');
+        this.events.emit(event, error);
+    }
+    scheduleRetry() {
+        this.clearTimers();
+        this.setState('offline');
+        // a state listener may have closed or stopped the connection
+        if (this.current !== 'offline' || this.stopped)
+            return;
+        const delay = this.policy.delay(this.attempt++, this.retryAfterMs);
+        this.retryAfterMs = undefined;
+        this.retryTimer = setTimeout(() => {
+            this.retryTimer = undefined;
+            if (!this.stopped && this.current === 'offline')
+                this.open();
+        }, delay);
+    }
+    abortAttempt() {
+        this.attemptId++;
+        this.clearTimers();
+        this.socket.disconnect();
+    }
+    clearTimers() {
+        this.clearConnectTimer();
+        if (this.retryTimer !== undefined) {
+            clearTimeout(this.retryTimer);
+            this.retryTimer = undefined;
+        }
+    }
+    clearConnectTimer() {
+        if (this.connectTimer !== undefined) {
+            clearTimeout(this.connectTimer);
+            this.connectTimer = undefined;
+        }
+    }
+    setState(next) {
+        if (this.current === next)
+            return;
+        const previous = this.current;
+        this.current = next;
+        this.events.emit('state', next, previous);
+    }
+}
+//# sourceMappingURL=connection.js.map

package/lib/mjs/connection.js.map

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

package/lib/mjs/contract.d.ts

@@ -0,0 +1,27 @@
+import type { ClientEventName, ClientEventPayload, CommandName, CommandPayload, CommandResult, ContractShape, EventName, EventPayload } from '@spinajs/http-socket-common';
+import type { ClientLifecycleEvents, LifecycleEventName, Unsubscribe } from './client.js';
+import type { CommandOptions } from './commands.js';
+import type { DurableCommandOptions } from './durable.js';
+import type { ConnectionState } from './connection.js';
+import type { StreamOptions } from './streams.js';
+/** A stream command declares its result as AsyncIterable<Item>; stream() yields the items. */
+export type StreamItem<C extends ContractShape, N extends CommandName<C>> = CommandResult<C, N> extends AsyncIterable<infer T> ? T : CommandResult<C, N>;
+/** A SocketClient seen through a contract: names and payloads are checked at compile time. */
+export interface TypedSocketClient<C extends ContractShape> {
+    readonly clientId: string;
+    readonly state: ConnectionState;
+    connect(): void;
+    disconnect(): void;
+    close(): Promise<void>;
+    command<N extends CommandName<C>>(name: N, payload: CommandPayload<C, N>, options?: CommandOptions): Promise<CommandResult<C, N>>;
+    durable<N extends CommandName<C>>(name: N, payload: CommandPayload<C, N>, options?: DurableCommandOptions): Promise<CommandResult<C, N>>;
+    stream<N extends CommandName<C>>(name: N, payload: CommandPayload<C, N>, options?: StreamOptions): AsyncIterableIterator<StreamItem<C, N>>;
+    emit<N extends ClientEventName<C>>(name: N, payload: ClientEventPayload<C, N>): boolean;
+    on<K extends LifecycleEventName>(event: K, listener: ClientLifecycleEvents[K]): Unsubscribe;
+    on<N extends EventName<C>>(event: N, listener: (payload: EventPayload<C, N>) => void): Unsubscribe;
+    once<K extends LifecycleEventName>(event: K, listener: ClientLifecycleEvents[K]): Unsubscribe;
+    once<N extends EventName<C>>(event: N, listener: (payload: EventPayload<C, N>) => void): Unsubscribe;
+    off<K extends LifecycleEventName>(event: K, listener: ClientLifecycleEvents[K]): void;
+    off<N extends EventName<C>>(event: N, listener: (payload: EventPayload<C, N>) => void): void;
+}
+//# sourceMappingURL=contract.d.ts.map

package/lib/mjs/contract.d.ts.map

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

package/lib/mjs/contract.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.js.map

package/lib/mjs/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/contract.ts"],"names":[],"mappings":""}

package/lib/mjs/durable.d.ts

@@ -0,0 +1,122 @@
+import { type SocketError } from '@spinajs/http-socket-common';
+import type { CommandDispatcher } from './commands.js';
+import type { Connection } from './connection.js';
+import { Emitter } from './emitter.js';
+import type { FailedOutboxEntry, OutboxEntry, OutboxStore } from './outbox.js';
+import { type ReconnectOptions } from './reconnect.js';
+export interface DurableOptions {
+    /** Durable commands sent and not yet answered at once. */
+    window?: number;
+    /** A command unanswered this long on a live connection is sent again; the server replays or joins it. */
+    ackTimeoutMs?: number;
+    /**
+     * Largest JSON-encoded payload, binary parts counted by length; the server's default limit. Checked
+     * before the command is persisted: one the server refuses for size would otherwise sit in the outbox.
+     */
+    maxPayloadBytes?: number;
+}
+export interface DurableCommandOptions {
+    /**
+     * Idempotency key, eg. an op id: 1-MAX_KEY_LENGTH printable ASCII characters, not starting with `${clientId}:`.
+     * When omitted, `${clientId}:${random nonce}` is generated and persisted with the entry.
+     */
+    key?: string;
+}
+export declare const DEFAULT_DURABLE: Readonly<Required<DurableOptions>>;
+export interface AckedCommand {
+    entry: OutboxEntry;
+    result: unknown;
+}
+export interface FailedCommand {
+    entry: FailedOutboxEntry;
+    error: SocketError;
+}
+export interface HeldCommand {
+    entry: OutboxEntry;
+    error: SocketError;
+}
+export interface DurableEvents {
+    acked: (event: AckedCommand) => void;
+    failed: (event: FailedCommand) => void;
+    /**
+     * The server refused a command as unauthenticated: the queue sends nothing until the connection
+     * comes online again. After a re-login the app reconnects ( disconnect() and connect() ) when the
+     * server has not closed the connection itself.
+     */
+    held: (event: HeldCommand) => void;
+}
+export interface DurableQueueOptions {
+    connection: Connection;
+    commands: CommandDispatcher;
+    store: OutboxStore;
+    clientId: string;
+    reconnect?: Partial<ReconnectOptions>;
+    durable?: DurableOptions;
+    /** Gets listener errors, and store failures that no submit() call can reject with. */
+    onListenerError?: (error: unknown) => void;
+}
+/**
+ * Durable commands ( spec §6 ): persisted before they are sent, sent in order up to a window, sent
+ * again after any drop, and settled in send order. The server runs each key once and runs a command
+ * only after the one named in its `after`, so a resend never runs twice and never overtakes.
+ */
+export declare class DurableQueue {
+    private readonly options;
+    readonly events: Emitter<DurableEvents>;
+    private readonly items;
+    private readonly policy;
+    private readonly window;
+    private readonly ackTimeoutMs;
+    private readonly maxPayloadBytes;
+    private readonly onStoreError;
+    private readonly unsubscribe;
+    /** generated keys start with it; app keys must not */
+    private readonly keyPrefix;
+    private loading;
+    private adding;
+    private attempt;
+    private pausedUntil;
+    private pauseTimer;
+    private probing;
+    private heldUntilOnline;
+    private closed;
+    private closing;
+    private onReported;
+    constructor(options: DurableQueueOptions);
+    /** Commands not yet settled to their callers, resumed ones included. */
+    get size(): number;
+    /**
+     * Persists the command, then sends it in order. Resolves with its result once it and every earlier
+     * command have settled. Rejects when the server refuses it for good ( it is then in the store's
+     * failed list ) or when the queue closes ( it stays in the outbox ). A caller that does not await
+     * it attaches a catch, or follows the `acked` and `failed` events instead.
+     */
+    submit(name: string, payload: unknown, options?: DurableCommandOptions): Promise<unknown>;
+    /**
+     * Rejects the callers still waiting for an answer; their entries stay in the store for the next start.
+     * Answered commands settle in send order once the store has applied their outcome, also after close.
+     * Resolves once the store has no write of this queue in flight and every answered command has been
+     * reported: only then may the next queue open the same store, and the listeners be dropped.
+     */
+    close(): Promise<void>;
+    /** Reads the store once; a failed read is tried again by the next submit() or the next time the connection comes online. */
+    private load;
+    private item;
+    private onState;
+    private pump;
+    private transmit;
+    private onReply;
+    private onAckTimeout;
+    private requeue;
+    /** One backoff for the whole queue: its commands are refused for shared reasons ( overload, shutdown ). */
+    private retry;
+    private succeed;
+    private fail;
+    private finish;
+    /** The caller hears of an outcome only once the store holds it, so a reload cannot undo what it was told. */
+    private record;
+    /** Callers and listeners hear about commands in send order, whatever order their replies came in. */
+    private settle;
+    private report;
+}
+//# sourceMappingURL=durable.d.ts.map

package/lib/mjs/durable.d.ts.map

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