@decocms/blocks 8.0.0 → 8.1.0-next.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 (175) hide show
  1. package/bin/deco.js +13 -0
  2. package/package.json +39 -3
  3. package/src/cms/applySectionConventions.ts +26 -2
  4. package/src/cms/blockSource.ts +37 -0
  5. package/src/cms/client.ts +5 -0
  6. package/src/cms/deferredTrigger.ts +58 -0
  7. package/src/cms/draftSource.ts +171 -57
  8. package/src/cms/index.ts +32 -3
  9. package/src/cms/loader.ts +318 -59
  10. package/src/cms/registry.ts +22 -0
  11. package/src/cms/renderJson.ts +179 -0
  12. package/src/cms/resolve.ts +396 -95
  13. package/src/cms/schema.ts +9 -5
  14. package/src/cms/sectionLoaders.ts +106 -56
  15. package/src/hooks/Image.tsx +70 -6
  16. package/src/hooks/LiveControls.tsx +30 -8
  17. package/src/hooks/Stats.tsx +134 -0
  18. package/src/hooks/index.ts +5 -0
  19. package/src/hooks/useLoadMore.ts +100 -0
  20. package/src/index.ts +37 -0
  21. package/src/middleware/observability.ts +173 -16
  22. package/src/preview/DraftPreviewBadge.tsx +306 -0
  23. package/src/preview/decoMark.ts +11 -0
  24. package/src/preview/index.ts +8 -0
  25. package/src/protocol/assets.ts +124 -0
  26. package/src/protocol/canonical.ts +7 -0
  27. package/src/protocol/ciphertext.ts +6 -0
  28. package/src/protocol/client.ts +170 -0
  29. package/src/protocol/conformance/cases/assets.ts +81 -0
  30. package/src/protocol/conformance/cases/guards.ts +314 -0
  31. package/src/protocol/conformance/cases/reads.ts +168 -0
  32. package/src/protocol/conformance/cases/types.ts +9 -0
  33. package/src/protocol/conformance/cases/wire.ts +138 -0
  34. package/src/protocol/conformance/cases/writes.ts +345 -0
  35. package/src/protocol/conformance/contentHashFixtures.ts +79 -0
  36. package/src/protocol/conformance/context.ts +222 -0
  37. package/src/protocol/conformance/index.ts +140 -0
  38. package/src/protocol/errors.ts +142 -0
  39. package/src/protocol/index.ts +39 -0
  40. package/src/protocol/keys.ts +279 -0
  41. package/src/protocol/params.ts +67 -0
  42. package/src/protocol/secrets.ts +231 -0
  43. package/src/protocol/server/assets.ts +119 -0
  44. package/src/protocol/server/auth.ts +49 -0
  45. package/src/protocol/server/bodyCache.ts +84 -0
  46. package/src/protocol/server/content.ts +175 -0
  47. package/src/protocol/server/core.ts +112 -0
  48. package/src/protocol/server/handler.ts +102 -0
  49. package/src/protocol/server/http.ts +139 -0
  50. package/src/protocol/server/index.ts +11 -0
  51. package/src/protocol/server/methods/apply.ts +341 -0
  52. package/src/protocol/server/methods/read.ts +156 -0
  53. package/src/protocol/server/rpc.ts +136 -0
  54. package/src/protocol/storage/fs/hash.ts +21 -0
  55. package/src/protocol/storage/fs/index.ts +338 -0
  56. package/src/protocol/storage/fs/lock.ts +68 -0
  57. package/src/protocol/storage/fs/transaction.ts +183 -0
  58. package/src/protocol/storage/fs/unsupported.ts +15 -0
  59. package/src/protocol/storage/memory.ts +238 -0
  60. package/src/protocol/storage.ts +182 -0
  61. package/src/protocol/types.ts +172 -0
  62. package/src/sdk/abTesting.ts +60 -3
  63. package/src/sdk/analytics.ts +72 -2
  64. package/src/sdk/cacheHeaders.ts +210 -10
  65. package/src/sdk/cacheStorage.ts +287 -0
  66. package/src/sdk/cachedLoader.ts +143 -90
  67. package/src/sdk/crypto.ts +16 -2
  68. package/src/sdk/deepOmit.ts +52 -0
  69. package/src/sdk/encoding.ts +2 -5
  70. package/src/sdk/experiments.ts +314 -0
  71. package/src/sdk/fetchCache.ts +269 -0
  72. package/src/sdk/fetchTimeout.ts +58 -0
  73. package/src/sdk/flags.ts +38 -8
  74. package/src/sdk/index.ts +7 -0
  75. package/src/sdk/instrumentedFetch.ts +25 -2
  76. package/src/sdk/nonce.ts +46 -0
  77. package/src/sdk/normalizeUrls.ts +2 -2
  78. package/src/sdk/observability.ts +8 -1
  79. package/src/sdk/otel.ts +131 -25
  80. package/src/sdk/otelHttpLog.ts +4 -4
  81. package/src/sdk/otelHttpMeter.ts +39 -13
  82. package/src/sdk/otelHttpTracer.ts +4 -4
  83. package/src/sdk/redirects.ts +113 -5
  84. package/src/sdk/responseCache.ts +82 -0
  85. package/src/sdk/urlUtils.ts +49 -0
  86. package/src/sdk/useSuggestions.ts +1 -1
  87. package/src/v8/analytics.ts +50 -0
  88. package/src/v8/background.ts +107 -0
  89. package/src/v8/builtins/data.ts +23 -0
  90. package/src/v8/builtins/index.ts +26 -0
  91. package/src/v8/builtins/lazy.ts +23 -0
  92. package/src/v8/builtins/legacy.ts +65 -0
  93. package/src/v8/builtins/matchers.ts +31 -0
  94. package/src/v8/builtins/multivariate.ts +25 -0
  95. package/src/v8/builtins/secret.ts +82 -0
  96. package/src/v8/canonical.ts +117 -0
  97. package/src/v8/ciphertext.ts +158 -0
  98. package/src/v8/cli/builtins.ts +20 -0
  99. package/src/v8/cli/check/index.ts +774 -0
  100. package/src/v8/cli/check/messages.ts +168 -0
  101. package/src/v8/cli/content.ts +287 -0
  102. package/src/v8/cli/index.ts +17 -0
  103. package/src/v8/cli/log.ts +18 -0
  104. package/src/v8/cli/main.ts +12 -0
  105. package/src/v8/cli/root.ts +66 -0
  106. package/src/v8/cli/run.ts +236 -0
  107. package/src/v8/cli/schema/builtinSchemas.ts +236 -0
  108. package/src/v8/cli/schema/generate.ts +507 -0
  109. package/src/v8/cli/schema/index.ts +63 -0
  110. package/src/v8/cli/schema/tsProgram.ts +497 -0
  111. package/src/v8/cli/schema/typeToSchema.ts +689 -0
  112. package/src/v8/cli/serve/server.ts +303 -0
  113. package/src/v8/cli/watch.ts +86 -0
  114. package/src/v8/client.ts +147 -0
  115. package/src/v8/cms.ts +237 -0
  116. package/src/v8/content.ts +195 -0
  117. package/src/v8/draft.ts +136 -0
  118. package/src/v8/errors.ts +59 -0
  119. package/src/v8/fetch.ts +152 -0
  120. package/src/v8/identity.ts +65 -0
  121. package/src/v8/index.ts +39 -0
  122. package/src/v8/json.ts +74 -0
  123. package/src/v8/matchRoute.ts +204 -0
  124. package/src/v8/remoteLoader.ts +282 -0
  125. package/src/v8/resolver.ts +278 -0
  126. package/src/v8/secrets.ts +17 -0
  127. package/src/v8/telemetry.ts +533 -0
  128. package/src/v8/types.ts +240 -0
  129. package/src/cms/blockSource.test.ts +0 -76
  130. package/src/cms/client.browserBundle.test.ts +0 -44
  131. package/src/cms/draftSource.test.ts +0 -343
  132. package/src/cms/layoutCacheRace.test.ts +0 -181
  133. package/src/cms/loadDecofileDirectory.test.ts +0 -109
  134. package/src/cms/loader.test.ts +0 -200
  135. package/src/cms/registry.test.ts +0 -110
  136. package/src/cms/resolve.test.ts +0 -980
  137. package/src/cms/schema.test.ts +0 -356
  138. package/src/cms/sectionLoaderContext.test.ts +0 -111
  139. package/src/cms/sectionLoaders.test.ts +0 -533
  140. package/src/cms/sectionMixins.test.ts +0 -167
  141. package/src/cms/stickyFlags.test.ts +0 -117
  142. package/src/flags/flags.test.ts +0 -148
  143. package/src/hooks/Image.test.ts +0 -100
  144. package/src/hooks/RenderSection.test.tsx +0 -81
  145. package/src/matchers/builtins.test.ts +0 -318
  146. package/src/matchers/override.test.ts +0 -205
  147. package/src/middleware/hydrationContext.test.ts +0 -61
  148. package/src/middleware/observability.test.ts +0 -242
  149. package/src/middleware/validateSection.test.ts +0 -147
  150. package/src/sdk/abTesting.test.ts +0 -326
  151. package/src/sdk/cacheHeaders.test.ts +0 -115
  152. package/src/sdk/cachedLoader.test.ts +0 -122
  153. package/src/sdk/cachedLoaderModule.test.ts +0 -209
  154. package/src/sdk/cn.test.ts +0 -34
  155. package/src/sdk/composite.test.ts +0 -121
  156. package/src/sdk/cookie.test.ts +0 -108
  157. package/src/sdk/encoding.test.ts +0 -71
  158. package/src/sdk/env.test.ts +0 -33
  159. package/src/sdk/flags.test.ts +0 -91
  160. package/src/sdk/http.test.ts +0 -71
  161. package/src/sdk/inflightTimeout.test.ts +0 -35
  162. package/src/sdk/instrumentedFetch.test.ts +0 -559
  163. package/src/sdk/invoke.test.ts +0 -115
  164. package/src/sdk/logger.test.ts +0 -432
  165. package/src/sdk/otel.test.ts +0 -526
  166. package/src/sdk/otelAdapters.test.ts +0 -89
  167. package/src/sdk/otelHttpLog.test.ts +0 -457
  168. package/src/sdk/otelHttpMeter.test.ts +0 -292
  169. package/src/sdk/otelHttpTracer.test.ts +0 -474
  170. package/src/sdk/requestContextStorage.browser.test.ts +0 -29
  171. package/src/sdk/urlRedaction.test.ts +0 -73
  172. package/src/sdk/useDevice.test.ts +0 -130
  173. package/src/sdk/useScript.test.ts +0 -128
  174. package/src/sdk/useSuggestions.test.ts +0 -230
  175. package/tsconfig.json +0 -7
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Server-side loader caching with stale-while-revalidate + stale-if-error.
3
3
  *
