@decocms/tanstack 8.6.0 → 8.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/README.md +4 -4
  2. package/dist/draft.d.ts +21 -5
  3. package/dist/draft.d.ts.map +1 -1
  4. package/dist/draft.js +23 -7
  5. package/dist/draft.js.map +1 -1
  6. package/dist/react/DecoDocument.d.ts.map +1 -1
  7. package/dist/react/DecoDocument.js +4 -4
  8. package/dist/react/DecoDocument.js.map +1 -1
  9. package/dist/react/pageValues.d.ts +3 -0
  10. package/dist/react/pageValues.d.ts.map +1 -1
  11. package/dist/react/pageValues.js +13 -4
  12. package/dist/react/pageValues.js.map +1 -1
  13. package/dist/scope/server.d.ts +5 -0
  14. package/dist/scope/server.d.ts.map +1 -1
  15. package/dist/scope/server.js.map +1 -1
  16. package/dist/server/index.d.ts +5 -3
  17. package/dist/server/index.d.ts.map +1 -1
  18. package/dist/server/index.js +6 -2
  19. package/dist/server/index.js.map +1 -1
  20. package/dist/worker/cache.d.ts +4 -2
  21. package/dist/worker/cache.d.ts.map +1 -1
  22. package/dist/worker/cache.js +6 -2
  23. package/dist/worker/cache.js.map +1 -1
  24. package/dist/worker/drafts.d.ts +32 -3
  25. package/dist/worker/drafts.d.ts.map +1 -1
  26. package/dist/worker/drafts.js +59 -4
  27. package/dist/worker/drafts.js.map +1 -1
  28. package/dist/worker/index.d.ts +8 -3
  29. package/dist/worker/index.d.ts.map +1 -1
  30. package/dist/worker/index.js +79 -35
  31. package/dist/worker/index.js.map +1 -1
  32. package/package.json +2 -2
  33. package/src/draft.ts +27 -7
  34. package/src/react/DecoDocument.tsx +20 -4
  35. package/src/react/pageValues.ts +12 -4
  36. package/src/scope/server.ts +5 -0
  37. package/src/server/index.ts +11 -5
  38. package/src/worker/cache.ts +6 -2
  39. package/src/worker/drafts.ts +81 -6
  40. package/src/worker/index.ts +93 -41
@@ -15,10 +15,12 @@
15
15
  * Both pass the same host check: a visitor on the live site never picks a
16
16
  * version.
17
17
  */
18
- import { type CMS, parseVersion, type RequestVersion } from "@decocms/blocks";
18
+ import { type CMS, parseDraftPointer, parseVersion, type RequestVersion } from "@decocms/blocks";
19
19
  import { DRAFT_COOKIE, DRAFT_PARAM } from "../draft.ts";
20
20
 
21
21
  const DRAFT_OFF = "off";
22
+ /** A draft pointer's version that names no draft: the release, nothing fetched. */
23
+ const LOCAL_VERSION = "local";
22
24
 
