fix(gguf): reserve framing for fields after metadata values (#12338)

fix(model): reserve GGUF framing for required later fields
This commit is contained in:
morluto authored and GitHub committed 2026-11-19 13:01:44 +00:00
1 parent 15150b017a
commit 6b65e63dfe
3 files changed
+130 -16

No files matched your search

+3
View File
@@ -257,6 +257,9 @@ The reader admits one active inspection per provider. It enforces a 100,000,000
byte header ceiling (safetensors counts its declared JSON bytes separately from
the fixed eight-byte length prefix; GGUF counts the complete header) and a separate 32 MiB
retained representation budget before retaining rows or expanding strings.
GGUF checks that a declared string leaves room for the minimum framing of
later metadata rows, tensor descriptors and array elements before charging
its representation budget.
Numeric products use exact integer arithmetic. GGUF follows its four-dimensional
tensor layout and limits metadata array nesting to 32 frames. Resource refusals
are typed, rather than returned as complete empty inventories. Cancellation
+45 -16
View File
@@ -35,7 +35,10 @@ const NAMES = [
"INT64",
"FLOAT64",
] as const;
const WIDTHS = [1, 1, 2, 2, 4, 4, 4, 1, 8, 12, 8, 8, 8];
const STRING_LENGTH_BYTES = 8;
const WIDTHS = [1, 1, 2, 2, 4, 4, 4, 1, STRING_LENGTH_BYTES, 12, 8, 8, 8];
const MIN_METADATA_ROW_BYTES = STRING_LENGTH_BYTES + 4 + 1;
const MIN_TENSOR_DESCRIPTOR_BYTES = STRING_LENGTH_BYTES + 4 + 4 + 8;
export interface GgufProgress {
onHeader(info: {
@@ -71,11 +74,15 @@ export class GgufHeader {
return (await this.#field(width)).word(0, width === 4 ? 32 : 64);
}
async #text(retain: boolean, maximum?: number): Promise<string> {
const rawLength = await this.#unsigned(8);
async #text(
retain: boolean,
requiredAfter: number,
maximum?: number,
): Promise<string> {
const rawLength = await this.#unsigned(STRING_LENGTH_BYTES);
if (maximum !== undefined && rawLength > BigInt(maximum))
rejectModel("GGUF name exceeds its format byte limit");
this.reader.guarantee(rawLength);
this.reader.guarantee(rawLength + BigInt(requiredAfter));
const length = Number(rawLength);
if (retain) this.#budget.charge(6 * length + 2);
// Omitted preview entries still need validation, but not decoded strings.
@@ -109,6 +116,7 @@ export class GgufHeader {
async #value(
type: number,
retain: boolean,
requiredAfter: number,
enclosingFrames = 0,
): Promise<{
value: JsonValue;
@@ -116,11 +124,13 @@ export class GgufHeader {
element_count: number | null;
complete: boolean;
}> {
if (NAMES[type] === undefined)
const width = WIDTHS[type];
if (width === undefined)
rejectModel(`Unknown GGUF metadata type ${String(type)}`);
this.reader.guarantee(width + requiredAfter);
if (type === 8)
return {
value: await this.#text(retain),
value: await this.#text(retain, requiredAfter),
element_type: null,
element_count: null,
complete: true,
@@ -139,7 +149,7 @@ export class GgufHeader {
const minimum = WIDTHS[element];
if (minimum === undefined)
rejectModel(`Unknown GGUF array element type ${String(element)}`);
this.reader.guarantee(rawCount * BigInt(minimum));
this.reader.guarantee(rawCount * BigInt(minimum) + BigInt(requiredAfter));
const count = Number(rawCount);
const preview: JsonValue[] = [];
if (retain)
@@ -147,7 +157,6 @@ export class GgufHeader {
let complete = count <= MODEL_ARRAY_PREVIEW;
for (let index = 0; index < count; index++) {
if (index % 4096 === 4095) await setImmediate();
this.reader.guarantee((count - index) * minimum);
if (
element !== 8 &&
element !== 9 &&
@@ -164,7 +173,12 @@ export class GgufHeader {
break;
}
const keep = retain && index < MODEL_ARRAY_PREVIEW;
const value = await this.#value(element, keep, frames);
const value = await this.#value(
element,
keep,
(count - index - 1) * minimum + requiredAfter,
frames,
);
if (keep)
preview.push(
element === 9
@@ -186,7 +200,7 @@ export class GgufHeader {
complete,
};
}
const b = await this.#field(WIDTHS[type] ?? 0);
const b = await this.#field(width);
let value: JsonValue;
switch (type) {
case 0:
@@ -273,7 +287,9 @@ export class GgufHeader {
rejectModel("Big-endian GGUF requires version 3");
const rawTensorCount = await this.#unsigned(8);
const rawMetadataCount = await this.#unsigned(8);
const minimumDirectoryBytes = rawTensorCount * 24n + rawMetadataCount * 13n;
const minimumDirectoryBytes =
rawTensorCount * BigInt(MIN_TENSOR_DESCRIPTOR_BYTES) +
rawMetadataCount * BigInt(MIN_METADATA_ROW_BYTES);
this.reader.requireFileExtent(this.reader.position, minimumDirectoryBytes);
const tensorCount = Number(rawTensorCount);
const metadataCount = Number(rawMetadataCount);
@@ -288,10 +304,16 @@ export class GgufHeader {
const metadata: ModelMetadata[] = [];
const keys = new Set<string>();
let alignment = 32;
let remainingDirectoryBytes = Number(minimumDirectoryBytes);
for (let index = 0; index < metadataCount; index++) {
this.reader.guarantee((metadataCount - index) * 13 + tensorCount * 24);
this.reader.guarantee(remainingDirectoryBytes);
remainingDirectoryBytes -= MIN_METADATA_ROW_BYTES;
const start = this.reader.position;
const key = await this.#text(true, 65535);
const key = await this.#text(
true,
remainingDirectoryBytes + MIN_METADATA_ROW_BYTES - STRING_LENGTH_BYTES,
65535,
);
// Numeric hierarchy components occur in standardized base_model.{id} keys.
if (
!/^[a-z0-9]+(?:[_-][a-z0-9]+)*(?:\.[a-z0-9]+(?:[_-][a-z0-9]+)*)*$/u.test(
@@ -304,7 +326,7 @@ export class GgufHeader {
if (keys.has(key)) rejectModel(`Duplicate GGUF metadata key ${key}`);
keys.add(key);
const type = Number(await this.#unsigned(4));
const parsed = await this.#value(type, true);
const parsed = await this.#value(type, true, remainingDirectoryBytes);
const row = {
index,
key,
@@ -345,9 +367,16 @@ export class GgufHeader {
progress?.onLimitation(message);
};
for (let index = 0; index < tensorCount; index++) {
this.reader.guarantee((tensorCount - index) * 24);
this.reader.guarantee(remainingDirectoryBytes);
remainingDirectoryBytes -= MIN_TENSOR_DESCRIPTOR_BYTES;
const start = this.reader.position;
const name = await this.#text(true, 64);
const name = await this.#text(
true,
remainingDirectoryBytes +
MIN_TENSOR_DESCRIPTOR_BYTES -
STRING_LENGTH_BYTES,
64,
);
if (names.has(name)) rejectModel(`Duplicate GGUF tensor name ${name}`);
names.add(name);
const dimensions = Number(await this.#unsigned(4));
@@ -1221,6 +1221,88 @@ it("retains GGUF representation capacity when declared string bytes can fit", as
});
});
it.each([
"metadata row",
"tensor descriptor",
"array element",
"outer array sibling",
] as const)(
"checks required GGUF %s framing before charging a large string",
async (following) => {
const seed = ggufFixture({ tensors: [] });
const largeStringBytes = 6_000_000;
const stringLength = seed.u64(BigInt(largeStringBytes));
const twoStrings = Buffer.concat([seed.u32(8), seed.u64(2n)]);
const array =
following === "array element" || following === "outer array sibling";
const outer = following === "outer array sibling";
const prefix = ggufFixture({
tensors: [],
metadata: [
{
key: "custom.value",
type: array ? 9 : 8,
value: Buffer.concat([
...(outer ? [seed.u32(9), seed.u64(2n)] : []),
...(array ? [twoStrings] : []),
stringLength,
]),
},
],
}).header;
if (following === "metadata row") prefix.writeBigUInt64LE(2n, 16);
if (following === "tensor descriptor") prefix.writeBigUInt64LE(1n, 8);
const stringEnd = prefix.length + largeStringBytes;
const emptyString = seed.text("");
const tail = {
"metadata row": Buffer.concat([
seed.text("custom.tail"),
seed.u32(0),
Buffer.from([1]),
]),
"tensor descriptor": Buffer.concat([
seed.text("weight"),
seed.u32(1),
seed.u64(1n),
seed.u32(0),
seed.u64(0n),
]),
"array element": emptyString,
"outer array sibling": Buffer.concat([
emptyString,
seed.u32(8),
seed.u64(0n),
]),
}[following];
const { provider, path } = await providerAt(prefix);
const handle = await open(path, "r+");
try {
// For nested arrays the immediate string sibling fits. Only the outer
// array's second element is missing, so its minimum must propagate.
if (outer)
await handle.write(emptyString, 0, emptyString.length, stringEnd);
else await handle.truncate(stringEnd);
const malformed = await provider.inspect({ path, hash: "header" });
if (malformed.ok) throw new Error("Missing GGUF framing was accepted");
expect.soft(malformed.error).toMatchObject(INVALID_FORMAT);
await handle.write(tail, 0, tail.length, stringEnd);
if (following === "tensor descriptor")
await handle.truncate(
Math.ceil((stringEnd + tail.length) / 32) * 32 + 4,
);
const limited = await provider.inspect({ path, hash: "header" });
if (limited.ok) throw new Error("Oversized representation was accepted");
expect(limited.error).toMatchObject({
_tag: "AnalysisResourceConstraintError",
reportedLimits: { maximum_representation_bytes: MODEL_REPORT_BYTES },
});
} finally {
await handle.close();
}
},
);
it("retains GGUF representation capacity when the declared directory can fit", async () => {
const header = Buffer.alloc(24);
header.write("GGUF");