4
- * Provides an in-memory cache layer for commerce loaders during SSR.
4
+ * Caches commerce loader results in memory and optional app-provided storage.
5
5
  * Supports:
6
6
  * - Single-flight dedup (identical concurrent requests share one fetch)
7
7
  * - SWR: serve stale immediately, refresh in background
@@ -13,11 +13,13 @@
13
13
 
14
14
  import {
15
15
  recordCacheMetric,
16
+ recordCacheSizeMetric,
16
17
  recordLoaderError,
17
18
  recordLoaderMetric,
18
19
  withTracing,
19
20
  } from "../middleware/observability";
20
21
  import { type CacheProfileName, loaderCacheOptions } from "./cacheHeaders";
22
+ import { cacheBackground, createCacheStore, getCacheStorageContext } from "./cacheStorage";
21
23
  import { withInflightTimeout } from "./inflightTimeout";
22
24
  import { RequestContext } from "./requestContext";
23
25
 
@@ -28,14 +30,8 @@ import { RequestContext } from "./requestContext";
28
30
  // pattern already used in `../cms/blockSource.ts`.
29
31
  declare const __DECO_BUILD_HASH__: string | undefined;
30
32
 
31
- // Prefixes every in-memory loader cache key with the build hash, mirroring the
32
- // edge cache's `__v`. This is defense-in-depth, NOT the primary invalidation
33
- // lever: the cache Map is per-isolate, so a fresh isolate spun for a new deploy
34
- // already starts empty, and a warm isolate keeps running its old bundle (hence
35
- // its old BUILD) until it is recycled — the prefix cannot flush that. It only
36
- // matters if this store ever becomes shared across builds. Gated on truthiness
37
- // (empty string ⇒ unversioned) to match getBuildHash()/getDeploymentId() in
38
- // workerEntry.ts / blockSource.ts.
33
+ // Include the build version even when called outside the TanStack worker. The
34
+ // request-scoped store additionally separates sites, content revisions and segments.
39
35
  const BUILD =
