@hollware/nuxt 0.6.0 → 0.8.0

package/dist/index.d.mts

@@ -29,6 +29,21 @@ export interface ModuleOptions {
    * No views are counted when it is not set.
    */
   beacon?: string;
+  /**
+   * How the pages that read Hollware are kept (S8):
+   *
+   * - `'purge'`: in Cloudflare's Workers Cache, which serves them without running the Worker, each
+   *   tagged with what it showed, until Hollware's webhook to `/_hollware/webhook` (signed with
+   *   `NUXT_HOLLWARE_WEBHOOK_SECRET`) purges what changed: a publish, an edit or an unpublish shows
+   *   in seconds everywhere. It needs `"cache": { "enabled": true }` in the site's wrangler.jsonc.
+   * - a number of seconds: kept by Nitro (`swr`) in each isolate, and rendered again in the
+   *   background once that old; a change shows within that time.
+   *
+   * Errors are never kept. Off when not set.
+   */
+  cache?: number | 'purge';
+  /** The secret of Hollware's webhook to this site, for `cache: 'purge'`; prefer `NUXT_HOLLWARE_WEBHOOK_SECRET`. */
+  webhookSecret?: string;
 }
 export declare const name = "@hollware/nuxt";
 /** The routes of the site that read Hollware for its pages, on the server. */

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { addComponent, addImports, addPlugin, addServerHandler, addServerImports, createResolver, defineNuxtModule } from "@nuxt/kit";
+import { addComponent, addImports, addPlugin, addServerHandler, addServerImports, addServerPlugin, createResolver, defineNuxtModule } from "@nuxt/kit";
 //#region src/index.ts
 const name = "@hollware/nuxt";
 /** The routes of the site that read Hollware for its pages, on the server. */
