@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
@@ -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
+ };