@the-open-engine/zeroshot 6.11.0 → 6.12.0

package/lib/cluster/connection.mjs

@@ -0,0 +1,378 @@
+import { JSON_RPC_VERSION, MAX_FRAME_BYTES, SUBSCRIPTION_METHODS, UNARY_METHODS } from './generated/protocol.mjs';
+import { ClusterConfigError, ClusterInternalError, ClusterProtocolError, ClusterRpcError, ClusterStateError, ClusterTimeoutError, ClusterTransportError, requestAbortError, } from './errors.mjs';
+import { boundedFrameText, isRecord } from './frames.mjs';
+import { BoundedQueue } from './queue.mjs';
+import { addSocketListener } from './socket.mjs';
+import { assertDefinition, assertMethodResult } from './validators.mjs';
+if (!Object.prototype.hasOwnProperty.call(Symbol, 'asyncDispose')) {
+    Object.defineProperty(Symbol, 'asyncDispose', {
+        configurable: false, enumerable: false,
+        value: Symbol.for('Symbol.asyncDispose'), writable: false,
+    });
+}
+export const CONNECTION_TRANSITIONS = Object.freeze({
+    OPEN: Object.freeze(['CLOSING']),
+    CLOSING: Object.freeze(['CLOSED']),
+    CLOSED: Object.freeze([]),
+});
+export const PROTOCOL_DIAGNOSTIC_CAPACITY = 128;
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((onResolve, onReject) => {
+        resolve = onResolve;
+        reject = onReject;
+    });
+    return { promise, resolve, reject };
+}
+export 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 ClusterStateError('Connection requires an already-open WebSocket', 'SOCKET_NOT_OPEN');
+        this.#socket = socket;
+        this.#removeSocketListeners.push(addSocketListener(socket, 'message', (event) => this.#onMessage(event)), addSocketListener(socket, 'error', () => { void this.#startClose(false); }), 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 (!UNARY_METHODS.includes(method)) {
+            throw new 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 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 (!SUBSCRIPTION_METHODS.includes(method)) {
+            throw new 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(requestAbortError(method));
+        if (options.requestTimeoutMs !== undefined && options.requestTimeoutMs < 0)
+            return Promise.reject(new 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(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 ClusterTimeoutError(`${method} request timed out`, 'REQUEST_TIMEOUT'));
+                void this.#sendNotification('$/cancelRequest', { id }).catch((error) => this.recordDiagnostic(error));
+            }, options.requestTimeoutMs);
+        }
+        const request = { jsonrpc: JSON_RPC_VERSION, id, method, params };
+        void this.#sendFrame(request).catch((cause) => {
+            if (!this.#removeExact(id, entry))
+                return;
+            this.#settleEntry(entry);
+            entry.reject(new 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 ClusterStateError(`connection is ${this.#state.toLowerCase()}`, `CONNECTION_${this.#state}`); }
+    async #sendFrame(value, allowClosing = false) {
+        if (this.#state === 'CLOSED' || (!allowClosing && this.#state !== 'OPEN'))
+            throw new 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: JSON_RPC_VERSION, method, params }, true);
+    }
+    #onMessage(event) {
+        if (this.#state !== 'OPEN')
+            return;
+        const inbound = boundedFrameText(event, 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 ${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 (!isRecord(frame)) {
+            this.#recordProtocolError('invalid JSON-RPC frame');
+            return;
+        }
+        if ('id' in frame) {
+            this.#routeResponse(frame);
+            return;
+        }
+        if (frame.jsonrpc !== JSON_RPC_VERSION) {
+            this.#recordProtocolError('invalid JSON-RPC frame');
+            return;
+        }
+        if (typeof frame.method === 'string' && 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 !== JSON_RPC_VERSION) {
+            entry.reject(new ClusterProtocolError('response identity mismatch', 'INVALID_RESPONSE_IDENTITY'));
+            return;
+        }
+        if (isRecord(frame.error)) {
+            this.#routeRpcError(entry, frame.error);
+            return;
+        }
+        this.#routeSuccess(entry, frame);
+    }
+    #reapLateSubscription(id, result) {
+        if (!this.#lateSubscriptionReapers.delete(id) || !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 {
+            assertDefinition('JsonRpcError', error);
+        }
+        catch (cause) {
+            entry.reject(cause);
+            return;
+        }
+        const data = isRecord(error.data) ? error.data : undefined;
+        entry.reject(new ClusterRpcError(error.code, error.message, data));
+    }
+    #routeSuccess(entry, frame) {
+        if (!('result' in frame)) {
+            entry.reject(new ClusterProtocolError('response has neither result nor error', 'INVALID_RESPONSE'));
+            return;
+        }
+        try {
+            assertMethodResult(entry.method, frame.result);
+        }
+        catch (error) {
+            if (entry.subscriptionKind && 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 BoundedQueue(), overflowed: false, cancelSent: false,
+        };
+        if (this.#subscriptions.has(registration.id)) {
+            entry.reject(new 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 === PROTOCOL_DIAGNOSTIC_CAPACITY)
+            this.protocolDiagnostics.shift();
+        this.protocolDiagnostics.push(new 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 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 (!CONNECTION_TRANSITIONS[this.#state].includes(to))
+            throw new ClusterInternalError(`illegal connection transition ${this.#state} -> ${to}`, 'ILLEGAL_STATE_TRANSITION');
+        this.#state = to;
+    }
+}
+Object.defineProperty(Connection.prototype, Symbol.asyncDispose, {
+    configurable: true, value: Connection.prototype.close,
+});

package/lib/cluster/errors.cjs

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClusterRpcError = exports.ClusterTimeoutError = exports.ClusterTransportError = exports.ClusterProtocolError = exports.ClusterInternalError = exports.ClusterStateError = exports.ClusterConfigError = exports.ClusterError = void 0;
+exports.requestAbortError = requestAbortError;
+class ClusterError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = new.target.name;
+    }
+}
+exports.ClusterError = ClusterError;
+class ClusterConfigError extends ClusterError {
+}
+exports.ClusterConfigError = ClusterConfigError;
+class ClusterStateError extends ClusterError {
+}
+exports.ClusterStateError = ClusterStateError;
+class ClusterInternalError extends ClusterError {
+}
+exports.ClusterInternalError = ClusterInternalError;
+class ClusterProtocolError extends ClusterError {
+}
+exports.ClusterProtocolError = ClusterProtocolError;
+class ClusterTransportError extends ClusterError {
+}
+exports.ClusterTransportError = ClusterTransportError;
+class ClusterTimeoutError extends ClusterError {
+}
+exports.ClusterTimeoutError = ClusterTimeoutError;
+function requestAbortError(method) {
+    return new DOMException(`${method} aborted locally; the server may still have committed this request`, 'AbortError');
+}
+class ClusterRpcError extends ClusterError {
+    rpcCode;
+    data;
+    constructor(rpcCode, message, data) {
+        super(message, data?.code ?? String(rpcCode));
+        this.rpcCode = rpcCode;
+        this.data = data;
+    }
+}
+exports.ClusterRpcError = ClusterRpcError;

package/lib/cluster/errors.d.ts

@@ -0,0 +1,23 @@
+import type { DomainErrorData } from './generated/protocol.js';
+export declare class ClusterError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+export declare class ClusterConfigError extends ClusterError {
+}
+export declare class ClusterStateError extends ClusterError {
+}
+export declare class ClusterInternalError extends ClusterError {
+}
+export declare class ClusterProtocolError extends ClusterError {
+}
+export declare class ClusterTransportError extends ClusterError {
+}
+export declare class ClusterTimeoutError extends ClusterError {
+}
+export declare function requestAbortError(method: string): DOMException;
+export declare class ClusterRpcError extends ClusterError {
+    readonly rpcCode: number;
+    readonly data?: DomainErrorData | undefined;
+    constructor(rpcCode: number, message: string, data?: DomainErrorData | undefined);
+}

package/lib/cluster/errors.mjs

@@ -0,0 +1,32 @@
+export class ClusterError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = new.target.name;
+    }
+}
+export class ClusterConfigError extends ClusterError {
+}
+export class ClusterStateError extends ClusterError {
+}
+export class ClusterInternalError extends ClusterError {
+}
+export class ClusterProtocolError extends ClusterError {
+}
+export class ClusterTransportError extends ClusterError {
+}
+export class ClusterTimeoutError extends ClusterError {
+}
+export function requestAbortError(method) {
+    return new DOMException(`${method} aborted locally; the server may still have committed this request`, 'AbortError');
+}
+export class ClusterRpcError extends ClusterError {
+    rpcCode;
+    data;
+    constructor(rpcCode, message, data) {
+        super(message, data?.code ?? String(rpcCode));
+        this.rpcCode = rpcCode;
+        this.data = data;
+    }
+}

