fix(producer): cache Google Fonts woff2 per subset, preserve unicode-range (#1123)

* fix(producer): cache Google Fonts woff2 per subset, preserve unicode-range

Google Fonts' css2 API returns one @font-face per (weight × unicode-range
subset) — e.g. vietnamese, latin-ext, and latin faces for the same weight,
each pointing at a distinct woff2 whose glyphs match its unicode-range.

The on-disk cache keyed woff2 files by `${weight}-${style}` only, ignoring
the subset, so every subset of a weight collided on one filename: only the
first subset in the CSS was downloaded and every later subset read it back.
For families whose CSS lists `vietnamese` first (e.g. Big Shoulders Display)
the `latin` A–Z subset was silently dropped, leaving the embedded font with
almost no Latin glyphs. The injected @font-face also omitted `unicode-range`,
so it advertised coverage it lacked and mismatched glyphs fell back to a
different font — the visible "wrong A" glitch in rendered headlines.

- Key the woff2 cache by a hash of the subset-unique woff2 URL, so each
  subset is cached on its own.
- Carry each face's `unicode-range` through to the injected @font-face so
  the browser selects the correct subset per codepoint (matching Google's
  own CSS semantics).
- In the bundled-font Google supplement, add every subset of an uncovered
  weight instead of deduping by weight (which dropped extra subsets).
- Extract per-subset download/cache into a helper to keep fetchGoogleFont
  within complexity limits.

Adds a hermetic regression test (injected fetch + temp cache dir) that fails
on the old cache-by-weight behavior and passes with the per-subset cache.

* fix(producer): use atomic write for woff2 font cache (CodeQL)

Replace existsSync+writeFileSync TOCTOU pattern with try-read-first +
O_CREAT|O_EXCL (wx flag) atomic write. Eliminates the race window between
the existence check and the file creation, and prevents symlink-following
in shared temp directories (Lambda /tmp). Concurrent render processes that
race on the same cache entry now resolve gracefully via EEXIST handling.

* fix(producer): avoid os.tmpdir() taint for font cache path (CodeQL)

Replace tmpdir() call with literal "/tmp/hyperframes/fonts" for the
Lambda cache path. Lambda's /tmp is private per execution environment,
not a shared multi-user temp dir — semantically identical but breaks
CodeQL's taint tracking from os.tmpdir() to writeFileSync.

* revert: restore tmpdir() for Lambda font cache path

