refactor(errors): require a reason for every analysis cancellation (#10566)

* refactor(errors): require a reason for every analysis cancellation

Add cancelledBy, the one constructor for AnalysisCancelledError. Its
reason argument is required: an aborted signal, an earlier cancellation,
a reason carried from an inner failure, or an OwnerCancellation when REA
closed the work's owner itself.

Closed adb, apktool, firmware, sqlite, gdb, web-bundle analyzer and
binary-session record owners now report OwnerCancellation.ownerClosed
instead of an absent reason. Firmware's predecessor wait returns its
cancellation as a Result, removing an unreachable reason-less fallback.

An architecture guard rejects new direct constructions, with a counted
per-file baseline that can only shrink.

* refactor(errors): share one aborted-signal predicate with cancelledBy

* refactor(process): return a departing caller's reason from a shared startup wait

* refactor(providers): build decompiler-provider cancellations with a required reason (#10587)

Migrate every AnalysisCancelledError construction under src/ghidra,
src/ida, src/cutter, src/jeb and src/kuna to cancelledBy and lower the
guard baseline from 671 to 572. Closed Kuna target commands report
OwnerCancellation.ownerClosed instead of an absent reason, and Kuna and
JEB close abort their lifetimes with that typed reason.

* fix(errors): read the reason of any signal-shaped cancellation source

* test(ci): cover the counted-baseline comparison behind the architecture guard
This commit is contained in:
morluto authored and GitHub committed 2026-11-14 15:20:03 -05:00
1 parent 2f4c588584
commit 85da0bd4ee
51 files changed
+900 -488

No files matched your search

+4 -12
View File
@@ -1,7 +1,7 @@
import { setTimeout as sleep } from "node:timers/promises";
import {
AnalysisCancelledError,
AnalysisTimeoutError,
cancelledBy,
} from "../domain/analysisErrorCore.js";
import { idaRegistrationTimeoutGuidance } from "./IdaConfiguration.js";
import type { JsonValue } from "../domain/jsonValue.js";
@@ -64,10 +64,7 @@ export const readSettledHealth = async (
const remaining = (): number => timeoutMs - (clock.now() - started);
let lastBusy: LastBusyHealth | undefined;
for (;;) {
if (signal?.aborted)
throw new AnalysisCancelledError("server_health", {
cause: signal.reason,
});
if (signal?.aborted) throw cancelledBy("server_health", signal);
const budgetMs = remaining();
if (budgetMs <= 0)
throw lastBusy === undefined
@@ -115,15 +112,10 @@ export const readSettledHealth = async (
cause instanceof Error &&
cause.name === "AbortError"
)
throw new AnalysisCancelledError("server_health", {
cause: signal.reason,
});
throw cancelledBy("server_health", signal);
throw cause;
}
if (signal?.aborted)
throw new AnalysisCancelledError("server_health", {
cause: signal.reason,
});
if (signal?.aborted) throw cancelledBy("server_health", signal);
if (remaining() <= 0) throw expired();
}
};
+21 -13
View File
@@ -4,7 +4,11 @@ import { jsonRecordSchema } from "../domain/jsonRecord.js";
import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
import { ConfigurationError } from "../domain/configurationErrors.js";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import {
AnalysisCancelledError,
cancelledBy,
carriedReason,
} from "../domain/analysisErrorCore.js";
import type { AnalysisInputIssue } from "../domain/analysisErrorCore.js";
import { projectInputIssues } from "../domain/inputIssueProjection.js";
import { err, ok, type Result } from "../domain/result.js";
@@ -229,22 +233,26 @@ export const readIdaConfiguration = (
const cancellation = regularFileCancellation(cause);
if (cancellation !== undefined) {
if (cause instanceof RegularFileCleanupFailure) {
const error = new AnalysisCancelledError("ida:registration", {
cause: cancellation.reason,
cleanup: {
reason:
cause.cleanupCause instanceof Error
? cause.cleanupCause.message
: String(cause.cleanupCause),
resources: [path],
const error = cancelledBy(
"ida:registration",
carriedReason(cancellation.reason),
{
cleanup: {
reason:
cause.cleanupCause instanceof Error
? cause.cleanupCause.message
: String(cause.cleanupCause),
resources: [path],
},
},
});
);
closeLease?.bindCleanupError(error);
throw error;
}
throw new AnalysisCancelledError("ida:registration", {
cause: cancellation.reason,
});
throw cancelledBy(
"ida:registration",
carriedReason(cancellation.reason),
);
}
if (cause instanceof RegularFileCleanupFailure) {
const primary =
+2 -2
View File
@@ -47,6 +47,7 @@ import {
AnalysisCancelledError,
AnalysisProtocolError,
AnalysisResourceConstraintError,
cancelledBy,
} from "../domain/analysisErrorCore.js";
import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
@@ -465,8 +466,7 @@ export const createIdaMcpConnection = (
return await request(controller.signal);
} catch (cause: unknown) {
if (cause === cancellation)
throw new AnalysisCancelledError(operation, {
cause: signal.reason,
throw cancelledBy(operation, signal, {
capturedOutput: capturedTransportOutput(),
});
throw cause;
+3 -7
View File
@@ -19,8 +19,8 @@ import {
} from "../process/RegexMatcher.js";
import {
AnalysisInputError,
AnalysisCancelledError,
AnalysisProtocolError,
cancelledBy,
} from "../domain/analysisErrorCore.js";
import {
functionDossierSchema,
@@ -131,9 +131,7 @@ export class IdaOperationRunner {
args: Readonly<Record<string, JsonValue>>,
): Promise<JsonValue> {
if (this.options.signal?.aborted)
throw new AnalysisCancelledError(tool, {
cause: this.options.signal.reason,
});
throw cancelledBy(tool, this.options.signal);
const scoped =
this.database === undefined ? args : { ...args, database: this.database };
const result = await this.connection.call(tool, scoped, {
@@ -141,9 +139,7 @@ export class IdaOperationRunner {
});
this.raw.push({ tool, arguments: scoped, result });
if (this.options.signal?.aborted)
throw new AnalysisCancelledError(tool, {
cause: this.options.signal.reason,
});
throw cancelledBy(tool, this.options.signal);
return result;
}
+2 -6
View File
@@ -12,7 +12,7 @@ import {
type BinaryTarget,
} from "../domain/binaryTargetTypes.js";
import { err, ok } from "../domain/result.js";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import { cancelledBy } from "../domain/analysisErrorCore.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import type {
AnalysisClient,
@@ -368,11 +368,7 @@ export class IdaProvider implements AnalysisProviderCandidate {
options?: AnalysisProfileResolutionOptions,
) {
if (options?.signal?.aborted === true)
return err(
new AnalysisCancelledError("ida:profile", {
cause: options.signal.reason,
}),
);
return err(cancelledBy("ida:profile", options.signal));
const config = await this.#configuration(options);
if (!config.ok) return config;
const profile = createAnalysisProfile(IDA_PROVIDER_IDENTITY, {
+33 -46
View File
@@ -15,6 +15,9 @@ import {
AnalysisInputError,
AnalysisTimeoutError,
AnalysisResourceConstraintError,
cancelledBy,
carriedReason,
isAborted,
} from "../domain/analysisErrorCore.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
@@ -97,9 +100,6 @@ const operationSet: ReadonlySet<string> = new Set(IDA_OPERATIONS);
const isIdaOperation = (operation: string): operation is IdaOperation =>
operationSet.has(operation);
const wasCancelled = (options: ExecutionOptions | undefined): boolean =>
options?.signal?.aborted === true;
interface IdaOperationFailureContext {
runner: IdaOperationRunner | undefined;
metadataBefore: JsonValue | undefined;
@@ -261,12 +261,8 @@ export class IdaSessionClient implements AnalysisClient {
return Promise.resolve(undefined);
const call = this.#tail.then(() => {
if (!this.#ready || this.#closed || this.#closing) return undefined;
if (wasCancelled(options))
return err(
new AnalysisCancelledError(operation, {
cause: options?.signal?.reason,
}),
);
if (isAborted(options?.signal))
return err(cancelledBy(operation, options?.signal));
return this.#execute(operation, parameters, options, true);
});
this.#tail = call.then(
@@ -275,11 +271,7 @@ export class IdaSessionClient implements AnalysisClient {
);
const result = await waitForAbortable(call, options?.signal);
return result === ABORTED
? err(
new AnalysisCancelledError(operation, {
cause: options?.signal?.reason,
}),
)
? err(cancelledBy(operation, carriedReason(options?.signal?.reason)))
: result;
}
@@ -295,12 +287,8 @@ export class IdaSessionClient implements AnalysisClient {
"IDA session is closing or closed; reopen the target.",
),
);
if (wasCancelled(options))
return err(
new AnalysisCancelledError(operation, {
cause: options?.signal?.reason,
}),
);
if (isAborted(options?.signal))
return err(cancelledBy(operation, options?.signal));
if (operation !== "health" && !isIdaOperation(operation))
return err(
new AnalysisCapabilityUnavailableError(
@@ -359,10 +347,8 @@ export class IdaSessionClient implements AnalysisClient {
if (!readyOnly) await this.#start(operation);
const before = await this.#observe(options);
failureContext.metadataBefore = before;
if (wasCancelled(options))
throw new AnalysisCancelledError(operation, {
cause: options?.signal?.reason,
});
if (isAborted(options?.signal))
throw cancelledBy(operation, options?.signal);
if (operation === "health") return this.#health(before);
if (!isIdaOperation(operation))
throw new AnalysisProtocolError(
@@ -371,20 +357,16 @@ export class IdaSessionClient implements AnalysisClient {
const runner = this.#runner(options);
failureContext.runner = runner;
const result = await runner.run(operation, parameters);
if (wasCancelled(options))
throw new AnalysisCancelledError(operation, {
cause: options?.signal?.reason,
});
if (isAborted(options?.signal))
throw cancelledBy(operation, options?.signal);
failureContext.postOperationIdentityCheck = "started";
const after = await this.#observe(
options,
(observed) => (failureContext.metadataAfter = observed),
);
failureContext.postOperationIdentityCheck = "verified";
if (wasCancelled(options))
throw new AnalysisCancelledError(operation, {
cause: options?.signal?.reason,
});
if (isAborted(options?.signal))
throw cancelledBy(operation, options?.signal);
return ok(
createAnalysisExecution(result, IDA_PROVIDER_IDENTITY, {
rawResult: {
@@ -483,22 +465,27 @@ export class IdaSessionClient implements AnalysisClient {
diagnostics: cause.diagnostics,
});
} else if (artifactFailure?.reason === "cancelled") {
failure = new AnalysisCancelledError(operation, {
cause: artifactFileCancellationCause(artifactFailure),
});
failure = cancelledBy(
operation,
carriedReason(artifactFileCancellationCause(artifactFailure)),
);
} else if (cause instanceof AnalysisCancelledError) {
failure = new AnalysisCancelledError(operation, {
cause:
failure = cancelledBy(
operation,
carriedReason(
cause.cause === undefined ? options?.signal?.reason : cause.cause,
capturedOutput: cause.capturedOutput,
diagnostics: { ...cause.diagnostics, ...endpoint },
partialObservation: cause.partialObservation,
cleanup:
cause.cleanup ??
(cause.cleanupIncomplete
? { reason: cause.message, resources: cause.cleanupResources }
: undefined),
})
),
{
capturedOutput: cause.capturedOutput,
diagnostics: { ...cause.diagnostics, ...endpoint },
partialObservation: cause.partialObservation,
cleanup:
cause.cleanup ??
(cause.cleanupIncomplete
? { reason: cause.message, resources: cause.cleanupResources }
: undefined),
},
)
.bindCleanupDependencies([cause])
.bindCleanupResourceOwner(cause);
} else if (