@decocms/tanstack 7.81.1 → 7.81.2

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@decocms/tanstack",
3
- "version": "7.81.1",
3
+ "version": "7.81.2",
4
4
  "type": "module",
5
5
  "description": "Deco framework binding for TanStack Start + Cloudflare Workers",
6
6
  "repository": {
@@ -27,9 +27,9 @@
27
27
  "lint:unused": "knip"
28
28
  },
29
29
  "dependencies": {
30
- "@decocms/blocks": "7.81.1",
31
- "@decocms/blocks-admin": "7.81.1",
32
- "@decocms/blocks-cli": "7.81.1",
30
+ "@decocms/blocks": "7.81.2",
31
+ "@decocms/blocks-admin": "7.81.2",
32
+ "@decocms/blocks-cli": "7.81.2",
33
33
  "@deco-cx/warp-node": "^0.3.16",
34
34
  "fast-json-patch": "^3.1.0",
35
35
  "ws": "^8.18.0"
@@ -0,0 +1,218 @@
1
+ // @vitest-environment node
2
+
3
+ import { setBlocks } from "@decocms/blocks/cms";
4
+ import { clearLoaderCache } from "@decocms/blocks/sdk/cachedLoader";
5
+ import { type CacheKVNamespace, createKVCacheStorage } from "@decocms/blocks/sdk/cacheStorage";
6
+ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
7
+ import { createDecoWorkerEntry } from "./workerEntry";
8
+
9
+ // A STALE-HIT is meant to answer from the stored copy right away. Measured on a
10
+ // production storefront (QA-166, Oficina Reserva, PLP `/roupas/sueteres`): 8
11
+ // visitors arriving together on an entry past `fresh` all got STALE-HIT and all
12
+ // took 1.12 s, against 0.2-0.5 s for a HIT — the background re-render started
13
+ // before the stale body went out, and every STALE-HIT started one.
14
+
15
+ function makeKV(): CacheKVNamespace {
16
+ const values = new Map<string, string>();
17
+ return {
18
+ get: async (key) => values.get(key) ?? null,
19
+ put: async (key, value) => {
20
+ values.set(key, value);
21
+ },
22
+ delete: async (key) => {
23
+ values.delete(key);
24
+ },
25
+ };
26
+ }
27
+
28
+ const jobs: Promise<unknown>[] = [];
29
+ const ctx = { waitUntil: (w: Promise<unknown>) => jobs.push(w), passThroughOnException() {} };
30
+ async function flush() {
31
+ while (jobs.length) await Promise.all(jobs.splice(0));
32
+ }
33
+
34
+ const options = {
35
+ observability: false as const,
36
+ outboundUserAgent: false as const,
37
+ geoCacheKey: "off" as const,
38
+ buildSegment: () => ({ device: "desktop" as const }),
39
+ cacheStorage: (bindings: Record<string, unknown>) =>
40
+ createKVCacheStorage(bindings.CACHE as CacheKVNamespace),
41
+ };
42
+ const env = () => ({ CACHE: makeKV(), BUILD_HASH: "build-A" });
43
+
44
+ const htmlOrigin = () => ({
45
+ fetch: vi.fn(
46
+ async (req: Request) =>
47
+ new Response(`<html>rendered ${req.url}</html>`, {
48
+ headers: { "content-type": "text/html" },
49
+ }),
50
+ ),
51
+ });
52
+ const sfnOrigin = () => ({
53
+ fetch: vi.fn(
54
+ async (req: Request) =>
55
+ new Response(`section for ${await req.text()}`, {
56
+ headers: { "content-type": "application/json", "X-Deco-Cacheable": "true" },
57
+ }),
58
+ ),
59
+ });
60
+
61
+ const page = (path: string) =>
62
+ new Request(`https://shop.test${path}`, { headers: { accept: "text/html" } });
63
+ const post = (pageUrl: string) =>
64
+ new Request("https://shop.test/_serverFn/abc123", {
65
+ method: "POST",
66
+ headers: { "content-type": "application/json" },
67
+ body: JSON.stringify({ data: { component: "Shelf", pageUrl } }),
68
+ });
69
+
70
+ /** `listing` is fresh=120s, swr=900s: +200s lands inside the SWR window. */
71
+ let clockOffsetMs = 0;
72
+ const INSIDE_SWR_MS = 200_000;
73
+
74
+ beforeEach(() => {
75
+ clearLoaderCache();
76
+ setBlocks({});
77
+ clockOffsetMs = 0;
78
+ const realNow = Date.now.bind(Date);
79
+ vi.spyOn(Date, "now").mockImplementation(() => realNow() + clockOffsetMs);
80
+ });
81
+
82
+ afterEach(() => vi.restoreAllMocks());
83
+
84
+ describe("HTML STALE-HIT", () => {
85
+ it("renders once for concurrent stale visitors, after the stale body went out", async () => {
86
+ const origin = htmlOrigin();
87
+ const bindings = env();
88
+ const worker = createDecoWorkerEntry(origin, options);
89
+
90
+ await worker.fetch(page("/produtos"), bindings, ctx);
91
+ await flush();
92
+ expect(origin.fetch).toHaveBeenCalledTimes(1);
93
+
94
+ clockOffsetMs = INSIDE_SWR_MS;
95
+ const stale = await Promise.all(
96
+ Array.from({ length: 5 }, () => worker.fetch(page("/produtos"), bindings, ctx)),
97
+ );
98
+ for (const res of stale) expect(res.headers.get("X-Cache")).toBe("STALE-HIT");
99
+ // Nothing re-rendered while the stale copies were still on their way out.
100
+ expect(origin.fetch).toHaveBeenCalledTimes(1);
101
+
102
+ for (const res of stale) await res.text();
103
+ await flush();
104
+ // One refresh for all five, not one each.
105
+ expect(origin.fetch).toHaveBeenCalledTimes(2);
106
+
107
+ clockOffsetMs = INSIDE_SWR_MS + 1_000;
108
+ const next = await worker.fetch(page("/produtos"), bindings, ctx);
109
+ expect(next.headers.get("X-Cache")).toBe("HIT");
110
+ });
111
+
112
+ it("revalidates again once the previous refresh settled", async () => {
113
+ const origin = htmlOrigin();
114
+ const bindings = env();
115
+ const worker = createDecoWorkerEntry(origin, options);
116
+
117
+ await worker.fetch(page("/produtos"), bindings, ctx);
118
+ await flush();
119
+
120
+ clockOffsetMs = INSIDE_SWR_MS;
121
+ await (await worker.fetch(page("/produtos"), bindings, ctx)).text();
122
+ await flush();
123
+ expect(origin.fetch).toHaveBeenCalledTimes(2);
124
+
125
+ // The refreshed entry goes stale in turn and is refreshed again.
126
+ clockOffsetMs = INSIDE_SWR_MS * 2;
127
+ const stale = await worker.fetch(page("/produtos"), bindings, ctx);
128
+ expect(stale.headers.get("X-Cache")).toBe("STALE-HIT");
129
+ await stale.text();
130
+ await flush();
131
+ expect(origin.fetch).toHaveBeenCalledTimes(3);
132
+ });
133
+
134
+ it("still refreshes when the client goes away mid-body", async () => {
135
+ const origin = htmlOrigin();
136
+ const bindings = env();
137
+ const worker = createDecoWorkerEntry(origin, options);
138
+
139
+ await worker.fetch(page("/produtos"), bindings, ctx);
140
+ await flush();
141
+
142
+ clockOffsetMs = INSIDE_SWR_MS;
143
+ const stale = await worker.fetch(page("/produtos"), bindings, ctx);
144
+ await stale.body?.cancel();
145
+ await flush();
146
+ expect(origin.fetch).toHaveBeenCalledTimes(2);
147
+ });
148
+ });
149
+
150
+ describe("POST server fn STALE-HIT (client-side navigation)", () => {
151
+ it("renders once for concurrent stale visitors, after the stale body went out", async () => {
152
+ const origin = sfnOrigin();
153
+ const bindings = env();
154
+ const worker = createDecoWorkerEntry(origin, options);
155
+
156
+ await worker.fetch(post("https://shop.test/produtos"), bindings, ctx);
157
+ await flush();
158
+ expect(origin.fetch).toHaveBeenCalledTimes(1);
159
+
160
+ clockOffsetMs = INSIDE_SWR_MS;
161
+ const stale = await Promise.all(
162
+ Array.from({ length: 5 }, () =>
163
+ worker.fetch(post("https://shop.test/produtos"), bindings, ctx),
164
+ ),
165
+ );
166
+ for (const res of stale) expect(res.headers.get("X-Cache")).toBe("STALE-HIT");
167
+ expect(origin.fetch).toHaveBeenCalledTimes(1);
168
+
169
+ for (const res of stale) await res.text();
170
+ await flush();
171
+ expect(origin.fetch).toHaveBeenCalledTimes(2);
172
+
173
+ clockOffsetMs = INSIDE_SWR_MS + 1_000;
174
+ const next = await worker.fetch(post("https://shop.test/produtos"), bindings, ctx);
175
+ expect(next.headers.get("X-Cache")).toBe("HIT");
176
+ });
177
+ });
178
+
179
+ describe("revalidation claim", () => {
180
+ it("expires a refresh that never settled, so the entry does not stay stale", async () => {
181
+ let hang = false;
182
+ const origin = {
183
+ fetch: vi.fn(async (req: Request) => {
184
+ // A render whose I/O was cancelled under it: never settles.
185
+ if (hang) return new Promise<Response>(() => {});
186
+ return new Response(`<html>rendered ${req.url}</html>`, {
187
+ headers: { "content-type": "text/html" },
188
+ });
189
+ }),
190
+ };
191
+ const bindings = env();
192
+ const worker = createDecoWorkerEntry(origin, options);
193
+
194
+ await worker.fetch(page("/produtos"), bindings, ctx);
195
+ await flush();
196
+
197
+ hang = true;
198
+ clockOffsetMs = INSIDE_SWR_MS;
199
+ await (await worker.fetch(page("/produtos"), bindings, ctx)).text();
200
+ await Promise.resolve();
201
+ expect(origin.fetch).toHaveBeenCalledTimes(2);
202
+ jobs.splice(0); // the hung refresh is never awaited
203
+
204
+ // Inside the claim window: no second render on top of the hung one.
205
+ clockOffsetMs = INSIDE_SWR_MS + 10_000;
206
+ await (await worker.fetch(page("/produtos"), bindings, ctx)).text();
207
+ await Promise.resolve();
208
+ expect(origin.fetch).toHaveBeenCalledTimes(2);
209
+ jobs.splice(0);
210
+
211
+ // Past it: the next stale visitor claims a fresh refresh.
212
+ hang = false;
213
+ clockOffsetMs = INSIDE_SWR_MS + 31_000;
214
+ await (await worker.fetch(page("/produtos"), bindings, ctx)).text();
215
+ await flush();
216
+ expect(origin.fetch).toHaveBeenCalledTimes(3);
217
+ });
218
+ });
@@ -115,6 +115,9 @@ describe("tracking params never poison the edge cache", () => {
115
115
  clockOffsetMs = INSIDE_SWR_MS;
116
116
  const stale = await worker.fetch(page("/produtos?gclid=POISON42"), bindings, ctx);
117
117
  expect(stale.headers.get("X-Cache")).toBe("STALE-HIT");
118
+ // Revalidation starts once the stale body has been delivered.
119
+ expect(origin.fetch).toHaveBeenCalledTimes(1);
120
+ await stale.text();
118
121
  await flush();
119
122
 
120
123
  // The background render must see the clean URL. Rendering the tracked one
@@ -151,6 +154,8 @@ describe("tracking params never poison the edge cache", () => {
151
154
  // cleaning the URL alone would render (and store) the tracked page.
152
155
  const stale = await worker.fetch(sfn("/produtos?gclid=POISON42"), bindings, ctx);
153
156
  expect(stale.headers.get("X-Cache")).toBe("STALE-HIT");
157
+ // Revalidation starts once the stale body has been delivered.
158
+ await stale.text();
154
159
  await flush();
155
160
 
156
161
  clockOffsetMs = INSIDE_SWR_MS + 1_000;
@@ -246,6 +251,8 @@ describe("POST server fn: tracked pageUrl converges on one key and is never stor
246
251
  ctx,
247
252
  );
248
253
  expect(stale.headers.get("X-Cache")).toBe("STALE-HIT");
254
+ // Revalidation starts once the stale body has been delivered.
255
+ await stale.text();
249
256
  await flush();
250
257
 
251
258
  // Refreshed rather than discarded: a third request HITs without a third
@@ -1186,6 +1186,69 @@ function pageJsonCorsHeaders(
1186
1186
  return {}; // origin not allow-listed → no CORS headers
1187
1187
  }
1188
1188
 
1189
+ // ---------------------------------------------------------------------------
1190
+ // Stale-while-revalidate: one background render per entry, after the stale body
1191
+ // ---------------------------------------------------------------------------
1192
+
1193
+ /**
1194
+ * How long a claimed revalidation blocks the next one for the same entry. A
1195
+ * render that neither settles nor fails (its I/O cancelled under it) must not
1196
+ * pin the entry stale for the rest of the SWR window.
1197
+ */
1198
+ const REVALIDATION_CLAIM_MS = 30_000;
1199
+
1200
+ /**
1201
+ * Claims the background revalidation of a cache entry in this isolate: the
1202
+ * returned function hands back a `release`, or `null` when one is already
1203
+ * running. Every STALE-HIT used to start its own full re-render: a stale page
1204
+ * that several visitors asked for at once was rendered once per visitor, on the
1205
+ * same single-threaded isolate, so each of them waited on all of those renders.
1206
+ * One refresh per entry is what deco's own loader cache does
1207
+ * (`revalidationLocker` + `bgFlights`).
1208
+ */
1209
+ function createRevalidationClaims(
1210
+ claimMs = REVALIDATION_CLAIM_MS,
1211
+ ): (key: string) => (() => void) | null {
1212
+ const claims = new Map<string, number>();
1213
+ return (key) => {
1214
+ const now = Date.now();
1215
+ const since = claims.get(key);
1216
+ if (since !== undefined && now - since < claimMs) return null;
1217
+ claims.set(key, now);
1218
+ return () => {
1219
+ if (claims.get(key) === now) claims.delete(key);
1220
+ };
1221
+ };
1222
+ }
1223
+
1224
+ /**
1225
+ * Runs `start` once `resp`'s body has been fully handed to the client (or the
1226
+ * client went away). The re-render runs on the same isolate: started before the
1227
+ * return, its SSR (hundreds of ms of CPU) interleaves with delivering the stale
1228
+ * response, so the visitor the stale entry was meant to serve fast waits on the
1229
+ * render anyway. Kept alive with `waitUntil`, so `start` may itself call it.
1230
+ */
1231
+ function afterBodySent(
1232
+ resp: Response,
1233
+ start: () => void,
1234
+ waitUntil: (promise: Promise<unknown>) => void,
1235
+ ): Response {
1236
+ if (!resp.body) {
1237
+ start();
1238
+ return resp;
1239
+ }
1240
+ const { readable, writable } = new TransformStream<Uint8Array, Uint8Array>();
1241
+ waitUntil(
1242
+ resp.body
1243
+ .pipeTo(writable)
1244
+ .catch(() => {
1245
+ // Client disconnected — still refresh the entry.
1246
+ })
1247
+ .finally(start),
1248
+ );
1249
+ return new Response(readable, resp);
1250
+ }
1251
+
1189
1252
  /**
1190
1253
  * Creates a Cloudflare Worker fetch handler that wraps a TanStack Start
1191
1254
  * server entry with intelligent edge caching.
@@ -1200,6 +1263,7 @@ export function createDecoWorkerEntry(
1200
1263
  ctx: WorkerExecutionContext,
1201
1264
  ): Promise<Response>;
1202
1265
  } {
1266
+ const claimRevalidation = createRevalidationClaims();
1203
1267
  // `/live/_meta` reads the admin schema from the `ASSETS` binding when the
1204
1268
  // build published it as a static asset (`decoVitePlugin({ metaAsset: true })`).
1205
1269
  // Registered here so no site has to remember a setup call; inert for builds
@@ -2831,46 +2895,55 @@ export function createDecoWorkerEntry(
2831
2895
 
2832
2896
  if (ageSec < sfnEdge.fresh + sfnEdge.swr) {
2833
2897
  recordCacheMetric(true, sfnProfile, "STALE-HIT", "edge");
2834
- // Stale-while-revalidate: serve stale, refresh in background
2835
- ctx.waitUntil(
2836
- (async () => {
2837
- try {
2838
- // Revalidate from the canonical body, for the same reason the
2839
- // HTML path revalidates from the clean URL: the entry is keyed
2840
- // on it, and a render from the tracked body embeds that landing
2841
- // URL. Rendering the tracked body would only be discarded,
2842
- // leaving the entry stale for the rest of the SWR window.
2843
- const bgBody = sfnCarriesTracking
2844
- ? canonicalizeServerFnPayloadForCacheKey(body, [])
2845
- : body;
2846
- const bgReq = new Request(request, { body: bgBody, method: "POST" });
2847
- const bgOrigin = await serverEntry.fetch(bgReq, env, ctx);
2848
- if (
2849
- bgOrigin.status === 200 &&
2850
- bgOrigin.headers.get("X-Deco-Cacheable") === "true" &&
2851
- !bgOrigin.headers.has("set-cookie") &&
2852
- serverFnCache
2853
- ) {
2854
- const ttl = sfnEdge.fresh + Math.max(sfnEdge.swr, sfnEdge.sie);
2855
- const toStore = bgOrigin.clone();
2856
- toStore.headers.set("Cache-Control", `public, max-age=${ttl}`);
2857
- toStore.headers.set("X-Deco-Stored-At", String(Date.now()));
2858
- toStore.headers.delete("CDN-Cache-Control");
2859
- toStore.headers.delete("X-Deco-Cacheable");
2860
- await serverFnCache.put(sfnCacheKey, toStore);
2898
+ // Stale-while-revalidate: serve stale, refresh in background — once
2899
+ // per entry, after the stale body went out (see `afterBodySent`).
2900
+ // Client-side navigation reaches every page through here.
2901
+ const revalidate = (release: () => void) =>
2902
+ ctx.waitUntil(
2903
+ (async () => {
2904
+ try {
2905
+ // Revalidate from the canonical body, for the same reason the
2906
+ // HTML path revalidates from the clean URL: the entry is keyed
2907
+ // on it, and a render from the tracked body embeds that landing
2908
+ // URL. Rendering the tracked body would only be discarded,
2909
+ // leaving the entry stale for the rest of the SWR window.
2910
+ const bgBody = sfnCarriesTracking
2911
+ ? canonicalizeServerFnPayloadForCacheKey(body, [])
2912
+ : body;
2913
+ const bgReq = new Request(request, { body: bgBody, method: "POST" });
2914
+ const bgOrigin = await serverEntry.fetch(bgReq, env, ctx);
2915
+ if (
2916
+ bgOrigin.status === 200 &&
2917
+ bgOrigin.headers.get("X-Deco-Cacheable") === "true" &&
2918
+ !bgOrigin.headers.has("set-cookie") &&
2919
+ serverFnCache
2920
+ ) {
2921
+ const ttl = sfnEdge.fresh + Math.max(sfnEdge.swr, sfnEdge.sie);
2922
+ const toStore = bgOrigin.clone();
2923
+ toStore.headers.set("Cache-Control", `public, max-age=${ttl}`);
2924
+ toStore.headers.set("X-Deco-Stored-At", String(Date.now()));
2925
+ toStore.headers.delete("CDN-Cache-Control");
2926
+ toStore.headers.delete("X-Deco-Cacheable");
2927
+ await serverFnCache.put(sfnCacheKey, toStore);
2928
+ }
2929
+ } catch {
2930
+ /* background revalidation failed */
2861
2931
  }
2862
- } catch {
2863
- /* background revalidation failed */
2864
- }
2865
- })(),
2866
- );
2932
+ })().finally(release),
2933
+ );
2867
2934
  const out = new Response(sfnCached.body, sfnCached);
