reverse-engineering-anything/tests/boundary/providers/hopper/hopperClient.protocol.test.ts

import { describe, expect, it, onTestFinished, vi } from "vitest";

import { HOPPER_OPERATIONS } from "../../../../src/hopper/HopperProvider.js";
import { HopperClient } from "../../../../src/hopper/HopperClient.js";
import type { HopperDiagnostic } from "../../../../src/hopper/HopperDiagnostics.js";
import { providerCleanupFailure } from "../../../../src/hopper/HopperDiagnostics.js";

import {
  HopperFixtureLauncher as FixtureLauncher,
  startHopperFixtureClient as startClient,
} from "./hopperClient.fixture.js";

describe("HopperClient protocol", () => {
  it("sanitizes unexpected owned-cleanup exceptions", () => {
    expect(
      providerCleanupFailure(
        new Error("secret-run-token 22222222-2222-4222-8222-222222222222"),
      ),
    ).toEqual({
      cleaned: false,
      reason: "owned provider cleanup failed",
    });
  });

  it("uses the caller-assigned provider run identity", async () => {
    const launcher = new FixtureLauncher();
    const client = new HopperClient({
      launcher,
      runId: "11111111-1111-4111-8111-111111111111",
      startupTimeoutMs: 1_000,
    });
    onTestFinished(() => client.close());

    expect((await client.start()).ok).toBe(true);
    expect(launcher.runIds).toEqual(["11111111-1111-4111-8111-111111111111"]);
  });

  it("keeps the native socket path below macOS sockaddr_un limits", async () => {
    const launcher = new FixtureLauncher();
    const client = new HopperClient({ launcher, startupTimeoutMs: 1_000 });
    onTestFinished(() => client.close());
    const started = await client.start();
    expect(started.ok).toBe(true);
    expect(Buffer.byteLength(launcher.socketPaths[0] ?? "")).toBeLessThan(104);
  });

  it("serializes concurrent calls until the active Hopper reply arrives", async () => {
    const launcher = new FixtureLauncher();
    const client = await startClient(launcher);
    const slow = client.callTool("echo", { label: "slow", gate: "serial" });
    const request = await launcher.waitForRequest("echo", "serial");
    const fast = client.callTool("echo", { label: "fast" });
    let fastSettled = false;
    void fast.then(() => {
      fastSettled = true;
    });
    await vi.waitFor(() =>
      expect(client.requestActivity()).toMatchObject({
        operation: "echo",
        queuedRequests: 1,
      }),
    );
    expect(fastSettled).toBe(false);
    expect(launcher.requests.filter(({ method }) => method === "echo")).toEqual(
      [request],
    );
    await launcher.release(request);
    await expect(Promise.all([slow, fast])).resolves.toEqual([
      { ok: true, value: { label: "slow", gate: "serial" } },
      { ok: true, value: { label: "fast" } },
    ]);
  });

  it("routes every established operation through the authenticated bridge", async () => {
    const client = await startClient();
    const results = await Promise.all(
      HOPPER_OPERATIONS.map((name) => client.callTool(name, {})),
    );
    expect(results).toHaveLength(HOPPER_OPERATIONS.length);
    expect(results.every((result) => result.ok)).toBe(true);
  });
});

describe("HopperClient response lifecycle", () => {
  it("reassembles a fragmented Unicode reply from the owned socket", async () => {
    const client = await startClient();

    await expect(
      client.callTool("echo", { label: "雪🦊", fragmented: true }),
    ).resolves.toEqual({
      ok: true,
      value: { label: "雪🦊", fragmented: true },
    });
  });

  it("accepts an owned-socket response above the former 10 MiB ceiling", async () => {
    const client = await startClient();
    const label = "x".repeat(10 * 1024 * 1024 + 1);

    const result = await client.callTool("echo", { label });

    expect(result).toEqual({ ok: true, value: { label } });
  });

  it("clears a partial reply when closing and restarting the owned session", async () => {
    const launcher = new FixtureLauncher();
    const client = await startClient(launcher);
    const partialReply = client.callTool("partial_then_wait", {});
    const request = await launcher.waitForRequest("partial_then_wait");
    const partialWrite = await launcher.waitForRequest("fixture_partial_write");
    expect(partialWrite.id).toBe(request.id);

    await client.close();
    await expect(partialReply).resolves.toMatchObject({
      ok: false,
      error: { _tag: "HopperProcessError" },
    });
    await expect(client.start()).resolves.toMatchObject({ ok: true });
    await expect(client.callTool("echo", { label: "fresh" })).resolves.toEqual({
      ok: true,
      value: { label: "fresh" },
    });
  });

  it("rejects a bridge session with the wrong capability token", async () => {
    const client = new HopperClient({
      launcher: new FixtureLauncher("wrong-token"),
      startupTimeoutMs: 1_000,
    });
    onTestFinished(() => client.close());
    const result = await client.start();
    expect(result.ok).toBe(false);
    if (!result.ok) expect(result.error._tag).toBe("HopperRemoteError");
  });

  it.each([
    ["malformed", "HopperProtocolError"],
    ["wrong_id", "HopperProtocolError"],
    ["wrong_event_id", "HopperProtocolError"],
    ["malformed_event", "HopperProtocolError"],
    ["remote_error", "HopperRemoteError"],
    ["exit", "HopperProcessError"],
  ])("projects %s as %s", async (method, expectedTag) => {
    const launcher = new FixtureLauncher();
    const client = await startClient(launcher);
    const result = await client.callTool(method);
    expect(result.ok).toBe(false);
    if (!result.ok) {
      expect(result.error._tag).toBe(expectedTag);
      if (result.error._tag === "HopperRemoteError")
        expect(result.error).toMatchObject({
          operation: method,
          requestId: (await launcher.waitForRequest(method)).id,
        });
    }
    if (expectedTag === "HopperProtocolError") {
      await client.close();
      const child = launcher.processes.at(-1);
      expect({
        exitCode: child?.exitCode,
        signalCode: child?.signalCode,
      }).toEqual({
        exitCode: 0,
        signalCode: null,
      });
    }
  });

  it("preserves a sanitized bridge exception diagnostic", async () => {
    const launcher = new FixtureLauncher();
    const diagnostics: HopperDiagnostic[] = [];
    const client = new HopperClient({
      launcher,
      startupTimeoutMs: 1_000,
      onDiagnostic: (event) => diagnostics.push(event),
    });
    onTestFinished(() => client.close());
    await expect(client.start()).resolves.toMatchObject({ ok: true });
    const result = await client.callTool("remote_error");
    expect(result.ok).toBe(false);
    if (!result.ok)
      expect(result.error).toMatchObject({
        _tag: "HopperRemoteError",
        diagnosticType: "bridge_exception",
      });
    expect(diagnostics).toContainEqual({
      type: "bridge-diagnostic",
      request_id: (await launcher.waitForRequest("remote_error")).id,
      code: -32001,
      category: "bridge_exception",
      message: "safe fake failure",
    });
  });
});