@decocms/blocks 8.5.1 → 8.6.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/dist/async/default.d.ts +10 -0
- package/dist/async/default.d.ts.map +1 -0
- package/dist/async/default.js +5 -0
- package/dist/async/default.js.map +1 -0
- package/dist/async/node.d.ts +3 -0
- package/dist/async/node.d.ts.map +1 -0
- package/dist/async/node.js +11 -0
- package/dist/async/node.js.map +1 -0
- package/dist/async/types.d.ts +6 -0
- package/dist/async/types.d.ts.map +1 -0
- package/dist/async/types.js +2 -0
- package/dist/async/types.js.map +1 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/v8/bucketing.d.ts +24 -0
- package/dist/v8/bucketing.d.ts.map +1 -0
- package/dist/v8/bucketing.js +78 -0
- package/dist/v8/bucketing.js.map +1 -0
- package/dist/v8/builtins/campaigns.d.ts +36 -0
- package/dist/v8/builtins/campaigns.d.ts.map +1 -0
- package/dist/v8/builtins/campaigns.js +107 -0
- package/dist/v8/builtins/campaigns.js.map +1 -0
- package/dist/v8/builtins/data.d.ts +2 -2
- package/dist/v8/builtins/data.js +2 -2
- package/dist/v8/builtins/experiments.d.ts +27 -0
- package/dist/v8/builtins/experiments.d.ts.map +1 -0
- package/dist/v8/builtins/experiments.js +62 -0
- package/dist/v8/builtins/experiments.js.map +1 -0
- package/dist/v8/builtins/index.d.ts.map +1 -1
- package/dist/v8/builtins/index.js +7 -2
- package/dist/v8/builtins/index.js.map +1 -1
- package/dist/v8/builtins/matchers.d.ts +0 -14
- package/dist/v8/builtins/matchers.d.ts.map +1 -1
- package/dist/v8/builtins/matchers.js +0 -19
- package/dist/v8/builtins/matchers.js.map +1 -1
- package/dist/v8/cli/builtins.d.ts +6 -0
- package/dist/v8/cli/builtins.d.ts.map +1 -1
- package/dist/v8/cli/builtins.js +19 -0
- package/dist/v8/cli/builtins.js.map +1 -1
- package/dist/v8/cli/check/index.d.ts.map +1 -1
- package/dist/v8/cli/check/index.js +231 -8
- package/dist/v8/cli/check/index.js.map +1 -1
- package/dist/v8/cli/schema/builtinSchemas.d.ts.map +1 -1
- package/dist/v8/cli/schema/builtinSchemas.js +76 -21
- package/dist/v8/cli/schema/builtinSchemas.js.map +1 -1
- package/dist/v8/cli/schema/generate.d.ts.map +1 -1
- package/dist/v8/cli/schema/generate.js +48 -2
- package/dist/v8/cli/schema/generate.js.map +1 -1
- package/dist/v8/client.d.ts +25 -0
- package/dist/v8/client.d.ts.map +1 -1
- package/dist/v8/client.js +58 -10
- package/dist/v8/client.js.map +1 -1
- package/dist/v8/cms.d.ts.map +1 -1
- package/dist/v8/cms.js +93 -42
- package/dist/v8/cms.js.map +1 -1
- package/dist/v8/content.d.ts +45 -0
- package/dist/v8/content.d.ts.map +1 -1
- package/dist/v8/content.js +68 -2
- package/dist/v8/content.js.map +1 -1
- package/dist/v8/current.d.ts +28 -0
- package/dist/v8/current.d.ts.map +1 -0
- package/dist/v8/current.js +77 -0
- package/dist/v8/current.js.map +1 -0
- package/dist/v8/draft.d.ts +40 -21
- package/dist/v8/draft.d.ts.map +1 -1
- package/dist/v8/draft.js +160 -25
- package/dist/v8/draft.js.map +1 -1
- package/dist/v8/experiments.d.ts +107 -0
- package/dist/v8/experiments.d.ts.map +1 -0
- package/dist/v8/experiments.js +292 -0
- package/dist/v8/experiments.js.map +1 -0
- package/dist/v8/hosts.d.ts +3 -2
- package/dist/v8/hosts.d.ts.map +1 -1
- package/dist/v8/hosts.js +3 -2
- package/dist/v8/hosts.js.map +1 -1
- package/dist/v8/index.d.ts +7 -5
- package/dist/v8/index.d.ts.map +1 -1
- package/dist/v8/index.js +6 -4
- package/dist/v8/index.js.map +1 -1
- package/dist/v8/remoteLoader.d.ts.map +1 -1
- package/dist/v8/remoteLoader.js +166 -20
- package/dist/v8/remoteLoader.js.map +1 -1
- package/dist/v8/resolver.d.ts +4 -2
- package/dist/v8/resolver.d.ts.map +1 -1
- package/dist/v8/resolver.js +11 -3
- package/dist/v8/resolver.js.map +1 -1
- package/dist/v8/settings.d.ts +16 -4
- package/dist/v8/settings.d.ts.map +1 -1
- package/dist/v8/settings.js +24 -21
- package/dist/v8/settings.js.map +1 -1
- package/dist/v8/types.d.ts +126 -21
- package/dist/v8/types.d.ts.map +1 -1
- package/package.json +35 -1
- package/src/async/default.ts +13 -0
- package/src/async/node.ts +12 -0
- package/src/async/types.ts +5 -0
- package/src/index.ts +4 -0
- package/src/v8/bucketing.ts +88 -0
- package/src/v8/builtins/campaigns.ts +120 -0
- package/src/v8/builtins/data.ts +2 -2
- package/src/v8/builtins/experiments.ts +72 -0
- package/src/v8/builtins/index.ts +7 -2
- package/src/v8/builtins/matchers.ts +0 -26
- package/src/v8/cli/builtins.ts +23 -0
- package/src/v8/cli/check/index.ts +289 -8
- package/src/v8/cli/schema/builtinSchemas.ts +82 -22
- package/src/v8/cli/schema/generate.ts +48 -3
- package/src/v8/client.ts +76 -10
- package/src/v8/cms.ts +108 -43
- package/src/v8/content.ts +86 -2
- package/src/v8/current.ts +98 -0
- package/src/v8/draft.ts +170 -30
- package/src/v8/experiments.ts +340 -0
- package/src/v8/hosts.ts +3 -2
- package/src/v8/index.ts +8 -4
- package/src/v8/remoteLoader.ts +190 -25
- package/src/v8/resolver.ts +14 -4
- package/src/v8/settings.ts +35 -29
- package/src/v8/types.ts +128 -19
|
@@ -0,0 +1,340 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@decocms/blocks/experiments`: who is in which A/B test, decided the same
|
|
3
|
+
* way on a server, in a browser and in a mobile app.
|
|
4
|
+
*
|
|
5
|
+
* The percentages are content (the saved block `experiments`, of the built-in
|
|
6
|
+
* type `split-traffic`); a decision is arithmetic over the visitor's id. What
|
|
7
|
+
* a visitor gets is never stored: it is recomputed from the percentage and the
|
|
8
|
+
* id, so one id serves every test (each roll hashes `name:id`), a new test
|
|
9
|
+
* needs no new state and two tests are independent.
|
|
10
|
+
*
|
|
11
|
+
* Pure functions over values and strings: no React, no framework, no module
|
|
12
|
+
* state, no environment reads, no network. Nothing here is called for you:
|
|
13
|
+
* the app reads the visitor its own way (`readVisitor` on the web, device
|
|
14
|
+
* storage in an app) and hands it to `cms.client({ visitor })`; the built-in
|
|
15
|
+
* `split-traffic` calls `assign` with it.
|
|
16
|
+
*
|
|
17
|
+
* The stored form is v7's `deco_segment` (the same fields and encoding; names
|
|
18
|
+
* sorted by code unit rather than v7's `localeCompare`) plus an `id`, so a
|
|
19
|
+
* visitor carried over from v7 keeps the group v7 put them in and analytics
|
|
20
|
+
* keeps reading the cookie it already reads. A visitor is written once, when
|
|
21
|
+
* it has no id; v7's stored assignments are read and honoured, never rewritten.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
import { newId, roll } from "./bucketing.ts";
|
|
25
|
+
|
|
26
|
+
/** The saved block `experiments`: each test's name and the whole percentage of visitors in it, 0–100. */
|
|
27
|
+
export type Experiments = Record<string, number>;
|
|
28
|
+
|
|
29
|
+
/** What a visitor got: each test's name and whether they are in it. */
|
|
30
|
+
export type Assignments = Record<string, boolean>;
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Who is visiting: an id every assignment is computed from, plus the
|
|
34
|
+
* assignments v7 stored (`active`, `inactiveDrawn`, `pct`, `exp`), which are honoured and
|
|
35
|
+
* carried, never rewritten.
|
|
36
|
+
*/
|
|
37
|
+
export interface Visitor {
|
|
38
|
+
/**
|
|
39
|
+
* 16 random bytes as 22 base64url characters, drawn once per visitor. `""`
|
|
40
|
+
* for a visitor with no id of its own (one built from a cache key's
|
|
41
|
+
* assignments), which is in only the tests `active` names.
|
|
42
|
+
*/
|
|
43
|
+
id: string;
|
|
44
|
+
/** Tests v7 put this visitor in. */
|
|
45
|
+
active: string[];
|
|
46
|
+
/** Tests v7 left this visitor out of. */
|
|
47
|
+
inactiveDrawn: string[];
|
|
48
|
+
/** The percentage each of v7's decisions was made at. */
|
|
49
|
+
pct: Record<string, number>;
|
|
50
|
+
/** v7's N-way decisions. Never read; carried as they are. */
|
|
51
|
+
exp?: Record<string, string>;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** What `readVisitor` answers. */
|
|
55
|
+
export interface VisitorFromRequest {
|
|
56
|
+
/** The request's visitor, or a new one when it had none. */
|
|
57
|
+
visitor: Visitor;
|
|
58
|
+
/**
|
|
59
|
+
* The `Set-Cookie` line to send when the visitor had no id (a first visit,
|
|
60
|
+
* or a v7 visitor getting theirs); `null` otherwise. Never send it from a
|
|
61
|
+
* preview.
|
|
62
|
+
*/
|
|
63
|
+
cookie: string | null;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** The fields of a request `readVisitor` reads: a `Request`, or anything with its `headers`. */
|
|
67
|
+
interface RequestWithHeaders {
|
|
68
|
+
url?: string;
|
|
69
|
+
headers: { get(name: string): string | null };
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** The visitor's stored form, v7's name for it. */
|
|
73
|
+
const VISITOR_COOKIE = "deco_segment";
|
|
74
|
+
|
|
75
|
+
/** One year: the id is the visitor, and it should outlive any single test. */
|
|
76
|
+
const VISITOR_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* A cookie over this stays out of every request. An id plus 50 of v7's
|
|
80
|
+
* decisions fits well under it; past it, `serializeVisitor` drops entries,
|
|
81
|
+
* the ones the id reproduces first.
|
|
82
|
+
*/
|
|
83
|
+
const COOKIE_BUDGET = 2048;
|
|
84
|
+
|
|
85
|
+
const ID_RE = /^[A-Za-z0-9_-]{22}$/;
|
|
86
|
+
|
|
87
|
+
/** A stored visitor before it is known to have an id. */
|
|
88
|
+
type Stored = Omit<Visitor, "id"> & { id?: string };
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* A record with no prototype, so a name such as `__proto__` is an ordinary
|
|
92
|
+
* key: decided, written and read back like any other.
|
|
93
|
+
*/
|
|
94
|
+
function record<T>(): Record<string, T> {
|
|
95
|
+
return Object.create(null) as Record<string, T>;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
function emptyStored(): Stored {
|
|
99
|
+
return { active: [], inactiveDrawn: [], pct: record() };
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
function stringList(value: unknown): string[] {
|
|
103
|
+
if (!Array.isArray(value)) return [];
|
|
104
|
+
return value.filter((entry): entry is string => typeof entry === "string");
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function pctRecord(value: unknown): Record<string, number> {
|
|
108
|
+
const out = record<number>();
|
|
109
|
+
if (typeof value !== "object" || value === null) return out;
|
|
110
|
+
for (const [name, pct] of Object.entries(value as Record<string, unknown>)) {
|
|
111
|
+
if (typeof pct === "number" && Number.isFinite(pct)) out[name] = pct;
|
|
112
|
+
}
|
|
113
|
+
return out;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
function expRecord(value: unknown): Record<string, string> | undefined {
|
|
117
|
+
if (typeof value !== "object" || value === null) return undefined;
|
|
118
|
+
const out = record<string>();
|
|
119
|
+
for (const [name, variant] of Object.entries(value as Record<string, unknown>)) {
|
|
120
|
+
if (typeof variant === "string") out[name] = variant;
|
|
121
|
+
}
|
|
122
|
+
return Object.keys(out).length > 0 ? out : undefined;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* A stored value, with or without an id; `null` when it doesn't read. Never
|
|
127
|
+
* throws. The value may arrive percent-encoded (some cookie APIs encode what
|
|
128
|
+
* they write; base64 never holds a `%`, so decoding first is always safe).
|
|
129
|
+
* Entries of the wrong type are dropped, and an id that is not 22 base64url
|
|
130
|
+
* characters is treated as absent.
|
|
131
|
+
*/
|
|
132
|
+
function parseStored(text: string | null | undefined): Stored | null {
|
|
133
|
+
if (typeof text !== "string" || text === "") return null;
|
|
134
|
+
try {
|
|
135
|
+
const parsed: unknown = JSON.parse(decodeURIComponent(atob(decodeURIComponent(text.trim()))));
|
|
136
|
+
if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
|
|
137
|
+
const body = parsed as Record<string, unknown>;
|
|
138
|
+
const stored: Stored = {
|
|
139
|
+
active: stringList(body.active),
|
|
140
|
+
inactiveDrawn: stringList(body.inactiveDrawn),
|
|
141
|
+
pct: pctRecord(body.pct),
|
|
142
|
+
};
|
|
143
|
+
if (typeof body.id === "string" && ID_RE.test(body.id)) stored.id = body.id;
|
|
144
|
+
const exp = expRecord(body.exp);
|
|
145
|
+
if (exp) stored.exp = exp;
|
|
146
|
+
return stored;
|
|
147
|
+
} catch {
|
|
148
|
+
return null;
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/** A new visitor: a fresh id and nothing else. */
|
|
153
|
+
export function newVisitor(): Visitor {
|
|
154
|
+
return { id: newId(), active: [], inactiveDrawn: [], pct: record() };
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/**
|
|
158
|
+
* A visitor out of its stored form (what `serializeVisitor` wrote, the value
|
|
159
|
+
* of the `deco_segment` cookie). `null` when the text is missing, doesn't
|
|
160
|
+
* read, or holds no id (a v7 value: `readVisitor` gives it one, keeping its
|
|
161
|
+
* decisions). Never throws.
|
|
162
|
+
*/
|
|
163
|
+
export function parseVisitor(text: string | null | undefined): Visitor | null {
|
|
164
|
+
const stored = parseStored(text);
|
|
165
|
+
return stored?.id === undefined ? null : (stored as Visitor);
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* The visitor's stored form: v7's `btoa(encodeURIComponent(JSON.stringify(...)))`,
|
|
170
|
+
* with a fixed key order and names sorted, so two equal visitors give
|
|
171
|
+
* byte-equal values. Under 2KB: past it, v7's entries are dropped, first the
|
|
172
|
+
* ones the id reproduces anyway.
|
|
173
|
+
*/
|
|
174
|
+
export function serializeVisitor(visitor: Visitor): string {
|
|
175
|
+
const active = [...visitor.active].sort();
|
|
176
|
+
const inactiveDrawn = [...visitor.inactiveDrawn].sort();
|
|
177
|
+
const dropped = new Set<string>();
|
|
178
|
+
|
|
179
|
+
const encode = (): string => {
|
|
180
|
+
const stillActive = active.filter((name) => !dropped.has(name));
|
|
181
|
+
const stillInactive = inactiveDrawn.filter((name) => !dropped.has(name));
|
|
182
|
+
const pct = record<number>();
|
|
183
|
+
for (const name of Object.keys(visitor.pct).sort()) {
|
|
184
|
+
// v7 kept a `pct` beside its N-way names too, and `exp` is carried
|
|
185
|
+
// untouched, so their fingerprint is carried with it.
|
|
186
|
+
const listed =
|
|
187
|
+
stillActive.includes(name) ||
|
|
188
|
+
stillInactive.includes(name) ||
|
|
189
|
+
(visitor.exp !== undefined && Object.hasOwn(visitor.exp, name));
|
|
190
|
+
if (listed) pct[name] = visitor.pct[name] as number;
|
|
191
|
+
}
|
|
192
|
+
const body: Record<string, unknown> = {
|
|
193
|
+
active: stillActive,
|
|
194
|
+
inactiveDrawn: stillInactive,
|
|
195
|
+
pct,
|
|
196
|
+
};
|
|
197
|
+
if (visitor.id !== undefined) body.id = visitor.id;
|
|
198
|
+
if (visitor.exp !== undefined) body.exp = visitor.exp;
|
|
199
|
+
return btoa(encodeURIComponent(JSON.stringify(body)));
|
|
200
|
+
};
|
|
201
|
+
|
|
202
|
+
let value = encode();
|
|
203
|
+
if (value.length <= COOKIE_BUDGET) return value;
|
|
204
|
+
|
|
205
|
+
// Over budget. A dropped entry is decided by the roll from then on, which
|
|
206
|
+
// keeps the decision only when the stored one already agrees with the roll.
|
|
207
|
+
// So drop those first, and the others only if the value is still too big.
|
|
208
|
+
const reproducible = (name: string): boolean => {
|
|
209
|
+
const pct = visitor.pct[name];
|
|
210
|
+
if (typeof pct !== "number") return false;
|
|
211
|
+
return active.includes(name) === roll(name, visitor.id) < pct;
|
|
212
|
+
};
|
|
213
|
+
for (const name of [
|
|
214
|
+
...inactiveDrawn.filter(reproducible),
|
|
215
|
+
...active.filter(reproducible),
|
|
216
|
+
...inactiveDrawn.filter((name) => !reproducible(name)),
|
|
217
|
+
...active.filter((name) => !reproducible(name)),
|
|
218
|
+
]) {
|
|
219
|
+
if (value.length <= COOKIE_BUDGET) break;
|
|
220
|
+
dropped.add(name);
|
|
221
|
+
value = encode();
|
|
222
|
+
}
|
|
223
|
+
return value;
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/** The raw `deco_segment` value out of a `Cookie` header. */
|
|
227
|
+
function readCookie(cookies: string | null): string | undefined {
|
|
228
|
+
if (!cookies) return undefined;
|
|
229
|
+
for (const part of cookies.split(";")) {
|
|
230
|
+
const eq = part.indexOf("=");
|
|
231
|
+
if (eq < 0) continue;
|
|
232
|
+
if (part.slice(0, eq).trim() !== VISITOR_COOKIE) continue;
|
|
233
|
+
return part.slice(eq + 1).trim();
|
|
234
|
+
}
|
|
235
|
+
return undefined;
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/** Whether a request came over plain http (localhost), where a `Secure` cookie isn't stored. */
|
|
239
|
+
function isPlainHttp(url: string | undefined): boolean {
|
|
240
|
+
if (typeof url !== "string") return false;
|
|
241
|
+
try {
|
|
242
|
+
return new URL(url).protocol === "http:";
|
|
243
|
+
} catch {
|
|
244
|
+
return false;
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* The web helper: the visitor out of a request's `deco_segment` cookie, and
|
|
250
|
+
* the `Set-Cookie` line to send back when it had no id (a first visit, or a
|
|
251
|
+
* v7 visitor, whose decisions are kept). The cookie isn't `HttpOnly` (the
|
|
252
|
+
* analytics script reads it, as in v7) and is `Secure` unless the request
|
|
253
|
+
* came over plain http. Never throws.
|
|
254
|
+
*/
|
|
255
|
+
export function readVisitor(request: RequestWithHeaders): VisitorFromRequest {
|
|
256
|
+
let header: string | null = null;
|
|
257
|
+
try {
|
|
258
|
+
header = request.headers.get("cookie");
|
|
259
|
+
} catch {
|
|
260
|
+
header = null;
|
|
261
|
+
}
|
|
262
|
+
const stored = parseStored(readCookie(header));
|
|
263
|
+
if (stored?.id !== undefined) return { visitor: stored as Visitor, cookie: null };
|
|
264
|
+
const visitor: Visitor = { ...(stored ?? emptyStored()), id: newId() };
|
|
265
|
+
const parts = [
|
|
266
|
+
`${VISITOR_COOKIE}=${serializeVisitor(visitor)}`,
|
|
267
|
+
"Path=/",
|
|
268
|
+
`Max-Age=${VISITOR_COOKIE_MAX_AGE}`,
|
|
269
|
+
"SameSite=Lax",
|
|
270
|
+
];
|
|
271
|
+
if (!isPlainHttp(request.url)) parts.push("Secure");
|
|
272
|
+
return { visitor, cookie: parts.join("; ") };
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
function roundPct(allocation: number): number {
|
|
276
|
+
return Math.round(Math.min(100, Math.max(0, allocation)));
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/**
|
|
280
|
+
* A v7 decision after the percentage moved: raising a percentage never
|
|
281
|
+
* removes anyone v7 put in, and lowering it never adds anyone v7 left out.
|
|
282
|
+
* Otherwise the roll decides, as for any visitor.
|
|
283
|
+
*/
|
|
284
|
+
function keptFromV7(stored: boolean, from: number, to: number): boolean | undefined {
|
|
285
|
+
if (to === from) return stored;
|
|
286
|
+
if (stored && to > from) return true;
|
|
287
|
+
if (!stored && to < from) return false;
|
|
288
|
+
return undefined;
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
/**
|
|
292
|
+
* This visitor's answer for every test: `true` when they are in it.
|
|
293
|
+
*
|
|
294
|
+
* A visitor is in a test when their roll for it (a fixed number in [0, 100)
|
|
295
|
+
* from the test's name and their id) is under its percentage, so 0 puts
|
|
296
|
+
* nobody in, 100 everybody, and raising a percentage only adds people. A
|
|
297
|
+
* fractional percentage is rounded. An assignment v7 stored is honoured while
|
|
298
|
+
* the percentage it was made at holds (a missing or `-1` percentage, v7's
|
|
299
|
+
* "any", included); once it moves, a v7 visitor in a test that grows stays
|
|
300
|
+
* in and one out of a test that shrinks stays out. Without a visitor every
|
|
301
|
+
* test is `false`. A visitor without an id (`""`, as a page built from a
|
|
302
|
+
* cache key's assignments gives one) has no roll: it is in exactly the tests
|
|
303
|
+
* its stored `active` and `pct` keep it in. Entries that aren't finite numbers are
|
|
304
|
+
* left out. Pure; never throws.
|
|
305
|
+
*/
|
|
306
|
+
export function assign(
|
|
307
|
+
experiments: Experiments | null | undefined,
|
|
308
|
+
visitor: Visitor | null | undefined,
|
|
309
|
+
): Assignments {
|
|
310
|
+
const assignments = record<boolean>();
|
|
311
|
+
if (typeof experiments !== "object" || experiments === null) return assignments;
|
|
312
|
+
const id = visitor !== null && typeof visitor === "object" ? visitor.id : undefined;
|
|
313
|
+
const known = typeof id === "string" && ID_RE.test(id);
|
|
314
|
+
const v: Partial<Visitor> = visitor !== null && typeof visitor === "object" ? visitor : {};
|
|
315
|
+
for (const name of Object.keys(experiments).sort()) {
|
|
316
|
+
const allocation = experiments[name];
|
|
317
|
+
if (typeof allocation !== "number" || !Number.isFinite(allocation)) continue;
|
|
318
|
+
const pct = roundPct(allocation);
|
|
319
|
+
const stored = list(v.active).includes(name)
|
|
320
|
+
? true
|
|
321
|
+
: list(v.inactiveDrawn).includes(name)
|
|
322
|
+
? false
|
|
323
|
+
: undefined;
|
|
324
|
+
// v7 wrote `round(traffic * 100)` here, and its own reader treated a
|
|
325
|
+
// missing or negative entry as "matches anything".
|
|
326
|
+
const raw = isRecord(v.pct) && Object.hasOwn(v.pct, name) ? v.pct[name] : undefined;
|
|
327
|
+
const from = typeof raw === "number" && Number.isFinite(raw) && raw >= 0 ? roundPct(raw) : pct;
|
|
328
|
+
const kept = stored === undefined ? undefined : keptFromV7(stored, from, pct);
|
|
329
|
+
assignments[name] = kept ?? (known && roll(name, id as string) < pct);
|
|
330
|
+
}
|
|
331
|
+
return assignments;
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
function list(value: unknown): string[] {
|
|
335
|
+
return Array.isArray(value) ? value : [];
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
339
|
+
return typeof value === "object" && value !== null;
|
|
340
|
+
}
|
package/src/v8/hosts.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Host patterns (see /next/api-reference#host-patterns): the format of
|
|
3
|
-
*
|
|
2
|
+
* Host patterns (see /next/api-reference#host-patterns): the format of a
|
|
3
|
+
* release's `previewHosts` (Studio writes them into the release metadata)
|
|
4
|
+
* and of `createCMS`'s `preview.hosts`.
|
|
4
5
|
*
|
|
5
6
|
* - Hostnames and patterns are compared lowercase, with one trailing dot
|
|
6
7
|
* removed; names outside ASCII in their punycode form.
|
package/src/v8/index.ts
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The next-major (v8) core SDK: `createCMS`, the clients,
|
|
3
|
-
* `matchRoute` and the draft pointer helpers
|
|
4
|
-
* `cms.draftCookie` are methods: they check the
|
|
2
|
+
* The next-major (v8) core SDK: `createCMS`, the clients, `currentClient`,
|
|
3
|
+
* the built-in blocks, `matchRoute` and the draft pointer helpers
|
|
4
|
+
* (`cms.readVersion` and `cms.draftCookie` are methods: they check the
|
|
5
|
+
* preview hosts). Re-exported from the package root, where
|
|
5
6
|
* these names are the documented ones; see /next/api-reference.
|
|
6
7
|
*/
|
|
7
8
|
export { createCMS, resetForTests } from "./cms.ts";
|
|
8
|
-
export {
|
|
9
|
+
export { currentClient } from "./current.ts";
|
|
10
|
+
export { formatDraftPointer, parseDraftPointer, parseVersion } from "./draft.ts";
|
|
9
11
|
export { matchRoute } from "./matchRoute.ts";
|
|
10
12
|
export { remoteLoader } from "./remoteLoader.ts";
|
|
11
13
|
export type {
|
|
@@ -14,6 +16,7 @@ export type {
|
|
|
14
16
|
BlockFunction,
|
|
15
17
|
Blocks,
|
|
16
18
|
Client,
|
|
19
|
+
ClientOptions,
|
|
17
20
|
CMS,
|
|
18
21
|
CMSError,
|
|
19
22
|
CMSSettings,
|
|
@@ -26,6 +29,7 @@ export type {
|
|
|
26
29
|
Page,
|
|
27
30
|
Redirect,
|
|
28
31
|
RequestLike,
|
|
32
|
+
RequestVersion,
|
|
29
33
|
Result,
|
|
30
34
|
Route,
|
|
31
35
|
Secret,
|
package/src/v8/remoteLoader.ts
CHANGED
|
@@ -9,13 +9,13 @@
|
|
|
9
9
|
* across restarts: every boot starts from the fallback.
|
|
10
10
|
* - `update()` (the CMS calls it in the background, on first use and then
|
|
11
11
|
* every interval) reads `sites/<site>/latest.json`,
|
|
12
|
-
* `{ revision, schemaHash, publishedAt }`. Whoever is newer wins: when it
|
|
12
|
+
* `{ revision, schemaHash, publishedAt, previewHosts }`. Whoever is newer wins: when it
|
|
13
13
|
* names a revision other than the one this process last swapped in, its
|
|
14
14
|
* `schemaHash` equals the fallback's, and its `publishedAt` is later than
|
|
15
15
|
* the fallback's `committedAt` (the commit time of the git HEAD
|
|
16
16
|
* `deco content` built it from), it downloads
|
|
17
|
-
* `sites/<site>/revisions/<revision>.json`,
|
|
18
|
-
* and swaps it in whole. Otherwise, and on any error, memory stays as it is.
|
|
17
|
+
* `sites/<site>/revisions/<revision>.json`,
|
|
18
|
+
* `{ revision, schemaHash, blocks, previewHosts }`, and swaps it in whole. Otherwise, and on any error, memory stays as it is.
|
|
19
19
|
* A fallback without a `schemaHash` never swaps; one without a `committedAt`
|
|
20
20
|
* (a custom loader, an older content module, a build outside git) counts as
|
|
21
21
|
* the oldest. Studio writes `publishedAt` on Publish, on "Make current" (a
|
|
@@ -25,17 +25,49 @@
|
|
|
25
25
|
* a publish still loses to it.
|
|
26
26
|
* Pointers aren't ordered among themselves, and the fallback's content is
|
|
27
27
|
* never compared: only the two timestamps are.
|
|
28
|
+
* - `previewHosts` (host patterns) is where the site may be previewed: Studio
|
|
29
|
+
* knows the site's addresses and writes them into the release metadata
|
|
30
|
+
* whenever it writes `latest.json` or a revision (delivery is trusted).
|
|
31
|
+
* Previews are checked against the current release's list: the last
|
|
32
|
+
* `latest.json` read, whether or not its revision was swapped in (a newer
|
|
33
|
+
* bundle still previews where Studio says). With no list to check
|
|
34
|
+
* (PO 2026-10-22), previews are allowed on every host: a site with no
|
|
35
|
+
* `latest.json` yet (a 404), or one whose `latest.json` has no
|
|
36
|
+
* `previewHosts` (published before Studio wrote the list; its next publish
|
|
37
|
+
* writes one). A read that fails (a network error, a 5xx, a malformed
|
|
38
|
+
* `latest.json`) isn't "no list": until a read succeeds, previews stay
|
|
39
|
+
* closed, and a later failure keeps the last answer (a 404 once a list
|
|
40
|
+
* was read is a failure too: a published site stays published).
|
|
41
|
+
* A preview request before this process has read `latest.json` reads it
|
|
42
|
+
* then (only `latest.json`, once, shared); a read older than the interval
|
|
43
|
+
* is read again the same way, so `dev: true` follows Studio too.
|
|
28
44
|
* - With `dev: true`, it never swaps, so local files win. `createCMS` passes
|
|
29
45
|
* its `dev` option, or `NODE_ENV === "development"` when the site omits it;
|
|
30
46
|
* this loader reads no environment itself.
|
|
31
47
|
* - A release larger than `MAX_SNAPSHOT_BYTES` is refused while it downloads,
|
|
32
48
|
* before it's buffered whole (a Worker isolate has 128 MB).
|
|
49
|
+
* - A client can ask for a published release by its commit SHA
|
|
50
|
+
* (`cms.client({ version })`): it's read from
|
|
51
|
+
* `sites/<site>/revisions/<sha>.json` on first use and kept in memory, a
|
|
52
|
+
* few at a time (the least recently used dropped first), since a revision
|
|
53
|
+
* never changes. One built with another schema than the bundled content is
|
|
54
|
+
* an error, never half a page.
|
|
33
55
|
* - Without `site` it's a plain loader over the fallback.
|
|
34
56
|
*
|
|
35
57
|
* Instances are process-wide singletons, like `createCMS`'s.
|
|
36
58
|
*/
|
|
37
59
|
import { readBoundedJson, timeoutSignal } from "./boundedJson.ts";
|
|
38
|
-
import {
|
|
60
|
+
import {
|
|
61
|
+
BoundedMap,
|
|
62
|
+
isSnapshot,
|
|
63
|
+
PEEK_RELEASE,
|
|
64
|
+
PREVIEW_HOSTS,
|
|
65
|
+
peekRelease,
|
|
66
|
+
previewHostsOf,
|
|
67
|
+
READ_REVISION,
|
|
68
|
+
type ReleasePreviewHosts,
|
|
69
|
+
} from "./content.ts";
|
|
70
|
+
import { errors } from "./errors.ts";
|
|
39
71
|
import { clearGlobals, contentIdentity } from "./identity.ts";
|
|
40
72
|
import { isPlainObject } from "./json.ts";
|
|
41
73
|
import type { Loader, Snapshot } from "./types.ts";
|
|
@@ -49,9 +81,15 @@ const INSTANCE_PREFIX = "decocms.blocks.remote:";
|
|
|
49
81
|
const FETCH_TIMEOUT_MS = 10_000;
|
|
50
82
|
/** The largest release accepted, in bytes of JSON. */
|
|
51
83
|
const MAX_SNAPSHOT_BYTES = 64 * 1024 * 1024;
|
|
84
|
+
/** Published releases kept in memory once read (a client asked for one by its SHA). */
|
|
85
|
+
const CACHED_REVISIONS = 3;
|
|
52
86
|
// OPEN: a revision is the git commit SHA; only SHA-1 (40 hex) object names are accepted.
|
|
53
87
|
const REVISION = /^[0-9a-f]{40}$/;
|
|
54
88
|
const SCHEMA_HASH = /^[0-9a-f]{64}$/;
|
|
89
|
+
/** How long a failed read of the preview hosts waits before a preview request tries again. */
|
|
90
|
+
const PREVIEW_HOSTS_RETRY_MS = 10_000;
|
|
91
|
+
/** How old the preview hosts may get before a preview request reads them again (without `interval`). */
|
|
92
|
+
const PREVIEW_HOSTS_MAX_AGE_MS = 60_000;
|
|
55
93
|
|
|
56
94
|
interface RemoteLoaderOptions {
|
|
57
95
|
site?: string;
|
|
@@ -66,6 +104,15 @@ interface Latest {
|
|
|
66
104
|
revision: string;
|
|
67
105
|
schemaHash: string;
|
|
68
106
|
publishedAt: string;
|
|
107
|
+
/** Where the site may be previewed; `undefined` when Studio wrote none. */
|
|
108
|
+
previewHosts: string[] | undefined;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** A revision file's body. */
|
|
112
|
+
interface Revision {
|
|
113
|
+
blocks: Record<string, unknown>;
|
|
114
|
+
schemaHash: string;
|
|
115
|
+
previewHosts: string[] | undefined;
|
|
69
116
|
}
|
|
70
117
|
|
|
71
118
|
class RemoteLoader implements Loader {
|
|
@@ -78,6 +125,18 @@ class RemoteLoader implements Loader {
|
|
|
78
125
|
/** The release this process last swapped in; `undefined` serves the fallback. */
|
|
79
126
|
#current: Snapshot | undefined;
|
|
80
127
|
readonly #dev: boolean;
|
|
128
|
+
/** Published releases read by SHA; immutable, so a hit is never revalidated. */
|
|
129
|
+
readonly #revisions = new BoundedMap<string, Promise<Snapshot>>(CACHED_REVISIONS);
|
|
130
|
+
/**
|
|
131
|
+
* The preview hosts the last read of `latest.json` found (its list, or
|
|
132
|
+
* `"every"`: a 404, or no `previewHosts` in it), and when. A failed read
|
|
133
|
+
* leaves it as it was.
|
|
134
|
+
*/
|
|
135
|
+
#hosts: { list: readonly string[] | "every"; at: number } | undefined;
|
|
136
|
+
/** A read of `latest.json` for its preview hosts, in flight. */
|
|
137
|
+
#hostsRead: Promise<void> | undefined;
|
|
138
|
+
/** When that read last failed. */
|
|
139
|
+
#hostsFailedAt = Number.NEGATIVE_INFINITY;
|
|
81
140
|
|
|
82
141
|
constructor(
|
|
83
142
|
fallback: Snapshot | Loader,
|
|
@@ -118,13 +177,117 @@ class RemoteLoader implements Loader {
|
|
|
118
177
|
// OPEN: a process that already swapped a release in keeps it (memory stays as it is).
|
|
119
178
|
if (!isNewer(latest.publishedAt, fallback.committedAt)) return { updated: false };
|
|
120
179
|
if (latest.revision === this.#current?.revision) return { updated: false };
|
|
121
|
-
const
|
|
122
|
-
const next: Snapshot = {
|
|
180
|
+
const revision = await this.#revision(site, latest);
|
|
181
|
+
const next: Snapshot = {
|
|
182
|
+
revision: latest.revision,
|
|
183
|
+
blocks: revision.blocks,
|
|
184
|
+
schemaHash: latest.schemaHash,
|
|
185
|
+
};
|
|
186
|
+
if (revision.previewHosts !== undefined) next.previewHosts = revision.previewHosts;
|
|
123
187
|
if (fallback.aliases !== undefined) next.aliases = fallback.aliases;
|
|
124
188
|
this.#current = next;
|
|
125
189
|
return { updated: true };
|
|
126
190
|
}
|
|
127
191
|
|
|
192
|
+
/**
|
|
193
|
+
* The current release's preview hosts (see `PREVIEW_HOSTS`): the last
|
|
194
|
+
* successful read of `latest.json`, reading it first when there is none yet
|
|
195
|
+
* or it is older than the interval (`peek`: never). `"every"` when
|
|
196
|
+
* the site has no `latest.json` (a 404) or it names no `previewHosts`;
|
|
197
|
+
* `"unknown"` while no read has succeeded (a failed one is retried after a
|
|
198
|
+
* pause), so previews stay closed rather than open on an error.
|
|
199
|
+
*/
|
|
200
|
+
async [PREVIEW_HOSTS](peek = false): Promise<ReleasePreviewHosts> {
|
|
201
|
+
const known = this.#hosts;
|
|
202
|
+
const maxAge = this.interval ?? PREVIEW_HOSTS_MAX_AGE_MS;
|
|
203
|
+
const stale = known === undefined || Date.now() - known.at >= maxAge;
|
|
204
|
+
if (!peek && stale && Date.now() - this.#hostsFailedAt >= PREVIEW_HOSTS_RETRY_MS) {
|
|
205
|
+
this.#hostsRead ??= this.#latest(encodeURIComponent(this.#site))
|
|
206
|
+
.then(
|
|
207
|
+
() => undefined,
|
|
208
|
+
() => {
|
|
209
|
+
// A 404 is an answer (`#latest` recorded it), not a failure.
|
|
210
|
+
if (this.#hosts === known) this.#hostsFailedAt = Date.now();
|
|
211
|
+
},
|
|
212
|
+
)
|
|
213
|
+
.finally(() => {
|
|
214
|
+
this.#hostsRead = undefined;
|
|
215
|
+
});
|
|
216
|
+
await this.#hostsRead;
|
|
217
|
+
}
|
|
218
|
+
const list = this.#hosts?.list;
|
|
219
|
+
if (list === undefined) return "unknown";
|
|
220
|
+
return list === "every" ? list : list.slice();
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
/** A published release by its commit SHA (see `READ_REVISION`). */
|
|
224
|
+
async [READ_REVISION](sha: string): Promise<Snapshot> {
|
|
225
|
+
if (!REVISION.test(sha)) throw errors.loaderFailed(`"${sha}" is not a release's commit SHA`);
|
|
226
|
+
if (this.#current?.revision === sha) return this.#current;
|
|
227
|
+
const fallback = this.#fallbackSnapshot ?? (await this.#loadFallback());
|
|
228
|
+
if (fallback.revision === sha) return fallback;
|
|
229
|
+
if (fallback.schemaHash === undefined) {
|
|
230
|
+
throw errors.loaderFailed(
|
|
231
|
+
`the release ${sha} can't be checked against this code: the bundled content has no schemaHash (run deco content)`,
|
|
232
|
+
);
|
|
233
|
+
}
|
|
234
|
+
const snapshot = await this.#readRevision(sha);
|
|
235
|
+
if (snapshot.schemaHash !== fallback.schemaHash) {
|
|
236
|
+
throw errors.loaderFailed(
|
|
237
|
+
`the release ${sha} was published with another schema than this code's ` +
|
|
238
|
+
`(${snapshot.schemaHash} ≠ ${fallback.schemaHash}): preview it on a deploy of its own code`,
|
|
239
|
+
);
|
|
240
|
+
}
|
|
241
|
+
if (fallback.aliases === undefined) return snapshot;
|
|
242
|
+
return { ...snapshot, aliases: fallback.aliases };
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/** Reads a revision once; a failed read isn't kept, so the next client tries again. */
|
|
246
|
+
#readRevision(sha: string): Promise<Snapshot> {
|
|
247
|
+
const held = this.#revisions.get(sha);
|
|
248
|
+
if (held !== undefined) return held;
|
|
249
|
+
const site = encodeURIComponent(this.#site);
|
|
250
|
+
const pending = this.#fetchRevision(site, sha, "the revision asked for").then((body) => {
|
|
251
|
+
const snapshot: Snapshot = {
|
|
252
|
+
revision: sha,
|
|
253
|
+
blocks: body.blocks,
|
|
254
|
+
schemaHash: body.schemaHash,
|
|
255
|
+
};
|
|
256
|
+
if (body.previewHosts !== undefined) snapshot.previewHosts = body.previewHosts;
|
|
257
|
+
return snapshot;
|
|
258
|
+
});
|
|
259
|
+
this.#revisions.set(sha, pending);
|
|
260
|
+
pending.catch(() => {
|
|
261
|
+
if (this.#revisions.get(sha) === pending) this.#revisions.delete(sha);
|
|
262
|
+
});
|
|
263
|
+
return pending;
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
async #fetchRevision(site: string, sha: string, expected: string): Promise<Revision> {
|
|
267
|
+
const label = `revision ${sha}`;
|
|
268
|
+
const response = await fetchWithTimeout(
|
|
269
|
+
`${deliveryOrigin()}/sites/${site}/revisions/${sha}.json`,
|
|
270
|
+
);
|
|
271
|
+
if (!response.ok) {
|
|
272
|
+
await response.body?.cancel();
|
|
273
|
+
throw new Error(`${label}: HTTP ${response.status}`);
|
|
274
|
+
}
|
|
275
|
+
const body = await readBoundedJson(response, label, MAX_SNAPSHOT_BYTES);
|
|
276
|
+
if (
|
|
277
|
+
!isPlainObject(body) ||
|
|
278
|
+
body.revision !== sha ||
|
|
279
|
+
typeof body.schemaHash !== "string" ||
|
|
280
|
+
!isPlainObject(body.blocks)
|
|
281
|
+
) {
|
|
282
|
+
throw new Error(`${label}: unexpected format, or not ${expected}`);
|
|
283
|
+
}
|
|
284
|
+
return {
|
|
285
|
+
blocks: body.blocks,
|
|
286
|
+
schemaHash: body.schemaHash,
|
|
287
|
+
previewHosts: previewHostsOf(body.previewHosts),
|
|
288
|
+
};
|
|
289
|
+
}
|
|
290
|
+
|
|
128
291
|
async #loadFallback(): Promise<Snapshot> {
|
|
129
292
|
const fallback = this.#fallback;
|
|
130
293
|
const snapshot = isSnapshot(fallback) ? fallback : await (fallback as Loader).load();
|
|
@@ -136,6 +299,12 @@ class RemoteLoader implements Loader {
|
|
|
136
299
|
const response = await fetchWithTimeout(`${deliveryOrigin()}/sites/${site}/latest.json`);
|
|
137
300
|
if (!response.ok) {
|
|
138
301
|
await response.body?.cancel();
|
|
302
|
+
// Not published yet: no list, so previews are allowed on every host (PO 2026-10-22).
|
|
303
|
+
// A site this process has read a list for can't be unpublished: a 404 then
|
|
304
|
+
// (a CDN fault, a publish caught mid-write) is a failed read, so it keeps the list.
|
|
305
|
+
if (response.status === 404 && !Array.isArray(this.#hosts?.list)) {
|
|
306
|
+
this.#hosts = { list: "every", at: Date.now() };
|
|
307
|
+
}
|
|
139
308
|
throw new Error(`latest.json: HTTP ${response.status}`);
|
|
140
309
|
}
|
|
141
310
|
const body: unknown = await response.json();
|
|
@@ -150,28 +319,24 @@ class RemoteLoader implements Loader {
|
|
|
150
319
|
) {
|
|
151
320
|
throw new Error("latest.json: unexpected format");
|
|
152
321
|
}
|
|
153
|
-
|
|
322
|
+
const previewHosts = previewHostsOf(body.previewHosts);
|
|
323
|
+
// The current release's metadata, whether or not its revision is swapped in.
|
|
324
|
+
// No `previewHosts` (published before Studio wrote the list): every host, as with no latest.json.
|
|
325
|
+
this.#hosts = { list: previewHosts ?? "every", at: Date.now() };
|
|
326
|
+
return {
|
|
327
|
+
revision: body.revision,
|
|
328
|
+
schemaHash: body.schemaHash,
|
|
329
|
+
publishedAt: body.publishedAt,
|
|
330
|
+
previewHosts,
|
|
331
|
+
};
|
|
154
332
|
}
|
|
155
333
|
|
|
156
|
-
async #revision(site: string, latest: Latest): Promise<
|
|
157
|
-
const
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
);
|
|
161
|
-
if (!response.ok) {
|
|
162
|
-
await response.body?.cancel();
|
|
163
|
-
throw new Error(`${label}: HTTP ${response.status}`);
|
|
164
|
-
}
|
|
165
|
-
const body = await readBoundedJson(response, label, MAX_SNAPSHOT_BYTES);
|
|
166
|
-
if (
|
|
167
|
-
!isPlainObject(body) ||
|
|
168
|
-
body.revision !== latest.revision ||
|
|
169
|
-
body.schemaHash !== latest.schemaHash ||
|
|
170
|
-
!isPlainObject(body.blocks)
|
|
171
|
-
) {
|
|
172
|
-
throw new Error(`${label}: unexpected format, or not the revision latest.json names`);
|
|
334
|
+
async #revision(site: string, latest: Latest): Promise<Revision> {
|
|
335
|
+
const body = await this.#fetchRevision(site, latest.revision, "the revision latest.json names");
|
|
336
|
+
if (body.schemaHash !== latest.schemaHash) {
|
|
337
|
+
throw new Error(`revision ${latest.revision}: not the schema latest.json names`);
|
|
173
338
|
}
|
|
174
|
-
return body
|
|
339
|
+
return body;
|
|
175
340
|
}
|
|
176
341
|
}
|
|
177
342
|
|