Skip to content

Write HTML. Render video. Built for agents.

feat(fonts): record resolver stage diagnostics on fail-closed font errors (#5189)

Jerrai0c76e5244647
diff --git a/packages/core/src/fonts/deterministicFonts-diagnostics.test.ts b/packages/core/src/fonts/deterministicFonts-diagnostics.test.ts
new file mode 100644
index 0000000000..8eeebce5fd
--- /dev/null
+++ b/packages/core/src/fonts/deterministicFonts-diagnostics.test.ts
@@ -0,0 +1,455 @@
+// @vitest-environment node
+
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+ _clearGoogleFontCssCacheForTests,
+ FONT_FETCH_FAILED,
+ FONT_FETCH_UNAVAILABLE,
+ FontFetchError,
+ injectDeterministicFontFaces,
+} from "./deterministicFonts.js";
+import type { FontAttemptDiag, FontDiagnostics } from "./fontDiagnostics.js";
+
+const FAMILY = "Bricolage Grotesque";
+const PAGE_TEXT = "quick brown fox";
+const PRIVATE_FAMILY = "PRIVATE_FONT_SENTINEL_7f3a";
+const WOFF2 = new Uint8Array([0x77, 0x4f, 0x46, 0x32, 1, 2, 3]);
+
+const block = (family = FAMILY, fmt = "woff2", n = 0): string =>
+ `/* latin */\n@font-face {\n font-family: '${family}';\n font-style: normal;\n font-weight: 200 800;\n src: url(https://fonts.gstatic.com/s/b/v9/f${n}.woff2) format('${fmt}');\n unicode-range: U+0000-00FF;\n}\n`;
+const blocks = (count: number, family = FAMILY, fmt = "woff2"): string =>
+ Array.from({ length: count }, (_, n) => block(family, fmt, n)).join("\n");
+const urlLessBlocks = `/* latin */\n@font-face {\n font-family: '${FAMILY}';\n font-style: normal;\n font-weight: 200 800;\n unicode-range: U+0000-00FF;\n}\n/* latin-ext */\n@font-face {\n font-family: '${FAMILY}';\n font-style: normal;\n font-weight: 200 800;\n}\n`;
+
+type Rule = (url: string) => Response | Promise<Response>;
+interface Stub {
+ css: string[];
+ woff2: string[];
+ fetchImpl: typeof fetch;
+}
+const status = (code: number): Response => new Response("x", { status: code });
+const ok = (body: string): Response => new Response(body, { status: 200 });
+function stub(css: Rule, woff: Rule = () => new Response(WOFF2, { status: 200 })): Stub {
+ const cssUrls: string[] = [];
+ const woff2Urls: string[] = [];
+ const fetchImpl: typeof fetch = async (input) => {
+ const url = String(input);
+ if (url.startsWith("https://fonts.gstatic.com/")) {
+ woff2Urls.push(url);
+ return woff(url);
+ }
+ cssUrls.push(url);
+ return css(url);
+ };
+ return { css: cssUrls, woff2: woff2Urls, fetchImpl };
+}
+
+const POLICY = { maxAttempts: 2, baseDelayMs: 0, attemptTimeoutMs: 2000, maxElapsedMs: 8000 };
+const page = (extraCss = ""): string =>
+ `<!doctype html><html><head><style>.a{font-family:'${FAMILY}',sans-serif;font-weight:700}${extraCss}</style></head><body><p class="a">The ${PAGE_TEXT} jumps.</p></body></html>`;
+
+async function fail(html: string, s: Stub, abortSignal?: AbortSignal): Promise<FontFetchError> {
+ try {
+ await injectDeterministicFontFaces(html, {
+ failClosedFontFetch: true,
+ allowSystemFontCapture: false,
+ fetchImpl: s.fetchImpl,
+ abortSignal,
+ fontFetchRetryPolicy: POLICY,
+ logger: { info: () => undefined, warn: () => undefined },
+ });
+ } catch (err) {
+ if (err instanceof FontFetchError) return err;
+ throw err;
+ }
+ throw new Error("expected FontFetchError");
+}
+
+function diagnosticsOf(e: FontFetchError): FontDiagnostics {
+ if (!e.diagnostics) throw new Error("expected diagnostics");
+ return e.diagnostics;
+}
+
+const attempt = (o: Partial<FontAttemptDiag> = {}): FontAttemptDiag => ({
+ path: "direct_google",
+ urlSource: "default",
+ textParam: "present",
+ cssCache: "fresh",
+ cssStatus: 200,
+ blocksTotal: 0,
+ regexMatches: 0,
+ assets: { total: 0, diskCacheHit: 0, fetchedOk: 0, nonOk: {} },
+ ...o,
+});
+const diagOf = (attempts: FontAttemptDiag[]): FontDiagnostics => ({
+ families: [{ required: true, resolved: false, attempts }],
+});
+
+beforeEach(() => {
+ process.env.HYPERFRAMES_FONT_CACHE_DIR = mkdtempSync(join(tmpdir(), "hf-dp-cache-"));
+ _clearGoogleFontCssCacheForTests();
+});
+
+const ROWS: Array<{ name: string; css: Rule; woff?: Rule; expected: FontAttemptDiag }> = [
+ { name: "CSS 400", css: () => status(400), expected: attempt({ cssStatus: 400 }) },
+ {
+ name: "CSS 204 empty body keeps the real status",
+ css: () => new Response(null, { status: 204 }),
+ expected: attempt({ cssStatus: 204 }),
+ },
+ {
+ name: "CSS 206 empty body keeps the real status",
+ css: () => new Response("", { status: 206 }),
+ expected: attempt({ cssStatus: 206 }),
+ },
+ {
+ name: "CSS 304 keeps the real status",
+ css: () => new Response(null, { status: 304 }),
+ expected: attempt({ cssStatus: 304 }),
+ },
+ {
+ name: "CSS 200 zero regex matches (woff2-variations label)",
+ css: () => ok(blocks(2, FAMILY, "woff2-variations")),
+ expected: attempt({ blocksTotal: 2 }),
+ },
+ {
+ name: "CSS 200 blocks without a url",
+ css: () => ok(urlLessBlocks),
+ expected: attempt({ blocksTotal: 2 }),
+ },
+ {
+ name: "CSS 200 all faces dropped by the family filter",
+ css: () => ok(blocks(2, "DM Sans")),
+ expected: attempt({ blocksTotal: 2, regexMatches: 2 }),
+ },
+ {
+ name: "CSS ok, all woff2 404",
+ css: () => ok(blocks(3)),
+ woff: () => status(404),
+ expected: attempt({
+ blocksTotal: 3,
+ regexMatches: 3,
+ assets: { total: 3, diskCacheHit: 0, fetchedOk: 0, nonOk: { "404": 3 } },
+ }),
+ },
+];
+
+describe("exact attempt record on the Unresolved error", () => {
+ for (const { name, css, woff, expected } of ROWS) {
+ it(name, async () => {
+ const e = await fail(page(), stub(css, woff));
+ expect(e.diagnostics).toEqual(diagOf([expected]));
+ });
+ }
+
+ it("leaves the pre-existing error contract unchanged", async () => {
+ const e = await fail(
+ page(),
+ stub(() => status(400)),
+ );
+ expect(e.message).toBe(
+ `[Compiler] Unresolved fonts in fail-closed mode: ${FAMILY}. Distributed renders require all fonts to be resolvable.`,
+ );
+ expect(e.code).toBe(FONT_FETCH_FAILED);
+ expect(e.name).toBe("FontFetchError");
+ expect(e.familyName).toBe(FAMILY);
+ expect(e.unresolvedFamilies).toEqual([FAMILY]);
+ });
+
+ it("a cached second failure records a cache hit with the retained status and no new request", async () => {
+ const s = stub(() => status(400));
+ const e1 = await fail(page(), s);
+ const e2 = await fail(page(), s);
+ expect(s.css.length).toBe(1);
+ expect(e1.diagnostics).toEqual(diagOf([attempt({ cssStatus: 400, cssCache: "fresh" })]));
+ expect(e2.diagnostics).toEqual(diagOf([attempt({ cssStatus: 400, cssCache: "hit" })]));
+ });
+});
+
+describe("shared CSS lookups", () => {
+ it("concurrent compiles each record their own attempt: one fresh, one hit, one upstream request", async () => {
+ const s = stub(async () => {
+ await new Promise((r) => setTimeout(r, 25));
+ return status(400);
+ });
+ const [e1, e2] = await Promise.all([fail(page(), s), fail(page(), s)]);
+ expect(s.css.length).toBe(1);
+ const caches = [e1, e2].map((e) => diagnosticsOf(e).families[0]?.attempts[0]?.cssCache);
+ expect(caches.sort()).toEqual(["fresh", "hit"]);
+ for (const e of [e1, e2]) {
+ expect(diagnosticsOf(e).families[0]?.attempts[0]?.cssStatus).toBe(400);
+ }
+ });
+
+ it("a retryable 503 keeps its UNAVAILABLE error and carries no diagnostics", async () => {
+ const s = stub(async () => {
+ await new Promise((r) => setTimeout(r, 25));
+ return status(503);
+ });
+ const errors = await Promise.all([fail(page(), s), fail(page(), s)]);
+ for (const e of errors) {
+ expect(e.code).toBe(FONT_FETCH_UNAVAILABLE);
+ expect(e.name).toBe("FontFetchUnavailableError");
+ expect(e.diagnostics).toBeUndefined();
+ }
+ });
+});
+
+describe("families", () => {
+ it("lists every family in resolver order with its required and resolved flags", async () => {
+ const html = page(
+ ".b{font-family:var(--none, 'Zzz Example')}.i{font-family:'Inter',sans-serif}",
+ );
+ const e = await fail(
+ html,
+ stub(() => status(400)),
+ );
+ const families = diagnosticsOf(e).families;
+ expect(families.map((f) => [f.required, f.resolved])).toEqual([
+ [true, false],
+ [true, true],
+ [false, false],
+ ]);
+ expect(families[0]?.attempts[0]?.path).toBe("direct_google");
+ expect(families[1]?.attempts[0]?.path).toBe("bundled_supplement");
+ });
+
+ it("carries flags in resolver order while unresolvedFamilies stays sorted by name", async () => {
+ const html = `<!doctype html><html><head><style>.z{font-family:'Zzz Required Font',sans-serif}.i{font-family:'Inter',sans-serif}.o{font-family:var(--none, 'Aaa Optional Font')}</style></head><body><p class="z i o">${PAGE_TEXT}</p></body></html>`;
+ const e = await fail(
+ html,
+ stub(() => status(400)),
+ );
+ expect(diagnosticsOf(e).families.map((f) => [f.required, f.resolved])).toEqual([
+ [true, false],
+ [true, true],
+ [false, false],
+ ]);
+ expect(e.message).toBe(
+ "[Compiler] Unresolved fonts in fail-closed mode: Zzz Required Font. Distributed renders require all fonts to be resolvable.",
+ );
+ expect(e.code).toBe(FONT_FETCH_FAILED);
+ expect(e.familyName).toBe("Zzz Required Font");
+ expect(e.unresolvedFamilies).toEqual(["Aaa Optional Font", "Zzz Required Font"]);
+ expect(JSON.stringify(e.diagnostics)).not.toMatch(/Aaa|Zzz/);
+ });
+
+ it("two required families failing at different stages stay indistinguishable by name", async () => {
+ const html = `<!doctype html><html><head><style>.z{font-family:'Zzz Required Font',sans-serif}.a{font-family:'Aaa Required Font',sans-serif}</style></head><body><p class="z a">${PAGE_TEXT}</p></body></html>`;
+ const e = await fail(
+ html,
+ stub((url) =>
+ url.includes("Aaa") ? status(400) : ok(blocks(2, FAMILY, "woff2-variations")),
+ ),
+ );
+ const families = diagnosticsOf(e).families;
+ expect(families.map((f) => [f.required, f.resolved])).toEqual([
+ [true, false],
+ [true, false],
+ ]);
+ const [first, second] = families.map((f) => f.attempts[0]);
+ expect(first).toEqual(attempt({ blocksTotal: 2 }));
+ expect(second).toEqual(attempt({ cssStatus: 400 }));
+ expect({ ...first, blocksTotal: 0, cssStatus: 400 }).toEqual(second);
+ // The payload cannot say which family produced which attempt.
+ expect(e.message).toBe(
+ "[Compiler] Unresolved fonts in fail-closed mode: Aaa Required Font, Zzz Required Font. Distributed renders require all fonts to be resolvable.",
+ );
+ expect(e.unresolvedFamilies).toEqual(["Aaa Required Font", "Zzz Required Font"]);
+ expect(JSON.stringify(e.diagnostics)).not.toMatch(/Aaa|Zzz/);
+ });
+});
+
+describe("authored stylesheet falling back to the default request", () => {
+ const AUTHORED = "Zorblax Display";
+ const OTHER = "Quillmark Serif";
+ const LINK = `https://fonts.googleapis.com/css2?family=${AUTHORED.replace(" ", "+")}:wght@400;700&display=swap`;
+ const authoredPage = (extraFamily = ""): string =>
+ `<!doctype html><html><head><link rel="stylesheet" href="${LINK}"><style>.a{font-family:'${AUTHORED}',sans-serif}${extraFamily}</style></head><body><p class="a o">The ${PAGE_TEXT} jumps.</p></body></html>`;
+ const isDefault = (url: string): boolean => url.includes("ital,wght@");
+ const authoredAttempt = (o: Partial<FontAttemptDiag> = {}): FontAttemptDiag =>
+ attempt({ urlSource: "authored", ...o });
+
+ it("records the rejected authored stylesheet and then the default attempt that found no usable file", async () => {
+ const e = await fail(
+ authoredPage(),
+ stub(
+ (url) => (isDefault(url) ? ok(blocks(1, AUTHORED)) : status(400)),
+ () => status(404),
+ ),
+ );
+ expect(diagnosticsOf(e).families).toEqual([
+ {
+ required: true,
+ resolved: false,
+ attempts: [
+ authoredAttempt({ cssStatus: 400 }),
+ attempt({
+ blocksTotal: 1,
+ regexMatches: 1,
+ assets: { total: 1, diskCacheHit: 0, fetchedOk: 0, nonOk: { "404": 1 } },
+ }),
+ ],
+ },
+ ]);
+ });
+
+ it("records an authored 200 with zero faces and then the default attempt", async () => {
+ const e = await fail(
+ authoredPage(),
+ stub((url) => (isDefault(url) ? status(400) : ok(blocks(2, AUTHORED, "woff2-variations")))),
+ );
+ expect(diagnosticsOf(e).families[0]?.attempts).toEqual([
+ authoredAttempt({ blocksTotal: 2 }),
+ attempt({ cssStatus: 400 }),
+ ]);
+ });
+
+ it("records no default attempt for a family whose authored stylesheet worked", async () => {
+ const s = stub((url) => {
+ if (url.includes("Quillmark")) return status(400);
+ return ok(blocks(1, AUTHORED));
+ });
+ const e = await fail(authoredPage(`.o{font-family:'${OTHER}',serif}`), s);
+ expect(diagnosticsOf(e).families).toEqual([
+ {
+ required: true,
+ resolved: true,
+ attempts: [
+ authoredAttempt({
+ blocksTotal: 1,
+ regexMatches: 1,
+ assets: { total: 1, diskCacheHit: 0, fetchedOk: 1, nonOk: {} },
+ }),
+ ],
+ },
+ { required: true, resolved: false, attempts: [attempt({ cssStatus: 400 })] },
+ ]);
+ expect(s.css.filter((url) => isDefault(url) && url.includes("Zorblax"))).toEqual([]);
+ });
+
+ it("keeps a transient UNAVAILABLE exactly as before: no default request, no diagnostics", async () => {
+ const s = stub(() => status(503));
+ const e = await fail(authoredPage(), s);
+ expect(e.code).toBe(FONT_FETCH_UNAVAILABLE);
+ expect(e.name).toBe("FontFetchUnavailableError");
+ expect(e.diagnostics).toBeUndefined();
+ expect(s.css.some(isDefault)).toBe(false);
+ });
+
+ it("records both attempts when the authored and default requests both fail, with the error contract unchanged", async () => {
+ const e = await fail(
+ authoredPage(),
+ stub(() => status(400)),
+ );
+ expect(diagnosticsOf(e).families[0]?.attempts).toEqual([
+ authoredAttempt({ cssStatus: 400 }),
+ attempt({ cssStatus: 400 }),
+ ]);
+ expect(e.message).toBe(
+ `[Compiler] Unresolved fonts in fail-closed mode: ${AUTHORED}. Distributed renders require all fonts to be resolvable.`,
+ );
+ expect(e.code).toBe(FONT_FETCH_FAILED);
+ expect(e.name).toBe("FontFetchError");
+ expect(e.familyName).toBe(AUTHORED);
+ expect(e.unresolvedFamilies).toEqual([AUTHORED]);
+ expect(e.url).toBe("");
+ expect(e.cause).toBeUndefined();
+ });
+
+ it("labels both attempts of a repeated compile as cache hits while the first compile's are fresh", async () => {
+ const s = stub(() => status(400));
+ const first = await fail(authoredPage(), s);
+ const second = await fail(authoredPage(), s);
+ expect(s.css.length).toBe(2);
+ expect(diagnosticsOf(first).families[0]?.attempts).toEqual([
+ authoredAttempt({ cssStatus: 400, cssCache: "fresh" }),
+ attempt({ cssStatus: 400, cssCache: "fresh" }),
+ ]);
+ expect(diagnosticsOf(second).families[0]?.attempts).toEqual([
+ authoredAttempt({ cssStatus: 400, cssCache: "hit" }),
+ attempt({ cssStatus: 400, cssCache: "hit" }),
+ ]);
+ });
+});
+
+describe("a lookup joined while another compile's request is in flight", () => {
+ const REQUIRED = "Quillmark Serif";
+ const OPTIONAL = "Zorblax Display";
+ const html = `<!doctype html><html><head><style>.r{font-family:'${REQUIRED}',serif}.o{font-family:var(--none, '${OPTIONAL}')}</style></head><body><p class="r o">The ${PAGE_TEXT} jumps.</p></body></html>`;
+ const drain = (): Promise<void> => new Promise((resolve) => setImmediate(resolve));
+ const until = async (done: () => boolean, what: string): Promise<void> => {
+ for (let turn = 0; turn < 200 && !done(); turn += 1) await drain();
+ if (!done()) throw new Error(`timed out waiting for ${what}`);
+ };
+
+ it("labels the joiner's swallowed optional lookup as a hit with no status", async () => {
+ let release: () => void = () => undefined;
+ const gate = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ let optionalRequests = 0;
+ const s = stub(async (url) => {
+ if (!url.includes("Zorblax")) return status(400);
+ optionalRequests += 1;
+ if (optionalRequests === 1) await gate;
+ return status(503);
+ });
+ // A lookup that awaits a shared promise registers an abort listener on its caller's signal, so
+ // the second compile's listener count shows when it has reached the optional family's lookup.
+ const joiner = new AbortController();
+ const joinerListeners = vi.spyOn(joiner.signal, "addEventListener");
+ try {
+ const first = fail(html, s);
+ await until(() => optionalRequests === 1, "the first compile's optional request");
+ const second = fail(html, s, joiner.signal);
+ await until(
+ () => joinerListeners.mock.calls.length >= 2,
+ "the second compile to await the optional lookup",
+ );
+ expect(optionalRequests).toBe(1);
+ release();
+ const errors = await Promise.all([first, second]);
+
+ expect(optionalRequests).toBe(POLICY.maxAttempts);
+ const optional = errors.map((e) => diagnosticsOf(e).families[1]);
+ expect(optional.map((f) => [f?.required, f?.resolved, f?.attempts.length])).toEqual([
+ [false, false, 1],
+ [false, false, 1],
+ ]);
+ expect(optional.map((f) => f?.attempts[0]?.cssCache)).toEqual(["fresh", "hit"]);
+ expect(optional.map((f) => f?.attempts[0]?.cssStatus)).toEqual([null, null]);
+ for (const e of errors) {
+ expect(e.code).toBe(FONT_FETCH_FAILED);
+ expect(e.message).toBe(
+ `[Compiler] Unresolved fonts in fail-closed mode: ${REQUIRED}. Distributed renders require all fonts to be resolvable.`,
+ );
+ expect(e.url).toBe("");
+ expect(e.cause).toBeUndefined();
+ }
+ } finally {
+ release();
+ }
+ });
+});
+
+describe("leak check", () => {
+ for (const { name, css, woff } of ROWS) {
+ it(`${name}: no family name, URL, CSS, page text or hash in the serialized diagnostics`, async () => {
+ const e = await fail(
+ page(`.b{font-family:var(--n, '${PRIVATE_FAMILY}')}.d{font-family:'${PAGE_TEXT} jumps'}`),
+ stub(css, woff),
+ );
+ const json = JSON.stringify(e.diagnostics);
+ expect(json).not.toMatch(
+ /https?:|gstatic|googleapis|font-face|\.woff2|text=|src:|%[0-9A-Fa-f]{2}|unicode-range|base64|"family"/i,
+ );
+ for (const secret of [FAMILY, PRIVATE_FAMILY, PAGE_TEXT]) {
+ expect(json).not.toContain(secret);
+ }
+ });
+ }
+});
diff --git a/packages/core/src/fonts/deterministicFonts.ts b/packages/core/src/fonts/deterministicFonts.ts
index 8f39998c8e..fbc5be4577 100644
--- a/packages/core/src/fonts/deterministicFonts.ts
+++ b/packages/core/src/fonts/deterministicFonts.ts
@@ -10,6 +10,15 @@ import postcss, { type AtRule, type Declaration, type Rule } from "postcss";
import { EMBEDDED_FONT_DATA } from "./fontData.generated.js";
import { fontToDataUri } from "./fontCompression.js";
import { authoredGoogleFontStylesheets, withPageText } from "./authoredGoogleFonts.js";
+import {
+ FontDiagCollector,
+ type FontAssetDiag,
+ type FontAttemptDiag,
+ type FontDiagnostics,
+ type FontDiagPath,
+} from "./fontDiagnostics.js";
+
+export type { FontDiagnostics };
type FontFaceSpec = {
weight: string;
@@ -697,7 +706,7 @@ async function bundledFamilyFaceRules(
// `emitFamily` so the authored CSS keeps matching.
const canonicalFamily = resolveAliasDisplayName(normalizedFamily);
const googleFaces = canonicalFamily
- ? await fetchFamilyFaces(canonicalFamily, optional, options, fontText)
+ ? await fetchFamilyFaces(canonicalFamily, "bundled_supplement", optional, options, fontText)
: [];
// Bundled weights only cover Latin. Keep other subsets (including
@@ -738,7 +747,13 @@ async function googleFamilyFaceRules(
options: InternalFontFetchOptions,
fontText?: string,
): Promise<string[] | null> {
- const googleFaces = await fetchFamilyFaces(lookupFamily, optional, options, fontText);
+ const googleFaces = await fetchFamilyFaces(
+ lookupFamily,
+ "direct_google",
+ optional,
+ options,
+ fontText,
+ );
if (googleFaces.length === 0) return null;
return googleFaces.map((face) =>
buildFontFaceRule(emitFamily, face.dataUri, face.weight, face.style, face.unicodeRange),
@@ -1011,6 +1026,7 @@ async function buildFontFaceCss(
([, a], [, b]) => Number(a.optional) - Number(b.optional),
);
for (const [normalizedFamily, { family: originalCaseFamily, optional }] of requiredFirst) {
+ options.diag.beginFamily(!optional);
const familyRules =
(await resolveFamilyFaceRules(
normalizedFamily,
@@ -1028,6 +1044,7 @@ async function buildFontFaceCss(
options,
fontText,
));
+ options.diag.endFamily(Boolean(familyRules));
if (familyRules) {
rules.push(...familyRules);
continue;
@@ -1161,6 +1178,11 @@ export class FontFetchError extends Error {
readonly cause?: unknown;
/** Unlike `message`, holds no URLs: safe for callers that must not echo resolver output. */
readonly unresolvedFamilies: readonly string[];
+ /**
+ * Resolver stage record for log forwarding. Set ONLY on the per-compile Unresolved error; shared
+ * (cached or retry-exhausted) errors are never mutated. Never part of `message` or any response body.
+ */
+ declare diagnostics?: FontDiagnostics;
constructor(
familyName: string,
@@ -1220,6 +1242,7 @@ interface InternalFontFetchOptions {
retryDeadlineMs: number;
/** Google stylesheet URL the page already wrote, keyed by normalized family name. */
authoredStylesheets: ReadonlyMap<string, readonly string[]>;
+ diag: FontDiagCollector;
}
/**
@@ -1399,9 +1422,13 @@ async function ensureWoff2DataUri(
weight: string,
style: string,
options: InternalFontFetchOptions,
+ tally: FontAssetDiag,
): Promise<string | null> {
+ tally.total += 1;
try {
- return `data:font/woff2;base64,${readFileSync(cachePath).toString("base64")}`;
+ const cached = `data:font/woff2;base64,${readFileSync(cachePath).toString("base64")}`;
+ tally.diskCacheHit += 1;
+ return cached;
} catch {
// Not cached yet — fall through to fetch.
}
@@ -1416,15 +1443,21 @@ async function ensureWoff2DataUri(
woff2What,
options,
);
- if (!fontResult.ok) return null;
+ if (!fontResult.ok) {
+ const status = String(fontResult.response.status);
+ tally.nonOk[status] = (tally.nonOk[status] ?? 0) + 1;
+ 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(fontResult.body), { flag: "wx", mode: 0o644 });
+ tally.fetchedOk += 1;
} catch (err) {
throwIfCallerAborted(options.abortSignal);
if (err instanceof FontFetchError) throw err;
if ((err as NodeJS.ErrnoException).code === "EEXIST") {
// Concurrent call wrote it — read their result below.
+ tally.diskCacheHit += 1;
} else if (options.failClosedFontFetch) {
throw fontFetchError(familyName, woff2Url, woff2What, { error: err });
} else {
@@ -1437,7 +1470,9 @@ async function ensureWoff2DataUri(
// Per-process cache for Google Fonts CSS lookups, keyed by request URL —
// repeat compiles of the same family reuse one network round trip. A
// rejected lookup evicts itself so a later call still retries.
-type GoogleFontCssResult = { ok: true; body: string } | { ok: false; status: number };
+type GoogleFontCssResult =
+ | { ok: true; body: string; status: number }
+ | { ok: false; status: number };
const googleFontCssCache = new Map<string, Promise<GoogleFontCssResult>>();
@@ -1461,11 +1496,13 @@ function fetchGoogleFontCss(
url: string,
familyName: string,
options: InternalFontFetchOptions,
+ attempt: FontAttemptDiag,
): Promise<GoogleFontCssResult> {
// Retries decide the outcome, so only callers with the same mode and attempt count share an entry.
const mode = options.failClosedFontFetch ? `closed${options.retryPolicy.maxAttempts}` : "open";
const key = `${mode}:${url}`;
let shared = googleFontCssCache.get(key);
+ attempt.cssCache = shared ? "hit" : "fresh";
if (!shared) {
// The shared fetch must not carry any one caller's abortSignal, or that
// caller cancelling would fail the lookup for every other waiter.
@@ -1477,7 +1514,8 @@ function fetchGoogleFontCss(
"Google Fonts CSS",
{ ...options, abortSignal: undefined },
).then((result) => {
- if (result.ok) return { ok: true as const, body: result.body };
+ if (result.ok)
+ return { ok: true as const, body: result.body, status: result.response.status };
// A transient status must not stick for the process lifetime.
if (isRetryableFontFetchStatus(result.response.status)) googleFontCssCache.delete(key);
return { ok: false as const, status: result.response.status };
@@ -1500,6 +1538,7 @@ function declaredFaceFamily(block: string): string | undefined {
// fallow-ignore-next-line complexity
async function fetchGoogleFont(
familyName: string,
+ path: FontDiagPath,
options: InternalFontFetchOptions,
fontText?: string,
): Promise<GoogleFontFace[]> {
@@ -1521,23 +1560,26 @@ async function fetchGoogleFont(
// `text=` asks Google for only the characters on the page. A CJK family
// without it is a hundred files, and the compile's font budget is 20s.
const defaultUrl = `https://fonts.googleapis.com/css2?family=${encodedFamily}:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,400;1,700${textParam}`;
+ const fetchStylesheet = (url: string, urlSource: FontAttemptDiag["urlSource"]) =>
+ fetchGoogleFontStylesheet(
+ googleFamilyName,
+ url,
+ options,
+ options.diag.startAttempt(path, urlSource, /[?&]text=/.test(url) ? "present" : "absent"),
+ );
if (!authoredStylesheet) {
- return (await fetchGoogleFontStylesheet(googleFamilyName, defaultUrl, options)).faces;
+ return (await fetchStylesheet(defaultUrl, "default")).faces;
}
const faces: GoogleFontFace[] = [];
const outcomes: string[] = [];
for (const url of authoredStylesheet) {
- const result = await fetchGoogleFontStylesheet(
- googleFamilyName,
- withPageText(url, fontText),
- options,
- );
+ const result = await fetchStylesheet(withPageText(url, fontText), "authored");
faces.push(...result.faces);
if (result.faces.length === 0)
outcomes.push(result.status ? `http_${result.status}` : "no_faces");
}
if (faces.length > 0) return faces;
- const fallback = (await fetchGoogleFontStylesheet(googleFamilyName, defaultUrl, options)).faces;
+ const fallback = (await fetchStylesheet(defaultUrl, "default")).faces;
options.log.warn(
`[Compiler] google_font_link_fallback family="${familyName}" link_outcomes=${outcomes.join(",")} ` +
`fallback_faces=${fallback.length}`,
@@ -1551,9 +1593,11 @@ async function readGoogleFontStylesheet(
familyName: string,
url: string,
options: InternalFontFetchOptions,
+ attempt: FontAttemptDiag,
): Promise<GoogleFontStylesheetRead> {
try {
- const cssResult = await fetchGoogleFontCss(url, familyName, options);
+ const cssResult = await fetchGoogleFontCss(url, familyName, options, attempt);
+ attempt.cssStatus = cssResult.status;
if (!cssResult.ok) {
// Missing families are deterministic; transient failures follow the
// caller's retry and fail-closed policy.
@@ -1595,11 +1639,13 @@ async function fetchGoogleFontStylesheet(
familyName: string,
url: string,
options: InternalFontFetchOptions,
+ attempt: FontAttemptDiag,
): Promise<{ faces: GoogleFontFace[]; status?: number }> {
const slug = fontSlug(familyName);
- const read = await readGoogleFontStylesheet(familyName, url, options);
+ const read = await readGoogleFontStylesheet(familyName, url, options, attempt);
if (read.css === null) return { faces: [], status: read.status };
const cssText = read.css;
+ attempt.blocksTotal = (cssText.match(/@font-face\s*\{/gi) ?? []).length;
// Parse @font-face blocks from the CSS response. The optional trailing
// capture grabs each face's `unicode-range` (Google emits it after `src`)
@@ -1613,6 +1659,7 @@ async function fetchGoogleFontStylesheet(
const faces: GoogleFontFace[] = [];
for (const match of cssText.matchAll(faceRegex)) {
+ attempt.regexMatches += 1;
const source = parseGoogleFontSource(match, familyName);
if (!source) continue;
const { weight, style, unicodeRange, url: woff2Url } = source;
@@ -1625,6 +1672,7 @@ async function fetchGoogleFontStylesheet(
weight,
style,
options,
+ attempt.assets,
);
if (dataUri) faces.push({ weight, style, dataUri, unicodeRange });
}
@@ -1641,15 +1689,17 @@ async function fetchGoogleFontStylesheet(
/** An optional family gets one retry on a transient failure, then renders its fallback with a warning. */
async function fetchFamilyFaces(
familyName: string,
+ path: FontDiagPath,
optional: boolean,
options: InternalFontFetchOptions,
fontText?: string,
): Promise<GoogleFontFace[]> {
- if (!optional) return fetchGoogleFont(familyName, options, fontText);
+ if (!optional) return fetchGoogleFont(familyName, path, options, fontText);
const maxAttempts = Math.min(options.retryPolicy.maxAttempts, 2);
try {
return await fetchGoogleFont(
familyName,
+ path,
{ ...options, retryPolicy: { ...options.retryPolicy, maxAttempts } },
fontText,
);
@@ -1886,6 +1936,7 @@ export async function injectDeterministicFontFaces(
html: string,
options: InjectDeterministicFontFacesOptions = {},
): Promise<string> {
+ const diag = new FontDiagCollector();
const failClosedFontFetch = options.failClosedFontFetch === true;
const fetchImpl = options.fetchImpl ?? fetch;
const allowSystemFontCapture = options.allowSystemFontCapture !== false;
@@ -1899,6 +1950,7 @@ export async function injectDeterministicFontFaces(
retryPolicy,
retryDeadlineMs: Date.now() + retryPolicy.maxElapsedMs,
authoredStylesheets: authoredGoogleFontStylesheets(html),
+ diag,
};
const existingFaces = extractExistingFontFaces(html);
@@ -1927,7 +1979,7 @@ export async function injectDeterministicFontFaces(
(family) => !pendingFamilies.get(family.toLowerCase())?.optional,
);
if (required.length > 0 && options.failClosedFontFetch) {
- throw new FontFetchError(
+ const unresolvedError = new FontFetchError(
required.join(", "),
"",
`[Compiler] Unresolved fonts in fail-closed mode: ${required.join(", ")}. ` +
@@ -1936,6 +1988,8 @@ export async function injectDeterministicFontFaces(
FONT_FETCH_FAILED,
unresolved,
);
+ unresolvedError.diagnostics = diag.snapshot();
+ throw unresolvedError;
}
if (!css) {
if (unresolved.length > 0) {
diff --git a/packages/core/src/fonts/fontDiagnostics.ts b/packages/core/src/fonts/fontDiagnostics.ts
new file mode 100644
index 0000000000..a16cad2917
--- /dev/null
+++ b/packages/core/src/fonts/fontDiagnostics.ts
@@ -0,0 +1,70 @@
+export type FontDiagPath = "bundled_supplement" | "direct_google";
+
+export interface FontAssetDiag {
+ total: number;
+ diskCacheHit: number;
+ fetchedOk: number;
+ nonOk: Record<string, number>;
+}
+
+export interface FontAttemptDiag {
+ path: FontDiagPath;
+ urlSource: "authored" | "default";
+ textParam: "present" | "absent";
+ cssCache: "hit" | "fresh";
+ /** The real HTTP status of the CSS lookup; null when no HTTP response was recorded for that attempt. */
+ cssStatus: number | null;
+ /** blocksTotal > 0 with regexMatches 0 is a coarse stage: no block had a woff2 url in the expected shape. */
+ blocksTotal: number;
+ regexMatches: number;
+ assets: FontAssetDiag;
+}
+
+export interface FontFamilyDiag {
+ required: boolean;
+ resolved: boolean;
+ attempts: FontAttemptDiag[];
+}
+
+/** Resolver stage record, in resolver family order. Enums, counts and HTTP statuses only: no names, URLs or text. */
+export interface FontDiagnostics {
+ families: FontFamilyDiag[];
+}
+
+export class FontDiagCollector {
+ private readonly families: FontFamilyDiag[] = [];
+ private current: FontFamilyDiag | undefined;
+
+ beginFamily(required: boolean): void {
+ this.current = { required, resolved: false, attempts: [] };
+ this.families.push(this.current);
+ }
+
+ endFamily(resolved: boolean): void {
+ if (this.current) this.current.resolved = resolved;
+ this.current = undefined;
+ }
+
+ startAttempt(
+ path: FontDiagPath,
+ urlSource: FontAttemptDiag["urlSource"],
+ textParam: FontAttemptDiag["textParam"],
+ ): FontAttemptDiag {
+ const attempt: FontAttemptDiag = {
+ path,
+ urlSource,
+ textParam,
+ cssCache: "fresh",
+ cssStatus: null,
+ blocksTotal: 0,
+ regexMatches: 0,
+ assets: { total: 0, diskCacheHit: 0, fetchedOk: 0, nonOk: {} },
+ };
+ this.current?.attempts.push(attempt);
+ return attempt;
+ }
+
+ snapshot(): FontDiagnostics {
+ return { families: this.families };
+ }
+}