40
36
  typeof __DECO_BUILD_HASH__ !== "undefined" && __DECO_BUILD_HASH__ ? __DECO_BUILD_HASH__ : "";
41
37
 
@@ -55,6 +51,8 @@ export interface CachedLoaderOptions {
55
51
  maxAge?: number;
56
52
  /** How long to serve stale on origin error, in ms. Default: 0 (no error fallback). */
57
53
  staleIfError?: number;
54
+ /** Maximum stale-while-revalidate window in ms. Default: 5 minutes. */
55
+ staleWhileRevalidate?: number;
58
56
  /** Key function to generate a cache key from loader props. Default: JSON.stringify. */
59
57
  keyFn?: (props: unknown) => string;
60
58
  }
@@ -78,7 +76,6 @@ export interface LoaderModule<TProps = any, TResult = any> {
78
76
  cacheKey?: (props: TProps, req?: Request) => string | null;
79
77
  }
80
78
 
81
-
82
79
  interface CacheEntry<T = unknown> {
83
80
  value: T;
84
81
  createdAt: number;
@@ -102,19 +99,48 @@ const DEFAULT_MAX_AGE = 60_000;
102
99
  const DEFAULT_MAX_CACHE_BYTES = 32 * 1024 * 1024;
103
100
 
104
101
  function resolveMaxBytes(): number {
105
- const env = typeof globalThis.process !== "undefined"
106
- ? globalThis.process.env
107
- : undefined;
102
+ const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
108
103
  const raw = env?.DECO_LOADER_CACHE_MAX_BYTES;
109
104
  if (!raw) return DEFAULT_MAX_CACHE_BYTES;
110
105
  const parsed = Number.parseInt(raw, 10);
111
106
  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_CACHE_BYTES;
112
107
  }
113
108
 
114
- const MAX_CACHE_BYTES = resolveMaxBytes();
109
+ let maxCacheBytes = resolveMaxBytes();
115
110
 
116
- const cache = new Map<string, CacheEntry>();
117
- let cacheBytes = 0;
111
+ /**
112
+ * Override the loader cache byte cap at runtime.
113
+ *
114
+ * The `DECO_LOADER_CACHE_MAX_BYTES` env override above only lands when the
115
+ * Worker's `compatibility_date` is new enough for `nodejs_compat` to populate
116
+ * `process.env`. Verified in workerd: with `2024-09-23` it is empty both at
117
+ * module scope and inside the handler; with `2025-06-01` it is populated. Sites
118
+ * pinned to an older date — a common thing to do, since the date also gates
119
+ * behaviour flags they may have tuned deliberately — had a documented knob that
120
+ * silently did nothing.
121
+ *
122
+ * Call this from the site's `setup.ts`, before any loader is wrapped.
123
+ *
124
+ * Sizing note: the cap is per ISOLATE, not per site, and a Worker isolate has
125
+ * 128 MB total, shared with the bundle, the V8 heap and the render working set.
126
+ * Setting it at or near 128 MB does not give headroom — it removes the ceiling.
127
+ */
128
+ export function setLoaderCacheMaxBytes(bytes: number): void {
129
+ if (!Number.isFinite(bytes) || bytes <= 0) return;
130
+ maxCacheBytes = bytes;
131
+ }
132
+
133
+ /** Current byte cap — exported for diagnostics and tests. */
134
+ export function getLoaderCacheMaxBytes(): number {
135
+ return maxCacheBytes;
136
+ }
137
+
138
+ const cache = createCacheStore<CacheEntry>(
139
+ "loaders",
140
+ Infinity,
141
+ Infinity,
142
+ (entry) => entry.estimatedBytes,
143
+ );
118
144
 
119
145
  // Bumped by clearLoaderCache(). A loader invocation captures this at entry and
120
146
  // only writes its result back if the generation is unchanged when it settles —
@@ -147,28 +173,28 @@ function estimateBytes(value: unknown): number {
147
173
  }
148
174
  }
