@decocms/blocks 7.71.6 → 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,338 @@
1
+ /**
2
+ * `@decocms/blocks/protocol/storage/fs`: the filesystem `ContentStorage`
3
+ * (Node only), which `deco serve` serves a working tree with.
4
+ *
5
+ * Inside the app root (the folder that contains `.deco/`):
6
+ * - `.deco/blocks/*.json` — the saved blocks; the only thing it writes.
7
+ * - `.deco/schema.gen.json`, falling back to `.deco/meta.gen.json` — read only.
8
+ * - `.deco/secrets.pub` — read only, reported by `describe`.
9
+ * - `.deco/index.ts` is code and is never written.
10
+ * - Uploads go to `public/assets` (or `assetsDir`), never overwriting a file.
11
+ *
12
+ * A file's version is its git blob hash, as `git hash-object` prints it.
13
+ * Commits are serialized per `.deco` folder (in process and across processes)
14
+ * and applied with staged files and atomic renames, rolled back on failure,
15
+ * with the folder fsynced before a commit returns.
16
+ *
17
+ * While committing it uses `.deco/.blocks.lock` and `.deco/.tx-*` folders;
18
+ * add both to `.gitignore`. A crashed process can leave them behind: a lock
19
+ * older than 30 s is taken over, and leftover `.tx-*` folders are removed by
20
+ * the next commit.
21
+ */
22
+ import { lstat, mkdir, open, readdir, readFile, stat } from "node:fs/promises";
23
+ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
24
+ import { suffixedAssetName } from "../../assets";
25
+ import { isBlockFileName } from "../../keys";
26
+ import {
27
+ type CommitResult,
28
+ type ContentStorage,
29
+ type StorageDescription,
30
+ type StorageFile,
31
+ StorageInvalidFileError,
32
+ StorageNotFoundError,
33
+ type StorageSnapshot,
34
+ StorageUnavailableError,
35
+ type StoredFileBody,
36
+ type StoredSchema,
37
+ } from "../../storage";
38
+ import type { Limits } from "../../types";
39
+ import { gitBlobHash, revisionOf } from "./hash";
40
+ import { withCommitLock } from "./lock";
41
+ import { applyFileChange, sweepStaleTransactions } from "./transaction";
42
+
43
+ export interface FsStorageOptions {
44
+ /** The app root: the folder that contains `.deco/`. */
45
+ root: string;
46
+ /**
47
+ * The repository root, which `describe` reports paths relative to. Default:
48
+ * the nearest folder above `root` (or `root` itself) that contains `.git`,
49
+ * else `root`.
50
+ */
51
+ repoRoot?: string;
52
+ /** Serve the content without accepting writes or uploads. */
53
+ readOnly?: boolean;
54
+ /** The upload folder, relative to `root` (default `public/assets`). */
55
+ assetsDir?: string;
56
+ /** The largest upload accepted, in bytes (default 25 MiB). */
57
+ assetsMaxBytes?: number;
58
+ /** Overrides the poll interval (default 2000 ms). */
59
+ pollIntervalMs?: number;
60
+ /** Lowers the protocol's limits. */
61
+ limits?: Partial<Limits>;
62
+ /** How long a commit waits for another process's lock (default 10 s). */
63
+ lockTimeoutMs?: number;
64
+ }
65
+
66
+ export type FsStorage = ContentStorage & {
67
+ /** The absolute app root. */
68
+ readonly root: string;
69
+ };
70
+
71
+ const DEFAULT_ASSETS_DIR = "public/assets";
72
+ const DEFAULT_ASSETS_MAX_BYTES = 25 * 1024 * 1024;
73
+
74
+ const toPosix = (path: string) => path.split(sep).join("/");
75
+
76
+ const isMissing = (error: unknown) => {
77
+ const code = (error as NodeJS.ErrnoException)?.code;
78
+ return code === "ENOENT" || code === "ENOTDIR";
79
+ };
80
+
81
+ async function exists(path: string): Promise<boolean> {
82
+ try {
83
+ await lstat(path);
84
+ return true;
85
+ } catch (error) {
86
+ if (isMissing(error)) return false;
87
+ throw error;
88
+ }
89
+ }
90
+
91
+ /** The nearest folder at or above `start` that contains `.git`, else `start`. */
92
+ async function findRepoRoot(start: string): Promise<string> {
93
+ for (let dir = start; ; dir = dirname(dir)) {
94
+ if (await exists(join(dir, ".git"))) return dir;
95
+ if (dirname(dir) === dir) return start;
96
+ }
97
+ }
98
+
99
+ async function readTextOrNull(path: string): Promise<string | null> {
100
+ try {
101
+ return await readFile(path, "utf8");
102
+ } catch (error) {
103
+ if (isMissing(error)) return null;
104
+ throw error;
105
+ }
106
+ }
107
+
108
+ async function readBytesOrNull(path: string): Promise<Uint8Array | null> {
109
+ try {
110
+ return await readFile(path);
111
+ } catch (error) {
112
+ if (isMissing(error)) return null;
113
+ throw error;
114
+ }
115
+ }
116
+
117
+ function assertBlockFile(file: string) {
118
+ if (!isBlockFileName(file)) throw new StorageInvalidFileError(file);
119
+ }
120
+
121
+ function wrapIoError(error: unknown): never {
122
+ if (
123
+ error instanceof StorageUnavailableError ||
124
+ error instanceof StorageNotFoundError ||
125
+ error instanceof StorageInvalidFileError
126
+ )
127
+ throw error;
128
+ throw new StorageUnavailableError(`filesystem error: ${(error as Error).message}`);
129
+ }
130
+
131
+ export function createFsStorage(options: FsStorageOptions): FsStorage {
132
+ const root = resolve(options.root);
133
+ const decoDir = join(root, ".deco");
134
+ const blocksDir = join(decoDir, "blocks");
135
+ const assetsDir = resolve(root, options.assetsDir ?? DEFAULT_ASSETS_DIR);
136
+ const readOnly = options.readOnly ?? false;
137
+ const lockOptions = { timeoutMs: options.lockTimeoutMs ?? 10_000, staleMs: 30_000 };
138
+ let repoRoot: Promise<string> | undefined;
139
+ let swept = false;
140
+
141
+ /** file -> stat fingerprint and its hash, so a poll only rehashes changed files. */
142
+ const hashCache = new Map<string, { fingerprint: string; version: string }>();
143
+
144
+ async function hashFile(file: string): Promise<StorageFile | null> {
145
+ const path = join(blocksDir, file);
146
+ let info: Awaited<ReturnType<typeof stat>>;
147
+ try {
148
+ info = await stat(path, { bigint: true });
149
+ } catch (error) {
150
+ if (isMissing(error)) return null;
151
+ throw error;
152
+ }
153
+ if (!info.isFile()) return null;
154
+ const fingerprint = `${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`;
155
+ const cached = hashCache.get(file);
156
+ if (cached?.fingerprint === fingerprint) {
157
+ return { file, version: cached.version, size: Number(info.size) };
158
+ }
159
+ let bytes: Uint8Array;
160
+ try {
161
+ bytes = await readFile(path);
162
+ } catch (error) {
163
+ if (isMissing(error)) return null;
164
+ throw error;
165
+ }
166
+ const version = gitBlobHash(bytes);
167
+ hashCache.set(file, { fingerprint, version });
168
+ return { file, version, size: bytes.byteLength };
169
+ }
170
+
171
+ /** The current version of a file, read fresh (no cache), or `null` when absent. */
172
+ async function freshVersion(file: string): Promise<string | null> {
173
+ try {
174
+ return gitBlobHash(await readFile(join(blocksDir, file)));
175
+ } catch (error) {
176
+ if (isMissing(error)) return null;
177
+ throw error;
178
+ }
179
+ }
180
+
181
+ async function readSchema(): Promise<StoredSchema | null> {
182
+ for (const name of ["schema.gen.json", "meta.gen.json"]) {
183
+ const bytes = await readBytesOrNull(join(decoDir, name));
184
+ if (bytes !== null) {
185
+ return {
186
+ version: gitBlobHash(bytes),
187
+ text: new TextDecoder().decode(bytes),
188
+ resolvedRef: null,
189
+ };
190
+ }
191
+ }
192
+ return null;
193
+ }
194
+
195
+ async function snapshot(): Promise<StorageSnapshot> {
196
+ if (!(await exists(decoDir))) {
197
+ throw new StorageNotFoundError(`no .deco folder in ${root}`);
198
+ }
199
+ let names: string[];
200
+ try {
201
+ names = (await readdir(blocksDir, { withFileTypes: true }))
202
+ .filter((entry) => entry.isFile() && isBlockFileName(entry.name))
203
+ .map((entry) => entry.name);
204
+ } catch (error) {
205
+ if (isMissing(error)) names = [];
206
+ else throw error;
207
+ }
208
+ const files = (await Promise.all(names.map(hashFile))).filter(
209
+ (f): f is StorageFile => f !== null,
210
+ );
211
+ files.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
212
+ const present = new Set(names);
213
+ for (const cached of hashCache.keys()) if (!present.has(cached)) hashCache.delete(cached);
214
+ return { revision: revisionOf(files), resolvedRef: null, files };
215
+ }
216
+
217
+ const storage: FsStorage = {
218
+ root,
219
+
220
+ async describe(): Promise<StorageDescription> {
221
+ repoRoot ??= options.repoRoot
222
+ ? Promise.resolve(resolve(options.repoRoot))
223
+ : findRepoRoot(root);
224
+ const base = await repoRoot;
225
+ const relativeRoot = toPosix(relative(base, root)) || ".";
226
+ return {
227
+ kind: "working-tree",
228
+ root: relativeRoot,
229
+ readOnly,
230
+ refs: null,
231
+ assets: readOnly
232
+ ? null
233
+ : {
234
+ dir: toPosix(relative(base, assetsDir)) || ".",
235
+ maxBytes: options.assetsMaxBytes ?? DEFAULT_ASSETS_MAX_BYTES,
236
+ },
237
+ idempotency: null,
238
+ pollIntervalMs: options.pollIntervalMs ?? 2000,
239
+ limits: options.limits,
240
+ };
241
+ },
242
+
243
+ async snapshot() {
244
+ try {
245
+ return await snapshot();
246
+ } catch (error) {
247
+ wrapIoError(error);
248
+ }
249
+ },
250
+
251
+ async readFiles(_snapshot, files) {
252
+ // A working tree has no past snapshots: read current bytes and report
253
+ // their version, so the core notices a file that changed meanwhile.
254
+ const out: Record<string, StoredFileBody> = Object.create(null);
255
+ await Promise.all(
256
+ files.map(async (file) => {
257
+ assertBlockFile(file);
258
+ const bytes = await readBytesOrNull(join(blocksDir, file));
259
+ if (bytes !== null) {
260
+ out[file] = { text: new TextDecoder().decode(bytes), version: gitBlobHash(bytes) };
261
+ }
262
+ }),
263
+ );
264
+ return out;
265
+ },
266
+
267
+ readSchema,
268
+
269
+ readSecretsPublicKey: () => readTextOrNull(join(decoDir, "secrets.pub")),
270
+
271
+ async commit(attempt): Promise<CommitResult> {
272
+ if (readOnly) throw new StorageUnavailableError("the storage is read-only");
273
+ if (attempt.receipt)
274
+ throw new StorageUnavailableError("the filesystem storage keeps no receipts");
275
+ for (const file of [
276
+ ...Object.keys(attempt.put),
277
+ ...attempt.delete,
278
+ ...Object.keys(attempt.expected),
279
+ ]) {
280
+ assertBlockFile(file);
281
+ }
282
+ if (!(await exists(decoDir))) throw new StorageNotFoundError(`no .deco folder in ${root}`);
283
+ try {
284
+ return await withCommitLock(decoDir, lockOptions, async () => {
285
+ // Under the lock, any transaction folder left is from a crashed commit.
286
+ if (!swept) {
287
+ await sweepStaleTransactions(decoDir);
288
+ swept = true;
289
+ }
290
+ if (attempt.expectedSchemaVersion !== undefined) {
291
+ const schema = await readSchema();
292
+ if ((schema?.version ?? null) !== attempt.expectedSchemaVersion) {
293
+ return { status: "stale" } as const;
294
+ }
295
+ }
296
+ for (const [file, expected] of Object.entries(attempt.expected)) {
297
+ if ((await freshVersion(file)) !== expected) return { status: "stale" } as const;
298
+ }
299
+ await applyFileChange(blocksDir, decoDir, { put: attempt.put, delete: attempt.delete });
300
+ const versions: Record<string, string> = {};
301
+ for (const [file, content] of Object.entries(attempt.put))
302
+ versions[file] = gitBlobHash(content);
303
+ const after = await snapshot();
304
+ return { status: "committed", revision: after.revision, versions } as const;
305
+ });
306
+ } catch (error) {
307
+ wrapIoError(error);
308
+ }
309
+ },
310
+
311
+ async putAsset(name, body) {
312
+ if (readOnly) throw new StorageUnavailableError("the storage is read-only");
313
+ if (!name || name.includes("/") || name.includes("\\") || name.startsWith(".")) {
314
+ throw new Error(`not an asset file name: ${JSON.stringify(name)}`);
315
+ }
316
+ await mkdir(assetsDir, { recursive: true });
317
+ let candidate = name;
318
+ for (let attempt = 0; ; attempt++) {
319
+ const path = join(assetsDir, candidate);
320
+ if (!isAbsolute(path) || dirname(path) !== assetsDir) throw new Error("invalid asset path");
321
+ try {
322
+ const handle = await open(path, "wx");
323
+ try {
324
+ await handle.writeFile(body);
325
+ await handle.sync();
326
+ } finally {
327
+ await handle.close();
328
+ }
329
+ return { name: candidate };
330
+ } catch (error) {
331
+ if ((error as NodeJS.ErrnoException).code !== "EEXIST" || attempt > 20) throw error;
332
+ candidate = suffixedAssetName(name);
333
+ }
334
+ }
335
+ },
336
+ };
337
+ return storage;
338
+ }
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Serializes commits to one `.deco` folder: an in-process queue per folder,
3
+ * plus a lock file so two processes (two `deco serve`s, or a script) never
4
+ * interleave a commit.
5
+ */
6
+ import { open, rm, stat } from "node:fs/promises";
7
+ import { join } from "node:path";
8
+ import { StorageUnavailableError } from "../../storage";
9
+
10
+ const LOCK_FILE = ".blocks.lock";
11
+ const queues = new Map<string, Promise<unknown>>();
12
+
13
+ const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
14
+
15
+ async function acquireFileLock(decoDir: string, timeoutMs: number, staleMs: number) {
16
+ const path = join(decoDir, LOCK_FILE);
17
+ const deadline = Date.now() + timeoutMs;
18
+ for (;;) {
19
+ try {
20
+ const handle = await open(path, "wx");
21
+ await handle.writeFile(`${process.pid}\n`);
22
+ await handle.close();
23
+ return () => rm(path, { force: true });
24
+ } catch (error) {
25
+ if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
26
+ }
27
+ const info = await stat(path).catch(() => null);
28
+ if (info && Date.now() - info.mtimeMs > staleMs) {
29
+ // A crashed writer left its lock behind.
30
+ await rm(path, { force: true });
31
+ continue;
32
+ }
33
+ if (Date.now() > deadline) {
34
+ throw new StorageUnavailableError("another process is writing .deco/blocks", 500);
35
+ }
36
+ await sleep(20);
37
+ }
38
+ }
39
+
40
+ interface LockOptions {
41
+ timeoutMs: number;
42
+ staleMs: number;
43
+ }
44
+
45
+ /** Runs `fn` while holding the commit lock of `decoDir`. */
46
+ export async function withCommitLock<T>(
47
+ decoDir: string,
48
+ options: LockOptions,
49
+ fn: () => Promise<T>,
50
+ ): Promise<T> {
51
+ const previous = queues.get(decoDir) ?? Promise.resolve();
52
+ const run = previous
53
+ .catch(() => {})
54
+ .then(async () => {
55
+ const release = await acquireFileLock(decoDir, options.timeoutMs, options.staleMs);
56
+ try {
57
+ return await fn();
58
+ } finally {
59
+ await release();
60
+ }
61
+ });
62
+ queues.set(decoDir, run);
63
+ try {
64
+ return await run;
65
+ } finally {
66
+ if (queues.get(decoDir) === run) queues.delete(decoDir);
67
+ }
68
+ }
@@ -0,0 +1,183 @@
1
+ /**
2
+ * An all-or-nothing change to several files in one folder.
3
+ *
4
+ * New contents are staged and fsynced in a private folder on the same
5
+ * filesystem, then renamed into place: a rename over an existing file is
6
+ * atomic, so a reader never sees a torn or missing file. Every file the
7
+ * change replaces or deletes is first hard-linked into the transaction
8
+ * folder, so if any step fails, the files already changed are put back. The
9
+ * folder itself is fsynced after the renames and unlinks, so the change
10
+ * survives a power loss once it returns.
11
+ *
12
+ * Staged and preserved copies use positional names (`0`, `1`, …), never the
13
+ * target names, so two targets that differ only in letter case can't collide
14
+ * on a case-insensitive filesystem (macOS, Windows).
15
+ */
16
+ import {
17
+ copyFile,
18
+ link,
19
+ mkdir,
20
+ mkdtemp,
21
+ open,
22
+ readdir,
23
+ rename,
24
+ rm,
25
+ stat,
26
+ unlink,
27
+ } from "node:fs/promises";
28
+ import { join } from "node:path";
29
+
30
+ /** The prefix of transaction folders; a leftover one is from a crashed commit. */
31
+ const TRANSACTION_PREFIX = ".tx-";
32
+
33
+ interface FileChange {
34
+ /** Files to write, by name inside `dir`. */
35
+ put: Record<string, string>;
36
+ /** Files to delete, by name inside `dir`. A file that's already gone is fine. */
37
+ delete: string[];
38
+ }
39
+
40
+ const codeOf = (error: unknown) => (error as NodeJS.ErrnoException)?.code;
41
+
42
+ async function writeDurably(path: string, content: string) {
43
+ const handle = await open(path, "wx");
44
+ try {
45
+ await handle.writeFile(content, "utf8");
46
+ await handle.sync();
47
+ } finally {
48
+ await handle.close();
49
+ }
50
+ }
51
+
52
+ /** Flushes a folder's entries (renames, unlinks) to disk; a no-op where that's unsupported. */
53
+ async function syncDir(dir: string) {
54
+ let handle: Awaited<ReturnType<typeof open>> | undefined;
55
+ try {
56
+ handle = await open(dir, "r");
57
+ await handle.sync();
58
+ } catch (error) {
59
+ // Windows can't open a folder; some filesystems can't fsync one.
60
+ if (!["EISDIR", "EPERM", "EACCES", "EINVAL", "EBADF", "ENOTSUP"].includes(codeOf(error)!))
61
+ throw error;
62
+ } finally {
63
+ await handle?.close();
64
+ }
65
+ }
66
+
67
+ async function preserve(source: string, backup: string): Promise<boolean> {
68
+ try {
69
+ await link(source, backup);
70
+ return true;
71
+ } catch (error) {
72
+ const code = codeOf(error);
73
+ if (code === "ENOENT") return false;
74
+ // Filesystems without hard links: fall back to a copy.
75
+ if (code === "EPERM" || code === "ENOTSUP" || code === "EXDEV" || code === "EOPNOTSUPP") {
76
+ try {
77
+ await copyFile(source, backup);
78
+ return true;
79
+ } catch (copyError) {
80
+ if (codeOf(copyError) === "ENOENT") return false;
81
+ throw copyError;
82
+ }
83
+ }
84
+ throw error;
85
+ }
86
+ }
87
+
88
+ async function sameFile(a: string, b: string): Promise<boolean> {
89
+ try {
90
+ const [x, y] = await Promise.all([stat(a, { bigint: true }), stat(b, { bigint: true })]);
91
+ return x.dev === y.dev && x.ino === y.ino;
92
+ } catch (error) {
93
+ if (codeOf(error) === "ENOENT") return false;
94
+ throw error;
95
+ }
96
+ }
97
+
98
+ /**
99
+ * The deletes to perform: on a case-insensitive filesystem, a file that
100
+ * differs from a written one only in letter case *is* that file, so the
101
+ * rename replaces it, and unlinking it would delete what was just written.
102
+ */
103
+ async function effectiveDeletes(dir: string, change: FileChange): Promise<string[]> {
104
+ const puts = Object.keys(change.put);
105
+ const out: string[] = [];
106
+ for (const file of new Set(change.delete)) {
107
+ if (file in change.put) continue;
108
+ const twin = puts.find((p) => p.toLowerCase() === file.toLowerCase());
109
+ if (twin && (await sameFile(join(dir, file), join(dir, twin)))) continue;
110
+ out.push(file);
111
+ }
112
+ return out;
113
+ }
114
+
115
+ /**
116
+ * Applies `change` to `dir` atomically: every file lands, or the folder is
117
+ * left as it was. `scratchParent` holds the transaction folder and must be on
118
+ * the same filesystem as `dir`.
119
+ */
120
+ export async function applyFileChange(dir: string, scratchParent: string, change: FileChange) {
121
+ await mkdir(dir, { recursive: true });
122
+ const deletes = await effectiveDeletes(dir, change);
123
+ const tx = await mkdtemp(join(scratchParent, TRANSACTION_PREFIX));
124
+ const staged = join(tx, "new");
125
+ const backups = join(tx, "old");
126
+ await mkdir(staged);
127
+ await mkdir(backups);
128
+
129
+ const puts = Object.entries(change.put);
130
+ // target -> its backup's path, or null when there was nothing to preserve
131
+ const touched = new Map<string, string | null>();
132
+ try {
133
+ for (const [index, [, content]] of puts.entries()) {
134
+ await writeDurably(join(staged, String(index)), content);
135
+ }
136
+ for (const file of [...puts.map(([file]) => file), ...deletes]) {
137
+ if (touched.has(file)) continue;
138
+ const backup = join(backups, String(touched.size));
139
+ touched.set(file, (await preserve(join(dir, file), backup)) ? backup : null);
140
+ }
141
+ for (const [index, [file]] of puts.entries()) {
142
+ await rename(join(staged, String(index)), join(dir, file));
143
+ }
144
+ for (const file of deletes) {
145
+ await unlink(join(dir, file)).catch((error: NodeJS.ErrnoException) => {
146
+ if (error.code !== "ENOENT") throw error;
147
+ });
148
+ }
149
+ await syncDir(dir);
150
+ } catch (error) {
151
+ for (const [file, backup] of touched) {
152
+ const target = join(dir, file);
153
+ try {
154
+ if (backup) await rename(backup, target);
155
+ else await rm(target, { force: true });
156
+ } catch {
157
+ // Best effort: keep restoring the others.
158
+ }
159
+ }
160
+ throw error;
161
+ } finally {
162
+ await rm(tx, { recursive: true, force: true });
163
+ }
164
+ }
165
+
166
+ /**
167
+ * Removes transaction folders a crashed commit left in `scratchParent`. Call
168
+ * it only while holding the commit lock, when no live transaction exists.
169
+ */
170
+ export async function sweepStaleTransactions(scratchParent: string): Promise<string[]> {
171
+ let names: string[];
172
+ try {
173
+ names = await readdir(scratchParent);
174
+ } catch (error) {
175
+ if (codeOf(error) === "ENOENT") return [];
176
+ throw error;
177
+ }
178
+ const stale = names.filter((name) => name.startsWith(TRANSACTION_PREFIX));
179
+ await Promise.all(
180
+ stale.map((name) => rm(join(scratchParent, name), { recursive: true, force: true })),
181
+ );
182
+ return stale;
183
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * What `@decocms/blocks/protocol/storage/fs` resolves to outside Node (the
3
+ * package's `default` export condition): the same API, failing on use. The
4
+ * filesystem storage needs `node:fs`; on Workers or in a browser, implement
5
+ * `ContentStorage` over the storage you have instead.
6
+ */
7
+ import type { createFsStorage as nodeCreateFsStorage } from "./index";
8
+
9
+ export type { FsStorage, FsStorageOptions } from "./index";
10
+
11
+ export const createFsStorage: typeof nodeCreateFsStorage = () => {
12
+ throw new Error(
13
+ "@decocms/blocks/protocol/storage/fs needs Node (node:fs); it isn't available in this runtime",
14
+ );
15
+ };