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。

24.6 KB
Raw Blame
/**
 * RemoteHost remote forwarding (ssh -R 等价物) 测试。
 *
 * 用 fake ssh2 Client (EventEmitter + forwardIn/unforwardIn) 注入私有字段,
 * 本地端用真实 net server (127.0.0.1 回环) 验证字节 pipe:
 *   - 首选端口绑定 / 端口冲突顺延 / 全部失败时报错提及 AllowTcpForwarding
 *   - 'tcp connection' 分发到正确的 forward 并双向 pipe
 *   - 本地目标不可达时只断 channel 不炸进程
 *   - ensure 幂等 / close 调 unforwardIn
 *   - 断线重连 re-arm: 愿望保留、端口变化触发 onRearmed
 */

import { describe, it, expect, vi } from 'vitest';
import { EventEmitter } from 'node:events';
import { Duplex, PassThrough } from 'node:stream';
import net from 'node:net';

import { RemoteHost, DEFAULT_REMOTE_FORWARD_PORT_BASE } from '../RemoteHost.js';
import type { HostConfig } from '../types.js';

const HOST_CONFIG: HostConfig = {
  id: 'test-host',
  hostname: '10.0.0.1',
  port: 22,
  user: 'deploy',
  authMethod: 'agent',
  source: 'manual',
  managedByCindy: false,
};

const noopLogger = {
  debug: () => {},
  info: () => {},
  warn: () => {},
  error: () => {},
};

interface ForwardInCall { addr: string; port: number }

type ForwardInCallback = (err: Error | undefined, port: number) => void;

/** 可按端口决定成败的 fake ssh2 Client。 */
class FakeClient extends EventEmitter {
  forwardInCalls: ForwardInCall[] = [];
  unforwardInCalls: ForwardInCall[] = [];
  /** 返回 false 的端口 forwardIn 失败 (模拟被占用 / sshd 拒绝)。 */
  constructor(private readonly allowPort: (port: number) => boolean = () => true) {
    super();
  }
  forwardIn(addr: string, port: number, cb: ForwardInCallback): void {
    this.forwardInCalls.push({ addr, port });
    queueMicrotask(() => {
      if (this.allowPort(port)) cb(undefined, port);
      else cb(new Error('Unable to bind'), 0);
    });
  }
  unforwardIn(addr: string, port: number, cb: () => void): void {
    this.unforwardInCalls.push({ addr, port });
    queueMicrotask(() => cb());
  }
}

/** forwardIn 回调完全手动驱动的 fake — 用来造在飞 / 迟到回调的竞态场景。 */
class ManualForwardClient extends EventEmitter {
  pending = new Map<number, ForwardInCallback>();
  unforwardInCalls: ForwardInCall[] = [];
  forwardIn(_addr: string, port: number, cb: ForwardInCallback): void {
    this.pending.set(port, cb);
  }
  unforwardIn(addr: string, port: number, cb: () => void): void {
    this.unforwardInCalls.push({ addr, port });
    queueMicrotask(() => cb());
  }
  succeed(port: number): void {
    const cb = this.pending.get(port);
    this.pending.delete(port);
    cb?.(undefined, port);
  }
}

interface FakeChannelBundle {
  channel: Duplex & { close: () => void };
  /** test 写入 → channel readable → 本地 sock (模拟远端发来的字节)。 */
  fromRemote: PassThrough;
  /** 本地 sock 写入 → test 读出 (模拟要送回远端的字节)。 */
  toRemote: PassThrough;
  closed: () => boolean;
}

function makeFakeChannel(): FakeChannelBundle {
  const fromRemote = new PassThrough();
  const toRemote = new PassThrough();
  let closed = false;
  // 手工拼 Duplex (@types/node 没有 {readable,writable} pair overload 的类型):
  // readable 侧由 fromRemote 推, writable 侧落进 toRemote 供断言。
  const channel = new Duplex({
    read() {},
    write(chunk: Buffer, _enc: BufferEncoding, cb: (err?: Error | null) => void) {
      if (toRemote.write(chunk)) cb();
      else toRemote.once('drain', () => cb());
    },
  }) as Duplex & { close: () => void };
  fromRemote.on('data', (chunk: Buffer) => channel.push(chunk));
  fromRemote.on('end', () => channel.push(null));
  channel.close = () => {
    if (closed) return;
    closed = true;
    channel.destroy();
  };
  return { channel, fromRemote, toRemote, closed: () => closed };
}