149
175
 
150
- function setCacheEntry<T>(key: string, entry: CacheEntry<T>) {
151
- const prev = cache.get(key);
152
- if (prev) cacheBytes -= prev.estimatedBytes;
153
- cacheBytes += entry.estimatedBytes;
154
- cache.set(key, entry);
176
+ /**
177
+ * The single write path into the cache — both the cold-miss and the SWR
178
+ * background-refresh callers route through here, which is why the size metric
179
+ * is emitted at this chokepoint rather than at each call site.
180
+ */
181
+ function setCacheEntry<T>(key: string, entry: CacheEntry<T>, name: string, retention: number) {
182
+ recordCacheSizeMetric(entry.estimatedBytes, name);
183
+ cache.set(key, entry, entry.createdAt + retention);
155
184
  }
156
185
 
157
186
  function deleteCacheEntry(key: string) {
158
- const prev = cache.get(key);
159
- if (!prev) return;
160
- cacheBytes -= prev.estimatedBytes;
161
187
  cache.delete(key);
162
188
  }
163
189
 
164
190
  function evictIfNeeded() {
165
- if (cacheBytes <= MAX_CACHE_BYTES) return;
166
- const oldest = [...cache.entries()].sort(
167
- (a, b) => a[1].createdAt - b[1].createdAt,
168
- );
169
- for (const [key] of oldest) {
191
+ let cacheBytes = cache.estimatedBytes;
192
+ if (cacheBytes <= maxCacheBytes) return;
193
+ const oldest = [...cache.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
194
+ for (const [key, entry] of oldest) {
170
195
  deleteCacheEntry(key);
171
- if (cacheBytes <= MAX_CACHE_BYTES) break;
196
+ cacheBytes -= entry.estimatedBytes;
197
+ if (cacheBytes <= maxCacheBytes) break;
172
198
  }
173
199
  }
174
200
 
@@ -208,7 +234,13 @@ export function createCachedLoader<TProps, TResult>(
208
234
  optionsOrProfile: CachedLoaderOptions | CacheProfileName,
209
235
  ): (props: TProps) => Promise<TResult> {
210
236
  const resolved = resolveOptions(optionsOrProfile);
211
- const { policy, maxAge = DEFAULT_MAX_AGE, staleIfError = 0, keyFn = JSON.stringify } = resolved;
237
+ const {
238
+ policy,
239
+ maxAge = DEFAULT_MAX_AGE,
240
+ staleIfError = 0,
241
+ staleWhileRevalidate = 300_000,
242
+ keyFn = JSON.stringify,
243
+ } = resolved;
212
244
 
213
245
  const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
214
246
  const isDev = env?.DECO_CACHE_DISABLE === "true" || env?.NODE_ENV === "development";
@@ -218,14 +250,17 @@ export function createCachedLoader<TProps, TResult>(
218
250
  console.warn(
219
251
  `[cachedLoader] ${name}: maxAge=${Math.round(maxAge / 1000)}s is very long — ` +
220
252
  `upstream changes take that long to propagate. Prefer a short window and use ` +
221
- `POST /_cache/purge-loaders (or a redeploy) for immediate invalidation.`,
253
+ `short TTLs for shared storage; the purge-loaders endpoint clears memory only.`,
222
254
  );
223
255
  }
224
256
 
225
257
  if (policy === "no-store") return loaderFn;
226
258
 
227
259
  return async (props: TProps): Promise<TResult> => {
228
- const cacheKey = `${BUILD}::${name}::${keyFn(props)}`;
260
+ const cacheKey = cache.key(`${BUILD}::${name}::${keyFn(props)}`);
261
+ const retention =
262
+ maxAge +
263
+ Math.max(staleIfError, policy === "stale-while-revalidate" ? staleWhileRevalidate : 0);
229
264
  // Snapshot the cache generation; a purge during this invocation bumps it,
230
265
  // and the deferred writes below skip repopulating a just-cleared entry.
231
266
  const gen = cacheGeneration;
@@ -246,11 +281,10 @@ export function createCachedLoader<TProps, TResult>(
246
281
  recordCacheMetric(false, name, undefined, "cachedLoader");
247
282
  const devStart = performance.now();
248
283
  const promise = withInflightTimeout(
249
- withTracing(
250
- "deco.cachedLoader",
251
- () => loaderFn(props),
252
- { "deco.loader": name, "deco.cache.policy": "no-cache-dev" },
253
- ),
284
+ withTracing("deco.cachedLoader", () => loaderFn(props), {
285
+ "deco.loader": name,
286
+ "deco.cache.policy": "no-cache-dev",
287
+ }),
254
288
  `cachedLoader:dev ${cacheKey}`,
255
289
  )
256
290
  .then((r) => {
@@ -267,7 +301,14 @@ export function createCachedLoader<TProps, TResult>(
267
301
  return promise;
268
302
  }
269
303
 
270
- const entry = cache.get(cacheKey) as CacheEntry<TResult> | undefined;
304
+ let entry = cache.get(cacheKey) as CacheEntry<TResult> | undefined;
305
+ if (!entry && getCacheStorageContext()?.storage) {
306
+ entry = (await cache.read(cacheKey)) as CacheEntry<TResult> | undefined;
307
+ evictIfNeeded();
308
+ }
309
+ // Another caller may have started the origin fetch while storage was being read.
310
+ const pending = inflightRequests.get(cacheKey);
311
+ if (pending) return pending as Promise<TResult>;
271
312
  const now = Date.now();
272
313
  const isStale = entry ? now - entry.createdAt > maxAge : true;
273
314
 
@@ -286,41 +327,52 @@ export function createCachedLoader<TProps, TResult>(
286
327
  return entry.value;
287
328
  }
288
329
 
289
- if (entry && isStale && !entry.refreshing) {
330
+ if (
331
+ entry &&
332
+ isStale &&
333
+ now - entry.createdAt <= maxAge + staleWhileRevalidate &&
334
+ !entry.refreshing
335
+ ) {
290
336
  // Stale-while-revalidate hit: serve stale, refresh in background.
291
337
  recordCacheMetric(true, name, "STALE-HIT", "cachedLoader");
292
338
  recordLoaderMetric(name, 0, "STALE-HIT");
293
339
  entry.refreshing = true;
294
- loaderFn(props)
295
- .then((result) => {
296
- // Skip the write if a purge cleared the cache mid-refresh — otherwise
297
- // we'd re-insert pre-purge data the purge was meant to drop.
298
- if (gen !== cacheGeneration) return;
299
- setCacheEntry(cacheKey, {
300
- value: result,
301
- createdAt: Date.now(),
302
- refreshing: false,
303
- estimatedBytes: estimateBytes(result),
304
- });
305
- evictIfNeeded();
306
- })
307
- .catch(() => {
308
- // Background refresh failed — entry stays stale.
309
- // If past the SIE window, evict so we don't serve indefinitely stale data.
310
- entry.refreshing = false;
311
- if (staleIfError > 0 && now - entry.createdAt > maxAge + staleIfError) {
312
- deleteCacheEntry(cacheKey);
313
- }
314
- });
340
+ cacheBackground(
341
+ Promise.resolve()
342
+ .then(() => loaderFn(props))
343
+ .then((result) => {
344
+ // Skip the write if a purge cleared the cache mid-refresh — otherwise
345
+ // we'd re-insert pre-purge data the purge was meant to drop.
346
+ if (gen !== cacheGeneration) return;
347
+ setCacheEntry(
348
+ cacheKey,
349
+ {
350
+ value: result,
351
+ createdAt: Date.now(),
352
+ refreshing: false,
353
+ estimatedBytes: estimateBytes(result),
354
+ },
355
+ name,
356
+ retention,
357
+ );
358
+ evictIfNeeded();
359
+ })
360
+ .catch(() => {
361
+ // Background refresh failed — entry stays stale.
362
+ // If past the SIE window, evict so we don't serve indefinitely stale data.
363
+ entry.refreshing = false;
364
+ if (staleIfError > 0 && now - entry.createdAt > maxAge + staleIfError) {
365
+ deleteCacheEntry(cacheKey);
366
+ }
367
+ }),
368
+ );
315
369
  return entry.value;
316
370
  }
317
371
 
318
- if (entry) {
319
- // Past SIE window — still serve the stale value once but mark
320
- // the decision as STALE-ERROR so dashboards can distinguish
321
- // this from healthy SWR.
322
- recordCacheMetric(true, name, "STALE-ERROR", "cachedLoader");
323
- recordLoaderMetric(name, 0, "STALE-ERROR");
372
+ if (entry && now - entry.createdAt <= maxAge + staleWhileRevalidate) {
373
+ // A background refresh is already running in this isolate.
374
+ recordCacheMetric(true, name, "STALE-HIT", "cachedLoader");
375
+ recordLoaderMetric(name, 0, "STALE-HIT");
324
376
  return entry.value;
325
377
  }
326
378
  }
@@ -341,12 +393,17 @@ export function createCachedLoader<TProps, TResult>(
341
393
  // Skip caching if a purge landed while this loader was in flight — still
342
394
  // return the fresh value to the caller, just don't persist a raced entry.
343
395
  if (gen === cacheGeneration) {
344
- setCacheEntry(cacheKey, {
345
- value: result,
346
- createdAt: Date.now(),
347
- refreshing: false,
348
- estimatedBytes: estimateBytes(result),
349
- });
396
+ setCacheEntry(
397
+ cacheKey,
398
+ {
399
+ value: result,
400
+ createdAt: Date.now(),
401
+ refreshing: false,
402
+ estimatedBytes: estimateBytes(result),
403
+ },
404
+ name,
405
+ retention,
406
+ );
350
407
  evictIfNeeded();
351
408
  }
352
409
  return result;
@@ -354,7 +411,7 @@ export function createCachedLoader<TProps, TResult>(
354
411
  .catch((err) => {
355
412
  // SIE fallback: if we have a stale entry within the error window, return it
356
413
  if (staleIfError > 0 && entry) {
357
- const age = now - entry.createdAt;
414
+ const age = Date.now() - entry.createdAt;
358
415
  if (age < maxAge + staleIfError) {
359
416
  console.warn(
360
417
  `[cachedLoader] ${name}: origin error, serving stale entry (age=${Math.round(age / 1000)}s, sie=${Math.round(staleIfError / 1000)}s)`,
@@ -374,7 +431,6 @@ export function createCachedLoader<TProps, TResult>(
374
431
  };
375
432
  }
376
433
 
377
-
378
434
  // ---------------------------------------------------------------------------
379
435
  // Module loader dedup (the `@decocms/apps` cache/cacheKey convention)
380
436
  //
@@ -404,11 +460,12 @@ export function createCachedLoaderFromModule<TProps, TResult>(
404
460
  name: string,
405
461
  mod: LoaderModule<TProps, TResult>,
406
462
  ): (props: TProps, req?: Request) => Promise<TResult> {
407
- const policy: CachePolicy = typeof mod.cache === "string"
408
- ? mod.cache
409
- : mod.cache && typeof mod.cache === "object"
410
- ? "stale-while-revalidate"
411
- : "no-store";
463
+ const policy: CachePolicy =
464
+ typeof mod.cache === "string"
465
+ ? mod.cache
466
+ : mod.cache && typeof mod.cache === "object"
467
+ ? "stale-while-revalidate"
468
+ : "no-store";
412
469
 
413
470
  // Only `stale-while-revalidate` (or `{ maxAge }`) opts into dedup — matching
414
471
  // `@decocms/apps`/deco, where `no-store` (the default) and `no-cache` both
@@ -432,7 +489,7 @@ export function createCachedLoaderFromModule<TProps, TResult>(
432
489
  // Explicit null → the loader declared this call uncacheable: run fresh.
433
490
  if (keyPart === null) return mod.default(props, req);
434
491
 
435
- const key = `${BUILD}::${name}::${keyPart}`;
492
+ const key = cache.key(`${BUILD}::${name}::${keyPart}`);
436
493
  const existing = moduleInflight.get(key) as Promise<TResult> | undefined;
437
494
  if (existing) return existing;
438
495
 
@@ -459,9 +516,7 @@ export function createLoaderEntry<TProps = any, TResult = any>(
459
516
  // first-calls — exactly the N-sections-per-render case — share one import
460
517
  // instead of racing into N. Reset on failure so a transient import error can
461
518
  // retry rather than poisoning the entry forever.
462
- let wrappedPromise:
463
- | Promise<(props: TProps, req?: Request) => Promise<TResult>>
464
- | undefined;
519
+ let wrappedPromise: Promise<(props: TProps, req?: Request) => Promise<TResult>> | undefined;
465
520
  return (props: TProps, req?: Request): Promise<TResult> => {
466
521
  if (!wrappedPromise) {
467
522
  wrappedPromise = importFn()
@@ -478,15 +533,13 @@ export function createLoaderEntry<TProps = any, TResult = any>(
478
533
  /**
479
534
  * Clear all cached entries in THIS isolate. Used both by decofile hot-reload
480
535
  * (`@decocms/blocks-admin`) and by the `POST /_cache/purge-loaders` route — an
481
- * escape hatch to invalidate immediately (e.g. after an out-of-band Magento/
482
- * catalog sync) without waiting out the TTL. Per-isolate: the route must be hit
483
- * for every isolate; a redeploy replaces isolates wholesale. Bumps the cache
536
+ * memory eviction hook. Shared storage entries expire by TTL and may hydrate
537
+ * memory again. Deployment/content scopes prevent reuse across versions. Bumps the cache
484
538
  * generation so any loader in flight at purge time won't repopulate a cleared
485
539
  * entry with pre-purge data.
486
540
  */
487
541
  export function clearLoaderCache() {
488
542
  cache.clear();
489
- cacheBytes = 0;
490
543
  inflightRequests.clear();
491
544
  moduleInflight.clear();
492
545
  cacheGeneration++;
@@ -497,7 +550,7 @@ export function getLoaderCacheStats() {
497
550
  return {
498
551
  entries: cache.size,
499
552
  inflight: inflightRequests.size,
500
- estimatedBytes: cacheBytes,
501
- maxBytes: MAX_CACHE_BYTES,
553
+ estimatedBytes: cache.estimatedBytes,
554
+ maxBytes: maxCacheBytes,
502
555
  };
503
556
  }
package/src/sdk/crypto.ts CHANGED
@@ -15,6 +15,8 @@
15
15
  * const apiKey = await resolveSecret(block.apiKey, "RESEND_API_KEY");
16
16
  */
17
17
 
18
+ import { getRuntimeEnv } from "./otelAdapters";
19
+
18
20
  const textDecoder = new TextDecoder();
19
21
  const textEncoder = new TextEncoder();
20
22
 
@@ -150,10 +152,13 @@ export async function resolveSecret(
150
152
  }
151
153
 
152
154
  /**
153
- * Get an environment variable, checking process.env first, then .dev.vars file.
155
+ * Get an environment variable, checking process.env first, then .dev.vars file,
156
+ * then the Cloudflare Workers `env` binding stashed in RequestContext.
154
157
  * Cloudflare Workers dev mode stores env vars in .dev.vars but they're only
155
158
  * accessible via the `env` binding inside request handlers. During setup.ts
156
- * (module-level init), we need to read the file directly.
159
+ * (module-level init), we need to read the file directly. In production/preview
160
+ * there is no .dev.vars and no process.env — the only source is the `env` object
161
+ * passed to the fetch handler, which workerEntry.ts stashes via setRuntimeEnv().
157
162
  */
158
163
  function getEnvVar(name: string): string | undefined {
159
164
  // 1. process.env (works in Node, may work in Workers with nodejs_compat)
@@ -181,5 +186,14 @@ function getEnvVar(name: string): string | undefined {
181
186
  // fs not available (e.g., pure Worker runtime) — ignore
182
187
  }
183
188
 
189
+ // 3. CF Workers `env` binding, stashed per-request in RequestContext by
190
+ // workerEntry.ts's setRuntimeEnv(env). This is the ONLY source in a real
191
+ // Workers production/preview deploy (no process.env, no .dev.vars). Returns
192
+ // undefined at module-init time (no active request) — that's why apps are
193
+ // re-configured on the first request via reconfigureAppsOnce().
194
+ const runtimeEnv = getRuntimeEnv();
195
+ const v = runtimeEnv?.[name];
196
+ if (typeof v === "string" && v) return v;
197
+
184
198
  return undefined;
185
199
  }
@@ -0,0 +1,52 @@
1
+ /**
2
+ * deepOmit — immutably remove dotted paths from an object tree.
3
+ *
4
+ * Used by section `renderJson` projections to trim a section's props before it
5
+ * is serialized for the mobile app (the ?renderJson page-as-JSON path):
6
+ *
7
+ * ```ts
8
+ * export const renderJson = (props: SectionProps<typeof loader>) =>
9
+ * deepOmit(props, "storeConfig", "page.seo", "page.productsMap.*.hasFetchedSimilars");
10
+ * ```
11
+ *
12
+ * Semantics:
13
+ * - Top-level key: `deepOmit(o, "seoProps")`.
14
+ * - Nested path (dot-separated): `deepOmit(o, "page.seo")`.
15
+ * - Wildcard `*`: fans the remaining path over every array element OR record
16
+ * value — `"page.productsMap.*.hasFetchedSimilars"` strips `hasFetchedSimilars`
17
+ * from every value of `productsMap`.
18
+ * - Arrays without an explicit `*`: the path auto-applies to each element and the
19
+ * array shape is preserved.
20
+ * - Missing key: a no-op — never fabricates an `undefined` branch.
21
+ *
22
+ * Pure: spreads/copies at each level, never mutates the input.
23
+ */
24
+ const omitAtPath = (obj: unknown, parts: string[]): unknown => {
25
+ if (!obj || typeof obj !== "object" || parts.length === 0) return obj;
26
+ const [key, ...rest] = parts;
27
+
28
+ // `*` fans the remaining path out over every array element / record value.
29
+ if (key === "*") {
30
+ if (Array.isArray(obj)) return obj.map((v) => omitAtPath(v, rest));
31
+ return Object.fromEntries(
32
+ Object.entries(obj as Record<string, unknown>).map(([k, v]) => [k, omitAtPath(v, rest)]),
33
+ );
34
+ }
35
+ // Preserve array shape: apply the same path to each element.
36
+ if (Array.isArray(obj)) return obj.map((v) => omitAtPath(v, parts));
37
+
38
+ const current = obj as Record<string, unknown>;
39
+ if (rest.length === 0) {
40
+ const copy = { ...current };
41
+ delete copy[key];
42
+ return copy;
43
+ }
44
+ if (!(key in current)) return current; // absent path = no-op, never creates undefined branches
45
+ return { ...current, [key]: omitAtPath(current[key], rest) };
46
+ };
47
+
48
+ export const deepOmit = <T extends object>(obj: T, ...paths: string[]): T => {
49
+ let result: unknown = obj;
50
+ for (const path of paths) result = omitAtPath(result, path.split("."));
51
+ return result as T;
52
+ };
@@ -26,7 +26,7 @@ export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string {
26
26
  return btoa(bin);
27
27
  }
28
28
 
29
- export function decodeBase64(b64: string): Uint8Array {
29
+ export function decodeBase64(b64: string): Uint8Array<ArrayBuffer> {
30
30
  const bin = atob(b64);
31
31
  const out = new Uint8Array(bin.length);
32
32
  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
@@ -34,10 +34,7 @@ export function decodeBase64(b64: string): Uint8Array {
34
34
  }
35
35
 
36
36
  export function encodeBase64Url(data: ArrayBuffer | Uint8Array | string): string {
37
- return encodeBase64(data)
38
- .replace(/\+/g, "-")
39
- .replace(/\//g, "_")
40
- .replace(/=+$/, "");
37
+ return encodeBase64(data).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
41
38
  }
42
39
 
43
40
  export function decodeBase64Url(b64url: string): Uint8Array {