Files
reverse-engineering-anything/tests/boundary/providers/hopper/hopperClient.handshakeRecovery.test.ts
T
morluto a8e472967b refactor(process): read Ghidra and Hopper replies through one bounded JSON-line reader (#10699)
* refactor(process): read Ghidra and Hopper replies through one bounded JSON-line reader

Both clients now share JsonLineBridgeReader: UTF-8 framing with a mandatory
reply line ceiling (bridge.max_reply_bytes, REA_BRIDGE_MAX_REPLY_BYTES,
default 256 MiB), one fatal UTF-8 policy, request-id correlation including
rejections on the reserved id 0, and typed stream failures. An oversized
reply is refused as a transport resource constraint naming the setting and
its bytes are discarded. Hopper rejections on id 0 now reach the request on
the wire instead of being dropped.

Deletes GhidraResponseRouter and HopperResponseStream.

* fix(process): bound each bridge reply by the ceiling its own request admitted

* fix(process): admit the bridge reply ceiling before launching Hopper or Ghidra

* fix(ghidra): keep a refused setting's configuration error through the provider boundary

* fix(process): admit both bridge ceilings per request as a typed configuration refusal

A malformed REA_BRIDGE_MAX_REQUEST_BYTES or REA_BRIDGE_MAX_REPLY_BYTES seed covered by a runtime override at startup is refused by the runtime view once the override is reset. Hopper and Ghidra read those getters in the request path (and Hopper re-read the request ceiling when a queued request reached the wire, outside the caller's context), so the refusal was thrown instead of returned. Both clients now copy both ceilings once at admission through readRuntimeSetting, return the ConfigurationError (Ghidra as an admission failure), and write queued requests under the ceilings they were admitted with.

* refactor(config): read rizin, gdb, Kuna, Ghidra and regex settings through readRuntimeSetting (#10795)

Each site caught the ConfigurationError a setting view throws for a malformed launch seed by hand. They now read through readRuntimeSetting and return its Result. GDB reads both debugger limits once per console command and reuses those accepted values for its limitations, timeout and diagnostics instead of re-reading the views after the command ran. Kuna's single-function read returns the refusal after releasing admission instead of throwing it. A counted architecture guard keeps the remaining hand-caught sites from growing.

* refactor(hopper): return typed bridge replies from HopperClient.callTool (#10833)

* refactor(hopper): return typed bridge replies from HopperClient.callTool

The reply contract table existed, but the provider, caller reconciliation and
regex search each applied it after callTool returned JsonValue. callTool is now
typed by method: it validates the reply against that method's contract and
returns the typed reply, or a HopperReplyContractError that names the method
and keeps the raw reply. The caller scan keeps that raw reply as its unread
page or native result. The provider dispatches list_names, file offsets and
the three reconciled operations through their literal methods, and health has
its own contract. Transport tests inject a JSON-value table for the fake
bridge's own methods.

* fix(hopper): refuse value-changing reply contracts and uninstalled methods

parseHopperReply returns the raw reply, so a contract whose input and output types differ (a coercion, default or transform) would promise a type the reply does not hold. ValueKeepingContracts refuses such a schema at compile time, for the production table and any injected one. A client whose type argument names a table it was not given now returns AnalysisCapabilityUnavailableError for a method with no installed contract instead of throwing.

* refactor(hopper): read the startup handshake through the health reply contract (#10853)

parseHopperServerInfo hand-checked each health field that hopperReplySchemas.health already defines. It now parses through that contract, keeps the zod failure as the protocol error's cause, and binds run_id to the launch.

* refactor(kuna): read the project deadline through readRuntimeSetting at each request (#10837)

* refactor(kuna): read the project deadline through readRuntimeSetting at each request

The string, call-graph and xref scans read kuna.project_timeout_ms inside the background producer they start, and the project export read it inside the shared startup promise. A malformed launch seed without an override was thrown from there and reached the caller only through the generic failure mapper; a concurrent waiter that swallows the startup promise's rejection never saw it. Each site now reads the deadline with readRuntimeSetting before starting its work and returns the refusal as that request's value; the export start returns it to each caller that needs the project, and the next request reads it again.

* fix(kuna): return a call-graph deadline refusal from analyze_function

The dossier reported any relationship failure as unavailable call coverage. A call-graph deadline refusal is the request's own setting failure, so it now returns as that ConfigurationError, as cleanup and cancellation already did.

* refactor(kuna): require the accepted project deadline on every export request

Remove acceptedExportDeadline's fallback read of the throwing configuration view. KunaProjectRequest and KunaExportRequest now require the deadline the starting operation accepted; the session passes the one it admitted through readRuntimeSetting into #lookupOrBuild. Direct cache callers in tests take it from one shared helper, withKunaProjectDeadline.

* test(mcp): carry main's Evidence-format const count (#10995) beside the bridge reply setting's

* fix(process): clean Hopper and Ghidra sessions up under the ceilings their start admitted

Cleanup requests re-admitted bridge.max_request_bytes and bridge.max_reply_bytes from the current settings. Once an override covering a malformed launch seed was reset, Hopper's shutdown_document and Ghidra's closing checkpoint_program and shutdown were refused before writing, leaving Hopper's document and files or Ghidra's JVM behind. Each session now keeps the ceilings it admitted at start, and its cleanup requests use them.

* fix(hopper): reauthenticate for cleanup under the session's admitted ceilings

The cleanup reconnect's health handshake still re-admitted the ceilings from the current settings, so a seed refused after an override reset blocked reauthentication and the shutdown after it. It now uses the same session ceilings as the shutdown requests, through one #cleanupLimits accessor.

* refactor(process): report an NDJSON line above its ceiling as a limit parse failure

Utf8NdjsonOversizeError now extends ParseFailureError<"limit"> (format ndjson, limit ndjson-line-bytes) and keeps the observed bytes the transport error reports, so parseFailureFromCause recognizes it like every other byte-format budget.
2026-11-15 20:37:21 +08:00

367 lines
12 KiB
TypeScript

import {
transportReplyContracts,
HopperFixtureLauncher,
} from "./hopperClient.fixture.js";
import { execFile, spawn, type ChildProcess } from "node:child_process";
import { access, rm } from "node:fs/promises";
import { setTimeout as delay } from "node:timers/promises";
import { promisify } from "node:util";
import { expect, it, onTestFinished } from "vitest";
import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjection.js";
import { ok } from "../../../../src/domain/result.js";
import { ConfigurationError } from "../../../../src/domain/configurationErrors.js";
import type { BridgeMaxReplyBytes } from "../../../../src/config/bridgeMaxReplyBytes.js";
import type {
BridgeLauncher,
BridgeSession,
} from "../../../../src/hopper/BridgeLauncher.js";
import { HopperClient } from "../../../../src/hopper/HopperClient.js";
import { waitFor } from "../../../support/testWait.js";
const stop = async (child: ChildProcess): Promise<void> => {
if (child.exitCode !== null || child.signalCode !== null) return;
const exited = new Promise<void>((resolve) =>
child.once("exit", () => resolve()),
);
child.kill("SIGKILL");
await exited;
};
// The GUI is a sibling owned by the test, never a descendant owned by REA's helper.
class ExternalBridgeLauncher implements BridgeLauncher {
readonly fixture: HopperFixtureLauncher;
readonly sessions: BridgeSession[] = [];
readonly helpers: ChildProcess[] = [];
constructor(
readonly identity: "matching" | "wrong-run" | "wrong-token" = "matching",
healthMode: "ready" | "gated" = "ready",
shutdownMode: "acknowledge" | "exit-without-ack" = "acknowledge",
) {
this.fixture = new HopperFixtureLauncher(
identity === "wrong-token" ? "foreign-token" : undefined,
"quiet",
healthMode,
shutdownMode,
);
}
async launch(session: BridgeSession) {
this.sessions.push(session);
await this.fixture.launch({
...session,
runId: this.identity === "wrong-run" ? "foreign-run" : session.runId,
});
const helper = spawn(process.execPath, ["-e", "process.exit(0)"], {
stdio: "ignore",
});
this.helpers.push(helper);
return ok({
process: helper,
ownsProcessLifetime: false as const,
providerLifetime: "external-application" as const,
shutdownMode: "bridge-request" as const,
});
}
}
const setup = (
identity?: "matching" | "wrong-run" | "wrong-token",
healthMode?: "ready" | "gated",
shutdownMode?: "acknowledge" | "exit-without-ack",
bridgeMaxReplyBytes?: BridgeMaxReplyBytes,
) => {
const launcher = new ExternalBridgeLauncher(
identity,
healthMode,
shutdownMode,
);
const client = new HopperClient({
replyContracts: transportReplyContracts,
launcher,
startupTimeoutMs: 2_000,
...(bridgeMaxReplyBytes === undefined ? {} : { bridgeMaxReplyBytes }),
});
onTestFinished(async () => {
await client.close();
await Promise.all(
[...launcher.helpers, ...launcher.fixture.processes].map(stop),
);
await Promise.all(
launcher.sessions.map(({ directory }) =>
rm(directory, { recursive: true, force: true }),
),
);
});
return { client, launcher };
};
it.each(["missing", "not-listening"] as const)(
"waits for a matching bridge published during close after a %s socket failure",
async (socketState) => {
const fixture = new HopperFixtureLauncher();
let session: BridgeSession | undefined;
let helper: ChildProcess | undefined;
const client = new HopperClient({
replyContracts: transportReplyContracts,
startupTimeoutMs: 2_000,
launcher: {
launch(value) {
session = value;
helper = spawn(process.execPath, ["-e", "process.exit(0)"], {
stdio: "ignore",
});
return Promise.resolve(
ok({
process: helper,
ownsProcessLifetime: false as const,
providerLifetime: "external-application" as const,
shutdownMode: "bridge-request" as const,
}),
);
},
},
});
onTestFinished(async () => {
await Promise.all(
[...(helper === undefined ? [] : [helper]), ...fixture.processes].map(
stop,
),
);
if (session !== undefined)
await rm(session.directory, { recursive: true, force: true });
});
const started = await client.start();
if (started.ok) throw new Error("Expected readiness to time out");
expect(projectAnalysisError(started.error)).toMatchObject({
code: "cleanup_incomplete",
details: { diagnostics: { primary_error: { code: "provider_timeout" } } },
});
if (session === undefined) throw new Error("Fixture did not launch");
if (socketState === "not-listening")
await promisify(execFile)(process.execPath, [
"-e",
'require("node:net").createServer().listen(process.argv[1], () => process.exit(0))',
session.socketPath,
]);
const closing = client.close();
// Publish after close has encountered an unavailable endpoint, within its
// cleanup window rather than before the caller requests cleanup.
await delay(150);
await rm(session.socketPath, { force: true });
await fixture.launch(session);
const closed = await closing;
if (!closed.ok) throw closed.error;
expect(fixture.requests.map(({ method }) => method)).toEqual([
"health",
"shutdown_document",
]);
await waitFor(() => expect(fixture.processes[0]?.exitCode).toBe(0));
await expect(access(session.directory)).rejects.toMatchObject({
code: "ENOENT",
});
},
);
it.each(["wrong-run", "wrong-token"] as const)(
"never requests document shutdown after the first handshake rejects %s",
async (identity) => {
const { client, launcher } = setup(identity);
const started = await client.start();
if (started.ok) throw new Error("Expected a rejected handshake");
expect(projectAnalysisError(started.error)).toMatchObject({
code: "cleanup_incomplete",
});
await launcher.fixture.waitForRequest("health");
expect(launcher.fixture.requests.map(({ method }) => method)).toEqual([
"health",
]);
expect(client.operationHealth()).toMatchObject({
state: "unknown",
stage: "launch",
});
const closed = await client.close();
if (closed.ok)
throw new Error("Expected retained foreign bridge ownership");
expect(projectAnalysisError(closed.error)).toMatchObject({
code: "cleanup_incomplete",
});
expect(
launcher.fixture.requests.every(({ method }) => method === "health"),
).toBe(true);
expect(launcher.fixture.processes[0]?.exitCode).toBeNull();
const session = launcher.sessions[0];
if (session === undefined) throw new Error("Fixture did not launch");
await access(session.directory);
},
);
it.each([false, true])(
"reconnects for authenticated cleanup after a previously valid bridge transport fails (seed refused after start: %s)",
async (refuseSeed) => {
// Cleanup uses the ceilings admitted at start, so a seed the runtime view
// refuses once its override is reset cannot block reauthentication.
let seedRefused = false;
const { client, launcher } = setup(undefined, undefined, undefined, {
get maximumBytes(): number {
if (seedRefused)
throw new ConfigurationError("invalid reply ceiling seed");
return 4 * 1024 * 1024;
},
source: "runtime",
});
const started = await client.start();
if (!started.ok) throw started.error;
const malformed = await client.callTool("malformed");
expect(malformed).toMatchObject({
ok: false,
error: { _tag: "HopperProtocolError" },
});
seedRefused = refuseSeed;
const closed = await client.close();
if (!closed.ok) throw closed.error;
expect(launcher.fixture.requests.map(({ method }) => method)).toEqual([
"health",
"malformed",
"health",
"shutdown_document",
]);
await waitFor(() =>
expect(launcher.fixture.processes[0]?.exitCode).toBe(0),
);
const session = launcher.sessions[0];
if (session === undefined) throw new Error("Fixture did not launch");
await expect(access(session.directory)).rejects.toMatchObject({
code: "ENOENT",
});
},
);
it("preserves launcher diagnostics after a health deadline and reauthenticates for cleanup", async () => {
const { client, launcher } = setup("matching", "gated");
const starting = client.start();
const first = await launcher.fixture.waitForRequest("health");
const started = await starting;
if (started.ok) throw new Error("Expected a health deadline");
expect(projectAnalysisError(started.error)).toMatchObject({
code: "cleanup_incomplete",
details: {
diagnostics: {
primary_error: {
code: "provider_timeout",
details: {
timeout_ms: 2_000,
stage: "startup",
launcher: { exit_code: 0, output_closed: true },
},
},
},
},
});
expect(client.requestActivity()).toBeNull();
const closing = client.close();
const next = await waitFor(() => {
const request = launcher.fixture.requests.find(
({ method, id }) => method === "health" && id !== first.id,
);
if (request === undefined)
throw new Error("Waiting for recovery handshake");
return request;
});
await launcher.fixture.release(next);
const closed = await closing;
if (!closed.ok) throw closed.error;
expect(launcher.fixture.requests.map(({ method }) => method)).toEqual([
"health",
"health",
"shutdown_document",
]);
});
it("recovers an application exit after the first valid handshake occurs during cleanup", async () => {
const { client, launcher } = setup("matching", "gated", "exit-without-ack");
const finishClose = async (
closed: Awaited<ReturnType<typeof client.close>>,
index: number,
) => {
if (!closed.ok) {
expect(projectAnalysisError(closed.error)).toMatchObject({
code: "cleanup_incomplete",
details: {
resources: expect.arrayContaining(["hopper-document"]),
diagnostics: {
authenticated_application: "readable",
},
},
});
const application = launcher.fixture.processes[index];
if (application === undefined) throw new Error("Fixture did not launch");
await waitFor(() => expect(application.exitCode).toBe(0));
closed = await client.close();
}
expect(closed.ok ? null : projectAnalysisError(closed.error)).toBeNull();
};
const starting = client.start();
const first = await launcher.fixture.waitForRequest("health");
const started = await starting;
if (started.ok) throw new Error("Expected the first handshake to time out");
expect(projectAnalysisError(started.error)).toMatchObject({
code: "cleanup_incomplete",
remediation: {
action: expect.stringContaining("restart the MCP connection"),
},
details: {
diagnostics: {
primary_error: { code: "provider_timeout" },
cleanup_error: {
details: {
diagnostics: { authenticated_application: "not_observed" },
},
},
},
},
});
const closing = client.close();
const next = await waitFor(() => {
const request = launcher.fixture.requests.find(
({ method, id }) => method === "health" && id !== first.id,
);
if (request === undefined)
throw new Error("Waiting for cleanup authentication");
return request;
});
await launcher.fixture.release(next);
const closed = await closing;
await finishClose(closed, 0);
expect(launcher.fixture.requests.map(({ method }) => method)).toEqual([
"health",
"health",
"shutdown_document",
]);
const session = launcher.sessions[0];
if (session === undefined) throw new Error("Fixture did not launch");
await expect(access(session.directory)).rejects.toMatchObject({
code: "ENOENT",
});
const restarted = client.start();
const health = await waitFor(() => {
const request = launcher.fixture.requests.find(
({ method, id }) => method === "health" && id > next.id,
);
if (request === undefined)
throw new Error("Waiting for restarted authentication");
return request;
});
await launcher.fixture.release(health);
const ready = await restarted;
if (!ready.ok) throw ready.error;
const observed = await client.callTool("current_document");
if (!observed.ok) throw observed.error;
expect(observed.value).toBe("fixture");
const reclosed = await client.close();
await finishClose(reclosed, 1);
});