app/lib/cv/pdf.server.ts

Functions

Imports

It imports app/db/cv.ts, app/lib/cache-purge.server.ts, app/lib/content/load-pipeline.server.ts, app/lib/cv/pdf-html.mjs, app/lib/error-message.mjs. Imported by app/lib/cv/save.server.ts, app/lib/health/checks.server.ts, app/lib/operator/sync-tools.server.ts, app/routes/cv-pdf.ts.

Source

1// The CV's PDF: rendered in the Worker by Browser Run after each CV save, kept as ONE object in the OG bucket,
2// and served at /dustin-edwards-cv.pdf by app/routes/cv-pdf.ts (docs/CV.md, "The PDF").
3//
4// THE OBJECT IS DERIVED. The CV rows are the source and the PDF is a function of them, stamped with
5// the fingerprint of the data it was drawn from (cvFingerprint, in custom metadata and on the PDF's last line). A
6// failed render never reverts a save: the save has already committed and written D1, and the stale or missing
7// object shows as the `cv-pdf-drift` health check, which the watchdog repairs through `sync_cv_pdf`.
8//
9// WHY OG, NOT MEDIA. OG is the bucket for derived, regenerable objects, with no backup mirror and no site code
10// that treats it as irreplaceable. MEDIA is the irreplaceable bucket: a put there queues a backup copy and a
11// delete there is policed (check:destructive). The key sits under `derived/`, not `og/`, because build:og prunes
12// everything under `og/` that no post references, and would delete this.
13
14import { readCv } from "~/db/cv";
15import { purgeCv, type PurgeOutcome } from "~/lib/cache-purge.server";
16import { loadPipeline } from "~/lib/content/load-pipeline.server";
17import { cvFingerprint, cvPdfOptions, fontFaceRule, PDF_FONTS, renderCvHtml } from "~/lib/cv/pdf-html.mjs";
18import { errorMessage } from "~/lib/error-message.mjs";
19import interNormalUrl from "~/fonts/inter-latin-normal.woff2?url";
20import serifItalicUrl from "~/fonts/source-serif-4-latin-italic.woff2?url";
21import serifNormalUrl from "~/fonts/source-serif-4-latin-normal.woff2?url";
22
23/** The one key. `dustin-edwards-` is ruling 127's prefix for a file the site serves under a name. */
24export const CV_PDF_KEY = "derived/dustin-edwards-cv.pdf";
25
26/** The custom-metadata field that carries the fingerprint of the CV data the object was drawn from. */
27export const FINGERPRINT_FIELD = "fingerprint";
28
29/** The font URLs the client build emits, by the file name PDF_FONTS names. */
30const FONT_URLS: Record<(typeof PDF_FONTS)[number]["file"], string> = {
31  "source-serif-4-latin-normal.woff2": serifNormalUrl,
32  "source-serif-4-latin-italic.woff2": serifItalicUrl,
33  "inter-latin-normal.woff2": interNormalUrl,
34};
35
36/** A render that finds a newer CV after it started tries again, this many times at most. */
37const MAX_ATTEMPTS = 3;
38
39// Isolate-wide: the font rules come from the deployed assets, the same for every request.
40let fontCssCache: Promise<string> | undefined;
41
42/** The `@font-face` rules, read through the ASSETS binding from the hashed font files the site already serves. */
43function fontCss(env: Env): Promise<string> {
44  // A failed read is not cached, so one bad fetch is not every later render's error.
45  fontCssCache ??= Promise.all(
46    PDF_FONTS.map(async ({ file, family, style }) => {
47      const url = FONT_URLS[file];
48      // The ASSETS binding ignores the hostname and matches only the pathname.
49      const response = await env.ASSETS.fetch(new Request(`https://assets.local${url}`));
50      if (!response.ok) throw new Error(`The font ${file} is not in the assets (${url} answered ${response.status}).`);
51      return fontFaceRule(family, new Uint8Array(await response.arrayBuffer()), style);
52    }),
53  )
54    .then((rules) => rules.join("\n"))
55    .catch((error) => {
56      fontCssCache = undefined;
57      throw error;
58    });
59  return fontCssCache;
60}
61
62/** The PDF bytes for a resolved CV, through Browser Run. Throws, naming what failed. */
63async function renderCvPdf(env: Env, CV: Awaited<ReturnType<typeof readCv>>): Promise<Uint8Array> {
64  if (!env.BROWSER) {
65    throw new Error("The BROWSER binding is not configured on this Worker, so the CV PDF cannot be rendered (wrangler.jsonc.example).");
66  }
67  const { renderBody } = await loadPipeline();
68  const html = await renderCvHtml(CV, { renderBody, fontCss: await fontCss(env) });
69  const response = await env.BROWSER.quickAction("pdf", {
70    html,
71    pdfOptions: cvPdfOptions(CV),
72    gotoOptions: { waitUntil: "load" },
73  });
74  if (!response.ok) {
75    throw new Error(`Browser Run answered ${response.status} for the CV PDF: ${(await response.text()).slice(0, 300)}`);
76  }
77  const bytes = new Uint8Array(await response.arrayBuffer());
78  // A 200 that is not a PDF must never replace the one that is.
79  if (bytes.length < 1024 || String.fromCharCode(...bytes.subarray(0, 5)) !== "%PDF-") {
80    throw new Error(`Browser Run answered 200 for the CV PDF with ${bytes.length} bytes that are not a PDF.`);
81  }
82  return bytes;
83}
84
85export type CvPdfOutcome =
86  | { action: "current"; fingerprint: string }
87  | { action: "stored"; fingerprint: string; bytes: number; purged: PurgeOutcome; attempts: number };
88
89/**
90 * Makes the stored PDF the one for the CV D1 holds NOW, and returns what it did. Reads D1 itself, so it renders
91 * what the page serves whoever calls it.
92 *
93 * A LATER SAVE CANNOT BE OVERWRITTEN BY AN EARLIER RENDER, and the guarantee is two compares:
94 *  1. after the render and before the put, D1's CV is read again; a render of anything but the CV D1 holds then is
95 *     discarded and the loop starts over, so a slow render of save A never lands after save B changed the data;
96 *  2. the put is conditional on the object being the one the loop read (`onlyIf`), so two renders that both pass
97 *     the first compare cannot both win blindly: the loser's put returns null and it re-reads, finds the winner's
98 *     fingerprint, and either stops (same data) or renders again (newer data).
99 * So the last object standing was drawn from the CV D1 held when it was put.
100 */
101export async function ensureCvPdf(env: Env): Promise<CvPdfOutcome> {
102  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
103    const cv = await readCv(env);
104    const fingerprint = await cvFingerprint(cv);
105    const stored = await env.OG.head(CV_PDF_KEY);
106    if (stored?.customMetadata?.[FINGERPRINT_FIELD] === fingerprint) return { action: "current", fingerprint };
107
108    const bytes = await renderCvPdf(env, cv);
109
110    // Compare 1: the data changed under the render.
111    if ((await cvFingerprint(await readCv(env))) !== fingerprint) continue;
112
113    // Compare 2: a conditional put. An object that was not there must still not be there; one that was must
114    // still be the one read above.
115    const put = await env.OG.put(CV_PDF_KEY, bytes, {
116      httpMetadata: { contentType: "application/pdf" },
117      customMetadata: { [FINGERPRINT_FIELD]: fingerprint },
118      onlyIf: stored ? { etagMatches: stored.etag } : { etagDoesNotMatch: "*" },
119    });
120    if (put === null) continue;
121
122    return { action: "stored", fingerprint, bytes: bytes.length, purged: await purgeCv("regenerate CV PDF"), attempts: attempt };
123  }
124  throw new Error(
125    `The CV changed (or the stored PDF did) during each of ${MAX_ATTEMPTS} renders, so the PDF was not replaced. ` +
126      "Run sync_cv_pdf; if it keeps failing, something is saving the CV continuously.",
127  );
128}
129
130/**
131 * The work a CV save starts after its commit and D1 write. A failure is logged as an alert (the line a log
132 * export or a person can find) AND rethrown, so the waitUntil task that carries it fails visibly; the drift check
133 * then reports the stale object until sync_cv_pdf repairs it. It never reverts or fails the save.
134 */
135export async function regenerateCvPdfAfterSave(env: Env, why: string): Promise<CvPdfOutcome> {
136  try {
137    return await ensureCvPdf(env);
138  } catch (error) {
139    console.error(JSON.stringify({ alert: "cv-pdf-render-failed", why, detail: errorMessage(error) }));
140    throw error;
141  }
142}
143
144/** The fingerprint the stored object carries, or null when there is no object. For the drift check and the route. */
145export async function storedCvPdfFingerprint(env: Env): Promise<string | null> {
146  const stored = await env.OG.head(CV_PDF_KEY);
147  return stored ? (stored.customMetadata?.[FINGERPRINT_FIELD] ?? "") : null;
148}