Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

11.6 KB
Raw Blame
/**
 * RpcClient — NDJSON RPC over any Duplex stream (unix socket / TCP / SSH exec).
 *
 * Lifecycle:
 *   const client = new RpcClient(stream, { onNotification, onClose, onError });
 *   await client.hello();                        // protocol handshake
 *   const result = await client.request(method, params);
 *   client.dispose();                            // tear down (does NOT close stream)
 *
 * Stream ownership: caller owns the underlying stream (creates + destroys).
 * RpcClient only attaches listeners — dispose() detaches them.
 *
 * Timeouts: per-request opt-in via opts.timeoutMs. Default = no timeout.
 * On timeout the pending promise rejects but the underlying request id is
 * marked as orphaned — if the response arrives later it's silently dropped.
 */

import type { Duplex } from 'node:stream';

import { NDJSONDecoder, encodeMessage } from './codec.js';
import {
  METHODS,
  PROTOCOL_VERSION,
  isRpcNotification,
  isRpcRequest,
  isRpcResponse,
  type HelloParams,
  type HelloResult,
  type NotificationName,
  type RpcError,
  type RpcId,
  type RpcMessage,
  type RpcNotification,
  type RpcRequest,
  type RpcResponse,
} from './protocol.js';

export interface RpcClientOptions {
  /** Called for any incoming notification (no id). */
  onNotification?: (n: RpcNotification) => void;
  /** Called when the underlying stream ends (peer closed or local dispose). */
  onClose?: () => void;
  /** Called when the underlying stream errors. */
  onError?: (err: Error) => void;
  /** Optional client identifier, sent on hello() for log correlation. */
  clientId?: string;
  /** Called when a corrupt NDJSON line is encountered (for diagnostics). */
  onCorruptLine?: (line: string, err: Error) => void;
}

export interface RpcRequestOptions {
  /** Reject the promise after this many ms. Default: no timeout. */
  timeoutMs?: number;
}

export class RpcClientError extends Error {
  constructor(public readonly rpcError: RpcError) {
    super(`[${rpcError.code}] ${rpcError.message}`);
    this.name = 'RpcClientError';
  }
}

interface PendingEntry {
  resolve: (result: unknown) => void;
  reject: (err: Error) => void;
  timer?: NodeJS.Timeout;
}

export type NotificationSubscriber = (n: RpcNotification) => void;
export type CloseSubscriber = () => void;
/**
 * Handler for server→client requests (reverse-request pattern).
 * Must return a result value (JSON-serializable) or throw to signal error.
 */
export type ServerRequestHandler = (params: unknown) => Promise<unknown> | unknown;

export class RpcClient {
  private nextId: RpcId = 1;
  private readonly pending = new Map<RpcId, PendingEntry>();
  private readonly decoder: NDJSONDecoder;
  private readonly onNotificationCtor?: (n: RpcNotification) => void;
  private readonly onClose?: () => void;
  private readonly onError?: (err: Error) => void;
  private readonly clientId?: string;
  private readonly listeners: Array<{ event: string; fn: (...args: unknown[]) => void }> = [];
  /** Additional subscribers added after construction via subscribe(). */
  private readonly subscribers = new Set<NotificationSubscriber>();
  /** Lifecycle subscribers — fire once when the underlying stream closes. */
  private readonly closeSubscribers = new Set<CloseSubscriber>();
  /** Handlers for server→client requests (reverse-request). */
  private readonly requestHandlers = new Map<string, ServerRequestHandler>();
  /** True once the underlying stream emitted 'close' (or dispose() ran). */
  private closedFired = false;
  private disposed = false;

  constructor(
    private readonly stream: Duplex,
    opts: RpcClientOptions = {},
  ) {
    this.onNotificationCtor = opts.onNotification;
    this.onClose = opts.onClose;
    this.onError = opts.onError;
    this.clientId = opts.clientId;
    this.decoder = new NDJSONDecoder({ onCorruptLine: opts.onCorruptLine });
    this.attach();
  }