/** makeReadyHost 接受的最小 fake client 面 (FakeClient / ManualForwardClient 共用)。 */
interface FakeSshClient extends EventEmitter {
  forwardIn(addr: string, port: number, cb: ForwardInCallback): void;
  unforwardIn(addr: string, port: number, cb: () => void): void;
}

function makeReadyHost(client: FakeSshClient): RemoteHost {
  const host = new RemoteHost(HOST_CONFIG, { logger: noopLogger });
  (host as unknown as { status: string }).status = 'ready';
  (host as unknown as { client: unknown }).client = client;
  return host;
}

async function flush(): Promise<void> {
  await new Promise((r) => setTimeout(r, 10));
}

/** 起一个在 127.0.0.1 随机端口的 echo server, 返回端口与关闭函数。 */
async function startEchoServer(): Promise<{ port: number; close: () => Promise<void> }> {
  const server = net.createServer((sock) => sock.pipe(sock));
  // 跟踪存活连接:close() 必须主动销毁它们。否则断言失败时 finally 里的
  // server.close() 会等残留连接自然关闭而永久挂起,把真实的断言失败掩盖成
  // 5s 用例超时(CI 实际发生过)。
  const sockets = new Set<net.Socket>();
  server.on('connection', (sock) => {
    sockets.add(sock);
    sock.on('close', () => sockets.delete(sock));
  });
  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
  const port = (server.address() as net.AddressInfo).port;
  return {
    port,
    close: () => new Promise<void>((resolve) => {
      for (const sock of sockets) sock.destroy();
      server.close(() => resolve());
    }),
  };
}

