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。

43.7 KB
Raw Blame
/**
 * ManagerServer test suite — covers hello, guards, error mapping, notifyAll,
 * sendRequest (server→client), and disconnect cleanup.
 *
 * Uses real IPC (unix socket / Windows named pipe) via net.connect.
 * Cross-platform — named pipe on Windows, unix socket elsewhere.
 */

import * as net from 'node:net';
import * as path from 'node:path';
import * as os from 'node:os';
import { afterEach, beforeEach, describe, expect, it } from 'vitest';

import { ManagerServer, makeServerError } from '../server.js';
import { PROTOCOL_VERSION } from '../protocol.js';
import { encodeMessage } from '../codec.js';

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

function makeIpcPath(): string {
  const uniq = `pi-mgr-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
  if (process.platform === 'win32') {
    return `\\\\.\\pipe\\${uniq}`;
  }
  return path.join(os.tmpdir(), `${uniq}.sock`);
}

function silentLogger() {
  return {
    debug: () => undefined,
    info: () => undefined,
    warn: () => undefined,
    error: () => undefined,
  };
}

/**
 * Read the next complete NDJSON frame from a socket.
 * Rejects on timeout, socket close, or socket error.
 */
// 模块级 per-socket 帧缓冲:一个 chunk 可能含多帧(CI 慢时帧合并), readNextFrame
// resolve 后若丢弃 buf 剩余帧, 下一次调用永远读不到它们(轮 40-w4 SERVER_BUSY
// 测试踩过的坑, makeFrameReader 注释)。跨调用保留剩余帧, 保持 readNextFrame
// 的一次取一帧形态。
const socketFrameBuffers = new Map<net.Socket, string>();

function readNextFrame(socket: net.Socket, timeoutMs = 15000, skipId?: number): Promise<any> {
  return new Promise((resolve, reject) => {
    // 先消费上次调用残留的帧(若有)。
    let buf = socketFrameBuffers.get(socket) ?? '';
    socketFrameBuffers.delete(socket);

    const timer = setTimeout(() => {
      cleanup();
      reject(new Error(`readNextFrame timeout after ${timeoutMs}ms`));
    }, timeoutMs);

    function onData(chunk: Buffer) {
      buf += chunk.toString('utf8');
      drain();
    }

    /** 从 buf 取一帧;取完但 buf 仍有剩余帧 → 存回共享缓冲(不丢)。 */
    function drain(): void {
      const nl = buf.indexOf('\n');
      if (nl < 0) return;
      const line = buf.slice(0, nl).replace(/\r$/, '');
      buf = buf.slice(nl + 1);
      let frame: any;
      try {
        frame = JSON.parse(line);
      } catch (err) {
        cleanup();
        reject(err);
        return;
      }
      // skipId 指定时跳过该 id 的 response 帧 —— reverse-request 测试里
      // id=2 的请求响应可能抢在 server→client 的 reverse request 前到达
      // (真 socket 时序, Linux 慢 runner 尤甚)。只读下一帧。
      if (skipId !== undefined && frame.type === 'response' && frame.id === skipId) {
        drain();
        return;
      }
      if (buf.trim().length > 0) socketFrameBuffers.set(socket, buf);
      cleanup();
      resolve(frame);
    }

    function onClose() {
      cleanup();
      reject(new Error('socket closed before frame received'));
    }

    function onError(err: Error) {
      cleanup();
      reject(err);
    }

    function cleanup() {
      clearTimeout(timer);
      socket.removeListener('data', onData);
      socket.removeListener('close', onClose);
      socket.removeListener('error', onError);
    }

    socket.on('data', onData);
    socket.once('close', onClose);
    socket.once('error', onError);
    // 上次残留帧直接消费(无需等新 data)。
    drain();
  });
}

/** Write an RPC request frame (NDJSON line). */
function writeRequest(socket: net.Socket, id: number, method: string, params: unknown = {}): void {
  socket.write(encodeMessage({ type: 'request', id, method, params }));
}

/** Connect a raw socket and wait for the connection to be established. */
async function connectRaw(socketPath: string): Promise<net.Socket> {
  const socket = net.connect(socketPath);
  await new Promise<void>((resolve, reject) => {
    socket.once('connect', () => resolve());
    socket.once('error', reject);
  });
  return socket;
}

/** Perform hello handshake on a raw socket. Returns the hello result payload. */
async function doHello(socket: net.Socket, clientId?: string): Promise<any> {
  const params: any = { protocolVersion: PROTOCOL_VERSION };
  if (clientId) params.clientId = clientId;
  writeRequest(socket, 1, 'protocol/hello', params);
  const resp = await readNextFrame(socket);
  if (resp.error) throw new Error(`hello failed: ${resp.error.code}: ${resp.error.message}`);
  return resp.result;
}

/**
 * 常驻帧队列读取器:持续累积 data, 按 \n 切帧。与 readNextFrame 的区别是
 * 不丢合并帧 —— readNextFrame 每次临时注册 onData, 若一个 chunk 含多帧只取
 * 第一帧、其余静默丢弃(轮 40-w4 SERVER_BUSY 测试踩坑:release 后 32 帧合并
 * 进同一 chunk, 循环 readNextFrame 只收到第一帧, 其余帧永不触发 data 事件)。
 * 返回按序取帧的 async 函数。
 */
function makeFrameReader(socket: net.Socket): () => Promise<any> {
  let buf = '';
  // 已解析待消费的帧(一个 chunk 可含多帧, 消费方逐个取)。
  const frames: unknown[] = [];
  const waiters: Array<{
    resolve: (frame: any) => void;
    reject: (err: Error) => void;
    timer: NodeJS.Timeout;
  }> = [];
  socket.on('data', (chunk: Buffer) => {
    buf += chunk.toString('utf8');
    while (true) {
      const nl = buf.indexOf('\n');
      if (nl < 0) break;
      const line = buf.slice(0, nl).replace(/\r$/, '');
      buf = buf.slice(nl + 1);
      const w = waiters.shift();
      if (w) {
        clearTimeout(w.timer);
        w.resolve(JSON.parse(line));
      } else {
        // 帧多于消费方:缓存, 等下一个 nextFrame() 直接取(不丢帧)。
        frames.push(JSON.parse(line));
      }
    }
  });
  return () => {
    const queued = frames.shift();
    if (queued !== undefined) return Promise.resolve(queued);
    return new Promise((resolve, reject) => {
      const timer = setTimeout(() => reject(new Error('frame timeout')), 5000);
      waiters.push({ resolve, reject, timer });
    });
  };
}

// ---------------------------------------------------------------------------
// Test suite
// ---------------------------------------------------------------------------

describe('ManagerServer', () => {
  let server: ManagerServer;
  let socketPath: string;

  beforeEach(async () => {
    socketPath = makeIpcPath();
    server = new ManagerServer({
      socketPath,
      managerVersion: 'test-0.0.0',
      logger: silentLogger(),
    });
    await server.start();
  });

  afterEach(async () => {
    await server.stop();
  });

  /** One isolated client per validation case; cleanup also covers failed handshakes. */
  async function requestFromClient(
    method: string,
    params: unknown = {},
    { id = 2, hello = true }: { id?: number; hello?: boolean } = {},
  ): Promise<any> {
    const socket = await connectRaw(socketPath);
    try {
      if (hello) await doHello(socket);
      const response = readNextFrame(socket);
      writeRequest(socket, id, method, params);
      return await response;
    } finally {
      socket.destroy();
      socketFrameBuffers.delete(socket);
    }
  }

  // -----------------------------------------------------------------------
  // 1. hello handshake
  // -----------------------------------------------------------------------
  describe('hello handshake', () => {
    it('accepts correct protocolVersion and returns server info', async () => {
      const socket = await connectRaw(socketPath);
      const result = await doHello(socket, 'test-client-1');
      expect(result.protocolVersion).toBe(PROTOCOL_VERSION);
      expect(result.managerVersion).toBe('test-0.0.0');
      socket.destroy();
    });

    it('accepts hello without clientId', async () => {
      const socket = await connectRaw(socketPath);
      const result = await doHello(socket);
      expect(result.protocolVersion).toBe(PROTOCOL_VERSION);
      socket.destroy();
    });

    it.each([
      {
        name: 'rejects mismatched protocolVersion with INVALID_PROTOCOL_VERSION',
        id: 1,
        params: { protocolVersion: 999 },
        error: { code: 'INVALID_PROTOCOL_VERSION', message: expect.stringContaining('999') },
      },
      {
        name: 'rejects missing protocolVersion with INVALID_PARAMS',
        id: 2,
        params: {},
        error: { code: 'INVALID_PARAMS', message: expect.stringContaining('protocolVersion') },
      },
      {
        name: 'rejects non-number protocolVersion with INVALID_PARAMS',
        id: 3,
        params: { protocolVersion: 'v1' },
        error: { code: 'INVALID_PARAMS' },
      },
    ].map(({ name, ...input }) => [name, input] as const))('%s', async (_name, { id, params, error }) => {
      const resp = await requestFromClient('protocol/hello', params, { id, hello: false });
      expect(resp.type).toBe('response');
      expect(resp.id).toBe(id);
      expect(resp.error).toBeDefined();
      expect(resp.error).toMatchObject(error);
    });

    it('allows client to proceed with requests after successful hello', async () => {
      server.setHandler('test/ping', async () => 'pong');
      const socket = await connectRaw(socketPath);
      await doHello(socket);
      writeRequest(socket, 2, 'test/ping', {});
      const resp = await readNextFrame(socket);
      expect(resp.result).toBe('pong');
      socket.destroy();
    });

    it('records clientId from hello params (verified by log independence)', async () => {
      server.setHandler('test/who', async (_params, ctx) => `You are ${ctx.clientId ?? 'unknown'}`);
      const socketA = await connectRaw(socketPath);
      const socketB = await connectRaw(socketPath);
      await doHello(socketA, 'client-A');
      await doHello(socketB, 'client-B');

      writeRequest(socketA, 2, 'test/who', {});
      writeRequest(socketB, 2, 'test/who', {});
      const [respA, respB] = await Promise.all([readNextFrame(socketA), readNextFrame(socketB)]);
      expect(respA.result).toBe('You are client-A');
      expect(respB.result).toBe('You are client-B');

      socketA.destroy();
      socketB.destroy();
    });

    it('rejects duplicate hello with INVALID_PARAMS (round 2 M-1)', async () => {
      const socket = await connectRaw(socketPath);
      await doHello(socket, 'first');
      writeRequest(socket, 5, 'protocol/hello', { protocolVersion: PROTOCOL_VERSION, clientId: 'second' });
      const resp = await readNextFrame(socket);
      expect(resp.error).toBeDefined();
      expect(resp.error.code).toBe('INVALID_PARAMS');
      expect(resp.error.message).toContain('already completed');
      // 后续请求仍可用, clientId 未被覆盖(协议其余部分不受影响)。
      server.setHandler('test/who2', async (_params, ctx) => `You are ${ctx.clientId ?? 'unknown'}`);
      writeRequest(socket, 6, 'test/who2', {});
      const resp2 = await readNextFrame(socket);
      expect(resp2.result).toBe('You are first');
      socket.destroy();
    });
  });

  // -----------------------------------------------------------------------
  // 2. NOT_INITIALIZED guard
  // -----------------------------------------------------------------------
  describe('NOT_INITIALIZED guard', () => {
    it.each([
      {
        name: 'rejects pi/list before hello with NOT_INITIALIZED',
        method: 'pi/list',
        params: {},
      },
      {
        name: 'rejects any non-hello method before initialization',
        method: 'pi/ensure',
        params: { sessionId: 'x' },
      },
    ].map(({ name, ...input }) => [name, input] as const))('%s', async (_name, { method, params }) => {
      const resp = await requestFromClient(method, params, { id: 1, hello: false });
      expect(resp.error).toBeDefined();
      expect(resp.error.code).toBe('NOT_INITIALIZED');
      expect(resp.error.message).toContain('protocol/hello');
    });

    it('allows hello before initialization (no NOT_INITIALIZED for hello itself)', async () => {
      const socket = await connectRaw(socketPath);
      const result = await doHello(socket);
      expect(result.protocolVersion).toBe(PROTOCOL_VERSION);
      socket.destroy();
    });
  });

  // -----------------------------------------------------------------------
  // 3. UNKNOWN_METHOD
  // -----------------------------------------------------------------------
  describe('UNKNOWN_METHOD', () => {
    it.each([
      {
        name: 'returns UNKNOWN_METHOD for unregistered method after hello',
        id: 2,
        method: 'totally/made-up',
      },
      {
        name: 'returns UNKNOWN_METHOD even for plausible-but-unregistered methods',
        id: 3,
        method: 'protocol/version',
      },
    ].map(({ name, ...input }) => [name, input] as const))('%s', async (_name, { id, method }) => {
      const resp = await requestFromClient(method, {}, { id });
      expect(resp.error).toBeDefined();
      expect(resp.error.code).toBe('UNKNOWN_METHOD');
      expect(resp.error.message).toContain(method);
    });
  });

  // -----------------------------------------------------------------------
  // 4. negative id rejection
  // -----------------------------------------------------------------------
  describe('negative id rejection', () => {
    it('rejects requests with negative id (after hello) with INVALID_PARAMS', async () => {
      const socket = await connectRaw(socketPath);
      await doHello(socket);
      // Send a negative-ID request after initialization
      writeRequest(socket, -1, 'pi/list', {});
      const resp = await readNextFrame(socket);
      expect(resp.error).toBeDefined();
      expect(resp.error.code).toBe('INVALID_PARAMS');
      expect(resp.error.message).toContain('non-negative');
      socket.destroy();
    });

    it('rejects negative-ID hello before NOT_INITIALIZED or hello handler',
      async () => {
        // Even protocol/hello with negative ID should be rejected for the
        // negative ID — NOT processed by the hello handler or NOT_INITIALIZED.
        const socket = await connectRaw(socketPath);
        writeRequest(socket, -2, 'protocol/hello', {
          protocolVersion: PROTOCOL_VERSION,
        });
        const resp = await readNextFrame(socket);
        expect(resp.error.code).toBe('INVALID_PARAMS');
        expect(resp.error.message).toContain('non-negative');
        socket.destroy();
      });

    it('negative id check fires before NOT_INITIALIZED for non-hello methods',
      async () => {
        // A non-hello method with negative ID must get INVALID_PARAMS,
        // not NOT_INITIALIZED.
        const socket = await connectRaw(socketPath);
        writeRequest(socket, -3, 'pi/list', {});
        const resp = await readNextFrame(socket);
        expect(resp.error.code).toBe('INVALID_PARAMS');
        expect(resp.error.message).toContain('non-negative');
        socket.destroy();
      });

    it('accepts id=0 as valid (non-negative)', async () => {
      const socket = await connectRaw(socketPath);
      await doHello(socket);
      server.setHandler('test/echo', async (params) => params);
      writeRequest(socket, 0, 'test/echo', { ok: true });
      const resp = await readNextFrame(socket);
      expect(resp.type).toBe('response');
      expect(resp.id).toBe(0);
      expect(resp.result).toEqual({ ok: true });
      socket.destroy();
    });
  });

  // -----------------------------------------------------------------------
  // 5. error code mapping
  // -----------------------------------------------------------------------
  describe('error code mapping', () => {
    it.each([
      {
        name: 'passes through known error codes from handler throws',
        method: 'test/known-error',
        createError: () => makeServerError('INVALID_PARAMS', 'bad params', { field: 'x' }),
        expectedError: { code: 'INVALID_PARAMS', message: 'bad params', data: { field: 'x' } },
      },
      {
        name: 'maps unknown error codes to INTERNAL',
        method: 'test/unknown-code',
        createError: () => Object.assign(new Error('something went wrong'), { code: 'WEIRD_CUSTOM_CODE' }),
        expectedError: { code: 'INTERNAL', message: 'something went wrong' },
      },
      {
        name: 'maps throws without code property to INTERNAL',
        method: 'test/no-code',
        createError: () => new Error('plain error'),
        expectedError: { code: 'INTERNAL', message: 'plain error' },
      },
      {
        name: 'maps non-Error throws to INTERNAL with fallback message',
        method: 'test/throw-string',
        createError: () => 'just a string',
        expectedError: { code: 'INTERNAL', message: 'internal error' },
      },
      {
        name: 'maps null-throws to INTERNAL with fallback message',
        method: 'test/throw-null',
        createError: () => null,
        expectedError: { code: 'INTERNAL', message: 'internal error' },
      },
      {
        name: 'maps SESSION_NOT_FOUND from handler',
        method: 'test/session-not-found',
        createError: () => makeServerError('SESSION_NOT_FOUND', 'no such session', { sessionId: 'abc' }),
        expectedError: { code: 'SESSION_NOT_FOUND', data: { sessionId: 'abc' } },
      },
    ].map(({ name, ...input }) => [name, input] as const))('%s', async (_name, { method, createError, expectedError }) => {
      server.setHandler(method, async () => {
        throw createError();
      });
      const resp = await requestFromClient(method);
      expect(resp.error).toMatchObject(expectedError);
      if ('data' in expectedError) {
        expect(resp.error.data).toEqual(expectedError.data);
      }
    });
  });

  // -----------------------------------------------------------------------
  // 6. notifyAll
  // -----------------------------------------------------------------------
  describe('notifyAll', () => {
    it('delivers notification to all connected clients', async () => {
      const socket1 = await connectRaw(socketPath);
      const socket2 = await connectRaw(socketPath);
      await doHello(socket1, 'c1');
      await doHello(socket2, 'c2');

      const msg1Promise = readNextFrame(socket1);
      const msg2Promise = readNextFrame(socket2);

      server.notifyAll({
        type: 'notification',
        method: 'session/closed',
        params: { sessionId: 's1', reason: 'killed', detail: 'test' },
      });

      const [msg1, msg2] = await Promise.all([msg1Promise, msg2Promise]);

      expect(msg1.type).toBe('notification');
      expect(msg1.method).toBe('session/closed');
      expect(msg1.params.sessionId).toBe('s1');
      expect(msg1.params.reason).toBe('killed');

      expect(msg2.type).toBe('notification');
      expect(msg2.method).toBe('session/closed');
      expect(msg2.params.sessionId).toBe('s1');

      socket1.destroy();
      socket2.destroy();
    });

    it('notifyAll delivers to each independently (one slow does not block)', async () => {
      const socket1 = await connectRaw(socketPath);
      const socket2 = await connectRaw(socketPath);
      await doHello(socket1);
      await doHello(socket2);

      const msg1Promise = readNextFrame(socket1);
      const msg2Promise = readNextFrame(socket2);

      server.notifyAll({
        type: 'notification',
        method: 'test/broadcast',
        params: { seq: 1 },
      });

      const [msg1, msg2] = await Promise.all([msg1Promise, msg2Promise]);
      expect(msg1.params.seq).toBe(1);
      expect(msg2.params.seq).toBe(1);

      socket1.destroy();
      socket2.destroy();
    });

    it('skips destroyed sockets in notifyAll', async () => {
      const socket1 = await connectRaw(socketPath);
      const socket2 = await connectRaw(socketPath);
      await doHello(socket1);
      await doHello(socket2);

      socket2.destroy();
      await new Promise((r) => setTimeout(r, 100));

      const msg1Promise = readNextFrame(socket1);

      server.notifyAll({
        type: 'notification',
        method: 'test/broadcast',
        params: { seq: 2 },
      });

      const msg1 = await msg1Promise;
      expect(msg1.params.seq).toBe(2);

      socket1.destroy();
    });
  });

  // -----------------------------------------------------------------------
  // 7. sendRequest (server→client)
  // -----------------------------------------------------------------------
  describe('sendRequest (server to client)', () => {
    it('resolves with client response when client replies', async () => {
      server.setHandler('test/trigger-reverse', async (_params, ctx) => {
        const result = await server.sendRequest(
          ctx,
          'client/ping',
          { foo: 'bar' },
          { timeoutMs: 5000 },
        );
        return { echoed: result };
      });

      const socket = await connectRaw(socketPath);
      await doHello(socket);

      writeRequest(socket, 2, 'test/trigger-reverse', {});

      // Read the server→client reverse request
      const reverseReq = await readNextFrame(socket, 15000, 2);
      expect(reverseReq.type).toBe('request');
      expect(reverseReq.method).toBe('client/ping');
      expect(reverseReq.params).toEqual({ foo: 'bar' });
      expect(reverseReq.id).toBeLessThan(0);

      // Client responds to the reverse request
      socket.write(
        encodeMessage({
          type: 'response',
          id: reverseReq.id,
          result: { pong: true },
        }),
      );

      // Read the final response to our original request
      const finalResp = await readNextFrame(socket);
      expect(finalResp.type).toBe('response');
      expect(finalResp.id).toBe(2);
      expect(finalResp.result).toEqual({ echoed: { pong: true } });

      socket.destroy();
    });

    it('uses decrementing negative IDs for consecutive sendRequest calls', async () => {
      // Test that server uses id=-1, id=-2, etc. for reverse requests.
      // We test one reverse request at a time to avoid race conditions.
      const ids: number[] = [];

      server.setHandler('test/one-reverse', async (_params, ctx) => {
        const result = await server.sendRequest(
          ctx,
          'client/ping',
          {},
          { timeoutMs: 5000 },
        );
        ids.push((result as any).serverId);
        return { ok: true };
      });

      // First connection: first reverse request should use id=-1
      const socket1 = await connectRaw(socketPath);
      await doHello(socket1);
      writeRequest(socket1, 2, 'test/one-reverse', {});
      const rev1 = await readNextFrame(socket1, 15000, 2);
      expect(rev1.id).toBe(-1);
      socket1.write(
        encodeMessage({
          type: 'response',
          id: rev1.id,
          result: { serverId: rev1.id },
        }),
      );
      const final1 = await readNextFrame(socket1);
      expect(final1.result.ok).toBe(true);
      socket1.destroy();

      // Second connection: still from same server, so id should continue decrementing
      const socket2 = await connectRaw(socketPath);
      await doHello(socket2);
      writeRequest(socket2, 2, 'test/one-reverse', {});
      const rev2 = await readNextFrame(socket2, 15000, 2);
      expect(rev2.id).toBe(-2);
      socket2.write(
        encodeMessage({
          type: 'response',
          id: rev2.id,
          result: { serverId: rev2.id },
        }),
      );
      const final2 = await readNextFrame(socket2);
      expect(final2.result.ok).toBe(true);
      socket2.destroy();
    });

    it('rejects on timeout when client does not respond', async () => {
      server.setHandler('test/trigger-timeout', async (_params, ctx) => {
        try {
          await server.sendRequest(ctx, 'client/slow', {}, { timeoutMs: 200 });
          return { ok: false };
        } catch (err) {
          return { error: (err as Error).message };
        }
      });

      const socket = await connectRaw(socketPath);
      await doHello(socket);

      writeRequest(socket, 2, 'test/trigger-timeout', {});

      // Read the reverse request from server
      const reverseReq = await readNextFrame(socket, 15000, 2);
      expect(reverseReq.type).toBe('request');
      expect(reverseReq.method).toBe('client/slow');

      // Do NOT respond — wait for timeout

      // Read the handler's response (it caught the timeout error)
      const finalResp = await readNextFrame(socket);
      expect(finalResp.result.error).toContain('timed out');
      expect(finalResp.result.error).toContain('client/slow');

      socket.destroy();
    });

    it('ignores cross-connection response injection (round 2 H-1)', async () => {
      // 攻击:连接 B 猜负 id 向 pendingServerRequests 注入伪造响应。
      // 修复后:handleServerRequestResponse 校验 entry.ctx === ctx, B 的注入
      // 被忽略, A 的 handler 正常收到 A 自己的响应。
      server.setHandler('test/trigger-inject', async (_params, ctx) => {
        const result = await server.sendRequest(
          ctx,
          'client/ping',
          {},
          { timeoutMs: 2000 },
        );
        return { echoed: result };
      });

      const socketA = await connectRaw(socketPath);
      const socketB = await connectRaw(socketPath);
      await doHello(socketA);
      await doHello(socketB);

      writeRequest(socketA, 2, 'test/trigger-inject', {});

      // A 收到反向请求(负 id)
      const reverseReq = await readNextFrame(socketA);
      expect(reverseReq.type).toBe('request');
      expect(reverseReq.id).toBeLessThan(0);

      // B 尝试注入伪造响应(同 id)
      socketB.write(
        encodeMessage({
          type: 'response',
          id: reverseReq.id,
          result: { injected: true },
        }),
      );

      // A 的 handler 仍挂起 —— 注入被忽略。A 自己响应。
      socketA.write(
        encodeMessage({
          type: 'response',
          id: reverseReq.id,
          result: { real: true },
        }),
      );

      const finalResp = await readNextFrame(socketA);
      expect(finalResp.result).toEqual({ echoed: { real: true } });

      socketA.destroy();
      socketB.destroy();
    });

    it('rejects immediately when socket is already destroyed', async () => {
      let capturedError: string | null = null;
      let resolveDone!: () => void;
      const done = new Promise<void>((r) => {
        resolveDone = r;
      });

      server.setHandler('test/destroy-then-send', async (_params, ctx) => {
        ctx.socket.destroy();
        try {
          await server.sendRequest(ctx, 'client/ping', {}, { timeoutMs: 1000 });
        } catch (err) {
          capturedError = (err as Error).message;
          resolveDone();
          throw err;
        }
      });

      const socket = await connectRaw(socketPath);
      await doHello(socket);

      writeRequest(socket, 2, 'test/destroy-then-send', {});

      await done;
      expect(capturedError).toContain('destroyed');

      socket.destroy();
    });

    it('rejects immediately on cyclic params (serialization failure) without leaking pending (round 18-U3 HIGH)', async () => {
      // sendRequest 在 JSON.stringify(循环引用)抛错时, 必须删除 pendingServerRequests
      // 并清 timer —— 否则 handler 挂到超时 / pending 泄漏(server.ts:210-217)。
      let capturedError: string | null = null;
      let resolveDone!: () => void;
      const done = new Promise<void>((r) => {
        resolveDone = r;
      });

      server.setHandler('test/cyclic-send', async (_params, ctx) => {
        const cyclic: Record<string, unknown> = { self: null };
        cyclic.self = cyclic;
        try {
          await server.sendRequest(ctx, 'client/cyclic', { payload: cyclic }, { timeoutMs: 50 });
          resolveDone();
        } catch (err) {
          capturedError = (err as Error).message;
          resolveDone();
          throw err;
        }
      });

      const socket = await connectRaw(socketPath);
      await doHello(socket);

      writeRequest(socket, 2, 'test/cyclic-send', {});

      await done;
      expect(capturedError).toContain('serialization failed');

      // handler 抛错 → 服务器回 id=2 的 error 响应(先读掉)。
      const errResp = await readNextFrame(socket);
      expect(errResp.id).toBe(2);
      expect(errResp.error).toBeDefined();

      // pending 已清理 → 后续同连接请求仍可正常响应(不会超时/卡死)。
      server.setHandler('test/ping-after-cyclic', async () => ({ ok: true }));
      writeRequest(socket, 3, 'test/ping-after-cyclic', {});
      const resp = await readNextFrame(socket);
      expect(resp.id).toBe(3);
      expect(resp.result).toEqual({ ok: true });

      socket.destroy();
    });

    it('sends reverse request and allows no-timeout (timeoutMs=0)', async () => {
      // timeoutMs=0 disables the timer. Verify the request still arrives
      // and the default path works (no premature timeout).
      server.setHandler('test/no-timeout', async (_params, ctx) => {
        // Fire the reverse request; we don't await it — just verify it was sent.
        // Clean up the pending entry by catching the eventual rejection when
        // the socket is destroyed.
        const promise = server.sendRequest(
          ctx,
          'client/need-reply',
          {},
          { timeoutMs: 0 },
        );
        // Attach a noop catch to prevent unhandled rejection when socket closes
        promise.catch(() => {});
        return { sent: true };
      });

      const socket = await connectRaw(socketPath);
      await doHello(socket);

      writeRequest(socket, 2, 'test/no-timeout', {});

      // The server should have sent a reverse request to us
      const reverseReq = await readNextFrame(socket, 15000, 2);
      expect(reverseReq.type).toBe('request');
      expect(reverseReq.method).toBe('client/need-reply');

      // And the handler returned (it didn't await the reverse request)
      const finalResp = await readNextFrame(socket);
      expect(finalResp.result).toEqual({ sent: true });

      socket.destroy();
    }, 15_000); // 慢 CI 下真 socket 帧到达可超 5s, 放宽 vitest 超时
  });

  // -----------------------------------------------------------------------
  // 8. disconnect cleanup
  // -----------------------------------------------------------------------
  describe('disconnect cleanup', () => {
    it('rejects pending server requests when client disconnects', async () => {
      let capturedError: string | null = null;
      let resolveDone!: () => void;
      const done = new Promise<void>((r) => {
        resolveDone = r;
      });

      server.setHandler('test/disconnect-test', async (_params, ctx) => {
        try {
          await server.sendRequest(ctx, 'client/ping', {}, { timeoutMs: 10000 });
        } catch (err) {
          capturedError = (err as Error).message;
          resolveDone();
          throw err;
        }
      });

      const socket = await connectRaw(socketPath);
      await doHello(socket);

      writeRequest(socket, 2, 'test/disconnect-test', {});

      // Read the reverse request from server
      const reverseReq = await readNextFrame(socket, 15000, 2);
      expect(reverseReq.type).toBe('request');
      expect(reverseReq.method).toBe('client/ping');

      // Disconnect without responding
      socket.destroy();

      // Wait for the rejection to propagate through close handler
      await done;
      expect(capturedError).toContain('disconnected');
    });

    it('calls onClientClose listeners when client disconnects', async () => {
      let closedClientId: string | undefined;
      const closePromise = new Promise<void>((resolve) => {
        server.onClientClose((ctx) => {
          closedClientId = ctx.clientId;
          resolve();
        });
      });

      const socket = await connectRaw(socketPath);
      await doHello(socket, 'listener-test-client');
      socket.destroy();

      await closePromise;
      expect(closedClientId).toBe('listener-test-client');
    });

    it('cleans up multiple pending requests for the same disconnected client', async () => {
      let errorCount = 0;
      let resolveDone!: () => void;
      const done = new Promise<void>((r) => {
        resolveDone = r;
      });

      server.setHandler('test/multi-pending', async (_params, ctx) => {
        const p1 = server
          .sendRequest(ctx, 'client/a', {}, { timeoutMs: 10000 })
          .catch(() => {
            errorCount++;
          });
        const p2 = server
          .sendRequest(ctx, 'client/b', {}, { timeoutMs: 10000 })
          .catch(() => {
            errorCount++;
          });
        await Promise.allSettled([p1, p2]);
        resolveDone();
        return { errorCount };
      });

      const socket = await connectRaw(socketPath);
      await doHello(socket);

      writeRequest(socket, 2, 'test/multi-pending', {});

      // Read both reverse requests (skipId=2: 先跳过 id=2 的 response 帧)
      const rev1 = await readNextFrame(socket, 15000, 2);
      const rev2 = await readNextFrame(socket);
      expect(rev1.type).toBe('request');
      expect(rev2.type).toBe('request');

      // Disconnect — should reject both pending requests
      socket.destroy();

      await done;
      expect(errorCount).toBe(2);
    }, 15_000); // 慢 CI 下真 socket 帧到达可超 5s, 放宽 vitest 超时

    it('stale server requests from one client do not affect another client', async () => {
      server.setHandler('test/make-pending', async (_params, ctx) => {
        // Fire-and-forget a sendRequest — reject on disconnect
        server
          .sendRequest(ctx, 'client/no-reply', {}, { timeoutMs: 10000 })
          .catch(() => {
            /* expected */
          });
        return { pending: true };
      });

      const socketA = await connectRaw(socketPath);
      const socketB = await connectRaw(socketPath);
      await doHello(socketA, 'client-A');
      await doHello(socketB, 'client-B');

      // Trigger pending on socketA (skipId=2: 先跳过 id=2 的 response 帧)
      writeRequest(socketA, 2, 'test/make-pending', {});
      const revA = await readNextFrame(socketA, 15000, 2);
      expect(revA.type).toBe('request');
      const respA = await readNextFrame(socketA);
      expect(respA.result).toEqual({ pending: true });

      // Disconnect socketA
      socketA.destroy();
      await new Promise((r) => setTimeout(r, 100));

      // socketB should still work
      server.setHandler('test/still-works', async () => 'all-good');
      writeRequest(socketB, 3, 'test/still-works', {});
      const respB = await readNextFrame(socketB);
      expect(respB.result).toBe('all-good');

      socketB.destroy();
    }, 15_000); // 慢 CI 下真 socket 帧到达可超 5s, 放宽 vitest 超时
  });

  // -----------------------------------------------------------------------
  // 9. Custom handlers and edge cases
  // -----------------------------------------------------------------------
  describe('custom handlers', () => {
    it('honors setHandler and returns result', async () => {
      server.setHandler('echo/test', async (params) => ({ echoed: params }));
      const socket = await connectRaw(socketPath);
      await doHello(socket);
      writeRequest(socket, 2, 'echo/test', { hello: 'world', num: 42 });
      const resp = await readNextFrame(socket);
      expect(resp.result).toEqual({ echoed: { hello: 'world', num: 42 } });
      socket.destroy();
    });

    it('allows handler override via setHandler', async () => {
      server.setHandler('test/version', async () => 'v1');
      server.setHandler('test/version', async () => 'v2');
      const socket = await connectRaw(socketPath);
      await doHello(socket);
      writeRequest(socket, 2, 'test/version', {});
      const resp = await readNextFrame(socket);
      expect(resp.result).toBe('v2');
      socket.destroy();
    });

    it('handles async handler returning undefined as valid result', async () => {
      server.setHandler('test/void', async () => {
        /* no return */
      });
      const socket = await connectRaw(socketPath);
      await doHello(socket);
      writeRequest(socket, 2, 'test/void', {});
      const resp = await readNextFrame(socket);
      expect(resp.type).toBe('response');
      expect(resp.id).toBe(2);
      expect(resp.result).toBeUndefined();
      socket.destroy();
    });

    it('rejects requests beyond per-client in-flight cap with SERVER_BUSY (round 40-w4 MEDIUM-2)', async () => {
      // 永不 resolve 的 handler:让前 32 个请求占满 in-flight 槽位。
      // 注意:每次调用都 push 新的 release(不能用单变量 —— 会被最后一个覆盖)。
      const releases: Array<() => void> = [];
      server.setHandler('test/hang', async () => new Promise<void>((r) => { releases.push(r); }));
      const socket = await connectRaw(socketPath);
      await doHello(socket);
      // 常驻帧读取器:release 后 32 帧可能合并进同一 chunk, 逐次 readNextFrame
      // 会丢合并帧 —— 用常驻队列逐帧取。
      const nextFrame = makeFrameReader(socket);
      for (let i = 0; i < 32; i += 1) writeRequest(socket, 100 + i, 'test/hang', {});
      // 第 33 个:in-flight 已满 → 同步返回 SERVER_BUSY(是所有请求里第一个响应)。
      writeRequest(socket, 200, 'test/hang', {});
      const resp = await nextFrame();
      expect(resp.id).toBe(200);
      expect(resp.error?.code).toBe('SERVER_BUSY');
      expect(resp.error?.message).toMatch(/in-flight/);
      // 释放挂起的 handler, 全部 32 个请求都拿到正常响应(限流不破坏既有请求,
      // 顺序不定 —— 收集全部)。
      releases.forEach((r) => r());
      const ids = new Set<number>();
      for (let i = 0; i < 32; i += 1) {
        const released = await nextFrame();
        expect(released.error).toBeUndefined();
        ids.add(released.id);
      }
      expect(ids.size).toBe(32); // 100..131 全部响应, 无重复无丢失
      socket.destroy();
    });

    it('handles synchronous handler', async () => {
      server.setHandler('test/sync', (params: any) => ({
        doubled: (params?.x ?? 0) * 2,
      }));
      const socket = await connectRaw(socketPath);
      await doHello(socket);
      writeRequest(socket, 2, 'test/sync', { x: 21 });
      const resp = await readNextFrame(socket);
      expect(resp.result).toEqual({ doubled: 42 });
      socket.destroy();
    });

    it('builtin hello handler can be overridden', async () => {
      server.setHandler('protocol/hello', async () => ({
        custom: 'hello-world',
      }));
      const socket = await connectRaw(socketPath);
      writeRequest(socket, 1, 'protocol/hello', {
        protocolVersion: PROTOCOL_VERSION,
      });
      const resp = await readNextFrame(socket);
      expect(resp.result).toEqual({ custom: 'hello-world' });
      socket.destroy();
    });
  });

  // -----------------------------------------------------------------------
  // 10. Server lifecycle
  // -----------------------------------------------------------------------
  describe('server lifecycle', () => {
    it('start() is idempotent', async () => {
      await server.start();
      await server.start();
      const socket = await connectRaw(socketPath);
      await doHello(socket);
      socket.destroy();
    });

    it('stop() is idempotent', async () => {
      await server.stop();
      await server.stop();
      // Should not throw
    });

    it('does not accept connections after stop()', async () => {
      await server.stop();
      try {
        await connectRaw(socketPath);
        expect.unreachable('should not connect after stop');
      } catch {
        // Expected — connection refused
      }
    });
  });

  // -----------------------------------------------------------------------
  // 11. MAX_CLIENTS connection limit (退役审轮 3 M-2)
  // -----------------------------------------------------------------------
  describe('MAX_CLIENTS connection limit', () => {
    it('accepts exactly 16 concurrent connections (at limit)', async () => {
      const sockets: net.Socket[] = [];
      try {
        for (let i = 0; i < 16; i++) {
          sockets.push(await connectRaw(socketPath));
        }
        expect(sockets).toHaveLength(16);

        // All 16 should be functional — do hello on a random one
        const helloResult = await doHello(sockets[7], `client-7`);
        expect(helloResult.protocolVersion).toBe(PROTOCOL_VERSION);
      } finally {
        for (const s of sockets) s.destroy();
      }
    });

    it('rejects 17th connection — socket destroyed immediately', async () => {
      const sockets: net.Socket[] = [];
      try {
        // Fill up to MAX_CLIENTS=16
        for (let i = 0; i < 16; i++) {
          sockets.push(await connectRaw(socketPath));
        }

        // 17th connection should be destroyed immediately
        const socket17 = net.connect(socketPath);
        await new Promise<void>((resolve) => {
          socket17.on('error', () => resolve());
          socket17.on('close', () => resolve());
          // Timeout safety net
          setTimeout(resolve, 2000);
        });
        // Give event loop a tick
        await new Promise((r) => setTimeout(r, 50));
        expect(socket17.destroyed).toBe(true);
      } finally {
        for (const s of sockets) s.destroy();
      }
    });

    it('accepts new connections after clients disconnect (slot reuse)', async () => {
      const sockets: net.Socket[] = [];
      try {
        // Fill to limit
        for (let i = 0; i < 16; i++) {
          sockets.push(await connectRaw(socketPath));
        }

        // Disconnect 4 clients
        for (let i = 0; i < 4; i++) {
          sockets[i].destroy();
        }
        // Wait for server to process close events
        await new Promise((r) => setTimeout(r, 50));

        // Should now accept 4 new connections
        const newSockets: net.Socket[] = [];
        for (let i = 0; i < 4; i++) {
          const s = await connectRaw(socketPath);
          newSockets.push(s);
        }
        expect(newSockets).toHaveLength(4);

        // Verify new connections work
        const helloResult = await doHello(newSockets[0], 'new-after-disconnect');
        expect(helloResult.protocolVersion).toBe(PROTOCOL_VERSION);

        for (const s of newSockets) s.destroy();
        // Remove the destroyed sockets from the array to avoid double-destroy
        for (let i = 0; i < 4; i++) sockets[i] = null as any;
        for (const s of sockets) {
          if (s && !s.destroyed) s.destroy();
        }
      } finally {
        for (const s of sockets) {
          if (s && !s.destroyed) s.destroy();
        }
      }
    });

    it('MAX_CLIENTS applies pre-hello (raw connections count)', async () => {
      const sockets: net.Socket[] = [];
      try {
        // Connect 16 raw sockets WITHOUT doing hello
        for (let i = 0; i < 16; i++) {
          sockets.push(await connectRaw(socketPath));
        }

        // 17th should be rejected even though none have completed hello
        const socket17 = net.connect(socketPath);
        await new Promise<void>((resolve) => {
          socket17.on('error', () => resolve());
          socket17.on('close', () => resolve());
          setTimeout(resolve, 2000);
        });
        await new Promise((r) => setTimeout(r, 50));
        expect(socket17.destroyed).toBe(true);
      } finally {
        for (const s of sockets) s.destroy();
      }
    });

    it('server still functional after hitting and releasing limit', async () => {
      // Hit the limit
      const sockets: net.Socket[] = [];
      for (let i = 0; i < 16; i++) {
        sockets.push(await connectRaw(socketPath));
      }

      // Disconnect all
      for (const s of sockets) s.destroy();
      await new Promise((r) => setTimeout(r, 50));

      // Server should be back to normal — accept new connections
      const fresh = await connectRaw(socketPath);
      const helloResult = await doHello(fresh, 'after-limit-release');
      expect(helloResult.protocolVersion).toBe(PROTOCOL_VERSION);

      // Register custom handler and use it
      server.setHandler('test/after-limit', async () => 'limit-ok');
      writeRequest(fresh, 2, 'test/after-limit', {});
      const resp = await readNextFrame(fresh);
      expect(resp.result).toBe('limit-ok');

      fresh.destroy();
    });
  });
});