  /**
   * Send protocol/hello and validate version match. Should be called once
   * immediately after construction, before any other request.
   *
   * `opts.timeoutMs` 强烈建议传 — daemon 活着但 unresponsive (被 uncaughtException
   * guard 救活但 hang 在 handler) 时 hello 永远不返回, 不传 timeout client 卡死。
   */
  async hello(opts: RpcRequestOptions = {}): Promise<HelloResult> {
    const params: HelloParams = {
      protocolVersion: PROTOCOL_VERSION,
      ...(this.clientId ? { clientId: this.clientId } : {}),
    };
    return await this.request<HelloResult>(METHODS.PROTOCOL_HELLO, params, opts);
  }

  /**
   * Send a request and wait for the matching response. Resolves with `result`,
   * rejects with `RpcClientError` if the server returned an `error` field, or
   * with a plain `Error` on timeout / stream close.
   */
  async request<R = unknown>(
    method: string,
    params: unknown,
    opts: RpcRequestOptions = {},
  ): Promise<R> {
    if (this.disposed || this.closedFired || this.stream.destroyed) {
      throw new Error('RpcClient is disposed or stream closed');
    }
    const id = this.nextId++;
    return await new Promise<R>((resolve, reject) => {
      const entry: PendingEntry = {
        resolve: resolve as (v: unknown) => void,
        reject,
      };
      if (opts.timeoutMs && opts.timeoutMs > 0) {
        entry.timer = setTimeout(() => {
          if (this.pending.delete(id)) {
            reject(new Error(`RPC ${method} timed out after ${opts.timeoutMs}ms`));
          }
        }, opts.timeoutMs);
      }
      this.pending.set(id, entry);
      try {
        this.stream.write(encodeMessage({ type: 'request', id, method, params }));
      } catch (err) {
        if (this.pending.delete(id)) {
          if (entry.timer) clearTimeout(entry.timer);
          reject(err as Error);
        }
      }
    });
  }

  /**
   * Subscribe to incoming notifications. Multiple subscribers are supported
   * (the constructor-level `onNotification` callback is invoked first, then
   * all subscribers). Returns an unsubscribe function.
   */
  subscribe(handler: NotificationSubscriber): () => void {
    this.subscribers.add(handler);
    return () => {
      this.subscribers.delete(handler);
    };
  }

  /**
   * Subscribe to stream-close lifecycle. Fires exactly once when the underlying
   * Duplex emits 'close' (peer hung up / local dispose). Subscribers added
   * **after** the close already fired are invoked synchronously here, so a
   * late RemoteQuery still learns about a dead daemon without polling.
   *
   * Why this matters: RemoteQuery only watches NOTIFICATIONS.SESSION_CLOSED
   * for end-of-stream. When the daemon is killed abruptly (force-upgrade,
   * SIGKILL, network blip), SESSION_CLOSED may not flush in time, leaving
   * the async iterator wedged on an empty queue. close subscription lets
   * RemoteQuery treat stream close as an implicit session-closed signal.
   */
  subscribeClose(handler: CloseSubscriber): () => void {
    if (this.closedFired) {
      try {
        handler();
      } catch {
        /* */
      }
      return () => undefined;
    }
    this.closeSubscribers.add(handler);
    return () => {
      this.closeSubscribers.delete(handler);
    };
  }

  /** True once the underlying stream closed (or dispose() ran). */
  isClosed(): boolean {
    return this.closedFired;
  }

  /** Send a notification (fire-and-forget, no response). */
  notify(method: NotificationName | string, params: unknown): void {
    if (this.disposed || this.closedFired || this.stream.destroyed) {
      throw new Error('RpcClient is disposed or stream closed');
    }
    this.stream.write(encodeMessage({ type: 'notification', method, params }));
  }

