@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.
- package/bin/deco.js +13 -0
- package/package.json +39 -3
- package/src/cms/applySectionConventions.ts +26 -2
- package/src/cms/blockSource.ts +37 -0
- package/src/cms/client.ts +5 -0
- package/src/cms/deferredTrigger.ts +58 -0
- package/src/cms/draftSource.ts +171 -57
- package/src/cms/index.ts +32 -3
- package/src/cms/loader.ts +318 -59
- package/src/cms/registry.ts +22 -0
- package/src/cms/renderJson.ts +179 -0
- package/src/cms/resolve.ts +396 -95
- package/src/cms/schema.ts +9 -5
- package/src/cms/sectionLoaders.ts +106 -56
- package/src/hooks/Image.tsx +70 -6
- package/src/hooks/LiveControls.tsx +30 -8
- package/src/hooks/Stats.tsx +134 -0
- package/src/hooks/index.ts +5 -0
- package/src/hooks/useLoadMore.ts +100 -0
- package/src/index.ts +37 -0
- package/src/middleware/observability.ts +173 -16
- package/src/preview/DraftPreviewBadge.tsx +306 -0
- package/src/preview/decoMark.ts +11 -0
- package/src/preview/index.ts +8 -0
- package/src/protocol/assets.ts +124 -0
- package/src/protocol/canonical.ts +7 -0
- package/src/protocol/ciphertext.ts +6 -0
- package/src/protocol/client.ts +170 -0
- package/src/protocol/conformance/cases/assets.ts +81 -0
- package/src/protocol/conformance/cases/guards.ts +314 -0
- package/src/protocol/conformance/cases/reads.ts +168 -0
- package/src/protocol/conformance/cases/types.ts +9 -0
- package/src/protocol/conformance/cases/wire.ts +138 -0
- package/src/protocol/conformance/cases/writes.ts +345 -0
- package/src/protocol/conformance/contentHashFixtures.ts +79 -0
- package/src/protocol/conformance/context.ts +222 -0
- package/src/protocol/conformance/index.ts +140 -0
- package/src/protocol/errors.ts +142 -0
- package/src/protocol/index.ts +39 -0
- package/src/protocol/keys.ts +279 -0
- package/src/protocol/params.ts +67 -0
- package/src/protocol/secrets.ts +231 -0
- package/src/protocol/server/assets.ts +119 -0
- package/src/protocol/server/auth.ts +49 -0
- package/src/protocol/server/bodyCache.ts +84 -0
- package/src/protocol/server/content.ts +175 -0
- package/src/protocol/server/core.ts +112 -0
- package/src/protocol/server/handler.ts +102 -0
- package/src/protocol/server/http.ts +139 -0
- package/src/protocol/server/index.ts +11 -0
- package/src/protocol/server/methods/apply.ts +341 -0
- package/src/protocol/server/methods/read.ts +156 -0
- package/src/protocol/server/rpc.ts +136 -0
- package/src/protocol/storage/fs/hash.ts +21 -0
- package/src/protocol/storage/fs/index.ts +338 -0
- package/src/protocol/storage/fs/lock.ts +68 -0
- package/src/protocol/storage/fs/transaction.ts +183 -0
- package/src/protocol/storage/fs/unsupported.ts +15 -0
- package/src/protocol/storage/memory.ts +238 -0
- package/src/protocol/storage.ts +182 -0
- package/src/protocol/types.ts +172 -0
- package/src/sdk/abTesting.ts +60 -3
- package/src/sdk/analytics.ts +72 -2
- package/src/sdk/cacheHeaders.ts +210 -10
- package/src/sdk/cacheStorage.ts +287 -0
- package/src/sdk/cachedLoader.ts +143 -90
- package/src/sdk/crypto.ts +16 -2
- package/src/sdk/deepOmit.ts +52 -0
- package/src/sdk/encoding.ts +2 -5
- package/src/sdk/experiments.ts +314 -0
- package/src/sdk/fetchCache.ts +269 -0
- package/src/sdk/fetchTimeout.ts +58 -0
- package/src/sdk/flags.ts +38 -8
- package/src/sdk/index.ts +7 -0
- package/src/sdk/instrumentedFetch.ts +25 -2
- package/src/sdk/nonce.ts +46 -0
- package/src/sdk/normalizeUrls.ts +2 -2
- package/src/sdk/observability.ts +8 -1
- package/src/sdk/otel.ts +131 -25
- package/src/sdk/otelHttpLog.ts +4 -4
- package/src/sdk/otelHttpMeter.ts +39 -13
- package/src/sdk/otelHttpTracer.ts +4 -4
- package/src/sdk/redirects.ts +113 -5
- package/src/sdk/responseCache.ts +82 -0
- package/src/sdk/urlUtils.ts +49 -0
- package/src/sdk/useSuggestions.ts +1 -1
- package/src/v8/analytics.ts +50 -0
- package/src/v8/background.ts +107 -0
- package/src/v8/builtins/data.ts +23 -0
- package/src/v8/builtins/index.ts +26 -0
- package/src/v8/builtins/lazy.ts +23 -0
- package/src/v8/builtins/legacy.ts +65 -0
- package/src/v8/builtins/matchers.ts +31 -0
- package/src/v8/builtins/multivariate.ts +25 -0
- package/src/v8/builtins/secret.ts +82 -0
- package/src/v8/canonical.ts +117 -0
- package/src/v8/ciphertext.ts +158 -0
- package/src/v8/cli/builtins.ts +20 -0
- package/src/v8/cli/check/index.ts +774 -0
- package/src/v8/cli/check/messages.ts +168 -0
- package/src/v8/cli/content.ts +287 -0
- package/src/v8/cli/index.ts +17 -0
- package/src/v8/cli/log.ts +18 -0
- package/src/v8/cli/main.ts +12 -0
- package/src/v8/cli/root.ts +66 -0
- package/src/v8/cli/run.ts +236 -0
- package/src/v8/cli/schema/builtinSchemas.ts +236 -0
- package/src/v8/cli/schema/generate.ts +507 -0
- package/src/v8/cli/schema/index.ts +63 -0
- package/src/v8/cli/schema/tsProgram.ts +497 -0
- package/src/v8/cli/schema/typeToSchema.ts +689 -0
- package/src/v8/cli/serve/server.ts +303 -0
- package/src/v8/cli/watch.ts +86 -0
- package/src/v8/client.ts +147 -0
- package/src/v8/cms.ts +237 -0
- package/src/v8/content.ts +195 -0
- package/src/v8/draft.ts +136 -0
- package/src/v8/errors.ts +59 -0
- package/src/v8/fetch.ts +152 -0
- package/src/v8/identity.ts +65 -0
- package/src/v8/index.ts +39 -0
- package/src/v8/json.ts +74 -0
- package/src/v8/matchRoute.ts +204 -0
- package/src/v8/remoteLoader.ts +282 -0
- package/src/v8/resolver.ts +278 -0
- package/src/v8/secrets.ts +17 -0
- package/src/v8/telemetry.ts +533 -0
- package/src/v8/types.ts +240 -0
- package/src/cms/blockSource.test.ts +0 -76
- package/src/cms/client.browserBundle.test.ts +0 -44
- package/src/cms/draftSource.test.ts +0 -343
- package/src/cms/layoutCacheRace.test.ts +0 -181
- package/src/cms/loadDecofileDirectory.test.ts +0 -109
- package/src/cms/loader.test.ts +0 -200
- package/src/cms/registry.test.ts +0 -110
- package/src/cms/resolve.test.ts +0 -980
- package/src/cms/schema.test.ts +0 -356
- package/src/cms/sectionLoaderContext.test.ts +0 -111
- package/src/cms/sectionLoaders.test.ts +0 -533
- package/src/cms/sectionMixins.test.ts +0 -167
- package/src/cms/stickyFlags.test.ts +0 -117
- package/src/flags/flags.test.ts +0 -148
- package/src/hooks/Image.test.ts +0 -100
- package/src/hooks/RenderSection.test.tsx +0 -81
- package/src/matchers/builtins.test.ts +0 -318
- package/src/matchers/override.test.ts +0 -205
- package/src/middleware/hydrationContext.test.ts +0 -61
- package/src/middleware/observability.test.ts +0 -242
- package/src/middleware/validateSection.test.ts +0 -147
- package/src/sdk/abTesting.test.ts +0 -326
- package/src/sdk/cacheHeaders.test.ts +0 -115
- package/src/sdk/cachedLoader.test.ts +0 -122
- package/src/sdk/cachedLoaderModule.test.ts +0 -209
- package/src/sdk/cn.test.ts +0 -34
- package/src/sdk/composite.test.ts +0 -121
- package/src/sdk/cookie.test.ts +0 -108
- package/src/sdk/encoding.test.ts +0 -71
- package/src/sdk/env.test.ts +0 -33
- package/src/sdk/flags.test.ts +0 -91
- package/src/sdk/http.test.ts +0 -71
- package/src/sdk/inflightTimeout.test.ts +0 -35
- package/src/sdk/instrumentedFetch.test.ts +0 -559
- package/src/sdk/invoke.test.ts +0 -115
- package/src/sdk/logger.test.ts +0 -432
- package/src/sdk/otel.test.ts +0 -526
- package/src/sdk/otelAdapters.test.ts +0 -89
- package/src/sdk/otelHttpLog.test.ts +0 -457
- package/src/sdk/otelHttpMeter.test.ts +0 -292
- package/src/sdk/otelHttpTracer.test.ts +0 -474
- package/src/sdk/requestContextStorage.browser.test.ts +0 -29
- package/src/sdk/urlRedaction.test.ts +0 -73
- package/src/sdk/useDevice.test.ts +0 -130
- package/src/sdk/useScript.test.ts +0 -128
- package/src/sdk/useSuggestions.test.ts +0 -230
- 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
|
+
}
|