@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,341 @@
1
+ /**
2
+ * `blocks.apply`, the protocol's only write:
3
+ *
4
+ * 1. All or nothing: every name in `set` and `delete` lands in one storage
5
+ * commit, or none does.
6
+ * 2. Durable when it returns.
7
+ * 3. `set` wins when a name is in both `set` and `delete`.
8
+ * 4. Validated first: names, value shapes, sizes and the secret guard are
9
+ * checked before anything is written, and every violation is reported.
10
+ * 5. Preconditions are optional: a failed `ifMatch` (or `ifSchemaMatch`)
11
+ * writes nothing and returns a Conflict; without them the last writer wins.
12
+ *
13
+ * 6. Two spellings of one name are one entry: a guard compares against the
14
+ * entry under any spelling, and the result reports `null` for every other
15
+ * spelling the commit deleted.
16
+ *
17
+ * A commit attempt that finds storage moved (files, the schema, or a request
18
+ * key reserved meanwhile) is retried against a new snapshot after a jittered
19
+ * backoff, rechecking every guard, up to `maxCommitAttempts` times.
20
+ */
21
+ import { applyRequestDigest, canonicalJson } from "../../canonical";
22
+ import {
23
+ type BlockViolation,
24
+ conflict,
25
+ invalidBlock,
26
+ invalidParams,
27
+ limitExceeded,
28
+ readOnly,
29
+ unavailable,
30
+ unsupported,
31
+ type VersionMismatch,
32
+ } from "../../errors";
33
+ import {
34
+ blockFileName,
35
+ blockNameFromFile,
36
+ checkBlockName,
37
+ checkDeletedName,
38
+ fullyDecodeFileName,
39
+ isBlockFileName,
40
+ serializeBlock,
41
+ spellingKey,
42
+ } from "../../keys";
43
+ import { checkSecrets } from "../../secrets";
44
+ import type { StorageDescription, StoredReceipt } from "../../storage";
45
+ import type { BlocksApplyParams, BlocksApplyResult, DecoMeta, Limits } from "../../types";
46
+ import { type LoadedContent, type LoadedEntry, loadCurrentContent } from "../content";
47
+ import type { Core } from "../core";
48
+ import { parseSchema, readSchema } from "./read";
49
+
50
+ const utf8 = new TextEncoder();
51
+
52
+ interface NormalizedApply {
53
+ set: Array<[name: string, value: unknown]>;
54
+ /** Names to delete that aren't also set. */
55
+ delete: string[];
56
+ ifMatch: Array<[name: string, version: string | null]>;
57
+ }
58
+
59
+ function normalize(params: BlocksApplyParams, limits: Limits): NormalizedApply {
60
+ const set = Object.entries(params.set ?? {});
61
+ const setNames = new Set(set.map(([name]) => name));
62
+ const deleteNames = [...new Set(params.delete ?? [])].filter((name) => !setNames.has(name));
63
+ const ops = set.length + deleteNames.length;
64
+ if (ops > limits.maxOpsPerApply) {
65
+ throw limitExceeded(`${ops} names in one blocks.apply; the limit is ${limits.maxOpsPerApply}`, {
66
+ limit: "maxOpsPerApply",
67
+ });
68
+ }
69
+ return { set, delete: deleteNames, ifMatch: Object.entries(params.ifMatch ?? {}) };
70
+ }
71
+
72
+ /** Checks everything that doesn't depend on stored content. */
73
+ function validateStatic(apply: NormalizedApply, limits: Limits, meta: DecoMeta | null) {
74
+ const violations: BlockViolation[] = [];
75
+ const bodies = new Map<string, string>();
76
+ const bySpelling = new Map<string, string>();
77
+ for (const [name, value] of apply.set) {
78
+ for (const v of checkBlockName(name))
79
+ violations.push({ name, rule: v.reason, message: v.message });
80
+ const key = spellingKey(name);
81
+ const twin = bySpelling.get(key);
82
+ if (twin !== undefined) {
83
+ violations.push({
84
+ name,
85
+ rule: "spelling-collision",
86
+ message: `"${name}" and "${twin}" are spellings of the same entry`,
87
+ });
88
+ } else bySpelling.set(key, name);
89
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
90
+ violations.push({ name, rule: "not-an-object", message: "an entry must be a JSON object" });
91
+ continue;
92
+ }
93
+ const body = serializeBlock(value);
94
+ if (utf8.encode(body).byteLength > limits.maxBlockBytes) {
95
+ violations.push({
96
+ name,
97
+ rule: "too-large",
98
+ message: `the entry is over ${limits.maxBlockBytes} bytes`,
99
+ });
100
+ continue;
101
+ }
102
+ bodies.set(name, body);
103
+ violations.push(...checkSecrets(name, value, meta));
104
+ }
105
+ for (const name of apply.delete) {
106
+ for (const v of checkDeletedName(name))
107
+ violations.push({ name, rule: v.reason, message: v.message });
108
+ }
109
+ return { violations, bodies };
110
+ }
111
+
112
+ /** The existing entries, by spelling key: two spellings of one name are one entry. */
113
+ type EntriesBySpelling = Map<string, { name: string; entry: LoadedEntry }>;
114
+
115
+ function entriesBySpelling(content: LoadedContent): EntriesBySpelling {
116
+ const out: EntriesBySpelling = new Map();
117
+ for (const [name, entry] of content.entries) {
118
+ out.set(fullyDecodeFileName(entry.file).name, { name, entry });
119
+ }
120
+ return out;
121
+ }
122
+
123
+ /** Checks the rules that depend on the entries that already exist. */
124
+ function validateAgainst(
125
+ content: LoadedContent,
126
+ bySpelling: EntriesBySpelling,
127
+ apply: NormalizedApply,
128
+ ): BlockViolation[] {
129
+ const violations: BlockViolation[] = [];
130
+ const existing = [...content.entries.keys()];
131
+ for (const [name] of apply.set) {
132
+ // Another spelling of an existing entry updates that entry; it isn't a new name.
133
+ if (bySpelling.has(spellingKey(name))) continue;
134
+ const others = apply.set.filter(([other]) => other !== name).map(([other]) => other);
135
+ for (const v of checkBlockName(name, { existingNames: [...existing, ...others] })) {
136
+ if (v.reason === "case-collision")
137
+ violations.push({ name, rule: v.reason, message: v.message });
138
+ }
139
+ }
140
+ return violations;
141
+ }
142
+
143
+ interface Plan {
144
+ put: Record<string, string>;
145
+ delete: string[];
146
+ expected: Record<string, string | null>;
147
+ }
148
+
149
+ /**
150
+ * Turns names into file operations: write `encode(name)`, delete every other
151
+ * spelling. Deleting any spelling of an entry deletes every spelling. Only
152
+ * guarded entries become commit expectations: without `ifMatch`, the last
153
+ * writer wins, so a concurrent save of the same entry must not turn into a
154
+ * retry storm.
155
+ */
156
+ function plan(
157
+ content: LoadedContent,
158
+ bySpelling: EntriesBySpelling,
159
+ apply: NormalizedApply,
160
+ bodies: Map<string, string>,
161
+ ): Plan {
162
+ const versionOf = new Map(
163
+ content.snapshot.files.filter((f) => isBlockFileName(f.file)).map((f) => [f.file, f.version]),
164
+ );
165
+ const groupFiles = (name: string) =>
166
+ (content.groups.get(spellingKey(name)) ?? []).map((f) => f.file);
167
+ const put: Record<string, string> = Object.create(null);
168
+ const deletes = new Set<string>();
169
+ const expected: Record<string, string | null> = Object.create(null);
170
+
171
+ for (const [name] of apply.set) {
172
+ const file = blockFileName(name);
173
+ put[file] = bodies.get(name)!;
174
+ for (const other of groupFiles(name)) if (other !== file) deletes.add(other);
175
+ }
176
+ for (const name of apply.delete) {
177
+ const file = blockFileName(name);
178
+ if (versionOf.has(file)) deletes.add(file);
179
+ if (bySpelling.has(spellingKey(name))) for (const other of groupFiles(name)) deletes.add(other);
180
+ }
181
+ for (const file of Object.keys(put)) deletes.delete(file);
182
+ // A guarded entry must still be exactly what the guard saw when the commit lands:
183
+ // every spelling of it, so a concurrent save under another spelling is caught too.
184
+ for (const [name] of apply.ifMatch) {
185
+ for (const file of [blockFileName(name), ...groupFiles(name)]) {
186
+ if (isBlockFileName(file)) expected[file] = versionOf.get(file) ?? null;
187
+ }
188
+ }
189
+ return { put, delete: [...deletes], expected };
190
+ }
191
+
192
+ /** A guard compares against the entry under any spelling: `null` means no spelling exists. */
193
+ function checkIfMatch(bySpelling: EntriesBySpelling, apply: NormalizedApply) {
194
+ const mismatches: Record<string, VersionMismatch> = {};
195
+ let failed = false;
196
+ for (const [name, expected] of apply.ifMatch) {
197
+ const actual = bySpelling.get(spellingKey(name))?.entry.version ?? null;
198
+ if (actual !== expected) {
199
+ mismatches[name] = { expected, actual };
200
+ failed = true;
201
+ }
202
+ }
203
+ return failed ? mismatches : null;
204
+ }
205
+
206
+ /**
207
+ * The result's versions: every name written or deleted, plus `null` for each
208
+ * other spelling the commit deleted, so a client's map never keeps an entry
209
+ * under a name that's gone.
210
+ */
211
+ function resultFromVersions(
212
+ apply: NormalizedApply,
213
+ revision: string,
214
+ fileVersions: Record<string, string>,
215
+ deletedFiles: readonly string[],
216
+ ): BlocksApplyResult {
217
+ const versions: Record<string, string | null> = Object.create(null);
218
+ const touched = new Set<string>();
219
+ for (const [name] of apply.set) {
220
+ versions[name] = fileVersions[blockFileName(name)] ?? null;
221
+ touched.add(spellingKey(name));
222
+ }
223
+ for (const name of apply.delete) {
224
+ versions[name] = null;
225
+ touched.add(spellingKey(name));
226
+ }
227
+ for (const file of deletedFiles) {
228
+ const name = blockNameFromFile(file);
229
+ if (!(name in versions) && touched.has(fullyDecodeFileName(file).name)) versions[name] = null;
230
+ }
231
+ return { revision, versions };
232
+ }
233
+
234
+ function receiptResult(apply: NormalizedApply, receipt: StoredReceipt): BlocksApplyResult {
235
+ return resultFromVersions(apply, receipt.revision, receipt.versions, receipt.deleted ?? []);
236
+ }
237
+
238
+ async function loadSchema(core: Core, params: BlocksApplyParams, limits: Limits) {
239
+ const stored = await readSchema(core, params.ref, limits.maxSchemaBytes);
240
+ if (stored === null) return { version: null, meta: null };
241
+ if (core.parsedSchema?.version !== stored.version) {
242
+ core.parsedSchema = { version: stored.version, meta: parseSchema(stored.text) };
243
+ }
244
+ return { version: stored.version, meta: core.parsedSchema.meta };
245
+ }
246
+
247
+ function checkFeatures(description: StorageDescription, core: Core, params: BlocksApplyParams) {
248
+ if (description.readOnly) throw readOnly();
249
+ core.checkRef(description, params.ref);
250
+ if (params.requestKey !== undefined && (!description.idempotency || !core.storage.getReceipt)) {
251
+ throw unsupported("this endpoint doesn't support request keys; omit requestKey");
252
+ }
253
+ }
254
+
255
+ export async function blocksApply(
256
+ core: Core,
257
+ params: BlocksApplyParams,
258
+ scope: string,
259
+ ): Promise<BlocksApplyResult> {
260
+ const description = await core.description();
261
+ checkFeatures(description, core, params);
262
+ if (params.requestKey === undefined) return applyOnce(core, params, description, null);
263
+
264
+ const digest = await applyRequestDigest(params);
265
+ const key = canonicalJson([scope, description.root, params.ref ?? null, params.requestKey]);
266
+ // Simultaneous duplicates: wait for the first, then find its receipt.
267
+ for (let pending = core.inflight.get(key); pending; pending = core.inflight.get(key)) {
268
+ await pending.catch(() => {});
269
+ }
270
+ const run = applyOnce(core, params, description, { key, digest });
271
+ core.inflight.set(key, run);
272
+ try {
273
+ return await run;
274
+ } finally {
275
+ if (core.inflight.get(key) === run) core.inflight.delete(key);
276
+ }
277
+ }
278
+
279
+ async function applyOnce(
280
+ core: Core,
281
+ params: BlocksApplyParams,
282
+ description: StorageDescription,
283
+ receipt: { key: string; digest: string } | null,
284
+ ): Promise<BlocksApplyResult> {
285
+ const limits = core.limits(description);
286
+ const apply = normalize(params, limits);
287
+
288
+ for (let attempt = 1; attempt <= core.maxCommitAttempts; attempt++) {
289
+ // Receipts for completed identical requests resolve before any guard is rechecked.
290
+ if (receipt) {
291
+ const stored = await core.storage.getReceipt!(receipt.key);
292
+ if (stored) {
293
+ if (stored.digest !== receipt.digest) {
294
+ throw invalidParams("requestKey was already used for a different request");
295
+ }
296
+ return receiptResult(apply, stored);
297
+ }
298
+ }
299
+
300
+ const schema = await loadSchema(core, params, limits);
301
+ if (params.ifSchemaMatch !== undefined && params.ifSchemaMatch !== schema.version) {
302
+ throw conflict({ schema: { expected: params.ifSchemaMatch, actual: schema.version } });
303
+ }
304
+ const { violations, bodies } = validateStatic(apply, limits, schema.meta);
305
+ const { snapshot, content } = await loadCurrentContent(core.storage, params.ref, {
306
+ readAll: false,
307
+ limits,
308
+ cache: core.cache,
309
+ });
310
+ const bySpelling = entriesBySpelling(content!);
311
+ violations.push(...validateAgainst(content!, bySpelling, apply));
312
+ if (violations.length > 0) throw invalidBlock(violations);
313
+
314
+ const mismatches = checkIfMatch(bySpelling, apply);
315
+ if (mismatches) throw conflict({ entries: mismatches });
316
+
317
+ const { put, delete: deletes, expected } = plan(content!, bySpelling, apply, bodies);
318
+ if (Object.keys(put).length === 0 && deletes.length === 0 && !receipt) {
319
+ return resultFromVersions(apply, snapshot.revision, {}, []);
320
+ }
321
+ // The schema the guards and the secret check used must still be current at commit time.
322
+ const dependsOnSchema = params.ifSchemaMatch !== undefined || apply.set.length > 0;
323
+ const result = await core.storage.commit({
324
+ ref: params.ref,
325
+ base: snapshot,
326
+ put,
327
+ delete: deletes,
328
+ expected,
329
+ ...(dependsOnSchema ? { expectedSchemaVersion: schema.version } : {}),
330
+ receipt: receipt ?? undefined,
331
+ });
332
+ if (result.status === "committed") {
333
+ return resultFromVersions(apply, result.revision, result.versions, deletes);
334
+ }
335
+ if (attempt < core.maxCommitAttempts) await core.backoff(attempt);
336
+ }
337
+ throw unavailable(
338
+ `storage kept changing; gave up after ${core.maxCommitAttempts} commit attempts`,
339
+ 250,
340
+ );
341
+ }
@@ -0,0 +1,156 @@
1
+ /**
2
+ * The three read methods: `describe`, `schema.get` and `blocks.list`.
3
+ */
4
+ import { publicKeyDerFromPem } from "../../ciphertext";
5
+ import { limitExceeded, notFound, unavailable } from "../../errors";
6
+ import {
7
+ ASSETS_URL_PREFIX,
8
+ type BlocksListResult,
9
+ type DecoMeta,
10
+ type DescribeResult,
11
+ PROTOCOL_NAME,
12
+ PROTOCOL_VERSION,
13
+ type ReadParams,
14
+ SCHEMA_FORMAT,
15
+ type SchemaGetResult,
16
+ } from "../../types";
17
+ import { loadCurrentContent } from "../content";
18
+ import type { Core } from "../core";
19
+
20
+ const DEFAULT_SERVER = { name: "deco-blocks", version: "unknown" };
21
+
22
+ /** The largest `.deco/secrets.pub` served (a 16384-bit key's PEM is under 3 KiB). */
23
+ const MAX_PUBLIC_KEY_BYTES = 16 * 1024;
24
+
25
+ /**
26
+ * The public key `describe` may serve: a single `PUBLIC KEY` PEM block of at
27
+ * most 16 KiB. Anything else (a private key committed by mistake, two
28
+ * blocks, stray text) is never broadcast to the site editor.
29
+ */
30
+ function servablePublicKey(text: string | null): string | null {
31
+ if (text === null) return null;
32
+ if (new TextEncoder().encode(text).byteLength > MAX_PUBLIC_KEY_BYTES) return null;
33
+ if (text.includes("PRIVATE KEY")) return null;
34
+ return publicKeyDerFromPem(text) === null ? null : text;
35
+ }
36
+
37
+ export async function describe(core: Core): Promise<DescribeResult> {
38
+ const description = await core.description();
39
+ const stored = await core.storage.readSecretsPublicKey();
40
+ const publicKey = servablePublicKey(stored);
41
+ if (stored !== null && publicKey === null) {
42
+ core.options.onError?.(
43
+ new Error(".deco/secrets.pub isn't a single PUBLIC KEY PEM block; describe reports no key"),
44
+ );
45
+ }
46
+ const readOnly = description.readOnly;
47
+ return {
48
+ protocol: PROTOCOL_NAME,
49
+ version: { major: PROTOCOL_VERSION.major, minor: PROTOCOL_VERSION.minor },
50
+ server: core.options.server ?? DEFAULT_SERVER,
51
+ kind: description.kind,
52
+ readOnly,
53
+ root: description.root,
54
+ schemaFormat: SCHEMA_FORMAT,
55
+ refs: description.refs,
56
+ writes: {
57
+ idempotency: core.storage.getReceipt ? description.idempotency : null,
58
+ schemaPreconditions: true,
59
+ },
60
+ pollIntervalMs: core.pollIntervalMs(description),
61
+ limits: core.limits(description),
62
+ preview: core.options.preview ?? null,
63
+ assets:
64
+ readOnly || description.assets === null
65
+ ? null
66
+ : {
67
+ dir: description.assets.dir,
68
+ urlPrefix: ASSETS_URL_PREFIX,
69
+ maxBytes: description.assets.maxBytes,
70
+ },
71
+ secrets: publicKey === null ? null : { publicKey },
72
+ };
73
+ }
74
+
75
+ /** Reads and parses the schema, enforcing the schema byte limit. */
76
+ export async function readSchema(
77
+ core: Core,
78
+ ref: string | undefined,
79
+ maxSchemaBytes: number,
80
+ ): Promise<{ version: string; resolvedRef: string | null; text: string } | null> {
81
+ const stored = await core.storage.readSchema({ ref });
82
+ if (stored === null) return null;
83
+ if (new TextEncoder().encode(stored.text).byteLength > maxSchemaBytes) {
84
+ throw limitExceeded(`the schema is over ${maxSchemaBytes} bytes`, { limit: "maxSchemaBytes" });
85
+ }
86
+ return stored;
87
+ }
88
+
89
+ /** Parses schema text; a file caught mid-write is reported as Unavailable, never served torn. */
90
+ export function parseSchema(text: string): DecoMeta {
91
+ let schema: unknown;
92
+ try {
93
+ schema = JSON.parse(text);
94
+ } catch {
95
+ throw unavailable("the schema file is being written; retry shortly", 500);
96
+ }
97
+ if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
98
+ throw unavailable("the schema file doesn't hold a JSON object", 500);
99
+ }
100
+ return schema as DecoMeta;
101
+ }
102
+
103
+ export async function schemaGet(core: Core, params: ReadParams): Promise<SchemaGetResult> {
104
+ const description = await core.description();
105
+ core.checkRef(description, params.ref);
106
+ const limits = core.limits(description);
107
+ const stored = await core.storage.readSchema({ ref: params.ref });
108
+ if (stored === null) {
109
+ throw notFound("no schema: neither .deco/schema.gen.json nor .deco/meta.gen.json exists");
110
+ }
111
+ if (params.ifNoneMatch !== undefined && params.ifNoneMatch === stored.version) {
112
+ return { notModified: true, version: stored.version };
113
+ }
114
+ if (new TextEncoder().encode(stored.text).byteLength > limits.maxSchemaBytes) {
115
+ throw limitExceeded(`the schema is over ${limits.maxSchemaBytes} bytes`, {
116
+ limit: "maxSchemaBytes",
117
+ });
118
+ }
119
+ return {
120
+ notModified: false,
121
+ version: stored.version,
122
+ resolvedRef: stored.resolvedRef,
123
+ schema: parseSchema(stored.text),
124
+ };
125
+ }
126
+
127
+ export async function blocksList(core: Core, params: ReadParams): Promise<BlocksListResult> {
128
+ const description = await core.description();
129
+ core.checkRef(description, params.ref);
130
+ const limits = core.limits(description);
131
+ const { snapshot, content } = await loadCurrentContent(
132
+ core.storage,
133
+ params.ref,
134
+ { readAll: true, limits, cache: core.cache },
135
+ (s) => params.ifNoneMatch !== undefined && params.ifNoneMatch === s.revision,
136
+ );
137
+ if (content === null) {
138
+ return { notModified: true, revision: snapshot.revision, resolvedRef: snapshot.resolvedRef };
139
+ }
140
+ // Null-prototype maps, so an entry named like an Object.prototype key stays an entry.
141
+ const blocks: Record<string, Record<string, unknown>> = Object.create(null);
142
+ const versions: Record<string, string> = Object.create(null);
143
+ for (const [name, entry] of content.entries) {
144
+ if (entry.value === undefined) continue;
145
+ blocks[name] = entry.value;
146
+ versions[name] = entry.version;
147
+ }
148
+ return {
149
+ notModified: false,
150
+ revision: snapshot.revision,
151
+ resolvedRef: snapshot.resolvedRef,
152
+ blocks,
153
+ versions,
154
+ diagnostics: content.diagnostics,
155
+ };
156
+ }
@@ -0,0 +1,136 @@
1
+ /**
2
+ * The JSON-RPC 2.0 layer: envelope validation, batches and dispatch.
3
+ *
4
+ * - Every request has an `id`; one without is rejected rather than run.
5
+ * - A batch runs in order, returns results in order, holds at most 10 calls,
6
+ * and isn't atomic.
7
+ * - The aggregate response is bounded: once it would pass
8
+ * `maxBatchResponseBytes`, later reads answer LimitExceeded instead.
9
+ * - A write's response is never replaced, alone or in a batch: the write has
10
+ * landed, and answering LimitExceeded would tell the client it hadn't.
11
+ */
12
+ import {
13
+ type ContentProtocolError,
14
+ internalError,
15
+ invalidRequest,
16
+ limitExceeded,
17
+ methodNotFound,
18
+ } from "../errors";
19
+ import { validateParams } from "../params";
20
+ import { MAX_BATCH_CALLS, METHOD_NAMES, type MethodName, type RpcId } from "../types";
21
+ import { type Core, toProtocolError } from "./core";
22
+ import { blocksApply } from "./methods/apply";
23
+ import { blocksList, describe, schemaGet } from "./methods/read";
24
+
25
+ const utf8 = new TextEncoder();
26
+
27
+ type Envelope = { id: RpcId; method: MethodName; params: unknown };
28
+
29
+ const isMethod = (method: string): method is MethodName =>
30
+ (METHOD_NAMES as readonly string[]).includes(method);
31
+
32
+ /** Validates one request object; returns the error response's id on failure. */
33
+ function parseEnvelope(
34
+ value: unknown,
35
+ ): Envelope | { error: ContentProtocolError; id: RpcId | null } {
36
+ const isObject = typeof value === "object" && value !== null && !Array.isArray(value);
37
+ const raw = (isObject ? value : {}) as Record<string, unknown>;
38
+ const id = typeof raw.id === "string" || typeof raw.id === "number" ? raw.id : null;
39
+ if (!isObject) return { error: invalidRequest("a request must be an object"), id: null };
40
+ if (raw.jsonrpc !== "2.0") return { error: invalidRequest('jsonrpc must be "2.0"'), id };
41
+ if (id === null) {
42
+ return { error: invalidRequest("every request needs a string or number id"), id: null };
43
+ }
44
+ if (typeof raw.method !== "string")
45
+ return { error: invalidRequest("method must be a string"), id };
46
+ for (const key of Object.keys(raw)) {
47
+ if (!["jsonrpc", "id", "method", "params"].includes(key)) {
48
+ return { error: invalidRequest(`unknown request member "${key}"`), id };
49
+ }
50
+ }
51
+ if (!isMethod(raw.method)) return { error: methodNotFound(raw.method), id };
52
+ return { id, method: raw.method, params: raw.params };
53
+ }
54
+
55
+ async function run(core: Core, envelope: Envelope, scope: string): Promise<unknown> {
56
+ switch (envelope.method) {
57
+ case "describe":
58
+ validateParams("describe", envelope.params);
59
+ return describe(core);
60
+ case "schema.get":
61
+ return schemaGet(core, validateParams("schema.get", envelope.params));
62
+ case "blocks.list":
63
+ return blocksList(core, validateParams("blocks.list", envelope.params));
64
+ case "blocks.apply":
65
+ return blocksApply(core, validateParams("blocks.apply", envelope.params), scope);
66
+ }
67
+ }
68
+
69
+ /** True for a well-formed `blocks.apply` request. */
70
+ function isWrite(value: unknown): boolean {
71
+ const envelope = parseEnvelope(value);
72
+ return !("error" in envelope) && envelope.method === "blocks.apply";
73
+ }
74
+
75
+ const errorResponse = (id: RpcId | null, error: ContentProtocolError) =>
76
+ JSON.stringify({ jsonrpc: "2.0", id, error: error.toJSON() });
77
+
78
+ async function call(core: Core, value: unknown, scope: string): Promise<string> {
79
+ const envelope = parseEnvelope(value);
80
+ if ("error" in envelope) return errorResponse(envelope.id, envelope.error);
81
+ try {
82
+ const result = await run(core, envelope, scope);
83
+ return JSON.stringify({ jsonrpc: "2.0", id: envelope.id, result });
84
+ } catch (error) {
85
+ const known = toProtocolError(error);
86
+ if (known) return errorResponse(envelope.id, known);
87
+ core.options.onError?.(error);
88
+ return errorResponse(envelope.id, internalError());
89
+ }
90
+ }
91
+
92
+ /**
93
+ * Runs a parsed request body (one request object or a batch array) and
94
+ * returns the serialized response body.
95
+ */
96
+ export async function dispatch(core: Core, body: unknown, scope: string, maxResponseBytes: number) {
97
+ if (!Array.isArray(body)) {
98
+ const response = await call(core, body, scope);
99
+ if (isWrite(body) || utf8.encode(response).byteLength <= maxResponseBytes) return response;
100
+ return errorResponse(
101
+ parseEnvelope(body).id,
102
+ limitExceeded(`the response is over ${maxResponseBytes} bytes`, {
103
+ limit: "maxBatchResponseBytes",
104
+ }),
105
+ );
106
+ }
107
+ if (body.length === 0) return errorResponse(null, invalidRequest("an empty batch"));
108
+ if (body.length > MAX_BATCH_CALLS) {
109
+ return errorResponse(
110
+ null,
111
+ limitExceeded(`a batch holds at most ${MAX_BATCH_CALLS} calls`, { limit: "maxBatchCalls" }),
112
+ );
113
+ }
114
+ const responses: string[] = [];
115
+ let total = 2; // the brackets
116
+ for (const item of body) {
117
+ const envelope = parseEnvelope(item);
118
+ const id = envelope.id;
119
+ const overBudget = () =>
120
+ errorResponse(
121
+ id,
122
+ limitExceeded(`the batch response is over ${maxResponseBytes} bytes`, {
123
+ limit: "maxBatchResponseBytes",
124
+ }),
125
+ );
126
+ // Writes always run, so a batch never drops a save; reads stop once over budget.
127
+ const write = !("error" in envelope) && envelope.method === "blocks.apply";
128
+ let response =
129
+ !write && total > maxResponseBytes ? overBudget() : await call(core, item, scope);
130
+ const bytes = utf8.encode(response).byteLength + (responses.length ? 1 : 0);
131
+ if (total + bytes > maxResponseBytes && !write) response = overBudget();
132
+ total += utf8.encode(response).byteLength + (responses.length ? 1 : 0);
133
+ responses.push(response);
134
+ }
135
+ return `[${responses.join(",")}]`;
136
+ }
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Content hashes for the filesystem storage. A file's version is its git blob
3
+ * hash (`sha1("blob <size>\0" + bytes)`), the same identifier GitHub uses, so
4
+ * versions read from a working tree match `git hash-object`.
5
+ */
6
+ import { createHash } from "node:crypto";
7
+
8
+ /** The git blob hash of `content`, as git computes it for `git hash-object`. */
9
+ export function gitBlobHash(content: Uint8Array | string): string {
10
+ const bytes = typeof content === "string" ? new TextEncoder().encode(content) : content;
11
+ return createHash("sha1").update(`blob ${bytes.byteLength}\0`).update(bytes).digest("hex");
12
+ }
13
+
14
+ /** A revision of a set of files: SHA-256 over the sorted `file\0version` listing. */
15
+ export function revisionOf(files: Iterable<{ file: string; version: string }>): string {
16
+ const listing = [...files]
17
+ .map(({ file, version }) => `${file}\0${version}`)
18
+ .sort()
19
+ .join("\n");
20
+ return createHash("sha256").update(listing).digest("hex");
21
+ }