@karibsen/eponyme 0.4.0 → 0.5.0

package/README.md

@@ -587,15 +587,44 @@ shorten. A visitor holding a copy keeps it until it expires, publication or not,
 why the default is deliberately small. Set it to `0` if a publication must be visible
 immediately to everyone; navigation then costs a round trip again.
 
-The CDN window can be long because it can be purged, and `eponyme:entry:published` is the
-place to do it:
+### Purging the CDN
+
+The CDN window can be long because it can be purged. CDNs purge by **tag** rather than by
+URL — one entry appears in several cached responses, its own and its collection's listing —
+so every cacheable response carries `Vercel-Cache-Tag` and `Cache-Tag`:
+
+| Response | Tags |
+|---|---|
+| `pages/homepage` | `eponyme`, `eponyme:pages/homepage` |
+| `articles/my-article` | `eponyme`, `eponyme:articles/my-article`, `eponyme:articles` |
+| The `articles` listing | `eponyme`, `eponyme:articles` |
+
+`getEponymeCacheTags()` returns exactly those tags and is auto-imported into server code,
+so a listener purges precisely what the responses were tagged with. On Vercel:
 
 ```ts
-nitroApp.hooks.hook('eponyme:entry:published', async ({ name, collection }) => {
-  await purgeCdnCache(collection ? `/${collection.name}/${collection.slug}` : `/${name}`)
+// server/plugins/purge.ts
+import { invalidateByTag } from '@vercel/functions'
+
+export default defineNitroPlugin((nitroApp) => {
+  const purge = async ({ name, collection }: { name: string, collection?: { name: string } }) => {
+    if (!import.meta.env.VERCEL) return
+    await invalidateByTag(getEponymeCacheTags(name, collection)).catch(() => {})
+  }
+
+  nitroApp.hooks.hook('eponyme:entry:published', purge)
+  nitroApp.hooks.hook('eponyme:entry:restored', purge)
+  nitroApp.hooks.hook('eponyme:entry:trashed', purge)
+  nitroApp.hooks.hook('eponyme:entry:untrashed', purge)
+  nitroApp.hooks.hook('eponyme:entry:purged', purge)
 })
 ```
 
+Invalidating marks the entry stale and revalidates in the background, so no visitor waits
+for it. A failed purge is swallowed: a CDN that cannot be reached must not turn a
+successful publication into an error the editor cannot act on. The worst case is the
+content appearing when `cdnCacheSeconds` expires on its own.
+
 **Only published content is ever cached.** Drafts, historical versions, `raw=1` reads,
 submissions, the trash, the user list and the session route all answer `no-store`. That is
 enforced by a server middleware that marks every Eponyme route uncacheable, which the few
@@ -806,7 +835,7 @@ a trash move leaves the entry itself untouched.
 
 ## Current status
 
-Eponyme is at version `0.4.0`. It is ready for controlled projects and production pilots. A few workflows still need hardening before a broad public release:
+Eponyme is at version `0.5.0`. It is ready for controlled projects and production pilots. A few workflows still need hardening before a broad public release:
 
 - Client revision tokens for long-running concurrent edits: the current `updatedAt` check protects overlapping writes within one request, not two editors who loaded the same older revision. A deletion is not guarded by a revision either
 - Retention controls for the trash: entries stay there until someone empties it

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@karibsen/eponyme",
   "configKey": "eponyme",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -106,7 +106,10 @@ Note that '~/' points at ${nuxt.options.srcDir}, so a server module needs '~~/'.
       { name: "getEponymeSitemapEntries", from: resolver.resolve("./runtime/server/utils/eponyme-sitemap") },
       // A `custom` form posts to the host application's own route, so this is what
       // keeps server-side validation as the security boundary.
