app/lib/cache-purge.server.ts

Functions

Imports

It imports app/kb/registry/route.ts, app/lib/cv/route.ts, app/lib/error-message.mjs, app/lib/llms/validate.mjs, app/lib/pages/route.ts, app/lib/publications/paths.mjs, app/lib/seo.ts. Imported by app/kb/procedures/primer-dependents.server.ts, app/kb/procedures/save.server.ts, app/kb/registry/save.server.ts, app/lib/cv/pdf.server.ts, app/lib/cv/save.server.ts, app/lib/dictionary/save.server.ts, app/lib/editor/post-rows.server.ts, app/lib/editor/publish.server.ts, app/lib/llms/save.server.ts, app/lib/operator/sync-tools.server.ts, app/lib/pages/save.server.ts, app/lib/phages/save.server.ts, app/lib/publications/save.server.ts, app/lib/roster/save.server.ts, app/lib/webmention/decide.server.ts.

Source

1// aislop-ignore-next-line ai-slop/hallucinated-import -- a Workers built-in, not an npm package
2import { cache } from "cloudflare:workers";
3
4import { LLMS_CACHE_TAG } from "~/lib/llms/validate.mjs";
5import { CV_CACHE_TAG } from "~/lib/cv/route";
6import { CONTENT_PAGES_CACHE_TAG } from "~/lib/pages/route";
7import { PUBLICATIONS_CACHE_TAG } from "~/lib/publications/paths.mjs";
8import { REGISTRY_CACHE_TAG } from "~/kb/registry/route";
9import { cacheTags } from "~/lib/seo";
10import { errorMessage } from "~/lib/error-message.mjs";
11
12// A purge never throws and never blocks a write: a failed invalidation is a stale page and a log
13// line, not a 500 after a publish that already succeeded.
14
15/**
16 * `true` purged, `false` failed (refused or threw: public pages stay stale until expiry), `null`
17 * skipped because this runtime has no purge API (Miniflare, local dev). Only `false` is a problem.
18 */
19export type PurgeOutcome = boolean | null;
20
21/** Several purges read as one: any failure fails, all done is done, otherwise skipped. */
22export function combinePurges(...outcomes: PurgeOutcome[]): PurgeOutcome {
23  if (outcomes.includes(false)) return false;
24  return outcomes.every((outcome) => outcome === true) ? true : null;
25}
26
27type PurgeResult = { success: boolean; errors?: Array<{ code: number; message: string }> };
28
29/**
30 * @param tags the cache tags to invalidate
31 * @param why  one phrase naming the write that caused this, for the log line
32 */
33async function purgeTags(tags: string[], why: string): Promise<PurgeOutcome> {
34  // Miniflare has no Workers Cache, so the API may be absent; a TypeError here would fail a save.
35  const purge = (cache as typeof cache & { purge?: (o: unknown) => Promise<PurgeResult> })?.purge;
36  if (typeof purge !== "function") {
37    console.log(JSON.stringify({ event: "cache-purge-skipped", why, reason: "no purge API on this runtime", tags }));
38    return null;
39  }
40
41  try {
42    // `purge` resolves `{ success: false }` on a refusal (usually the rate limit) rather than rejecting.
43    const result = await purge({ tags });
44    if (!result?.success) {
45      console.error(
46        JSON.stringify({
47          alert: "cache-purge-refused",
48          why,
49          tags,
50          errors: result?.errors ?? [],
51        }),
52      );
53      return false;
54    }
55    return true;
56  } catch (error) {
57    console.error(
58      JSON.stringify({
59        alert: "cache-purge-threw",
60        why,
61        tags,
62        detail: errorMessage(error),
63      }),
64    );
65    return false;
66  }
67}
68
69/**
70 * @param slug the post whose page changed
71 */
72export async function purgePost(slug: string, why: string): Promise<PurgeOutcome> {
73  return purgeTags([`post:${slug}`], why);
74}
75
76// Not `purgeEverything`, which would also drop the hand-authored pages no publish changes.
77export async function purgePosts(why: string): Promise<PurgeOutcome> {
78  return purgeTags([cacheTags()], why);
79}
80
81/** Every procedure page, sheet and twin carries this one tag (app/kb/procedures/route.ts). */
82export async function purgeProcedures(why: string): Promise<PurgeOutcome> {
83  return purgeTags(["procedures"], why);
84}
85
86/**
87 * Every registry page, listing and twin carries this one tag (app/kb/registry/route.ts). A protocol page links
88 * the registry's items by their own addresses and states none of their facts, so no other tag moves.
89 */
90export async function purgeRegistry(why: string): Promise<PurgeOutcome> {
91  return purgeTags([REGISTRY_CACHE_TAG], why);
92}
93
94/**
95 * The publication pages, exports and twins carry their own tag. The home page, the search page and the
96 * blog listings carry `posts` and show papers too (the three newest, the count, a search record), so a
97 * save purges both.
98 */
99export async function purgePublications(why: string): Promise<PurgeOutcome> {
100  return purgeTags([PUBLICATIONS_CACHE_TAG, cacheTags()], why);
101}
102
103/** Every content page and its twin carries this one tag (app/lib/pages/route.ts). */
104export async function purgePages(why: string): Promise<PurgeOutcome> {
105  return purgeTags([CONTENT_PAGES_CACHE_TAG], why);
106}
107
108/**
109 * The roster is embedded in two pages: the list on /teaching/phage-discovery, which carries the content
110 * pages' tag, and the counts on the home page, which carries `posts` (app/routes/home.tsx). A cohort save
111 * purges both, because purging only the program page would leave the home page's counts stale.
112 */
113export async function purgeRoster(why: string): Promise<PurgeOutcome> {
114  return purgeTags([CONTENT_PAGES_CACHE_TAG, cacheTags()], why);
115}
116
117/**
118 * The phage table is embedded in one page, /research/phages: its HTML and its markdown twin both carry the
119 * content-pages tag, so a phage save purges that tag (and only it). A phage appears nowhere else.
120 */
121export async function purgePhages(why: string): Promise<PurgeOutcome> {
122  return purgeTags([CONTENT_PAGES_CACHE_TAG], why);
123}
124
125/** /llms.txt carries this one tag (app/routes/llms.ts). */
126export async function purgeLlms(why: string): Promise<PurgeOutcome> {
127  return purgeTags([LLMS_CACHE_TAG], why);
128}
129
130/** The CV page, its charts and its markdown twin carry this one tag (app/lib/cv/route.ts). */
131export async function purgeCv(why: string): Promise<PurgeOutcome> {
132  return purgeTags([CV_CACHE_TAG], why);
133}