@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
package/src/v8/cms.ts
ADDED
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `createCMS`: the block map plus the content, created once per process.
|
|
3
|
+
*
|
|
4
|
+
* Instances are process-wide singletons stored on `globalThis` under a
|
|
5
|
+
* `Symbol.for("decocms.blocks.cms:…")` key derived from the configuration, so
|
|
6
|
+
* a package loaded twice (two bundles, a dev reload) still shares one content
|
|
7
|
+
* cache. See /next/api-reference#one-instance-per-process.
|
|
8
|
+
*/
|
|
9
|
+
import { runInBackground } from "./background";
|
|
10
|
+
import { builtIns } from "./builtins/index";
|
|
11
|
+
import { secretBlock } from "./builtins/secret";
|
|
12
|
+
import { CMSClient } from "./client";
|
|
13
|
+
import { ContentStore, isLoader, isSnapshot } from "./content";
|
|
14
|
+
import { clearGlobals, contentIdentity, fnv1a, readEnv } from "./identity";
|
|
15
|
+
import { remoteLoader, resetRemoteLoaders } from "./remoteLoader";
|
|
16
|
+
import { resolveDestination, setCurrentTelemetry, TelemetryPipeline } from "./telemetry";
|
|
17
|
+
import type { Blocks, Client, CMS, CMSConfig, Loader, Snapshot } from "./types";
|
|
18
|
+
|
|
19
|
+
const INSTANCE_PREFIX = "decocms.blocks.cms:";
|
|
20
|
+
const MIN_INTERVAL = 60_000;
|
|
21
|
+
/** Each check runs one interval, plus or minus up to this much, after the previous one. */
|
|
22
|
+
const JITTER = 10_000;
|
|
23
|
+
|
|
24
|
+
/** Options that must agree between two `createCMS` calls sharing an instance. */
|
|
25
|
+
interface Fingerprint {
|
|
26
|
+
interval: number;
|
|
27
|
+
telemetry: string;
|
|
28
|
+
secrets: string;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
class CMSInstance implements CMS {
|
|
32
|
+
readonly config: Readonly<CMSConfig>;
|
|
33
|
+
readonly fingerprint: Fingerprint;
|
|
34
|
+
readonly #store: ContentStore;
|
|
35
|
+
readonly #interval: number;
|
|
36
|
+
readonly #warned = new Set<string>();
|
|
37
|
+
/** The built-ins with a `secret` that holds this instance's key (the first call's). */
|
|
38
|
+
readonly #builtIns: Readonly<Blocks>;
|
|
39
|
+
readonly #telemetry: TelemetryPipeline | undefined;
|
|
40
|
+
#blocks: Blocks;
|
|
41
|
+
/**
|
|
42
|
+
* When the next check is due. The first is on the first `forRelease()`, not
|
|
43
|
+
* at construction: Workers read `Date.now()` as 0 at module scope.
|
|
44
|
+
*/
|
|
45
|
+
#nextCheck: number | undefined;
|
|
46
|
+
|
|
47
|
+
constructor(config: CMSConfig, interval: number) {
|
|
48
|
+
this.config = config;
|
|
49
|
+
this.#blocks = config.blocks;
|
|
50
|
+
this.#interval = interval;
|
|
51
|
+
this.#store = new ContentStore(contentOf(config));
|
|
52
|
+
this.fingerprint = fingerprintOf(config, interval);
|
|
53
|
+
const destination = resolveDestination(config.telemetry, config.site);
|
|
54
|
+
if (destination !== null) {
|
|
55
|
+
this.#telemetry = new TelemetryPipeline(destination);
|
|
56
|
+
setCurrentTelemetry(this.#telemetry);
|
|
57
|
+
}
|
|
58
|
+
// Decrypted values never leave in telemetry: the pipeline redacts each one.
|
|
59
|
+
const telemetry = this.#telemetry;
|
|
60
|
+
const secret = secretBlock(config.secrets?.key, (value) => telemetry?.redact(value));
|
|
61
|
+
this.#builtIns = Object.freeze({ ...builtIns, secret });
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
forRelease(): Client {
|
|
65
|
+
this.#scheduleUpdate();
|
|
66
|
+
const telemetry = this.#telemetry;
|
|
67
|
+
if (telemetry === undefined) return this.#client(() => this.#store.release());
|
|
68
|
+
return this.#client(() =>
|
|
69
|
+
this.#store.release().then((snapshot) => {
|
|
70
|
+
telemetry.useRelease(snapshot);
|
|
71
|
+
return snapshot;
|
|
72
|
+
}),
|
|
73
|
+
);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
forDraft(pointer: string): Client {
|
|
77
|
+
return this.#client(() => this.#store.draft(pointer));
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
forRevision(revision: string): Client {
|
|
81
|
+
return this.#client(() => this.#store.revision(revision));
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
update(): Promise<{ updated: boolean }> {
|
|
85
|
+
this.#nextCheck = this.#due();
|
|
86
|
+
return this.#store.update();
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** A later `createCMS` call with the same key hands in its (possibly hot-reloaded) map and content. */
|
|
90
|
+
adopt(config: CMSConfig): void {
|
|
91
|
+
this.#blocks = config.blocks;
|
|
92
|
+
this.#store.replace(contentOf(config));
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
#client(load: () => Promise<Snapshot>): Client {
|
|
96
|
+
return new CMSClient({
|
|
97
|
+
load,
|
|
98
|
+
blocks: this.#blocks,
|
|
99
|
+
builtIns: this.#builtIns,
|
|
100
|
+
onCollision: (name) => this.#warnCollision(name),
|
|
101
|
+
telemetry: this.#telemetry?.forClient(),
|
|
102
|
+
});
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Checks a content source with `update()` on first use and then every
|
|
107
|
+
* `interval` (± up to 10 s), at an idle moment, never in front of a request.
|
|
108
|
+
*/
|
|
109
|
+
#scheduleUpdate(): void {
|
|
110
|
+
if (!this.#store.updatable) return;
|
|
111
|
+
if (this.#nextCheck !== undefined && Date.now() < this.#nextCheck) return;
|
|
112
|
+
this.#nextCheck = this.#due();
|
|
113
|
+
runInBackground(() => this.#store.update());
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
#due(): number {
|
|
117
|
+
return Date.now() + this.#interval + (Math.random() * 2 - 1) * JITTER;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
#warnCollision(name: string): void {
|
|
121
|
+
if (this.#warned.has(name)) return;
|
|
122
|
+
this.#warned.add(name);
|
|
123
|
+
console.warn(
|
|
124
|
+
`[decocms/blocks] the saved block "${name}" has the name of a block type, built-in or alias; ` +
|
|
125
|
+
"the function wins. Rename the saved block (deco check reports this).",
|
|
126
|
+
);
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Creates the CMS, or returns the instance this configuration already has.
|
|
132
|
+
* Create it once, at module scope, and ask it for a client per request.
|
|
133
|
+
*/
|
|
134
|
+
export function createCMS(config: CMSConfig): CMS {
|
|
135
|
+
validate(config);
|
|
136
|
+
// A remoteLoader passed as `content` carries the `interval` it was created with.
|
|
137
|
+
const own = (config.content as { interval?: unknown }).interval;
|
|
138
|
+
const interval = resolveInterval(config.interval ?? (typeof own === "number" ? own : undefined));
|
|
139
|
+
const key = Symbol.for(INSTANCE_PREFIX + identityOf(config));
|
|
140
|
+
const store = globalThis as unknown as Record<symbol, CMSInstance | undefined>;
|
|
141
|
+
const existing = store[key];
|
|
142
|
+
if (existing instanceof Object && typeof existing.adopt === "function") {
|
|
143
|
+
warnOnConflict(existing.fingerprint, fingerprintOf(config, interval));
|
|
144
|
+
existing.adopt(config);
|
|
145
|
+
return existing;
|
|
146
|
+
}
|
|
147
|
+
const instance = new CMSInstance(config, interval);
|
|
148
|
+
store[key] = instance;
|
|
149
|
+
return instance;
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/** Clears every stored CMS instance, so a test starts clean. */
|
|
153
|
+
export function resetForTests(): void {
|
|
154
|
+
clearGlobals(INSTANCE_PREFIX);
|
|
155
|
+
resetRemoteLoaders();
|
|
156
|
+
setCurrentTelemetry(undefined);
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/** With `site` and `token`, the content is the fallback of hosted releases and drafts. */
|
|
160
|
+
function contentOf(config: CMSConfig): Snapshot | Loader {
|
|
161
|
+
if (!config.site || !config.token) return config.content;
|
|
162
|
+
return remoteLoader(config.content, { site: config.site, token: config.token });
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
function validate(config: CMSConfig): void {
|
|
166
|
+
if (config === null || typeof config !== "object") {
|
|
167
|
+
throw new TypeError("createCMS: expected a config object");
|
|
168
|
+
}
|
|
169
|
+
if (config.blocks === null || typeof config.blocks !== "object") {
|
|
170
|
+
throw new TypeError("createCMS: `blocks` must be your block map (an object of functions)");
|
|
171
|
+
}
|
|
172
|
+
if (!isLoader(config.content) && !isSnapshot(config.content)) {
|
|
173
|
+
throw new TypeError(
|
|
174
|
+
"createCMS: `content` must be the content module ({ revision, blocks }) or a loader with load()",
|
|
175
|
+
);
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
function resolveInterval(configured: number | undefined): number {
|
|
180
|
+
const env = readEnv("DECO_CONTENT_INTERVAL");
|
|
181
|
+
const raw = configured ?? (env ? Number(env) : MIN_INTERVAL);
|
|
182
|
+
if (!Number.isFinite(raw)) return MIN_INTERVAL;
|
|
183
|
+
if (raw < MIN_INTERVAL) {
|
|
184
|
+
console.warn(
|
|
185
|
+
`[decocms/blocks] interval ${raw} ms is below the minimum; raised to ${MIN_INTERVAL} ms.`,
|
|
186
|
+
);
|
|
187
|
+
return MIN_INTERVAL;
|
|
188
|
+
}
|
|
189
|
+
return raw;
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/**
|
|
193
|
+
* The instance key: the content's identity (never its revision, so a hot
|
|
194
|
+
* reload keeps the instance) and, with the hosted Deco CMS, the site and a
|
|
195
|
+
* hash of the token, which never appears in the global symbol registry.
|
|
196
|
+
*
|
|
197
|
+
* A content module is identified by the `.deco` folder it was generated from
|
|
198
|
+
* (its `root`). One without a `root` is identified by the object itself, so
|
|
199
|
+
* two such modules never share an instance; a hot reload of one then gets a
|
|
200
|
+
* new instance instead of updating the old.
|
|
201
|
+
*/
|
|
202
|
+
function identityOf(config: CMSConfig): string {
|
|
203
|
+
const content = contentIdentity(config.content);
|
|
204
|
+
if (!config.site || !config.token) return content;
|
|
205
|
+
return `${content}|site:${config.site}|token:${fnv1a(config.token)}`;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
function fingerprintOf(config: CMSConfig, interval: number): Fingerprint {
|
|
209
|
+
return {
|
|
210
|
+
interval,
|
|
211
|
+
telemetry: stableJson(config.telemetry ?? null),
|
|
212
|
+
secrets: config.secrets?.key ? fnv1a(config.secrets.key) : "",
|
|
213
|
+
};
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
function warnOnConflict(first: Fingerprint, next: Fingerprint): void {
|
|
217
|
+
const conflicts = (Object.keys(first) as (keyof Fingerprint)[]).filter(
|
|
218
|
+
(name) => first[name] !== next[name],
|
|
219
|
+
);
|
|
220
|
+
if (conflicts.length === 0) return;
|
|
221
|
+
console.warn(
|
|
222
|
+
`[decocms/blocks] createCMS was called again for the same content with different options ` +
|
|
223
|
+
`(${conflicts.join(", ")}); keeping the first instance's options.`,
|
|
224
|
+
);
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
function stableJson(value: unknown): string {
|
|
228
|
+
if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
|
|
229
|
+
if (value !== null && typeof value === "object") {
|
|
230
|
+
const record = value as Record<string, unknown>;
|
|
231
|
+
return `{${Object.keys(record)
|
|
232
|
+
.sort()
|
|
233
|
+
.map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
|
|
234
|
+
.join(",")}}`;
|
|
235
|
+
}
|
|
236
|
+
return JSON.stringify(value) ?? "undefined";
|
|
237
|
+
}
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The content side of a CMS: one source (the content module or a `Loader`),
|
|
3
|
+
* the caches every client shares, and the release revisions this process has
|
|
4
|
+
* served. Clients only ever see whole `{ revision, blocks }` snapshots.
|
|
5
|
+
*
|
|
6
|
+
* Drafts are never recorded as served: `forRevision(revision)` takes a
|
|
7
|
+
* revision string a client may hand back, so it must only ever reach published
|
|
8
|
+
* content, never a draft someone loaded with a pointer.
|
|
9
|
+
*/
|
|
10
|
+
import { formatDraftPointer, parseDraftPointer } from "./draft";
|
|
11
|
+
import { errors, isResolutionError } from "./errors";
|
|
12
|
+
import { isPlainObject } from "./json";
|
|
13
|
+
import type { Loader, Snapshot } from "./types";
|
|
14
|
+
|
|
15
|
+
const SERVED_REVISIONS = 16;
|
|
16
|
+
const CACHED_DRAFTS = 32;
|
|
17
|
+
|
|
18
|
+
export function isLoader(content: unknown): content is Loader {
|
|
19
|
+
return (
|
|
20
|
+
(typeof content === "object" || typeof content === "function") &&
|
|
21
|
+
content !== null &&
|
|
22
|
+
typeof (content as Loader).load === "function"
|
|
23
|
+
);
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export function isSnapshot(content: unknown): content is Snapshot {
|
|
27
|
+
return (
|
|
28
|
+
isPlainObject(content) &&
|
|
29
|
+
typeof content.revision === "string" &&
|
|
30
|
+
isPlainObject(content.blocks) &&
|
|
31
|
+
(content.aliases === undefined || isPlainObject(content.aliases))
|
|
32
|
+
);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export class ContentStore {
|
|
36
|
+
#source: Snapshot | Loader;
|
|
37
|
+
#release: Promise<Snapshot> | undefined;
|
|
38
|
+
#updating: Promise<{ updated: boolean }> | undefined;
|
|
39
|
+
readonly #drafts = new BoundedMap<string, Promise<Snapshot>>(CACHED_DRAFTS);
|
|
40
|
+
readonly #served = new BoundedMap<string, Snapshot>(SERVED_REVISIONS);
|
|
41
|
+
|
|
42
|
+
constructor(source: Snapshot | Loader) {
|
|
43
|
+
this.#source = source;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** Whether the source can change while the process runs (has `update()`). */
|
|
47
|
+
get updatable(): boolean {
|
|
48
|
+
return isLoader(this.#source) && typeof this.#source.update === "function";
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* The current release. A snapshot is the release; a loader with `update()`
|
|
53
|
+
* is loaded once and reloaded after an update; a loader without `update()`
|
|
54
|
+
* is asked on every call, since it's always current by construction.
|
|
55
|
+
*/
|
|
56
|
+
release(): Promise<Snapshot> {
|
|
57
|
+
const source = this.#source;
|
|
58
|
+
if (!isLoader(source)) return Promise.resolve(this.#serve(source));
|
|
59
|
+
if (!this.updatable) return this.#load(source, null).then((snapshot) => this.#serve(snapshot));
|
|
60
|
+
if (this.#release === undefined) {
|
|
61
|
+
const pending = this.#load(source, null).then((snapshot) => this.#serve(snapshot));
|
|
62
|
+
this.#release = pending;
|
|
63
|
+
// A failed load isn't cached: the next client tries again.
|
|
64
|
+
pending.catch(() => {
|
|
65
|
+
if (this.#release === pending) this.#release = undefined;
|
|
66
|
+
});
|
|
67
|
+
}
|
|
68
|
+
return this.#release;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* The draft a pointer names. A snapshot has no drafts and ignores the
|
|
73
|
+
* pointer. A loader gets `load(pointer)` only for a pointer that parses;
|
|
74
|
+
* anything else is `LOADER_FAILED`, never a silent fallback to the release.
|
|
75
|
+
*/
|
|
76
|
+
draft(pointer: string): Promise<Snapshot> {
|
|
77
|
+
const source = this.#source;
|
|
78
|
+
if (!isLoader(source)) return this.release();
|
|
79
|
+
const parsed = parseDraftPointer(pointer);
|
|
80
|
+
if (parsed === null) {
|
|
81
|
+
return Promise.reject(errors.loaderFailed(`invalid draft pointer "${truncate(pointer)}"`));
|
|
82
|
+
}
|
|
83
|
+
const key = formatDraftPointer(parsed);
|
|
84
|
+
const cached = this.#drafts.get(key);
|
|
85
|
+
if (cached !== undefined) return cached;
|
|
86
|
+
const pending = this.#load(source, pointer);
|
|
87
|
+
this.#drafts.set(key, pending);
|
|
88
|
+
pending.catch(() => this.#drafts.delete(key));
|
|
89
|
+
return pending;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** A release revision this store has served, or the release when it's unknown (drafts included). */
|
|
93
|
+
revision(revision: string): Promise<Snapshot> {
|
|
94
|
+
const served = this.#served.get(revision);
|
|
95
|
+
return served === undefined ? this.release() : Promise.resolve(served);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/** Asks the source for newer content; never throws, and concurrent calls share one check. */
|
|
99
|
+
update(): Promise<{ updated: boolean }> {
|
|
100
|
+
const source = this.#source;
|
|
101
|
+
if (!isLoader(source) || typeof source.update !== "function") {
|
|
102
|
+
return Promise.resolve({ updated: false });
|
|
103
|
+
}
|
|
104
|
+
this.#updating ??= (async () => {
|
|
105
|
+
try {
|
|
106
|
+
const result = await source.update?.();
|
|
107
|
+
const updated = result?.updated === true;
|
|
108
|
+
if (updated) {
|
|
109
|
+
this.#release = undefined;
|
|
110
|
+
// A loader that ignores the pointer hands back the release as the
|
|
111
|
+
// draft; that copy is as stale as the release now.
|
|
112
|
+
this.#drafts.clear();
|
|
113
|
+
}
|
|
114
|
+
return { updated };
|
|
115
|
+
} catch {
|
|
116
|
+
return { updated: false };
|
|
117
|
+
} finally {
|
|
118
|
+
this.#updating = undefined;
|
|
119
|
+
}
|
|
120
|
+
})();
|
|
121
|
+
return this.#updating;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Swaps the content in place, for a hot reload that hands the same CMS a new
|
|
126
|
+
* content module. Any new object swaps, even with the same `revision`: an
|
|
127
|
+
* edited JSON file reloads without rerunning `deco content`, so the new
|
|
128
|
+
* module carries new `blocks` under the old revision.
|
|
129
|
+
*/
|
|
130
|
+
replace(source: Snapshot | Loader): void {
|
|
131
|
+
const previous = this.#source;
|
|
132
|
+
if (source === previous) {
|
|
133
|
+
// The same loader (a hosted remoteLoader that adopted new fallback content): re-read it.
|
|
134
|
+
this.#release = undefined;
|
|
135
|
+
return;
|
|
136
|
+
}
|
|
137
|
+
if (isSnapshot(previous)) this.#served.delete(previous.revision);
|
|
138
|
+
this.#source = source;
|
|
139
|
+
this.#release = undefined;
|
|
140
|
+
this.#drafts.clear();
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
async #load(loader: Loader, pointer: string | null): Promise<Snapshot> {
|
|
144
|
+
let snapshot: unknown;
|
|
145
|
+
try {
|
|
146
|
+
snapshot = pointer === null ? await loader.load() : await loader.load(pointer);
|
|
147
|
+
} catch (error) {
|
|
148
|
+
if (isResolutionError(error)) throw error;
|
|
149
|
+
throw errors.loaderFailed(
|
|
150
|
+
pointer === null ? "the content loader failed" : "the draft couldn't load",
|
|
151
|
+
error,
|
|
152
|
+
);
|
|
153
|
+
}
|
|
154
|
+
if (!isSnapshot(snapshot)) {
|
|
155
|
+
throw errors.loaderFailed("the content loader returned something other than a snapshot");
|
|
156
|
+
}
|
|
157
|
+
return snapshot;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
#serve(snapshot: Snapshot): Snapshot {
|
|
161
|
+
this.#served.set(snapshot.revision, snapshot);
|
|
162
|
+
return snapshot;
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
function truncate(value: string): string {
|
|
167
|
+
return value.length > 80 ? `${value.slice(0, 80)}…` : value;
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/** A Map that forgets its least recently set entry past `limit`. */
|
|
171
|
+
class BoundedMap<K, V> {
|
|
172
|
+
readonly #map = new Map<K, V>();
|
|
173
|
+
constructor(readonly limit: number) {}
|
|
174
|
+
|
|
175
|
+
get(key: K): V | undefined {
|
|
176
|
+
return this.#map.get(key);
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
set(key: K, value: V): void {
|
|
180
|
+
this.#map.delete(key);
|
|
181
|
+
this.#map.set(key, value);
|
|
182
|
+
if (this.#map.size > this.limit) {
|
|
183
|
+
const oldest = this.#map.keys().next();
|
|
184
|
+
if (!oldest.done) this.#map.delete(oldest.value);
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
delete(key: K): void {
|
|
189
|
+
this.#map.delete(key);
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
clear(): void {
|
|
193
|
+
this.#map.clear();
|
|
194
|
+
}
|
|
195
|
+
}
|
package/src/v8/draft.ts
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Draft pointers (see /next/api-reference#draft-pointers): the string
|
|
3
|
+
* `<host[:port]><path[?query]>@<version>` that names a draft, and the two
|
|
4
|
+
* helpers that carry one from a `?__draft=` link into a cookie.
|
|
5
|
+
*/
|
|
6
|
+
import type { DraftPointer } from "./types";
|
|
7
|
+
|
|
8
|
+
/** The draft cookie's name, for frameworks whose cookie API has no Request (Next.js `cookies()`). */
|
|
9
|
+
export const DRAFT_COOKIE = "deco-draft";
|
|
10
|
+
|
|
11
|
+
const DRAFT_PARAM = "__draft";
|
|
12
|
+
const DRAFT_OFF = "off";
|
|
13
|
+
|
|
14
|
+
/** Lowercase DNS name; a single label (`localhost`) is allowed. */
|
|
15
|
+
const HOST_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
|
|
16
|
+
const PORT_RE = /^[0-9]{1,5}$/;
|
|
17
|
+
const VERSION_RE = /^[A-Za-z0-9._-]{1,64}$/;
|
|
18
|
+
/** Rooted path with an optional query; no `@`, `#`, whitespace or scheme characters. */
|
|
19
|
+
const PATH_RE = /^\/[A-Za-z0-9/_.%~=&?-]*$/;
|
|
20
|
+
const MAX_POINTER_LENGTH = 4096;
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Parses a pointer, strictly: `null` on a scheme, a stray `@`, an unrooted
|
|
24
|
+
* path, an odd character in the host or version, or a port out of range. The
|
|
25
|
+
* host is lowercased (DNS names are case-insensitive); path and version are
|
|
26
|
+
* kept as they are.
|
|
27
|
+
*/
|
|
28
|
+
export function parseDraftPointer(raw: string | null | undefined): DraftPointer | null {
|
|
29
|
+
if (typeof raw !== "string" || raw.length === 0 || raw.length > MAX_POINTER_LENGTH) return null;
|
|
30
|
+
const at = raw.lastIndexOf("@");
|
|
31
|
+
if (at <= 0) return null;
|
|
32
|
+
const version = raw.slice(at + 1);
|
|
33
|
+
if (!VERSION_RE.test(version)) return null;
|
|
34
|
+
|
|
35
|
+
const location = raw.slice(0, at);
|
|
36
|
+
const slash = location.indexOf("/");
|
|
37
|
+
if (slash <= 0) return null;
|
|
38
|
+
const path = location.slice(slash);
|
|
39
|
+
if (!PATH_RE.test(path) || path.startsWith("//")) return null;
|
|
40
|
+
|
|
41
|
+
const host = normalizeHost(location.slice(0, slash));
|
|
42
|
+
return host === null ? null : { host, path, version };
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Builds a pointer from its parts: the inverse of {@link parseDraftPointer}.
|
|
47
|
+
* Throws a `TypeError` when the parts can't form a pointer that parses, so a
|
|
48
|
+
* bad pointer is caught where it's built rather than where it's loaded.
|
|
49
|
+
*/
|
|
50
|
+
export function formatDraftPointer(pointer: DraftPointer): string {
|
|
51
|
+
const raw = `${pointer.host}${pointer.path}@${pointer.version}`;
|
|
52
|
+
const parsed = parseDraftPointer(raw);
|
|
53
|
+
if (parsed === null || parsed.path !== pointer.path || parsed.version !== pointer.version) {
|
|
54
|
+
throw new TypeError(`invalid draft pointer parts: ${JSON.stringify(pointer)}`);
|
|
55
|
+
}
|
|
56
|
+
return `${parsed.host}${parsed.path}@${parsed.version}`;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function normalizeHost(authority: string): string | null {
|
|
60
|
+
const parts = authority.toLowerCase().split(":");
|
|
61
|
+
if (parts.length > 2) return null;
|
|
62
|
+
const [host, port] = parts;
|
|
63
|
+
if (!host || !HOST_RE.test(host)) return null;
|
|
64
|
+
if (port === undefined) return host;
|
|
65
|
+
if (!PORT_RE.test(port) || Number(port) > 65535) return null;
|
|
66
|
+
return `${host}:${port}`;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** Anything with a `url` and `headers`: a fetch `Request`, a `NextRequest`, a framework wrapper. */
|
|
70
|
+
export type RequestLike = Request | { url: string; headers: Headers };
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* The draft pointer a request carries: `?__draft=` from the URL first, then
|
|
74
|
+
* the `deco-draft` cookie. `null` when neither is present, or when the URL
|
|
75
|
+
* says `?__draft=off`. The value is returned as is; `cms.forDraft` validates it.
|
|
76
|
+
*/
|
|
77
|
+
export function draftPointer(request: RequestLike): string | null {
|
|
78
|
+
const param = draftParam(request);
|
|
79
|
+
if (param === DRAFT_OFF) return null;
|
|
80
|
+
if (param) return param;
|
|
81
|
+
const cookie = readCookie(request.headers.get("cookie"), DRAFT_COOKIE);
|
|
82
|
+
return cookie && cookie !== DRAFT_OFF ? cookie : null;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* The `Set-Cookie` value for a request whose URL carries `?__draft=`: one that
|
|
87
|
+
* stores the pointer, or one that expires the cookie when the value is `off`
|
|
88
|
+
* (how the site editor ends a preview). `null` on every other request, and for
|
|
89
|
+
* a pointer that doesn't parse, so garbage never lands in the cookie.
|
|
90
|
+
*
|
|
91
|
+
* The site editor previews your site inside a cross-site iframe, so the cookie
|
|
92
|
+
* is `Secure; SameSite=None; Partitioned` (CHIPS): `SameSite=Lax` would never
|
|
93
|
+
* be sent there. `HttpOnly` keeps page scripts from reading the pointer.
|
|
94
|
+
*/
|
|
95
|
+
export function draftCookie(request: RequestLike): string | null {
|
|
96
|
+
const param = draftParam(request);
|
|
97
|
+
if (!param) return null;
|
|
98
|
+
if (param === DRAFT_OFF) return serializeCookie("", ["Max-Age=0"]);
|
|
99
|
+
if (parseDraftPointer(param) === null) return null;
|
|
100
|
+
return serializeCookie(encodeURIComponent(param), []);
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
function serializeCookie(value: string, extra: string[]): string {
|
|
104
|
+
return [
|
|
105
|
+
`${DRAFT_COOKIE}=${value}`,
|
|
106
|
+
"Path=/",
|
|
107
|
+
...extra,
|
|
108
|
+
"HttpOnly",
|
|
109
|
+
"Secure",
|
|
110
|
+
"SameSite=None",
|
|
111
|
+
"Partitioned",
|
|
112
|
+
].join("; ");
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
function draftParam(request: RequestLike): string | null {
|
|
116
|
+
try {
|
|
117
|
+
return new URL(request.url, "http://localhost").searchParams.get(DRAFT_PARAM);
|
|
118
|
+
} catch {
|
|
119
|
+
return null;
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
function readCookie(header: string | null, name: string): string | null {
|
|
124
|
+
if (!header) return null;
|
|
125
|
+
for (const part of header.split(";")) {
|
|
126
|
+
const eq = part.indexOf("=");
|
|
127
|
+
if (eq === -1 || part.slice(0, eq).trim() !== name) continue;
|
|
128
|
+
const value = part.slice(eq + 1).trim();
|
|
129
|
+
try {
|
|
130
|
+
return decodeURIComponent(value);
|
|
131
|
+
} catch {
|
|
132
|
+
return null;
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
return null;
|
|
136
|
+
}
|
package/src/v8/errors.ts
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import type { CMSError, CMSErrorCode } from "./types";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The concrete {@link CMSError}. It extends `Error` so a lazy block can reject
|
|
5
|
+
* with it (and a stack trace survives), while still satisfying the plain
|
|
6
|
+
* `{ code, message, path, cause }` shape the API documents.
|
|
7
|
+
*/
|
|
8
|
+
export class ResolutionError extends Error implements CMSError {
|
|
9
|
+
readonly code: CMSErrorCode;
|
|
10
|
+
readonly path: (string | number)[];
|
|
11
|
+
override readonly cause?: unknown;
|
|
12
|
+
|
|
13
|
+
constructor(code: CMSErrorCode, message: string, path: (string | number)[], cause?: unknown) {
|
|
14
|
+
super(message);
|
|
15
|
+
this.name = "CMSError";
|
|
16
|
+
this.code = code;
|
|
17
|
+
this.path = path;
|
|
18
|
+
if (cause !== undefined) this.cause = cause;
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export function isResolutionError(value: unknown): value is ResolutionError {
|
|
23
|
+
return value instanceof ResolutionError;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
function describe(cause: unknown): string {
|
|
27
|
+
if (cause instanceof Error) return cause.message;
|
|
28
|
+
try {
|
|
29
|
+
return String(cause);
|
|
30
|
+
} catch {
|
|
31
|
+
return "unknown error";
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export const errors = {
|
|
36
|
+
notFound: (name: string) =>
|
|
37
|
+
new ResolutionError("NOT_FOUND", `no saved block named "${name}"`, []),
|
|
38
|
+
|
|
39
|
+
unknownBlock: (type: string, path: (string | number)[]) =>
|
|
40
|
+
new ResolutionError(
|
|
41
|
+
"UNKNOWN_BLOCK",
|
|
42
|
+
`"${type}" is neither a type in the block map nor a saved block`,
|
|
43
|
+
path,
|
|
44
|
+
),
|
|
45
|
+
|
|
46
|
+
cycle: (chain: string[]) =>
|
|
47
|
+
new ResolutionError("CYCLE", `saved blocks refer to each other: ${chain.join(" → ")}`, chain),
|
|
48
|
+
|
|
49
|
+
blockFailed: (type: string, path: (string | number)[], cause: unknown) =>
|
|
50
|
+
new ResolutionError("BLOCK_FAILED", `block "${type}" failed: ${describe(cause)}`, path, cause),
|
|
51
|
+
|
|
52
|
+
loaderFailed: (message: string, cause?: unknown) =>
|
|
53
|
+
new ResolutionError(
|
|
54
|
+
"LOADER_FAILED",
|
|
55
|
+
cause === undefined ? message : `${message}: ${describe(cause)}`,
|
|
56
|
+
[],
|
|
57
|
+
cause,
|
|
58
|
+
),
|
|
59
|
+
};
|