@decocms/blocks 8.0.0 → 8.1.0-next.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (220) hide show
  1. package/bin/deco.js +13 -0
  2. package/package.json +32 -82
  3. package/src/index.ts +35 -8
  4. package/src/protocol/assets.ts +124 -0
  5. package/src/protocol/canonical.ts +7 -0
  6. package/src/protocol/ciphertext.ts +6 -0
  7. package/src/protocol/client.ts +170 -0
  8. package/src/protocol/conformance/cases/assets.ts +81 -0
  9. package/src/protocol/conformance/cases/guards.ts +314 -0
  10. package/src/protocol/conformance/cases/reads.ts +168 -0
  11. package/src/protocol/conformance/cases/types.ts +9 -0
  12. package/src/protocol/conformance/cases/wire.ts +138 -0
  13. package/src/protocol/conformance/cases/writes.ts +345 -0
  14. package/src/protocol/conformance/contentHashFixtures.ts +79 -0
  15. package/src/protocol/conformance/context.ts +222 -0
  16. package/src/protocol/conformance/index.ts +140 -0
  17. package/src/protocol/errors.ts +142 -0
  18. package/src/protocol/index.ts +39 -0
  19. package/src/protocol/keys.ts +279 -0
  20. package/src/protocol/params.ts +67 -0
  21. package/src/protocol/secrets.ts +231 -0
  22. package/src/protocol/server/assets.ts +119 -0
  23. package/src/protocol/server/auth.ts +49 -0
  24. package/src/protocol/server/bodyCache.ts +84 -0
  25. package/src/protocol/server/content.ts +175 -0
  26. package/src/protocol/server/core.ts +112 -0
  27. package/src/protocol/server/handler.ts +102 -0
  28. package/src/protocol/server/http.ts +139 -0
  29. package/src/protocol/server/index.ts +11 -0
  30. package/src/protocol/server/methods/apply.ts +341 -0
  31. package/src/protocol/server/methods/read.ts +156 -0
  32. package/src/protocol/server/rpc.ts +136 -0
  33. package/src/protocol/storage/fs/hash.ts +21 -0
  34. package/src/protocol/storage/fs/index.ts +338 -0
  35. package/src/protocol/storage/fs/lock.ts +68 -0
  36. package/src/protocol/storage/fs/transaction.ts +183 -0
  37. package/src/protocol/storage/fs/unsupported.ts +15 -0
  38. package/src/protocol/storage/memory.ts +238 -0
  39. package/src/protocol/storage.ts +182 -0
  40. package/src/protocol/types.ts +172 -0
  41. package/src/v8/analytics.ts +50 -0
  42. package/src/v8/background.ts +107 -0
  43. package/src/v8/builtins/data.ts +23 -0
  44. package/src/v8/builtins/index.ts +26 -0
  45. package/src/v8/builtins/lazy.ts +23 -0
  46. package/src/v8/builtins/legacy.ts +65 -0
  47. package/src/v8/builtins/matchers.ts +31 -0
  48. package/src/v8/builtins/multivariate.ts +25 -0
  49. package/src/v8/builtins/secret.ts +82 -0
  50. package/src/v8/canonical.ts +117 -0
  51. package/src/v8/ciphertext.ts +158 -0
  52. package/src/v8/cli/builtins.ts +20 -0
  53. package/src/v8/cli/check/index.ts +774 -0
  54. package/src/v8/cli/check/messages.ts +168 -0
  55. package/src/v8/cli/content.ts +287 -0
  56. package/src/v8/cli/index.ts +17 -0
  57. package/src/v8/cli/log.ts +18 -0
  58. package/src/v8/cli/main.ts +12 -0
  59. package/src/v8/cli/root.ts +66 -0
  60. package/src/v8/cli/run.ts +236 -0
  61. package/src/v8/cli/schema/builtinSchemas.ts +236 -0
  62. package/src/v8/cli/schema/generate.ts +507 -0
  63. package/src/v8/cli/schema/index.ts +63 -0
  64. package/src/v8/cli/schema/tsProgram.ts +497 -0
  65. package/src/v8/cli/schema/typeToSchema.ts +689 -0
  66. package/src/v8/cli/serve/server.ts +303 -0
  67. package/src/v8/cli/watch.ts +86 -0
  68. package/src/v8/client.ts +147 -0
  69. package/src/v8/cms.ts +237 -0
  70. package/src/v8/content.ts +195 -0
  71. package/src/v8/draft.ts +136 -0
  72. package/src/v8/errors.ts +59 -0
  73. package/src/v8/fetch.ts +133 -0
  74. package/src/v8/identity.ts +65 -0
  75. package/src/v8/index.ts +39 -0
  76. package/src/v8/json.ts +74 -0
  77. package/src/v8/matchRoute.ts +204 -0
  78. package/src/v8/remoteLoader.ts +282 -0
  79. package/src/v8/resolver.ts +278 -0
  80. package/src/v8/secrets.ts +17 -0
  81. package/src/v8/telemetry.ts +533 -0
  82. package/src/v8/types.ts +240 -0
  83. package/src/cms/applySectionConventions.ts +0 -124
  84. package/src/cms/blockSource.test.ts +0 -76
  85. package/src/cms/blockSource.ts +0 -191
  86. package/src/cms/client.browserBundle.test.ts +0 -44
  87. package/src/cms/client.ts +0 -80
  88. package/src/cms/draftSource.test.ts +0 -343
  89. package/src/cms/draftSource.ts +0 -362
  90. package/src/cms/index.ts +0 -151
  91. package/src/cms/layoutCacheRace.test.ts +0 -181
  92. package/src/cms/loadDecofileDirectory.test.ts +0 -109
  93. package/src/cms/loadDecofileDirectory.ts +0 -89
  94. package/src/cms/loader.test.ts +0 -200
  95. package/src/cms/loader.ts +0 -304
  96. package/src/cms/registry.test.ts +0 -110
  97. package/src/cms/registry.ts +0 -242
  98. package/src/cms/resolve.test.ts +0 -980
  99. package/src/cms/resolve.ts +0 -2282
  100. package/src/cms/schema.test.ts +0 -356
  101. package/src/cms/schema.ts +0 -1215
  102. package/src/cms/sectionLoaderContext.test.ts +0 -111
  103. package/src/cms/sectionLoaderContext.ts +0 -113
  104. package/src/cms/sectionLoaders.test.ts +0 -533
  105. package/src/cms/sectionLoaders.ts +0 -636
  106. package/src/cms/sectionMixins.test.ts +0 -167
  107. package/src/cms/sectionMixins.ts +0 -153
  108. package/src/cms/stickyFlags.test.ts +0 -117
  109. package/src/flags/audience.ts +0 -56
  110. package/src/flags/everyone.ts +0 -29
  111. package/src/flags/flag.ts +0 -15
  112. package/src/flags/flags.test.ts +0 -148
  113. package/src/flags/multivariate/image.ts +0 -11
  114. package/src/flags/multivariate/message.ts +0 -11
  115. package/src/flags/multivariate/page.ts +0 -16
  116. package/src/flags/multivariate/section.ts +0 -16
  117. package/src/flags/multivariate.ts +0 -1
  118. package/src/flags/types.ts +0 -59
  119. package/src/flags/utils/multivariate.ts +0 -20
  120. package/src/hooks/Image.test.ts +0 -100
  121. package/src/hooks/Image.tsx +0 -250
  122. package/src/hooks/JsonLd.tsx +0 -353
  123. package/src/hooks/LazySection.tsx +0 -121
  124. package/src/hooks/LiveControls.tsx +0 -122
  125. package/src/hooks/Picture.tsx +0 -127
  126. package/src/hooks/RenderSection.test.tsx +0 -81
  127. package/src/hooks/RenderSection.tsx +0 -91
  128. package/src/hooks/SectionErrorFallback.tsx +0 -97
  129. package/src/hooks/index.ts +0 -30
  130. package/src/matchers/builtins.test.ts +0 -318
  131. package/src/matchers/builtins.ts +0 -459
  132. package/src/matchers/countryNames.ts +0 -104
  133. package/src/matchers/override.test.ts +0 -205
  134. package/src/matchers/override.ts +0 -136
  135. package/src/matchers/posthog.ts +0 -154
  136. package/src/middleware/decoState.ts +0 -55
  137. package/src/middleware/healthMetrics.ts +0 -133
  138. package/src/middleware/hydrationContext.test.ts +0 -61
  139. package/src/middleware/hydrationContext.ts +0 -79
  140. package/src/middleware/index.ts +0 -88
  141. package/src/middleware/liveness.ts +0 -21
  142. package/src/middleware/observability.test.ts +0 -242
  143. package/src/middleware/observability.ts +0 -643
  144. package/src/middleware/validateSection.test.ts +0 -147
  145. package/src/middleware/validateSection.ts +0 -100
  146. package/src/sdk/abTesting.test.ts +0 -326
  147. package/src/sdk/abTesting.ts +0 -499
  148. package/src/sdk/analytics.ts +0 -77
  149. package/src/sdk/cacheHeaders.test.ts +0 -115
  150. package/src/sdk/cacheHeaders.ts +0 -433
  151. package/src/sdk/cachedLoader.test.ts +0 -122
  152. package/src/sdk/cachedLoader.ts +0 -503
  153. package/src/sdk/cachedLoaderModule.test.ts +0 -209
  154. package/src/sdk/clx.ts +0 -5
  155. package/src/sdk/cn.test.ts +0 -34
  156. package/src/sdk/cn.ts +0 -28
  157. package/src/sdk/composite.test.ts +0 -121
  158. package/src/sdk/composite.ts +0 -114
  159. package/src/sdk/cookie.test.ts +0 -108
  160. package/src/sdk/cookie.ts +0 -129
  161. package/src/sdk/crypto.ts +0 -185
  162. package/src/sdk/csp.ts +0 -59
  163. package/src/sdk/detectDevice.ts +0 -45
  164. package/src/sdk/djb2.ts +0 -20
  165. package/src/sdk/encoding.test.ts +0 -71
  166. package/src/sdk/encoding.ts +0 -47
  167. package/src/sdk/env.test.ts +0 -33
  168. package/src/sdk/env.ts +0 -54
  169. package/src/sdk/flags.test.ts +0 -91
  170. package/src/sdk/flags.ts +0 -108
  171. package/src/sdk/http.test.ts +0 -71
  172. package/src/sdk/http.ts +0 -124
  173. package/src/sdk/index.ts +0 -90
  174. package/src/sdk/inflightTimeout.test.ts +0 -35
  175. package/src/sdk/inflightTimeout.ts +0 -53
  176. package/src/sdk/instrumentedFetch.test.ts +0 -559
  177. package/src/sdk/instrumentedFetch.ts +0 -339
  178. package/src/sdk/invoke.test.ts +0 -115
  179. package/src/sdk/invoke.ts +0 -298
  180. package/src/sdk/logger.test.ts +0 -432
  181. package/src/sdk/logger.ts +0 -304
  182. package/src/sdk/mergeCacheControl.ts +0 -150
  183. package/src/sdk/normalizeUrls.ts +0 -91
  184. package/src/sdk/observability.ts +0 -109
  185. package/src/sdk/otel.test.ts +0 -526
  186. package/src/sdk/otel.ts +0 -1012
  187. package/src/sdk/otelAdapters/clickhouseCollector.ts +0 -65
  188. package/src/sdk/otelAdapters.test.ts +0 -89
  189. package/src/sdk/otelAdapters.ts +0 -144
  190. package/src/sdk/otelHttpLog.test.ts +0 -457
  191. package/src/sdk/otelHttpLog.ts +0 -419
  192. package/src/sdk/otelHttpMeter.test.ts +0 -292
  193. package/src/sdk/otelHttpMeter.ts +0 -506
  194. package/src/sdk/otelHttpTracer.test.ts +0 -474
  195. package/src/sdk/otelHttpTracer.ts +0 -543
  196. package/src/sdk/redirects.ts +0 -228
  197. package/src/sdk/requestContext.ts +0 -281
  198. package/src/sdk/requestContextStorage.browser.test.ts +0 -29
  199. package/src/sdk/requestContextStorage.browser.ts +0 -43
  200. package/src/sdk/requestContextStorage.ts +0 -35
  201. package/src/sdk/retry.ts +0 -45
  202. package/src/sdk/serverTimings.ts +0 -68
  203. package/src/sdk/signal.ts +0 -42
  204. package/src/sdk/sitemap.ts +0 -160
  205. package/src/sdk/urlRedaction.test.ts +0 -73
  206. package/src/sdk/urlRedaction.ts +0 -82
  207. package/src/sdk/urlUtils.ts +0 -134
  208. package/src/sdk/useDevice.test.ts +0 -130
  209. package/src/sdk/useDevice.ts +0 -89
  210. package/src/sdk/useDeviceContext.tsx +0 -108
  211. package/src/sdk/useId.ts +0 -7
  212. package/src/sdk/useScript.test.ts +0 -128
  213. package/src/sdk/useScript.ts +0 -210
  214. package/src/sdk/useSuggestions.test.ts +0 -230
  215. package/src/sdk/useSuggestions.ts +0 -188
  216. package/src/sdk/wrapCaughtErrors.ts +0 -107
  217. package/src/setup.ts +0 -120
  218. package/src/types/index.ts +0 -53
  219. package/src/types/widgets.ts +0 -14
  220. 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
+ }
@@ -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
+ }
@@ -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
+ };