@hollware/nuxt 0.10.0 → 0.11.0

package/README.md

@@ -49,6 +49,27 @@ const { data } = await useHollwareEntry('blog', 'en', useRoute().params.slug as
 Every page carries `<meta name="generator" content="Hollware">`; set `hollware.generator: false`
 to leave it out.
 
+## Previews
+
+"Preview on the site" in the admin opens the entry's page with `?hollware-preview=<token>`, a
+signed link for one entry that works for one hour. The module answers that request with a `303` to
+the same URL without the parameter (other parameters kept) and keeps the token in the
+`hollware_preview` cookie: `HttpOnly`, `SameSite=Lax`, `Path=/`, an hour, and `Secure` on every
+request but `http://localhost` and `http://127.0.0.1`, so local development works. The token is in
+a URL once: not in the address bar, the history, a `Referer` or a copied link, but for the first
+request's line in the logs. A value not shaped like a token sets no cookie.
+
+A request with the cookie reads the latest revision of that entry through `useHollwareEntry`, a
+draft included, and nothing keeps what it answers: no cache tag, `Cache-Control: no-store`, and the
+cache of `hollware.cache` neither serves nor stores it. A token that is expired or not valid is
+refused by Hollware: the page is what it is without a token (a 404 for a draft) and the response
+clears the cookie. A token for another entry is answered as no entry and keeps the cookie. It needs
+the Worker secret `HOLLWARE_SECRET` in Hollware.
+
+The redirect adds `hollware-view=<random>` to the URL: a value of no secret, new for each link, so
+the previewed page is at a URL no cache holds, and Workers Cache in front of the site (`cache:
+'purge'`) cannot answer it with the published page before the Worker reads the cookie.
+
 ## Links
 
 - Docs: <https://hollware.com>

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { PREVIEW_HEADER } from "./runtime/tags.mjs";
 import { addComponent, addImports, addPlugin, addServerHandler, addServerImports, addServerPlugin, createResolver, defineNuxtModule } from "@nuxt/kit";
 //#region src/index.ts
 const name = "@hollware/nuxt";
@@ -53,6 +54,11 @@ var src_default = defineNuxtModule({
 			filePath: resolve("./runtime/components/HollwareContent")
 		});
 		if (options.generator) addPlugin(resolve("./runtime/generator"));
+		addServerPlugin(resolve("./runtime/server/preview"));
+		addServerHandler({
+			middleware: true,
+			handler: resolve("./runtime/server/preview-exchange")
+		});
 		if (options.cache === "purge") {
 			addServerPlugin(resolve("./runtime/server/cache"));
 			addServerHandler({
@@ -62,7 +68,11 @@ var src_default = defineNuxtModule({
 			});
 		}
 		if (typeof options.cache === "number" && options.cache > 0) {
-			const pages = { swr: options.cache };
+			const pages = { cache: {
+				swr: true,
+				maxAge: options.cache,
+				varies: [PREVIEW_HEADER]
+			} };
 			const routes = {
 				swr: false,
 				cache: false

package/dist/runtime/composables.d.mts

@@ -1,7 +1,15 @@
 import { PageEntry } from "./types.mjs";
 import { MaybeRefOrGetter } from "vue";
 //#region src/runtime/composables.d.ts
-/** An entry, with its Comark document; `data` is null while it loads, `error` a 404 when it is not published. */
+/**
+ * An entry, with its Comark document; `data` is null while it loads, `error` a 404 when it is not
+ * published. A visitor who opened the admin's "Preview on the site" link has the token in the
+ * `hollware_preview` cookie (the server exchanged it for the link's `?hollware-preview=`), and the
+ * `/_hollware/entry` route reads the latest revision of that entry instead: a draft too. The page
+ * then answers `no-store`; a token that does not hold (expired, of another entry) is an error,
+ * never the published version, and when Hollware says it expired or is invalid the response
+ * clears the cookie.
+ */
 export declare function useHollwareEntry(collection: MaybeRefOrGetter<string>, locale: MaybeRefOrGetter<string>, slug: MaybeRefOrGetter<string>): import("nuxt/app").AsyncData<{
   outcome: 'ok';
   entry: PageEntry;

package/dist/runtime/composables.mjs

@@ -1,5 +1,6 @@
 import { entryTags, groupTags, listTags, recordTags, siteTags } from "./tags.mjs";
 import { useFetch, useRequestEvent } from "nuxt/app";
+import { appendResponseHeader } from "h3";
 import { computed, toValue } from "vue";
 //#region src/runtime/composables.ts
 /**
@@ -12,15 +13,26 @@ import { computed, toValue } from "vue";
 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. */
+/**
+* An entry, with its Comark document; `data` is null while it loads, `error` a 404 when it is not
+* published. A visitor who opened the admin's "Preview on the site" link has the token in the
+* `hollware_preview` cookie (the server exchanged it for the link's `?hollware-preview=`), and the
+* `/_hollware/entry` route reads the latest revision of that entry instead: a draft too. The page
+* then answers `no-store`; a token that does not hold (expired, of another entry) is an error,
+* never the published version, and when Hollware says it expired or is invalid the response
+* clears the cookie.
+*/
 function useHollwareEntry(collection, locale, slug) {
 	const path = computed(() => `/_hollware/entry/${encodeURIComponent(toValue(collection))}/${encodeURIComponent(toValue(locale))}/${encodeURIComponent(toValue(slug))}`);
 	const event = pageRequest();
 	return useFetch(path, {
-		key: path.value,
 		transform: (answer) => {
 			recordTags(event, entryTags(answer.entry));
 			return answer;
+		},
+		onResponseError: ({ response }) => {
+			if (event === void 0) return;
+			for (const cookie of response.headers.getSetCookie()) appendResponseHeader(event, "set-cookie", cookie);
 		}
 	});
 }

package/dist/runtime/server/answer.mjs

@@ -1,5 +1,5 @@
-import { HollwareClientError } from "@hollware/client";
 import { createError, setResponseHeader } from "h3";
+import { HollwareClientError } from "@hollware/client";
 //#region src/runtime/server/answer.ts
 /**
 * Hollware's answer as the site's own: a `not_found` outcome is a 404, a refusal of the read API

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

@@ -3,7 +3,7 @@
  * 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`).
+ * browser keeps nothing: only the edge does (`cloudflare-cdn-cache-control`). A preview is never kept.
  */
 declare const _default: import("nitropack").NitroAppPlugin;
 //#endregion

package/dist/runtime/server/cache.mjs

@@ -1,14 +1,16 @@
 import { edgeHeaders, tagsOf } from "../tags.mjs";
+import { previewTokenFromCookie } from "@hollware/client";
 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`).
+* browser keeps nothing: only the edge does (`cloudflare-cdn-cache-control`). A preview is never kept.
 */
 var cache_default = defineNitroPlugin((nitroApp) => {
 	nitroApp.hooks.hook("beforeResponse", (event) => {
+		if (previewTokenFromCookie(event.node.req.headers.cookie) !== void 0) return;
 		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);
 	});

package/dist/runtime/server/preview-exchange.d.mts

@@ -0,0 +1,11 @@
+//#region src/runtime/server/preview-exchange.d.ts
+/**
+ * The link of the admin's "Preview on the site" (`?hollware-preview=<token>`) is exchanged for a
+ * cookie, so the token is in a URL once: a `303` to the same URL without the parameter, with the
+ * token in `hollware_preview` (HttpOnly, SameSite=Lax, an hour, Secure but on http://localhost and
+ * http://127.0.0.1), `no-store` and `Referrer-Policy: no-referrer`. The token is not checked here:
+ * Hollware does, when the page reads. A value not shaped like a token sets no cookie.
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void> | undefined>;
+//#endregion
+export { _default as default };

package/dist/runtime/server/preview-exchange.mjs

@@ -0,0 +1,22 @@
+import { requestUrl } from "./url.mjs";
+import { defineEventHandler, sendRedirect, setResponseHeader } from "h3";
+import { exchangeHeaders, exchangePreviewLink } from "@hollware/client";
+//#region src/runtime/server/preview-exchange.ts
+/**
+* The link of the admin's "Preview on the site" (`?hollware-preview=<token>`) is exchanged for a
+* cookie, so the token is in a URL once: a `303` to the same URL without the parameter, with the
+* token in `hollware_preview` (HttpOnly, SameSite=Lax, an hour, Secure but on http://localhost and
+* http://127.0.0.1), `no-store` and `Referrer-Policy: no-referrer`. The token is not checked here:
+* Hollware does, when the page reads. A value not shaped like a token sets no cookie.
+*/
+var preview_exchange_default = defineEventHandler((event) => {
+	if (event.method !== "GET" && event.method !== "HEAD") return;
+	const url = requestUrl(event);
+	if (url.pathname.startsWith("/_hollware/")) return;
+	const exchange = exchangePreviewLink(url);
+	if (exchange === void 0) return;
+	for (const [name, value] of exchangeHeaders(exchange, url)) if (name !== "location") setResponseHeader(event, name, value);
+	return sendRedirect(event, exchange.location, 303);
+});
+//#endregion
+export { preview_exchange_default as default };

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

@@ -0,0 +1,12 @@
+//#region src/runtime/server/preview.d.ts
+/**
+ * A request that carries a preview token (the `hollware_preview` cookie, see `preview-exchange`)
+ * reads the latest revision of an entry, and nothing may keep what it answers: the response is
+ * `no-store` and has no cache tag, so neither the browser nor Workers Cache keeps it, and the
+ * request gets a header of its own for Nitro's cache (`hollware.cache: <seconds>`) to vary on, so
+ * it neither reads nor fills the entry that every other request of the path shares. Any request
+ * without a token has no such header, whatever it sent.
+ */
+declare const _default: import("nitropack").NitroAppPlugin;
+//#endregion
+export { _default as default };

package/dist/runtime/server/preview.mjs

@@ -0,0 +1,27 @@
+import { PREVIEW_HEADER } from "../tags.mjs";
+import { removeResponseHeader, setResponseHeader } from "h3";
+import { previewTokenFromCookie } from "@hollware/client";
+import { defineNitroPlugin } from "nitropack/runtime";
+//#region src/runtime/server/preview.ts
+/**
+* A request that carries a preview token (the `hollware_preview` cookie, see `preview-exchange`)
+* reads the latest revision of an entry, and nothing may keep what it answers: the response is
+* `no-store` and has no cache tag, so neither the browser nor Workers Cache keeps it, and the
+* request gets a header of its own for Nitro's cache (`hollware.cache: <seconds>`) to vary on, so
+* it neither reads nor fills the entry that every other request of the path shares. Any request
+* without a token has no such header, whatever it sent.
+*/
+var preview_default = defineNitroPlugin((nitroApp) => {
+	nitroApp.hooks.hook("request", (event) => {
+		const headers = event.node.req.headers;
+		if (previewTokenFromCookie(headers.cookie) === void 0) delete headers[PREVIEW_HEADER];
+		else headers[PREVIEW_HEADER] = crypto.randomUUID();
+	});
+	nitroApp.hooks.hook("beforeResponse", (event) => {
+		if (previewTokenFromCookie(event.node.req.headers.cookie) === void 0) return;
+		setResponseHeader(event, "cache-control", "no-store");
+		for (const name of ["cache-tag", "cloudflare-cdn-cache-control"]) removeResponseHeader(event, name);
+	});
+});
+//#endregion
+export { preview_default as default };

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

@@ -1,5 +1,5 @@
-import { HollwareReader } from "@hollware/client";
 import { H3Event } from "h3";
+import { HollwareReader } from "@hollware/client";
 //#region src/runtime/server/reader.d.ts
 /**
  * The site's reader of Hollware for a request: the service binding when the Worker has it, else

package/dist/runtime/server/reader.mjs

@@ -1,6 +1,6 @@
 import { entryTags, groupTags, listTags, recordTags, siteTags } from "../tags.mjs";
-import { createClient } from "@hollware/client";
 import { createError } from "h3";
+import { createClient } from "@hollware/client";
 import { useRuntimeConfig } from "nitropack/runtime";
 //#region src/runtime/server/reader.ts
 function isReader(value) {
@@ -40,7 +40,7 @@ function tagging(event, reader) {
 		...reader,
 		getEntry: async (...args) => {
 			const answer = await reader.getEntry(...args);
-			recordTags(event, entryTags(answer.entry));
+			if (args[4]?.preview === void 0) recordTags(event, entryTags(answer.entry));
 			return answer;
 		},
 		listEntries: async (...args) => {

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

@@ -1,11 +1,25 @@
 import { answer, forPage } from "../answer.mjs";
+import { requestUrl } from "../url.mjs";
 import { useHollware } from "../reader.mjs";
-import { defineEventHandler, getRouterParam } from "h3";
+import { appendResponseHeader, createError, defineEventHandler, getHeader, getRouterParam } from "h3";
+import { clearedPreviewCookie, isPreviewRefusal, isSecureRequest, previewTokenFromCookie } from "@hollware/client";
 //#region src/runtime/server/routes/entry.ts
 var entry_default = defineEventHandler(async (event) => {
 	const { site, reader } = useHollware(event);
 	const param = (name) => getRouterParam(event, name) ?? "";
-	const found = await answer(event, () => reader.getEntry(site, param("collection"), param("slug"), param("locale"), { formats: ["document"] }));
+	const preview = previewTokenFromCookie(getHeader(event, "cookie"));
+	const found = await answer(event, () => reader.getEntry(site, param("collection"), param("slug"), param("locale"), {
+		formats: ["document"],
+		...preview === void 0 ? {} : { preview }
+	}).catch((error) => {
+		if (preview === void 0 || !isPreviewRefusal(error)) throw error;
+		const secure = isSecureRequest(requestUrl(event));
+		appendResponseHeader(event, "set-cookie", clearedPreviewCookie({ secure }));
+		throw createError({
+			statusCode: 404,
+			statusMessage: "Not found in Hollware"
+		});
+	}));
 	return {
 		outcome: found.outcome,
 		entry: forPage(found.entry)

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

@@ -0,0 +1,8 @@
+import { H3Event } from "h3";
+//#region src/runtime/server/url.d.ts
+/**
+ * The URL the visitor asked for. On Workers it is the one of the Request itself, whose scheme and
+ * host are the real ones; elsewhere h3 builds it from the `Host` header.
+ */
+export declare function requestUrl(event: H3Event): URL;
+//#endregion

package/dist/runtime/server/url.mjs

@@ -0,0 +1,13 @@
+import { getRequestURL } from "h3";
+//#region src/runtime/server/url.ts
+/**
+* The URL the visitor asked for. On Workers it is the one of the Request itself, whose scheme and
+* host are the real ones; elsewhere h3 builds it from the `Host` header.
+*/
+function requestUrl(event) {
+	const request = event.context["cloudflare"]?.request;
+	const url = typeof request === "object" && request !== null ? Reflect.get(request, "url") : void 0;
+	return typeof url === "string" ? new URL(url) : getRequestURL(event);
+}
+//#endregion
+export { requestUrl };

package/dist/runtime/tags.d.mts

@@ -23,5 +23,11 @@ export declare const EDGE_SECONDS = 31536000;
  * 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;
+/**
+ * A request header that only the preview plugin sets, and that Nitro's cache (`cache: <seconds>`)
+ * varies on: a preview gets a fresh value each time, so it never reads or fills the entry that
+ * every other request of the same path shares.
+ */
+export declare const PREVIEW_HEADER = "x-hollware-preview";
 //#endregion
 export {};

package/dist/runtime/tags.mjs

@@ -51,5 +51,11 @@ function edgeHeaders(tags, status, method) {
 		"cloudflare-cdn-cache-control": `max-age=${EDGE_SECONDS}`
 	};
 }
+/**
+* A request header that only the preview plugin sets, and that Nitro's cache (`cache: <seconds>`)
+* varies on: a preview gets a fresh value each time, so it never reads or fills the entry that
+* every other request of the same path shares.
+*/
+const PREVIEW_HEADER = "x-hollware-preview";
 //#endregion
-export { EDGE_SECONDS, edgeHeaders, entryTags, groupTags, listTags, recordTags, siteTags, tagsOf };
+export { EDGE_SECONDS, PREVIEW_HEADER, edgeHeaders, entryTags, groupTags, listTags, recordTags, siteTags, tagsOf };

package/package.json

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