fix(firmware): separate analysis and publication deadlines (#4602)

Separate extraction/inventory and caller-selectable publication budgets in the shared firmware workflow. Preserve phase, selected timeout, verified progress, caller cancellation identity and committed observations through cleanup. Enforce monotonic expiry even before timer callbacks run.

Validated with 101 targeted tests, full static checks, documentation checks and real OpenWrt CLI/MCP workflows with digest and cleanup verification. Existing main CI failures are documented separately.

Fixes #4176.
This commit is contained in:
Nitin Kushwaha authored and GitHub committed 2026-10-20 13:57:20 +00:00
1 parent 52d1a72af0
commit cf5194f68e
11 files changed
+726 -102

No files matched your search

@@ -30,7 +30,9 @@ export class FirmwareAnalysisService {
options?: ExecutionOptions,
): Promise<Result<Evidence, AnalysisError>> {
if (options?.signal?.aborted === true)
return err(new AnalysisCancelledError(operation));
return err(
new AnalysisCancelledError(operation, { cause: options.signal.reason }),
);
const parsed = firmwareRequestSchema.safeParse({ operation, input });
if (!parsed.success)
return err(new AnalysisInputError(operation, { cause: parsed.error }));
+2
View File
@@ -73,6 +73,7 @@ export const registerFirmwareCommands = (
maxDepth: extractInput.max_depth,
maxOutputBytes: extractInput.max_output_bytes,
maxOutputFiles: extractInput.max_output_files,
publicationTimeoutMs: extractInput.publication_timeout_ms,
}),
run: ({ args, options }) =>
execute(CLI_COMMANDS.extractFirmware, "extract_firmware", {
@@ -84,6 +85,7 @@ export const registerFirmwareCommands = (
max_depth: options.maxDepth,
max_output_bytes: options.maxOutputBytes,
max_output_files: options.maxOutputFiles,
publication_timeout_ms: options.publicationTimeoutMs,
}),
});
};
+10
View File
@@ -45,6 +45,16 @@ export const firmwareInputSchemas = {
.max(100_000)
.default(10_000)
.describe("Staging entry budget, including directories and links"),
publication_timeout_ms: z
.number()
.int()
.min(1)
// Node timers cannot represent longer delays without overflow.
.max(2_147_483_647)
.default(120_000)
.describe(
"Publication and final cleanup budget in milliseconds, started after extraction and inventory; increase for a slow destination",
),
}),
} as const;
+111
View File
@@ -0,0 +1,111 @@
import { afterEach, expect, it, vi } from "vitest";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { firmwareRequestSchema } from "../domain/firmware/firmwareAnalysis.js";
import {
firmwareFailure,
firmwarePhaseInterruption,
} from "./FirmwareFailures.js";
import { startFirmwareDeadline } from "./FirmwareDeadline.js";
afterEach(() => vi.restoreAllMocks());
it("enforces absolute expiry before the timer callback while preserving observed caller cancellation", () => {
const now = vi.spyOn(performance, "now").mockReturnValue(100);
const deadline = startFirmwareDeadline("publication", 1_000);
expect(deadline.expiresAtMs).toBe(1_100);
now.mockReturnValue(1_099);
expect(
firmwarePhaseInterruption("extract_firmware", deadline.signal, deadline),
).toBeUndefined();
now.mockReturnValue(1_100);
expect(deadline.signal.aborted).toBe(false);
const expired = firmwarePhaseInterruption(
"extract_firmware",
deadline.signal,
deadline,
);
if (expired === undefined) throw new Error("Expected elapsed deadline");
expect(projectAnalysisError(expired)).toMatchObject({
code: "provider_timeout",
details: { timeout_ms: 1_000, diagnostics: { phase: "publication" } },
});
const reason = { caller: "stop at expiry" };
const cancelled = firmwarePhaseInterruption(
"extract_firmware",
AbortSignal.abort(reason),
deadline,
);
expect(cancelled).toBeInstanceOf(AnalysisCancelledError);
expect(cancelled?.cause).toBe(reason);
});
it("defaults and preserves the caller's publication budget at the shared contract", () => {
const parse = (input: Record<string, unknown>) =>
firmwareRequestSchema.parse({
operation: "extract_firmware",
input: { path: "/firmware.bin", output_directory: "/output", ...input },
});
expect(parse({}).input).toMatchObject({ publication_timeout_ms: 120_000 });
expect(parse({ publication_timeout_ms: 345_678 }).input).toMatchObject({
publication_timeout_ms: 345_678,
});
for (const value of [0, -1, 0.5, 2_147_483_648, null, "120000"])
expect(() => parse({ publication_timeout_ms: value })).toThrow();
});
it("reports the publication phase, verified progress and its selected budget", () => {
const reason = new Error("deadline");
const failure = firmwareFailure(
new AnalysisCancelledError("extract_firmware", { cause: reason }),
{
engine: "unblob",
operation: "extract_firmware",
deadline: {
phase: "publication",
signal: AbortSignal.abort(reason),
timeoutMs: 345_678,
expiresAtMs: 0,
},
publication: {
output_directory: "/output",
verified_files: 2,
total_files: 10,
},
},
);
expect(projectAnalysisError(failure)).toMatchObject({
code: "provider_timeout",
details: {
timeout_ms: 345_678,
diagnostics: {
phase: "publication",
publication: {
output_directory: "/output",
verified_files: 2,
total_files: 10,
},
},
},
remediation: { action: expect.stringContaining("publication_timeout_ms") },
});
});
it("keeps a distinct caller cancellation when the phase deadline has also expired", () => {
const reason = { caller: "stop" };
const original = new AnalysisCancelledError("extract_firmware", {
cause: reason,
});
expect(
firmwareFailure(original, {
engine: "unblob",
operation: "extract_firmware",
deadline: {
phase: "publication",
signal: AbortSignal.abort(new Error("late timeout")),
timeoutMs: 345_678,
expiresAtMs: 0,
},
}),
).toBe(original);
});
+22
View File
@@ -0,0 +1,22 @@
/** The phase and budget that own an observed firmware timeout. */
export interface FirmwareDeadline {
readonly phase: "analysis" | "publication";
readonly signal: AbortSignal;
readonly timeoutMs: number;
readonly expiresAtMs: number;
}
/** Keep a phase's selected budget paired with its cancellation identity. */
export const startFirmwareDeadline = (
phase: FirmwareDeadline["phase"],
timeoutMs: number,
): FirmwareDeadline => ({
phase,
expiresAtMs: performance.now() + timeoutMs,
signal: AbortSignal.timeout(timeoutMs),
timeoutMs,
});
/** Timers may not have run when synchronous inventory or result parsing returns. */
export const firmwareDeadlineElapsed = (deadline: FirmwareDeadline): boolean =>
performance.now() >= deadline.expiresAtMs;
+71 -21
View File
@@ -14,25 +14,66 @@ import {
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { FIRMWARE_LIMITS } from "./FirmwareRelease.js";
import type { FirmwareDeadline } from "./FirmwareDeadline.js";
import { firmwareDeadlineElapsed } from "./FirmwareDeadline.js";
import type { AnalysisErrorOptions } from "../domain/analysisErrorBase.js";
import { z } from "zod";
type FirmwarePublicationProgress = {
readonly output_directory: string;
readonly verified_files: number;
readonly total_files: number;
};
interface FirmwareFailureContext {
readonly engine: string;
readonly operation: string;
readonly deadline?: FirmwareDeadline | undefined;
readonly treeCleanupLease?: AnalysisCleanupLease | undefined;
readonly publication?: FirmwarePublicationProgress | undefined;
}
const timeoutFailure = (
operation: string,
reason: unknown,
deadline: FirmwareDeadline,
options: Pick<AnalysisErrorOptions, "partialObservation"> & {
readonly publication?: FirmwarePublicationProgress | undefined;
} = {},
): AnalysisTimeoutError =>
new AnalysisTimeoutError(operation, deadline.timeoutMs, {
cause: reason,
partialObservation: options.partialObservation,
diagnostics: {
phase: deadline.phase,
...(options.publication === undefined
? {}
: { publication: options.publication }),
},
...(deadline.phase === "publication"
? {
userMessage: `Firmware publication exceeded its ${deadline.timeoutMs}ms budget. Extraction already completed.`,
remediationAction:
"Read any retained publication receipt first. For a retry, choose an absent local output directory or increase publication_timeout_ms (--publication-timeout-ms in the CLI).",
}
: {}),
});
/** Translate the producing file owner's outcome without guessing from a later signal. */
export const firmwareFailure = (
cause: unknown,
engine: string,
operation: string,
deadline?: AbortSignal,
treeCleanupLease?: AnalysisCleanupLease,
context: FirmwareFailureContext,
): AnalysisError => {
const { engine, operation, deadline, treeCleanupLease, publication } =
context;
if (
cause instanceof AnalysisCancelledError &&
deadline?.aborted &&
cause.cause === deadline.reason
deadline?.signal.aborted &&
cause.cause === deadline.signal.reason
)
return new AnalysisTimeoutError(operation, FIRMWARE_LIMITS.timeoutMs, {
cause: cause.cause,
return timeoutFailure(operation, cause.cause, deadline, {
partialObservation: cause.partialObservation,
publication,
});
if (cause instanceof AnalysisError) return cause;
if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined) {
@@ -49,18 +90,13 @@ export const firmwareFailure = (
const outcome = cause.fileCleanupFailure.outcome;
const primary =
outcome.kind === "failed"
? firmwareFailure(
outcome.cause,
engine,
operation,
deadline,
treeCleanupLease,
)
? firmwareFailure(outcome.cause, context)
: cause.fileCleanupFailure.completionCancellation !== undefined
? firmwareCancellation(
operation,
cause.fileCleanupFailure.completionCancellation.reason,
deadline,
publication,
)
: undefined;
if (primary !== undefined)
@@ -76,6 +112,7 @@ export const firmwareFailure = (
operation,
artifactFileCancellationCause(cause),
deadline,
publication,
),
cleanup,
operation,
@@ -87,6 +124,7 @@ export const firmwareFailure = (
operation,
artifactFileCancellationCause(cause),
deadline,
publication,
);
if (cause instanceof z.ZodError)
return new AnalysisOutputError(
@@ -106,10 +144,22 @@ export const firmwareFailure = (
export const firmwareCancellation = (
operation: string,
reason: unknown,
deadline?: AbortSignal,
deadline?: FirmwareDeadline,
publication?: FirmwarePublicationProgress,
): AnalysisError =>
deadline?.aborted && reason === deadline.reason
? new AnalysisTimeoutError(operation, FIRMWARE_LIMITS.timeoutMs, {
cause: reason,
})
deadline?.signal.aborted && reason === deadline.signal.reason
? timeoutFailure(operation, reason, deadline, { publication })
: new AnalysisCancelledError(operation, { cause: reason });
/** Preserve observed cancellation identity; otherwise enforce the monotonic budget. */
export const firmwarePhaseInterruption = (
operation: string,
signal: AbortSignal,
deadline: FirmwareDeadline,
publication?: FirmwarePublicationProgress,
): AnalysisError | undefined =>
signal.aborted
? firmwareCancellation(operation, signal.reason, deadline, publication)
: firmwareDeadlineElapsed(deadline)
? timeoutFailure(operation, undefined, deadline, { publication })
: undefined;
+59 -28
View File
@@ -30,6 +30,10 @@ import {
BINWALK_PROVIDER_IDENTITY,
UNBLOB_PROVIDER_IDENTITY,
} from "./FirmwareRelease.js";
import {
startFirmwareDeadline,
type FirmwareDeadline,
} from "./FirmwareDeadline.js";
import { admitFirmwareVersion } from "./FirmwareVersion.js";
import {
firmwareToolUnavailable,
@@ -47,7 +51,10 @@ import {
normalizeUnblobReport,
} from "./FirmwareReports.js";
import { firmwareFailure, firmwareCancellation } from "./FirmwareFailures.js";
import {
firmwareFailure,
firmwarePhaseInterruption,
} from "./FirmwareFailures.js";
import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
type Outcome = Awaited<ReturnType<FirmwareAnalysisPort["execute"]>>;
@@ -186,7 +193,12 @@ export class FirmwareProvider implements FirmwareAnalysisPort {
try {
await this.#files.close();
} catch (cause: unknown) {
failures.push(firmwareFailure(cause, "firmware", "close_firmware"));
failures.push(
firmwareFailure(cause, {
engine: "firmware",
operation: "close_firmware",
}),
);
}
const workspace = await this.#retryWorkspaceCleanup();
if (workspace.failure !== undefined) failures.push(workspace.failure);
@@ -199,7 +211,10 @@ export class FirmwareProvider implements FirmwareAnalysisPort {
try {
await this.#files.retryCleanup();
} catch (cause: unknown) {
fileFailure = firmwareFailure(cause, "firmware", "close_firmware");
fileFailure = firmwareFailure(cause, {
engine: "firmware",
operation: "close_firmware",
});
}
const workspace = await this.#retryWorkspaceCleanup();
return {
@@ -303,11 +318,14 @@ export class FirmwareProvider implements FirmwareAnalysisPort {
let rootLease: AnalysisCleanupLease | undefined;
const engineName =
request.operation === "inspect_firmware_regions" ? "binwalk" : "unblob";
const deadline = AbortSignal.timeout(FIRMWARE_LIMITS.timeoutMs);
const signal =
const withCaller = (phase: FirmwareDeadline) =>
options?.signal === undefined
? deadline
: AbortSignal.any([options.signal, deadline]);
? phase.signal
: AbortSignal.any([options.signal, phase.signal]);
// Extraction and publication have separate budgets: publication time depends on the
// destination filesystem, so it must not be charged to the extraction deadline.
let deadline = startFirmwareDeadline("analysis", FIRMWARE_LIMITS.timeoutMs);
let signal = withCaller(deadline);
let outcome: Outcome;
try {
if (signal.aborted)
@@ -465,6 +483,19 @@ export class FirmwareProvider implements FirmwareAnalysisPort {
request.operation,
signal,
);
// The inventory can finish after its deadline expired; an expired
// extraction must not publish under the fresh publication budget.
const interruption = firmwarePhaseInterruption(
request.operation,
signal,
deadline,
);
if (interruption !== undefined) throw interruption;
deadline = startFirmwareDeadline(
"publication",
request.input.publication_timeout_ms,
);
signal = withCaller(deadline);
result = await publishFirmwareExtraction({
files: this.#files,
workspacePath: root.path,
@@ -520,12 +551,11 @@ export class FirmwareProvider implements FirmwareAnalysisPort {
),
);
} catch (cause: unknown) {
const failure = firmwareFailure(
cause,
engineName,
request.operation,
const failure = firmwareFailure(cause, {
engine: engineName,
operation: request.operation,
deadline,
);
});
outcome = err(failure);
}
const finished = await finishFirmwareWorkspace(
@@ -558,16 +588,19 @@ export class FirmwareProvider implements FirmwareAnalysisPort {
finished.error.cleanupResources.includes(root.path)
)
rootLease.bindCleanupError(finished.error);
if (finished.ok && signal.aborted)
return err(
firmwareCancellation(
request.operation,
signal.reason,
deadline,
).retainPartialObservation(
completedFirmwareObservation(finished.value),
),
if (finished.ok) {
const interruption = firmwarePhaseInterruption(
request.operation,
signal,
deadline,
);
if (interruption !== undefined)
return err(
interruption.retainPartialObservation(
completedFirmwareObservation(finished.value),
),
);
}
return finished;
}
}
@@ -580,7 +613,7 @@ const finishFirmwareWorkspace = async (
request: FirmwareRequest,
rootLease: AnalysisCleanupLease | undefined,
signal: AbortSignal,
deadline: AbortSignal,
deadline: FirmwareDeadline,
): Promise<Outcome> => {
if (
!outcome.ok &&
@@ -613,12 +646,10 @@ const finishFirmwareWorkspace = async (
},
);
rootLease?.bindCleanupError(cleanup);
if (outcome.ok && signal.aborted) {
const primary = firmwareCancellation(
request.operation,
signal.reason,
deadline,
);
const primary = outcome.ok
? firmwarePhaseInterruption(request.operation, signal, deadline)
: undefined;
if (outcome.ok && primary !== undefined) {
primary.retainPartialObservation(
completedFirmwareObservation(outcome.value),
);
+34 -23
View File
@@ -1,16 +1,16 @@
import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import { firmwareFailure } from "./FirmwareFailures.js";
import {
firmwareFailure,
firmwarePhaseInterruption,
} from "./FirmwareFailures.js";
import { createHash } from "node:crypto";
import { join } from "node:path";
import type { z } from "zod";
import { SafeOutputTree } from "../artifacts/SafeOutputTree.js";
import { SafeOutputTreeCreationFailure } from "../artifacts/SafeOutputTreeCreationFailure.js";
import {
AnalysisOutputError,
AnalysisCancelledError,
} from "../domain/analysisErrorCore.js";
import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import { firmwareResultSchemas } from "../domain/firmware/firmwareAnalysis.js";
@@ -40,6 +40,7 @@ const UNNAMED_DEPENDENCY_CONTINUATION =
"The producer reported a missing extractor dependency without naming it; its identity is unavailable in this evidence. No specific installation or rerun can be prescribed from this report. Retain the gap as unextracted unless additional provider evidence establishes the dependency. REA installs nothing.";
import { FIRMWARE_LIMITS } from "./FirmwareRelease.js";
import type { FirmwareDeadline } from "./FirmwareDeadline.js";
/** The depth ceiling cannot be raised past the input schema maximum. */
const MAX_EXTRACTION_DEPTH = 10;
@@ -89,7 +90,7 @@ const gapSortKey = (gap: ExtractionGap): string =>
export const publishFirmwareExtraction = async (context: {
files: FirmwareFileAccess;
workspacePath: string;
deadline: AbortSignal;
deadline: FirmwareDeadline;
outputDirectory: string;
entries: readonly FirmwareEntry[];
normalized: ReturnType<typeof normalizeUnblobReport>;
@@ -108,12 +109,20 @@ export const publishFirmwareExtraction = async (context: {
let result:
| z.infer<typeof firmwareResultSchemas.extract_firmware>
| undefined;
const files: z.infer<typeof firmwareResultSchemas.extract_firmware>["files"] =
[];
let totalFiles = 0;
const progress = () => ({
output_directory: context.outputDirectory,
verified_files: files.length,
total_files: totalFiles,
});
try {
const materialized = new Set(
context.entries
.filter((entry) => entry.kind === "file")
.map((entry) => `$output/${entry.relativePath}`),
);
const materialized = new Set<string>();
for (const entry of context.entries)
if (entry.kind === "file")
materialized.add(`$output/${entry.relativePath}`);
totalFiles = materialized.size;
for (const path of context.normalized.files.keys()) {
if (path !== "$input" && !materialized.has(path))
throw new AnalysisOutputError(
@@ -121,7 +130,6 @@ export const publishFirmwareExtraction = async (context: {
`Reported regular file is absent from materialized output: ${path}`,
);
}
const files = [];
const unpublished = [];
tree = await SafeOutputTree.create(context.outputDirectory);
for (const entry of context.entries) {
@@ -180,10 +188,13 @@ export const publishFirmwareExtraction = async (context: {
),
published_bytes: files.reduce((sum, file) => sum + file.size, 0),
});
if (context.signal.aborted)
throw new AnalysisCancelledError("extract_firmware", {
cause: context.signal.reason,
});
const interruption = firmwarePhaseInterruption(
"extract_firmware",
context.signal,
context.deadline,
progress(),
);
if (interruption !== undefined) throw interruption;
await tree.commit(context.signal);
return result;
} catch (cause: unknown) {
@@ -195,13 +206,13 @@ export const publishFirmwareExtraction = async (context: {
: new AnalysisCleanupLease(async () => {
await ownedTree.rollback();
});
const primary = firmwareFailure(
cause,
"unblob",
"extract_firmware",
context.deadline,
treeLease,
);
const primary = firmwareFailure(cause, {
engine: "unblob",
operation: "extract_firmware",
deadline: context.deadline,
treeCleanupLease: treeLease,
publication: progress(),
});
try {
await treeLease?.release();
} catch (cleanupCause: unknown) {