@decocms/tanstack 7.64.1 → 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 +4 -4
- package/src/sdk/kvHydration.test.ts +88 -0
- package/src/sdk/kvHydration.ts +60 -9
- package/src/vite/plugin.js +30 -2
- package/src/vite/plugin.test.ts +44 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@decocms/tanstack",
|
|
3
|
-
"version": "7.64.
|
|
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.
|
|
31
|
-
"@decocms/blocks-admin": "7.64.
|
|
32
|
-
"@decocms/blocks-cli": "7.64.
|
|
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
|
+
});
|
package/src/sdk/kvHydration.ts
CHANGED
|
@@ -24,7 +24,13 @@
|
|
|
24
24
|
* `DecofileProvider` pattern from the deco-cx/deco Fresh runtime.
|
|
25
25
|
*/
|
|
26
26
|
|
|
27
|
-
import {
|
|
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.
|
|
102
|
-
*
|
|
103
|
-
*
|
|
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
|
-
|
|
133
|
-
|
|
134
|
-
|
|
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 =
|
|
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;
|
package/src/vite/plugin.js
CHANGED
|
@@ -173,8 +173,27 @@ export function generateSchemaArgs(siteName) {
|
|
|
173
173
|
return ["--site", siteName];
|
|
174
174
|
}
|
|
175
175
|
|
|
176
|
-
/**
|
|
177
|
-
|
|
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).
|
package/src/vite/plugin.test.ts
CHANGED
|
@@ -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
|
+
});
|