@@ -27,7 +27,8 @@ var src_default = defineNuxtModule({
 			site: options.site,
 			binding: options.binding,
 			url: options.url ?? "",
-			token: options.token ?? ""
+			token: options.token ?? "",
+			webhookSecret: options.webhookSecret ?? ""
 		};
 		addServerImports([{
 			name: "useHollware",
@@ -52,6 +53,26 @@ var src_default = defineNuxtModule({
 			filePath: resolve("./runtime/components/HollwareContent")
 		});
 		if (options.generator) addPlugin(resolve("./runtime/generator"));
+		if (options.cache === "purge") {
+			addServerPlugin(resolve("./runtime/server/cache"));
+			addServerHandler({
+				route: "/_hollware/webhook",
+				method: "post",
+				handler: resolve("./runtime/server/routes/webhook")
+			});
+		}
+		if (typeof options.cache === "number" && options.cache > 0) {
+			const pages = { swr: options.cache };
+			const routes = {
+				swr: false,
+				cache: false
+			};
+			nuxt.options.routeRules = {
+				"/**": pages,
+				"/_hollware/**": routes,
+				...nuxt.options.routeRules
+			};
+		}
 		if (options.beacon !== void 0 && options.beacon !== "") {
 			nuxt.options.runtimeConfig.public["hollware"] = {
 				site: options.site,

package/dist/runtime/composables.d.mts

@@ -1,11 +1,6 @@
 import { PageEntry } from "./types.mjs";
 import { MaybeRefOrGetter } from "vue";
 //#region src/runtime/composables.d.ts
-/**
- * The published content of the site, for a page: each reads the site's own `/_hollware/` route,
- * which reads Hollware on the server, so no token reaches the browser. They are `useFetch`, so the
- * page renders on the server with the answer and the browser does not ask again.
- */
 /** An entry, with its Comark document; `data` is null while it loads, `error` a 404 when it is not published. */
 export declare function useHollwareEntry(collection: MaybeRefOrGetter<string>, locale: MaybeRefOrGetter<string>, slug: MaybeRefOrGetter<string>): import("nuxt/app").AsyncData<{
   outcome: 'ok';
@@ -38,6 +33,7 @@ export declare function useHollwareSite(): import("nuxt/app").AsyncData<{
     key: string;
     locales: string[];
     defaultLocale: string;
+    url: string | null;
     styleGuide: string | null;
     collections: {
       name: string;

package/dist/runtime/composables.mjs

@@ -1,32 +1,58 @@
-import { useFetch } from "nuxt/app";
+import { entryTags, groupTags, listTags, recordTags, siteTags } from "./tags.mjs";
+import { useFetch, useRequestEvent } from "nuxt/app";
 import { computed, toValue } from "vue";
 //#region src/runtime/composables.ts
 /**
 * The published content of the site, for a page: each reads the site's own `/_hollware/` route,
 * which reads Hollware on the server, so no token reaches the browser. They are `useFetch`, so the
-* page renders on the server with the answer and the browser does not ask again.
+* page renders on the server with the answer and the browser does not ask again. On the server,
+* each records on the page's request the cache tags of what it read (S8).
 */
+/** The request of the page being rendered, on the server; none in the browser. */
+function pageRequest() {
+	return import.meta.server ? useRequestEvent() : void 0;
+}
 /** An entry, with its Comark document; `data` is null while it loads, `error` a 404 when it is not published. */
 function useHollwareEntry(collection, locale, slug) {
 	const path = computed(() => `/_hollware/entry/${encodeURIComponent(toValue(collection))}/${encodeURIComponent(toValue(locale))}/${encodeURIComponent(toValue(slug))}`);
-	return useFetch(path, { key: path.value });
+	const event = pageRequest();
+	return useFetch(path, {
+		key: path.value,
+		transform: (answer) => {
+			recordTags(event, entryTags(answer.entry));
+			return answer;
+		}
+	});
 }
 /** A page of the published entries of a collection, newest first. */
 function useHollwareEntries(collection, options = {}, fetching = {}) {
 	const path = computed(() => `/_hollware/entries/${encodeURIComponent(toValue(collection))}`);
+	const event = pageRequest();
 	return useFetch(path, {
 		query: computed(() => toValue(options)),
-		...fetching
+		...fetching,
+		transform: (answer) => {
+			recordTags(event, listTags(toValue(collection), toValue(options).locale, answer.entries));
+			return answer;
+		}
 	});
 }
 /** The entries of a translation group, one per locale. */
 function useHollwareTranslations(collection, group) {
 	const path = computed(() => `/_hollware/translations/${encodeURIComponent(toValue(collection))}/${encodeURIComponent(toValue(group))}`);
-	return useFetch(path);
+	const event = pageRequest();
+	return useFetch(path, { transform: (answer) => {
+		recordTags(event, groupTags(toValue(collection), toValue(group), answer.entries));
+		return answer;
+	} });
 }
 /** The site: its locales, its collections and their schemas. */
 function useHollwareSite() {
-	return useFetch("/_hollware/site");
+	const event = pageRequest();
+	return useFetch("/_hollware/site", { transform: (answer) => {
+		recordTags(event, siteTags());
+		return answer;
+	} });
 }
 //#endregion
 export { useHollwareEntries, useHollwareEntry, useHollwareSite, useHollwareTranslations };

package/dist/runtime/server/cache.d.mts

@@ -0,0 +1,10 @@
+//#region src/runtime/server/cache.d.ts
+/**
+ * The cache of `hollware.cache: 'purge'` (S8): a response that read Hollware and answered 200 is
+ * kept by Cloudflare's Workers Cache, which serves it again without running the Worker, tagged with
+ * what it showed, until an event of Hollware purges one of its tags (`/_hollware/webhook`). The
+ * browser keeps nothing: only the edge does (`cloudflare-cdn-cache-control`).
+ */
+declare const _default: import("nitropack").NitroAppPlugin;
+//#endregion
+export { _default as default };

package/dist/runtime/server/cache.mjs

@@ -0,0 +1,17 @@
+import { edgeHeaders, tagsOf } from "../tags.mjs";
+import { defineNitroPlugin } from "nitropack/runtime";
+//#region src/runtime/server/cache.ts
+/**
+* The cache of `hollware.cache: 'purge'` (S8): a response that read Hollware and answered 200 is
+* kept by Cloudflare's Workers Cache, which serves it again without running the Worker, tagged with
+* what it showed, until an event of Hollware purges one of its tags (`/_hollware/webhook`). The
+* browser keeps nothing: only the edge does (`cloudflare-cdn-cache-control`).
+*/
+var cache_default = defineNitroPlugin((nitroApp) => {
+	nitroApp.hooks.hook("beforeResponse", (event) => {
+		const headers = edgeHeaders(tagsOf(event), event.node.res.statusCode, event.method);
+		for (const [name, value] of Object.entries(headers ?? {})) event.node.res.setHeader(name, value);
+	});
+});
+//#endregion
+export { cache_default as default };

package/dist/runtime/server/reader.mjs

@@ -1,3 +1,4 @@
+import { entryTags, groupTags, listTags, recordTags, siteTags } from "../tags.mjs";
 import { createClient } from "@hollware/client";
 import { createError } from "h3";
 import { useRuntimeConfig } from "nitropack/runtime";
@@ -16,19 +17,48 @@ function useHollware(event) {
 	const binding = typeof env === "object" && env !== null ? Reflect.get(env, config.binding) : void 0;
 	if (isReader(binding)) return {
 		site: config.site,
-		reader: createClient({ binding })
+		reader: tagging(event, createClient({ binding }))
 	};
 	if (config.url !== "" && config.token !== "") return {
 		site: config.site,
-		reader: createClient({
+		reader: tagging(event, createClient({
 			url: config.url,
 			token: config.token
-		})
+		}))
 	};
 	throw createError({
 		statusCode: 500,
 		statusMessage: `Hollware: the Worker has no binding ${config.binding}, and hollware.url with a read token (NUXT_HOLLWARE_TOKEN) is not set.`
 	});
 }
+/**
+* The reader, recording on the request the cache tags of what each read answered (S8): a route of
+* the site's own that reads through `useHollware` is tagged with no work of its own.
+*/
+function tagging(event, reader) {
+	return {
+		...reader,
+		getEntry: async (...args) => {
+			const answer = await reader.getEntry(...args);
+			recordTags(event, entryTags(answer.entry));
+			return answer;
+		},
+		listEntries: async (...args) => {
+			const answer = await reader.listEntries(...args);
+			recordTags(event, listTags(args[1], args[2]?.locale, answer.entries));
+			return answer;
+		},
+		getTranslations: async (...args) => {
+			const answer = await reader.getTranslations(...args);
+			recordTags(event, groupTags(args[1], args[2], answer.entries ?? []));
+			return answer;
+		},
+		describeSite: async (...args) => {
+			const answer = await reader.describeSite(...args);
+			recordTags(event, siteTags());
+			return answer;
+		}
+	};
+}
 //#endregion
 export { useHollware };

package/dist/runtime/server/routes/entries.d.mts

@@ -1,7 +1,7 @@
 //#region src/runtime/server/routes/entries.d.ts
 declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
   outcome: "ok";
-  entries: (Record<string, unknown> | undefined)[];
+  entries: Record<string, unknown>[];
   nextCursor: string | null;
 }>>;
 //#endregion

package/dist/runtime/server/routes/entries.mjs

@@ -19,9 +19,10 @@ var entries_default = defineEventHandler(async (event) => {
 		...limit === void 0 ? {} : { limit: Number(limit) }
 	};
 	const page = await answer(event, () => reader.listEntries(site, getRouterParam(event, "collection") ?? "", options));
+	const entries = page.entries.map(forPage).flatMap((entry) => entry === void 0 ? [] : [entry]);
 	return {
 		outcome: page.outcome,
-		entries: page.entries.map(forPage),
+		entries,
 		nextCursor: page.nextCursor
 	};
 });

package/dist/runtime/server/routes/site.d.mts

@@ -5,6 +5,7 @@ declare const _default: import("h3").EventHandler<import("h3").EventHandlerReque
     key: string;
     locales: string[];
     defaultLocale: string;
+    url: string | null;
     styleGuide: string | null;
     collections: {
       name: string;

package/dist/runtime/server/routes/translations.d.mts

@@ -1,7 +1,7 @@
 //#region src/runtime/server/routes/translations.d.ts
 declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
   outcome: "not_found" | "ok";
-  entries: (Record<string, unknown> | undefined)[];
+  entries: Record<string, unknown>[];
 }>>;
 //#endregion
 export { _default as default };

package/dist/runtime/server/routes/translations.mjs

@@ -5,9 +5,10 @@ import { defineEventHandler, getRouterParam } from "h3";
 var translations_default = defineEventHandler(async (event) => {
 	const { site, reader } = useHollware(event);
 	const group = await answer(event, () => reader.getTranslations(site, getRouterParam(event, "collection") ?? "", getRouterParam(event, "group") ?? ""));
+	const entries = (group.entries ?? []).map(forPage).flatMap((entry) => entry === void 0 ? [] : [entry]);
 	return {
 		outcome: group.outcome,
-		entries: (group.entries ?? []).map(forPage)
+		entries
 	};
 });
 //#endregion

package/dist/runtime/server/routes/webhook.d.mts

@@ -0,0 +1,6 @@
+//#region src/runtime/server/routes/webhook.d.ts
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
+  purged: string[];
+}>>;
+//#endregion
+export { _default as default };

package/dist/runtime/server/routes/webhook.mjs

@@ -0,0 +1,38 @@
+import { verifyWebhook } from "@hollware/core";
+import { createError, defineEventHandler, getRequestHeaders, readRawBody } from "h3";
+import { useRuntimeConfig } from "nitropack/runtime";
+//#region src/runtime/server/routes/webhook.ts
+function cacheOf(context) {
+	const cloudflare = typeof context === "object" && context !== null ? Reflect.get(context, "cloudflare") : void 0;
+	const ctx = typeof cloudflare === "object" && cloudflare !== null ? Reflect.get(cloudflare, "context") : void 0;
+	const cache = typeof ctx === "object" && ctx !== null ? Reflect.get(ctx, "cache") : void 0;
+	return typeof cache === "object" && cache !== null && typeof Reflect.get(cache, "purge") === "function" ? { purge: (options) => Reflect.apply(Reflect.get(cache, "purge"), cache, [options]) } : void 0;
+}
+var webhook_default = defineEventHandler(async (event) => {
+	const config = useRuntimeConfig(event);
+	const secret = String(Reflect.get(Reflect.get(config, "hollware") ?? {}, "webhookSecret") ?? "");
+	const body = await readRawBody(event, "utf8") ?? "";
+	const headers = new Headers(Object.entries(getRequestHeaders(event)).flatMap(([name, value]) => value === void 0 ? [] : [[name, value]]));
+	const now = Math.floor(Date.now() / 1e3);
+	if (secret === "" || !await verifyWebhook({
+		secret,
+		body,
+		headers,
+		now
+	})) throw createError({
+		statusCode: 401,
+		statusMessage: "The signature of the event does not hold"
+	});
+	const payload = JSON.parse(body);
+	const found = typeof payload === "object" && payload !== null ? Reflect.get(payload, "cacheTags") : void 0;
+	const tags = Array.isArray(found) ? found.filter((tag) => typeof tag === "string") : [];
+	const cache = cacheOf(event.context);
+	if (cache === void 0) throw createError({
+		statusCode: 501,
+		statusMessage: "This Worker has no cache to purge: set \"cache\": { \"enabled\": true } in wrangler.jsonc"
+	});
+	if (tags.length > 0) await cache.purge({ tags });
+	return { purged: tags };
+});
+//#endregion
+export { webhook_default as default };

package/dist/runtime/tags.d.mts

@@ -0,0 +1,26 @@
+//#region src/runtime/tags.d.ts
+/** What a request holds of its own, whether Nuxt's or h3's: its context. */
+interface Tagged {
+  readonly context: Record<string, unknown>;
+}
+export declare function recordTags(event: Tagged | undefined, tags: readonly string[]): void;
+export declare function tagsOf(event: Tagged): string[];
+interface Entryish {
+  readonly id?: unknown;
+}
+/** The tags of an entry read alone. */
+export declare function entryTags(entry: Entryish | undefined): string[];
+/** The tags of a list: the list itself, in its locale or every one, and each entry it shows. */
+export declare function listTags(collection: string, locale: string | undefined, entries: readonly Entryish[]): string[];
+/** The tags of the translations of a group. */
+export declare function groupTags(collection: string, group: string, entries: readonly Entryish[]): string[];
+export declare function siteTags(): string[];
+/** How long the edge keeps a page no event purges: a year, the most it keeps anything. */
+export declare const EDGE_SECONDS = 31536000;
+/**
+ * The headers that let the edge keep a response, tagged with what it showed: only a GET that
+ * answered 200 and read Hollware. An error, a redirect or a write is never kept, nor a response
+ * that read nothing to purge it by. The browser keeps nothing; only the edge does.
+ */
+export declare function edgeHeaders(tags: readonly string[], status: number, method: string): Readonly<Record<string, string>> | null;
+//#endregion

package/dist/runtime/tags.mjs

@@ -0,0 +1,55 @@
+import { EVERY_LOCALE, SITE_TAG, entryTag, groupTag, listTag } from "@hollware/core";
+//#region src/runtime/tags.ts
+/**
+* The cache tags of a response (S8): what it showed of Hollware, in the names of the contract of
+* `@hollware/core`, gathered on its request as each read answers, and written as `Cache-Tag` once
+* it is rendered. A page gathers the tags of every read it made; a route of `/_hollware/` those of
+* its own.
+*/
+const KEY = "hollwareTags";
+function recordTags(event, tags) {
+	if (event === void 0 || tags.length === 0) return;
+	const found = event.context[KEY];
+	const set = found instanceof Set ? found : /* @__PURE__ */ new Set();
+	for (const tag of tags) set.add(tag);
+	event.context[KEY] = set;
+}
+function tagsOf(event) {
+	const found = event.context[KEY];
+	return found instanceof Set ? [...found].map(String) : [];
+}
+function idsOf(entries) {
+	return entries.flatMap((entry) => typeof entry.id === "string" ? [entryTag(entry.id)] : []);
+}
+/** The tags of an entry read alone. */
+function entryTags(entry) {
+	return entry === void 0 ? [] : idsOf([entry]);
+}
+/** The tags of a list: the list itself, in its locale or every one, and each entry it shows. */
+function listTags(collection, locale, entries) {
+	return [listTag(collection, locale ?? EVERY_LOCALE), ...idsOf(entries)];
+}
+/** The tags of the translations of a group. */
+function groupTags(collection, group, entries) {
+	return [groupTag(collection, group), ...idsOf(entries)];
+}
+function siteTags() {
+	return [SITE_TAG];
+}
+/** How long the edge keeps a page no event purges: a year, the most it keeps anything. */
+const EDGE_SECONDS = 31536e3;
+/**
+* The headers that let the edge keep a response, tagged with what it showed: only a GET that
+* answered 200 and read Hollware. An error, a redirect or a write is never kept, nor a response
+* that read nothing to purge it by. The browser keeps nothing; only the edge does.
+*/
+function edgeHeaders(tags, status, method) {
+	if (tags.length === 0 || status !== 200 || method !== "GET") return null;
+	return {
+		"cache-tag": tags.join(","),
+		"cache-control": "public, max-age=0, must-revalidate",
+		"cloudflare-cdn-cache-control": `max-age=${EDGE_SECONDS}`
+	};
+}
+//#endregion
+export { EDGE_SECONDS, edgeHeaders, entryTags, groupTags, listTags, recordTags, siteTags, tagsOf };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hollware/nuxt",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Read Hollware from a Nuxt site, over a service binding or HTTP.",
   "homepage": "https://hollware.com",
   "bugs": {
@@ -29,7 +29,8 @@
   },
   "dependencies": {
     "@comark/vue": "0.7.0",
-    "@hollware/client": "0.6.0",
+    "@hollware/client": "0.8.0",
+    "@hollware/core": "0.8.0",
     "@nuxt/kit": "4.6.1"
   },
   "devDependencies": {