describe('RemoteHost remote forwarding', () => {
  it('arms forwardIn on the preferred port and lists it as armed', async () => {
    const client = new FakeClient();
    const host = makeReadyHost(client);
    const fwd = await host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });

    expect(fwd.remotePort).toBe(DEFAULT_REMOTE_FORWARD_PORT_BASE);
    expect(client.forwardInCalls).toEqual([
      { addr: '127.0.0.1', port: DEFAULT_REMOTE_FORWARD_PORT_BASE },
    ]);
    expect(host.listRemoteForwards()).toEqual([
      {
        localHost: '127.0.0.1',
        localPort: 7890,
        remotePort: DEFAULT_REMOTE_FORWARD_PORT_BASE,
        armed: true,
      },
    ]);
  });

  it('falls back to the next candidate port when the preferred one is taken', async () => {
    const client = new FakeClient((port) => port !== DEFAULT_REMOTE_FORWARD_PORT_BASE);
    const host = makeReadyHost(client);
    const fwd = await host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });

    expect(fwd.remotePort).toBe(DEFAULT_REMOTE_FORWARD_PORT_BASE + 1);
    expect(client.forwardInCalls.map((c) => c.port)).toEqual([
      DEFAULT_REMOTE_FORWARD_PORT_BASE,
      DEFAULT_REMOTE_FORWARD_PORT_BASE + 1,
    ]);
  });

  it('throws an actionable error when every candidate port fails', async () => {
    const client = new FakeClient(() => false);
    const host = makeReadyHost(client);
    await expect(
      host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 }),
    ).rejects.toThrow(/AllowTcpForwarding/);
  });

  it('rejects invalid local targets before touching ssh', async () => {
    const host = makeReadyHost(new FakeClient());
    await expect(
      host.ensureRemoteForward({ localHost: 'bad host', localPort: 7890 }),
    ).rejects.toThrow(/localHost/);
    await expect(
      host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 0 }),
    ).rejects.toThrow(/localPort/);
    // preferredRemotePort 同样入口校验: 0 会静默变成远端 ephemeral 绑端口语义
    // (review: PR #715 copilot R7)。
    await expect(
      host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890, preferredRemotePort: 0 }),
    ).rejects.toThrow(/preferredRemotePort/);
    await expect(
      host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890, preferredRemotePort: 70000 }),
    ).rejects.toThrow(/preferredRemotePort/);
    // localHost 的引号与空白同样拒 (与 desktop IPC / prefs-store 对齐,
    // review: PR #715 copilot R8) — 否则晚到 net.connect 才以难懂的错误失败。
    await expect(
      host.ensureRemoteForward({ localHost: `12'7.0.0.1`, localPort: 7890 }),
    ).rejects.toThrow(/localHost/);
    await expect(
      host.ensureRemoteForward({ localHost: '12"7.0.0.1', localPort: 7890 }),
    ).rejects.toThrow(/localHost/);
  });

  it('is idempotent for the same local target (no duplicate forwardIn)', async () => {
    const client = new FakeClient();
    const host = makeReadyHost(client);
    const a = await host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });
    const b = await host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });
    expect(a.remotePort).toBe(b.remotePort);
    expect(client.forwardInCalls).toHaveLength(1);
  });

  it('pipes a forwarded connection to the local target and back', async () => {
    const echo = await startEchoServer();
    try {
      const client = new FakeClient();
      const host = makeReadyHost(client);
      const fwd = await host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: echo.port });

      const fake = makeFakeChannel();
      client.emit(
        'tcp connection',
        { srcIP: '127.0.0.1', srcPort: 55000, destIP: '127.0.0.1', destPort: fwd.remotePort },
        () => fake.channel,
        () => { throw new Error('unexpected reject'); },
      );
      fake.fromRemote.write('ping-through-tunnel');

      // echo server 原样弹回 → 应出现在要送回远端的流里。真实 TCP 往返需要
      // 多个事件循环 + 网络轮次,固定 10ms flush 在慢 CI 上不够(实际误挂过):
      // 改用有界轮询累积读取,消除调度抖动依赖。
      let echoed = '';
      await vi.waitFor(() => {
        const chunk = fake.toRemote.read();
        if (chunk) echoed += chunk.toString();
        expect(echoed).toBe('ping-through-tunnel');
      });
      fake.channel.close();
    } finally {
      await echo.close();
    }
  });

  it('closes the channel (no crash) when the local target is unreachable', async () => {
    // 先占一个端口再释放, 拿到一个几乎必然拒连的端口。
    const probe = await startEchoServer();
    const deadPort = probe.port;
    await probe.close();

    const client = new FakeClient();
    const host = makeReadyHost(client);
    const fwd = await host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: deadPort });

    const fake = makeFakeChannel();
    client.emit(
      'tcp connection',
      { srcIP: '127.0.0.1', srcPort: 55001, destIP: '127.0.0.1', destPort: fwd.remotePort },
      () => fake.channel,
      () => { throw new Error('unexpected reject'); },
    );
    // ECONNREFUSED 是异步的; 等它发生。
    await flush();
    expect(fake.closed()).toBe(true);
  });

  it('rejects connections to unknown destPorts', async () => {
    const client = new FakeClient();
    const host = makeReadyHost(client);
    await host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });

    let rejected = false;
    client.emit(
      'tcp connection',
      { srcIP: '127.0.0.1', srcPort: 55002, destIP: '127.0.0.1', destPort: 1 },
      () => { throw new Error('unexpected accept'); },
      () => { rejected = true; },
    );
    expect(rejected).toBe(true);
  });

  it('rejects forwarded connections from non-loopback sources (fail-closed, PR #715 copilot)', async () => {
    // 远端 sshd 配了 permissive GatewayPorts 时, 隧道口绑到非 loopback 接口,
    // 远端网络的任意机器都能经隧道借用本机 Proxy — 只接受 loopback 来源
    // (远端 daemon 与 sshd 同机, 合法来源恒为 loopback)。
    const client = new FakeClient();
    const host = makeReadyHost(client);
    const fwd = await host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });

    let rejected = false;
    client.emit(
      'tcp connection',
      { srcIP: '192.168.1.50', srcPort: 55003, destIP: '192.168.1.10', destPort: fwd.remotePort },
      () => { throw new Error('unexpected accept'); },
      () => { rejected = true; },
    );
    expect(rejected).toBe(true);
  });

  it('close() unforwards on the live client and drops the record', async () => {
    const client = new FakeClient();
    const host = makeReadyHost(client);
    const fwd = await host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });
    await fwd.close();

    expect(client.unforwardInCalls).toEqual([
      { addr: '127.0.0.1', port: DEFAULT_REMOTE_FORWARD_PORT_BASE },
    ]);
    expect(host.listRemoteForwards()).toEqual([]);
  });

  it('keeps a shared forward alive until the last handle closes (refcount)', async () => {
    // 轮 42 P1(codex-connector):同 host 多个 Pi 会话共享同一 in-process MCP
    // bridge(local 端口相同) — ensure 幂等命中同一 record, 一方 dispose 不得
    // 拆掉别人还在用的隧道。最后一个 handle close 才真正 unforward。
    const client = new FakeClient();
    const host = makeReadyHost(client);
    const a = await host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });
    const b = await host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });

    // a dispose: 共享者 b 还在 → 不拆。
    await a.close();
    expect(client.unforwardInCalls).toEqual([]);
    expect(host.listRemoteForwards()).toHaveLength(1);

    // b dispose: 最后一人 → 真正 unforward + 摘除。
    await b.close();
    expect(client.unforwardInCalls).toEqual([
      { addr: '127.0.0.1', port: DEFAULT_REMOTE_FORWARD_PORT_BASE },
    ]);
    expect(host.listRemoteForwards()).toEqual([]);

    // 同 handle 重复 close 幂等: 不再触发第二次 unforward。
    await b.close();
    expect(client.unforwardInCalls).toHaveLength(1);
  });

  it('re-arms on reconnect and reports a changed port via onRearmed', async () => {
    const client1 = new FakeClient();
    const host = makeReadyHost(client1);
    let rearmed: number | null = null;
    const fwd = await host.ensureRemoteForward({
      localHost: '127.0.0.1',
      localPort: 7890,
      onRearmed: (port) => { rearmed = port; },
    });
    expect(fwd.remotePort).toBe(DEFAULT_REMOTE_FORWARD_PORT_BASE);

    // 模拟断线重连: 标记 disarm (handlePostReadyClose 路径) 并换上新 client,
    // 新连接上原端口已被别人占 → 应顺延并回调 onRearmed。
    (host as unknown as { markForwardsDisarmed(): void }).markForwardsDisarmed();
    const client2 = new FakeClient((port) => port !== DEFAULT_REMOTE_FORWARD_PORT_BASE);
    (host as unknown as { client: unknown }).client = client2;
    await (host as unknown as { rearmForwards(): Promise<void> }).rearmForwards();

    expect(fwd.remotePort).toBe(DEFAULT_REMOTE_FORWARD_PORT_BASE + 1);
    expect(rearmed).toBe(DEFAULT_REMOTE_FORWARD_PORT_BASE + 1);
    expect(host.listRemoteForwards()[0]?.armed).toBe(true);
  });

  it('re-arm prefers the last bound port (no churn / no onRearmed when it is still free)', async () => {
    // 首轮 base 被占 → 绑到 base+1; 重连后 base 已空闲, 仍应留在 base+1
    // (远端 daemon env / marker 指向它, 端口 churn 会触发无谓的 env 重写)。
    const client1 = new FakeClient((port) => port !== DEFAULT_REMOTE_FORWARD_PORT_BASE);
    const host = makeReadyHost(client1);
    let rearmed: number | null = null;
    const fwd = await host.ensureRemoteForward({
      localHost: '127.0.0.1',
      localPort: 7890,
      onRearmed: (port) => { rearmed = port; },
    });
    expect(fwd.remotePort).toBe(DEFAULT_REMOTE_FORWARD_PORT_BASE + 1);

    (host as unknown as { markForwardsDisarmed(): void }).markForwardsDisarmed();
    const client2 = new FakeClient(() => true); // 全部空闲
    (host as unknown as { client: unknown }).client = client2;
    await (host as unknown as { rearmForwards(): Promise<void> }).rearmForwards();

    expect(fwd.remotePort).toBe(DEFAULT_REMOTE_FORWARD_PORT_BASE + 1);
    expect(rearmed).toBeNull();
    expect(client2.forwardInCalls.map((c) => c.port)).toEqual([DEFAULT_REMOTE_FORWARD_PORT_BASE + 1]);
  });

  it('unbinds a late forwardIn success that races the 10s watchdog', async () => {
    vi.useFakeTimers();
    try {
      const client = new ManualForwardClient();
      const host = makeReadyHost(client);
      const pending = host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });
      // 第一个候选卡在在飞状态; 看门狗 10s 后判失败, 转下一候选。
      await vi.advanceTimersByTimeAsync(10_100);
      expect(client.pending.has(DEFAULT_REMOTE_FORWARD_PORT_BASE + 1)).toBe(true);
      // 迟到的成功: 必须立刻 unbind, 不能在服务端留下野监听。
      client.succeed(DEFAULT_REMOTE_FORWARD_PORT_BASE);
      expect(client.unforwardInCalls).toContainEqual({
        addr: '127.0.0.1',
        port: DEFAULT_REMOTE_FORWARD_PORT_BASE,
      });
      client.succeed(DEFAULT_REMOTE_FORWARD_PORT_BASE + 1);
      const fwd = await pending;
      expect(fwd.remotePort).toBe(DEFAULT_REMOTE_FORWARD_PORT_BASE + 1);
    } finally {
      vi.useRealTimers();
    }
  });

  it('unbinds the just-bound port when close() races an in-flight arm', async () => {
    const client = new ManualForwardClient();
    const host = makeReadyHost(client);
    const pending = host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });
    pending.catch(() => { /* assertion below via rejects */ });
    // arm 在飞 (forwardIn 未回调) 时关掉 forward。
    await host.closeAllRemoteForwards();
    expect(host.listRemoteForwards()).toEqual([]);
    // 迟到的绑定成功: record 已摘除, 必须 unbind 而不是留野监听。
    client.succeed(DEFAULT_REMOTE_FORWARD_PORT_BASE);
    await expect(pending).rejects.toThrow(/closed while arming/);
    await flush();
    expect(client.unforwardInCalls).toContainEqual({
      addr: '127.0.0.1',
      port: DEFAULT_REMOTE_FORWARD_PORT_BASE,
    });
  });

  it('re-arms on the current connection when forwardIn resolves on a stale one (review P1)', async () => {
    // arm 在飞期间断线/重连: 旧 client 的迟到成功不得把隧道误标 armed —
    // 应在旧 client 上 unbind 并在当前连接上重试。
    const client1 = new ManualForwardClient();
    const client2 = new ManualForwardClient();
    const host = makeReadyHost(client1);
    const pending = host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });
    // 断线/重连窗口: markForwardsDisarmed 清掉在飞 arm 引用, client 换成新连接。
    (host as unknown as { markForwardsDisarmed(): void }).markForwardsDisarmed();
    (host as unknown as { client: unknown }).client = client2;
    // 旧连接迟到成功 → StaleForwardArmError → armWithStaleRetry 立即在 client2 重试。
    client1.succeed(DEFAULT_REMOTE_FORWARD_PORT_BASE);
    await flush();
    expect(client1.unforwardInCalls).toContainEqual({
      addr: '127.0.0.1',
      port: DEFAULT_REMOTE_FORWARD_PORT_BASE,
    });
    // 重试落在 client2 上, 完成绑定。
    expect(client2.pending.has(DEFAULT_REMOTE_FORWARD_PORT_BASE)).toBe(true);
    client2.succeed(DEFAULT_REMOTE_FORWARD_PORT_BASE);
    const fwd = await pending;
    expect(fwd.remotePort).toBe(DEFAULT_REMOTE_FORWARD_PORT_BASE);
    expect(host.listRemoteForwards()[0]?.armed).toBe(true);
  });

  it('clears the forward listener client on disconnect; a new client re-attaches (review R3)', async () => {
    // forwardListenerClient 不清会让 RemoteHost 长期持有死 client (抑制 GC +
    // 多次重连后旧 client listener 堆积); 断连后必须置空, 新连接 arm 时重挂。
    const client1 = new FakeClient();
    const host = makeReadyHost(client1);
    await host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });
    expect(client1.listenerCount('tcp connection')).toBe(1);

    (host as unknown as { markForwardsDisarmed(): void }).markForwardsDisarmed();
    expect((host as unknown as { forwardListenerClient: unknown }).forwardListenerClient).toBeNull();

    const client2 = new FakeClient();
    (host as unknown as { client: unknown }).client = client2;
    await (host as unknown as { rearmForwards(): Promise<void> }).rearmForwards();
    expect(client2.listenerCount('tcp connection')).toBe(1);
    expect((host as unknown as { forwardListenerClient: unknown }).forwardListenerClient).toBe(client2);
  });

  it('keeps the wish when re-arm fails, without throwing (logged only)', async () => {
    const client1 = new FakeClient();
    const host = makeReadyHost(client1);
    await host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });

    (host as unknown as { markForwardsDisarmed(): void }).markForwardsDisarmed();
    const client2 = new FakeClient(() => false);
    (host as unknown as { client: unknown }).client = client2;
    await (host as unknown as { rearmForwards(): Promise<void> }).rearmForwards();

    const listed = host.listRemoteForwards();
    expect(listed).toHaveLength(1);
    expect(listed[0]?.armed).toBe(false);
  });

  it('defers arming until connect when the host is not ready', async () => {
    const client = new FakeClient();
    const host = new RemoteHost(HOST_CONFIG, { logger: noopLogger });
    // disconnected 状态: 只登记愿望, 不碰 ssh。
    const fwdPromise = host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890 });
    await expect(fwdPromise).resolves.toBeDefined();
    expect(client.forwardInCalls).toHaveLength(0);

    // 连接建立 → doConnect onReady 路径的 rearmForwards 把它挂上。
    (host as unknown as { status: string }).status = 'ready';
    (host as unknown as { client: unknown }).client = client;
    await (host as unknown as { rearmForwards(): Promise<void> }).rearmForwards();
    expect(client.forwardInCalls).toHaveLength(1);
  });
});

