@decocms/tanstack 7.64.0 → 7.64.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.64.0",
3
+ "version": "7.64.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.64.0",
31
- "@decocms/blocks-admin": "7.64.0",
32
- "@decocms/blocks-cli": "7.64.0",
30
+ "@decocms/blocks": "7.64.2",
31
+ "@decocms/blocks-admin": "7.64.2",
32
+ "@decocms/blocks-cli": "7.64.2",
33
33
  "@deco-cx/warp-node": "^0.3.16",
34
34
  "fast-json-patch": "^3.1.0",
35
35
  "ws": "^8.18.0"
@@ -213,3 +213,91 @@ describe("maybePollRevision", () => {
213
213
  expect(getCalls()).toBe(callsAfterHydrate + 1);
214
214
  });
215
215
  });
216
+
217
+ // ---------------------------------------------------------------------------
218
+ // No-bundled-fallback semantics (`decoVitePlugin({ fastDeploy: true })`)
219
+ //
220
+ // When the server bundle is stubbed, KV is the ONLY source of content. The
221
+ // "warn and serve bundled" recovery would serve an EMPTY site — 200s with no
222
+ // pages, which get edge-cached and outlive the KV failure. These assert it
223
+ // fails loudly instead, and that the default (bundled present) is unchanged.
224
+ // ---------------------------------------------------------------------------
225
+ describe("ensureBlocksHydrated without a bundled fallback", () => {
226
+ /** Simulates the stubbed server bundle: `export const blocks = {}`. */
227
+ const stubBundle = () => setBlocks({});
228
+
229
+ it("throws when the snapshot is missing instead of serving an empty site", async () => {
230
+ stubBundle();
231
+ const { kv } = makeKV(); // no decofile:<id> seeded
232
+ const env = { DECO_KV: kv, DECO_FAST_DEPLOY: "1", DECO_DEPLOYMENT_ID: ID };
233
+
234
+ await expect(ensureBlocksHydrated(env)).rejects.toThrow(/not found and no bundled snapshot/);
235
+ expect(loadBlocks()).toEqual({});
236
+ });
237
+
238
+ it("throws when KV itself fails", async () => {
239
+ stubBundle();
240
+ const kv = {
241
+ get: () => Promise.reject(new Error("KV unreachable")),
242
+ put: () => Promise.resolve(),
243
+ delete: () => Promise.resolve(),
244
+ } as unknown as KVNamespace;
245
+
246
+ await expect(
247
+ ensureBlocksHydrated({ DECO_KV: kv, DECO_FAST_DEPLOY: "1", DECO_DEPLOYMENT_ID: ID }),
248
+ ).rejects.toThrow(/KV unreachable/);
249
+ });
250
+
251
+ it("throws when no deployment id resolves", async () => {
252
+ stubBundle();
253
+ const { kv } = makeKV();
254
+
255
+ await expect(
256
+ ensureBlocksHydrated({ DECO_KV: kv, DECO_FAST_DEPLOY: "1" }),
257
+ ).rejects.toThrow(/no deployment id/);
258
+ });
259
+
260
+ it("does not latch hydration on the fatal path, so the next request retries", async () => {
261
+ stubBundle();
262
+ const blocks = { Site: { name: "from-kv" } };
263
+ const store = new Map<string, string>();
264
+ const kv: KVNamespace = {
265
+ get: (k) => Promise.resolve(store.get(k) ?? null),
266
+ put: (k, v) => {
267
+ store.set(k, v);
268
+ return Promise.resolve();
269
+ },
270
+ delete: (k) => {
271
+ store.delete(k);
272
+ return Promise.resolve();
273
+ },
274
+ };
275
+ const env = { DECO_KV: kv, DECO_FAST_DEPLOY: "1", DECO_DEPLOYMENT_ID: ID };
276
+
277
+ // First request: snapshot absent → fatal.
278
+ await expect(ensureBlocksHydrated(env)).rejects.toThrow();
279
+
280
+ // Operator seeds it; the isolate must pick it up rather than stay empty.
281
+ store.set(SNAP, JSON.stringify(blocks));
282
+ store.set(REV, computeRevision(blocks));
283
+
284
+ await expect(ensureBlocksHydrated(env)).resolves.toBeUndefined();
285
+ expect(loadBlocks()).toEqual(blocks);
286
+ });
287
+
288
+ it("still warns and serves bundled when a bundled snapshot IS present", async () => {
289
+ // Default configuration — must behave exactly as before this change.
290
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
291
+ const kv = {
292
+ get: () => Promise.reject(new Error("KV unreachable")),
293
+ put: () => Promise.resolve(),
294
+ delete: () => Promise.resolve(),
295
+ } as unknown as KVNamespace;
296
+
297
+ await expect(
298
+ ensureBlocksHydrated({ DECO_KV: kv, DECO_FAST_DEPLOY: "1", DECO_DEPLOYMENT_ID: ID }),
299
+ ).resolves.toBeUndefined();
300
+ expect(loadBlocks()).toEqual(BUNDLED);
301
+ expect(warn).toHaveBeenCalled();
302
+ });
303
+ });
@@ -24,7 +24,13 @@
24
24
  * `DecofileProvider` pattern from the deco-cx/deco Fresh runtime.
