@mapled/next 0.10.0 → 0.11.0

package/README.md

@@ -369,11 +369,30 @@ export function UpdateNotice() {
 ```
 
 - It is polling, and it is cheap: tabs ask **your** route, never Mapled. The route reuses one answer for `ttl` seconds (default 5) — in the instance and, through `s-maxage`, at the CDN in front of it — and a check that finds nothing new is a 304. However many tabs are open, Mapled hears from the site a few times a minute, and the key's rate limit is left for reads.
-- The route reads the release under the same `mapled` cache tag as the content, so it moves when the webhook refreshes the cache and not before — a tab that refreshes on it never renders the old release again. Live updates therefore need the webhook from [Refresh on publish](#refresh-on-publish); without it both change only when their ISR window (`revalidate`, 3600 by default) runs out.
+- The route moves when the webhook has refreshed your site's cache, and not before — a tab that refreshes on it never renders the old release again. It reads the release under the same `mapled` cache tag as the content, and never names one newer than the release your site's cache last answered the publish webhook for: the webhook handler revalidates the cache before it answers, its answer carries the cache's mark (`x-mapled-cache`), and Mapled records the answer with the mark. So a cache entry filled early — after a deploy, an eviction, or when its `revalidate` window runs out between a publish and its webhook — doesn't move the route ahead of the pages. Only while a publish's webhook is on its way — or failing — does the route ask Mapled past its cache, once per `ttl`. Live updates therefore need the webhook from [Refresh on publish](#refresh-on-publish): until your site has answered a publish's webhook, the route names the release before it (`null` before the first one it answered), and without a webhook it names nothing new — nothing tells it when your pages have a release, so open tabs don't follow Publish. A new webhook address starts over: the site there hasn't answered anything yet.
+- Live updates follow the deployment the webhook reaches. Another deployment on the same key — a preview, a second site — renders from a cache of its own, which no publish revalidates, so its route names no release and its open tabs stay as they are. The route tells the answers apart by the mark: each Next.js cache keeps its own (`cacheMark()`), so deployments that share a cache share the mark, and one with a cache of its own has another. After a deploy onto a fresh cache — or once the cache has lost the mark — the route names no release until the next publish's webhook has been answered from that cache. (Before 0.11.0 such a deployment followed the webhook's one and could refresh its tabs into the release they already showed.)
+- A webhook handler of your own — one that refreshes more than the `mapled` tag, say — answers with the cache's mark, or the route names no release (it logs once why):
+
+```ts
+import { revalidateTag } from "next/cache";
+import { cacheMark, verifySignature } from "@mapled/next/server";
+
+export async function POST(req: Request) {
+  const body = await req.text();
+  const signature = req.headers.get("x-mapled-signature") ?? "";
+  if (!(await verifySignature(process.env.MAPLED_WEBHOOK_SECRET!, body, signature))) {
+    return Response.json({ error: "Invalid signature." }, { status: 401 });
+  }
+  revalidateTag("mapled");
+  // after revalidating: the mark says which cache has let go of the old release
+  return Response.json({ revalidated: true }, { headers: { "x-mapled-cache": await cacheMark() } });
+}
+```
+
 - The route answers `{ release, publishedAt }` — the number of publishes and the time of the last one, nothing else — and may be cached by anyone. While Mapled can't be reached it keeps answering the last release it knew.
 - Expect a publish to reach an open tab in about ten seconds with the defaults. `<MapledLive interval={3} />` and `createReleaseHandler({ key, ttl: 1 })` make it quicker at the price of more requests to your site.
 - With a `basePath` in `next.config`, the route answers under it, and so does the default: `<MapledLive />` asks `/docs/api/mapled/release` on a site with `basePath: "/docs"` — Next writes the basePath into the bundle, and the component reads it from there (0.10.0 and later; earlier versions ask `/api/mapled/release`). An `endpoint` you pass is asked as written, basePath included: `<MapledLive endpoint="/docs/live" />`.
-- Leave route segment config off the release route: `createReleaseHandler` sets how it is cached. `dynamic = "force-static"` turns it into a copy Next builds without the tab's request, and `fetchCache = "force-no-store"` reads the release past the cache tag — the route would move before the webhook refreshes the pages. `dynamic = "force-dynamic"` does the same when the handler's `revalidate` is `false` or `0`; at its default it is harmless. Middleware that runs on the route has to let the tab's `GET` through: no redirect, rewrite or sign-in wall. `output: "export"` has no server to run the route at all.
+- Leave route segment config off the release route: `createReleaseHandler` sets how it is cached. `dynamic = "force-static"` turns it into a copy Next builds without the tab's request, and `fetchCache = "force-no-store"` reads the release past the cache tag, so Mapled hears from the route every `ttl`. `dynamic = "force-dynamic"` does the same when the handler's `revalidate` is `false` or `0`; at its default it is harmless. On the webhook route, leave `fetchCache` off too: with `"force-no-store"` every answer names a new cache mark, and the release route may name no release. Middleware that runs on the route has to let the tab's `GET` through: no redirect, rewrite or sign-in wall. `output: "export"` has no server to run the route at all.
 
 Outside React, `watchRelease({ onPublish })` from `@mapled/next` is the same watch as a plain function — it returns the function that stops it.
 
@@ -506,6 +525,8 @@ await db.remove("orders", id);
 
 The server key reaches only operational collections with access class `public`/`server` — editorial content, internal and sensitive collections stay out of reach, and it grants nothing on the Management API.
 
+A write is checked against the collection's fields: data that doesn't fit them is a 400 `VALIDATION_FAILED`, a slug another record uses a 409 `SLUG_TAKEN`. A write that ran while a field it sends was renamed, removed or changed is a 409 `FIELDS_CHANGED` and writes nothing — send it again against the fields as they are now.
+
 ## Without Next.js: the HTTP API
 
 The client is a thin layer over a plain HTTP API, so any site — or a build script — can read Mapled. The base URL is `https://api.mapled.io`; every request carries the delivery key in `x-mapled-key`.
@@ -516,7 +537,7 @@ The client is a thin layer over a plain HTTP API, so any site — or a build scr
 | `GET /v1/delivery/collections/{collection}/records/{id}` | `{ record, release }` — 404 when it isn't in the release |
 | `GET /v1/delivery/collections/{collection}/records/by-slug/{slug}` | `{ record, release }` |
 | `GET /v1/delivery/singles/{single}` | `{ record, release }` — `record` is `null` while the single is empty |
-| `GET /v1/delivery/release` | `{ release, publishedAt }` — the release being served now; `null`s before the first publish |
+| `GET /v1/delivery/release` | `{ release, publishedAt }` — the release being served now; `null`s before the first publish. With `?webhook=1` also `webhook`: `{ release, publishedAt, deliveredAt, cache }` of the newest release your site answered the publish webhook for, with the `x-mapled-cache` mark the answer carried (`null`s before the first, and again after the webhook's address changes), or `null` when the project has no webhook |
 | `POST /v1/delivery/forms/{form}` | `201 { ok: true }` — see [Forms](#forms) |
 
 ```bash
@@ -528,7 +549,7 @@ curl -H "x-mapled-key: $MAPLED_KEY" \
 - Only published content of collections with access **Public** is served; sensitive fields are never in an answer. Image and file values are asset ids — `https://api.mapled.io/files/{id}` is the file, with `?w=`, `h=`, `fit=`, `fmt=`, `q=` for a resized variant.
 - Answers are per key — `Cache-Control: private` — with an `ETag`: send it back as `If-None-Match` and an unchanged answer is a 304. A read pinned with `release=N` never changes and may be cached for good. `GET /v1/delivery/release` is the cheap way to learn that something was published: relay it from a route of your own server, and `watchRelease({ endpoint, onPublish })` from `@mapled/next` — no framework in it — tells open tabs ([Live updates](#live-updates)).
 - Errors share one envelope: `{ error: { code, message, requestId } }`. A key gets 1,200 requests a minute; past that, 429 `RATE_LIMITED` with `retry-after`.
-- The publish webhook is a `POST` with a JSON body `{ event, project, release, at, id }` and the headers `x-mapled-event` (`release.published`, `project.restored` or `test`), `x-mapled-event-id` (the same on every retry — use it to deduplicate), `x-mapled-attempt` and `x-mapled-signature`: `sha256=` followed by the hex HMAC-SHA256 of the raw body with the signing secret. Compare in constant time, answer 2xx within 5 seconds. `verifySignature` from `@mapled/next/server` does the check anywhere Web Crypto exists.
+- The publish webhook is a `POST` with a JSON body `{ event, project, release, at, id }` and the headers `x-mapled-event` (`release.published`, `project.restored` or `test`), `x-mapled-event-id` (the same on every retry — use it to deduplicate), `x-mapled-attempt` and `x-mapled-signature`: `sha256=` followed by the hex HMAC-SHA256 of the raw body with the signing secret. Compare in constant time, answer 2xx within 5 seconds. `verifySignature` from `@mapled/next/server` does the check anywhere Web Crypto exists. An answer may carry `x-mapled-cache` — up to 64 letters, digits, `-` or `_` naming the cache the handler revalidated; Mapled records it with the release, and the `?webhook=1` pointer gives it back.
 - Live data: `GET` / `POST /v1/app/collections/{collection}/records` and `GET` / `PATCH` / `DELETE /v1/app/collections/{collection}/records/{id}` with the server key in `x-mapled-server-key`; writes send `{ "data": { … } }`.
 
 Preview (drafts on the site) is built on Next.js draft mode and ships with this package only.
@@ -545,5 +566,6 @@ Preview (drafts on the site) is built on Next.js draft mode and ships with this
 - `createReleaseHandler({ key, apiUrl?, ttl?, revalidate? })` — App Router `GET` handler of the release route; `<MapledLive endpoint? interval? onPublish? />` from `@mapled/next/live` and `watchRelease({ endpoint?, interval?, onPublish })` ask it
 - `createPagesReleaseHandler({ key, apiUrl?, ttl? })` — Pages Router API route of the release route (the default export of `pages/api/mapled/release.ts`); `<MapledLive endpoint? interval? onPublish? />` from `@mapled/next/live/pages` asks it
 - `verifySignature(secret, body, signature)` — if you'd rather build your own handler
+- `cacheMark()` — the mark of this deployment's Next.js cache: a webhook handler of your own answers with it in `x-mapled-cache` (`createRevalidateHandler` does), and `createReleaseHandler` follows only an answer that carries its own
 
 The delivery key only reads published, public content — safe to use anywhere.

package/dist/server.d.ts

@@ -19,6 +19,16 @@ export declare function createPreviewHandler(options?: {
 }): (req: Request) => Promise<Response>;
 /** GET handler to leave preview (mount at /api/mapled/preview/exit). */
 export declare function createExitPreviewHandler(): (req: Request) => Promise<Response>;
+/** The mark of this deployment's Next.js cache: a random value made once
+    and kept in that cache, never expiring (`unstable_cache`). Handlers
+    that read through the same cache read the same mark; a deployment
+    with a cache of its own — a preview, another site on the same key —
+    reads another. `createRevalidateHandler` answers the publish webhook
+    with it (`x-mapled-cache`), Mapled records it with the release the
+    answer acknowledges, and the release route follows only an
+    acknowledgement its own cache gave (§18.8). Outside Next.js, or while
+    its cache doesn't answer, the mark is this process's. */
+export declare function cacheMark(): Promise<string>;
 export declare function createRevalidateHandler(options: {
     secret: string;
     /** Cache tags to refresh — defaults to ["mapled"], which covers every
@@ -34,10 +44,12 @@ type ReleaseOptions = {
 /** GET handler for the release route of an App Router site (mount at
     app/api/mapled/release/route.ts): the release this site serves right
     now, for `<MapledLive />` from "@mapled/next/live" to ask about. The
-    pointer is read under the "mapled" tag like the content is, so it
-    moves when the publish webhook refreshes the cache and not before — a
-    tab that refreshes on it renders the new release, never the old one
-    again. */
+    pointer is read under the "mapled" tag like the content is, and never
+    past the release this deployment's cache has acknowledged through the
+    publish webhook — however the cache entry was filled, the route moves
+    when the webhook has refreshed this cache and not before, so a tab
+    that refreshes on it renders the new release, never the old one
+    again. A deployment the webhook doesn't reach names none. */
 export declare function createReleaseHandler(options: ReleaseOptions & {
     /** ISR window of the pointer, the same as a read's (default 3600 — the webhook keeps it fresh). */
     revalidate?: number | false;

package/dist/server.js

@@ -83,6 +83,44 @@ export function createExitPreviewHandler() {
         });
     };
 }
+/** A mark as `cacheMark` makes them: 32 hex digits. */
+const MARK = /^[0-9a-f]{32}$/;
+function mint() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** what `unstable_cache` runs when the cache has no mark yet */
+async function minted() {
+    return mint();
+}
+/** the mark where no Next.js cache answers: this process's */
+let processMark;
+let nextCache;
+/** "next/cache", loaded once — by the first handler that needs it */
+const cacheModule = () => (nextCache ??= import("next/cache"));
+/** The mark of this deployment's Next.js cache: a random value made once
+    and kept in that cache, never expiring (`unstable_cache`). Handlers
+    that read through the same cache read the same mark; a deployment
+    with a cache of its own — a preview, another site on the same key —
+    reads another. `createRevalidateHandler` answers the publish webhook
+    with it (`x-mapled-cache`), Mapled records it with the release the
+    answer acknowledges, and the release route follows only an
+    acknowledgement its own cache gave (§18.8). Outside Next.js, or while
+    its cache doesn't answer, the mark is this process's. */
+export async function cacheMark() {
+    try {
+        const { unstable_cache } = await cacheModule();
+        // bound: Next keys the entry by the function's source, and a bound function's reads the same in every bundle
+        const mark = await unstable_cache(minted.bind(null), ["@mapled/next", "cache-mark"], { revalidate: false })();
+        if (typeof mark === "string" && MARK.test(mark))
+            return mark;
+    }
+    catch {
+        // outside Next.js, or its cache didn't answer
+    }
+    return (processMark ??= mint());
+}
 export function createRevalidateHandler(options) {
     if (!options.secret) {
         throw new Error("Mapled: the webhook secret is required.");
@@ -93,56 +131,151 @@ export function createRevalidateHandler(options) {
         if (!signature || !(await verifySignature(options.secret, body, signature))) {
             return Response.json({ error: "Invalid signature." }, { status: 401 });
         }
-        const { revalidateTag } = await import("next/cache");
+        const { revalidateTag } = await cacheModule();
         for (const tag of options.tags ?? ["mapled"])
             revalidateTag(tag);
-        return Response.json({ revalidated: true });
+        // which cache this answer speaks for: the release route follows only its own (§18.8)
+        return Response.json({ revalidated: true }, { headers: { "x-mapled-cache": await cacheMark() } });
     };
 }
+/** `{ release, publishedAt }` as Mapled writes it — a release, or nulls
+    before the first; anything else throws. */
+function asPointer(body) {
+    const { release = null, publishedAt = null } = (body ?? {});
+    if (release === null)
+        return { release: null, publishedAt: null };
+    if (!Number.isInteger(release) || release < 1 || typeof publishedAt !== "string") {
+        throw new Error("Mapled's answer wasn't a release");
+    }
+    return { release, publishedAt };
+}
+/** The pointer's `webhook` as Mapled writes it; anything else throws. */
+function asAcknowledged(body) {
+    const { cache = null } = (body ?? {});
+    if (cache !== null && typeof cache !== "string")
+        throw new Error("Mapled's answer wasn't a release");
+    return { ...asPointer(body), cache };
+}
+/** The pointer and, when asked with `?webhook=1`, the release the site
+    has acknowledged through its publish webhook: null — the project has
+    no webhook; undefined — this Mapled doesn't say. `copy` is the answer
+    as it came, to tell one cached copy from another. */
+async function readPointer(url, init) {
+    const res = await fetch(url, init);
+    if (!res.ok)
+        throw new Error(`Mapled answered ${res.status}`);
+    const copy = await res.text();
+    const body = JSON.parse(copy);
+    const webhook = body?.webhook;
+    return { live: asPointer(body), acknowledged: webhook === undefined ? undefined : webhook === null ? null : asAcknowledged(webhook), copy };
+}
+const NONE = { release: null, publishedAt: null };
+const UNACKNOWLEDGED = { ...NONE, cache: null };
+/** What the route names for a copy naming `live`: the release this
+    cache acknowledged, never past `live` — none when the acknowledgement
+    is another cache's, or names none. */
+function follow(acknowledged, live, mark) {
+    if (acknowledged.cache !== mark || acknowledged.release === null)
+        return NONE;
+    if (acknowledged.release >= (live.release ?? 0))
+        return live;
+    return { release: acknowledged.release, publishedAt: acknowledged.publishedAt };
+}
 /** The release route, whichever router mounts it: one answer reused for
     `ttl` seconds, in this instance and at the CDN in front of it —
     however many tabs ask, Mapled hears from the site a few times a
     minute. `next` is how the pointer is fetched: under the content's
     cache tag in the App Router, as is in the Pages Router, which has no
-    such cache. */
+    such cache.
+
+    Under the tag the answer is the one the site's cache holds, and an
+    entry can be filled at any moment — cold after a deploy, evicted,
+    expired — also between a publish's commit and its webhook, while the
+    pages still render the release before. So the App Router asks with
+    `?webhook=1` and never names a release newer than the one this
+    site's cache has acknowledged through the webhook: the site
+    revalidates before it answers, and Mapled records the answer with the
+    cache's mark. An answer from another cache — the deployment the
+    webhook reaches, when this one is a preview or another site on the
+    same key — says nothing of this one's pages. Nothing else proves a
+    release rendered — without a webhook, from a Mapled that doesn't say,
+    or while the acknowledgement is another cache's, the route names
+    none. Only while the cached copy names a release it doesn't say is
+    acknowledged does the route ask Mapled as it is now — the site may
+    have answered since the copy was made — once a ttl, until Mapled
+    says a webhook for it was answered. */
 function releaseAnswers(options, next) {
     if (!options.key)
         throw new Error("Mapled: a delivery key is required.");
     const base = (options.apiUrl ?? "https://api.mapled.io").replace(/\/+$/, "");
     const ttlMs = Math.max(1, options.ttl ?? 5) * 1000;
+    const headers = { "x-mapled-key": options.key };
     let held = null;
+    /** the cached copy Mapled has since said a webhook for was answered, and what that means here: not asked about again */
+    let settled = null;
     /** when Mapled was last asked — an answer or a failure, either waits a ttl */
     let askedAt = 0;
     let loading = null;
     let complained = false;
+    let unmarkedSaid = false;
+    /** What this site's pages render: the cached pointer, capped at the
+        release this site's cache has acknowledged. `trouble` — the read of
+        Mapled as it is now failed, and the answer is what the cached copy
+        says; `unmarked` — the acknowledgement names no cache. */
+    async function siteRelease() {
+        const url = `${base}/v1/delivery/release?webhook=1`;
+        const cached = await readPointer(url, { headers, next });
+        const live = cached.live;
+        if (live.release === null || !cached.acknowledged)
+            return { answer: NONE };
+        const mark = await cacheMark();
+        let acknowledged = cached.acknowledged;
+        let trouble;
+        // the copy may have been made between the site's answer and Mapled's record of it
+        if ((acknowledged.release ?? 0) < live.release) {
+            if (settled?.copy === cached.copy && settled.mark === mark)
+                return { answer: settled.answer };
+            try {
+                const now = await readPointer(url, { headers, cache: "no-store" });
+                // as Mapled has it now: a webhook removed or moved since the copy was made has acknowledged nothing
+                acknowledged = now.acknowledged ?? UNACKNOWLEDGED;
+                // answered for this copy's release — by this cache or another, asking again changes nothing
+                if ((acknowledged.release ?? 0) >= live.release)
+                    settled = { copy: cached.copy, mark, answer: follow(acknowledged, live, mark) };
+            }
+            catch (err) {
+                trouble = err ?? new Error("request failed");
+            }
+        }
+        return { answer: follow(acknowledged, live, mark), trouble, unmarked: acknowledged.release !== null && acknowledged.cache === null };
+    }
     async function load() {
+        let trouble;
+        let unmarked;
         try {
-            const init = {
-                headers: { "x-mapled-key": options.key },
-                ...(next ? { next } : {}),
-            };
-            const res = await fetch(`${base}/v1/delivery/release`, init);
-            if (!res.ok)
-                throw new Error(`Mapled answered ${res.status}`);
-            const body = (await res.json());
-            const release = body?.release ?? null;
-            const publishedAt = body?.publishedAt ?? null;
-            const published = Number.isInteger(release) && release >= 1 && typeof publishedAt === "string";
-            if (!published && release !== null)
-                throw new Error("Mapled's answer wasn't a release");
-            held = published ? { release, publishedAt } : { release: null, publishedAt: null };
-            complained = false;
+            if (next)
+                ({ answer: held, trouble, unmarked } = await siteRelease());
+            else
+                held = (await readPointer(`${base}/v1/delivery/release`, { headers })).live;
         }
         catch (err) {
             // the last answer stays good while Mapled can't be reached
-            if (!complained) {
-                complained = true;
-                console.error(`[mapled] The release route can't read the live release: ${err instanceof Error ? err.message : "request failed"}.`);
-            }
+            trouble = err ?? new Error("request failed");
         }
         finally {
             askedAt = Date.now();
         }
+        if (trouble === undefined)
+            complained = false;
+        else if (!complained) {
+            // one line for the developer, not one per poll
+            complained = true;
+            console.error(`[mapled] The release route can't read the live release: ${trouble instanceof Error ? trouble.message : "request failed"}.`);
+        }
+        if (unmarked && !unmarkedSaid) {
+            unmarkedSaid = true;
+            console.warn("[mapled] The release route names no release until your site answers a publish webhook with its cache's mark: createRevalidateHandler does (0.11.0 and later); a webhook handler of your own answers with `x-mapled-cache: await cacheMark()` (README, «Live updates»).");
+        }
     }
     /** `asked` — the tab's If-None-Match */
     return async function answer(asked) {
@@ -168,10 +301,12 @@ function releaseAnswers(options, next) {
 /** GET handler for the release route of an App Router site (mount at
     app/api/mapled/release/route.ts): the release this site serves right
     now, for `<MapledLive />` from "@mapled/next/live" to ask about. The
-    pointer is read under the "mapled" tag like the content is, so it
-    moves when the publish webhook refreshes the cache and not before — a
-    tab that refreshes on it renders the new release, never the old one
-    again. */
+    pointer is read under the "mapled" tag like the content is, and never
+    past the release this deployment's cache has acknowledged through the
+    publish webhook — however the cache entry was filled, the route moves
+    when the webhook has refreshed this cache and not before, so a tab
+    that refreshes on it renders the new release, never the old one
+    again. A deployment the webhook doesn't reach names none. */
 export function createReleaseHandler(options) {
     const answer = releaseAnswers(options, { revalidate: options.revalidate ?? 3600, tags: ["mapled"] });
     return async function GET(req) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/next",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Read published Mapled content in a Next.js site \u2014 delivery client, ISR tags, and a revalidation webhook handler.",
   "license": "MIT",
   "homepage": "https://mapled.io",