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
This commit is contained in:
morluto authored and GitHub committed 2026-11-19 12:36:54 +00:00
1 parent 96dae7de70
commit daf5e91f39
6 files changed
+114 -146

No files matched your search

+4 -1
View File
@@ -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.
+13 -8
View File
@@ -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 <path>:` 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<Record<string, JsonValue>>;
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 },
);
};
+31 -80
View File
@@ -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])],
+18 -26
View File
@@ -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<ErlangBeam["atoms"]> = [];
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
+43 -30
View File
@@ -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),
}
: {}),
},
);
}
+5 -1
View File
@@ -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 {