@the-open-engine/zeroshot 6.11.0 → 6.13.0

package/src/cluster/client.ts

@@ -0,0 +1,199 @@
+import { PROTOCOL_VERSION } from './generated/protocol.js';
+import type {
+  AgentAttachParams, AgentAttachResult, ApplyParams, ApplyResult, DeleteParams, DeleteResult,
+  GetParams, GetResult, InitializeParams, InitializeResult, LogsParams, LogsResult,
+  PlanParams, PlanResult, ResubmitParams, ResubmitResult, RetryParams, RetryResult,
+  StopParams, StopResult, UpdateParams, UpdateResult, WatchParams, WatchResult,
+} from './generated/protocol.js';
+import { Connection } from './connection.js';
+import type { CallOptions } from './connection.js';
+import { addSocketListener } from './socket.js';
+import type { WebSocketLike } from './socket.js';
+import { ClusterConfigError, ClusterProtocolError, ClusterTransportError } from './errors.js';
+import {
+  AgentAttachSubscriptionStream,
+  LogsSubscriptionStream,
+  WatchSubscriptionStream,
+} from './subscriptions.js';
+
+export interface ConnectOptions {
+  readonly protocols?: string | readonly string[];
+  readonly webSocketFactory?: (url: string, protocols?: string | readonly string[]) => WebSocketLike | Promise<WebSocketLike>;
+  readonly signal?: AbortSignal;
+  readonly initialize?: InitializeParams;
+}
+export interface WatchSubscription { readonly result: WatchResult; readonly stream: WatchSubscriptionStream; }
+export interface LogsSubscription { readonly result: LogsResult; readonly stream: LogsSubscriptionStream; }
+export interface AgentAttachSubscription { readonly result: AgentAttachResult; readonly stream: AgentAttachSubscriptionStream; }
+export interface CoherentWatchSubscription extends WatchSubscription { readonly snapshot: GetResult; }
+
+export class ClusterClient {
+  constructor(readonly connection: Connection) {}
+  async initialize(
+    params: InitializeParams = { protocolVersion: PROTOCOL_VERSION },
+    options?: CallOptions,
+  ): Promise<InitializeResult> {
+    const result = await this.connection.call('initialize', params, options);
+    if (result.protocolVersion !== params.protocolVersion || result.protocolVersion !== PROTOCOL_VERSION) {
+      throw new ClusterProtocolError(
+        `protocol version mismatch: requested ${params.protocolVersion}, received ${result.protocolVersion}`,
+        'UNSUPPORTED_PROTOCOL_VERSION',
+      );
+    }
+    return result;
+  }
+  plan(params: PlanParams, options?: CallOptions): Promise<PlanResult> {
+    return this.connection.call('plan', params, options);
+  }
+  apply(params: ApplyParams, options?: CallOptions): Promise<ApplyResult> {
+    return this.connection.call('apply', params, options);
+  }
+  update(params: UpdateParams, options?: CallOptions): Promise<UpdateResult> {
+    return this.connection.call('update', params, options);
+  }
+  stop(params: StopParams, options?: CallOptions): Promise<StopResult> {
+    return this.connection.call('stop', params, options);
+  }
+  retry(params: RetryParams, options?: CallOptions): Promise<RetryResult> {
+    return this.connection.call('retry', params, options);
+  }
+  resubmit(params: ResubmitParams, options?: CallOptions): Promise<ResubmitResult> {
+    return this.connection.call('resubmit', params, options);
+  }
+  delete(params: DeleteParams, options?: CallOptions): Promise<DeleteResult> {
+    return this.connection.call('delete', params, options);
+  }
+  get(params: GetParams = {}, options?: CallOptions): Promise<GetResult> {
+    return this.connection.call('get', params, options);
+  }
+  async watch(
+    params: WatchParams = {},
+    options?: CallOptions,
+  ): Promise<WatchSubscription> {
+    const established = await this.connection.openSubscription('watch', params, options);
+    return {
+      result: established.result,
+      stream: new WatchSubscriptionStream({
+        connection: this.connection,
+        registration: established.registration,
+        result: established.result,
+        params,
+      }),
+    };
+  }
+  async watchColdStart(
+    params: Omit<WatchParams, 'fromCursor'> = {},
+    options?: CallOptions,
+  ): Promise<CoherentWatchSubscription> {
+    const snapshot = await this.get({}, options);
+    const watch = await this.watch({
+      ...params,
+      ...(snapshot.atCursor === undefined ? {} : { fromCursor: snapshot.atCursor }),
+    }, options);
+    return { snapshot, ...watch };
+  }
+  async logs(params: LogsParams = {}, options?: CallOptions): Promise<LogsSubscription> {
+    const established = await this.connection.openSubscription('logs', params, options);
+    return {
+      result: established.result,
+      stream: new LogsSubscriptionStream(this.connection, established.registration),
+    };
+  }
+  async agentAttach(
+    params: AgentAttachParams,
+    options?: CallOptions,
+  ): Promise<AgentAttachSubscription> {
+    const established = await this.connection.openSubscription('agent/attach', params, options);
+    return {
+      result: established.result,
+      stream: new AgentAttachSubscriptionStream(this.connection, established.registration),
+    };
+  }
+}
+
+async function defaultWebSocketFactory(
+  url: string,
+  protocols?: string | readonly string[],
+): Promise<WebSocketLike> {
+  const globalWebSocket = (globalThis as {
+    readonly WebSocket?: new (
+      url: string,
+      protocols?: string | readonly string[],
+    ) => WebSocketLike;
+  }).WebSocket;
+  if (globalWebSocket) return new globalWebSocket(url, protocols);
+  try {
+    // Dynamic loading keeps the optional Node runtime off the browser/global-WebSocket path.
+    const imported: unknown = await import('ws');
+    const candidate = imported !== null && typeof imported === 'object' && 'default' in imported
+      ? imported.default
+      : imported;
+    if (typeof candidate !== 'function') {
+      throw new TypeError("The installed 'ws' module does not export a WebSocket constructor");
+    }
+    const Constructor = candidate as new (
+      url: string,
+      protocols?: string | readonly string[],
+    ) => WebSocketLike;
+    return new Constructor(url, protocols);
+  } catch (cause) {
+    throw new ClusterConfigError(
+      "No WebSocket runtime is available; install 'ws' or pass webSocketFactory",
+      'WEBSOCKET_UNAVAILABLE',
+      { cause },
+    );
+  }
+}
+
+async function waitForOpen(socket: WebSocketLike, signal?: AbortSignal): Promise<void> {
+  if (socket.readyState === 1) return;
+  if (socket.readyState !== 0) {
+    throw new ClusterTransportError('WebSocket is already closing or closed', 'OPEN_FAILED');
+  }
+  if (signal?.aborted) throw new DOMException(
+    'connect aborted locally; the server may still have committed this request',
+    'AbortError',
+  );
+  await new Promise<void>((resolve, reject) => {
+    let settled = false;
+    const removers: Array<() => void> = [];
+    const settle = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      for (const remove of removers) remove();
+      signal?.removeEventListener('abort', onAbort);
+      fn();
+    };
+    const onAbort = () => settle(() => reject(new DOMException(
+      'connect aborted locally; the server may still have committed this request',
+      'AbortError',
+    )));
+    removers.push(
+      addSocketListener(socket, 'open', () => settle(resolve)),
+      addSocketListener(socket, 'error', (error) => settle(() => reject(new ClusterTransportError('WebSocket failed to open', 'OPEN_FAILED', { cause: error })))),
+      addSocketListener(socket, 'close', () => settle(() => reject(new ClusterTransportError('WebSocket closed before opening', 'OPEN_FAILED')))),
+    );
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+export async function connect(url: string, options: ConnectOptions = {}): Promise<Connection> {
+  const factory = options.webSocketFactory ?? defaultWebSocketFactory;
+  let socket: WebSocketLike | undefined;
+  try {
+    socket = await factory(url, options.protocols);
+    await waitForOpen(socket, options.signal);
+    const connection = new Connection(socket);
+    await new ClusterClient(connection).initialize(
+      options.initialize,
+      options.signal === undefined ? {} : { signal: options.signal },
+    );
+    return connection;
+  } catch (error) {
+    if (socket) {
+      try { await socket.close(); }
+      catch { /* preserve the construction error */ }
+    }
+    throw error;
+  }
+}

package/src/cluster/connection.ts

@@ -0,0 +1,300 @@
+import { JSON_RPC_VERSION, MAX_FRAME_BYTES, SUBSCRIPTION_METHODS, UNARY_METHODS } from './generated/protocol.js';
+import type {
+  ClusterMethod, ClusterMethodParams, ClusterMethodResults, DomainErrorData,
+  SubscriptionMethod, UnaryClusterMethod,
+} from './generated/protocol.js';
+import {
+  ClusterConfigError, ClusterInternalError, ClusterProtocolError, ClusterRpcError,
+  ClusterStateError, ClusterTimeoutError, ClusterTransportError, requestAbortError,
+} from './errors.js';
+import { boundedFrameText, isRecord } from './frames.js';
+import type { FrameRecord } from './frames.js';
+import { BoundedQueue } from './queue.js';
+import { addSocketListener } from './socket.js';
+import type { WebSocketLike } from './socket.js';
+import { assertDefinition, assertMethodResult } from './validators.js';
+if (!Object.prototype.hasOwnProperty.call(Symbol, 'asyncDispose')) {
+  Object.defineProperty(Symbol, 'asyncDispose', {
+    configurable: false, enumerable: false,
+    value: Symbol.for('Symbol.asyncDispose'), writable: false,
+  });
+}
+
+export type ConnectionState = 'OPEN' | 'CLOSING' | 'CLOSED';
+export const CONNECTION_TRANSITIONS: Readonly<Record<ConnectionState, readonly ConnectionState[]>> = Object.freeze({
+  OPEN: Object.freeze(['CLOSING'] as const),
+  CLOSING: Object.freeze(['CLOSED'] as const),
+  CLOSED: Object.freeze([] as const),
+});
+export const PROTOCOL_DIAGNOSTIC_CAPACITY = 128;
+export interface CallOptions { readonly signal?: AbortSignal; readonly requestTimeoutMs?: number; }
+
+type Deferred<T> = {
+  readonly promise: Promise<T>;
+  readonly resolve: (value: T) => void;
+  readonly reject: (reason: unknown) => void;
+};
+function deferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void; let reject!: (reason: unknown) => void;
+  const promise = new Promise<T>((onResolve, onReject) => {
+    resolve = onResolve; reject = onReject;
+  });
+  return { promise, resolve, reject };
+}
+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;
+};
+type PendingEntry = {
+  readonly id: string; readonly method: ClusterMethod; readonly expectedId: string;
+  readonly resolve: (value: unknown) => void; readonly reject: (reason: unknown) => void;
+  readonly subscriptionKind?: SubscriptionKind; settled: boolean;
+  abortHandler?: () => void; signal?: AbortSignal; timeout?: ReturnType<typeof setTimeout>;
+};
+
+export class Connection {
+  #state: ConnectionState = 'OPEN'; #sequence = 1;
+  readonly #pending = new Map<string, PendingEntry>();
+  readonly #subscriptions = new Map<string, SubscriptionRegistration>();
+  readonly #lateSubscriptionReapers = new Set<string>();
+  readonly #removeSocketListeners: Array<() => void> = [];
+  readonly #ownedSubscriptions = new WeakSet<SubscriptionRegistration>();
+  #closePromise?: Promise<void>;
+  readonly closeDiagnostics: unknown[] = [];
+  readonly protocolDiagnostics: ClusterProtocolError[] = [];
+
+  readonly #socket: WebSocketLike;
+  constructor(socket: WebSocketLike) {
+    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(): ConnectionState { return this.#state; }
+  get pendingSize(): number { return this.#pending.size; }
+  get subscriptionCount(): number { return this.#subscriptions.size; }
+  call<M extends UnaryClusterMethod>(method: M, params: ClusterMethodParams[M], options: CallOptions = {}): Promise<ClusterMethodResults[M]> {
+    if (!(UNARY_METHODS as readonly string[]).includes(method)) {
+      throw new ClusterConfigError(`${method} is a subscription method`, 'INVALID_METHOD');
+    }
+    return this.#dispatch(method, params, options) as Promise<ClusterMethodResults[M]>;
+  }
+  cancelSubscription(registration: SubscriptionRegistration): Promise<void> {
+    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<M extends SubscriptionMethod>(method: M, params: ClusterMethodParams[M], options: CallOptions = {}): Promise<EstablishedSubscription<ClusterMethodResults[M]>> {
+    if (!(SUBSCRIPTION_METHODS as readonly string[]).includes(method)) {
+      throw new ClusterConfigError(`${method} is not a subscription method`, 'INVALID_METHOD');
+    }
+    return this.#dispatch(method, params, options, method) as Promise<EstablishedSubscription<ClusterMethodResults[M]>>;
+  }
+  unregisterSubscription(id: string, registration: SubscriptionRegistration): void {
+    if (this.#subscriptions.get(id) !== registration) return;
+    this.#subscriptions.delete(id);
+    this.#disarmSubscriptionAbort(registration);
+  }
+  recordDiagnostic(error: unknown): void { this.closeDiagnostics.push(error); }
+  close(): Promise<void> { return this.#startClose(true); }
+
+  #dispatch(method: ClusterMethod, params: unknown, options: CallOptions, subscriptionKind?: SubscriptionKind): Promise<unknown> {
+    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<unknown>();
+    const entry: PendingEntry = { 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: unknown) => 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: unknown) => this.recordDiagnostic(error));
+      }, options.requestTimeoutMs);
+    }
+    const request = { jsonrpc: JSON_RPC_VERSION, id, method, params };
+    void this.#sendFrame(request).catch((cause: unknown) => {
+      if (!this.#removeExact(id, entry)) return; this.#settleEntry(entry);
+      entry.reject(new ClusterTransportError(`failed to send ${method}`, 'SEND_FAILED', { cause }));
+    });
+    return result.promise;
+  }
+  #allocateId(): string { return `z${this.#sequence++}`; }
+  #removeExact(id: string, entry: PendingEntry): boolean { if (this.#pending.get(id) !== entry) return false; this.#pending.delete(id); return true; }
+  #settleEntry(entry: PendingEntry): void {
+    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(): void { if (this.#state !== 'OPEN') throw new ClusterStateError(`connection is ${this.#state.toLowerCase()}`, `CONNECTION_${this.#state}`); }
+  async #sendFrame(value: unknown, allowClosing = false): Promise<void> {
+    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<void>((resolve, reject) => { try { this.#socket.send(payload, (error?: Error) => error ? reject(error) : resolve()); } catch (error) { reject(error); } });
+      return;
+    }
+    const sent = this.#socket.send(payload); if (sent && typeof (sent as Promise<void>).then === 'function') await sent;
+  }
+  #sendNotification(method: '$/cancelRequest' | 'subscription/cancel', params: FrameRecord): Promise<void> {
+    return this.#sendFrame({ jsonrpc: JSON_RPC_VERSION, method, params }, true);
+  }
+  #onMessage(event: unknown): void {
+    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: unknown; 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: FrameRecord): void {
+    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: string, result: unknown): void {
+    if (!this.#lateSubscriptionReapers.delete(id) || !isRecord(result)) return;
+    if (typeof result.subscriptionId !== 'string') return;
+    void this.#sendNotification('subscription/cancel', { subscriptionId: result.subscriptionId })
+      .catch((error: unknown) => this.recordDiagnostic(error));
+  }
+  #routeRpcError(entry: PendingEntry, error: FrameRecord): void {
+    try { assertDefinition('JsonRpcError', error); }
+    catch (cause) { entry.reject(cause); return; }
+    const data = isRecord(error.data) ? error.data as DomainErrorData : undefined;
+    entry.reject(new ClusterRpcError(error.code as number, error.message as string, data));
+  }
+  #routeSuccess(entry: PendingEntry, frame: FrameRecord): void {
+    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: unknown) => this.recordDiagnostic(cause));
+      }
+      entry.reject(error); return;
+    }
+    if (!entry.subscriptionKind) { entry.resolve(frame.result); return; }
+    const result = frame.result as ClusterMethodResults[SubscriptionMethod];
+    const registration: SubscriptionRegistration = {
+      id: result.subscriptionId, kind: entry.subscriptionKind,
+      queue: new BoundedQueue<FrameRecord>(), 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: SubscriptionRegistration, signal: AbortSignal | undefined): void {
+    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: unknown) => this.recordDiagnostic(error));
+    };
+    registration.abortSignal = signal;
+    registration.abortHandler = onAbort;
+    signal.addEventListener('abort', onAbort, { once: true });
+    if (signal.aborted) onAbort();
+  }
+  #disarmSubscriptionAbort(registration: SubscriptionRegistration): void {
+    if (registration.abortSignal && registration.abortHandler) {
+      registration.abortSignal.removeEventListener('abort', registration.abortHandler);
+    }
+    delete registration.abortSignal;
+    delete registration.abortHandler;
+  }
+  #routeNotification(method: string, params: FrameRecord, frame: FrameRecord, bytes: number): void {
+    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: unknown) => this.recordDiagnostic(error));
+      return;
+    }
+    if (terminal) { this.unregisterSubscription(subscriptionId, registration); registration.queue.endRetainingBuffer(); }
+  }
+  #recordProtocolError(message: string, cause?: unknown): void {
+    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: boolean): Promise<void> {
+    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: boolean): Promise<void> {
+    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: ConnectionState): void {
+    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/src/cluster/errors.ts

@@ -0,0 +1,32 @@
+import type { DomainErrorData } from './generated/protocol.js';
+
+export class ClusterError extends Error {
+  constructor(message: string, readonly code: string, options?: ErrorOptions) {
+    super(message, options);
+    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: string): DOMException {
+  return new DOMException(
+    `${method} aborted locally; the server may still have committed this request`,
+    'AbortError',
+  );
+}
+
+export class ClusterRpcError extends ClusterError {
+  constructor(
+    readonly rpcCode: number,
+    message: string,
+    readonly data?: DomainErrorData,
+  ) {
+    super(message, data?.code ?? String(rpcCode));
+  }
+}

package/src/cluster/frames.ts

@@ -0,0 +1,44 @@
+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' };
+
+function boundedUtf8Length(value: string, maximum: number): number | undefined {
+  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: unknown, maximum: number): BoundedFrameText {
+  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: unknown): value is FrameRecord {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}