Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(hopper): enforce caller-supplied request deadlines (#1119)

vilmerfroste8939ca2208b
diff --git a/docs/testing.md b/docs/testing.md
index d63f49a12..70fadaac3 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -221,6 +221,15 @@ decompilation, reference and search operations. A literal `--help` trace query p
that selector data is preserved independently of global CLI flags.
Unmapped annotation destinations and
oversized later batch names fail before any earlier edit is applied.
+
+`verify:hopper:deadlines` checks the native client's optional request deadlines
+on macOS with an owned source-built fixture. Zero and elapsed deadlines must
+leave native comments unchanged, including when a synchronous progress observer
+delays timer dispatch. It also observes a short analysis deadline and verifies
+subsequent wire recovery and clean shutdown. Caller timeout does not interrupt
+Hopper's synchronous native operation. Socket boundary tests deterministically
+cover active and queued expiry, late replies and timer cleanup.
+
The Linux demo lane remains a separate `verify:hopper:linux` command.
`verify:hopper:fat` is a separate macOS lane requiring installed Hopper and the
diff --git a/package.json b/package.json
index 9276c2e14..68d6b5bb7 100644
--- a/package.json
+++ b/package.json
@@ -138,6 +138,7 @@
"typecheck": "tsc --noEmit",
"verify:test-temp-hygiene": "npm run build:cached && node scripts/verify-test-temp-hygiene.mjs",
"verify:hopper": "npm run verify:fixtures && npm run build:cached && node scripts/verify-real-hopper.mjs",
+ "verify:hopper:deadlines": "npm run verify:fixtures && npm run build:cached && node scripts/verify-real-hopper-deadlines.mjs",
"verify:hopper:fat": "npm run build:cached && node scripts/verify-real-hopper-fat.mjs",
"verify:hopper:fat64": "npm run build:cached && node scripts/verify-real-hopper-fat.mjs --fat64",
"verify:apple-dispatch": "npm run build:cached && node scripts/verify/apple/dispatch.mjs",
diff --git a/scripts/verify-real-hopper-deadlines.mjs b/scripts/verify-real-hopper-deadlines.mjs
new file mode 100644
index 000000000..4382b4174
--- /dev/null
+++ b/scripts/verify-real-hopper-deadlines.mjs
@@ -0,0 +1,126 @@
+import assert from "node:assert/strict";
+import { copyFile, mkdtemp, realpath, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { firstProcedureAddress } from "../dist/application/RealHopperAssertions.js";
+import { parseBinaryTarget } from "../dist/application/BinaryTargetResolver.js";
+import { resolveHopperAnalysisProfile } from "../dist/hopper/HopperAnalysisProfile.js";
+import { HopperApplicationLauncher } from "../dist/hopper/BridgeLauncher.js";
+import { HopperClient } from "../dist/hopper/HopperClient.js";
+import { HOPPER_PROVIDER_IDENTITY } from "../dist/hopper/HopperProvider.js";
+import { loadRealHopperFixtureTargets } from "./lib/real-hopper-fixture.mjs";
+
+// These options belong to the native client, below the CLI/MCP tool surface.
+assert.equal(
+ process.platform,
+ "darwin",
+ "This lane requires native macOS Hopper",
+);
+const fixtures = await loadRealHopperFixtureTargets(
+ process.env.REA_HOPPER_CONFORMANCE_MANIFEST_PATH ??
+ "build/conformance/manifest.json",
+);
+const root = await realpath(
+ await mkdtemp(join(tmpdir(), "rea-hopper-deadlines-")),
+);
+const target = join(root, "deadline-fixture");
+let client;
+try {
+ await copyFile(fixtures.primary.path, target);
+ const parsed = await parseBinaryTarget(target);
+ if (!parsed.ok) throw parsed.error;
+ const launcherPath =
+ process.env.HOPPER_LAUNCHER_PATH ??
+ "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
+ const resolved = await resolveHopperAnalysisProfile(parsed.value, {
+ launcherPath,
+ loaderArgsOverride: [],
+ provider: HOPPER_PROVIDER_IDENTITY,
+ });
+ if (!resolved.ok) throw resolved.error;
+ const image = resolved.value.profile?.parameters.prepared_image;
+ client = new HopperClient({
+ launcher: new HopperApplicationLauncher({
+ launcherPath,
+ targetPath: target,
+ targetKind: "executable",
+ launchMode: "native",
+ loaderArgs: resolved.value.compatibility.loaderArgs,
+ ...(image === undefined
+ ? {}
+ : {
+ preparedImage: { image, sourceSha256: parsed.value.sha256 },
+ }),
+ bridgeScriptPath: fileURLToPath(
+ new URL("../bridge/hopper_bridge.py", import.meta.url),
+ ),
+ }),
+ });
+ const call = async (name, args = {}) => {
+ const result = await client.callTool(name, args);
+ if (!result.ok) throw result.error;
+ return result.value;
+ };
+ const procedures = await call("list_procedures");
+ const address = firstProcedureAddress(procedures);
+ const original = await call("comment", { address });
+ for (const timeoutMs of [0, 10]) {
+ const result = await client.callTool(
+ "set_comment",
+ { address, comment: "expired mutation must never reach Hopper" },
+ {
+ timeoutMs,
+ ...(timeoutMs === 0
+ ? {}
+ : {
+ progress: {
+ report: () => {
+ const started = performance.now();
+ while (performance.now() - started < 30) {
+ // Delay the timer callback beyond the admitted deadline.
+ }
+ return Promise.resolve();
+ },
+ },
+ }),
+ },
+ );
+ assert.equal(result.ok, false);
+ assert.equal(result.error._tag, "HopperTimeoutError");
+ assert.equal(result.error.providerState, "not_started");
+ assert.equal(await call("comment", { address }), original);
+ assert.equal(client.requestActivity(), null);
+ }
+ const active = await client.callTool(
+ "analyze_function",
+ { procedure: address },
+ { timeoutMs: 1 },
+ );
+ if (!active.ok) assert.equal(active.error._tag, "HopperTimeoutError");
+ const activityAfterDeadline = client.requestActivity();
+ await call("health");
+ assert.equal(client.requestActivity(), null);
+ const closed = await client.closeWithOutcome();
+ if (!closed.ok) throw closed.error;
+ console.log(
+ JSON.stringify(
+ {
+ expiredNativeMutations: "not_applied",
+ delayedProgress: "deadline_enforced",
+ activeAnalysis: active.ok
+ ? "completed_within_deadline"
+ : "caller_timed_out",
+ nativeWorkRetained: activityAfterDeadline !== null,
+ lateReplyRecovery: "passed",
+ cleanShutdown: true,
+ },
+ null,
+ 2,
+ ),
+ );
+} finally {
+ if (client !== undefined) await client.close();
+ await rm(root, { recursive: true, force: true });
+}
diff --git a/src/hopper/HopperClient.ts b/src/hopper/HopperClient.ts
index 20430c16e..29edb484b 100644
--- a/src/hopper/HopperClient.ts
+++ b/src/hopper/HopperClient.ts
@@ -405,6 +405,8 @@ export class HopperClient {
arguments_: Readonly<Record<string, JsonValue>> = {},
options: {
readonly signal?: AbortSignal;
+ /** Deadline after startup, including waiting for Hopper's serial bridge. */
+ readonly timeoutMs?: number;
readonly progress?: ProgressReporter;
} = {},
): Promise<Result<JsonValue, AnalysisError>> {
@@ -638,6 +640,9 @@ export class HopperClient {
const startedAt = performance.now();
const result = await this.#requests.run(id, method, params, {
...(options.signal === undefined ? {} : { signal: options.signal }),
+ ...(options.timeoutMs === undefined
+ ? {}
+ : { timeoutMs: options.timeoutMs }),
...(options.progress !== undefined ? { progress: options.progress } : {}),
});
this.#retainRequestHealth(result, id, method);
diff --git a/src/hopper/HopperRequestQueue.test.ts b/src/hopper/HopperRequestQueue.test.ts
new file mode 100644
index 000000000..183d67bae
--- /dev/null
+++ b/src/hopper/HopperRequestQueue.test.ts
@@ -0,0 +1,300 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+ HopperCancelledError,
+ HopperProtocolError,
+} from "../domain/hopperErrors.js";
+import { ok } from "../domain/result.js";
+import { HopperRequestQueue } from "./HopperRequestQueue.js";
+
+afterEach(() => {
+ vi.useRealTimers();
+ vi.restoreAllMocks();
+});
+
+describe("HopperRequestQueue deadlines", () => {
+ it("times out active callers while retaining the wire until the late reply", async () => {
+ vi.useFakeTimers();
+ const sent: number[] = [];
+ const queue = new HopperRequestQueue(({ id }) => sent.push(id));
+ const result = vi.fn();
+ const pending = queue
+ .run(1, "analyze_function", {}, { timeoutMs: 25 })
+ .then(result);
+ const next = queue.run(2, "echo", {}, {});
+ await vi.advanceTimersByTimeAsync(25);
+ expect(result).toHaveBeenCalledWith({
+ ok: false,
+ error: expect.objectContaining({
+ _tag: "HopperTimeoutError",
+ timeoutMs: 25,
+ operation: "analyze_function",
+ requestId: 1,
+ providerState: "busy",
+ }),
+ });
+ expect(sent).toEqual([1]);
+ expect(queue.activity()).toMatchObject({
+ callerState: "cancelled",
+ queuedRequests: 1,
+ });
+ expect(vi.getTimerCount()).toBe(0);
+ expect(queue.accept(1, ok("late"))).toBe(true);
+ expect(sent).toEqual([1, 2]);
+ queue.accept(2, ok("next"));
+ await pending;
+ await expect(next).resolves.toEqual(ok("next"));
+ expect(result).toHaveBeenCalledTimes(1);
+ expect(queue.activity()).toBeNull();
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it("expires a queued request without transmitting it", async () => {
+ vi.useFakeTimers();
+ const sent: number[] = [];
+ const queue = new HopperRequestQueue(({ id }) => sent.push(id));
+ const active = queue.run(1, "active", {}, {});
+ const settled = vi.fn();
+ const queued = queue.run(2, "queued", {}, { timeoutMs: 10 }).then(settled);
+ await vi.advanceTimersByTimeAsync(10);
+ expect(settled).toHaveBeenCalledWith(
+ expect.objectContaining({
+ ok: false,
+ error: expect.objectContaining({
+ _tag: "HopperTimeoutError",
+ requestId: 2,
+ providerState: "not_started",
+ }),
+ }),
+ );
+ expect(queue.hasQueued(2)).toBe(false);
+ queue.accept(1, ok(null));
+ await Promise.all([active, queued]);
+ expect(sent).toEqual([1]);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it("cleans deadline and abort observers on success before the deadline", async () => {
+ vi.useFakeTimers();
+ const queue = new HopperRequestQueue(() => {});
+ const controller = new AbortController();
+ const remove = vi.spyOn(controller.signal, "removeEventListener");
+ const settled = vi.fn();
+ const pending = queue
+ .run(1, "echo", {}, { timeoutMs: 25, signal: controller.signal })
+ .then(settled);
+ queue.accept(1, ok(42));
+ controller.abort();
+ await vi.advanceTimersByTimeAsync(100);
+ await pending;
+ expect(settled).toHaveBeenCalledExactlyOnceWith(ok(42));
+ expect(remove).toHaveBeenCalledWith("abort", expect.any(Function));
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it("keeps explicit cancellation distinct from a later timeout", async () => {
+ vi.useFakeTimers();
+ const queue = new HopperRequestQueue(() => {});
+ const controller = new AbortController();
+ const pending = queue.run(
+ 1,
+ "echo",
+ {},
+ { timeoutMs: 25, signal: controller.signal },
+ );
+ controller.abort();
+ await expect(pending).resolves.toEqual({
+ ok: false,
+ error: new HopperCancelledError(),
+ });
+ expect(vi.getTimerCount()).toBe(0);
+ queue.accept(1, ok(null));
+ await vi.advanceTimersByTimeAsync(100);
+ expect(queue.activity()).toBeNull();
+ });
+
+ it("does not recreate timers when a progress observer cancels synchronously", async () => {
+ vi.useFakeTimers();
+ const send = vi.fn();
+ const queue = new HopperRequestQueue(send);
+ const controller = new AbortController();
+ const pending = queue.run(
+ 1,
+ "echo",
+ {},
+ {
+ timeoutMs: 100,
+ signal: controller.signal,
+ progress: {
+ report: () => {
+ controller.abort();
+ return Promise.resolve();
+ },
+ },
+ },
+ );
+ await expect(pending).resolves.toMatchObject({
+ ok: false,
+ error: { _tag: "HopperCancelledError" },
+ });
+ expect(vi.getTimerCount()).toBe(0);
+ expect(send).not.toHaveBeenCalled();
+ expect(queue.activity()).toBeNull();
+ const next = queue.run(2, "next", {}, {});
+ expect(send).toHaveBeenCalledExactlyOnceWith(
+ { id: 2, method: "next", params: {} },
+ expect.any(Function),
+ );
+ queue.accept(2, ok(null));
+ await next;
+ });
+
+ it("cleans all deadlines on teardown, including after an active timeout", async () => {
+ vi.useFakeTimers();
+ const queue = new HopperRequestQueue(() => {});
+ const result = vi.fn();
+ const active = queue.run(1, "active", {}, { timeoutMs: 10 }).then(result);
+ const queued = queue.run(2, "queued", {}, { timeoutMs: 100 });
+ await vi.advanceTimersByTimeAsync(10);
+ const failure = new HopperProtocolError("closed");
+ queue.failAll(failure);
+ await active;
+ await expect(queued).resolves.toEqual({ ok: false, error: failure });
+ expect(result).toHaveBeenCalledTimes(1);
+ expect(queue.activity()).toBeNull();
+ expect(queue.queuedCount()).toBe(0);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+});
+
+describe("HopperRequestQueue deadline admission and races", () => {
+ it("removes queued cancelled work and honours cancellation before admission", async () => {
+ vi.useFakeTimers();
+ const sent: number[] = [];
+ const queue = new HopperRequestQueue(({ id }) => sent.push(id));
+ const active = queue.run(1, "active", {}, {});
+ const controller = new AbortController();
+ const queued = queue.run(
+ 2,
+ "queued",
+ {},
+ { timeoutMs: 100, signal: controller.signal },
+ );
+ controller.abort();
+ await expect(queued).resolves.toMatchObject({
+ ok: false,
+ error: { _tag: "HopperCancelledError" },
+ });
+ await expect(
+ queue.run(
+ 3,
+ "pre-aborted",
+ {},
+ { timeoutMs: 100, signal: controller.signal },
+ ),
+ ).resolves.toMatchObject({
+ ok: false,
+ error: { _tag: "HopperCancelledError" },
+ });
+ expect(queue.queuedCount()).toBe(0);
+ queue.accept(1, ok(null));
+ await active;
+ expect(sent).toEqual([1]);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it.each([NaN, Infinity, -1, 0.5, 2_147_483_648])(
+ "rejects invalid deadline %s without sending",
+ async (timeoutMs) => {
+ vi.useFakeTimers();
+ const send = vi.fn();
+ const queue = new HopperRequestQueue(send);
+ await expect(
+ queue.run(1, "echo", {}, { timeoutMs }),
+ ).resolves.toMatchObject({
+ ok: false,
+ error: { _tag: "HopperProtocolError" },
+ });
+ expect(send).not.toHaveBeenCalled();
+ expect(vi.getTimerCount()).toBe(0);
+ },
+ );
+
+ it("expires zero deadlines without sending and settles only once if aborted afterward", async () => {
+ vi.useFakeTimers();
+ const send = vi.fn();
+ const queue = new HopperRequestQueue(send);
+ await expect(
+ queue.run(1, "echo", {}, { timeoutMs: 0 }),
+ ).resolves.toMatchObject({
+ ok: false,
+ error: {
+ _tag: "HopperTimeoutError",
+ timeoutMs: 0,
+ providerState: "not_started",
+ },
+ });
+ expect(send).not.toHaveBeenCalled();
+ const controller = new AbortController();
+ const settled = vi.fn();
+ const pending = queue
+ .run(2, "echo", {}, { timeoutMs: 10, signal: controller.signal })
+ .then(settled);
+ await vi.advanceTimersByTimeAsync(10);
+ controller.abort();
+ queue.accept(2, ok("late"));
+ await pending;
+ expect(settled).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({
+ ok: false,
+ error: expect.objectContaining({ _tag: "HopperTimeoutError" }),
+ }),
+ );
+ expect(vi.getTimerCount()).toBe(0);
+ });
+});
+
+describe("Hopper deadlines before timer dispatch", () => {
+ it("does not transmit overdue queued work when the event loop delays its timer", async () => {
+ vi.useFakeTimers();
+ const clock = vi.spyOn(performance, "now").mockReturnValue(0);
+ const sent: number[] = [];
+ const queue = new HopperRequestQueue(({ id }) => sent.push(id));
+ const active = queue.run(1, "active", {}, {});
+ const expired = queue.run(2, "set_comment", {}, { timeoutMs: 10 });
+ clock.mockReturnValue(20);
+ queue.accept(1, ok(null));
+ await expect(expired).resolves.toMatchObject({
+ ok: false,
+ error: {
+ _tag: "HopperTimeoutError",
+ operation: "set_comment",
+ providerState: "not_started",
+ },
+ });
+ await active;
+ expect(sent).toEqual([1]);
+ expect(queue.activity()).toBeNull();
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it("accepts an overdue active reply without turning elapsed timeout into success", async () => {
+ vi.useFakeTimers();
+ const clock = vi.spyOn(performance, "now").mockReturnValue(0);
+ const sent: number[] = [];
+ const queue = new HopperRequestQueue(({ id }) => sent.push(id));
+ const expired = queue.run(1, "active", {}, { timeoutMs: 10 });
+ const next = queue.run(2, "next", {}, {});
+ clock.mockReturnValue(20);
+ expect(queue.accept(1, ok("late"))).toBe(true);
+ await expect(expired).resolves.toMatchObject({
+ ok: false,
+ error: { _tag: "HopperTimeoutError" },
+ });
+ expect(sent).toEqual([1, 2]);
+ queue.accept(2, ok(null));
+ await next;
+ expect(queue.activity()).toBeNull();
+ expect(vi.getTimerCount()).toBe(0);
+ });
+});
diff --git a/src/hopper/HopperRequestQueue.ts b/src/hopper/HopperRequestQueue.ts
index 4cf2d7e00..6ae162e06 100644
--- a/src/hopper/HopperRequestQueue.ts
+++ b/src/hopper/HopperRequestQueue.ts
@@ -10,14 +10,20 @@ import {
HopperProcessError,
HopperProtocolError,
HopperRemoteError,
+ HopperTimeoutError,
} from "../domain/hopperErrors.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { err, type Result } from "../domain/result.js";
export type HopperRequestResult = Result<JsonValue, HopperError>;
+/** Node timer ceiling; larger deadlines would be clamped instead of honored. */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
export interface HopperRequestQueueOptions {
readonly signal?: AbortSignal;
+ /** Caller deadline from admission, including time waiting in the FIFO. */
+ readonly timeoutMs?: number;
readonly progress?: ProgressReporter;
}
@@ -48,8 +54,12 @@ interface QueuedRequest {
readonly onAbort: (() => void) | undefined;
callerState: "waiting" | "cancelled";
callerSettled: boolean;
+ transmitted: boolean;
startedAt: number | undefined;
heartbeat: NodeJS.Timeout | undefined;
+ deadline: NodeJS.Timeout | undefined;
+ readonly deadlineAt: number | undefined;
+ readonly timeoutMs: number | undefined;
}
/** FIFO that keeps the wire serialized until Hopper actually replies. */
@@ -59,7 +69,7 @@ export class HopperRequestQueue {
constructor(private readonly send: RequestSender) {}
- /** Queue one request until Hopper replies or the caller cancels it. */
+ /** Settle the caller on reply, cancellation, or deadline; retain active wire work. */
run(
id: number,
method: string,
@@ -68,6 +78,32 @@ export class HopperRequestQueue {
): Promise<HopperRequestResult> {
if (options.signal?.aborted === true)
return Promise.resolve(err(new HopperCancelledError()));
+ const timeoutMs = options.timeoutMs;
+ if (
+ timeoutMs !== undefined &&
+ (!Number.isInteger(timeoutMs) ||
+ timeoutMs < 0 ||
+ timeoutMs > MAX_TIMEOUT_MS)
+ )
+ return Promise.resolve(
+ err(
+ new HopperProtocolError(
+ `Hopper timeoutMs must be an integer between 0 and ${String(MAX_TIMEOUT_MS)}`,
+ ),
+ ),
+ );
+ if (timeoutMs === 0)
+ return Promise.resolve(
+ err(
+ new HopperTimeoutError(
+ 0,
+ method,
+ id,
+ "not_started",
+ hopperOperationStage(method),
+ ),
+ ),
+ );
return new Promise((resolve) => {
let entry: QueuedRequest;
const onAbort =
@@ -82,12 +118,22 @@ export class HopperRequestQueue {
onAbort,
callerState: "waiting",
callerSettled: false,
+ transmitted: false,
startedAt: undefined,
heartbeat: undefined,
+ deadline: undefined,
+ deadlineAt:
+ timeoutMs === undefined ? undefined : performance.now() + timeoutMs,
+ timeoutMs,
};
this.#queue.push(entry);
if (onAbort !== undefined)
options.signal?.addEventListener("abort", onAbort, { once: true });
+ if (timeoutMs !== undefined)
+ entry.deadline = setTimeout(
+ () => this.#cancel(entry, this.#timeoutError(entry, timeoutMs)),
+ timeoutMs,
+ );
if (this.#active !== undefined || this.#queue.length > 1)
this.#report(
entry,
@@ -101,6 +147,7 @@ export class HopperRequestQueue {
accept(id: number, result: HopperRequestResult): boolean {
const entry = this.#active;
if (entry === undefined || entry.id !== id) return false;
+ this.#expireIfElapsed(entry);
this.#releaseWire(entry);
if (!entry.callerSettled)
this.#settleCaller(
@@ -187,6 +234,10 @@ export class HopperRequestQueue {
if (this.#active !== undefined) return;
const entry = this.#queue.shift();
if (entry === undefined) return;
+ if (this.#expireIfElapsed(entry)) {
+ this.#drain();
+ return;
+ }
if (entry.signal?.aborted === true) {
this.#settleCaller(entry, err(new HopperCancelledError()), "cancelled");
this.#drain();
@@ -195,6 +246,17 @@ export class HopperRequestQueue {
this.#active = entry;
entry.startedAt = performance.now();
this.#report(entry, `${entry.method} started on Hopper's serial bridge`);
+ this.#expireIfElapsed(entry);
+ // A progress observer may cancel or tear down synchronously before send.
+ // No native work exists yet, so it is safe to release this reserved slot.
+ if (this.#active !== entry || entry.callerSettled) {
+ if (this.#active === entry) {
+ this.#active = undefined;
+ this.#releaseWire(entry);
+ this.#drain();
+ }
+ return;
+ }
entry.heartbeat = setInterval(() => {
if (entry.callerSettled || entry.startedAt === undefined) return;
const elapsed = Math.round(performance.now() - entry.startedAt);
@@ -204,6 +266,7 @@ export class HopperRequestQueue {
);
}, 1_000);
try {
+ entry.transmitted = true;
this.send(
{ id: entry.id, method: entry.method, params: entry.params },
() =>
@@ -229,16 +292,43 @@ export class HopperRequestQueue {
}
}
- #cancel(entry: QueuedRequest): void {
+ #timeoutError(entry: QueuedRequest, timeoutMs: number): HopperTimeoutError {
+ return new HopperTimeoutError(
+ timeoutMs,
+ entry.method,
+ entry.id,
+ entry.transmitted ? "busy" : "not_started",
+ hopperOperationStage(entry.method),
+ );
+ }
+
+ #expireIfElapsed(entry: QueuedRequest): boolean {
+ if (
+ entry.deadlineAt !== undefined &&
+ entry.timeoutMs !== undefined &&
+ performance.now() >= entry.deadlineAt
+ )
+ this.#settleCaller(
+ entry,
+ err(this.#timeoutError(entry, entry.timeoutMs)),
+ "cancelled",
+ );
+ return entry.callerSettled;
+ }
+
+ #cancel(
+ entry: QueuedRequest,
+ error: HopperError = new HopperCancelledError(),
+ ): void {
if (entry.callerSettled) return;
if (this.#active === entry) {
- this.#settleCaller(entry, err(new HopperCancelledError()), "cancelled");
+ this.#settleCaller(entry, err(error), "cancelled");
return;
}
const index = this.#queue.indexOf(entry);
if (index < 0) return;
this.#queue.splice(index, 1);
- this.#settleCaller(entry, err(new HopperCancelledError()), "cancelled");
+ this.#settleCaller(entry, err(error), "cancelled");
}
#settleCaller(
@@ -249,6 +339,8 @@ export class HopperRequestQueue {
if (entry.callerSettled) return;
entry.callerSettled = true;
entry.callerState = callerState;
+ if (entry.deadline !== undefined) clearTimeout(entry.deadline);
+ entry.deadline = undefined;
if (this.#active === entry && entry.heartbeat !== undefined) {
clearInterval(entry.heartbeat);
entry.heartbeat = undefined;
diff --git a/tests/boundary/providers/hopper/hopperClient.deadlines.test.ts b/tests/boundary/providers/hopper/hopperClient.deadlines.test.ts
new file mode 100644
index 000000000..0202cd077
--- /dev/null
+++ b/tests/boundary/providers/hopper/hopperClient.deadlines.test.ts
@@ -0,0 +1,151 @@
+import { describe, expect, it, vi } from "vitest";
+import { access } from "node:fs/promises";
+
+import {
+ HopperFixtureLauncher,
+ startHopperFixtureClient,
+} from "./hopperClient.fixture.js";
+
+describe("HopperClient request deadlines", () => {
+ it("propagates deadlines through the socket client and accepts late replies safely", async () => {
+ const launcher = new HopperFixtureLauncher();
+ const client = await startHopperFixtureClient(launcher);
+ const settled = vi.fn();
+ const pending = client
+ .callTool("echo", { gate: "deadline" }, { timeoutMs: 100 })
+ .then(settled);
+ const request = await launcher.waitForRequest("echo", "deadline");
+ try {
+ await vi.waitFor(
+ () =>
+ expect(settled).toHaveBeenCalledWith({
+ ok: false,
+ error: expect.objectContaining({
+ _tag: "HopperTimeoutError",
+ timeoutMs: 100,
+ operation: "echo",
+ }),
+ }),
+ { timeout: 1000 },
+ );
+ expect(client.requestActivity()).toMatchObject({
+ callerState: "cancelled",
+ operation: "echo",
+ });
+ } finally {
+ await launcher.release(request);
+ await pending;
+ }
+ await expect(
+ client.callTool("echo", { value: "alive" }, { timeoutMs: 1000 }),
+ ).resolves.toEqual({
+ ok: true,
+ value: { value: "alive" },
+ });
+ expect(settled).toHaveBeenCalledTimes(1);
+ expect(client.requestActivity()).toBeNull();
+ });
+
+ it("never transmits a request whose deadline expired in the FIFO", async () => {
+ const launcher = new HopperFixtureLauncher();
+ const client = await startHopperFixtureClient(launcher);
+ const active = client.callTool("echo", { gate: "hold-active" });
+ const request = await launcher.waitForRequest("echo", "hold-active");
+ try {
+ await expect(
+ client.callTool("echo", { value: "expired" }, { timeoutMs: 25 }),
+ ).resolves.toMatchObject({
+ ok: false,
+ error: { _tag: "HopperTimeoutError" },
+ });
+ expect(
+ launcher.requests.some(({ params }) => params?.value === "expired"),
+ ).toBe(false);
+ } finally {
+ await launcher.release(request);
+ await active;
+ }
+ await expect(client.callTool("echo", { value: "next" })).resolves.toEqual({
+ ok: true,
+ value: { value: "next" },
+ });
+ expect(
+ launcher.requests.some(({ params }) => params?.value === "expired"),
+ ).toBe(false);
+ });
+
+ it("closes and releases pending callers and private resources after an active timeout", async () => {
+ const launcher = new HopperFixtureLauncher();
+ const client = await startHopperFixtureClient(launcher);
+ const pending = client.callTool(
+ "echo",
+ { gate: "timeout-close" },
+ { timeoutMs: 100 },
+ );
+ await launcher.waitForRequest("echo", "timeout-close");
+ await expect(pending).resolves.toMatchObject({
+ ok: false,
+ error: { _tag: "HopperTimeoutError" },
+ });
+ const queued = client.callTool(
+ "echo",
+ { value: "queued" },
+ { timeoutMs: 1000 },
+ );
+ await vi.waitFor(() =>
+ expect(client.requestActivity()?.queuedRequests).toBe(1),
+ );
+ await client.close();
+ await expect(queued).resolves.toMatchObject({
+ ok: false,
+ error: { _tag: "HopperProcessError" },
+ });
+ expect(client.requestActivity()).toBeNull();
+ for (const directory of launcher.directories)
+ await expect(access(directory)).rejects.toBeDefined();
+ expect(
+ launcher.processes.every(
+ (child) => child.exitCode !== null || child.signalCode !== null,
+ ),
+ ).toBe(true);
+ });
+});
+
+it("does not send a mutation after its synchronous progress observer consumes the deadline", async () => {
+ const launcher = new HopperFixtureLauncher();
+ const client = await startHopperFixtureClient(launcher);
+ const result = await client.callTool(
+ "set_comment",
+ { comment: "must not reach the native boundary" },
+ {
+ timeoutMs: 10,
+ progress: {
+ report: () => {
+ const started = performance.now();
+ while (performance.now() - started < 30) {
+ // Exercise an observer delaying dispatch of the actual deadline timer.
+ }
+ return Promise.resolve();
+ },
+ },
+ },
+ );
+ expect(result).toMatchObject({
+ ok: false,
+ error: {
+ _tag: "HopperTimeoutError",
+ operation: "set_comment",
+ providerState: "not_started",
+ },
+ });
+ await expect(
+ client.callTool("echo", { value: "recovered" }),
+ ).resolves.toEqual({
+ ok: true,
+ value: { value: "recovered" },
+ });
+ expect(launcher.requests.some(({ method }) => method === "set_comment")).toBe(
+ false,
+ );
+ expect(client.requestActivity()).toBeNull();
+});