From cfab299c9a8dca59b419560b7472f37d5d34c51c Mon Sep 17 00:00:00 2001 From: ci-check Date: Wed, 18 Nov 2026 20:16:20 +0800 Subject: [PATCH 1/2] docs(image-rescale): reconcile the forced-path trigger-gate comments with the code MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The two comments describing shedDownscaleImage's forced path contradicted each other and both misstated the code: - The doRescale header comment claimed "A within-maxDim image is NOT skipped here" — wrong for below-trigger within-maxDim images, which ARE skipped. - The shedDownscaleImage doc claimed "there is no trigger gate ... images already within maxDim are left alone" — wrong for above-trigger within- maxDim images, which ARE re-encoded (adopted only if strictly smaller). The code (doRescale gate) is correct: the 100 KiB trigger gate applies ONLY to within-maxDim images as a cheap pre-filter (skip small, re-encode large); above-maxDim images are always re-encoded. Both comments now state the actual truth table. Adds a regression test pinning both gate directions (#3617): below-trigger within-maxDim is skipped, above-trigger within-maxDim is re-encoded and adopted. Closes #7150 --- src/image-rescale.ts | 22 ++++++++++++++-------- tests/image-rescale-cache-budget.test.ts | 16 ++++++++++++++++ 2 files changed, 30 insertions(+), 8 deletions(-) diff --git a/src/image-rescale.ts b/src/image-rescale.ts index b8d1c54332..d8c1218f67 100644 --- a/src/image-rescale.ts +++ b/src/image-rescale.ts @@ -149,10 +149,14 @@ function loadJimp(): Promise { return jimpLoad; } -// force (#3701 byte-shed ladder): skips the 100 KiB trigger gate and adopts ANY -// strict byte reduction (not just <80%). A within-maxDim image is NOT skipped -// here — a same-dim re-encode is adopted only if strictly smaller; the byte-shed -// caller pre-filters maxDim-fitting images before calling (egress-shed rung B). +// force (#3701 byte-shed ladder): adopts ANY strict byte reduction (not just <80%). +// Above-maxDim images are always re-encoded (downscaled) — no trigger gate. For +// within-maxDim images the 100 KiB trigger gate IS applied as a cheap pre-filter: +// an image at/below the trigger is skipped (re-encoding a small image rarely pays), +// while one above it is re-encoded at the same dims and adopted only if strictly +// smaller. The byte-shed caller pre-filters maxDim-fitting images before calling +// (egress-shed rung B), so the within-maxDim branch is defensive — only hit when the +// header dim parse disagrees with the authoritative Jimp.read decode. async function doRescale(mime: RescaledMime, b64: string, origBytes: number, maxDim: number, force = false): Promise { try { const mod = await loadJimp(); @@ -220,10 +224,12 @@ export function clearRescaleEncodeCache(maxBytesForTest = ENCODE_CACHE_MAX_BYTES } /** #3701 byte-shed ladder step: forced re-encode at an explicit longest-edge dim. - * Unlike rescaleImage there is no trigger gate and no keep-ratio floor — any strict - * reduction is adopted; images already within maxDim are left alone. Returns the new - * base64 (same mime) or null when nothing was saved (unsupported format, jimp absent, - * or the re-encode did not shrink). Cached per hash+dim. */ + * Unlike rescaleImage there is no keep-ratio floor — any strict reduction is adopted. + * Above-maxDim images are always re-encoded (downscaled). Within-maxDim images are + * skipped at/below the 100 KiB trigger (cheap pre-filter) and re-encoded at the same + * dims above it, adopted only if strictly smaller. Returns the new base64 (same mime) + * or null when nothing was saved (unsupported format, jimp absent, at/below the + * trigger, or the re-encode did not shrink). Cached per hash+dim. */ export async function shedDownscaleImage(mediaType: string, b64: string, maxDim: number): Promise { const mime = normalizeMime(mediaType); if (!mime || typeof b64 !== "string" || b64.length === 0 || !Number.isFinite(maxDim) || maxDim <= 0) return null; diff --git a/tests/image-rescale-cache-budget.test.ts b/tests/image-rescale-cache-budget.test.ts index 8fe5b6f501..7d10f3c4ad 100644 --- a/tests/image-rescale-cache-budget.test.ts +++ b/tests/image-rescale-cache-budget.test.ts @@ -151,3 +151,19 @@ test("a normal reset restores the production budget after a test override", asyn await shedDownscaleImage("image/png", input(0), 1); assert.equal(reads, 3, "the default reset restores normal cache admission"); }); + +test("forced within-maxDim: the 100 KiB trigger gate skips small, re-encodes large", async (t) => { + // A 1x1 image is within maxDim=1 (scale=1, no downscale). The forced path's + // trigger gate is a cheap pre-filter: below-trigger images are skipped entirely + // (no decode/re-encode), above-trigger images are re-encoded at the same dims and + // adopted only if strictly smaller. Pins both directions (#3617). + const pixels = new Jimp({ width: 1, height: 1 }); + t.mock.method(pixels, "getBuffer", async () => Buffer.alloc(8)); + t.mock.method(Jimp, "read", async () => pixels); + + const below = "a".repeat(136532); // b64Bytes = 102399, below the 100 KiB trigger + const above = "a".repeat(136536); // b64Bytes = 102402, above the trigger + + assert.equal(await shedDownscaleImage("image/png", below, 1), null, "below trigger is skipped"); + assert.equal(await shedDownscaleImage("image/png", above, 1), Buffer.alloc(8).toString("base64"), "above trigger is re-encoded and adopted"); +}); From 0108a5bc0cc64dc4ed64b33f87900d3a19e6ba53 Mon Sep 17 00:00:00 2001 From: ci-check Date: Wed, 18 Nov 2026 20:41:56 +0800 Subject: [PATCH 2/2] docs(image-rescale): name the parse-failure case in the forced-path gate comment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The rung B pre-filter (egress-shed) only skips KNOWN-dim within-maxDim images (dims !== undefined && max <= dim), so the defensive within-maxDim branch is also hit when the header dim parse FAILS (dims === undefined) and the decode shows within-maxDim — not only when the parse disagrees with the decode. Align the comment with that exact condition. --- src/image-rescale.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/image-rescale.ts b/src/image-rescale.ts index d8c1218f67..08ad202749 100644 --- a/src/image-rescale.ts +++ b/src/image-rescale.ts @@ -154,9 +154,9 @@ function loadJimp(): Promise { // within-maxDim images the 100 KiB trigger gate IS applied as a cheap pre-filter: // an image at/below the trigger is skipped (re-encoding a small image rarely pays), // while one above it is re-encoded at the same dims and adopted only if strictly -// smaller. The byte-shed caller pre-filters maxDim-fitting images before calling -// (egress-shed rung B), so the within-maxDim branch is defensive — only hit when the -// header dim parse disagrees with the authoritative Jimp.read decode. +// smaller. The byte-shed caller pre-filters known-dim maxDim-fitting images before +// calling (egress-shed rung B), so the within-maxDim branch is defensive — only hit +// when the header dim parse fails or disagrees with the authoritative Jimp.read decode. async function doRescale(mime: RescaledMime, b64: string, origBytes: number, maxDim: number, force = false): Promise { try { const mod = await loadJimp();