imgtune 0.2.0 → 0.3.0

package/dist/resources/compression.js

@@ -0,0 +1,122 @@
+// Transfer compression: text-like responses served with no Content-Encoding. The saving is the body's length minus its
+// brotli-11 length (a real encode; a body over SAMPLE_BYTES is encoded in part and extrapolated, labelled an estimate).
+// Findings are grouped per host and content type: one server or CDN setting covers the group.
+import { brotliCompressSync, constants } from "node:zlib";
+import { digestOf, heavyValue } from "./cache.js";
+/** Responses smaller than this are not worth a setting: the saving is below a packet. */
+export const MIN_BYTES = 1024;
+/** A body longer than this is brotli-encoded on its first SAMPLE_BYTES only, and the rest is extrapolated. */
+export const SAMPLE_BYTES = 1024 * 1024;
+/** A group saves less than this in total: no finding. */
+const MIN_SAVED = 1024;
+const MAX_URLS = 10;
+/**
+ * The brotli size of a text body as a share of its size, for a file whose body the scan did not keep (a body still streaming at
+ * the settle, or over the refetch cap). A typical minified script, style sheet or document lands near this; it is an estimate.
+ */
+export const TYPICAL_BROTLI_RATIO = 0.3;
+const TEXT_APPLICATION = /^application\/(javascript|x-javascript|ecmascript|json|ld\+json|manifest\+json|xml|wasm|x-font-ttf|font-sfnt|x-font-opentype)$/;
+/** Whether a content type is text-like (compressible): text/*, scripts, JSON, XML, SVG, WASM, TTF and OTF fonts. */
+export function isTextLike(contentType) {
+    return contentType.startsWith("text/") || contentType === "image/svg+xml" || TEXT_APPLICATION.test(contentType) || contentType === "font/ttf" || contentType === "font/otf" || contentType === "font/sfnt";
+}
+/**
+ * The brotli-11 size of a body: exact when short, else the sample's ratio applied to the whole (`estimate` true). Over the
+ * run's resource budget it is a quick brotli (quality 4) of the same bytes, also an estimate.
+ */
+export async function brotliSizeOf(body) {
+    const key = `compression:brotli11:${digestOf(body)}`;
+    const measured = await heavyValue(key, async () => {
+        const sampled = body.length > SAMPLE_BYTES;
+        const part = sampled ? body.subarray(0, SAMPLE_BYTES) : body;
+        const out = brotliCompressSync(part, {
+            params: {
+                [constants.BROTLI_PARAM_QUALITY]: constants.BROTLI_MAX_QUALITY,
+                [constants.BROTLI_PARAM_SIZE_HINT]: part.length,
+            },
+        });
+        const bytes = sampled ? Math.round((out.length / part.length) * body.length) : out.length;
+        return { bytes, estimate: sampled };
+    });
+    if (measured !== undefined)
+        return measured;
+    const part = body.length > SAMPLE_BYTES ? body.subarray(0, SAMPLE_BYTES) : body;
+    const quick = brotliCompressSync(part, { params: { [constants.BROTLI_PARAM_QUALITY]: 4, [constants.BROTLI_PARAM_SIZE_HINT]: part.length } });
+    return { bytes: Math.round((quick.length / part.length) * body.length), estimate: true };
+}
+const kb = (bytes) => `${(bytes / 1024).toFixed(0)} KB`;
+function hostOf(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return "unknown host";
+    }
+}
+/** The cheap filter: an uncompressed text-like response of at least MIN_BYTES, successful, under the body cap. */
+export function wantsRecord(r) {
+    return r.contentEncoding === undefined && r.status >= 200 && r.status < 300 && isTextLike(r.contentType) && r.bytes >= MIN_BYTES && r.bytes <= 20 * 1024 * 1024;
+}
+export const analyzer = {
+    kind: "compression",
+    wants: wantsRecord,
+    async analyze(records) {
+        try {
+            const members = [];
+            for (const r of records) {
+                if (!wantsRecord(r))
+                    continue;
+                if (r.body === undefined) {
+                    // No body: the headers and the size decide the finding, and the brotli size is estimated (never claimed as measured).
+                    const brotli = Math.round(r.bytes * TYPICAL_BROTLI_RATIO);
+                    members.push({ url: r.url, host: hostOf(r.url), contentType: r.contentType, bytes: r.bytes, saved: Math.max(0, r.bytes - brotli), brotli, estimate: true });
+                    continue;
+                }
+                const { bytes: brotli, estimate } = await brotliSizeOf(r.body);
+                const bytes = r.body.length;
+                members.push({ url: r.url, host: hostOf(r.url), contentType: r.contentType, bytes, saved: Math.max(0, bytes - brotli), brotli, estimate });
+            }
+            const groups = new Map();
+            for (const m of members) {
+                const key = `${m.host}\n${m.contentType}`;
+                groups.set(key, [...(groups.get(key) ?? []), m]);
+            }
+            const findings = [];
+            for (const [key, list] of groups) {
+                const saved = list.reduce((sum, m) => sum + m.saved, 0);
+                if (saved < MIN_SAVED)
+                    continue;
+                const bytes = list.reduce((sum, m) => sum + m.bytes, 0);
+                const brotli = list.reduce((sum, m) => sum + m.brotli, 0);
+                const largest = [...list].sort((a, b) => b.bytes - a.bytes);
+                const { host, contentType } = largest[0];
+                const estimate = list.some((m) => m.estimate);
+                findings.push({
+                    id: `compression:${digestOf(key).slice(0, 16)}`,
+                    kind: "compression",
+                    url: largest[0].url,
+                    bytes,
+                    savedBytes: saved,
+                    estimate,
+                    title: `${list.length} ${contentType} file(s) from ${host} sent uncompressed: ${kb(bytes)}, brotli would send ${kb(brotli)} (saves ~${kb(saved)})`,
+                    fix: [
+                        `enable brotli (or gzip) for ${contentType} responses from ${host} at the server or CDN (nginx: \`brotli on; brotli_types ${contentType};\` or \`gzip on; gzip_types ${contentType};\`)`,
+                        `expected: ${kb(brotli)} per view for these files (brotli 11), from ${kb(bytes)}`,
+                    ],
+                    details: {
+                        host,
+                        contentType,
+                        files: list.length,
+                        bytes,
+                        brotliBytes: brotli,
+                        urls: largest.slice(0, MAX_URLS).map((m) => m.url),
+                    },
+                });
+            }
+            return findings.sort((a, b) => b.savedBytes - a.savedBytes);
+        }
+        catch {
+            return [];
+        }
+    },
+};

