@karibsen/eponyme 0.3.0 → 0.5.0

package/README.md

@@ -559,6 +559,78 @@ ${entries.map(entry => `  <url><loc>https://example.com${entry.loc}</loc>${entry
 })
 ```
 
+## Caching
+
+Published content is the same for every visitor, so it is cached at three levels. The
+defaults suit a content site and can be tuned or switched off:
+
+```ts
+export default defineNuxtConfig({
+  eponyme: {
+    prismaClient: '~~/server/utils/prisma',
+    cacheSeconds: 5,          // server instance
+    browserCacheSeconds: 30,  // visitor's browser
+    cdnCacheSeconds: 300,     // CDN or edge
+  },
+})
+```
+
+| Option | Who holds the copy | Purgeable |
+|---|---|---|
+| `cacheSeconds` | The server instance, in memory | Yes — cleared on every write |
+| `browserCacheSeconds` | The visitor's browser | **No** |
+| `cdnCacheSeconds` | The CDN | Yes — see below |
+
+`browserCacheSeconds` is what makes a client-side navigation instant: the browser answers
+from its own cache instead of crossing the network. It is also the one window nobody can
+shorten. A visitor holding a copy keeps it until it expires, publication or not, which is
+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.
+
+### 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
+// 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
+public ones override — so a route added later is private until someone decides otherwise,
+rather than public until someone remembers.
+
 ## Forms
 
 Use `form()` for public forms. A form owns a schema, its own routes and its anti-abuse
@@ -763,7 +835,7 @@ a trash move leaves the entry itself untouched.
 
 ## Current status
 
-Eponyme is at version `0.3.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.d.mts

@@ -26,6 +26,18 @@ interface ModuleOptions {
      * another instance can still serve the previous content. `0` disables the cache.
      */
     cacheSeconds?: number;
+    /**
+     * How long a browser may reuse published content, in seconds. This is what makes a
+     * client-side navigation instant, and it is the one window nobody can purge: a visitor
+     * who already holds a copy keeps it until it expires. Keep it short. `0` disables it.
+     */
+    browserCacheSeconds?: number;
+    /**
+     * How long a CDN may reuse published content, in seconds. A CDN can be purged — the
+     * `eponyme:entry:published` hook is the place to do it — so this can be generous.
+     * `0` disables it.
+     */
+    cdnCacheSeconds?: number;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 

package/dist/module.json

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

package/dist/module.mjs

@@ -16,7 +16,9 @@ const module$1 = defineNuxtModule({
     auth: {
       sessionDurationDays: 7
     },
-    cacheSeconds: 5
+    cacheSeconds: 5,
+    browserCacheSeconds: 30,
+    cdnCacheSeconds: 300
   },
   moduleDependencies: {
     "@nuxt/icon": {
@@ -72,7 +74,9 @@ const module$1 = defineNuxtModule({
       sessionDurationDays: options.auth?.sessionDurationDays ?? 7
     };
     nuxt.options.runtimeConfig.eponymeContent = {
-      cacheSeconds: options.cacheSeconds ?? 5
+      cacheSeconds: options.cacheSeconds ?? 5,
+      browserCacheSeconds: options.browserCacheSeconds ?? 30,
+      cdnCacheSeconds: options.cdnCacheSeconds ?? 300
     };
     const preparing = Boolean(nuxt.options._prepare);
     if (!options.prismaClient) {
@@ -102,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",
@@ -151,6 +158,7 @@ declare module '#eponyme/captcha' {
 }
 `
     });
+    addServerHandler({ middleware: true, handler: resolver.resolve("./runtime/server/middleware/eponyme-no-store") });
     addServerHandler({ route: "/api/eponyme/**", handler: resolver.resolve("./runtime/server/api/eponyme/[name].get") });
     addServerHandler({ route: "/api/eponyme/**", method: "patch", handler: resolver.resolve("./runtime/server/api/eponyme/[name].patch") });
     addServerHandler({ route: "/api/eponyme-statuses", handler: resolver.resolve("./runtime/server/api/eponyme-statuses.get") });

package/dist/runtime/composables/useEponyme.js

