From daf5e91f39409a8f5fe50efe0ce220d6efe23eb0 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 07:36:54 -0500 Subject: [PATCH] fix(erlang): report the enforced BEAM table row limit (#12321) * fix(erlang): report the enforced BEAM table row limit * docs(erlang): describe the reported fixed table ceiling --- docs/erlang-beam.md | 5 +- src/domain/parseFailureAnalysisError.ts | 21 +++-- src/erlang/BeamParser.test.ts | 111 +++++++---------------- src/erlang/BeamParser.ts | 44 ++++----- src/erlang/BeamProvider.ts | 73 +++++++++------ tests/boundary/mcp/erlangBeamMcp.test.ts | 6 +- 6 files changed, 114 insertions(+), 146 deletions(-) diff --git a/docs/erlang-beam.md b/docs/erlang-beam.md index 309aac655c..8422550469 100644 --- a/docs/erlang-beam.md +++ b/docs/erlang-beam.md @@ -130,7 +130,10 @@ coverage, and executes no bytecode. The selected file is limited to 64 MiB by default (512 MiB maximum). At most 64 chunks and 4096 atoms are examined by default, and at most 65536 export, -import, and lambda rows together. Malformed `FOR1`/`BEAM` headers, truncated +import, and lambda rows together. A refusal at this fixed row ceiling reports +`max_table_rows` in `reported_limits`. It has no caller override. + +Malformed `FOR1`/`BEAM` headers, truncated chunks, and `AtU8` names that are not valid UTF-8 fail without partial success. The reader checks each encountered chunk's payload and alignment padding against the declared form before applying the chunk count limit. diff --git a/src/domain/parseFailureAnalysisError.ts b/src/domain/parseFailureAnalysisError.ts index a086acf72d..a0cf5dd892 100644 --- a/src/domain/parseFailureAnalysisError.ts +++ b/src/domain/parseFailureAnalysisError.ts @@ -6,6 +6,7 @@ import { type ResourceConstraintRecovery, } from "./analysisErrorCore.js"; import type { AnalysisErrorOptions } from "./analysisErrorBase.js"; +import type { JsonValue } from "./jsonValue.js"; import { ParseFailureError } from "./parseFailure.js"; /** A parse limit of `format`; any other cause, or another format's limit, is not one. */ @@ -25,8 +26,8 @@ const reportedRequired = (required: number | bigint): number | string => * the failure's detail (prefixed with `Selected artifact :` when `path` * names one) and `reportedLimits` comes from the failure's `LimitRef` * (`{ boundary: name, maximum, required? }`), so neither is spelled again at - * the catch site. Existing contracts may select their established field for - * the maximum. The producer supplies recovery for its own budget. + * the catch site. Existing contracts may keep context fields and select their + * established field for the maximum. The producer supplies budget recovery. */ export const parseLimitConstraint = ( operation: string, @@ -36,15 +37,14 @@ export const parseLimitConstraint = ( ResourceConstraintRecovery & { readonly path?: string | undefined; readonly legacyMaximumKey?: string; + readonly reportedLimitContext?: Readonly>; readonly requestSent?: boolean; }, ): AnalysisResourceConstraintError => { const { detail, limit } = cause.failure; - const { path, legacyMaximumKey, ...errorOptions } = options; - return new AnalysisResourceConstraintError( - operation, - resource, - path === undefined ? detail : `Selected artifact ${path}: ${detail}`, + const { path, legacyMaximumKey, reportedLimitContext, ...errorOptions } = + options; + const reportedLimit = legacyMaximumKey === undefined ? { boundary: limit.name, @@ -53,7 +53,12 @@ export const parseLimitConstraint = ( ? {} : { required: reportedRequired(limit.required) }), } - : { [legacyMaximumKey]: limit.maximum }, + : { [legacyMaximumKey]: limit.maximum }; + return new AnalysisResourceConstraintError( + operation, + resource, + path === undefined ? detail : `Selected artifact ${path}: ${detail}`, + { ...reportedLimitContext, ...reportedLimit }, { ...errorOptions, cause }, ); }; diff --git a/src/erlang/BeamParser.test.ts b/src/erlang/BeamParser.test.ts index de722942af..5a2b53a8dd 100644 --- a/src/erlang/BeamParser.test.ts +++ b/src/erlang/BeamParser.test.ts @@ -14,7 +14,7 @@ import { erlangBeamManyAtomsFixture, erlangBeamOtp29Fixture, } from "./Beam.fixture.js"; -import { BeamCapacityFailure, parseErlangBeam } from "./BeamParser.js"; +import { parseErlangBeam } from "./BeamParser.js"; import { BeamProvider } from "./BeamProvider.js"; import { ArtifactResourceScope } from "../resources/ArtifactResourceScope.js"; @@ -316,9 +316,14 @@ it("rejects combined table rows before allocating them", () => { ), ).toThrow( expect.objectContaining({ - reason: "limit", - boundary: "capacity", - message: expect.stringContaining("row budget"), + failure: expect.objectContaining({ + kind: "limit", + limit: { + name: "max_table_rows", + maximum: MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS, + required: MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS + 1, + }, + }), }), ); const complete = Buffer.alloc( @@ -344,17 +349,29 @@ it("rejects combined table rows before allocating them", () => { ); }); -it("fails when the atom budget is exhausted", () => { - const bytes = erlangBeamManyAtomsFixture(3); - expect(() => - parse( - bytes, - inspectErlangBeamInputSchema.parse({ - path: defaults.path, - max_atoms: 1, +it.each([ + { + bytes: erlangBeamManyAtomsFixture(3), + limit: { name: "max_atoms", maximum: 1, required: 3 }, + }, + { + bytes: erlangBeamFixture(), + limit: { name: "max_chunks", maximum: 1 }, + }, +])("retains the exhausted $limit.name allowance", ({ bytes, limit }) => { + const input = inspectErlangBeamInputSchema.parse({ + path: defaults.path, + [limit.name]: limit.maximum, + }); + expect(() => parse(bytes, input)).toThrow( + expect.objectContaining({ + failure: expect.objectContaining({ + kind: "limit", + format: "beam", + limit, }), - ), - ).toThrow(ArtifactReaderFailure); + }), + ); }); it("does not infer a BEAM budget from diagnostic prose", async () => { @@ -382,72 +399,6 @@ it("does not infer a BEAM budget from diagnostic prose", async () => { } }); -it.each([ - { - resource: "atoms", - bytes: erlangBeamManyAtomsFixture(3), - settings: { max_atoms: 1 }, - maximum: 1, - remediation: "Raise max_atoms above 1", - }, - { - resource: "chunks", - bytes: erlangBeamFixture(), - settings: { max_chunks: 1 }, - maximum: 1, - remediation: "Raise max_chunks above 1", - }, - { - resource: "table-rows", - bytes: erlangBeamRowsFixture([ - ["ExpT", MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS + 1], - ]), - settings: {}, - maximum: MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS, - remediation: `${String(MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS)}-row ceiling`, - }, -])( - "retains the producing $resource allowance when diagnostic wording changes", - async ({ resource, bytes, settings, maximum, remediation }) => { - const input = inspectErlangBeamInputSchema.parse({ - path: defaults.path, - ...settings, - }); - let cause: unknown; - try { - parse(bytes, input); - } catch (failure) { - cause = failure; - } - expect(cause).toBeInstanceOf(BeamCapacityFailure); - if (!(cause instanceof BeamCapacityFailure)) - throw new Error("Missing named parser allowance"); - expect(cause).toMatchObject({ - resource, - maximum, - reason: "limit", - boundary: "capacity", - }); - cause.message = "BEAM parser allowance exhausted."; - const provider = new BeamProvider(); - const injection = vi - .spyOn(ArtifactResourceScope.prototype, "run") - .mockRejectedValueOnce(cause); - try { - const result = await provider.inspect(input); - if (result.ok) throw new Error("Expected named capacity failure"); - expect(result.error).toMatchObject({ - _tag: "AnalysisResourceConstraintError", - retryable: false, - remediationAction: expect.stringContaining(remediation), - }); - } finally { - injection.mockRestore(); - await provider.close(); - } - }, -); - it.each([ ["Atom", Buffer.from([0, 0, 0, 1, 1, 0x61])], ["AtU8", Buffer.from([0, 0, 0, 1, 1, 0x61])], diff --git a/src/erlang/BeamParser.ts b/src/erlang/BeamParser.ts index 74ee22a2d8..444d19aff1 100644 --- a/src/erlang/BeamParser.ts +++ b/src/erlang/BeamParser.ts @@ -1,6 +1,7 @@ import { isUtf8 } from "node:buffer"; import { ArtifactReaderFailure } from "../resources/index.js"; import { BinaryReader } from "../domain/binaryContainer.js"; +import { decodeLimit } from "../domain/parseFailure.js"; import { MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS, type ErlangBeam, @@ -8,18 +9,6 @@ import { } from "../domain/erlang/beam.js"; import { sha256Hex } from "../kernel/sha256Hex.js"; -/** The producing parser names its count allowance independently of diagnostic text. */ -export class BeamCapacityFailure extends ArtifactReaderFailure { - constructor( - readonly resource: "atoms" | "chunks" | "table-rows", - readonly maximum: number, - message: string, - ) { - super("limit", message, { boundary: "capacity" }); - this.name = "BeamCapacityFailure"; - } -} - const fail = (message: string): never => { throw new ArtifactReaderFailure("format", message); }; @@ -139,10 +128,10 @@ const parseAtoms = ( // Reject an impossible table before treating its count as a budget refusal. if (count > payload.length - 4) fail("BEAM atom table is truncated."); if (count > maxAtoms) - throw new BeamCapacityFailure( - "atoms", - maxAtoms, + throw decodeLimit( + "beam", `BEAM atom table exceeds the ${String(maxAtoms)}-atom budget.`, + { name: "max_atoms", maximum: maxAtoms, required: count }, ); const atoms: NonNullable = []; let at = 4; @@ -244,10 +233,10 @@ export const parseErlangBeam = ( const padded = payloadOffset + size + ((4 - (size % 4)) % 4); if (padded > formEnd) fail("BEAM chunk padding exceeds the form."); if (chunks.length >= input.max_chunks) - throw new BeamCapacityFailure( - "chunks", - input.max_chunks, + throw decodeLimit( + "beam", `BEAM form exceeds the ${String(input.max_chunks)}-chunk budget.`, + { name: "max_chunks", maximum: input.max_chunks }, ); const name = form.range(at, 4, "BEAM chunk name").toString("latin1"); const payload = form.range(payloadOffset, size, "BEAM chunk payload"); @@ -299,16 +288,19 @@ export const parseErlangBeam = ( lambdaChunk === undefined || lambdaChunk.payload.length === 0 ? null : frameRows(lambdaChunk.payload, 6, "lambda"); - if ( + const tableRows = (exportTable?.count ?? 0) + - (importTable?.count ?? 0) + - (lambdaTable?.count ?? 0) > - MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS - ) - throw new BeamCapacityFailure( - "table-rows", - MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS, + (importTable?.count ?? 0) + + (lambdaTable?.count ?? 0); + if (tableRows > MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS) + throw decodeLimit( + "beam", `BEAM tables exceed the ${String(MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS)}-row budget.`, + { + name: "max_table_rows", + maximum: MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS, + required: tableRows, + }, ); const exports = exportTable === null diff --git a/src/erlang/BeamProvider.ts b/src/erlang/BeamProvider.ts index f4c2f6a1d5..ed1dd40091 100644 --- a/src/erlang/BeamProvider.ts +++ b/src/erlang/BeamProvider.ts @@ -27,7 +27,12 @@ import { type InspectErlangBeamInput, } from "../domain/erlang/beam.js"; import { err, ok } from "../domain/result.js"; -import { BeamCapacityFailure, parseErlangBeam } from "./BeamParser.js"; +import type { LimitRef } from "../domain/parseFailure.js"; +import { + isParseLimit, + parseLimitConstraint, +} from "../domain/parseFailureAnalysisError.js"; +import { parseErlangBeam } from "./BeamParser.js"; const OPERATION = "inspect_erlang_beam"; @@ -77,27 +82,25 @@ export class BeamProvider implements BeamPort { } } -const inputBudgetRemediation = ( - cause: ArtifactReaderFailure, - input: InspectErlangBeamInput, -): string | undefined => { - if (cause.boundary === "file-size") - return input.max_file_bytes >= MAX_INSPECT_ERLANG_BEAM_FILE_BYTES - ? `The file exceeds the ${String(MAX_INSPECT_ERLANG_BEAM_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.`; - if (!(cause instanceof BeamCapacityFailure)) return undefined; - switch (cause.resource) { - case "atoms": - return cause.maximum >= MAX_INSPECT_ERLANG_BEAM_ATOMS +const fileBudgetRemediation = (maximum: number): string => + maximum >= MAX_INSPECT_ERLANG_BEAM_FILE_BYTES + ? `The file exceeds the ${String(MAX_INSPECT_ERLANG_BEAM_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 parserBudgetRemediation = ({ name, maximum }: LimitRef) => { + switch (name) { + case "max_atoms": + return maximum >= MAX_INSPECT_ERLANG_BEAM_ATOMS ? `The file exceeds the ${String(MAX_INSPECT_ERLANG_BEAM_ATOMS)}-atom ceiling this operation accepts; select a smaller artifact.` - : `Raise max_atoms above ${String(cause.maximum)} or select a smaller artifact; the limit is the caller-selected atom budget.`; - case "table-rows": - return `The file exceeds the ${String(cause.maximum)}-row ceiling this operation accepts; select a smaller artifact.`; - case "chunks": - return cause.maximum >= MAX_INSPECT_ERLANG_BEAM_CHUNKS + : `Raise max_atoms above ${String(maximum)} or select a smaller artifact; the limit is the caller-selected atom budget.`; + case "max_table_rows": + return `The file exceeds the ${String(maximum)}-row ceiling this operation accepts; select a smaller artifact.`; + case "max_chunks": + return maximum >= MAX_INSPECT_ERLANG_BEAM_CHUNKS ? `The file exceeds the ${String(MAX_INSPECT_ERLANG_BEAM_CHUNKS)}-chunk ceiling this operation accepts; select a smaller artifact.` - : `Raise max_chunks above ${String(cause.maximum)} or select a smaller artifact; the limit is the caller-selected chunk budget.`; + : `Raise max_chunks above ${String(maximum)} or select a smaller artifact; the limit is the caller-selected chunk budget.`; } + return undefined; }; const beamFailurePrimary = ( @@ -111,29 +114,39 @@ const beamFailurePrimary = ( input.path, ); if (identityFailure !== undefined) return identityFailure; + const reportedLimits = { + max_file_bytes: input.max_file_bytes, + max_chunks: input.max_chunks, + max_atoms: input.max_atoms, + }; + if (origin === "owned-or-classified" && isParseLimit(cause, "beam")) { + const { limit } = cause.failure; + const remediationAction = parserBudgetRemediation(limit); + return parseLimitConstraint(OPERATION, "capacity", cause, { + reportedLimitContext: reportedLimits, + legacyMaximumKey: limit.name, + ...(remediationAction === undefined ? {} : { remediationAction }), + retryable: false, + }); + } if ( origin === "owned-or-classified" && cause instanceof ArtifactReaderFailure ) { if (cause.reason === "limit") { - const remediationAction = inputBudgetRemediation(cause, input); return new AnalysisResourceConstraintError( OPERATION, cause.boundary ?? "memory", cause.message, - { - max_file_bytes: input.max_file_bytes, - max_chunks: input.max_chunks, - max_atoms: input.max_atoms, - }, + reportedLimits, { cause, - ...(remediationAction === undefined - ? {} - : { + ...(cause.boundary === "file-size" + ? { retryable: false, - remediationAction, - }), + remediationAction: fileBudgetRemediation(input.max_file_bytes), + } + : {}), }, ); } diff --git a/tests/boundary/mcp/erlangBeamMcp.test.ts b/tests/boundary/mcp/erlangBeamMcp.test.ts index b887ac774a..d7adc2852b 100644 --- a/tests/boundary/mcp/erlangBeamMcp.test.ts +++ b/tests/boundary/mcp/erlangBeamMcp.test.ts @@ -92,17 +92,19 @@ mcpTest( const { client, session } = await connect(mcp); const root = await createTestTempDirectory("rea-beam-capacity-"); try { - for (const [label, bytes, settings, remediation] of [ + for (const [label, bytes, settings, budget, remediation] of [ [ "atoms", erlangBeamFixture(), { max_atoms: 1 }, + { max_atoms: 1 }, "Raise max_atoms above 1", ], [ "chunks", erlangBeamFixture(), { max_chunks: 1 }, + { max_chunks: 1 }, "Raise max_chunks above 1", ], [ @@ -111,6 +113,7 @@ mcpTest( ["ExpT", MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS + 1], ]), {}, + { max_table_rows: MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS }, `${String(MAX_INSPECT_ERLANG_BEAM_TABLE_ROWS)}-row ceiling`, ], ] as const) { @@ -126,6 +129,7 @@ mcpTest( code: "resource_constraint", retryable: false, remediation: { action: expect.stringContaining(remediation) }, + details: { reported_limits: budget }, }); } } finally {