From 9a9ddc9605fe767feb2fbe548f4cfeb7336ba0e0 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 07:15:30 -0500 Subject: [PATCH] refactor(elf): preserve unwind parser limit facts (#12308) refactor(elf): preserve unwind parser limit ownership --- src/native/elf/ElfUnwindRangesProvider.ts | 64 ++++++++----------- src/native/elf/ElfUnwindTables.test.ts | 64 ++++++++++++------- src/native/elf/ElfUnwindTables.ts | 44 ++++++------- .../filesystem/elfUnwindRanges.test.ts | 38 ++++++++++- 4 files changed, 123 insertions(+), 87 deletions(-) diff --git a/src/native/elf/ElfUnwindRangesProvider.ts b/src/native/elf/ElfUnwindRangesProvider.ts index 8a474f0d11..eba7ece81d 100644 --- a/src/native/elf/ElfUnwindRangesProvider.ts +++ b/src/native/elf/ElfUnwindRangesProvider.ts @@ -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); } diff --git a/src/native/elf/ElfUnwindTables.test.ts b/src/native/elf/ElfUnwindTables.test.ts index 39caeebf13..c5cd7cd8ca 100644 --- a/src/native/elf/ElfUnwindTables.test.ts +++ b/src/native/elf/ElfUnwindTables.test.ts @@ -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 }, + }), + }), ); }); diff --git a/src/native/elf/ElfUnwindTables.ts b/src/native/elf/ElfUnwindTables.ts index 5b6bed12cf..d6136b271f 100644 --- a/src/native/elf/ElfUnwindTables.ts +++ b/src/native/elf/ElfUnwindTables.ts @@ -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; diff --git a/tests/boundary/filesystem/elfUnwindRanges.test.ts b/tests/boundary/filesystem/elfUnwindRanges.test.ts index 0cc1a78519..195cc20df4 100644 --- a/tests/boundary/filesystem/elfUnwindRanges.test.ts +++ b/tests/boundary/filesystem/elfUnwindRanges.test.ts @@ -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() },