package/dist/resources/favicon.js

@@ -0,0 +1,130 @@
+// Favicons and apple-touch-icons. A favicon over FAVICON_BYTES, or an apple-touch-icon over APPLE_BYTES, is flagged. The
+// fix is a re-encode at the size the browser uses (32 px for a favicon, 180 px for apple-touch), and the saving is the
+// real size of that re-encode (sharp, PNG). An ICO is read through its largest PNG frame. Favicons are fetched once per
+// site, so every title says "per first visit".
+import sharp from "sharp";
+import { cachedValue, digestOf } from "./cache.js";
+export const FAVICON_BYTES = 10 * 1024;
+export const APPLE_BYTES = 30 * 1024;
+/** The largest icon response read at all (an icon this size is already the problem). */
+export const ICON_READ_MAX = 1024 * 1024;
+const FAVICON_PX = 32;
+const APPLE_PX = 180;
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+const kb = (bytes) => `${(bytes / 1024).toFixed(1)} KB`;
+/** The icon roles the page declares, by absolute URL: apple-touch for an apple-touch-icon link, else favicon. */
+export function roleOf(ctx, url) {
+    const link = ctx.icons.find((icon) => icon.href === url);
+    if (link !== undefined)
+        return /apple-touch/i.test(link.rel) ? "apple-touch" : "favicon";
+    if (/\/favicon\.ico$/i.test(new URL(url).pathname))
+        return "favicon";
+    return undefined;
+}
+/** The largest PNG frame of an ICO file, or undefined when it has none (BMP-only icons are not decoded). */
+export function largestPngFrame(ico) {
+    if (ico.length < 6 || ico.readUInt16LE(0) !== 0 || ico.readUInt16LE(2) !== 1)
+        return undefined;
+    const count = ico.readUInt16LE(4);
+    let best;
+    for (let i = 0; i < count; i++) {
+        const at = 6 + i * 16;
+        if (at + 16 > ico.length)
+            break;
+        const w = ico[at] === 0 ? 256 : ico[at];
+        const h = ico[at + 1] === 0 ? 256 : ico[at + 1];
+        const size = ico.readUInt32LE(at + 8);
+        const offset = ico.readUInt32LE(at + 12);
+        if (offset + size > ico.length || size < 8)
+            continue;
+        const data = ico.subarray(offset, offset + size);
+        if (!data.subarray(0, 4).equals(PNG_MAGIC))
+            continue;
+        if (best === undefined || w * h > best.area)
+            best = { area: w * h, data };
+    }
+    return best?.data;
+}
+/** The image the browser decodes from an icon response: the PNG frame of an ICO, else the body itself. */
+function decodableOf(record, body) {
+    const isIco = record.contentType === "image/x-icon" || record.contentType === "image/vnd.microsoft.icon" || body.subarray(0, 4).equals(Buffer.from([0, 0, 1, 0]));
+    if (!isIco)
+        return body;
+    return largestPngFrame(body);
+}
+/** The PNG of the icon at `px` square, and its width and height before (the source's size from the decoder). */
+async function reencode(image, px) {
+    const key = `favicon:png:${px}:${digestOf(image)}`;
+    return cachedValue(key, async () => {
+        const meta = await sharp(image).metadata();
+        const out = await sharp(image).resize(px, px, { fit: "cover" }).png({ compressionLevel: 9 }).toBuffer();
+        return { bytes: out.length, width: px, height: px, sourceWidth: meta.width ?? 0, sourceHeight: meta.height ?? 0 };
+    });
+}
+export const wantsRecord = (r) => r.status >= 200 &&
+    r.status < 300 &&
+    r.contentType.startsWith("image/") &&
+    r.bytes <= ICON_READ_MAX &&
+    (r.contentType.includes("icon") || /favicon|apple-touch-icon/i.test(r.url) || /\.ico(?:[?#]|$)/i.test(r.url));
+export const analyzer = {
+    kind: "favicon",
+    wants: wantsRecord,
+    async analyze(records, ctx) {
+        try {
+            const findings = [];
+            for (const r of records) {
+                if (r.body === undefined)
+                    continue;
+                const role = roleOf(ctx, r.url);
+                if (role === undefined)
+                    continue;
+                const threshold = role === "apple-touch" ? APPLE_BYTES : FAVICON_BYTES;
+                if (r.bytes <= threshold)
+                    continue;
+                const px = role === "apple-touch" ? APPLE_PX : FAVICON_PX;
+                const label = role === "apple-touch" ? "apple-touch-icon" : "favicon";
+                const path = new URL(r.url).pathname;
+                const isSvg = r.contentType === "image/svg+xml";
+                const frame = isSvg ? undefined : decodableOf(r, r.body);
+                let measured;
+                if (frame !== undefined) {
+                    try {
+                        measured = await reencode(frame, px);
+                    }
+                    catch {
+                        measured = undefined;
+                    }
+                }
+                const source = measured !== undefined && measured.sourceWidth > 0 ? `${measured.sourceWidth}x${measured.sourceHeight}` : "unreadable";
+                const saved = measured === undefined ? 0 : Math.max(0, r.bytes - measured.bytes);
+                const fix = [];
+                if (isSvg) {
+                    fix.push("serve it as an optimised SVG (svgo, default preset) or a 32 px PNG; an SVG icon scales at every size");
+                }
+                else {
+                    fix.push(measured !== undefined
+                        ? `replace with a ${px}x${px} PNG (sharp resize ${px}, fit cover, PNG compression 9): ${kb(measured.bytes)} (from ${kb(r.bytes)})`
+                        : `replace with a ${px}x${px} PNG: the file is not decodable here (an ICO with no PNG frame, or not an image)`);
+                    if (role === "favicon")
+                        fix.push(`or an SVG favicon when the logo is vector: <link rel="icon" type="image/svg+xml" href="/icon.svg">`);
+                }
+                fix.push(`point the <link rel="${role === "apple-touch" ? "apple-touch-icon" : "icon"}"> at the new file; it is fetched once per site, on a first visit`);
+                findings.push({
+                    id: `favicon:${digestOf(r.url).slice(0, 16)}`,
+                    kind: "favicon",
+                    url: r.url,
+                    bytes: r.bytes,
+                    savedBytes: saved,
+                    estimate: false,
+                    title: `${label} ${path}: ${source}${isSvg ? " SVG" : ""}, ${kb(r.bytes)} per first visit${measured !== undefined ? `; a ${px} px PNG is ${kb(measured.bytes)}` : ""}`,
+                    fix,
+                    details: { role, source, px, bytes: r.bytes, rebuiltBytes: measured?.bytes ?? null },
+                });
+            }
+            return findings;
+        }
+        catch {
+            return [];
+        }
+    },
+};