  /**
   * Register a handler for server→client requests (reverse-request pattern).
   * When the server sends a request with this method, the handler is called
   * and its return value (or thrown error) is sent back as the response.
   */
  setRequestHandler(method: string, handler: ServerRequestHandler): void {
    this.requestHandlers.set(method, handler);
  }

  /**
   * Detach listeners and reject any pending requests. Does NOT close the
   * underlying stream — caller owns it.
   *
   * Also fires close subscribers (idempotent — `closedFired` guards), so
   * RemoteQuery instances created against this client get their messageQueue
   * ended even when teardown comes from our side rather than peer EOF.
   */
  dispose(): void {
    if (this.disposed) return;
    this.disposed = true;
    for (const { event, fn } of this.listeners) {
      this.stream.off(event, fn);
    }
    this.listeners.length = 0;
    for (const [, entry] of this.pending) {
      if (entry.timer) clearTimeout(entry.timer);
      entry.reject(new Error('RpcClient disposed'));
    }
    this.pending.clear();
    this.fireClose();
  }

  private attach(): void {
    const onData = (chunk: Buffer | string): void => {
      for (const msg of this.decoder.push(chunk)) {
        this.handleIncoming(msg);
      }
    };
    const onClose = (): void => {
      // Reject pending — but keep dispose flag so request() refuses new sends.
      for (const [, entry] of this.pending) {
        if (entry.timer) clearTimeout(entry.timer);
        entry.reject(new Error('RPC stream closed'));
      }
      this.pending.clear();
      this.onClose?.();
      this.fireClose();
    };
    const onError = (err: Error): void => {
      this.onError?.(err);
    };
    this.stream.on('data', onData);
    this.stream.on('close', onClose);
    this.stream.on('error', onError);
    this.listeners.push({ event: 'data', fn: onData as (...args: unknown[]) => void });
    this.listeners.push({ event: 'close', fn: onClose as (...args: unknown[]) => void });
    this.listeners.push({ event: 'error', fn: onError as (...args: unknown[]) => void });
  }

  private handleIncoming(msg: RpcMessage): void {
    if (isRpcResponse(msg)) {
      this.handleResponse(msg);
      return;
    }
    if (isRpcNotification(msg)) {
      this.onNotificationCtor?.(msg);
      for (const sub of this.subscribers) {
        try {
          sub(msg);
        } catch {
          /* ignore subscriber errors */
        }
      }
      return;
    }
    if (isRpcRequest(msg)) {
      void this.handleServerRequest(msg);
      return;
    }
  }

  private async handleServerRequest(req: RpcRequest): Promise<void> {
    const handler = this.requestHandlers.get(req.method);
    if (!handler) {
      const response: RpcResponse = {
        type: 'response',
        id: req.id,
        error: { code: 'UNKNOWN_METHOD', message: `no client handler for ${req.method}` },
      };
      if (!this.disposed) this.stream.write(encodeMessage(response));
      return;
    }
    try {
      const result = await handler(req.params);
      const response: RpcResponse = { type: 'response', id: req.id, result };
      if (!this.disposed) this.stream.write(encodeMessage(response));
    } catch (err) {
      const response: RpcResponse = {
        type: 'response',
        id: req.id,
        error: { code: 'INTERNAL', message: (err as Error)?.message ?? 'handler error' },
      };
      if (!this.disposed) this.stream.write(encodeMessage(response));
    }
  }

  private fireClose(): void {
    if (this.closedFired) return;
    this.closedFired = true;
    for (const sub of this.closeSubscribers) {
      try {
        sub();
      } catch {
        /* */
      }
    }
    this.closeSubscribers.clear();
  }

  private handleResponse(msg: RpcResponse): void {
    const entry = this.pending.get(msg.id);
    if (!entry) {
      // Likely a late response after timeout — drop silently.
      return;
    }
    this.pending.delete(msg.id);
    if (entry.timer) clearTimeout(entry.timer);
    if (msg.error) {
      entry.reject(new RpcClientError(msg.error));
    } else {
      entry.resolve(msg.result);
    }
  }
}