23
25
  function draftParam(url: URL): string | null {
24
26
  return url.searchParams.get(DRAFT_PARAM);
@@ -51,6 +53,25 @@ export function readDraftVersion(request: Request): RequestVersion | null {
51
53
  return parseVersion(readCookie(request.headers.get("cookie"), DRAFT_COOKIE));
52
54
  }
53
55
 
56
+ /**
57
+ * Whether a request carries a draft signal at all: `?__draft=` with any value
58
+ * (`off` and a value that doesn't parse too) or the draft cookie. Such a
59
+ * request is a preview: it never goes through a page cache and its response
60
+ * is never cached (`draftResponseHeaders`), whatever the host check decides.
61
+ */
62
+ export function hasDraftSignal(request: Pick<Request, "url" | "headers">): boolean {
63
+ return (
64
+ draftParam(new URL(request.url)) !== null ||
65
+ readCookie(request.headers.get("cookie"), DRAFT_COOKIE) !== null
66
+ );
67
+ }
68
+
69
+ /** Whether a version names a saved draft (a pointer, not a release's SHA and not `local`). */
70
+ function namesDraft(version: string): boolean {
71
+ const parsed = parseDraftPointer(version);
72
+ return parsed !== null && parsed.version !== LOCAL_VERSION;
73
+ }
74
+
54
75
  function serializeCookie(value: string, extra: string[]): string {
55
76
  // The same cookie `cms.draftCookie` writes (a test holds the two together).
56
77
  return [
@@ -72,26 +93,80 @@ export interface DraftDecision {
72
93
  * `cms.client()`'s options; `null` for the current release.
73
94
  */
74
95
  version: RequestVersion | null;
75
- /** The `Set-Cookie` the response carries: storing a link's version, or ending a preview. */
96
+ /**
97
+ * The `Set-Cookie` the response carries: storing a link's version (the
98
+ * worker sends it only with a response below 500), or ending a preview.
99
+ */
76
100
  setCookie: string | null;
101
+ /**
102
+ * The link named a draft that can't be read (deleted, or its host
103
+ * failing): the request renders the release, the cookie is expired when
104
+ * the draft is gone (a failure that may pass leaves it), and the page says so calmly (`DraftBadge`'s `unavailable`), never a 500.
105
+ */
106
+ unavailable?: true;
107
+ /**
108
+ * The release check made for this draft request (`cms.checkRelease()`):
109
+ * the host check, the read below and the page's draft reads all wait for
110
+ * it, so the request reads `latest.json` once.
111
+ */
112
+ releaseCheck?: string;
77
113
  }
78
114
 
79
- /** The version a request renders, and the cookie its response sets. */
115
+ /**
116
+ * The version a request renders, and the cookie its response sets. A draft
117
+ * request first checks for the latest release, once (`cms.checkRelease()`),
118
+ * and the host check and every draft read share that check. A draft
119
+ * pointer is read once before the page renders (`forDraft(...).revision()`,
120
+ * the same read the page makes, shared while in flight): a draft that can't
121
+ * be read gives the release and `unavailable`, never an error page.
122
+ */
80
123
  export async function decideDraft(
81
- cms: Pick<CMS, "readVersion">,
124
+ cms: Pick<CMS, "readVersion" | "forDraft" | "checkRelease">,
82
125
  request: Request,
83
126
  ): Promise<DraftDecision> {
84
127
  const url = new URL(request.url);
85
128
  const param = draftParam(url);
86
129
  // Ending a preview is allowed on any host, so a cookie set earlier always goes.
87
- if (param === DRAFT_OFF) return { version: null, setCookie: serializeCookie("", ["Max-Age=0"]) };
130
+ if (param === DRAFT_OFF) return { version: null, setCookie: expiredCookie() };
88
131
  const version = readDraftVersion(request);
89
132
  if (version === null) return { version: null, setCookie: null };
90
- if ((await cms.readVersion(request)) === null) return { version: null, setCookie: null };
133
+ // One release check per draft request, shared below and by the page.
134
+ const releaseCheck = namesDraft(version.version) ? await cms.checkRelease() : undefined;
135
+ if ((await cms.readVersion(request, { releaseCheck })) === null) {
136
+ return { version: null, setCookie: null };
137
+ }
138
+ if (releaseCheck !== undefined) {
139
+ try {
140
+ await cms.forDraft(version.version, { releaseCheck }).revision();
141
+ } catch (error) {
142
+ // Gone (deleted): the preview ends. Any other failure (the drafts' host
143
+ // down, a timeout) leaves the cookie alone, so the next request tries again.
144
+ const setCookie = isDraftGone(error) ? expiredCookie() : null;
145
+ return { version: null, setCookie, unavailable: true };
146
+ }
147
+ }
91
148
  // The link's own value goes in the cookie, its preview parameters with it.
92
149
  const fromLink = param !== null && parseVersion(param) !== null;
93
150
  return {
94
151
  version,
95
152
  setCookie: fromLink ? serializeCookie(encodeURIComponent(param), []) : null,
153
+ ...(releaseCheck === undefined ? {} : { releaseCheck }),
96
154
  };
97
155
  }
156
+
157
+ /**
158
+ * Whether a draft read failed because the drafts' host no longer has the
159
+ * draft (`404`/`410`), as opposed to a failure that may pass (a `5xx`, a
160
+ * timeout, a network error). Reads the error and its causes.
161
+ */
162
+ function isDraftGone(error: unknown): boolean {
163
+ for (let e = error, depth = 0; e instanceof Error && depth < 5; e = e.cause, depth++) {
164
+ if (/draft changes: HTTP (404|410)\b/.test(e.message)) return true;
165
+ }
166
+ return false;
167
+ }
168
+
169
+ /** The `Set-Cookie` that ends a preview. */
170
+ function expiredCookie(): string {
171
+ return serializeCookie("", ["Max-Age=0"]);
172
+ }
@@ -8,14 +8,19 @@
8
8
  * - Versions: the host allowlist (`./drafts.ts`) for a Studio link's version
9
9
  * (a draft, or a published release by its commit SHA, with the preview's
10
10
  * moment and switched tests and campaigns), the draft cookie, the
11
- * `x-deco-version` request header the page reads, and on the response
12
- * `no-store`, `Vary: Cookie` and `noindex`.
11
+ * `x-deco-version` request header the page reads. A preview (any request
12
+ * with `?__draft=`, `off` included, or the draft cookie) never goes through
13
+ * `pageCache` and answers `Cache-Control: max-age=0, no-cache,
14
+ * must-revalidate`, `Vary: Cookie` and `noindex`. A link's cookie is set
15
+ * only with a response below 500; a link to a draft that can't be read
16
+ * anymore renders the release, expires the cookie and tells the page
17
+ * (`draftUnavailable`), never a 500.
13
18
  * - The CMS redirects, before any route.
14
19
  * - No page cache: caching is the site's (`pageCache`, the README's
15
20
  * worker-entry recipe), with the helpers it needs exported here
16
21
  * (`assignmentsKey`, `cacheVersion`, `isCacheable`, …).
17
22
  * The worker calls `pageCache` only for a request `isCacheable` accepts,
18
- * never for a preview, and adds the visitor's cookie after it, so a stored
23
+ * never for a preview (any draft signal), and adds the visitor's cookie after it, so a stored
19
24
  * copy never carries one. A page request with `Authorization` is never
20
25
  * handed to it and answers `private, no-cache, no-store`. A response with no
21
26
  * `CDN-Cache-Control` tells the CDN `no-store`, at one exit.
@@ -44,13 +49,13 @@ import { readVisitor, serializeVisitor, type Visitor } from "@decocms/blocks/exp
44
49
  import { recordServerRequest } from "@decocms/blocks/metrics";
45
50
  import { runInScope } from "@decocms/tanstack/scope";
46
51
  import { ASSIGNMENTS_HEADER, serializeAssignments } from "../assignments.ts";
47
- import { draftResponseHeaders, VERSION_HEADER } from "../draft.ts";
52
+ import { draftResponseHeaders, RELEASE_CHECK_HEADER, VERSION_HEADER } from "../draft.ts";
48
53
  import { PAGE_STATUS_HEADER } from "../shared.ts";
49
54
  import { VISITOR_HEADER } from "../visitor.ts";
50
55
  import { type RequestAssignments, readAssignments } from "./assignments.ts";
51
56
  import { isCacheable } from "./cache.ts";
52
57
  import { dedupeSetCookies } from "./cookies.ts";
53
- import { type DraftDecision, decideDraft } from "./drafts.ts";
58
+ import { type DraftDecision, decideDraft, hasDraftSignal } from "./drafts.ts";
54
59
  import { type CspOptions, htmlSecurityHeaders } from "./security.ts";
55
60
  import { type Device, detectDevice } from "./segment.ts";
56
61
  import { isServerFnPath } from "./serverFn.ts";
@@ -181,7 +186,8 @@ function fixedRoute(pathname: string): string | null {
181
186
  const REDIRECT_ROUTE = "redirect";
182
187
 
183
188
  /**
184
- * The cache label of `http.server.request.duration`: `DRAFT` for a preview,
189
+ * The cache label of `http.server.request.duration`: `DRAFT` for a preview
190
+ * (any draft signal),
185
191
  * otherwise what the site's `pageCache` said in `X-Cache`. A response that
186
192
  * never went through it (a redirect, the site's `routes`, an asset, a page
187
193
  * without a `pageCache`) is `BYPASS` whatever `X-Cache` an upstream put on it.
@@ -234,12 +240,15 @@ export function createDecoWorker<Env = unknown>(options: DecoWorkerOptions<Env>)
234
240
  // The release's redirects, read once per revision (a draft's are read each time).
235
241
  let releaseRedirects: { revision: string; list: Promise<Redirect[]> } | undefined;
236
242
 
237
- async function redirectsFor(pointer: string | null): Promise<Redirect[]> {
243
+ async function redirectsFor(
244
+ pointer: string | null,
245
+ releaseCheck: string | undefined,
246
+ ): Promise<Redirect[]> {
238
247
  const read = async (client: ReturnType<CMS["forRelease"]>) => {
239
248
  const [list] = await client.list<Redirect>("redirect");
240
249
  return list ?? [];
241
250
  };
242
- if (pointer) return read(cms.client({ version: pointer }));
251
+ if (pointer) return read(cms.client({ version: pointer, releaseCheck }));
243
252
  const client = cms.client();
244
253
  const revision = await client.revision();
245
254
  if (releaseRedirects?.revision !== revision) {
@@ -313,9 +322,13 @@ export function createDecoWorker<Env = unknown>(options: DecoWorkerOptions<Env>)
313
322
  }
314
323
  }
315
324
 
316
- async function findRedirect(url: URL, pointer: string | null): Promise<Response | null> {
325
+ async function findRedirect(
326
+ url: URL,
327
+ pointer: string | null,
328
+ releaseCheck: string | undefined,
329
+ ): Promise<Response | null> {
317
330
  try {
318
- const redirects = await redirectsFor(pointer);
331
+ const redirects = await redirectsFor(pointer, releaseCheck);
319
332
  if (!redirects.length) return null;
320
333
  const match = matchRoute(url, { routes: [], redirects });
321
334
  if (match.kind !== "redirect") return null;
@@ -329,6 +342,8 @@ export function createDecoWorker<Env = unknown>(options: DecoWorkerOptions<Env>)
329
342
  response: Response;
330
343
  /** Answered by the site's `pageCache`: its `X-Cache` labels the metric. */
331
344
  cached?: true;
345
+ /** A fingerprinted or static asset: its own `Cache-Control`, a preview's or not. */
346
+ asset?: true;
332
347
  /** Answered by the site's `routes`: not this app's page, so no `preload` hints. */
333
348
  routed?: true;
334
349
  /** A CMS redirect. */
@@ -359,7 +374,13 @@ export function createDecoWorker<Env = unknown>(options: DecoWorkerOptions<Env>)
359
374
  return { request, visitor: null };
360
375
  }
361
376
  const { visitor, cookie } = readVisitor(request);
362
- const assignments = await readAssignments(cms, { visitor, ...draft.version });
377
+ // A draft's read shares the request's release check (`decideDraft`), never one of its own.
378
+ const releaseCheck = draft.version ? draft.releaseCheck : undefined;
379
+ const assignments = await readAssignments(cms, {
380
+ visitor,
381
+ ...draft.version,
382
+ ...(releaseCheck ? { releaseCheck } : {}),
383
+ });
363
384
  const headers = new Headers(request.headers);
364
385
  headers.set(VISITOR_HEADER, serializeVisitor(visitor));
365
386
  headers.set(ASSIGNMENTS_HEADER, serializeAssignments(assignments));
@@ -375,6 +396,7 @@ export function createDecoWorker<Env = unknown>(options: DecoWorkerOptions<Env>)
375
396
  env: Env,
376
397
  ctx: ExecutionContextLike,
377
398
  decision: DraftDecision,
399
+ preview: boolean,
378
400
  ): Promise<Served> {
379
401
  const draft = decision.version?.version ?? null;
380
402
  const url = new URL(request.url);
@@ -409,7 +431,7 @@ export function createDecoWorker<Env = unknown>(options: DecoWorkerOptions<Env>)
409
431
  !isServerFnPath(url.pathname) &&
410
432
  !BYPASS_PATHS.some((p) => url.pathname.startsWith(p))
411
433
  ) {
412
- const redirect = await findRedirect(url, draft);
434
+ const redirect = await findRedirect(url, draft, decision.releaseCheck);
413
435
  if (redirect) return { response: redirect, redirect: true };
414
436
  }
415
437
 
@@ -420,54 +442,62 @@ export function createDecoWorker<Env = unknown>(options: DecoWorkerOptions<Env>)
420
442
 
421
443
  if (asset) {
422
444
  const origin = await serverEntry.fetch(request, env, ctx);
423
- if (origin.status !== 200) return { response: origin };
424
- if (isHtml(origin)) return { response: new Response("Not Found", { status: 404 }) };
445
+ if (origin.status !== 200) return { response: origin, asset: true };
446
+ if (isHtml(origin)) {
447
+ return { response: new Response("Not Found", { status: 404 }), asset: true };
448
+ }
425
449
  const resp = mutable(origin);
426
450
  resp.headers.set("Cache-Control", "public, max-age=31536000, immutable");
427
451
  resp.headers.set("Vary", "Accept-Encoding");
428
- return { response: resp };
452
+ return { response: resp, asset: true };
429
453
  }
430
454
 
431
455
  const visited = await withDecisions(request, decision);
432
- const served = await page(
433
- visited.request,
434
- env,
435
- ctx,
456
+ const served = await page(visited.request, env, ctx, {
436
457
  draft,
458
+ preview,
459
+ unavailable: decision.unavailable === true,
437
460
  url,
438
- visited.visitor,
439
- visited.assignments,
440
- );
461
+ visitor: visited.visitor,
462
+ assignments: visited.assignments,
463
+ });
441
464
  return visited.visitorCookie === undefined
442
465
  ? served
443
466
  : { ...served, visitorCookie: visited.visitorCookie };
444
467
  }
