@the-open-engine/zeroshot 6.11.0 → 6.13.0

package/lib/cluster/connection.cjs

@@ -0,0 +1,382 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Connection = exports.PROTOCOL_DIAGNOSTIC_CAPACITY = exports.CONNECTION_TRANSITIONS = void 0;
+const protocol_js_1 = require("./generated/protocol.cjs");
+const errors_js_1 = require("./errors.cjs");
+const frames_js_1 = require("./frames.cjs");
+const queue_js_1 = require("./queue.cjs");
+const socket_js_1 = require("./socket.cjs");
+const validators_js_1 = require("./validators.cjs");
+if (!Object.prototype.hasOwnProperty.call(Symbol, 'asyncDispose')) {
+    Object.defineProperty(Symbol, 'asyncDispose', {
+        configurable: false, enumerable: false,
+        value: Symbol.for('Symbol.asyncDispose'), writable: false,
+    });
+}
+exports.CONNECTION_TRANSITIONS = Object.freeze({
+    OPEN: Object.freeze(['CLOSING']),
+    CLOSING: Object.freeze(['CLOSED']),
+    CLOSED: Object.freeze([]),
+});
+exports.PROTOCOL_DIAGNOSTIC_CAPACITY = 128;
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((onResolve, onReject) => {
+        resolve = onResolve;
+        reject = onReject;
+    });
+    return { promise, resolve, reject };
+}
+class Connection {
+    #state = 'OPEN';
+    #sequence = 1;
+    #pending = new Map();
+    #subscriptions = new Map();
+    #lateSubscriptionReapers = new Set();
+    #removeSocketListeners = [];
+    #ownedSubscriptions = new WeakSet();
+    #closePromise;
+    closeDiagnostics = [];
+    protocolDiagnostics = [];
+    #socket;
+    constructor(socket) {
+        if (socket.readyState !== 1)
+            throw new errors_js_1.ClusterStateError('Connection requires an already-open WebSocket', 'SOCKET_NOT_OPEN');
+        this.#socket = socket;
+        this.#removeSocketListeners.push((0, socket_js_1.addSocketListener)(socket, 'message', (event) => this.#onMessage(event)), (0, socket_js_1.addSocketListener)(socket, 'error', () => { void this.#startClose(false); }), (0, socket_js_1.addSocketListener)(socket, 'close', () => { void this.#startClose(false); }));
+    }
+    get state() { return this.#state; }
+    get pendingSize() { return this.#pending.size; }
+    get subscriptionCount() { return this.#subscriptions.size; }
+    call(method, params, options = {}) {
+        if (!protocol_js_1.UNARY_METHODS.includes(method)) {
+            throw new errors_js_1.ClusterConfigError(`${method} is a subscription method`, 'INVALID_METHOD');
+        }
+        return this.#dispatch(method, params, options);
+    }
+    cancelSubscription(registration) {
+        if (!this.#ownedSubscriptions.has(registration)) {
+            return Promise.reject(new errors_js_1.ClusterStateError('subscription is not owned by this connection', 'UNOWNED_SUBSCRIPTION'));
+        }
+        if (registration.cancelSent)
+            return Promise.resolve();
+        registration.cancelSent = true;
+        return this.#sendNotification('subscription/cancel', { subscriptionId: registration.id });
+    }
+    openSubscription(method, params, options = {}) {
+        if (!protocol_js_1.SUBSCRIPTION_METHODS.includes(method)) {
+            throw new errors_js_1.ClusterConfigError(`${method} is not a subscription method`, 'INVALID_METHOD');
+        }
+        return this.#dispatch(method, params, options, method);
+    }
+    unregisterSubscription(id, registration) {
+        if (this.#subscriptions.get(id) !== registration)
+            return;
+        this.#subscriptions.delete(id);
+        this.#disarmSubscriptionAbort(registration);
+    }
+    recordDiagnostic(error) { this.closeDiagnostics.push(error); }
+    close() { return this.#startClose(true); }
+    #dispatch(method, params, options, subscriptionKind) {
+        this.#requireOpen();
+        if (options.signal?.aborted)
+            return Promise.reject((0, errors_js_1.requestAbortError)(method));
+        if (options.requestTimeoutMs !== undefined && options.requestTimeoutMs < 0)
+            return Promise.reject(new errors_js_1.ClusterConfigError('requestTimeoutMs must be non-negative', 'INVALID_TIMEOUT'));
+        const id = this.#allocateId();
+        const result = deferred();
+        const entry = { id, method, expectedId: id, resolve: result.resolve, reject: result.reject, settled: false, ...(subscriptionKind === undefined ? {} : { subscriptionKind }) };
+        this.#pending.set(id, entry);
+        if (options.signal) {
+            const onAbort = () => {
+                if (!this.#removeExact(id, entry))
+                    return;
+                this.#settleEntry(entry);
+                if (entry.subscriptionKind)
+                    this.#lateSubscriptionReapers.add(id);
+                entry.reject((0, errors_js_1.requestAbortError)(method));
+                void this.#sendNotification('$/cancelRequest', { id }).catch((error) => this.recordDiagnostic(error));
+            };
+            entry.signal = options.signal;
+            entry.abortHandler = onAbort;
+            options.signal.addEventListener('abort', onAbort, { once: true });
+        }
+        if (options.requestTimeoutMs !== undefined) {
+            entry.timeout = setTimeout(() => {
+                if (!this.#removeExact(id, entry))
+                    return;
+                this.#settleEntry(entry);
+                if (entry.subscriptionKind)
+                    this.#lateSubscriptionReapers.add(id);
+                entry.reject(new errors_js_1.ClusterTimeoutError(`${method} request timed out`, 'REQUEST_TIMEOUT'));
+                void this.#sendNotification('$/cancelRequest', { id }).catch((error) => this.recordDiagnostic(error));
+            }, options.requestTimeoutMs);
+        }
+        const request = { jsonrpc: protocol_js_1.JSON_RPC_VERSION, id, method, params };
+        void this.#sendFrame(request).catch((cause) => {
+            if (!this.#removeExact(id, entry))
+                return;
+            this.#settleEntry(entry);
+            entry.reject(new errors_js_1.ClusterTransportError(`failed to send ${method}`, 'SEND_FAILED', { cause }));
+        });
+        return result.promise;
+    }
+    #allocateId() { return `z${this.#sequence++}`; }
+    #removeExact(id, entry) { if (this.#pending.get(id) !== entry)
+        return false; this.#pending.delete(id); return true; }
+    #settleEntry(entry) {
+        if (entry.settled)
+            return;
+        entry.settled = true;
+        if (entry.timeout !== undefined)
+            clearTimeout(entry.timeout);
+        if (entry.signal && entry.abortHandler)
+            entry.signal.removeEventListener('abort', entry.abortHandler);
+    }
+    #requireOpen() { if (this.#state !== 'OPEN')
+        throw new errors_js_1.ClusterStateError(`connection is ${this.#state.toLowerCase()}`, `CONNECTION_${this.#state}`); }
+    async #sendFrame(value, allowClosing = false) {
+        if (this.#state === 'CLOSED' || (!allowClosing && this.#state !== 'OPEN'))
+            throw new errors_js_1.ClusterStateError(`connection is ${this.#state.toLowerCase()}`, `CONNECTION_${this.#state}`);
+        const payload = JSON.stringify(value);
+        if (this.#socket.send.length >= 2) {
+            await new Promise((resolve, reject) => { try {
+                this.#socket.send(payload, (error) => error ? reject(error) : resolve());
+            }
+            catch (error) {
+                reject(error);
+            } });
+            return;
+        }
+        const sent = this.#socket.send(payload);
+        if (sent && typeof sent.then === 'function')
+            await sent;
+    }
+    #sendNotification(method, params) {
+        return this.#sendFrame({ jsonrpc: protocol_js_1.JSON_RPC_VERSION, method, params }, true);
+    }
+    #onMessage(event) {
+        if (this.#state !== 'OPEN')
+            return;
+        const inbound = (0, frames_js_1.boundedFrameText)(event, protocol_js_1.MAX_FRAME_BYTES);
+        if (inbound.kind === 'unsupported') {
+            this.#recordProtocolError('WebSocket message is not text or bytes');
+            return;
+        }
+        if (inbound.kind === 'oversized') {
+            this.#recordProtocolError(`frame exceeds ${protocol_js_1.MAX_FRAME_BYTES} bytes`);
+            return;
+        }
+        const { text, bytes } = inbound;
+        let frame;
+        try {
+            frame = JSON.parse(text);
+        }
+        catch (cause) {
+            this.#recordProtocolError('invalid JSON frame', cause);
+            return;
+        }
+        if (!(0, frames_js_1.isRecord)(frame)) {
+            this.#recordProtocolError('invalid JSON-RPC frame');
+            return;
+        }
+        if ('id' in frame) {
+            this.#routeResponse(frame);
+            return;
+        }
+        if (frame.jsonrpc !== protocol_js_1.JSON_RPC_VERSION) {
+            this.#recordProtocolError('invalid JSON-RPC frame');
+            return;
+        }
+        if (typeof frame.method === 'string' && (0, frames_js_1.isRecord)(frame.params)) {
+            this.#routeNotification(frame.method, frame.params, frame, bytes);
+            return;
+        }
+        this.#recordProtocolError('unrecognized JSON-RPC frame');
+    }
+    #routeResponse(frame) {
+        if (typeof frame.id !== 'string') {
+            this.#recordProtocolError('response id is not a string');
+            return;
+        }
+        const entry = this.#pending.get(frame.id);
+        if (!entry) {
+            this.#reapLateSubscription(frame.id, frame.result);
+            return;
+        }
+        this.#removeExact(frame.id, entry);
+        this.#settleEntry(entry);
+        if (frame.id !== entry.expectedId || frame.jsonrpc !== protocol_js_1.JSON_RPC_VERSION) {
+            entry.reject(new errors_js_1.ClusterProtocolError('response identity mismatch', 'INVALID_RESPONSE_IDENTITY'));
+            return;
+        }
+        if ((0, frames_js_1.isRecord)(frame.error)) {
+            this.#routeRpcError(entry, frame.error);
+            return;
+        }
+        this.#routeSuccess(entry, frame);
+    }
+    #reapLateSubscription(id, result) {
+        if (!this.#lateSubscriptionReapers.delete(id) || !(0, frames_js_1.isRecord)(result))
+            return;
+        if (typeof result.subscriptionId !== 'string')
+            return;
+        void this.#sendNotification('subscription/cancel', { subscriptionId: result.subscriptionId })
+            .catch((error) => this.recordDiagnostic(error));
+    }
+    #routeRpcError(entry, error) {
+        try {
+            (0, validators_js_1.assertDefinition)('JsonRpcError', error);
+        }
+        catch (cause) {
+            entry.reject(cause);
+            return;
+        }
+        const data = (0, frames_js_1.isRecord)(error.data) ? error.data : undefined;
+        entry.reject(new errors_js_1.ClusterRpcError(error.code, error.message, data));
+    }
+    #routeSuccess(entry, frame) {
+        if (!('result' in frame)) {
+            entry.reject(new errors_js_1.ClusterProtocolError('response has neither result nor error', 'INVALID_RESPONSE'));
+            return;
+        }
+        try {
+            (0, validators_js_1.assertMethodResult)(entry.method, frame.result);
+        }
+        catch (error) {
+            if (entry.subscriptionKind && (0, frames_js_1.isRecord)(frame.result) && typeof frame.result.subscriptionId === 'string') {
+                void this.#sendNotification('subscription/cancel', { subscriptionId: frame.result.subscriptionId })
+                    .catch((cause) => this.recordDiagnostic(cause));
+            }
+            entry.reject(error);
+            return;
+        }
+        if (!entry.subscriptionKind) {
+            entry.resolve(frame.result);
+            return;
+        }
+        const result = frame.result;
+        const registration = {
+            id: result.subscriptionId, kind: entry.subscriptionKind,
+            queue: new queue_js_1.BoundedQueue(), overflowed: false, cancelSent: false,
+        };
+        if (this.#subscriptions.has(registration.id)) {
+            entry.reject(new errors_js_1.ClusterProtocolError('duplicate subscriptionId', 'DUPLICATE_SUBSCRIPTION'));
+            return;
+        }
+        this.#ownedSubscriptions.add(registration);
+        this.#subscriptions.set(registration.id, registration);
+        this.#armSubscriptionAbort(registration, entry.signal);
+        entry.resolve({ result, registration });
+    }
+    #armSubscriptionAbort(registration, signal) {
+        if (!signal)
+            return;
+        const onAbort = () => {
+            if (this.#subscriptions.get(registration.id) !== registration)
+                return;
+            this.unregisterSubscription(registration.id, registration);
+            registration.queue.closeAndDiscard();
+            void this.cancelSubscription(registration).catch((error) => this.recordDiagnostic(error));
+        };
+        registration.abortSignal = signal;
+        registration.abortHandler = onAbort;
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted)
+            onAbort();
+    }
+    #disarmSubscriptionAbort(registration) {
+        if (registration.abortSignal && registration.abortHandler) {
+            registration.abortSignal.removeEventListener('abort', registration.abortHandler);
+        }
+        delete registration.abortSignal;
+        delete registration.abortHandler;
+    }
+    #routeNotification(method, params, frame, bytes) {
+        const subscriptionId = params.subscriptionId;
+        if (typeof subscriptionId !== 'string') {
+            this.#recordProtocolError('subscription notification has no subscriptionId');
+            return;
+        }
+        const registration = this.#subscriptions.get(subscriptionId);
+        if (!registration)
+            return;
+        const terminal = method === 'subscription/closed';
+        const outcome = registration.queue.push(frame, bytes);
+        if (outcome === 'overflow') {
+            registration.overflowed = true;
+            this.unregisterSubscription(subscriptionId, registration);
+            registration.queue.endRetainingBuffer();
+            if (!terminal)
+                void this.cancelSubscription(registration).catch((error) => this.recordDiagnostic(error));
+            return;
+        }
+        if (terminal) {
+            this.unregisterSubscription(subscriptionId, registration);
+            registration.queue.endRetainingBuffer();
+        }
+    }
+    #recordProtocolError(message, cause) {
+        if (this.protocolDiagnostics.length === exports.PROTOCOL_DIAGNOSTIC_CAPACITY)
+            this.protocolDiagnostics.shift();
+        this.protocolDiagnostics.push(new errors_js_1.ClusterProtocolError(message, 'INVALID_PEER_FRAME', cause === undefined ? undefined : { cause }));
+    }
+    #startClose(sendCancels) {
+        if (this.#closePromise)
+            return this.#closePromise;
+        if (this.#state === 'CLOSED')
+            return Promise.resolve();
+        this.#transition('CLOSING');
+        this.#closePromise = Promise.resolve().then(() => this.#finishClose(sendCancels));
+        return this.#closePromise;
+    }
+    async #finishClose(sendCancels) {
+        const subscriptions = [...this.#subscriptions.values()];
+        this.#subscriptions.clear();
+        for (const subscription of subscriptions) {
+            this.#disarmSubscriptionAbort(subscription);
+            subscription.queue.closeAndDiscard();
+        }
+        const pending = [...this.#pending.values()];
+        this.#pending.clear();
+        for (const entry of pending) {
+            this.#settleEntry(entry);
+            entry.reject(new errors_js_1.ClusterTransportError('connection closed', 'CONNECTION_CLOSED'));
+        }
+        this.#lateSubscriptionReapers.clear();
+        if (sendCancels)
+            for (const subscription of subscriptions) {
+                try {
+                    await this.cancelSubscription(subscription);
+                }
+                catch (error) {
+                    this.recordDiagnostic(error);
+                }
+            }
+        try {
+            await this.#socket.close();
+        }
+        catch (error) {
+            this.recordDiagnostic(error);
+        }
+        for (const remove of this.#removeSocketListeners.splice(0)) {
+            try {
+                remove();
+            }
+            catch (error) {
+                this.recordDiagnostic(error);
+            }
+        }
+        this.#transition('CLOSED');
+    }
+    #transition(to) {
+        if (!exports.CONNECTION_TRANSITIONS[this.#state].includes(to))
+            throw new errors_js_1.ClusterInternalError(`illegal connection transition ${this.#state} -> ${to}`, 'ILLEGAL_STATE_TRANSITION');
+        this.#state = to;
+    }
+}
+exports.Connection = Connection;
+Object.defineProperty(Connection.prototype, Symbol.asyncDispose, {
+    configurable: true, value: Connection.prototype.close,
+});

package/lib/cluster/connection.d.ts

@@ -0,0 +1,41 @@
+import type { ClusterMethodParams, ClusterMethodResults, SubscriptionMethod, UnaryClusterMethod } from './generated/protocol.js';
+import { ClusterProtocolError } from './errors.js';
+import type { FrameRecord } from './frames.js';
+import { BoundedQueue } from './queue.js';
+import type { WebSocketLike } from './socket.js';
+export type ConnectionState = 'OPEN' | 'CLOSING' | 'CLOSED';
+export declare const CONNECTION_TRANSITIONS: Readonly<Record<ConnectionState, readonly ConnectionState[]>>;
+export declare const PROTOCOL_DIAGNOSTIC_CAPACITY = 128;
+export interface CallOptions {
+    readonly signal?: AbortSignal;
+    readonly requestTimeoutMs?: number;
+}
+export type SubscriptionKind = 'watch' | 'logs' | 'agent/attach';
+export type SubscriptionRegistration = {
+    readonly id: string;
+    readonly kind: SubscriptionKind;
+    readonly queue: BoundedQueue<FrameRecord>;
+    overflowed: boolean;
+    cancelSent: boolean;
+    abortHandler?: () => void;
+    abortSignal?: AbortSignal;
+};
+export type EstablishedSubscription<R> = {
+    readonly result: R;
+    readonly registration: SubscriptionRegistration;
+};
+export declare class Connection {
+    #private;
+    readonly closeDiagnostics: unknown[];
+    readonly protocolDiagnostics: ClusterProtocolError[];
+    constructor(socket: WebSocketLike);
+    get state(): ConnectionState;
+    get pendingSize(): number;
+    get subscriptionCount(): number;
+    call<M extends UnaryClusterMethod>(method: M, params: ClusterMethodParams[M], options?: CallOptions): Promise<ClusterMethodResults[M]>;
+    cancelSubscription(registration: SubscriptionRegistration): Promise<void>;
+    openSubscription<M extends SubscriptionMethod>(method: M, params: ClusterMethodParams[M], options?: CallOptions): Promise<EstablishedSubscription<ClusterMethodResults[M]>>;
+    unregisterSubscription(id: string, registration: SubscriptionRegistration): void;
+    recordDiagnostic(error: unknown): void;
+    close(): Promise<void>;
+}