refactor(elf): preserve unwind parser limit facts (#12308)

refactor(elf): preserve unwind parser limit ownership
This commit is contained in:
morluto authored and GitHub committed 2026-11-19 12:15:30 +00:00
1 parent 4afa99bebe
commit 9a9ddc9605
4 files changed
+123 -87

No files matched your search

+27 -37
View File
@@ -1,4 +1,5 @@
import {
isParseLimit,
parseFailureAnalysisError,
parseLimitConstraint,
} from "../../domain/parseFailureAnalysisError.js";
@@ -31,7 +32,8 @@ import {
binaryResourceCeiling,
} from "../../domain/binaryContainer.js";
import {
ElfUnwindSymbolTextFailure,
ELF_UNWIND_FORMAT,
ELF_UNWIND_RECORD_LIMIT,
parseElfUnwindRanges,
} from "./ElfUnwindTables.js";
@@ -86,36 +88,40 @@ export class ElfUnwindRangesProvider implements ElfUnwindRangesPort {
}
}
const inputBudgetRemediation = (
boundary: "file-size" | "capacity",
input: InspectElfUnwindRangesInput,
): string =>
boundary === "file-size"
? input.max_file_bytes >= MAX_INSPECT_ELF_UNWIND_FILE_BYTES
? `The image exceeds the ${String(MAX_INSPECT_ELF_UNWIND_FILE_BYTES)}-byte input ceiling this operation accepts; select a smaller artifact.`
: `Raise max_file_bytes above ${String(input.max_file_bytes)} bytes or select a smaller artifact; the limit is the caller-selected input read budget.`
: input.max_ranges >= MAX_INSPECT_ELF_UNWIND_RANGES
? `The image exceeds the ${String(MAX_INSPECT_ELF_UNWIND_RANGES)}-record unwind ceiling this operation accepts; select a smaller artifact.`
: `Raise max_ranges above ${String(input.max_ranges)} or select a smaller artifact; the limit is the caller-selected unwind record budget.`;
const fileBudgetRemediation = (maximum: number): string =>
maximum >= MAX_INSPECT_ELF_UNWIND_FILE_BYTES
? `The image exceeds the ${String(MAX_INSPECT_ELF_UNWIND_FILE_BYTES)}-byte input ceiling this operation accepts; select a smaller artifact.`
: `Raise max_file_bytes above ${String(maximum)} bytes or select a smaller artifact; the limit is the caller-selected input read budget.`;
const recordBudgetRemediation = (maximum: number): string =>
maximum >= MAX_INSPECT_ELF_UNWIND_RANGES
? `The image exceeds the ${String(MAX_INSPECT_ELF_UNWIND_RANGES)}-record unwind ceiling this operation accepts; select a smaller artifact.`
: `Raise max_ranges above ${String(maximum)} or select a smaller artifact; the limit is the caller-selected unwind record budget.`;
const elfUnwindFailurePrimary = (
facts: ArtifactFilePrimaryFacts,
input: InspectElfUnwindRangesInput,
) => {
const { cause, origin } = facts;
// The page's symbol-name text allowance is fixed; only a smaller page avoids it.
if (cause instanceof ElfUnwindSymbolTextFailure)
if (isParseLimit(cause, ELF_UNWIND_FORMAT)) {
const { detail, limit } = cause.failure;
const records = limit.name === ELF_UNWIND_RECORD_LIMIT;
return new AnalysisResourceConstraintError(
OPERATION,
"capacity",
cause.message,
{ limit: input.limit, maximum_bytes: cause.maximumBytes },
detail,
records
? { max_file_bytes: input.max_file_bytes, max_ranges: limit.maximum }
: { limit: input.limit, maximum_bytes: limit.maximum },
{
cause,
retryable: false,
remediationAction: `Request a smaller limit than ${String(input.limit)}, or page with offset; the ${String(cause.maximumBytes)}-byte symbol-name text allowance is fixed, and max_ranges and max_file_bytes do not raise it.`,
remediationAction: records
? recordBudgetRemediation(limit.maximum)
: `Request a smaller limit than ${String(input.limit)}, or page with offset; the ${String(limit.maximum)}-byte symbol-name text allowance is fixed, and max_ranges and max_file_bytes do not raise it.`,
},
);
}
if (cause instanceof BinaryResourceFailure)
return parseLimitConstraint(
OPERATION,
@@ -139,11 +145,10 @@ const elfUnwindFailurePrimary = (
origin === "owned-or-classified" &&
cause instanceof ArtifactReaderFailure
) {
if (cause.reason === "limit") {
const structural = cause.boundary === "memory";
if (cause.reason === "limit" && cause.boundary === "file-size")
return new AnalysisResourceConstraintError(
OPERATION,
cause.boundary ?? "memory",
"file-size",
cause.message,
{
max_file_bytes: input.max_file_bytes,
@@ -151,25 +156,10 @@ const elfUnwindFailurePrimary = (
},
{
cause,
...(cause.boundary === undefined
? {}
: structural
? cause.fixedAllowance === undefined
? {}
: {
retryable: false as const,
fixedAllowance: cause.fixedAllowance,
}
: {
retryable: false as const,
remediationAction: inputBudgetRemediation(
cause.boundary,
input,
),
}),
retryable: false,
remediationAction: fileBudgetRemediation(input.max_file_bytes),
},
);
}
if (cause.reason === "path" || cause.reason === "format")
return stableArtifactInputFailure(cause, OPERATION);
}
+41 -23
View File
@@ -6,10 +6,7 @@ import {
elfUnwindRangesSchema,
inspectElfUnwindRangesInputSchema,
} from "../../domain/native/elfUnwindRanges.js";
import {
ElfUnwindSymbolTextFailure,
parseElfUnwindRanges,
} from "./ElfUnwindTables.js";
import { parseElfUnwindRanges } from "./ElfUnwindTables.js";
import {
UNWIND_FN_A,
UNWIND_FN_A_SIZE,
@@ -508,24 +505,40 @@ it("returns only the CIEs a page's ranges name, however many the image has", ()
expect(first.coverage.total_cies).toBe(502);
});
it("fails closed when the CIE or FDE budget is exhausted", () => {
const bytes = elfUnwindFixture();
const input = inspectElfUnwindRangesInputSchema.parse({
path: "/artifacts/unwind.elf",
max_ranges: 1,
});
expect(() =>
parseElfUnwindRanges(
bytes,
{
path: input.path,
sha256: "a".repeat(64),
bytes: bytes.length,
},
input,
),
).toThrow(ArtifactReaderFailure);
});
it.each([
{ field: "CIE", maximum: 1, suffixNames: 0 },
{ field: "FDE", maximum: 2, suffixNames: 1 },
])(
"fails closed when the $field budget is exhausted",
({ field, maximum, suffixNames }) => {
const bytes = elfUnwindFixture({ suffixNames });
const input = inspectElfUnwindRangesInputSchema.parse({
path: "/artifacts/unwind.elf",
max_ranges: maximum,
});
expect(() =>
parseElfUnwindRanges(
bytes,
{
path: input.path,
sha256: "a".repeat(64),
bytes: bytes.length,
},
input,
),
).toThrow(
expect.objectContaining({
failure: expect.objectContaining({
kind: "limit",
format: "elf-unwind-ranges",
field,
offset: expect.any(Number),
limit: { name: "max_ranges", maximum },
}),
}),
);
},
);
it("stops when the caller has already cancelled", () => {
const bytes = elfUnwindFixture();
@@ -1190,7 +1203,12 @@ it("bounds the symbol-name text decoded for one page by its own allowance", () =
symbol: { text: "s".repeat(65535) },
});
expect(() => parse(bytes, { limit: 300 })).toThrow(
ElfUnwindSymbolTextFailure,
expect.objectContaining({
failure: expect.objectContaining({
kind: "limit",
limit: { name: "symbol_name_text_bytes", maximum: 16 * 1024 * 1024 },
}),
}),
);
});
+19 -25
View File
@@ -5,10 +5,8 @@ import {
keyedBy,
uniqueKeyed,
} from "../../domain/keyedCollection.js";
import {
assertArtifactReadActive,
ArtifactReaderFailure,
} from "../../resources/index.js";
import { assertArtifactReadActive } from "../../resources/index.js";
import { decodeLimit } from "../../domain/parseFailure.js";
import { readElfDynamicEntry } from "../../domain/elfDynamicEntry.js";
import { readElfSymbol } from "../../domain/elfSymbol.js";
import {
@@ -242,20 +240,8 @@ const placeSection = (
return { location: declared, problem: null };
};
/**
* Symbol names for one page exceeded their fixed text allowance. Unlike the
* record budgets, max_ranges does not raise it; a smaller page avoids it.
*/
export class ElfUnwindSymbolTextFailure extends Error {
readonly maximumBytes = MAX_ELF_UNWIND_SYMBOL_TEXT_BYTES;
constructor() {
super(
`ELF unwind symbol names on this page exceed the ${String(MAX_ELF_UNWIND_SYMBOL_TEXT_BYTES)}-byte symbol-name text allowance.`,
);
this.name = "ElfUnwindSymbolTextFailure";
}
}
export const ELF_UNWIND_FORMAT = "elf-unwind-ranges";
export const ELF_UNWIND_RECORD_LIMIT = "max_ranges";
/** Read .eh_frame/.eh_frame_hdr function ranges. Truncation stays incomplete. */
export const parseElfUnwindRanges = (
@@ -791,11 +777,12 @@ export const parseElfUnwindRanges = (
let fdeRecords = 0;
let discarded = 0;
let indirectFdes = 0;
const budget = (kind: "CIE" | "FDE"): void => {
throw new ArtifactReaderFailure(
"limit",
const budget = (kind: "CIE" | "FDE", offset: number): never => {
throw decodeLimit(
ELF_UNWIND_FORMAT,
`ELF unwind ${kind} count exceeds the selected max_ranges budget of ${String(input.max_ranges)}.`,
{ boundary: "capacity" },
{ name: ELF_UNWIND_RECORD_LIMIT, maximum: input.max_ranges },
{ field: kind, offset },
);
};
@@ -862,9 +849,9 @@ export const parseElfUnwindRanges = (
}
const isCie = id === 0;
if (isCie) {
if (cieRecords + 1 > input.max_ranges) budget("CIE");
if (cieRecords + 1 > input.max_ranges) budget("CIE", recordStart);
cieRecords += 1;
} else if (fdeRecords + 1 > input.max_ranges) budget("FDE");
} else if (fdeRecords + 1 > input.max_ranges) budget("FDE", recordStart);
else fdeRecords += 1;
examined += 1;
let undecoded = false;
@@ -1945,7 +1932,14 @@ const symbolNameDecoder = (): ((name: SymbolName) => string) => {
if (cached !== undefined) return cached;
charged += name.contentBytes;
if (charged > MAX_ELF_UNWIND_SYMBOL_TEXT_BYTES)
throw new ElfUnwindSymbolTextFailure();
throw decodeLimit(
ELF_UNWIND_FORMAT,
`ELF unwind symbol names on this page exceed the ${String(MAX_ELF_UNWIND_SYMBOL_TEXT_BYTES)}-byte symbol-name text allowance.`,
{
name: "symbol_name_text_bytes",
maximum: MAX_ELF_UNWIND_SYMBOL_TEXT_BYTES,
},
);
const text = elfStringTableText(name) ?? "";
decoded.set(name, text);
return text;
@@ -2,6 +2,7 @@ import { symlink, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { describe, expect, it } from "vitest";
import { createElfUnwindRangesService } from "../../../src/composition/binaryDiagnostics.js";
import { MAX_ELF_UNWIND_SYMBOL_TEXT_BYTES } from "../../../src/domain/native/elfUnwindRanges.js";
import { elfUnwindFixture } from "../../../src/native/elf/ElfUnwindTables.fixture.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
@@ -90,7 +91,9 @@ describe("ELF unwind range stable filesystem boundary", () => {
await service.close();
}
});
});
describe("ELF unwind range budgets", () => {
it("tells a caller over the symbol-name text allowance to request a smaller page", async () => {
const root = await createTestTempDirectory("rea-elf-unwind-names-");
const path = join(root, "program");
@@ -105,6 +108,20 @@ describe("ELF unwind range stable filesystem boundary", () => {
expect(result.error).toMatchObject({
_tag: "AnalysisResourceConstraintError",
retryable: false,
reportedLimits: {
limit: 300,
maximum_bytes: MAX_ELF_UNWIND_SYMBOL_TEXT_BYTES,
},
cause: {
failure: {
kind: "limit",
format: "elf-unwind-ranges",
limit: {
name: "symbol_name_text_bytes",
maximum: MAX_ELF_UNWIND_SYMBOL_TEXT_BYTES,
},
},
},
});
const remediation =
"remediationAction" in result.error
@@ -127,10 +144,27 @@ describe("ELF unwind range stable filesystem boundary", () => {
try {
const tooSmall = await service.inspect({ path, max_file_bytes: 64 });
if (tooSmall.ok) throw new Error("Expected resource budget failure");
expect(tooSmall.error._tag).toBe("AnalysisResourceConstraintError");
expect(tooSmall.error).toMatchObject({
_tag: "AnalysisResourceConstraintError",
resource: "file-size",
reportedLimits: { max_file_bytes: 64 },
});
const tooMany = await service.inspect({ path, max_ranges: 1 });
if (tooMany.ok) throw new Error("Expected range budget failure");
expect(tooMany.error._tag).toBe("AnalysisResourceConstraintError");
expect(tooMany.error).toMatchObject({
_tag: "AnalysisResourceConstraintError",
resource: "capacity",
reportedLimits: { max_ranges: 1 },
cause: {
failure: {
kind: "limit",
format: "elf-unwind-ranges",
field: "CIE",
offset: expect.any(Number),
limit: { name: "max_ranges", maximum: 1 },
},
},
});
const cancelled = await service.inspect(
{ path },
{ signal: AbortSignal.abort() },