refactor(il2cpp): report format failures through ParseFailure (#10701)

This commit is contained in:
morluto authored and GitHub committed 2026-11-14 21:11:29 -05:00
1 parent cd5ea9a9fb
commit 3a29b6b8ea
12 files changed
+150 -42

No files matched your search

+50 -13
View File
@@ -1,3 +1,5 @@
import { ParseFailureError } from "../domain/parseFailure.js";
/** Existing selected-binary allowance also bounds its retained pointer workspace. */
export const IL2CPP_BINARY_BYTES = 1024 * 1024 * 1024;
@@ -29,24 +31,59 @@ export const IL2CPP_BINARY_FAILURE_REASONS = {
export type Il2cppBinaryFailureReason =
(typeof IL2CPP_BINARY_FAILURE_REASONS)[keyof typeof IL2CPP_BINARY_FAILURE_REASONS][number];
/** A named workspace budget; the parse stopped without showing the input invalid. */
export type Il2cppBinaryCapacityReason =
(typeof IL2CPP_BINARY_FAILURE_REASONS.capacity)[number];
type Il2cppBinaryFormatReason = Exclude<
Il2cppBinaryFailureReason,
Il2cppBinaryCapacityReason
>;
/** A native image REA cannot link, either outside coverage or inconsistent with the metadata. */
export class Il2cppBinaryFormatFailure extends Error {
readonly kind: "unsupported" | "malformed" | "capacity";
/** The ParseFailure format of a native image linked against IL2CPP metadata. */
export const IL2CPP_BINARY_FORMAT = "il2cpp-binary";
const isUnsupported = (reason: Il2cppBinaryFormatReason) =>
(IL2CPP_BINARY_FAILURE_REASONS.unsupported as readonly string[]).includes(
reason,
);
/**
* A native image REA cannot link, either outside coverage or inconsistent
* with the metadata. The stable `reason` names the IL2CPP rule; a capacity
* reason is a ParseFailure `limit` carrying the exceeded maximum.
*/
export class Il2cppBinaryFormatFailure extends ParseFailureError<
"malformed" | "unsupported" | "limit"
> {
constructor(reason: Il2cppBinaryFormatReason, message: string);
constructor(
reason: Il2cppBinaryCapacityReason,
message: string,
maximum: number,
);
constructor(
readonly reason: Il2cppBinaryFailureReason,
message: string,
maximum?: number,
) {
super(`${reason}: ${message}`);
const detail = `${reason}: ${message}`;
super(
maximum !== undefined
? {
kind: "limit",
format: IL2CPP_BINARY_FORMAT,
detail,
limit: { name: reason, maximum },
}
: isUnsupported(reason as Il2cppBinaryFormatReason)
? {
kind: "unsupported",
format: IL2CPP_BINARY_FORMAT,
detail,
undecodedContent: false,
}
: { kind: "malformed", format: IL2CPP_BINARY_FORMAT, detail },
);
this.name = "Il2cppBinaryFormatFailure";
this.kind = (
IL2CPP_BINARY_FAILURE_REASONS.unsupported as readonly string[]
).includes(reason)
? "unsupported"
: (IL2CPP_BINARY_FAILURE_REASONS.capacity as readonly string[]).includes(
reason,
)
? "capacity"
: "malformed";
}
}
+1 -1
View File
@@ -366,7 +366,7 @@ export function* linkGenericMethodsSteps(
// Capacity is a budget refusal, never a fact about this row.
if (
!(cause instanceof Il2cppBinaryFormatFailure) ||
cause.kind === "capacity"
cause.kind === "limit"
)
throw cause;
issue(row, specAt, cause.message);
+11 -2
View File
@@ -93,6 +93,7 @@ export function* openImageSteps(image: Buffer): Generator<void, NativeImage> {
throw new Il2cppBinaryFormatFailure(
"native-index-capacity",
cause.message,
cause.failure.limit.maximum,
);
if (cause instanceof BinaryFormatFailure)
throw new Il2cppBinaryFormatFailure(
@@ -124,8 +125,16 @@ export function* openImageSteps(image: Buffer): Generator<void, NativeImage> {
IL2CPP_BINARY_BYTES,
);
} catch (cause) {
if (cause instanceof ElfPointerRelocationFailure)
throw new Il2cppBinaryFormatFailure(cause.reason, cause.message);
if (cause instanceof ElfPointerRelocationFailure) {
if (cause.reason !== "native-index-capacity")
throw new Il2cppBinaryFormatFailure(cause.reason, cause.message);
if (cause.maximum !== undefined)
throw new Il2cppBinaryFormatFailure(
cause.reason,
cause.message,
cause.maximum,
);
}
if (cause instanceof BinaryFormatFailure)
throw new Il2cppBinaryFormatFailure("malformed-container", cause.message);
throw cause;
+6 -2
View File
@@ -111,7 +111,8 @@ function* nameAddresses(
if (Buffer.byteLength(name) > TOTAL_NAME_OCCURRENCES)
throw new Il2cppBinaryFormatFailure(
"native-index-capacity",
"module-name trie exceeds its65536-node workspace",
`module-name trie exceeds its ${TOTAL_NAME_OCCURRENCES}-node workspace`,
TOTAL_NAME_OCCURRENCES,
);
let node = root;
const bytes = Buffer.from(name, "utf8");
@@ -122,7 +123,8 @@ function* nameAddresses(
if (nodes >= TOTAL_NAME_OCCURRENCES)
throw new Il2cppBinaryFormatFailure(
"native-index-capacity",
"module-name trie exceeds its65536-node workspace",
`module-name trie exceeds its ${TOTAL_NAME_OCCURRENCES}-node workspace`,
TOTAL_NAME_OCCURRENCES,
);
next = { next: new Map(), owners: [] };
node.next.set(bytes[at]!, next);
@@ -162,6 +164,7 @@ function* nameAddresses(
throw new Il2cppBinaryFormatFailure(
"native-index-capacity",
`native name-address index exceeds ${TOTAL_NAME_OCCURRENCES} entries`,
TOTAL_NAME_OCCURRENCES,
);
found.set(address, node.owners);
}
@@ -531,6 +534,7 @@ function* findModuleArrayByCode(
throw new Il2cppBinaryFormatFailure(
"native-index-capacity",
`module-array index exceeds ${MODULE_ARRAY_CANDIDATES} entries`,
MODULE_ARRAY_CANDIDATES,
);
}
}
+2
View File
@@ -106,6 +106,7 @@ const createTypeRenderer = (
throw new Il2cppBinaryFormatFailure(
"native-type-text-capacity",
`rendered type text workspace exceeds ${TYPE_TEXT_BYTES} UTF-8 bytes`,
TYPE_TEXT_BYTES,
);
beforeText?.(bytes);
};
@@ -131,6 +132,7 @@ const createTypeRenderer = (
throw new Il2cppBinaryFormatFailure(
"type-nesting-capacity",
`type rendering exceeds ${TYPE_DEPTH} nested frames`,
TYPE_DEPTH,
);
active.add(address);
try {
+37 -12
View File
@@ -15,26 +15,47 @@ export const IL2CPP_METADATA_FAILURE_REASONS = {
"invalid-string",
],
} as const;
export type Il2cppMetadataFailureKind =
keyof typeof IL2CPP_METADATA_FAILURE_REASONS;
export type Il2cppMetadataFailureReason =
(typeof IL2CPP_METADATA_FAILURE_REASONS)[Il2cppMetadataFailureKind][number];
(typeof IL2CPP_METADATA_FAILURE_REASONS)[keyof typeof IL2CPP_METADATA_FAILURE_REASONS][number];
/** Distinguish inputs outside decoder coverage from damaged metadata. */
export class Il2cppMetadataFormatFailure extends Error {
readonly kind: Il2cppMetadataFailureKind;
/** The ParseFailure format of an IL2CPP `global-metadata.dat`. */
export const IL2CPP_METADATA_FORMAT = "il2cpp-metadata";
const metadataFailure = (
reason: Il2cppMetadataFailureReason,
detail: string,
): ParseFailure & {
readonly kind: "malformed" | "truncated" | "unsupported";
} =>
(IL2CPP_METADATA_FAILURE_REASONS.unsupported as readonly string[]).includes(
reason,
)
? {
kind: "unsupported",
format: IL2CPP_METADATA_FORMAT,
detail,
undecodedContent: false,
}
: {
kind: reason === "truncated-header" ? "truncated" : "malformed",
format: IL2CPP_METADATA_FORMAT,
detail,
};
/**
* Distinguish inputs outside decoder coverage from damaged metadata. The
* stable `reason` names the IL2CPP rule the bytes broke.
*/
export class Il2cppMetadataFormatFailure extends ParseFailureError<
"malformed" | "truncated" | "unsupported"
> {
constructor(
readonly reason: Il2cppMetadataFailureReason,
message: string,
options?: ErrorOptions,
) {
super(`${reason}: ${message}`, options);
super(metadataFailure(reason, `${reason}: ${message}`), options);
this.name = "Il2cppMetadataFormatFailure";
this.kind = (
IL2CPP_METADATA_FAILURE_REASONS.unsupported as readonly string[]
).includes(reason)
? "unsupported"
: "corrupt";
}
}
@@ -84,3 +105,7 @@ export const readIndex = (bytes: Buffer, offset: number, width: 1 | 2 | 4) => {
return bytes.readInt32LE(offset);
};
import type { Il2cppMetadataSection } from "../domain/il2cpp/il2cppMetadata.js";
import {
ParseFailureError,
type ParseFailure,
} from "../domain/parseFailure.js";
+1 -1
View File
@@ -83,7 +83,7 @@ const failureForPrimary = (
const { cause, origin } = facts;
if (origin === "owned-or-classified" && cause instanceof AnalysisError)
return cause;
if (cause instanceof Il2cppBinaryFormatFailure && cause.kind === "capacity")
if (cause instanceof Il2cppBinaryFormatFailure && cause.kind === "limit")
return new AnalysisResourceConstraintError(
OPERATION,
cause.reason === "native-type-text-capacity" ? "memory" : "capacity",