25
25
  */
26
26
 
27
- import { getDeploymentId, getRevision, setBlocks } from "@decocms/blocks/cms";
27
+ import {
28
+ DEPLOYMENT_ID_ENV,
29
+ getDeploymentId,
30
+ getRevision,
31
+ loadBlocks,
32
+ setBlocks,
33
+ } from "@decocms/blocks/cms";
28
34
  import { KVBlockSource } from "../cms/kvBlockSource";
29
35
  import type { KVNamespace } from "@decocms/blocks/cms";
30
36
  import { setSpanAttribute } from "@decocms/blocks/sdk/observability";
@@ -95,12 +101,36 @@ export function getFastDeployKV(env: Env): KVNamespace | null {
95
101
  return getKV(env);
96
102
  }
97
103
 
104
+ /**
105
+ * Is there a bundled snapshot to fall back on?
106
+ *
107
+ * `decoVitePlugin({ fastDeploy: true })` stubs `blocks.gen` out of the server
108
+ * bundle to avoid holding the decofile twice (see the option's docs). That
109
+ * makes KV the ONLY source of content, so the "warn and serve bundled"
110
+ * recovery below would actually serve an EMPTY site — 200s with no pages,
111
+ * which then get edge-cached and outlive the KV failure that caused them.
112
+ *
113
+ * Checking the in-memory map rather than a build-time flag keeps this honest
114
+ * in both configurations, and means sites that still bundle their decofile
115
+ * (the default) behave exactly as before.
116
+ */
117
+ function hasBundledFallback(): boolean {
118
+ return Object.keys(loadBlocks()).length > 0;
119
+ }
120
+
98
121
  /**
99
122
  * Cold-start hydration. Awaits the KV snapshot once per isolate and swaps it
100
123
  * into the in-memory block map. Concurrent first requests share a single
101
- * in-flight load. On any error (KV outage, bad JSON) we keep the bundled
102
- * snapshot and mark hydration done — recovery happens via `maybePollRevision`
103
- * once KV is reachable again (its revision will differ from the bundled one).
124
+ * in-flight load.
125
+ *
126
+ * On failure (KV outage, bad JSON, snapshot not seeded) the behavior depends on
127
+ * whether a bundled snapshot exists:
128
+ *
129
+ * - Bundled present (default): warn, serve bundled, mark hydration done —
130
+ * `maybePollRevision` recovers once KV is reachable again.
131
+ * - Bundled stubbed out (`fastDeploy`): throw. There is no content to serve, so
132
+ * a 5xx is the only honest answer; hydration is left unlatched so the next
133
+ * request retries instead of pinning the isolate to an empty decofile.
104
134
  */