-      { name: "validateEponymeForm", from: resolver.resolve("./runtime/server/utils/eponyme-form") }
+      { name: "validateEponymeForm", from: resolver.resolve("./runtime/server/utils/eponyme-form") },
+      // The tags a CDN purge has to invalidate when an entry changes, matching exactly what
+      // the cached responses were tagged with.
+      { name: "getEponymeCacheTags", from: resolver.resolve("./runtime/server/utils/eponyme-cache") }
     ]);
     addRouteMiddleware({
       name: "eponyme-auth",

package/dist/runtime/server/api/eponyme/[name].get.js

@@ -1,7 +1,8 @@
 import { createError, defineEventHandler, getQuery, getRequestURL } from "h3";
 import { useEponymeService } from "../../services/eponyme-service.js";
 import { requireEponymeUser } from "../../utils/auth.js";
-import { setEponymePublicCache } from "../../utils/eponyme-cache.js";
+import { getEponymeCacheTags, setEponymePublicCache } from "../../utils/eponyme-cache.js";
+import { splitEponymeCollectionEntry } from "../../utils/eponyme-entry.js";
 import { interpolateEponymeContent } from "../../utils/eponyme-variables.js";
 function readVersion(raw) {
   if (raw === "draft") return "draft";
@@ -14,7 +15,7 @@ export default defineEventHandler(async (event) => {
   const version = readVersion(requestedVersion);
   const raw = Boolean(getQuery(event).raw);
   if (version !== "published") await requireEponymeUser(event);
-  else if (!raw) setEponymePublicCache(event);
+  else if (!raw) setEponymePublicCache(event, getEponymeCacheTags(name, splitEponymeCollectionEntry(useEponymeService(), name)?.name));
   const result = name ? await useEponymeService().getResult(name, version) : void 0;
   if (!result) throw createError({ statusCode: 404, statusMessage: "Eponyme entry not found." });
   const data = raw ? result.data : interpolateEponymeContent(result.data);

package/dist/runtime/server/api/eponyme-collections/[path].get.js

@@ -1,7 +1,7 @@
 import { createError, defineEventHandler, getQuery, getRequestURL } from "h3";
 import { useEponymeService } from "../../services/eponyme-service.js";
 import { requireEponymeUser } from "../../utils/auth.js";
-import { setEponymePublicCache } from "../../utils/eponyme-cache.js";
+import { getEponymeCacheTags, setEponymePublicCache } from "../../utils/eponyme-cache.js";
 import { interpolateEponymeContent } from "../../utils/eponyme-variables.js";
 const MAX_TAKE = 200;
 function readCount(raw, min, max) {
@@ -15,7 +15,7 @@ export default defineEventHandler(async (event) => {
   const query = getQuery(event);
   const version = query.version === "draft" ? "draft" : "published";
   if (version === "draft") await requireEponymeUser(event);
-  else if (!query.raw) setEponymePublicCache(event);
+  else if (!query.raw) setEponymePublicCache(event, getEponymeCacheTags(name));
   if (!name) throw createError({ statusCode: 404, statusMessage: "Eponyme collection not found." });
   const service = useEponymeService();
   const orderBy = query.orderBy === void 0 || query.orderBy === "" ? void 0 : String(query.orderBy);

package/dist/runtime/server/api/eponyme-sitemap.get.js

@@ -1,7 +1,7 @@
 import { defineEventHandler } from "h3";
-import { setEponymePublicCache } from "../utils/eponyme-cache.js";
+import { getEponymeCacheTags, setEponymePublicCache } from "../utils/eponyme-cache.js";
 import { getEponymeSitemapEntries } from "../utils/eponyme-sitemap.js";
 export default defineEventHandler(async (event) => {
-  setEponymePublicCache(event);
+  setEponymePublicCache(event, getEponymeCacheTags("sitemap"));
   return { entries: await getEponymeSitemapEntries() };
 });

package/dist/runtime/server/utils/eponyme-cache.d.ts

@@ -1,4 +1,18 @@
 import type { H3Event } from 'h3';
+/**
+ * Cache tags for one entry, most specific first.
+ *
+ * A CDN cannot usually be purged by URL — Vercel and Cloudflare both purge by tag — and one
+ * entry appears in more than one cached response: its own, and its collection's listing.
+ * Tagging both is what lets publishing an article drop the article *and* the index that
+ * lists it.
+ *
+ * A comma is the delimiter every CDN uses for this header, so it is stripped rather than
+ * escaped: a tag containing one would silently become two.
+ */
+export declare function getEponymeCacheTags(name: string, collection?: {
+    name: string;
+} | string): string[];
 /**
  * Published content is identical for every visitor, so both the browser and the CDN may
  * hold on to it. The two windows are deliberately different:
@@ -8,7 +22,7 @@ import type { H3Event } from 'h3';
  * - `max-age` is the browser's, and a browser cache cannot be purged by anyone. Whatever
  *   it holds is served until it expires, publication or not, which is why it stays short.
  */
-export declare function setEponymePublicCache(event: H3Event): void;
+export declare function setEponymePublicCache(event: H3Event, tags?: string[]): void;
 /**
  * Drafts and historical versions are unreleased material. `no-store` rather than
  * `no-cache`: nothing may keep a copy at all, not even one it promises to revalidate.

package/dist/runtime/server/utils/eponyme-cache.js

@@ -1,7 +1,19 @@
 import { setResponseHeader } from "h3";
 import { useRuntimeConfig } from "nitropack/runtime";
 const STALE_WHILE_REVALIDATE_FACTOR = 12;
-export function setEponymePublicCache(event) {
+export function getEponymeCacheTags(name, collection) {
+  const collectionName = typeof collection === "string" ? collection : collection?.name;
+  const tags = ["eponyme", `eponyme:${name}`];
+  if (collectionName) tags.push(`eponyme:${collectionName}`);
+  return [...new Set(tags)].map((tag) => tag.replace(/,/g, "").slice(0, 256));
+}
+function setCacheTags(event, tags) {
+  if (!tags.length) return;
+  const value = tags.join(",");
+  setResponseHeader(event, "Vercel-Cache-Tag", value);
+  setResponseHeader(event, "Cache-Tag", value);
+}
+export function setEponymePublicCache(event, tags = []) {
   const config = useRuntimeConfig().eponymeContent;
   const browser = Math.max(0, Math.trunc(config?.browserCacheSeconds ?? 30));
   const cdn = Math.max(0, Math.trunc(config?.cdnCacheSeconds ?? 300));
@@ -14,6 +26,7 @@ export function setEponymePublicCache(event) {
     "Cache-Control",
     `public, max-age=${browser}, s-maxage=${cdn}, stale-while-revalidate=${cdn * STALE_WHILE_REVALIDATE_FACTOR}`
   );
+  setCacheTags(event, tags);
 }
 export function setEponymePrivateCache(event) {
   setResponseHeader(event, "Cache-Control", "no-store");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karibsen/eponyme",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A lightweight, type-safe content manager for Nuxt.",
   "license": "MIT",
   "type": "module",