2868
2935
  const hdrs = cacheHeaders(sfnProfile);
2869
2936
  for (const [k, v] of Object.entries(hdrs)) out.headers.set(k, v);
2870
2937
  out.headers.set("X-Cache", "STALE-HIT");
2871
2938
  out.headers.set("X-Cache-Profile", sfnProfile);
2872
2939
  out.headers.set("X-Cache-Age", String(Math.round(ageSec)));
2873
- return out;
2940
+ const release = claimRevalidation(sfnCacheKey.url);
2941
+ if (!release) return out;
2942
+ return afterBodySent(
2943
+ out,
2944
+ () => revalidate(release),
2945
+ (p) => ctx.waitUntil(p),
2946
+ );
2874
2947
  }
2875
2948
  }
2876
2949
 
@@ -3060,7 +3133,7 @@ export function createDecoWorkerEntry(
3060
3133
  // Helper: store a response in Cache API with the full retention window.
3061
3134
  // Callers own the tracking decision: a response is storable iff it was
3062
3135
  // rendered from the clean URL this `cacheKey` represents.
3063
- function storeInCache(resp: Response) {
3136
+ function storeInCache(resp: Response): Promise<unknown> | undefined {
3064
3137
  if (!cache) return;
3065
3138
  try {
3066
3139
  const storageTtl = edgeConfig.fresh + Math.max(edgeConfig.swr, edgeConfig.sie);
@@ -3068,12 +3141,12 @@ export function createDecoWorkerEntry(
3068
3141
  toStore.headers.set("Cache-Control", `public, max-age=${storageTtl}`);
3069
3142
  toStore.headers.set("X-Deco-Stored-At", String(Date.now()));
3070
3143
  toStore.headers.delete("CDN-Cache-Control");
3071
- ctx.waitUntil(
3072
- withTracing("deco.cache.store", () => cache.put(cacheKey, toStore), {
3073
- "cache.profile": profile,
3074
- "cache.kind": "html",
3075
- }),
3076
- );
3144
+ const stored = withTracing("deco.cache.store", () => cache.put(cacheKey, toStore), {
3145
+ "cache.profile": profile,
3146
+ "cache.kind": "html",
3147
+ });
3148
+ ctx.waitUntil(stored);
3149
+ return stored;
3077
3150
  } catch {
3078
3151
  // Cache API unavailable
3079
3152
  }
@@ -3116,7 +3189,7 @@ export function createDecoWorkerEntry(
3116
3189
  }
3117
3190
 
3118
3191
  // Helper: background revalidation (fetch origin, store result)
3119
- function revalidateInBackground() {
3192
+ function revalidateInBackground(release: () => void) {
3120
3193
  ctx.waitUntil(
3121
3194
  Promise.resolve(serverEntry.fetch(revalidationRequest(), env, ctx))
3122
3195
  .then((origin) => {
@@ -3130,13 +3203,14 @@ export function createDecoWorkerEntry(
3130
3203
  const cleanOrigin = origin.headers.has("set-cookie")
3131
3204
  ? stripSafeCookiesForCache(origin, safeCookieSet)
3132
3205
  : origin;
3133
- storeInCache(cleanOrigin);
3206
+ return storeInCache(cleanOrigin);
3134
3207
  }
3135
3208
  }
3136
3209
  })
3137
3210
  .catch(() => {
3138
3211
  // Background revalidation failed — stale entry stays until SIE expires
3139
- }),
3212
+ })
3213
+ .finally(release),
3140
3214
  );
3141
3215
  }
3142
3216
 
@@ -3169,8 +3243,17 @@ export function createDecoWorkerEntry(
3169
3243
  if (ageSec < edgeConfig.fresh + edgeConfig.swr) {
3170
3244
  // STALE-HIT within SWR window — serve stale, revalidate in background
3171
3245
  recordCacheMetric(true, profile, "STALE-HIT", "edge");
3172
- revalidateInBackground();
3173
- return dressResponse(cached, "STALE-HIT", { "X-Cache-Age": String(Math.round(ageSec)) });
3246
+ const stale = dressResponse(cached, "STALE-HIT", {
3247
+ "X-Cache-Age": String(Math.round(ageSec)),
3248
+ });
3249
+ const release = claimRevalidation(cacheKey.url);
3250
+ // Already refreshing in this isolate: serve stale and leave it be.
3251
+ if (!release) return stale;
3252
+ return afterBodySent(
3253
+ stale,
3254
+ () => revalidateInBackground(release),
3255
+ (p) => ctx.waitUntil(p),
3256
+ );
3174
3257
  }
3175
3258
 
3176
3259
  // Past SWR window but still in cache (within SIE window) — keep reference