describe('RemoteHost remote forwarding — exactRemotePort (固定端口)', () => {
  it('binds only the fixed port and succeeds when it is free', async () => {
    const client = new FakeClient();
    const host = makeReadyHost(client);
    const fwd = await host.ensureRemoteForward({
      localHost: '127.0.0.1',
      localPort: 7890,
      preferredRemotePort: 45000,
      exactRemotePort: true,
    });
    expect(fwd.remotePort).toBe(45000);
    expect(client.forwardInCalls).toEqual([{ addr: '127.0.0.1', port: 45000 }]);
  });

  it('fails without falling back to other candidates when the fixed port is busy', async () => {
    // 固定端口语义: 远端 env 写死该端口, 顺延 = env 失效 + 必须重启 daemon,
    // 宁可失败让调用方 (agent-proxy 保活器) 重试/清理残留监听。
    const client = new FakeClient((port) => port !== 45000);
    const host = makeReadyHost(client);
    await expect(
      host.ensureRemoteForward({
        localHost: '127.0.0.1',
        localPort: 7890,
        preferredRemotePort: 45000,
        exactRemotePort: true,
      }),
    ).rejects.toThrow(/remote port forwarding failed/);
    expect(client.forwardInCalls).toEqual([{ addr: '127.0.0.1', port: 45000 }]);
  });

  it('rejects exactRemotePort without preferredRemotePort at the entrance', async () => {
    const client = new FakeClient();
    const host = makeReadyHost(client);
    await expect(
      host.ensureRemoteForward({ localHost: '127.0.0.1', localPort: 7890, exactRemotePort: true }),
    ).rejects.toThrow(/exactRemotePort requires preferredRemotePort/);
    expect(client.forwardInCalls).toHaveLength(0);
  });

  it('exact mode seeds the fixed port even when the record previously drifted (PR #992 copilot)', async () => {
    // 同 key 的 record 先在非 exact 阶段顺延漂到别的端口; 之后同 key 改
    // exactRemotePort=true 重绑时, 候选必须回到 preferred 固定端口, 不得以
    // 漂移值为种子把「固定端口」语义吃回去。
    const client = new FakeClient((port) => port !== 45000 && port !== 45001);
    const host = makeReadyHost(client);
    // 非 exact: 45000、45001 都被占 → 顺延到 45002 (record 漂到 45002)。
    const fwd = await host.ensureRemoteForward({
      localHost: '127.0.0.1',
      localPort: 7890,
      preferredRemotePort: 45000,
    });
    expect(fwd.remotePort).toBe(45002);
    expect(client.forwardInCalls).toEqual([
      { addr: '127.0.0.1', port: 45000 },
      { addr: '127.0.0.1', port: 45001 },
      { addr: '127.0.0.1', port: 45002 },
    ]);
    // 模拟同 record 在 exact 语义下重绑 (断开愿望, 以 exact 重新登记)。
    await host.closeRemoteForward('127.0.0.1', 7890);
    const client2 = new FakeClient((port) => port === 45000); // 45000 现在可用
    (host as unknown as { client: unknown }).client = client2;
    const exact = await host.ensureRemoteForward({
      localHost: '127.0.0.1',
      localPort: 7890,
      preferredRemotePort: 45000,
      exactRemotePort: true,
    });
    expect(exact.remotePort).toBe(45000);
    // 只试了固定端口 45000 — 没有从漂移的 45002 开始。
    expect(client2.forwardInCalls).toEqual([{ addr: '127.0.0.1', port: 45000 }]);
  });
});