@decocms/blocks 7.72.0 → 8.0.0-next.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (148) hide show
  1. package/bin/deco.js +13 -0
  2. package/package.json +32 -3
  3. package/src/cms/schema.ts +1 -1
  4. package/src/hooks/LiveControls.tsx +2 -0
  5. package/src/hooks/useLoadMore.ts +2 -0
  6. package/src/index.ts +37 -0
  7. package/src/protocol/assets.ts +124 -0
  8. package/src/protocol/canonical.ts +7 -0
  9. package/src/protocol/ciphertext.ts +6 -0
  10. package/src/protocol/client.ts +170 -0
  11. package/src/protocol/conformance/cases/assets.ts +81 -0
  12. package/src/protocol/conformance/cases/guards.ts +314 -0
  13. package/src/protocol/conformance/cases/reads.ts +168 -0
  14. package/src/protocol/conformance/cases/types.ts +9 -0
  15. package/src/protocol/conformance/cases/wire.ts +138 -0
  16. package/src/protocol/conformance/cases/writes.ts +345 -0
  17. package/src/protocol/conformance/contentHashFixtures.ts +79 -0
  18. package/src/protocol/conformance/context.ts +222 -0
  19. package/src/protocol/conformance/index.ts +140 -0
  20. package/src/protocol/errors.ts +142 -0
  21. package/src/protocol/index.ts +39 -0
  22. package/src/protocol/keys.ts +279 -0
  23. package/src/protocol/params.ts +67 -0
  24. package/src/protocol/secrets.ts +231 -0
  25. package/src/protocol/server/assets.ts +119 -0
  26. package/src/protocol/server/auth.ts +49 -0
  27. package/src/protocol/server/bodyCache.ts +84 -0
  28. package/src/protocol/server/content.ts +175 -0
  29. package/src/protocol/server/core.ts +112 -0
  30. package/src/protocol/server/handler.ts +102 -0
  31. package/src/protocol/server/http.ts +139 -0
  32. package/src/protocol/server/index.ts +11 -0
  33. package/src/protocol/server/methods/apply.ts +341 -0
  34. package/src/protocol/server/methods/read.ts +156 -0
  35. package/src/protocol/server/rpc.ts +136 -0
  36. package/src/protocol/storage/fs/hash.ts +21 -0
  37. package/src/protocol/storage/fs/index.ts +338 -0
  38. package/src/protocol/storage/fs/lock.ts +68 -0
  39. package/src/protocol/storage/fs/transaction.ts +183 -0
  40. package/src/protocol/storage/fs/unsupported.ts +15 -0
  41. package/src/protocol/storage/memory.ts +238 -0
  42. package/src/protocol/storage.ts +182 -0
  43. package/src/protocol/types.ts +172 -0
  44. package/src/v8/analytics.ts +50 -0
  45. package/src/v8/background.ts +107 -0
  46. package/src/v8/builtins/data.ts +23 -0
  47. package/src/v8/builtins/index.ts +26 -0
  48. package/src/v8/builtins/lazy.ts +23 -0
  49. package/src/v8/builtins/legacy.ts +65 -0
  50. package/src/v8/builtins/matchers.ts +31 -0
  51. package/src/v8/builtins/multivariate.ts +25 -0
  52. package/src/v8/builtins/secret.ts +82 -0
  53. package/src/v8/canonical.ts +117 -0
  54. package/src/v8/ciphertext.ts +158 -0
  55. package/src/v8/cli/builtins.ts +20 -0
  56. package/src/v8/cli/check/index.ts +774 -0
  57. package/src/v8/cli/check/messages.ts +168 -0
  58. package/src/v8/cli/content.ts +287 -0
  59. package/src/v8/cli/index.ts +17 -0
  60. package/src/v8/cli/log.ts +18 -0
  61. package/src/v8/cli/main.ts +12 -0
  62. package/src/v8/cli/root.ts +66 -0
  63. package/src/v8/cli/run.ts +236 -0
  64. package/src/v8/cli/schema/builtinSchemas.ts +236 -0
  65. package/src/v8/cli/schema/generate.ts +507 -0
  66. package/src/v8/cli/schema/index.ts +63 -0
  67. package/src/v8/cli/schema/tsProgram.ts +497 -0
  68. package/src/v8/cli/schema/typeToSchema.ts +689 -0
  69. package/src/v8/cli/serve/server.ts +303 -0
  70. package/src/v8/cli/watch.ts +86 -0
  71. package/src/v8/client.ts +147 -0
  72. package/src/v8/cms.ts +237 -0
  73. package/src/v8/content.ts +195 -0
  74. package/src/v8/draft.ts +136 -0
  75. package/src/v8/errors.ts +59 -0
  76. package/src/v8/fetch.ts +152 -0
  77. package/src/v8/identity.ts +65 -0
  78. package/src/v8/index.ts +39 -0
  79. package/src/v8/json.ts +74 -0
  80. package/src/v8/matchRoute.ts +204 -0
  81. package/src/v8/remoteLoader.ts +282 -0
  82. package/src/v8/resolver.ts +278 -0
  83. package/src/v8/secrets.ts +17 -0
  84. package/src/v8/telemetry.ts +533 -0
  85. package/src/v8/types.ts +240 -0
  86. package/src/cms/blockSource.test.ts +0 -76
  87. package/src/cms/client.browserBundle.test.ts +0 -44
  88. package/src/cms/deferredTrigger.test.ts +0 -32
  89. package/src/cms/draftSource.test.ts +0 -519
  90. package/src/cms/layoutCacheRace.test.ts +0 -181
  91. package/src/cms/loadDecofileDirectory.test.ts +0 -109
  92. package/src/cms/loader.test.ts +0 -557
  93. package/src/cms/registry.test.ts +0 -110
  94. package/src/cms/renderJson.test.ts +0 -167
  95. package/src/cms/resolve.test.ts +0 -1492
  96. package/src/cms/schema.test.ts +0 -356
  97. package/src/cms/sectionLoaderContext.test.ts +0 -111
  98. package/src/cms/sectionLoaders.test.ts +0 -625
  99. package/src/cms/sectionMixins.test.ts +0 -167
  100. package/src/cms/stickyFlags.test.ts +0 -117
  101. package/src/flags/flags.test.ts +0 -148
  102. package/src/hooks/Image.test.ts +0 -239
  103. package/src/hooks/RenderSection.test.tsx +0 -81
  104. package/src/hooks/Stats.test.ts +0 -112
  105. package/src/hooks/useLoadMore.test.ts +0 -205
  106. package/src/matchers/builtins.test.ts +0 -318
  107. package/src/matchers/override.test.ts +0 -205
  108. package/src/middleware/hydrationContext.test.ts +0 -61
  109. package/src/middleware/observability.test.ts +0 -335
  110. package/src/middleware/validateSection.test.ts +0 -147
  111. package/src/preview/DraftPreviewBadge.render.test.tsx +0 -67
  112. package/src/preview/DraftPreviewBadge.test.ts +0 -55
  113. package/src/sdk/abTesting.test.ts +0 -381
  114. package/src/sdk/cacheHeaders.test.ts +0 -258
  115. package/src/sdk/cacheStorage.test.ts +0 -242
  116. package/src/sdk/cachedLoader.test.ts +0 -122
  117. package/src/sdk/cachedLoaderMaxBytes.test.ts +0 -23
  118. package/src/sdk/cachedLoaderModule.test.ts +0 -209
  119. package/src/sdk/cachedLoaderSizeMetric.test.ts +0 -93
  120. package/src/sdk/cn.test.ts +0 -34
  121. package/src/sdk/composite.test.ts +0 -121
  122. package/src/sdk/cookie.test.ts +0 -108
  123. package/src/sdk/crypto.test.ts +0 -65
  124. package/src/sdk/deepOmit.test.ts +0 -45
  125. package/src/sdk/encoding.test.ts +0 -71
  126. package/src/sdk/env.test.ts +0 -33
  127. package/src/sdk/experiments.test.ts +0 -328
  128. package/src/sdk/fetchCache.test.ts +0 -164
  129. package/src/sdk/flags.test.ts +0 -91
  130. package/src/sdk/http.test.ts +0 -71
  131. package/src/sdk/inflightTimeout.test.ts +0 -35
  132. package/src/sdk/instrumentedFetch.test.ts +0 -559
  133. package/src/sdk/invoke.test.ts +0 -115
  134. package/src/sdk/logger.test.ts +0 -432
  135. package/src/sdk/otel.test.ts +0 -691
  136. package/src/sdk/otelAdapters.test.ts +0 -89
  137. package/src/sdk/otelHttpLog.test.ts +0 -457
  138. package/src/sdk/otelHttpMeter.test.ts +0 -395
  139. package/src/sdk/otelHttpTracer.test.ts +0 -474
  140. package/src/sdk/replaceStream.test.ts +0 -117
  141. package/src/sdk/requestContextStorage.browser.test.ts +0 -29
  142. package/src/sdk/splitExactRedirects.test.ts +0 -154
  143. package/src/sdk/urlRedaction.test.ts +0 -73
  144. package/src/sdk/urlUtils.test.ts +0 -34
  145. package/src/sdk/useDevice.test.ts +0 -130
  146. package/src/sdk/useScript.test.ts +0 -128
  147. package/src/sdk/useSuggestions.test.ts +0 -230
  148. package/tsconfig.json +0 -7