105
135
  export function ensureBlocksHydrated(env: Env, _ctx?: ExecutionContextLike): Promise<void> {
106
136
  if (!isFastDeployEnabled(env)) return Promise.resolve();
@@ -114,28 +144,49 @@ export function ensureBlocksHydrated(env: Env, _ctx?: ExecutionContextLike): Pro
114
144
  // content). Never read another deployment's key.
115
145
  const deploymentId = getDeploymentId(env);
116
146
  if (!deploymentId) {
147
+ if (!hasBundledFallback()) {
148
+ return Promise.reject(
149
+ new Error(
150
+ `[CMS/KV] no deployment id (set ${DEPLOYMENT_ID_ENV}) and no bundled snapshot to fall back on`,
151
+ ),
152
+ );
153
+ }
117
154
  setSpanAttribute("deco.block.source", "bundled");
118
155
  G.__deco!.kvHydrated = true;
119
156
  return Promise.resolve();
120
157
  }
121
158
 
122
159
  const load = (async () => {
160
+ // Held rather than rethrown inline so the `finally` below can decide
161
+ // whether to latch — latching on a fatal path would serve an empty
162
+ // decofile for the isolate's entire life.
163
+ let fatal: Error | null = null;
123
164
  try {
124
165
  const snapshot = await new KVBlockSource(kv, deploymentId).loadSnapshot();
125
166
  if (snapshot) {
126
167
  setBlocks(snapshot.blocks);
127
168
  setSpanAttribute("deco.block.source", "kv");
128
- } else {
169
+ } else if (hasBundledFallback()) {
129
170
  setSpanAttribute("deco.block.source", "bundled");
171
+ } else {
172
+ fatal = new Error(
173
+ `[CMS/KV] decofile:${deploymentId} not found and no bundled snapshot to fall back on — ` +
174
+ `seed it before activating this version`,
175
+ );
130
176
  }
131
177
  } catch (e) {
132
- // Non-fatal: serve the bundled snapshot. The poll loop recovers later.
133
- console.warn("[CMS/KV] cold-start hydration failed, using bundled snapshot:", e);
134
- setSpanAttribute("deco.block.source", "bundled");
178
+ if (hasBundledFallback()) {
179
+ // Non-fatal: serve the bundled snapshot. The poll loop recovers later.
180
+ console.warn("[CMS/KV] cold-start hydration failed, using bundled snapshot:", e);
181
+ setSpanAttribute("deco.block.source", "bundled");
182
+ } else {
183
+ fatal = e instanceof Error ? e : new Error(String(e));
184
+ }
135
185
  } finally {
136
- G.__deco!.kvHydrated = true;
186
+ G.__deco!.kvHydrated = !fatal;
137
187
  G.__deco!.kvHydration = null;
138
188
  }
189
+ if (fatal) throw fatal;
139
190
  })();
140
191
 
141
192
  G.__deco!.kvHydration = load;
@@ -173,8 +173,27 @@ export function generateSchemaArgs(siteName) {
173
173
  return ["--site", siteName];
174
174
  }
175
175
 
176
- /** @returns {import("vite").PluginOption} */
177
- export function decoVitePlugin() {
176
+ /**
177
+ * @param {object} [opts]
178
+ * @param {boolean} [opts.fastDeploy=false] Stub `blocks.gen` out of the SERVER
179
+ * bundle too, so the worker's only copy of the decofile is the one hydrated
180
+ * from KV at cold start.
181
+ *
182
+ * Without this, a fast-deploy site holds the decofile TWICE: the bundled
183
+ * `JSON.parse(...)` graph stays permanently reachable through the site's
184
+ * `import { blocks } from ".deco/blocks.gen"` module binding, and
185
+ * `ensureBlocksHydrated` adds a second graph via `setBlocks()`. For a 10MB
186
+ * decofile that is tens of MB of avoidable isolate memory.
187
+ *
188
+ * Opt-in because it removes the fallback: with no bundled snapshot, a cold
189
+ * start that cannot read KV has no content to serve. `ensureBlocksHydrated`
190
+ * detects that case and fails the request loudly (5xx) instead of serving an
191
+ * empty site — see `kvHydration.ts`. Only enable alongside
192
+ * `DECO_FAST_DEPLOY=1` + a `DECO_KV` binding + a deploy pipeline that seeds
193
+ * `decofile:<deployment-id>` BEFORE the new version activates.
194
+ * @returns {import("vite").PluginOption}
195
+ */
196
+ export function decoVitePlugin({ fastDeploy = false } = {}) {
178
197
  /** @type {import("vite").Plugin} */
179
198
  const plugin = {
180
199
  name: "deco-server-only-stubs",
@@ -207,6 +226,15 @@ export function decoVitePlugin() {
207
226
  return "export const blocks = {};";
208
227
  }
209
228
 
229
+ // Fast-deploy: stub on the SERVER too. The worker hydrates the decofile
230
+ // from KV at cold start, so shipping it in the bundle would just pin a
231
+ // second, permanently-reachable copy in isolate memory (the site's
232
+ // `import { blocks }` binding keeps the bundled graph alive for the
233
+ // isolate's whole life, even after `setBlocks()` swaps in the KV one).
234
+ if (fastDeploy) {
235
+ return "export const blocks = {};";
236
+ }
237
+
210
238
  // SSR: read .json sibling and emit JSON.parse(...) wrapper.
211
239
  // This avoids the Vite SSR module runner hanging on large dynamic
212
240
  // imports and lets V8 use its fast JSON parser (~2-10x vs object literal).
@@ -50,3 +50,47 @@ describe("decoVitePlugin — loaders.gen client stub", () => {
50
50
  expect(plugin.load("/repo/src/actions/foo.ts", { ssr: false })).toBeUndefined();
51
51
  });
52
52
  });
53
+
54
+ /**
55
+ * `fastDeploy: true` must stub blocks.gen out of the SERVER bundle too.
56
+ *
57
+ * Otherwise a fast-deploy site holds the decofile twice: the bundled
58
+ * JSON.parse(...) graph stays reachable via the site's `import { blocks }`
59
+ * binding for the isolate's whole life, and ensureBlocksHydrated adds a
60
+ * second graph. Tens of MB of avoidable memory for a 10MB decofile.
61
+ */
62
+ describe("decoVitePlugin — fastDeploy server stub", () => {
63
+ const id = "/repo/.deco/blocks.gen.ts";
64
+ const STUB = "export const blocks = {};";
65
+
66
+ it("stubs blocks.gen on SSR when fastDeploy is on", () => {
67
+ const plugin = decoVitePlugin({ fastDeploy: true }) as {
68
+ load: (id: string, options?: { ssr?: boolean }) => string | undefined;
69
+ };
70
+ expect(plugin.load(id, { ssr: true })).toBe(STUB);
71
+ });
72
+
73
+ it("keeps stubbing the client bundle when fastDeploy is on", () => {
74
+ const plugin = decoVitePlugin({ fastDeploy: true }) as {
75
+ load: (id: string, options?: { ssr?: boolean }) => string | undefined;
76
+ };
77
+ expect(plugin.load(id, { ssr: false })).toBe(STUB);
78
+ });
79
+
80
+ it("does NOT stub blocks.gen on SSR by default (bundled fallback preserved)", () => {
81
+ const plugin = decoVitePlugin() as {
82
+ load: (id: string, options?: { ssr?: boolean }) => string | undefined;
83
+ };
84
+ // No .json sibling on disk for this synthetic path, so the hook falls
85
+ // through to Vite (undefined) rather than returning a stub. The point is
86
+ // that it never returns the empty stub for SSR.
87
+ expect(plugin.load(id, { ssr: true })).not.toBe(STUB);
88
+ });
89
+
90
+ it("leaves unrelated modules alone with fastDeploy on", () => {
91
+ const plugin = decoVitePlugin({ fastDeploy: true }) as {
92
+ load: (id: string, options?: { ssr?: boolean }) => string | undefined;
93
+ };
94
+ expect(plugin.load("/repo/src/sections/Hero.tsx", { ssr: true })).toBeUndefined();
95
+ });
96
+ });