fix(browser): preserve caller cancellation through CDP observations

This commit is contained in:
morluto committed 2026-10-19 14:00:01 +08:00
1 parent 9aca543f46
commit 7f4e7d5577
15 files changed
+678 -48

No files matched your search

+30
View File
@@ -1,5 +1,6 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import { delayWithCancellation } from "./CdpCaptureValues.js";
describe("cancellable browser observation delays", () => {
@@ -24,4 +25,33 @@ describe("cancellable browser observation delays", () => {
await waiting;
expect(completed).toBe(true);
});
it("preserves exact cancellation reasons before and during a capture wait", async () => {
const preAbortedReason = { _tag: "pre-aborted" };
const preAborted = new AbortController();
preAborted.abort(preAbortedReason);
const beforeStart = await delayWithCancellation(
1,
"observe_web_execution",
preAborted.signal,
).catch((error: unknown) => error);
expect(beforeStart).toBeInstanceOf(AnalysisCancelledError);
expect(beforeStart).toMatchObject({ cause: preAbortedReason });
vi.useFakeTimers();
const reason = new Error("capture wait cancelled");
const active = new AbortController();
const waiting = delayWithCancellation(
10_000,
"observe_web_execution",
active.signal,
).catch((error: unknown) => error);
active.abort(reason);
const duringWait = await waiting;
expect(duringWait).toBeInstanceOf(AnalysisCancelledError);
expect(duringWait).toMatchObject({ cause: reason });
expect(vi.getTimerCount()).toBe(0);
});
});
+5 -2
View File
@@ -125,7 +125,8 @@ export const delayWithCancellation = async (
const maximumTimerDelay = 2_147_483_647;
let remaining = durationMs;
while (remaining > 0) {
if (signal?.aborted === true) throw new AnalysisCancelledError(operation);
if (signal?.aborted === true)
throw new AnalysisCancelledError(operation, { cause: signal.reason });
const delay = Math.min(remaining, maximumTimerDelay);
await new Promise<void>((resolve, reject) => {
const timer = setTimeout(() => {
@@ -135,7 +136,9 @@ export const delayWithCancellation = async (
const onAbort = (): void => {
clearTimeout(timer);
signal?.removeEventListener("abort", onAbort);
reject(new AnalysisCancelledError(operation));
reject(
new AnalysisCancelledError(operation, { cause: signal?.reason }),
);
};
signal?.addEventListener("abort", onAbort, { once: true });
if (signal?.aborted === true) onAbort();
+15 -9
View File
@@ -66,7 +66,8 @@ export class CdpConnection {
limits?: { readonly maxPayloadBytes: number },
onConnected?: (connection: CdpConnection) => void,
): Promise<CdpConnection> {
if (signal?.aborted === true) throw new AnalysisCancelledError(operation);
if (signal?.aborted === true)
throw new AnalysisCancelledError(operation, { cause: signal.reason });
const maxPayloadBytes =
limits === undefined
? WEB_RUNTIME_LIMITS.protocolBytes
@@ -152,7 +153,9 @@ export class CdpConnection {
if (this.#closed || this.socket.readyState !== WebSocket.OPEN)
throw this.#transportError(this.#transportFailure);
if (signal?.aborted === true)
throw new AnalysisCancelledError(this.operation);
throw new AnalysisCancelledError(this.operation, {
cause: signal.reason,
});
const id = this.#nextId;
this.#nextId += 1;
const message = JSON.stringify({
@@ -166,7 +169,11 @@ export class CdpConnection {
const pending = this.#pending.get(id);
if (pending === undefined) return;
this.#complete(id, pending);
reject(new AnalysisCancelledError(this.operation));
reject(
new AnalysisCancelledError(this.operation, {
cause: signal?.reason,
}),
);
};
const timer = setTimeout(() => {
const pending = this.#pending.get(id);
@@ -446,11 +453,9 @@ const waitForOpen = async (
const onFailure = (cause: unknown): void => {
cleanup();
reject(
signal?.aborted === true
? new AnalysisCancelledError(operation)
: new BrowserObservationError(operation, "endpoint_unreachable", {
cause,
}),
new BrowserObservationError(operation, "endpoint_unreachable", {
cause,
}),
);
};
const onClose = (code: number, reason: Buffer): void => {
@@ -461,8 +466,9 @@ const waitForOpen = async (
);
};
const onAbort = (): void => {
cleanup();
terminateSocket(socket);
onFailure(new AnalysisCancelledError(operation));
reject(new AnalysisCancelledError(operation, { cause: signal?.reason }));
};
const cleanup = (): void => {
clearTimeout(timer);
+223
View File
@@ -0,0 +1,223 @@
import { createServer, type RequestListener, type Server } from "node:http";
import { once } from "node:events";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import { BrowserObservationError } from "../domain/browserObservationError.js";
import { afterEach, describe, expect, it } from "vitest";
import {
discoverCdpEndpoint,
readCdpJson,
withCdpDiscoveryDeadline,
} from "./CdpEndpoint.js";
const servers: Server[] = [];
const listen = async (
handler: RequestListener,
): Promise<{ readonly server: Server; readonly endpoint: string }> => {
const server = createServer(handler);
servers.push(server);
server.listen(0, "127.0.0.1");
await once(server, "listening");
const address = server.address();
if (address === null || typeof address === "string")
throw new Error("Expected a TCP listener address.");
return {
server,
endpoint: `http://127.0.0.1:${String(address.port)}`,
};
};
afterEach(async () => {
await Promise.all(
servers.splice(0).map(async (server) => {
server.closeAllConnections();
if (server.listening) {
server.close();
await once(server, "close");
}
}),
);
});
describe("CDP discovery cancellation ownership", () => {
it("preserves the exact reason for a pre-aborted discovery request", async () => {
let requests = 0;
const { endpoint } = await listen((_request, response) => {
requests += 1;
response.end("{}");
});
const reason = { _tag: "caller-stop" };
const controller = new AbortController();
controller.abort(reason);
const failure = await readCdpJson(
new URL("/json/version", endpoint),
"inspect_web_page",
controller.signal,
).catch((error: unknown) => error);
expect(failure).toBeInstanceOf(AnalysisCancelledError);
expect(failure).toMatchObject({ cause: reason });
expect(requests).toBe(0);
});
it("cancels an in-flight discovery at the HTTP producer with the original reason", async () => {
let requestedPath: string | undefined;
let requestSeen!: () => void;
const seen = new Promise<void>((resolve) => {
requestSeen = resolve;
});
const { endpoint } = await listen((request) => {
requestedPath = request.url;
requestSeen();
});
const reason = new Error("operator stopped discovery");
const controller = new AbortController();
const discovery = discoverCdpEndpoint(
endpoint,
"inspect_web_page",
controller.signal,
).catch((error: unknown) => error);
await seen;
controller.abort(reason);
const failure = await discovery;
expect(requestedPath).toBe("/json/version");
expect(failure).toBeInstanceOf(AnalysisCancelledError);
expect(failure).toMatchObject({ cause: reason });
});
it("does not replace a primary discovery failure when cancellation arrives later", async () => {
const primary = new BrowserObservationError(
"inspect_web_page",
"protocol_error",
);
const controller = new AbortController();
const failure = await withCdpDiscoveryDeadline(
"inspect_web_page",
controller.signal,
async () => {
throw primary;
},
100,
).catch((error: unknown) => error);
controller.abort(new Error("late caller cancellation"));
expect(failure).toBe(primary);
});
it("does not replace a plain physical failure rejected before a late abort", async () => {
const primary = new Error("socket failed before cancellation");
const controller = new AbortController();
const pending = withCdpDiscoveryDeadline(
"inspect_web_page",
controller.signal,
() => Promise.reject(primary),
100,
).catch((error: unknown) => error);
controller.abort(new Error("later caller cancellation"));
const failure = await pending;
expect(failure).toBe(primary);
});
it("classifies its own discovery deadline as timeout", async () => {
const failure = await withCdpDiscoveryDeadline(
"inspect_web_page",
undefined,
(signal) =>
new Promise((_resolve, reject) => {
signal.addEventListener("abort", () => reject(signal.reason), {
once: true,
});
}),
1,
).catch((error: unknown) => error);
expect(failure).toBeInstanceOf(BrowserObservationError);
expect(failure).toMatchObject({ reason: "timeout" });
});
it("normalizes a typed cancellation caused by its own deadline to timeout", async () => {
const failure = await withCdpDiscoveryDeadline(
"inspect_web_page",
undefined,
(signal) =>
new Promise((_resolve, reject) => {
signal.addEventListener(
"abort",
() =>
reject(
new AnalysisCancelledError("inspect_web_page", {
cause: signal.reason,
}),
),
{ once: true },
);
}),
1,
).catch((error: unknown) => error);
expect(failure).toBeInstanceOf(BrowserObservationError);
expect(failure).toMatchObject({ reason: "timeout" });
});
it("treats the caller's AnalysisError abort reason as cancellation when caller wins first", async () => {
const reason = new BrowserObservationError(
"inspect_web_page",
"protocol_error",
);
const controller = new AbortController();
const failure = await withCdpDiscoveryDeadline(
"inspect_web_page",
controller.signal,
async () => {
controller.abort(reason);
throw reason;
},
0,
).catch((error: unknown) => error);
expect(failure).toBeInstanceOf(AnalysisCancelledError);
expect(failure).toMatchObject({ cause: reason });
});
it("keeps a deadline rejection when the caller aborts only after timeout", async () => {
const controller = new AbortController();
const failure = await withCdpDiscoveryDeadline(
"inspect_web_page",
controller.signal,
(signal) =>
new Promise((_resolve, reject) => {
signal.addEventListener("abort", () => reject(signal.reason), {
once: true,
});
}),
0,
).catch((error: unknown) => error);
controller.abort(new Error("caller stopped after timeout"));
expect(failure).toBeInstanceOf(BrowserObservationError);
expect(failure).toMatchObject({ reason: "timeout" });
});
});
it("preserves an independent typed cancellation when the discovery deadline also expires", async () => {
const primary = new AnalysisCancelledError("inspect_web_page", {
cause: "independent cancellation",
});
const failure = await withCdpDiscoveryDeadline(
"inspect_web_page",
undefined,
(signal) =>
new Promise((_resolve, reject) => {
signal.addEventListener("abort", () => reject(primary), { once: true });
}),
1,
).catch((cause: unknown) => cause);
expect(failure).toBe(primary);
});
+43 -13
View File
@@ -157,21 +157,50 @@ export const withCdpDiscoveryDeadline = async <T>(
timeoutMs: number = CDP_DISCOVERY_RESPONSE_LIMITS.timeoutMs,
): Promise<T> => {
const deadline = new AbortController();
const timer = setTimeout(() => deadline.abort(), timeoutMs);
let abortSource: "caller" | "deadline" | undefined;
let abortReason: unknown;
const abort = (source: "caller" | "deadline", reason: unknown): void => {
if (abortSource !== undefined) return;
abortSource = source;
abortReason = reason;
deadline.abort(reason);
};
const onCallerAbort = (): void => {
if (signal?.aborted === true) abort("caller", signal.reason);
};
const timer = setTimeout(
() => abort("deadline", new Error("CDP discovery deadline exceeded")),
timeoutMs,
);
signal?.addEventListener("abort", onCallerAbort, { once: true });
onCallerAbort();
try {
return await work(
signal === undefined
? deadline.signal
: AbortSignal.any([signal, deadline.signal]),
);
return await work(deadline.signal);
} catch (cause: unknown) {
if (deadline.signal.aborted && signal?.aborted !== true)
throw new BrowserObservationError(operation, "timeout", {
detail: `CDP browser-socket discovery exceeded its ${String(timeoutMs)} ms deadline.`,
});
if (cause === abortReason) {
if (abortSource === "caller")
throw new AnalysisCancelledError(operation, { cause: abortReason });
if (abortSource === "deadline")
throw new BrowserObservationError(operation, "timeout", {
detail: `CDP browser-socket discovery exceeded its ${String(timeoutMs)} ms deadline.`,
});
}
// A concrete failure produced before cancellation remains authoritative.
if (cause instanceof AnalysisError) {
if (
abortSource === "deadline" &&
cause instanceof AnalysisCancelledError &&
cause.cause === abortReason
)
throw new BrowserObservationError(operation, "timeout", {
detail: `CDP browser-socket discovery exceeded its ${String(timeoutMs)} ms deadline.`,
});
throw cause;
}
throw cause;
} finally {
clearTimeout(timer);
signal?.removeEventListener("abort", onCallerAbort);
}
};
@@ -409,7 +438,7 @@ export const readCdpJson = async (
): Promise<unknown> =>
await new Promise((resolve, reject) => {
if (signal?.aborted === true) {
reject(new AnalysisCancelledError(operation));
reject(new AnalysisCancelledError(operation, { cause: signal.reason }));
return;
}
let response: IncomingMessage | undefined;
@@ -431,7 +460,7 @@ export const readCdpJson = async (
};
const onAbort = (): void => {
if (signal?.aborted === true)
finish(new AnalysisCancelledError(operation));
finish(new AnalysisCancelledError(operation, { cause: signal.reason }));
};
request_ = request(
url,
@@ -523,7 +552,8 @@ const endpointFailure = (
signal?: AbortSignal,
): AnalysisError => {
if (cause instanceof AnalysisError) return cause;
if (signal?.aborted === true) return new AnalysisCancelledError(operation);
if (signal?.aborted === true)
return new AnalysisCancelledError(operation, { cause: signal.reason });
return new BrowserObservationError(operation, "endpoint_unreachable", {
cause,
});
+6 -1
View File
@@ -370,8 +370,13 @@ const waitForWindow = async (
if (settled) return;
settled = true;
clearTimeout(timer);
signal?.removeEventListener("abort", onAbort);
removeEnd();
reject(new AnalysisCancelledError("observe_web_session"));
reject(
new AnalysisCancelledError("observe_web_session", {
cause: signal?.reason,
}),
);
};
const timer = setTimeout(() => finish("window_elapsed"), durationMs);
removeEnd = capture.onEnd(finish);
+3 -1
View File
@@ -53,7 +53,9 @@ export const captureWebExecution = async (
const reason = await waiting;
session.beginCompletion();
if (session.options.signal?.aborted)
throw new AnalysisCancelledError(session.operation);
throw new AnalysisCancelledError(session.operation, {
cause: session.options.signal.reason,
});
sources.check();
requests.check();
let raw: unknown;
@@ -10,6 +10,7 @@ it("settles an already lost transport without arming a timer that cannot resolve
window.end("target_terminated");
await expect(window.start(30_000)).resolves.toBe("target_terminated");
expect(window.active).toBe(false);
expect(window.armedAt).toBeUndefined();
});
it("ends the actual armed window at its selected duration and disposes its timer", async () => {
@@ -41,11 +42,20 @@ it("settles caller cancellation and removes its local timer", async () => {
options: { signal: controller.signal },
});
try {
const assertion = expect(window.start(30_000)).rejects.toMatchObject({
const reason = new Error("operator stopped the armed window");
const result = window.start(30_000).catch((error: unknown) => error);
controller.abort(reason);
const failure = await result;
expect(failure).toMatchObject({
_tag: "AnalysisCancelledError",
cause: reason,
});
controller.abort();
await assertion;
expect(() => window.check()).toThrow(failure as Error);
const endedAt = window.endedAt;
window.end("target_terminated");
expect(window.reason).toBeUndefined();
expect(window.endedAt).toBe(endedAt);
await expect(window.start(30_000)).rejects.toBe(failure);
expect(window.active).toBe(false);
expect(vi.getTimerCount()).toBe(0);
} finally {
+6 -4
View File
@@ -63,18 +63,20 @@ export class CdpExecutionWindow {
/** The timer starts at arming, before progress delivery can delay the external action. */
start(duration: number): Promise<EndReason> {
this.armedAt = new Date().toISOString();
if (this.#failure !== undefined) return Promise.reject(this.#failure);
if (this.reason !== undefined) return Promise.resolve(this.reason);
this.armedAt = new Date().toISOString();
return new Promise((resolve, reject) => {
this.#resolve = resolve;
this.#reject = reject;
this.#timer = setTimeout(() => this.end("window_elapsed"), duration);
const signal = this.session.options.signal;
const abort = (): void => {
this.endedAt = new Date().toISOString();
this.dispose();
this.#reject?.(new AnalysisCancelledError(this.session.operation));
this.fail(
new AnalysisCancelledError(this.session.operation, {
cause: signal?.reason,
}),
);
};
this.#removeAbort = () => signal?.removeEventListener("abort", abort);
signal?.addEventListener("abort", abort, { once: true });