@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
@@ -0,0 +1,314 @@
1
+ /**
2
+ * Generic variant resolution — sticky, self-healing, N-way, and independent of
3
+ * where the variant list comes from.
4
+ *
5
+ * ## What this is
6
+ *
7
+ * Two layers, deliberately separable:
8
+ *
9
+ * 1. {@link stickyDecide} — the assignment *policy*, extracted from
10
+ * `cms/resolve.ts`'s `evaluateVariantRule`: reuse the decision already made
11
+ * this request, else honour the `deco_segment` cookie while its fingerprint
12
+ * still matches, else roll fresh. Pure, synchronous, no CMS, no KV, no
13
+ * cookies. The CMS multivariate path and this module both call it, so the
14
+ * two cannot drift.
15
+ * 2. {@link resolveExperimentVariant} — the N-way experiment on top of it:
16
+ * reads config from KV, draws from a weight vector, records the assignment
17
+ * for the framework to persist into `deco_segment`.
18
+ *
19
+ * ## Self-healing re-roll
20
+ *
21
+ * The stored fingerprint is a hash of the *weight vector*. Change a weight (a
22
+ * ramp stage advancing 5% to 10%) and every stored assignment's fingerprint
23
+ * goes stale, so each visitor is re-rolled exactly once and then re-sticks on
24
+ * the new weights. The control plane never has to know this mechanic exists —
25
+ * hence "no fingerprint field" in the published config.
26
+ *
27
+ * ## Why not `sdk/abTesting.ts`
28
+ *
29
+ * That is a binary `"worker" | "fallback"` whole-request proxy for the
30
+ * migration period. Its bucket type, cookie, and fallback machinery are all
31
+ * two-way-specific. Only its `kv.get<T>(key, "json")` shape is borrowed here.
32
+ */
33
+
34
+ import { djb2 } from "./djb2";
35
+ import { parseSegmentCookie, SEGMENT_COOKIE, type StoredFlag } from "./flags";
36
+ import { getRuntimeEnv } from "./otelAdapters";
37
+ import { RequestContext } from "./requestContext";
38
+
39
+ // ---------------------------------------------------------------------------
40
+ // Layer 1 — the extracted sticky/re-roll core
41
+ // ---------------------------------------------------------------------------
42
+
43
+ /** Outcome of a sticky decision. `isFresh` is true when it was rolled now. */
44
+ export interface StickyDecision<V> {
45
+ value: V;
46
+ isFresh: boolean;
47
+ }
48
+
49
+ /**
50
+ * Sticky assignment with self-healing re-roll, over any value type.
51
+ *
52
+ * Precedence: a decision already recorded this request (so every resolve pass
53
+ * agrees) then the stored decision, if its fingerprint still matches, then a
54
+ * fresh roll. `fingerprint === -1` on the stored decision marks a classic-deco
55
+ * segment written without the blocks extension: honour it rather than
56
+ * re-rolling, or every legacy visitor churns on first contact.
57
+ *
58
+ * @param name Cohort identity — matcher block name or experiment key.
59
+ * @param fingerprint Current config fingerprint; a mismatch re-rolls once.
60
+ * @param recorded Decisions already made this request (mutated: the new one
61
+ * is pushed onto it). Undefined disables both dedupe and
62
+ * persistence.
63
+ * @param stored Decisions parsed from the visitor's cookie.
64
+ * @param roll Draws a fresh value. Called at most once.
65
+ * @param accepts Guards a stored value that is no longer valid — e.g. a
66
+ * variant deleted from the config. Rejected means re-roll.
67
+ */
68
+ export function stickyDecide<V extends boolean | string>({
69
+ name,
70
+ fingerprint,
71
+ recorded,
72
+ stored,
73
+ roll,
74
+ accepts,
75
+ }: {
76
+ name: string;
77
+ fingerprint: number;
78
+ recorded: StoredFlag[] | undefined;
79
+ stored: StoredFlag[];
80
+ roll: () => V;
81
+ accepts?: (value: V) => boolean;
82
+ }): StickyDecision<V> {
83
+ const already = recorded?.find((f) => f.name === name && f.pct === fingerprint);
84
+ if (already) return { value: already.value as V, isFresh: false };
85
+
86
+ const prev = stored.find((f) => f.name === name);
87
+ const usable =
88
+ prev !== undefined &&
89
+ (prev.pct === -1 || prev.pct === fingerprint) &&
90
+ (!accepts || accepts(prev.value as V));
91
+
92
+ const value = usable ? (prev.value as V) : roll();
93
+ recorded?.push({ name, value, pct: fingerprint });
94
+ return { value, isFresh: !usable };
95
+ }
96
+
97
+ // ---------------------------------------------------------------------------
98
+ // Layer 2 — experiments
99
+ // ---------------------------------------------------------------------------
100
+
101
+ /** One arm of an experiment, as published by the control plane. */
102
+ export interface ExperimentVariant<P = unknown> {
103
+ id: string;
104
+ /** Integer share of traffic. Weights across an experiment must sum to 100. */
105
+ weight: number;
106
+ /** Opaque to the runtime — forwarded to the caller untouched. */
107
+ payload: P;
108
+ }
109
+
110
+ /** An active experiment. */
111
+ export interface ExperimentDefinition<P = unknown> {
112
+ key: string;
113
+ variants: ExperimentVariant<P>[];
114
+ }
115
+
116
+ /**
117
+ * Frozen contract 1 — the document written to KV by the control plane's
118
+ * `EXPERIMENT_ACTIVE_PUBLISH`, keyed by hostname. Only *active* experiments
119
+ * appear: status and time-window logic live in the control plane, so the
120
+ * runtime does no date math and parses no status.
121
+ */
122
+ export interface ExperimentConfig<P = unknown> {
123
+ version: number;
124
+ experiments: ExperimentDefinition<P>[];
125
+ }
126
+
127
+ /** Frozen contract 2 — what a caller gets back. */
128
+ export interface ResolvedVariant<P = unknown> {
129
+ experimentKey: string;
130
+ variantId: string;
131
+ payload: P;
132
+ /** True when assigned on this request — a first visit or a re-roll. */
133
+ isFresh: boolean;
134
+ }
135
+
136
+ /** The slice of a KV namespace this module uses (mirrors `abTesting.ts`). */
137
+ interface ExperimentKV {
138
+ get<T>(key: string, type: "json"): Promise<T | null>;
139
+ }
140
+
141
+ /** Default Workers binding holding the published config. */
142
+ export const EXPERIMENTS_KV_BINDING = "EXPERIMENTS_KV";
143
+
144
+ /** Bag key for the per-request config read, so N loaders share one KV get. */
145
+ const CONFIG_BAG_KEY = "deco:experiments:config";
146
+ /** Bag key for assignments made this request, drained by the cookie writer. */
147
+ const ASSIGNMENTS_BAG_KEY = "deco:experiments:assignments";
148
+
149
+ /**
150
+ * Fingerprint of a weight vector. Order-independent (the control plane may
151
+ * reorder variants without meaning to re-roll anyone) and never `-1`, which is
152
+ * reserved for "legacy cookie, no fingerprint".
153
+ */
154
+ export function weightsFingerprint(variants: ExperimentVariant[]): number {
155
+ const vector = [...variants]
156
+ .map((v) => `${v.id}:${v.weight}`)
157
+ .sort()
158
+ .join("|");
159
+ return djb2(vector) % 1_000_000;
160
+ }
161
+
162
+ /**
163
+ * Draw a variant id from the weight vector. `rand` is a 0-1 sample.
164
+ *
165
+ * Weights are treated as shares of their own total rather than of a hardcoded
166
+ * 100, so a config that violates the sum-to-100 contract still splits traffic
167
+ * in the intended proportions instead of collapsing onto the first arm.
168
+ */
169
+ export function pickWeightedVariant(variants: ExperimentVariant[], rand: number): string {
170
+ const total = variants.reduce((sum, v) => sum + Math.max(0, v.weight), 0);
171
+ if (total <= 0) return variants[0].id;
172
+
173
+ let cursor = rand * total;
174
+ for (const v of variants) {
175
+ cursor -= Math.max(0, v.weight);
176
+ if (cursor < 0) return v.id;
177
+ }
178
+ return variants[variants.length - 1].id;
179
+ }
180
+
181
+ /**
182
+ * Read the published config for a hostname. Mirrors `abTesting.ts`'s
183
+ * `kv.get<T>(key, "json")` shape. Returns null when the binding is absent, the
184
+ * key is unset, or the document is unusable — every one of which must mean
185
+ * "no experiment", never a thrown request.
186
+ */
187
+ export async function readExperimentConfig<P = unknown>(
188
+ kv: ExperimentKV | undefined,
189
+ hostname: string,
190
+ ): Promise<ExperimentConfig<P> | null> {
191
+ if (!kv) return null;
192
+ try {
193
+ const config = await kv.get<ExperimentConfig<P>>(hostname, "json");
194
+ return Array.isArray(config?.experiments) ? config : null;
195
+ } catch {
196
+ return null;
197
+ }
198
+ }
199
+
200
+ /**
201
+ * Explicit inputs, for tests and for callers outside a request context.
202
+ * Omitted fields fall back to the ambient {@link RequestContext} + Workers env.
203
+ */
204
+ export interface ExperimentContext<P = unknown> {
205
+ /** Skips the KV read entirely when provided. */
206
+ config?: ExperimentConfig<P> | null;
207
+ kv?: ExperimentKV;
208
+ hostname?: string;
209
+ /** Raw `deco_segment` cookie value from the request. */
210
+ segmentCookie?: string;
211
+ /** Assignment sink; the cookie writer drains it. */
212
+ assignments?: StoredFlag[];
213
+ /** Injectable RNG — tests pass a fixed sample. */
214
+ random?: () => number;
215
+ }
216
+
217
+ /**
218
+ * Resolve this visitor's variant for `experimentKey`.
219
+ *
220
+ * Returns null when no active experiment matches — no config published, the
221
+ * key absent, or the experiment has no variants. Callers must behave exactly
222
+ * as they do today on null.
223
+ *
224
+ * The assignment is recorded for persistence into the existing `deco_segment`
225
+ * cookie under `experimentKey` (frozen contract 4); **the caller does not set
226
+ * cookies itself**. Because it lands in that cookie, the CDN cache-key folding
227
+ * already wired in `tanstack/sdk/workerEntry.ts` (`segmentCacheToken` to
228
+ * `__abf`) covers it with no change, and analytics that already read
229
+ * `deco_segment` see it for free.
230
+ *
231
+ * @example
232
+ * ```ts
233
+ * const variant = await resolveExperimentVariant<{ collectionId: string }>("plp-ranking");
234
+ * if (!variant) return vtexProductListingPage(props, req, ctx); // unchanged path
235
+ * props.selectedFacets = [
236
+ * ...(props.selectedFacets ?? []),
237
+ * { key: "productClusterIds", value: variant.payload.collectionId },
238
+ * ];
239
+ * ```
240
+ */
241
+ export async function resolveExperimentVariant<P = unknown>(
242
+ experimentKey: string,
243
+ ctx: ExperimentContext<P> = {},
244
+ ): Promise<ResolvedVariant<P> | null> {
245
+ const config = ctx.config !== undefined ? ctx.config : await loadConfig<P>(ctx);
246
+ const experiment = config?.experiments.find((e) => e.key === experimentKey);
247
+ if (!experiment?.variants?.length) return null;
248
+
249
+ const stored = parseSegmentCookie(ctx.segmentCookie ?? ambientSegmentCookie());
250
+ const random = ctx.random ?? Math.random;
251
+ const { value: variantId, isFresh } = stickyDecide<string>({
252
+ name: experimentKey,
253
+ fingerprint: weightsFingerprint(experiment.variants),
254
+ recorded: ctx.assignments ?? ambientAssignments(),
255
+ stored,
256
+ roll: () => pickWeightedVariant(experiment.variants, random()),
257
+ // A variant retired mid-flight leaves visitors holding a dead id. Re-roll
258
+ // them onto a live arm instead of returning a payload that no longer exists.
259
+ accepts: (id) => experiment.variants.some((v) => v.id === id),
260
+ });
261
+
262
+ const variant = experiment.variants.find((v) => v.id === variantId) ?? experiment.variants[0];
263
+ return { experimentKey, variantId: variant.id, payload: variant.payload, isFresh };
264
+ }
265
+
266
+ // ---------------------------------------------------------------------------
267
+ // Ambient request wiring
268
+ // ---------------------------------------------------------------------------
269
+
270
+ /**
271
+ * One KV read per request, shared by every caller, memoised on the in-flight
272
+ * promise so concurrent section loaders coalesce instead of racing.
273
+ */
274
+ function loadConfig<P>(ctx: ExperimentContext<P>): Promise<ExperimentConfig<P> | null> {
275
+ const kv = ctx.kv ?? (getRuntimeEnv()?.[EXPERIMENTS_KV_BINDING] as ExperimentKV | undefined);
276
+ const hostname = ctx.hostname ?? ambientHostname();
277
+ if (!kv || !hostname) return Promise.resolve(null);
278
+
279
+ const cached = RequestContext.getBag<Promise<ExperimentConfig<P> | null>>(CONFIG_BAG_KEY);
280
+ if (cached) return cached;
281
+
282
+ const pending = readExperimentConfig<P>(kv, hostname);
283
+ RequestContext.setBag(CONFIG_BAG_KEY, pending);
284
+ return pending;
285
+ }
286
+
287
+ function ambientHostname(): string | undefined {
288
+ const request = RequestContext.current?.request;
289
+ return request ? new URL(request.url).hostname : undefined;
290
+ }
291
+
292
+ function ambientSegmentCookie(): string | undefined {
293
+ const cookies = RequestContext.current?.request?.headers.get("cookie");
294
+ if (!cookies) return undefined;
295
+ const match = cookies.match(new RegExp(`(?:^|;\\s*)${SEGMENT_COOKIE}=([^;]+)`));
296
+ return match?.[1];
297
+ }
298
+
299
+ function ambientAssignments(): StoredFlag[] | undefined {
300
+ if (!RequestContext.current) return undefined;
301
+ const existing = RequestContext.getBag<StoredFlag[]>(ASSIGNMENTS_BAG_KEY);
302
+ if (existing) return existing;
303
+ const fresh: StoredFlag[] = [];
304
+ RequestContext.setBag(ASSIGNMENTS_BAG_KEY, fresh);
305
+ return fresh;
306
+ }
307
+
308
+ /**
309
+ * Assignments recorded this request, for the framework's cookie writer.
310
+ * Empty when nothing was assigned — callers must not re-issue the cookie then.
311
+ */
312
+ export function takeExperimentAssignments(): StoredFlag[] {
313
+ return RequestContext.getBag<StoredFlag[]>(ASSIGNMENTS_BAG_KEY) ?? [];
314
+ }
@@ -0,0 +1,269 @@
1
+ /**
2
+ * Shared SWR fetch cache for commerce API responses.
3
+ *
4
+ * Provides in-flight deduplication + stale-while-revalidate + stale-if-error
5
+ * for server-side GET requests, keyed by full URL string. Ported from the
6
+ * VTEX app's `fetchCache.ts` (itself inspired by deco-cx/deco
7
+ * `runtime/fetch/fetchCache.ts`) and generalized so every commerce app
8
+ * (VTEX, Magento, Shopify, ...) shares ONE implementation instead of each
9
+ * rolling its own uninstrumented copy.
10
+ *
11
+ * **Why this lives in `@decocms/blocks/sdk` (the chokepoint):** cache hit/miss
12
+ * telemetry only becomes automatic when a single shared util emits it. Each
13
+ * cache instance calls {@link recordCacheMetric} with `layer: "swr"` on every
14
+ * decision branch, so any app that routes upstream GETs through
15
+ * {@link createFetchCache} lands hit/miss/stale in ClickHouse for free — no
16
+ * per-app wiring. The metric is a no-op when no meter is configured (dev,
17
+ * tests), so there is zero cost off the instrumented path.
18
+ *
19
+ * **Provider isolation:** every {@link createFetchCache} call owns its own
20
+ * bounded memory tier and in-flight Map. Shared storage keys include the
21
+ * provider name, so VTEX / Magento / Shopify entries never collide. The `provider` string rides on the `provider` metric label so
22
+ * dashboards can slice hit ratio per backend.
23
+ *
24
+ * Note on why the SWR cache — not `createInstrumentedFetch` — must emit the
25
+ * hit/miss counter: on a HIT the cache returns BEFORE invoking `doFetch`, so
26
+ * the instrumented fetch (and its `http.client.request.duration` histogram)
27
+ * never runs. Hit ratio can only be measured here.
28
+ */
29
+
30
+ import { type CacheDecision, recordCacheMetric } from "../middleware/observability";
31
+ import { cacheBackground, createCacheStore, getCacheStorageContext } from "./cacheStorage";
32
+
33
+ /** Fresh-TTL (ms) by HTTP status class. See {@link FetchCacheConfig}. */
34
+ export interface FreshTtlByStatus {
35
+ /** 2xx — how long a success body stays fresh. */
36
+ success: number;
37
+ /** 404 — how long a not-found stays fresh (kept short on purpose). */
38
+ notFound: number;
39
+ /** 5xx — a server error is never treated as a good cache hit (use 0). */
40
+ serverError: number;
41
+ }
42
+
43
+ export interface FetchCacheConfig {
44
+ /**
45
+ * Backend name — `vtex` / `magento` / `shopify` / ... Emitted as
46
+ * `deco.cache.profile` on the `deco.cache.requests` metric so dashboards can
47
+ * break down SWR hit ratio per provider. Also namespaces the instance's
48
+ * in-memory Maps (each instance is already isolated, but this keeps the
49
+ * telemetry label meaningful).
50
+ */
51
+ provider: string;
52
+ /** Max distinct cache keys kept in memory; oldest `createdAt` evicted first. */
53
+ maxEntries: number;
54
+ /** Fresh-TTL (ms) by status class. */
55
+ freshTtlMs: FreshTtlByStatus;
56
+ /**
57
+ * Stale-if-error window (ms): how long PAST the freshness TTL a last-good 2xx
58
+ * entry may still be served while the origin is failing. Set to 0 to disable
59
+ * stale serving.
60
+ */
61
+ staleIfErrorMs: number;
62
+ /**
63
+ * Inflight-slot backstop timeout (ms). Bounds how long a single hung
64
+ * `fetch()` can hold a dedup entry alive. MUST stay ABOVE any per-call
65
+ * timeout the underlying fetch owns — this is a last-resort leak backstop,
66
+ * not the primary timeout.
67
+ */
68
+ inflightBackstopMs: number;
69
+ }
70
+
71
+ interface CacheEntry {
72
+ body: unknown;
73
+ status: number;
74
+ createdAt: number;
75
+ refreshing: boolean;
76
+ }
77
+
78
+ export interface FetchCacheOptions {
79
+ /** Custom fresh TTL in ms. If provided, overrides status-based TTL. */
80
+ ttl?: number;
81
+ /**
82
+ * Stale-if-error window in ms for this call. Defaults to the instance's
83
+ * {@link FetchCacheConfig.staleIfErrorMs}. Set to 0 to disable stale serving.
84
+ */
85
+ sieMs?: number;
86
+ }
87
+
88
+ export interface FetchCache {
89
+ /**
90
+ * Wrap a GET fetch call with SWR caching + in-flight dedup. Returns the
91
+ * parsed JSON body, or `null` for cacheable non-2xx responses (e.g. 404).
92
+ * 5xx responses throw so the caller can handle them explicitly.
93
+ */
94
+ fetchWithCache<T>(
95
+ cacheKey: string,
96
+ doFetch: () => Promise<Response>,
97
+ opts?: FetchCacheOptions,
98
+ ): Promise<T | null>;
99
+ /** Drop all entries + inflight slots (mainly for tests). */
100
+ clear(): void;
101
+ /** Diagnostics: current entry / inflight counts. */
102
+ getStats(): { entries: number; inflight: number };
103
+ }
104
+
105
+ /**
106
+ * Race a Promise against a timeout so callers' `.finally()` always runs.
107
+ * Critical for evicting the inflight Map entry when a `fetch()` hangs —
108
+ * without this, a never-settling Promise leaks the Map slot forever and every
109
+ * subsequent request for the same key joins the zombie Promise.
110
+ */
111
+ function withTimeout<T>(work: Promise<T>, ms: number, label: string): Promise<T> {
112
+ let timer: ReturnType<typeof setTimeout> | undefined;
113
+ const timeout = new Promise<never>((_, reject) => {
114
+ timer = setTimeout(() => {
115
+ reject(new Error(`${label} timed out after ${ms}ms`));
116
+ }, ms);
117
+ });
118
+ return Promise.race([work, timeout]).finally(() => {
119
+ clearTimeout(timer);
120
+ });
121
+ }
122
+
123
+ /**
124
+ * Create an isolated SWR fetch cache instance for one provider.
125
+ *
126
+ * @example
127
+ * const cache = createFetchCache({ provider: "vtex", ...VTEX_KNOBS });
128
+ * const body = await cache.fetchWithCache(url, () => fetch(url));
129
+ */
130
+ export function createFetchCache(config: FetchCacheConfig): FetchCache {
131
+ const { provider, maxEntries, freshTtlMs, staleIfErrorMs, inflightBackstopMs } = config;
132
+
133
+ const store = createCacheStore<CacheEntry>(`fetch:${provider}`, maxEntries);
134
+ const inflight = new Map<string, Promise<CacheEntry>>();
135
+
136
+ function freshTtlForStatus(status: number): number {
137
+ if (status >= 200 && status < 300) return freshTtlMs.success;
138
+ if (status === 404) return freshTtlMs.notFound;
139
+ if (status >= 500) return freshTtlMs.serverError;
140
+ return 0;
141
+ }
142
+
143
+ // Single attempt on purpose — the underlying fetch (resilience layer) owns
144
+ // retries/backoff/breaker. Retrying here would multiply upstream calls and
145
+ // re-enter the breaker too fast.
146
+ async function executeFetch(url: string, doFetch: () => Promise<Response>): Promise<CacheEntry> {
147
+ const response = await doFetch();
148
+ if (response.status >= 500) {
149
+ throw new Error(`fetchWithCache: ${response.status} ${response.statusText} — ${url}`);
150
+ }
151
+ const body = response.ok ? await response.json() : null;
152
+ return { body, status: response.status, createdAt: Date.now(), refreshing: false };
153
+ }
154
+
155
+ function emit(decision: CacheDecision) {
156
+ // `hit` is true for every branch that avoids a foreground upstream fetch
157
+ // (fresh, dedup-join, stale-serve); MISS is the only non-hit. The backend
158
+ // rides on the dedicated `provider` label (NOT `profile`, which the edge
159
+ // layer reserves for page-type) so dashboards don't blend the two.
160
+ recordCacheMetric(decision !== "MISS", undefined, decision, "swr", provider);
161
+ }
162
+
163
+ async function fetchWithCache<T>(
164
+ cacheKey: string,
165
+ doFetch: () => Promise<Response>,
166
+ opts?: FetchCacheOptions,
167
+ ): Promise<T | null> {
168
+ cacheKey = store.key(cacheKey);
169
+ const entry = getCacheStorageContext()?.storage
170
+ ? await store.read(cacheKey)
171
+ : store.get(cacheKey);
172
+ const now = Date.now();
173
+
174
+ if (entry) {
175
+ const maxAge = opts?.ttl ?? freshTtlForStatus(entry.status);
176
+ const age = now - entry.createdAt;
177
+ const isStale = age > maxAge;
178
+
179
+ if (!isStale) {
180
+ emit("HIT");
181
+ return Promise.resolve(entry.body as T | null);
182
+ }
183
+
184
+ // Beyond the stale-if-error window the last-good entry is too old to keep
185
+ // serving during an outage: drop it and fall through to a foreground
186
+ // refetch (cold path, counted as MISS there). On a healthy origin this is
187
+ // never reached because the background refresh keeps resetting createdAt.
188
+ const sieMs = opts?.sieMs ?? staleIfErrorMs;
189
+ const tooStale = age > maxAge + sieMs;
190
+
191
+ if (!tooStale) {
192
+ if (!entry.refreshing) {
193
+ entry.refreshing = true;
194
+ // Background refresh: no retry — stale data is already being served.
195
+ cacheBackground(
196
+ withTimeout(
197
+ executeFetch(cacheKey, doFetch),
198
+ inflightBackstopMs,
199
+ `fetchCache stale-refresh ${cacheKey}`,
200
+ )
201
+ .then((fresh) => {
202
+ const ttl = opts?.ttl ?? freshTtlForStatus(fresh.status);
203
+ const existingWasSuccess = entry.status >= 200 && entry.status < 300;
204
+ const freshIsError = fresh.status >= 400;
205
+ const wouldDowngrade = existingWasSuccess && freshIsError;
206
+ if (ttl > 0 && !wouldDowngrade) {
207
+ store.set(
208
+ cacheKey,
209
+ fresh,
210
+ fresh.createdAt + ttl + (opts?.sieMs ?? staleIfErrorMs),
211
+ );
212
+ } else {
213
+ entry.refreshing = false;
214
+ }
215
+ })
216
+ .catch(() => {
217
+ entry.refreshing = false;
218
+ }),
219
+ );
220
+ }
221
+ // Serve last-good within the SIE window: this is the stale-while-
222
+ // revalidate serve.
223
+ emit("STALE-HIT");
224
+ return Promise.resolve(entry.body as T | null);
225
+ }
226
+
227
+ store.delete(cacheKey);
228
+ // fall through to the cold path below with the dead entry removed
229
+ }
230
+
231
+ const existing = inflight.get(cacheKey);
232
+ if (existing) {
233
+ // Joined an in-flight upstream fetch — no upstream call of our own.
234
+ emit("HIT");
235
+ return existing.then((e) => e.body as T | null);
236
+ }
237
+
238
+ // Cold miss: run the loader. Wrap with a timeout so `.finally()` always
239
+ // evicts the inflight slot even if `executeFetch` never settles.
240
+ emit("MISS");
241
+ const promise = withTimeout(
242
+ executeFetch(cacheKey, doFetch),
243
+ inflightBackstopMs,
244
+ `fetchCache ${cacheKey}`,
245
+ )
246
+ .then((fresh) => {
247
+ const ttl = opts?.ttl ?? freshTtlForStatus(fresh.status);
248
+ if (ttl > 0) {
249
+ store.set(cacheKey, fresh, fresh.createdAt + ttl + (opts?.sieMs ?? staleIfErrorMs));
250
+ }
251
+ return fresh;
252
+ })
253
+ .finally(() => inflight.delete(cacheKey));
254
+
255
+ inflight.set(cacheKey, promise);
256
+ return promise.then((e) => e.body as T | null);
257
+ }
258
+
259
+ return {
260
+ fetchWithCache,
261
+ clear() {
262
+ store.clear();
263
+ inflight.clear();
264
+ },
265
+ getStats() {
266
+ return { entries: store.size, inflight: inflight.size };
267
+ },
268
+ };
269
+ }
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Default network-level timeout for outbound `fetch()` calls.
3
+ *
4
+ * Background: nothing in `@decocms/blocks` previously bounded how long an
5
+ * outbound fetch could hang. `withInflightTimeout` (see `./inflightTimeout.ts`)
6
+ * only frees the module-level dedup Map slot when a wrapped Promise never
7
+ * settles — it abandons the underlying fetch rather than aborting it, so the
8
+ * TCP connection (and the isolate memory pinned to it) stays alive until the
9
+ * runtime kills the request. This module fixes the root cause: actually abort
10
+ * the request via `AbortSignal.timeout`, composed with any caller-supplied
11
+ * signal so callers that already do their own cancellation aren't overridden.
12
+ */
13
+
14
+ /** Default per-request timeout for outbound fetch calls. */
15
+ export const DEFAULT_FETCH_TIMEOUT_MS = 10_000;
16
+
17
+ /**
18
+ * Named alias for `typeof fetch`. Prefer this over repeating `typeof fetch`
19
+ * in signatures — packages that ban the bare `fetch` global (see this
20
+ * monorepo's `biome.json` `noRestrictedGlobals` override) flag `typeof fetch`
21
+ * too, since it's the same identifier reference; `FetchFn` sidesteps that.
22
+ */
23
+ export type FetchFn = typeof fetch;
24
+
25
+ /**
26
+ * Combine a caller-supplied `AbortSignal` (if any) with a timeout signal, so
27
+ * neither cancellation source is lost. Pass `timeoutMs <= 0` or
28
+ * non-finite to opt out of the timeout entirely (e.g. long-lived streaming
29
+ * requests) while still honoring the caller's own signal.
30
+ */
31
+ export function withTimeoutSignal(
32
+ signal: AbortSignal | undefined | null,
33
+ timeoutMs: number,
34
+ ): AbortSignal | undefined {
35
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return signal ?? undefined;
36
+ const timeoutSignal = AbortSignal.timeout(timeoutMs);
37
+ return signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
38
+ }
39
+
40
+ /**
41
+ * Wrap a `fetch` implementation so every call is aborted after `timeoutMs`
42
+ * unless it settles first. Use directly at ad-hoc fetch call sites that
43
+ * don't go through `createInstrumentedFetch` (e.g. one-off API clients).
44
+ *
45
+ * When `baseFetch` is omitted, `globalThis.fetch` is resolved on every call
46
+ * (not captured once at wrap time) so tests that swap `globalThis.fetch`
47
+ * with a mock after this module loads still get intercepted.
48
+ */
49
+ export function withFetchTimeout(
50
+ baseFetch?: typeof fetch,
51
+ timeoutMs: number = DEFAULT_FETCH_TIMEOUT_MS,
52
+ ): typeof fetch {
53
+ return (input, init) =>
54
+ (baseFetch ?? globalThis.fetch)(input, {
55
+ ...init,
56
+ signal: withTimeoutSignal(init?.signal, timeoutMs),
57
+ });
58
+ }