@@ -0,0 +1,303 @@
1
+ /**
2
+ * `deco serve`: the local server the site editor uses to edit the files on
3
+ * this machine (spec: cli › deco serve; content-protocol › The local server).
4
+ *
5
+ * The content protocol is `@decocms/blocks/protocol`'s `createContentHandler`
6
+ * (at `/rpc`) and `createAssetHandler` (at `/assets/<name>`) over the
7
+ * filesystem storage; they own the bearer token, `Content-Type`, size limits
8
+ * and upload rules. This file is the Node HTTP layer and the checks that
9
+ * depend on where it runs:
10
+ *
11
+ * - Listens on 127.0.0.1 unless `--host` says otherwise (with a warning).
12
+ * - Browser requests are accepted only from the site editor's origins and
13
+ * `--allow-origin`; CORS and Chrome's local-network preflights are answered.
14
+ * - Any `Host` other than the server's own address is refused (DNS rebinding).
15
+ * - Every save regenerates `.deco/blocks.gen.ts`.
16
+ */
17
+ import { randomBytes } from "node:crypto";
18
+ import fs from "node:fs";
19
+ import http from "node:http";
20
+ import type { AddressInfo } from "node:net";
21
+ import path from "node:path";
22
+ import { Readable } from "node:stream";
23
+ import { ErrorCode } from "../../../protocol/errors";
24
+ import { blockNameFromFile } from "../../../protocol/keys";
25
+ import { createContentHandler } from "../../../protocol/server";
26
+ import { createAssetHandler } from "../../../protocol/server/assets";
27
+ import type { ContentStorage } from "../../../protocol/storage";
28
+ import { createFsStorage } from "../../../protocol/storage/fs";
29
+ import { readSavedBlocks, writeContent } from "../content";
30
+ import { consoleReporter, type Reporter } from "../log";
31
+ import { CliError, decoPaths, findDecoRoot, packageVersion } from "../root";
32
+
33
+ /** The site editor's origins: the browser origins allowed by default. */
34
+ const STUDIO_ORIGINS = [
35
+ "https://studio.decocms.com",
36
+ "https://admin.decocms.com",
37
+ "https://admin.deco.cx",
38
+ ];
39
+
40
+ /** Where the site editor link points. */
41
+ const STUDIO_ORIGIN = STUDIO_ORIGINS[0];
42
+
43
+ const DEFAULT_PORT = 4545;
44
+ const DEFAULT_HOST = "127.0.0.1";
45
+
46
+ const LOOPBACK = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
47
+
48
+ export interface ServeOptions {
49
+ root?: string;
50
+ cwd?: string;
51
+ port?: number;
52
+ host?: string;
53
+ /** The local app the site editor previews: `localhost:8001` or a full loopback URL. */
54
+ preview?: string;
55
+ token?: string;
56
+ allowOrigins?: string[];
57
+ /** The upload folder, relative to the folder that contains `.deco`. */
58
+ assets?: string;
59
+ readOnly?: boolean;
60
+ reporter?: Reporter;
61
+ env?: NodeJS.ProcessEnv;
62
+ }
63
+
64
+ export interface RunningServer {
65
+ /** The content protocol endpoint, `http://127.0.0.1:4545/rpc`. */
66
+ endpoint: string;
67
+ token: string;
68
+ siteEditorUrl: string;
69
+ port: number;
70
+ close(): Promise<void>;
71
+ }
72
+
73
+ /** The app the site editor previews when `--preview` isn't given and no Vite port is set. */
74
+ export const DEFAULT_PREVIEW_URL = "http://localhost:5173";
75
+
76
+ const VITE_CONFIGS = ["vite.config.ts", "vite.config.mts", "vite.config.js", "vite.config.mjs"];
77
+
78
+ /**
79
+ * `http://localhost:<server.port>` from the app's Vite config, read as text
80
+ * (the config is never executed), or `DEFAULT_PREVIEW_URL`.
81
+ */
82
+ function defaultPreviewUrl(root: string): string {
83
+ for (const name of VITE_CONFIGS) {
84
+ let source: string;
85
+ try {
86
+ source = fs.readFileSync(path.join(root, name), "utf8");
87
+ } catch {
88
+ continue;
89
+ }
90
+ const port = /\bserver\s*:\s*\{[^}]*?\bport\s*:\s*(\d{2,5})\b/.exec(source)?.[1];
91
+ return port ? `http://localhost:${port}` : DEFAULT_PREVIEW_URL;
92
+ }
93
+ return DEFAULT_PREVIEW_URL;
94
+ }
95
+
96
+ /**
97
+ * `--preview` as a URL: a bare `host:port` gets `http://`; only http(s) on a
98
+ * loopback host, since the site editor loads it in an iframe.
99
+ */
100
+ function previewUrl(input: string): string {
101
+ const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(input) ? input : `http://${input}`;
102
+ const url = URL.canParse(withScheme) ? new URL(withScheme) : null;
103
+ if (!url || !/^https?:$/.test(url.protocol) || !LOOPBACK.has(url.hostname)) {
104
+ throw new CliError(
105
+ `--preview must be a local address such as localhost:5173 or http://127.0.0.1:3000, got ${input}`,
106
+ );
107
+ }
108
+ return url.pathname === "/" && !url.search && !url.hash ? url.origin : url.href;
109
+ }
110
+
111
+ /** Start the server; resolves once it listens. */
112
+ export async function startServer(options: ServeOptions = {}): Promise<RunningServer> {
113
+ const reporter = options.reporter ?? consoleReporter;
114
+ const env = options.env ?? process.env;
115
+ const paths = decoPaths(findDecoRoot(options));
116
+ const host = options.host ?? DEFAULT_HOST;
117
+ const requestedPort = options.port ?? DEFAULT_PORT;
118
+ const readOnly = options.readOnly ?? false;
119
+ if (options.token !== undefined && options.token.trim() === "") {
120
+ throw new CliError("--token can't be empty: pass a token, or leave it out for a random one");
121
+ }
122
+ if (options.token === undefined && env.DECO_SERVE_TOKEN?.trim() === "") {
123
+ throw new CliError(
124
+ "DECO_SERVE_TOKEN can't be empty: set a token, or unset it for a random one",
125
+ );
126
+ }
127
+ const token = options.token ?? env.DECO_SERVE_TOKEN ?? randomBytes(32).toString("base64url");
128
+ const preview = previewUrl(options.preview ?? defaultPreviewUrl(paths.root));
129
+ const allowedOrigins = new Set(
130
+ [...STUDIO_ORIGINS, ...(options.allowOrigins ?? [])].map((o) => o.replace(/\/+$/, "")),
131
+ );
132
+
133
+ if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) {
134
+ throw new CliError(`--port must be a port number, got ${requestedPort}`);
135
+ }
136
+
137
+ const fsStorage = createFsStorage({ root: paths.root, readOnly, assetsDir: options.assets });
138
+ const storage: ContentStorage = {
139
+ ...fsStorage,
140
+ async commit(attempt) {
141
+ const result = await fsStorage.commit(attempt);
142
+ if (result.status !== "committed") return result;
143
+ const names = [...Object.keys(attempt.put), ...attempt.delete].map(blockNameFromFile);
144
+ reporter.info(
145
+ `saved ${names.length} block${names.length === 1 ? "" : "s"}: ${names.join(", ")}`,
146
+ );
147
+ // Every save changes the content, so the content module's revision
148
+ // changes too (a revision is never reused for different content). An
149
+ // unchanged module isn't rewritten, so this costs nothing when it isn't.
150
+ try {
151
+ await writeContent(paths);
152
+ } catch (error) {
153
+ reporter.warn(`couldn't regenerate .deco/blocks.gen.ts: ${(error as Error).message}`);
154
+ }
155
+ return result;
156
+ },
157
+ async putAsset(name, body) {
158
+ const stored = await fsStorage.putAsset!(name, body);
159
+ reporter.info(`uploaded /assets/${stored.name}`);
160
+ return stored;
161
+ },
162
+ };
163
+ const rpc = createContentHandler(storage, {
164
+ token,
165
+ server: { name: "deco-cli", version: packageVersion() },
166
+ preview: { url: preview },
167
+ onError: (error) => reporter.warn(String((error as Error)?.message ?? error)),
168
+ });
169
+ const assets = createAssetHandler(storage, { token });
170
+
171
+ let port = requestedPort;
172
+ const allowedHosts = () => {
173
+ const hosts = new Set([`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`]);
174
+ if (!LOOPBACK.has(host)) hosts.add(`${host.includes(":") ? `[${host}]` : host}:${port}`);
175
+ return hosts;
176
+ };
177
+
178
+ const server = http.createServer(async (req, res) => {
179
+ const origin = req.headers.origin;
180
+ const cors: Record<string, string> = {};
181
+ const refuse = (status: number, code: number, message: string) => {
182
+ res.writeHead(status, { "content-type": "application/json", ...cors });
183
+ res.end(JSON.stringify({ jsonrpc: "2.0", id: null, error: { code, message } }));
184
+ };
185
+
186
+ try {
187
+ // DNS rebinding: only our own address.
188
+ if (!allowedHosts().has(String(req.headers.host ?? "").toLowerCase())) {
189
+ return refuse(403, ErrorCode.Forbidden, "unexpected Host header");
190
+ }
191
+ if (origin !== undefined) {
192
+ if (!allowedOrigins.has(origin)) {
193
+ return refuse(403, ErrorCode.Forbidden, `origin ${origin} isn't allowed`);
194
+ }
195
+ cors["access-control-allow-origin"] = origin;
196
+ cors.vary = "Origin";
197
+ }
198
+ if (req.method === "OPTIONS") {
199
+ const preflight: Record<string, string> = {
200
+ "access-control-allow-methods": "POST, PUT, OPTIONS",
201
+ "access-control-allow-headers": "authorization, content-type",
202
+ "access-control-max-age": "600",
203
+ };
204
+ // Chrome's Local Network Access / Private Network Access preflight.
205
+ if (req.headers["access-control-request-private-network"] === "true") {
206
+ preflight["access-control-allow-private-network"] = "true";
207
+ }
208
+ res.writeHead(204, { ...cors, ...preflight });
209
+ return res.end();
210
+ }
211
+
212
+ const { pathname } = new URL(req.url ?? "/", "http://localhost");
213
+ const handler =
214
+ pathname === "/rpc" ? rpc : pathname.startsWith("/assets/") ? assets : undefined;
215
+ if (!handler) return refuse(404, ErrorCode.NotFound, "not found");
216
+ const response = await handler(toRequest(req));
217
+ const headers = Object.fromEntries(response.headers);
218
+ res.writeHead(response.status, { ...headers, "cache-control": "no-store", ...cors });
219
+ res.end(Buffer.from(await response.arrayBuffer()));
220
+ } catch (error) {
221
+ refuse(500, ErrorCode.InternalError, (error as Error).message);
222
+ }
223
+ });
224
+
225
+ await new Promise<void>((resolve, reject) => {
226
+ server.once("error", (error: NodeJS.ErrnoException) =>
227
+ reject(
228
+ error.code === "EADDRINUSE"
229
+ ? new CliError(`port ${requestedPort} is in use; pass --port`)
230
+ : error,
231
+ ),
232
+ );
233
+ server.listen(requestedPort, host, () => resolve());
234
+ });
235
+ port = (server.address() as AddressInfo).port;
236
+
237
+ const displayHost = host.includes(":") ? `[${host}]` : host;
238
+ const endpoint = `http://${displayHost}:${port}/rpc`;
239
+ const siteEditorUrl = `${STUDIO_ORIGIN}/site-editor#endpoint=${encodeURIComponent(endpoint)}&token=${encodeURIComponent(token)}`;
240
+
241
+ if (!LOOPBACK.has(host)) {
242
+ reporter.warn(
243
+ `warning: listening on ${host}: other machines can reach this server (the token still applies)`,
244
+ );
245
+ }
246
+ const schemaFile = fs.existsSync(paths.schema)
247
+ ? ".deco/schema.gen.json"
248
+ : fs.existsSync(paths.legacySchema)
249
+ ? ".deco/meta.gen.json"
250
+ : "no schema: run deco schema";
251
+ const count = Object.keys(readSavedBlocks(paths.blocks).blocks).length;
252
+ const description = await storage.describe();
253
+ const label = (name: string) => name.padEnd(21);
254
+ reporter.info(`${label("Deco server")}${endpoint}`);
255
+ reporter.info(`${label("Root")}${description.root} (${schemaFile}, ${count} blocks)`);
256
+ reporter.info(
257
+ description.assets
258
+ ? `${label("Assets")}${description.assets.dir} (PUT /assets/<name>)`
259
+ : `${label("Assets")}read-only: uploads are off`,
260
+ );
261
+ reporter.info(`${label("Preview")}${preview}`);
262
+ reporter.info(`${label("Site editor")}${siteEditorUrl}`);
263
+
264
+ return {
265
+ endpoint,
266
+ token,
267
+ siteEditorUrl,
268
+ port,
269
+ close: () =>
270
+ new Promise<void>((resolve) => {
271
+ server.closeAllConnections?.();
272
+ server.close(() => resolve());
273
+ }),
274
+ };
275
+ }
276
+
277
+ /** A Node request as a fetch `Request`, its body streamed. */
278
+ function toRequest(req: http.IncomingMessage): Request {
279
+ const headers = new Headers();
280
+ for (const [key, value] of Object.entries(req.headers)) {
281
+ if (Array.isArray(value)) for (const v of value) headers.append(key, v);
282
+ else if (value !== undefined) headers.set(key, value);
283
+ }
284
+ const hasBody = req.method !== "GET" && req.method !== "HEAD";
285
+ return new Request(new URL(req.url ?? "/", "http://localhost"), {
286
+ method: req.method,
287
+ headers,
288
+ body: hasBody ? (Readable.toWeb(req) as ReadableStream<Uint8Array>) : undefined,
289
+ duplex: "half",
290
+ } as RequestInit);
291
+ }
292
+
293
+ /** `deco serve`: start, then run until interrupted. */
294
+ export async function serve(options: ServeOptions = {}): Promise<number> {
295
+ const running = await startServer(options);
296
+ await new Promise<void>((resolve) => {
297
+ const stop = () => resolve();
298
+ process.once("SIGINT", stop);
299
+ process.once("SIGTERM", stop);
300
+ });
301
+ await running.close();
302
+ return 0;
303
+ }
@@ -0,0 +1,86 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+
4
+ export interface Watcher {
5
+ close(): void;
6
+ }
7
+
8
+ /**
9
+ * Call `onChange` (debounced) when a file under `dir` that passes `filter`
10
+ * changes. `filter` gets the path relative to `dir`, with forward slashes.
11
+ * A missing `dir` is created so a later first file is seen.
12
+ */
13
+ export function watchTree(
14
+ dir: string,
15
+ filter: (relativePath: string) => boolean,
16
+ onChange: () => void,
17
+ debounceMs = 100,
18
+ ): Watcher {
19
+ fs.mkdirSync(dir, { recursive: true });
20
+ let timer: ReturnType<typeof setTimeout> | undefined;
21
+ const watcher = fs.watch(dir, { recursive: true }, (_event, filename) => {
22
+ if (filename === null) return;
23
+ const rel = String(filename).split(path.sep).join("/");
24
+ if (!filter(rel)) return;
25
+ clearTimeout(timer);
26
+ timer = setTimeout(onChange, debounceMs);
27
+ });
28
+ return {
29
+ close() {
30
+ clearTimeout(timer);
31
+ watcher.close();
32
+ },
33
+ };
34
+ }
35
+
36
+ /**
37
+ * Watch a set of single files that can change between runs (the sources a
38
+ * schema was read from outside the root). Each file's folder is watched, not
39
+ * the file, so an editor that saves by replacing the file is still seen.
40
+ * `update` swaps the set; a folder that can't be watched is skipped until the
41
+ * next update.
42
+ */
43
+ export function watchFiles(
44
+ onChange: () => void,
45
+ debounceMs = 100,
46
+ ): Watcher & { update(files: Iterable<string>): void } {
47
+ const watchers = new Map<string, fs.FSWatcher>();
48
+ let names = new Map<string, Set<string>>();
49
+ let timer: ReturnType<typeof setTimeout> | undefined;
50
+ return {
51
+ update(files) {
52
+ const next = new Map<string, Set<string>>();
53
+ for (const file of files) {
54
+ const dir = path.dirname(file);
55
+ const set = next.get(dir) ?? new Set<string>();
56
+ set.add(path.basename(file));
57
+ next.set(dir, set);
58
+ }
59
+ names = next;
60
+ for (const [dir, watcher] of watchers) {
61
+ if (!next.has(dir)) {
62
+ watcher.close();
63
+ watchers.delete(dir);
64
+ }
65
+ }
66
+ for (const dir of next.keys()) {
67
+ if (watchers.has(dir)) continue;
68
+ try {
69
+ const watcher = fs.watch(dir, (_event, filename) => {
70
+ if (filename === null || !names.get(dir)?.has(String(filename))) return;
71
+ clearTimeout(timer);
72
+ timer = setTimeout(onChange, debounceMs);
73
+ });
74
+ watchers.set(dir, watcher);
75
+ } catch {
76
+ // gone since the program read it: picked up again on the next update
77
+ }
78
+ }
79
+ },
80
+ close() {
81
+ clearTimeout(timer);
82
+ for (const watcher of watchers.values()) watcher.close();
83
+ watchers.clear();
84
+ },
85
+ };
86
+ }
@@ -0,0 +1,147 @@
1
+ /**
2
+ * A client: one revision, loaded on first use and read for the rest of its
3
+ * life, plus a memo of block results. Create one per request.
4
+ */
5
+ import { errors, isResolutionError, ResolutionError } from "./errors";
6
+ import { isBlock } from "./json";
7
+ import { Resolver } from "./resolver";
8
+ import type { ClientTelemetry } from "./telemetry";
9
+ import type {
10
+ Block,
11
+ Blocks,
12
+ Client,
13
+ CMSError,
14
+ ListOptions,
15
+ ResolveOptions,
16
+ Result,
17
+ Snapshot,
18
+ } from "./types";
19
+
20
+ interface ClientOptions {
21
+ /** Loads this client's snapshot; called at most once. */
22
+ load: () => Promise<Snapshot>;
23
+ blocks: Blocks;
24
+ /** The built-ins, with this CMS's `secret`. */
25
+ builtIns: Readonly<Blocks>;
26
+ onCollision?: (name: string) => void;
27
+ telemetry?: ClientTelemetry;
28
+ }
29
+
30
+ type Loaded = { resolver: Resolver; snapshot: Snapshot } | { error: CMSError };
31
+
32
+ export class CMSClient implements Client {
33
+ readonly #options: ClientOptions;
34
+ readonly #reported = new WeakSet<CMSError>();
35
+ #loaded: Promise<Loaded> | undefined;
36
+
37
+ constructor(options: ClientOptions) {
38
+ this.#options = options;
39
+ }
40
+
41
+ async resolve<T = unknown>(target: unknown, options: ResolveOptions = {}): Promise<Result<T>> {
42
+ const loaded = await this.#load();
43
+ if ("error" in loaded) return this.#fail(loaded.error);
44
+ const { resolver } = loaded;
45
+ const run = options.run !== false;
46
+ try {
47
+ if (typeof target === "string") {
48
+ if (resolver.entry(target) === undefined) return this.#fail(errors.notFound(target));
49
+ const value = run ? await resolver.resolveEntry(target) : resolver.expandEntry(target);
50
+ return [value as T, null];
51
+ }
52
+ const value = run
53
+ ? await resolver.resolve(target, [], [], false)
54
+ : resolver.expand(target, [], [], false);
55
+ return [value as T, null];
56
+ } catch (error) {
57
+ return this.#fail(asCMSError(error));
58
+ }
59
+ }
60
+
61
+ async list<T = Block>(type: string, options: ListOptions<T> = {}): Promise<Result<T[]>> {
62
+ const loaded = await this.#load();
63
+ if ("error" in loaded) return this.#fail(loaded.error);
64
+ const { resolver, snapshot } = loaded;
65
+ const wanted = resolver.canonicalType(type);
66
+ const names = Object.keys(snapshot.blocks)
67
+ .sort(byCodeUnit)
68
+ .filter((name) => {
69
+ const entry = snapshot.blocks[name];
70
+ return isBlock(entry) && resolver.canonicalType(entry.__resolveType) === wanted;
71
+ });
72
+
73
+ let entries: T[];
74
+ try {
75
+ const values = await Promise.all(
76
+ names.map((name) =>
77
+ options.run === true
78
+ ? resolver.resolveEntry(name).catch((error) => {
79
+ throw atEntry(name, error);
80
+ })
81
+ : resolver.expandEntry(name),
82
+ ),
83
+ );
84
+ entries = values.filter((value) => value !== undefined) as T[];
85
+ } catch (error) {
86
+ return this.#fail(asCMSError(error));
87
+ }
88
+
89
+ if (options.where) entries = entries.filter(options.where);
90
+ if (options.sort) entries = [...entries].sort(options.sort);
91
+ if (typeof options.limit === "number" && options.limit >= 0) {
92
+ entries = entries.slice(0, Math.floor(options.limit));
93
+ }
94
+ return [entries, null];
95
+ }
96
+
97
+ async revision(): Promise<string> {
98
+ const loaded = await this.#load();
99
+ if ("error" in loaded) throw loaded.error;
100
+ return loaded.snapshot.revision;
101
+ }
102
+
103
+ #load(): Promise<Loaded> {
104
+ this.#loaded ??= this.#options.load().then(
105
+ (snapshot): Loaded => ({
106
+ snapshot,
107
+ resolver: new Resolver({
108
+ snapshot,
109
+ blocks: this.#options.blocks,
110
+ builtIns: this.#options.builtIns,
111
+ onCollision: this.#options.onCollision,
112
+ onBlock: this.#options.telemetry?.block,
113
+ }),
114
+ }),
115
+ (error): Loaded => ({
116
+ error: isResolutionError(error)
117
+ ? error
118
+ : errors.loaderFailed("the content loader failed", error),
119
+ }),
120
+ );
121
+ return this.#loaded;
122
+ }
123
+
124
+ /** Returns the error result, reporting each error to telemetry once per client. */
125
+ #fail(error: CMSError): [null, CMSError] {
126
+ if (this.#options.telemetry && !this.#reported.has(error)) {
127
+ this.#reported.add(error);
128
+ this.#options.telemetry.error(error);
129
+ }
130
+ return [null, error];
131
+ }
132
+ }
133
+
134
+ /** Plain code-unit order, the same on every server and locale. */
135
+ function byCodeUnit(a: string, b: string): number {
136
+ return a < b ? -1 : a > b ? 1 : 0;
137
+ }
138
+
139
+ function asCMSError(error: unknown): CMSError {
140
+ return isResolutionError(error) ? error : errors.blockFailed("<unknown>", [], error);
141
+ }
142
+
143
+ /** Prefixes a failed list entry's path with the entry's name, so the log says which one. */
144
+ function atEntry(name: string, error: unknown): unknown {
145
+ if (!isResolutionError(error) || error.code === "CYCLE") return error;
146
+ return new ResolutionError(error.code, error.message, [name, ...error.path], error.cause);
147
+ }