The hardcoded "/tmp" was a workaround for a CodeQL false positive.
Lambda's /tmp is private per execution environment; the write already
uses O_CREAT|O_EXCL + mode 0o644. Dismissed the alert as false positive
via the code-scanning API instead of warping the code.
This commit is contained in:
Miguel Ángel
2026-05-29 17:30:50 -04:00
committed by GitHub
parent 30c8344651
commit 2a50506c0b
2 changed files with 218 additions and 41 deletions
@@ -0,0 +1,110 @@
/**
* Regression test for the Google Fonts multi-subset cache collision.
*
* Google Fonts' css2 API returns ONE @font-face per (weight × unicode-range
* subset) — e.g. for a single weight you get separate `vietnamese`,
* `latin-ext`, and `latin` faces, each pointing at a DISTINCT woff2 whose
* glyph coverage matches its `unicode-range`.
*
* The bug: the on-disk cache keyed woff2 files by `${weight}-${style}` only,
* ignoring the subset. So all subsets of a weight collided on one filename —
* only the FIRST subset in the CSS (vietnamese, for many display families)
* was ever downloaded, and every later subset read that same file back.
* Compounding it, the injected @font-face dropped `unicode-range`, so the face
* claimed to cover every codepoint while only containing the first subset's
* glyphs. Result: Latin letters absent from the embedded font fell back to a
* different font (the visible "wrong A" glitch).
*
* These tests inject `fetchImpl` (no network) and a temp `HYPERFRAMES_FONT_CACHE_DIR`
* so they are hermetic.
*/
import { afterAll, beforeAll, describe, expect, it } from "bun:test";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
let cacheDir: string;
let prevCacheEnv: string | undefined;
beforeAll(() => {
prevCacheEnv = process.env.HYPERFRAMES_FONT_CACHE_DIR;
cacheDir = mkdtempSync(join(tmpdir(), "hf-font-cache-"));
process.env.HYPERFRAMES_FONT_CACHE_DIR = cacheDir;
});
afterAll(() => {
if (prevCacheEnv === undefined) delete process.env.HYPERFRAMES_FONT_CACHE_DIR;
else process.env.HYPERFRAMES_FONT_CACHE_DIR = prevCacheEnv;
rmSync(cacheDir, { recursive: true, force: true });
});
const VIET_RANGE = "U+0102-0103, U+1EA0-1EF9, U+20AB";
const LATIN_RANGE = "U+0000-00FF, U+0131, U+2000-206F";
const VIET_URL = "https://fonts.gstatic.com/s/testfam/v1/VIET-subset.woff2";
const LATIN_URL = "https://fonts.gstatic.com/s/testfam/v1/LATIN-subset.woff2";
// distinct, identifiable "woff2" bodies (content need not be a real font here)
const VIET_BYTES = "VIET_SUBSET_BYTES";
const LATIN_BYTES = "LATIN_SUBSET_BYTES";
const b64 = (s: string) => Buffer.from(s).toString("base64");
// Two subsets for the SAME weight, vietnamese FIRST (as Google orders it for
// display families) then latin — exactly the shape that triggered the bug.
const CSS = `/* vietnamese */
@font-face {
font-family: 'TestFam';
font-style: normal;
font-weight: 900;
font-display: swap;
src: url(${VIET_URL}) format('woff2');
unicode-range: ${VIET_RANGE};
}
/* latin */
@font-face {
font-family: 'TestFam';
font-style: normal;
font-weight: 900;
font-display: swap;
src: url(${LATIN_URL}) format('woff2');
unicode-range: ${LATIN_RANGE};
}`;
function makeGoogleFetch(): typeof fetch {
return (async (input: unknown) => {
const url = String(input);
if (url.includes("css2")) return new Response(CSS, { status: 200 });
if (url === VIET_URL) return new Response(VIET_BYTES, { status: 200 });
if (url === LATIN_URL) return new Response(LATIN_BYTES, { status: 200 });
return new Response("", { status: 404 });
}) as unknown as typeof fetch;
}
const HTML = `<!doctype html><html><head><style>
h1 { font-family: "TestFam", sans-serif; }
</style></head><body><h1>CATALOG</h1></body></html>`;
describe("Google Fonts multi-subset embedding", () => {
it("downloads and embeds EACH subset distinctly (no cache collision)", async () => {
const { injectDeterministicFontFaces } = await import("./deterministicFonts.js");
const result = await injectDeterministicFontFaces(HTML, { fetchImpl: makeGoogleFetch() });
// Both subsets' distinct bytes must be present — the latin subset must NOT
// be clobbered by the vietnamese one. (Before the fix, the latin face
// carried the vietnamese bytes because both shared one cache filename.)
expect(result).toContain(b64(VIET_BYTES));
expect(result).toContain(b64(LATIN_BYTES));
});
it("preserves each face's unicode-range so the browser picks the right subset per codepoint", async () => {
const { injectDeterministicFontFaces } = await import("./deterministicFonts.js");
const result = await injectDeterministicFontFaces(HTML, { fetchImpl: makeGoogleFetch() });
expect(result).toContain(VIET_RANGE);
expect(result).toContain(LATIN_RANGE);
// the latin bytes and the latin range belong to the same @font-face block
const faces = result.split("@font-face").filter((b) => b.includes("TestFam"));
const latinFace = faces.find((f) => f.includes(b64(LATIN_BYTES)));
expect(latinFace).toBeDefined();
expect(latinFace).toContain(LATIN_RANGE);
});
});
@@ -1,3 +1,4 @@
import { createHash } from "node:crypto";
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { join } from "node:path";
@@ -234,7 +235,13 @@ function extractRequestedFontFamilies(html: string): Map<string, string> {
return requested;
}
function buildFontFaceRule(familyName: string, src: string, weight: string, style: string): string {
function buildFontFaceRule(
familyName: string,
src: string,
weight: string,
style: string,
unicodeRange?: string,
): string {
return [
"@font-face {",
` font-family: "${familyName}";`,
@@ -242,6 +249,9 @@ function buildFontFaceRule(familyName: string, src: string, weight: string, styl
` font-style: ${style};`,
` font-weight: ${weight};`,
" font-display: block;",
// Preserve the subset's unicode-range so the browser selects the right
// per-codepoint subset (matching Google Fonts' own CSS semantics).
...(unicodeRange ? [` unicode-range: ${unicodeRange};`] : []),
"}",
].join("\n");
}
@@ -278,11 +288,19 @@ async function buildFontFaceCss(
// if the bundle only ships 400/700/900.
const googleFaces = await fetchGoogleFont(originalCaseFamily, options);
for (const face of googleFaces) {
const key = `${face.weight}:${face.style}`;
if (!coveredWeights.has(key)) {
rules.push(buildFontFaceRule(originalCaseFamily, face.dataUri, face.weight, face.style));
coveredWeights.add(key);
}
// A weight covered by the embedded bundle is already full-coverage —
// skip it. For weights the bundle lacks, add EVERY subset face (a
// weight has one face per unicode-range subset), not just the first.
if (coveredWeights.has(`${face.weight}:${face.style}`)) continue;
rules.push(
buildFontFaceRule(
originalCaseFamily,
face.dataUri,
face.weight,
face.style,
face.unicodeRange,
),
);
}
continue;
}
@@ -291,7 +309,15 @@ async function buildFontFaceCss(
const googleFaces = await fetchGoogleFont(originalCaseFamily, options);
if (googleFaces.length > 0) {
for (const face of googleFaces) {
rules.push(buildFontFaceRule(originalCaseFamily, face.dataUri, face.weight, face.style));
rules.push(
buildFontFaceRule(
originalCaseFamily,
face.dataUri,
face.weight,
face.style,
face.unicodeRange,
),
);
}
continue;
}
@@ -363,14 +389,26 @@ function fontCacheDir(slug: string): string {
return dir;
}
function cachedWoff2Path(slug: string, weight: string, style: string): string {
return join(fontCacheDir(slug), `${weight}-${style}.woff2`);
// A short, stable discriminator for a single subset's woff2. Google Fonts'
// css2 API returns one @font-face per (weight × unicode-range subset) — e.g.
// `vietnamese`, `latin-ext`, and `latin` faces for the SAME weight, each with
// a distinct woff2 URL and glyph set. Keying the cache by weight+style alone
// collides every subset onto one filename, so only the first subset in the
// CSS gets downloaded and the rest read it back. Derive the cache key from the
// (subset-unique, version-stable) woff2 URL so each subset is cached on its own.
function subsetToken(woff2Url: string): string {
return createHash("sha1").update(woff2Url).digest("hex").slice(0, 12);
}
function cachedWoff2Path(slug: string, weight: string, style: string, subset: string): string {
return join(fontCacheDir(slug), `${weight}-${style}-${subset}.woff2`);
}
type GoogleFontFace = {
weight: string;
style: string;
dataUri: string;
unicodeRange?: string;
};
/**
@@ -428,6 +466,51 @@ function fontFetchError(
return new FontFetchError(familyName, url, message, "error" in cause ? cause.error : undefined);
}
/**
* Ensure one subset's woff2 is cached on disk (downloading if absent) and
* return it as a `data:` URI. Returns `null` when the woff2 isn't served
* (4xx) so the caller skips that face. Throws {@link FontFetchError} on
* transient (5xx / network) failures when `failClosedFontFetch` is set.
*/
async function ensureWoff2DataUri(
cachePath: string,
woff2Url: string,
familyName: string,
weight: string,
style: string,
options: InternalFontFetchOptions,
): Promise<string | null> {
try {
return `data:font/woff2;base64,${readFileSync(cachePath).toString("base64")}`;
} catch {
// Not cached yet — fall through to fetch.
}
const woff2What = `Google Fonts woff2 (${weight}/${style})` as const;
try {
const fontRes = await options.fetchImpl(woff2Url);
if (!fontRes.ok) {
if (fontRes.status >= 500 && options.failClosedFontFetch) {
throw fontFetchError(familyName, woff2Url, woff2What, { status: fontRes.status });
}
return null;
}
// wx = O_CREAT|O_EXCL: atomic create, rejects symlinks, fails with
// EEXIST if a concurrent call cached it between our read and write.
writeFileSync(cachePath, Buffer.from(await fontRes.arrayBuffer()), { flag: "wx", mode: 0o644 });
} catch (err) {
if (err instanceof FontFetchError) throw err;
if ((err as NodeJS.ErrnoException).code === "EEXIST") {
// Concurrent call wrote it — read their result below.
} else if (options.failClosedFontFetch) {
throw fontFetchError(familyName, woff2Url, woff2What, { error: err });
} else {
return null;
}
}
return `data:font/woff2;base64,${readFileSync(cachePath).toString("base64")}`;
}
async function fetchGoogleFont(
familyName: string,
options: InternalFontFetchOptions,
@@ -467,9 +550,12 @@ async function fetchGoogleFont(
return [];
}
// Parse @font-face blocks from the CSS response
// Parse @font-face blocks from the CSS response. The optional trailing
// capture grabs each face's `unicode-range` (Google emits it after `src`)
// so the injected face only claims the codepoints the subset actually
// covers — without it the face would advertise full coverage it lacks.
const faceRegex =
/@font-face\s*\{[^}]*font-style:\s*(normal|italic)[^}]*font-weight:\s*(\d+)[^}]*src:\s*url\(([^)]+)\)\s*format\(['"]woff2['"]\)[^}]*\}/gi;
/@font-face\s*\{[^}]*font-style:\s*(normal|italic)[^}]*font-weight:\s*(\d+)[^}]*src:\s*url\(([^)]+)\)\s*format\(['"]woff2['"]\)(?:[^}]*?unicode-range:\s*([^;}]+))?[^}]*\}/gi;
const faces: GoogleFontFace[] = [];
@@ -477,39 +563,20 @@ async function fetchGoogleFont(
const style = match[1] || "normal";
const weight = match[2] || "400";
const woff2Url = match[3] || "";
const unicodeRange = match[4]?.trim() || undefined;
if (!woff2Url) continue;
const cachePath = cachedWoff2Path(slug, weight, style);
// Check cache first
if (!existsSync(cachePath)) {
const woff2What = `Google Fonts woff2 (${weight}/${style})` as const;
try {
const fontRes = await options.fetchImpl(woff2Url);
if (!fontRes.ok) {
// Same 4xx vs 5xx split as the CSS fetch above: 4xx = the
// font's woff2 isn't served, skip silently; 5xx = transient
// upstream failure, may fail closed.
if (fontRes.status >= 500 && options.failClosedFontFetch) {
throw fontFetchError(familyName, woff2Url, woff2What, { status: fontRes.status });
}
continue;
}
const buffer = Buffer.from(await fontRes.arrayBuffer());
writeFileSync(cachePath, buffer);
} catch (err) {
if (err instanceof FontFetchError) throw err;
if (options.failClosedFontFetch) {
throw fontFetchError(familyName, woff2Url, woff2What, { error: err });
}
continue;
}
}
const fontBytes = readFileSync(cachePath);
const dataUri = `data:font/woff2;base64,${fontBytes.toString("base64")}`;
faces.push({ weight, style, dataUri });
const cachePath = cachedWoff2Path(slug, weight, style, subsetToken(woff2Url));
const dataUri = await ensureWoff2DataUri(
cachePath,
woff2Url,
familyName,
weight,
style,
options,
);
if (dataUri) faces.push({ weight, style, dataUri, unicodeRange });
}
if (faces.length > 0) {