@karibsen/eponyme 0.3.0 → 0.4.0

package/README.md

@@ -559,6 +559,49 @@ ${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.
+
+The CDN window can be long because it can be purged, and `eponyme:entry:published` is the
+place to do it:
+
+```ts
+nitroApp.hooks.hook('eponyme:entry:published', async ({ name, collection }) => {
+  await purgeCdnCache(collection ? `/${collection.name}/${collection.slug}` : `/${name}`)
+})
+```
+
+**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 +806,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.4.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.4.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) {
@@ -151,6 +155,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,7 @@
-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 { setEponymePublicCache } from "../../utils/eponyme-cache.js";
 import { interpolateEponymeContent } from "../../utils/eponyme-variables.js";
 function readVersion(raw) {
   if (raw === "draft") return "draft";
@@ -11,12 +12,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);
   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 { 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);
   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 { setEponymePublicCache } from "../utils/eponyme-cache.js";
 import { getEponymeSitemapEntries } from "../utils/eponyme-sitemap.js";
-export default defineEventHandler(async () => {
+export default defineEventHandler(async (event) => {
+  setEponymePublicCache(event);
   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,16 @@
+import type { H3Event } from 'h3';
+/**
+ * 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): 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,20 @@
+import { setResponseHeader } from "h3";
+import { useRuntimeConfig } from "nitropack/runtime";
+const STALE_WHILE_REVALIDATE_FACTOR = 12;
+export function setEponymePublicCache(event) {
+  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}`
+  );
+}
+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.4.0",
   "description": "A lightweight, type-safe content manager for Nuxt.",
   "license": "MIT",
   "type": "module",