445
468
 
446
- /** A page or server-function request: the site's `pageCache` when it may cache it, else the app. */
469
+ /**
470
+ * A page or server-function request: the site's `pageCache` when it may
471
+ * cache it, else the app. A preview (any draft signal) always renders: its
472
+ * headers are set at the exit (`serve`).
473
+ */
447
474
  async function page(
448
475
  request: Request,
449
476
  env: Env,
450
477
  ctx: ExecutionContextLike,
451
- draft: string | null,
452
- url: URL,
453
- visitor: Visitor | null,
454
- assignments: RequestAssignments | undefined,
478
+ inputs: {
479
+ draft: string | null;
480
+ preview: boolean;
481
+ unavailable: boolean;
482
+ url: URL;
483
+ visitor: Visitor | null;
484
+ assignments: RequestAssignments | undefined;
485
+ },
455
486
  ): Promise<Served> {
487
+ const { draft, preview, unavailable, url, visitor, assignments } = inputs;
456
488
  const render = async (scope?: { csegToken?: string }): Promise<Response> =>
457
489
  withPageStatus(
458
- await runInScope({ csegToken: scope?.csegToken, draft: draft ?? undefined }, () =>
459
- serverEntry.fetch(request, env, ctx),
490
+ await runInScope(
491
+ {
492
+ csegToken: scope?.csegToken,
493
+ draft: draft ?? undefined,
494
+ ...(unavailable ? { draftUnavailable: true } : {}),
495
+ },
496
+ () => serverEntry.fetch(request, env, ctx),
460
497
  ),
461
498
  );
462
499
 
463
- if (draft !== null) {
464
- const out = mutable(await render());
465
- for (const [k, v] of Object.entries(draftResponseHeaders(draft))) {
466
- if (k.toLowerCase() !== "vary") out.headers.set(k, v);
467
- else appendVary(out.headers, v);
468
- }
469
- return { response: out };
470
- }
500
+ if (draft !== null || preview) return { response: await render() };
471
501
  // A signed request's page is that caller's: no shared cache may keep it,
472
502
  // whatever the app said (RFC 9111 lets one store a `public` answer to it).
473
503
  if (request.headers.has("authorization")) {
@@ -501,6 +531,8 @@ export function createDecoWorker<Env = unknown>(options: DecoWorkerOptions<Env>)
501
531
  env: Env,
502
532
  ctx: ExecutionContextLike,
503
533
  ): Promise<{ response: Response; served: Served; draft: boolean }> {
534
+ // Any draft signal makes the request a preview, whatever the decision.
535
+ const preview = hasDraftSignal(incoming);
504
536
  let decision: DraftDecision = { version: null, setCookie: null };
505
537
  try {
506
538
  decision = await decideDraft(cms, incoming);
@@ -510,16 +542,20 @@ export function createDecoWorker<Env = unknown>(options: DecoWorkerOptions<Env>)
510
542
  // The page reads the version, the visitor and the assignments from these
511
543
  // headers; a copy from outside never counts.
512
544
  let request = incoming;
513
- const own = [VERSION_HEADER, VISITOR_HEADER, ASSIGNMENTS_HEADER];
545
+ const own = [VERSION_HEADER, VISITOR_HEADER, ASSIGNMENTS_HEADER, RELEASE_CHECK_HEADER];
514
546
  if (own.some((name) => incoming.headers.has(name)) || decision.version !== null) {
515
547
  const headers = new Headers(incoming.headers);
516
548
  for (const name of own) headers.delete(name);
517
549
  if (decision.version !== null) headers.set(VERSION_HEADER, decision.version.version);
550
+ // The page's draft reads wait for the request's release check, never one of their own.
551
+ if (decision.version !== null && decision.releaseCheck !== undefined) {
552
+ headers.set(RELEASE_CHECK_HEADER, decision.releaseCheck);
553
+ }
518
554
  request = new Request(incoming, { headers });
519
555
  }
520
556
 
521
- const served = await handle(request, env, ctx, decision);
522
- const draft = decision.version !== null;
557
+ const served = await handle(request, env, ctx, decision, preview);
558
+ const draft = decision.version !== null || preview;
523
559
  let response = served.response;
524
560
  // A WebSocket upgrade passes through untouched.
525
561
  if (response.status === 101) return { response, served, draft };
@@ -531,7 +567,23 @@ export function createDecoWorker<Env = unknown>(options: DecoWorkerOptions<Env>)
531
567
  if (!response.headers.has("CDN-Cache-Control")) {
532
568
  response.headers.set("CDN-Cache-Control", "no-store");
533
569
  }
534
- if (decision.setCookie) response.headers.append("Set-Cookie", decision.setCookie);
570
+ // A preview's response is never answered from a cache: the exact header,
571
+ // whatever the app or a route said. A fingerprinted asset stays immutable.
572
+ if (preview && !served.asset) {
573
+ for (const [k, v] of Object.entries(draftResponseHeaders(true))) {
574
+ if (k.toLowerCase() !== "vary") response.headers.set(k, v);
575
+ else appendVary(response.headers, v);
576
+ }
577
+ // Nor kept by the CDN, whatever a route said: with the draft in a cookie
578
+ // a preview shares its URL with the published page.
579
+ response.headers.set("CDN-Cache-Control", "no-store");
580
+ }
581
+ // A link's cookie only with a page that rendered: a failed render never
582
+ // pins the preview to it. The cookie that ends a preview always goes.
583
+ const ending = decision.version === null;
584
+ if (decision.setCookie && (ending || response.status < 500)) {
585
+ response.headers.append("Set-Cookie", decision.setCookie);
586
+ }
535
587
  if (served.visitorCookie) response.headers.append("Set-Cookie", served.visitorCookie);
536
588
  dedupeSetCookies(response);
537
589
  if (isHtml(response)) {