package/lib/cluster/frames.cjs

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.boundedFrameText = boundedFrameText;
+exports.isRecord = isRecord;
+function boundedUtf8Length(value, maximum) {
+    let bytes = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const codePoint = value.codePointAt(index);
+        if (codePoint === undefined)
+            break;
+        if (codePoint <= 0x7f)
+            bytes += 1;
+        else if (codePoint <= 0x7ff)
+            bytes += 2;
+        else if (codePoint <= 0xffff)
+            bytes += 3;
+        else {
+            bytes += 4;
+            index += 1;
+        }
+        if (bytes > maximum)
+            return undefined;
+    }
+    return bytes;
+}
+function boundedFrameText(event, maximum) {
+    const candidate = event && typeof event === 'object' && 'data' in event
+        ? event.data
+        : event;
+    if (typeof candidate === 'string') {
+        const bytes = boundedUtf8Length(candidate, maximum);
+        return bytes === undefined ? { kind: 'oversized' } : { kind: 'frame', text: candidate, bytes };
+    }
+    if (candidate instanceof ArrayBuffer) {
+        if (candidate.byteLength > maximum)
+            return { kind: 'oversized' };
+        return { kind: 'frame', text: new TextDecoder().decode(candidate), bytes: candidate.byteLength };
+    }
+    if (ArrayBuffer.isView(candidate)) {
+        if (candidate.byteLength > maximum)
+            return { kind: 'oversized' };
+        const view = new Uint8Array(candidate.buffer, candidate.byteOffset, candidate.byteLength);
+        return { kind: 'frame', text: new TextDecoder().decode(view), bytes: candidate.byteLength };
+    }
+    return { kind: 'unsupported' };
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/lib/cluster/frames.d.ts

@@ -0,0 +1,12 @@
+export type FrameRecord = Readonly<Record<string, unknown>>;
+export type BoundedFrameText = {
+    readonly kind: 'frame';
+    readonly text: string;
+    readonly bytes: number;
+} | {
+    readonly kind: 'oversized';
+} | {
+    readonly kind: 'unsupported';
+};
+export declare function boundedFrameText(event: unknown, maximum: number): BoundedFrameText;
+export declare function isRecord(value: unknown): value is FrameRecord;

package/lib/cluster/frames.mjs

@@ -0,0 +1,45 @@
+function boundedUtf8Length(value, maximum) {
+    let bytes = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const codePoint = value.codePointAt(index);
+        if (codePoint === undefined)
+            break;
+        if (codePoint <= 0x7f)
+            bytes += 1;
+        else if (codePoint <= 0x7ff)
+            bytes += 2;
+        else if (codePoint <= 0xffff)
+            bytes += 3;
+        else {
+            bytes += 4;
+            index += 1;
+        }
+        if (bytes > maximum)
+            return undefined;
+    }
+    return bytes;
+}
+export function boundedFrameText(event, maximum) {
+    const candidate = event && typeof event === 'object' && 'data' in event
+        ? event.data
+        : event;
+    if (typeof candidate === 'string') {
+        const bytes = boundedUtf8Length(candidate, maximum);
+        return bytes === undefined ? { kind: 'oversized' } : { kind: 'frame', text: candidate, bytes };
+    }
+    if (candidate instanceof ArrayBuffer) {
+        if (candidate.byteLength > maximum)
+            return { kind: 'oversized' };
+        return { kind: 'frame', text: new TextDecoder().decode(candidate), bytes: candidate.byteLength };
+    }
+    if (ArrayBuffer.isView(candidate)) {
+        if (candidate.byteLength > maximum)
+            return { kind: 'oversized' };
+        const view = new Uint8Array(candidate.buffer, candidate.byteOffset, candidate.byteLength);
+        return { kind: 'frame', text: new TextDecoder().decode(view), bytes: candidate.byteLength };
+    }
+    return { kind: 'unsupported' };
+}
+export function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}