@@ -10,9 +10,10 @@ export function useEponyme(name, options = {}) {
   const saving = ref(false);
   const requestFetch = useRequestFetch();
   const cacheKey = `eponyme:${name}:${version}${options.raw ? ":raw" : ""}`;
+  const fetchCache = version === "published" && !options.raw ? void 0 : "no-store";
   const { data: response, pending: loading, error, refresh: load } = useAsyncData(
     cacheKey,
-    () => requestFetch(`/api/eponyme/${name}`, { query: { version, raw: options.raw ? 1 : void 0 }, cache: "no-store" }),
+    () => requestFetch(`/api/eponyme/${name}`, { query: { version, raw: options.raw ? 1 : void 0 }, cache: fetchCache }),
     { getCachedData: cacheDuringHydrationOnly }
   );
   const data = computed(() => response.value?.data);

package/dist/runtime/composables/useEponymeCollection.js

@@ -15,7 +15,8 @@ export function useEponymeCollection(name, options = {}) {
     // The options belong in the key, otherwise two differently sorted calls to the
     // same collection would share one cache entry.
     `eponyme:collection:public:${name}:${options.take ?? ""}:${options.skip ?? ""}:${options.orderBy ?? ""}:${options.order ?? ""}`,
-    () => requestFetch(`/api/eponyme-collections/${name}`, { query, cache: "no-store" }),
+    // Always the published listing, which is publicly cacheable: the browser cache may answer it.
+    () => requestFetch(`/api/eponyme-collections/${name}`, { query }),
     { getCachedData: cacheDuringHydrationOnly }
   );
   const entries = computed(() => result.data.value?.entries ?? []);
@@ -37,7 +38,11 @@ export function useEponymeCollectionEntry(name, slug, options = {}) {
   const requestFetch = useRequestFetch();
   const result = useAsyncData(
     `eponyme:collection-entry:${name}:${slug}:${version}`,
-    () => requestFetch(`/api/eponyme/${name}/${encodeURIComponent(slug)}`, { query: { version }, cache: "no-store" }),
+    () => requestFetch(`/api/eponyme/${name}/${encodeURIComponent(slug)}`, {
+      query: { version },
+      // A draft or a historical version must never be stored, whatever the server says.
+      cache: version === "published" ? void 0 : "no-store"
+    }),
     { getCachedData: cacheDuringHydrationOnly }
   );
   if (import.meta.client) useEventListener(window, "focus", () => void result.refresh());

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

@@ -1,6 +1,8 @@
-import { createError, defineEventHandler, getQuery, getRequestURL, setResponseHeader } from "h3";
+import { createError, defineEventHandler, getQuery, getRequestURL } from "h3";
 import { useEponymeService } from "../../services/eponyme-service.js";
 import { requireEponymeUser } from "../../utils/auth.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";
@@ -11,12 +13,11 @@ export default defineEventHandler(async (event) => {
   const name = decodeURIComponent(getRequestURL(event).pathname.replace(/^\/api\/eponyme\//, ""));
   const requestedVersion = getQuery(event).version;
   const version = readVersion(requestedVersion);
-  if (version !== "published") {
-    await requireEponymeUser(event);
-    setResponseHeader(event, "Cache-Control", "no-store");
-  }
+  const raw = Boolean(getQuery(event).raw);
+  if (version !== "published") await requireEponymeUser(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 = getQuery(event).raw ? result.data : interpolateEponymeContent(result.data);
+  const data = raw ? result.data : interpolateEponymeContent(result.data);
   return requestedVersion ? { ...result, data } : { data };
 });

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

@@ -1,6 +1,7 @@
 import { createError, defineEventHandler, getQuery, getRequestURL } from "h3";
 import { useEponymeService } from "../../services/eponyme-service.js";
 import { requireEponymeUser } from "../../utils/auth.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) {
@@ -14,6 +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, 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,5 +1,7 @@
 import { defineEventHandler } from "h3";
+import { getEponymeCacheTags, setEponymePublicCache } from "../utils/eponyme-cache.js";
 import { getEponymeSitemapEntries } from "../utils/eponyme-sitemap.js";
-export default defineEventHandler(async () => {
+export default defineEventHandler(async (event) => {
+  setEponymePublicCache(event, getEponymeCacheTags("sitemap"));
   return { entries: await getEponymeSitemapEntries() };
 });

package/dist/runtime/server/middleware/eponyme-no-store.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Every Eponyme route is uncacheable until it says otherwise.
+ *
+ * The routes that may be cached are a short, deliberate list — published content, the
+ * collection listings, the sitemap — and each calls `setEponymePublicCache` to override
+ * this. Everything else carries sessions, drafts, trashed entries, form submissions or
+ * the user list, and none of it may ever be stored by a browser or a CDN.
+ *
+ * Written as a default rather than as a header on each handler so that the dangerous
+ * direction is the one that takes effort: a route added later is private until someone
+ * decides otherwise, instead of public until someone remembers.
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, void>;
+export default _default;

package/dist/runtime/server/middleware/eponyme-no-store.js

@@ -0,0 +1,6 @@
+import { defineEventHandler, getRequestURL } from "h3";
+import { setEponymePrivateCache } from "../utils/eponyme-cache.js";
+export default defineEventHandler((event) => {
+  if (!getRequestURL(event).pathname.startsWith("/api/eponyme")) return;
+  setEponymePrivateCache(event);
+});

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

@@ -0,0 +1,30 @@
+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:
+ *
+ * - `s-maxage` is the CDN's, and a CDN can be purged — `eponyme:entry:published` is the
+ *   hook to do it from, so this one can afford to be long.
+ * - `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, 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.
+ */
+export declare function setEponymePrivateCache(event: H3Event): void;

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

@@ -0,0 +1,33 @@
+import { setResponseHeader } from "h3";
+import { useRuntimeConfig } from "nitropack/runtime";
+const STALE_WHILE_REVALIDATE_FACTOR = 12;
+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));
+  if (!browser && !cdn) {
+    setResponseHeader(event, "Cache-Control", "no-cache");
+    return;
+  }
+  setResponseHeader(
+    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.3.0",
+  "version": "0.5.0",
   "description": "A lightweight, type-safe content manager for Nuxt.",
   "license": "MIT",
   "type": "module",