@decocms/blocks 8.1.2 → 8.2.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 (91) hide show
  1. package/dist/protocol/client.d.ts +17 -4
  2. package/dist/protocol/client.d.ts.map +1 -1
  3. package/dist/protocol/client.js +46 -10
  4. package/dist/protocol/client.js.map +1 -1
  5. package/dist/protocol/conformance/cases/changes.d.ts +3 -0
  6. package/dist/protocol/conformance/cases/changes.d.ts.map +1 -0
  7. package/dist/protocol/conformance/cases/changes.js +295 -0
  8. package/dist/protocol/conformance/cases/changes.js.map +1 -0
  9. package/dist/protocol/conformance/context.d.ts +14 -0
  10. package/dist/protocol/conformance/context.d.ts.map +1 -1
  11. package/dist/protocol/conformance/context.js.map +1 -1
  12. package/dist/protocol/conformance/index.d.ts.map +1 -1
  13. package/dist/protocol/conformance/index.js +4 -1
  14. package/dist/protocol/conformance/index.js.map +1 -1
  15. package/dist/protocol/errors.d.ts +26 -0
  16. package/dist/protocol/errors.d.ts.map +1 -1
  17. package/dist/protocol/errors.js.map +1 -1
  18. package/dist/protocol/index.d.ts +4 -2
  19. package/dist/protocol/index.d.ts.map +1 -1
  20. package/dist/protocol/index.js +4 -2
  21. package/dist/protocol/index.js.map +1 -1
  22. package/dist/protocol/params.d.ts +4 -2
  23. package/dist/protocol/params.d.ts.map +1 -1
  24. package/dist/protocol/params.js +11 -1
  25. package/dist/protocol/params.js.map +1 -1
  26. package/dist/protocol/server/assets.d.ts +1 -1
  27. package/dist/protocol/server/assets.js +1 -1
  28. package/dist/protocol/server/core.d.ts +12 -1
  29. package/dist/protocol/server/core.d.ts.map +1 -1
  30. package/dist/protocol/server/core.js +8 -0
  31. package/dist/protocol/server/core.js.map +1 -1
  32. package/dist/protocol/server/index.d.ts +1 -1
  33. package/dist/protocol/server/index.js +1 -1
  34. package/dist/protocol/server/methods/apply.d.ts +37 -0
  35. package/dist/protocol/server/methods/apply.d.ts.map +1 -1
  36. package/dist/protocol/server/methods/apply.js +4 -3
  37. package/dist/protocol/server/methods/apply.js.map +1 -1
  38. package/dist/protocol/server/methods/changes.d.ts +6 -0
  39. package/dist/protocol/server/methods/changes.d.ts.map +1 -0
  40. package/dist/protocol/server/methods/changes.js +385 -0
  41. package/dist/protocol/server/methods/changes.js.map +1 -0
  42. package/dist/protocol/server/rpc.d.ts.map +1 -1
  43. package/dist/protocol/server/rpc.js +7 -0
  44. package/dist/protocol/server/rpc.js.map +1 -1
  45. package/dist/protocol/storage/fs/git.d.ts +63 -0
  46. package/dist/protocol/storage/fs/git.d.ts.map +1 -0
  47. package/dist/protocol/storage/fs/git.js +376 -0
  48. package/dist/protocol/storage/fs/git.js.map +1 -0
  49. package/dist/protocol/storage/fs/index.d.ts +2 -0
  50. package/dist/protocol/storage/fs/index.d.ts.map +1 -1
  51. package/dist/protocol/storage/fs/index.js +53 -1
  52. package/dist/protocol/storage/fs/index.js.map +1 -1
  53. package/dist/protocol/storage/memory.d.ts +10 -0
  54. package/dist/protocol/storage/memory.d.ts.map +1 -1
  55. package/dist/protocol/storage/memory.js +45 -0
  56. package/dist/protocol/storage/memory.js.map +1 -1
  57. package/dist/protocol/storage.d.ts +53 -1
  58. package/dist/protocol/storage.d.ts.map +1 -1
  59. package/dist/protocol/storage.js.map +1 -1
  60. package/dist/protocol/types.d.ts +105 -4
  61. package/dist/protocol/types.d.ts.map +1 -1
  62. package/dist/protocol/types.js +16 -3
  63. package/dist/protocol/types.js.map +1 -1
  64. package/dist/v8/cli/run.d.ts.map +1 -1
  65. package/dist/v8/cli/run.js +2 -1
  66. package/dist/v8/cli/run.js.map +1 -1
  67. package/dist/v8/cli/serve/server.d.ts +2 -0
  68. package/dist/v8/cli/serve/server.d.ts.map +1 -1
  69. package/dist/v8/cli/serve/server.js +37 -2
  70. package/dist/v8/cli/serve/server.js.map +1 -1
  71. package/package.json +1 -1
  72. package/src/protocol/client.ts +81 -13
  73. package/src/protocol/conformance/cases/changes.ts +362 -0
  74. package/src/protocol/conformance/context.ts +12 -0
  75. package/src/protocol/conformance/index.ts +4 -1
  76. package/src/protocol/errors.ts +17 -0
  77. package/src/protocol/index.ts +4 -2
  78. package/src/protocol/params.ts +26 -3
  79. package/src/protocol/server/assets.ts +1 -1
  80. package/src/protocol/server/core.ts +9 -0
  81. package/src/protocol/server/index.ts +1 -1
  82. package/src/protocol/server/methods/apply.ts +8 -4
  83. package/src/protocol/server/methods/changes.ts +493 -0
  84. package/src/protocol/server/rpc.ts +7 -0
  85. package/src/protocol/storage/fs/git.ts +424 -0
  86. package/src/protocol/storage/fs/index.ts +59 -1
  87. package/src/protocol/storage/memory.ts +57 -0
  88. package/src/protocol/storage.ts +55 -1
  89. package/src/protocol/types.ts +106 -4
  90. package/src/v8/cli/run.ts +2 -1
  91. package/src/v8/cli/serve/server.ts +46 -2
@@ -5,6 +5,7 @@ import { ContentProtocolError, invalidBlock, notFound, unavailable } from "../er
5
5
  import { blockNameFromFile } from "../keys.ts";
6
6
  import {
7
7
  type ContentStorage,
8
+ type StorageChanges,
8
9
  type StorageDescription,
9
10
  StorageInvalidFileError,
10
11
  StorageNotFoundError,
@@ -17,6 +18,8 @@ const MiB = 1024 * 1024;
17
18
 
18
19
  /** `blocks.apply`'s own guards: names (set plus delete) in one call. Internal, not advertised. */
19
20
  export const MAX_OPS_PER_APPLY = 500;
21
+ /** `changes.get`'s own guard: names in one call (two sides of up to 1 MiB each). Internal, not advertised. */
22
+ export const MAX_NAMES_PER_GET = 20;
20
23
  /** Bytes of one stored entry. */
21
24
  export const MAX_BLOCK_BYTES = 1 * MiB;
22
25
  /** Bytes of one HTTP request body, uncompressed. */
@@ -50,6 +53,12 @@ export class Core {
50
53
  readonly cache: BodyCache;
51
54
  /** The last parsed schema, by version: the secret guard reads it on every write. */
52
55
  parsedSchema: { version: string; meta: DecoMeta } | null = null;
56
+ /**
57
+ * The last `storage.changes()` answer, by changes revision (base plus
58
+ * content): a poll on unchanged content and base doesn't ask the storage
59
+ * again, which for `deco serve` means no git call beyond reading `HEAD`.
60
+ */
61
+ changesMemo: { revision: string; changes: StorageChanges } | null = null;
53
62
 
54
63
  constructor(
55
64
  readonly storage: ContentStorage,
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * `@decocms/blocks/protocol/server`: the content protocol's server core.
3
3
  *
4
- * `createContentHandler(storage)` serves the four methods over any
4
+ * `createContentHandler(storage)` serves the seven methods over any
5
5
  * `ContentStorage`. Web-standard APIs only, so it runs on Node, Bun, Workers
6
6
  * and Deno. (`deco serve`'s asset uploads use `./assets`, which isn't public.)
7
7
  */
@@ -1,5 +1,6 @@
1
1
  /**
2
- * `blocks.apply`, the protocol's only write:
2
+ * `blocks.apply`, the protocol's write that takes new values (the other
3
+ * write, `changes.discard`, only restores the base: see ./changes.ts):
3
4
  *
4
5
  * 1. All or nothing: every name in `set` and `delete` lands in one storage
5
6
  * commit, or none does.
@@ -105,9 +106,9 @@ function validateStatic(apply: NormalizedApply, meta: DecoMeta | null) {
105
106
  }
106
107
 
107
108
  /** The existing entries, by spelling key: two spellings of one name are one entry. */
108
- type EntriesBySpelling = Map<string, { name: string; entry: LoadedEntry }>;
109
+ export type EntriesBySpelling = Map<string, { name: string; entry: LoadedEntry }>;
109
110
 
110
- function entriesBySpelling(content: LoadedContent): EntriesBySpelling {
111
+ export function entriesBySpelling(content: LoadedContent): EntriesBySpelling {
111
112
  const out: EntriesBySpelling = new Map();
112
113
  for (const [name, entry] of content.entries) {
113
114
  out.set(fullyDecodeFileName(entry.file).name, { name, entry });
@@ -185,7 +186,10 @@ function plan(
185
186
  }
186
187
 
187
188
  /** A guard compares against the entry under any spelling: `null` means no spelling exists. */
188
- function checkIfMatch(bySpelling: EntriesBySpelling, apply: NormalizedApply) {
189
+ export function checkIfMatch(
190
+ bySpelling: EntriesBySpelling,
191
+ apply: Pick<NormalizedApply, "ifMatch">,
192
+ ) {
189
193
  const mismatches: Record<string, VersionMismatch> = {};
190
194
  let failed = false;
191
195
  for (const [name, expected] of apply.ifMatch) {
@@ -0,0 +1,493 @@
1
+ /**
2
+ * `changes.list`, `changes.get` and `changes.discard`: a source's content is
3
+ * its base plus its changes, and these three read and drop the changes.
4
+ *
5
+ * - Entries, not files: every spelling of a name (`spellingKey`) is one
6
+ * entry, on the base side as on the current side, and an entry is changed
7
+ * when any file of its spelling group differs from the base.
8
+ * - The storage says which files differ (`changes()`) and reads base bodies
9
+ * (`readBaseFiles()`); the core turns files into entries, resolving the
10
+ * winning spelling on each side exactly as `blocks.list` does.
11
+ * - `changes.discard` is a write: it restores the base files of the named
12
+ * entries as the storage reads them, and deletes their files the base
13
+ * doesn't have, in one commit guarded like `blocks.apply` (optional
14
+ * `ifMatch`, Conflict, retries), plus the base revision (`expectedBase`),
15
+ * so a base that moves meanwhile is re-read rather than half-restored.
16
+ * The commit says `reason: "discard"`: a storage with a staging area (the
17
+ * fs storage's git index) also brings those files' staged entries back to
18
+ * the base, so a discarded block that was `git add`ed (or `git mv`ed or
19
+ * `git rm`ed) isn't left staged for a later commit.
20
+ */
21
+ import { sha256Hex } from "../../canonical.ts";
22
+ import {
23
+ type BlockViolation,
24
+ conflict,
25
+ invalidBlock,
26
+ invalidParams,
27
+ limitExceeded,
28
+ readOnly,
29
+ unavailable,
30
+ } from "../../errors.ts";
31
+ import {
32
+ blockFileName,
33
+ blockNameFromFile,
34
+ checkDeletedName,
35
+ entryHasPath,
36
+ fullyDecodeFileName,
37
+ isBlockFileName,
38
+ resolveSpellings,
39
+ spellingKey,
40
+ } from "../../keys.ts";
41
+ import type {
42
+ StorageBase,
43
+ StorageChanges,
44
+ StorageFile,
45
+ StorageSnapshot,
46
+ StoredFileBody,
47
+ } from "../../storage.ts";
48
+ import type {
49
+ BlocksApplyResult,
50
+ Change,
51
+ ChangeDetail,
52
+ ChangeDiagnostic,
53
+ ChangesBase,
54
+ ChangesDiscardParams,
55
+ ChangesGetParams,
56
+ ChangesGetResult,
57
+ ChangesListResult,
58
+ ReadParams,
59
+ } from "../../types.ts";
60
+ import { type ParsedBody, parseBody } from "../bodyCache.ts";
61
+ import { type LoadedContent, loadCurrentContent } from "../content.ts";
62
+ import { type Core, MAX_BLOCK_BYTES, MAX_NAMES_PER_GET, MAX_OPS_PER_APPLY } from "../core.ts";
63
+ import { checkIfMatch, type EntriesBySpelling, entriesBySpelling } from "./apply.ts";
64
+
65
+ const keyOf = (file: string) => fullyDecodeFileName(file).name;
66
+
67
+ const byFile = (a: { file: string }, b: { file: string }) =>
68
+ a.file < b.file ? -1 : a.file > b.file ? 1 : 0;
69
+
70
+ /** One entry that differs from the base, with the files behind it. */
71
+ interface EntryChange {
72
+ name: string;
73
+ kind: "set" | "delete";
74
+ /** The current winner's version; `null` when no file of the entry exists now. */
75
+ version: string | null;
76
+ baseVersion: string | null;
77
+ /** The current winning file, when it was readable as a candidate. */
78
+ currentFile: string | null;
79
+ /** The base's winning file, when the base has the entry. */
80
+ baseFile: string | null;
81
+ /** The entry's files that differ from the base. */
82
+ changedFiles: string[];
83
+ /** The entry's files in the base. */
84
+ baseFiles: StorageFile[];
85
+ }
86
+
87
+ interface ChangesState {
88
+ base: StorageBase;
89
+ revision: string;
90
+ snapshot: StorageSnapshot;
91
+ content: LoadedContent;
92
+ bySpelling: EntriesBySpelling;
93
+ /** Changed entries, by spelling key. */
94
+ changes: Map<string, EntryChange>;
95
+ }
96
+
97
+ const toChangesBase = (base: StorageBase): ChangesBase => ({
98
+ revision: base.revision,
99
+ resolvedRef: base.resolvedRef,
100
+ });
101
+
102
+ /** The changes' revision: it moves when the base, its branch or the content moves. */
103
+ function changesRevision(base: StorageBase, snapshot: StorageSnapshot): Promise<string> {
104
+ return sha256Hex(`${base.revision}\n${base.resolvedRef ?? ""}\n${snapshot.revision}`);
105
+ }
106
+
107
+ /** Parses base bodies, caching them like current ones (base versions identify content too). */
108
+ async function readBaseBodies(
109
+ core: Core,
110
+ base: StorageBase,
111
+ files: StorageFile[],
112
+ ): Promise<Map<string, ParsedBody>> {
113
+ const out = new Map<string, ParsedBody>();
114
+ const toRead: StorageFile[] = [];
115
+ for (const file of files) {
116
+ if (file.size !== undefined && file.size > MAX_BLOCK_BYTES) {
117
+ out.set(file.file, {
118
+ ok: false,
119
+ kind: "too-large",
120
+ bytes: file.size,
121
+ message: `the file is over ${MAX_BLOCK_BYTES} bytes`,
122
+ });
123
+ continue;
124
+ }
125
+ toRead.push(file);
126
+ }
127
+ if (toRead.length === 0) return out;
128
+ const bodies = await core.storage.readBaseFiles(
129
+ base,
130
+ toRead.map((f) => f.file),
131
+ );
132
+ for (const file of toRead) {
133
+ const read = bodies[file.file];
134
+ if (read === undefined) continue; // The base moved: the caller notices.
135
+ // Parsed like a current body, which is read without its BOM.
136
+ out.set(file.file, parseBody(read.text.replace(/^\uFEFF/, ""), MAX_BLOCK_BYTES));
137
+ }
138
+ return out;
139
+ }
140
+
141
+ /** The base's winning file of one spelling group. */
142
+ async function baseWinner(
143
+ core: Core,
144
+ base: StorageBase,
145
+ files: StorageFile[],
146
+ ): Promise<StorageFile | null> {
147
+ if (files.length <= 1) return files[0] ?? null;
148
+ const bodies = await readBaseBodies(core, base, files);
149
+ const candidates = files.map((file) => {
150
+ const body = bodies.get(file.file);
151
+ return { ...file, hasPath: body?.ok === true && entryHasPath(body.value) };
152
+ });
153
+ const [resolved] = resolveSpellings(candidates).values();
154
+ return resolved?.winner ?? null;
155
+ }
156
+
157
+ /** Asks the storage which files differ, unless the memo already knows for this revision. */
158
+ async function storageChanges(
159
+ core: Core,
160
+ base: StorageBase,
161
+ snapshot: StorageSnapshot,
162
+ revision: string,
163
+ ): Promise<StorageChanges> {
164
+ if (core.changesMemo?.revision === revision) return core.changesMemo.changes;
165
+ const answer = await core.storage.changes(base, snapshot);
166
+ const changes: StorageChanges = {
167
+ files: [...new Set(answer.files.filter(isBlockFileName))].sort(),
168
+ baseFiles: answer.baseFiles.filter((f) => isBlockFileName(f.file)),
169
+ };
170
+ core.changesMemo = { revision, changes };
171
+ return changes;
172
+ }
173
+
174
+ /** Reads the base, the content and what differs, as entries. */
175
+ async function loadChanges(core: Core): Promise<ChangesState> {
176
+ const base = await core.storage.base();
177
+ const { snapshot, content } = await loadCurrentContent(core.storage, {
178
+ readAll: false,
179
+ cache: core.cache,
180
+ });
181
+ const revision = await changesRevision(base, snapshot);
182
+ const answer = await storageChanges(core, base, snapshot, revision);
183
+
184
+ const changedByKey = new Map<string, string[]>();
185
+ for (const file of answer.files) {
186
+ const key = keyOf(file);
187
+ const group = changedByKey.get(key);
188
+ if (group) group.push(file);
189
+ else changedByKey.set(key, [file]);
190
+ }
191
+ const baseByKey = new Map<string, StorageFile[]>();
192
+ for (const file of answer.baseFiles) {
193
+ const key = keyOf(file.file);
194
+ if (!changedByKey.has(key)) continue;
195
+ const group = baseByKey.get(key);
196
+ if (group) group.push(file);
197
+ else baseByKey.set(key, [file]);
198
+ }
199
+
200
+ const bySpelling = entriesBySpelling(content!);
201
+ const changes = new Map<string, EntryChange>();
202
+ for (const [key, changedFiles] of changedByKey) {
203
+ const baseFiles = (baseByKey.get(key) ?? []).sort(byFile);
204
+ const current = bySpelling.get(key);
205
+ const currentFiles = content!.groups.get(key) ?? [];
206
+ const winner = await baseWinner(core, base, baseFiles);
207
+ const exists = currentFiles.length > 0;
208
+ changes.set(key, {
209
+ name:
210
+ current?.name ??
211
+ (winner ? blockNameFromFile(winner.file) : blockNameFromFile(changedFiles[0]!)),
212
+ kind: exists ? "set" : "delete",
213
+ version: current?.entry.version ?? (exists ? currentFiles[0]!.version : null),
214
+ baseVersion: winner?.version ?? null,
215
+ currentFile: current?.entry.file ?? null,
216
+ baseFile: winner?.file ?? null,
217
+ changedFiles,
218
+ baseFiles,
219
+ });
220
+ }
221
+ return { base, revision, snapshot, content: content!, bySpelling, changes };
222
+ }
223
+
224
+ export async function changesList(core: Core, params: ReadParams): Promise<ChangesListResult> {
225
+ const state = await loadChanges(core);
226
+ const base = toChangesBase(state.base);
227
+ if (params.ifNoneMatch !== undefined && params.ifNoneMatch === state.revision) {
228
+ return { notModified: true, revision: state.revision, base };
229
+ }
230
+ // Null-prototype, so an entry named like an Object.prototype key stays an entry.
231
+ const changes: Record<string, Change> = Object.create(null);
232
+ const sorted = [...state.changes.values()].sort((a, b) =>
233
+ a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
234
+ );
235
+ for (const change of sorted) {
236
+ changes[change.name] = {
237
+ kind: change.kind,
238
+ version: change.version,
239
+ baseVersion: change.baseVersion,
240
+ };
241
+ }
242
+ return { notModified: false, revision: state.revision, base, changes };
243
+ }
244
+
245
+ function checkNames(names: string[], limit: number, limitName: string, method: string) {
246
+ const unique = [...new Set(names)];
247
+ if (unique.length > limit) {
248
+ throw limitExceeded(`${unique.length} names in one ${method}; the limit is ${limit}`, {
249
+ limit: limitName,
250
+ });
251
+ }
252
+ return unique;
253
+ }
254
+
255
+ /** How many times `changes.get` reads when files keep changing under it. */
256
+ const MAX_GET_READS = 3;
257
+
258
+ export async function changesGet(core: Core, params: ChangesGetParams): Promise<ChangesGetResult> {
259
+ const names = checkNames(params.names, MAX_NAMES_PER_GET, "maxNamesPerGet", "changes.get");
260
+ const empty = names.findIndex((name) => name.length === 0);
261
+ if (empty !== -1) throw invalidParams(`names.${empty}: the name is empty`);
262
+
263
+ for (let read = 1; read <= MAX_GET_READS; read++) {
264
+ const state = await loadChanges(core);
265
+ const plans: Array<{
266
+ name: string;
267
+ kind: ChangeDetail["kind"];
268
+ version: string | null;
269
+ baseVersion: string | null;
270
+ currentFile: string | null;
271
+ baseFile: string | null;
272
+ }> = [];
273
+ for (const name of names) {
274
+ const key = spellingKey(name);
275
+ const change = state.changes.get(key);
276
+ if (change) {
277
+ plans.push({
278
+ name,
279
+ kind: change.kind,
280
+ version: change.version,
281
+ baseVersion: change.baseVersion,
282
+ currentFile: change.currentFile,
283
+ baseFile: change.baseFile,
284
+ });
285
+ continue;
286
+ }
287
+ const current = state.bySpelling.get(key);
288
+ if (!current) continue; // In neither side.
289
+ plans.push({
290
+ name,
291
+ kind: null,
292
+ version: current.entry.version,
293
+ baseVersion: current.entry.version,
294
+ currentFile: current.entry.file,
295
+ baseFile: null,
296
+ });
297
+ }
298
+
299
+ const currentFiles = [...new Set(plans.flatMap((p) => (p.currentFile ? [p.currentFile] : [])))];
300
+ const current = await readCurrentBodies(core, state.snapshot, currentFiles);
301
+ if (current === null) continue; // A file changed while being read: read again.
302
+ const baseFiles = plans.flatMap((p) => {
303
+ if (!p.baseFile) return [];
304
+ const change = state.changes.get(spellingKey(p.name));
305
+ return change?.baseFiles.filter((f) => f.file === p.baseFile) ?? [];
306
+ });
307
+ const baseBodies = await readBaseBodies(core, state.base, baseFiles);
308
+
309
+ const entries: Record<string, ChangeDetail> = Object.create(null);
310
+ const diagnostics: ChangeDiagnostic[] = [];
311
+ const side = (
312
+ body: ParsedBody | undefined,
313
+ file: string | null,
314
+ which: ChangeDiagnostic["side"],
315
+ ) => {
316
+ if (file === null || body === undefined) return null;
317
+ if (body.ok) return body.value;
318
+ diagnostics.push({ file, kind: body.kind, message: body.message, side: which });
319
+ return null;
320
+ };
321
+ for (const plan of plans) {
322
+ const after = side(
323
+ plan.currentFile ? current.get(plan.currentFile) : undefined,
324
+ plan.currentFile,
325
+ "after",
326
+ );
327
+ // An unchanged entry's base is its current body: no base read.
328
+ const before =
329
+ plan.kind === null
330
+ ? after
331
+ : side(
332
+ plan.baseFile ? baseBodies.get(plan.baseFile) : undefined,
333
+ plan.baseFile,
334
+ "before",
335
+ );
336
+ entries[plan.name] = {
337
+ kind: plan.kind,
338
+ before,
339
+ after,
340
+ version: plan.version,
341
+ baseVersion: plan.baseVersion,
342
+ };
343
+ }
344
+ diagnostics.sort((a, b) => byFile(a, b) || (a.side < b.side ? -1 : a.side > b.side ? 1 : 0));
345
+ return { base: toChangesBase(state.base), entries, diagnostics };
346
+ }
347
+ throw unavailable("saved blocks kept changing while being read; retry shortly", 250);
348
+ }
349
+
350
+ /** Reads current bodies; `null` when one changed since the snapshot. */
351
+ async function readCurrentBodies(
352
+ core: Core,
353
+ snapshot: StorageSnapshot,
354
+ files: string[],
355
+ ): Promise<Map<string, ParsedBody> | null> {
356
+ const out = new Map<string, ParsedBody>();
357
+ const versionOf = new Map(snapshot.files.map((f) => [f.file, f]));
358
+ const toRead: string[] = [];
359
+ for (const file of files) {
360
+ const info = versionOf.get(file);
361
+ if (!info) return null;
362
+ if (info.size !== undefined && info.size > MAX_BLOCK_BYTES) {
363
+ out.set(file, {
364
+ ok: false,
365
+ kind: "too-large",
366
+ bytes: info.size,
367
+ message: `the file is over ${MAX_BLOCK_BYTES} bytes`,
368
+ });
369
+ continue;
370
+ }
371
+ const hit = core.cache.get(file, info.version);
372
+ if (hit) out.set(file, hit);
373
+ else toRead.push(file);
374
+ }
375
+ if (toRead.length === 0) return out;
376
+ const bodies: Record<string, StoredFileBody> = await core.storage.readFiles(snapshot, toRead);
377
+ for (const file of toRead) {
378
+ const read = bodies[file];
379
+ if (read === undefined) return null;
380
+ const body = parseBody(read.text, MAX_BLOCK_BYTES);
381
+ core.cache.set(file, read.version, body);
382
+ if (read.version !== versionOf.get(file)!.version) return null;
383
+ out.set(file, body);
384
+ }
385
+ return out;
386
+ }
387
+
388
+ /** The files a guarded entry has now (every spelling), as commit expectations. */
389
+ function guardExpectations(
390
+ state: ChangesState,
391
+ ifMatch: Array<[string, string | null]>,
392
+ ): Record<string, string | null> {
393
+ const versionOf = new Map(
394
+ state.snapshot.files.filter((f) => isBlockFileName(f.file)).map((f) => [f.file, f.version]),
395
+ );
396
+ const expected: Record<string, string | null> = Object.create(null);
397
+ for (const [name] of ifMatch) {
398
+ const group = (state.content.groups.get(spellingKey(name)) ?? []).map((f) => f.file);
399
+ for (const file of [blockFileName(name), ...group]) {
400
+ if (isBlockFileName(file)) expected[file] = versionOf.get(file) ?? null;
401
+ }
402
+ }
403
+ return expected;
404
+ }
405
+
406
+ export async function changesDiscard(
407
+ core: Core,
408
+ params: ChangesDiscardParams,
409
+ ): Promise<BlocksApplyResult> {
410
+ const description = await core.description();
411
+ if (description.readOnly) throw readOnly();
412
+ const names = checkNames(params.names, MAX_OPS_PER_APPLY, "maxOpsPerDiscard", "changes.discard");
413
+ const violations: BlockViolation[] = [];
414
+ for (const name of names) {
415
+ for (const v of checkDeletedName(name))
416
+ violations.push({ name, rule: v.reason, message: v.message });
417
+ }
418
+ if (violations.length > 0) throw invalidBlock(violations);
419
+ const ifMatch = Object.entries(params.ifMatch ?? {});
420
+
421
+ for (let attempt = 1; attempt <= core.maxCommitAttempts; attempt++) {
422
+ const state = await loadChanges(core);
423
+ const mismatches = checkIfMatch(state.bySpelling, { ifMatch });
424
+ if (mismatches) throw conflict({ entries: mismatches });
425
+
426
+ const restore = new Map<string, StorageFile>();
427
+ const deletes: string[] = [];
428
+ const discarded: EntryChange[] = [];
429
+ for (const name of names) {
430
+ const change = state.changes.get(spellingKey(name));
431
+ if (!change || discarded.includes(change)) continue;
432
+ discarded.push(change);
433
+ const inBase = new Map(change.baseFiles.map((f) => [f.file, f]));
434
+ for (const file of change.changedFiles) {
435
+ const baseFile = inBase.get(file);
436
+ if (baseFile) restore.set(file, baseFile);
437
+ else deletes.push(file);
438
+ }
439
+ }
440
+
441
+ const currentVersions = () => {
442
+ const versions: Record<string, string | null> = Object.create(null);
443
+ for (const name of names) {
444
+ versions[name] = state.bySpelling.get(spellingKey(name))?.entry.version ?? null;
445
+ }
446
+ return versions;
447
+ };
448
+ if (restore.size === 0 && deletes.length === 0) {
449
+ return { revision: state.snapshot.revision, versions: currentVersions() };
450
+ }
451
+
452
+ const bodies = await core.storage.readBaseFiles(state.base, [...restore.keys()]);
453
+ const put: Record<string, string> = Object.create(null);
454
+ let baseMoved = false;
455
+ for (const file of restore.keys()) {
456
+ const body = bodies[file];
457
+ if (body === undefined) baseMoved = true;
458
+ else put[file] = body.text;
459
+ }
460
+ if (!baseMoved) {
461
+ const result = await core.storage.commit({
462
+ base: state.snapshot,
463
+ put,
464
+ delete: deletes,
465
+ expected: guardExpectations(state, ifMatch),
466
+ expectedBase: state.base.revision,
467
+ reason: "discard",
468
+ });
469
+ if (result.status === "committed") {
470
+ const versions = currentVersions();
471
+ const snapshotVersion = new Map(state.snapshot.files.map((f) => [f.file, f.version]));
472
+ for (const name of names) {
473
+ const change = state.changes.get(spellingKey(name));
474
+ if (!change) continue;
475
+ const file = change.baseFile;
476
+ versions[name] =
477
+ file === null ? null : (result.versions[file] ?? snapshotVersion.get(file) ?? null);
478
+ }
479
+ const touched = new Set(discarded.map((c) => spellingKey(c.name)));
480
+ for (const file of deletes) {
481
+ const name = blockNameFromFile(file);
482
+ if (!(name in versions) && touched.has(keyOf(file))) versions[name] = null;
483
+ }
484
+ return { revision: result.revision, versions };
485
+ }
486
+ }
487
+ if (attempt < core.maxCommitAttempts) await core.backoff(attempt);
488
+ }
489
+ throw unavailable(
490
+ `storage kept changing; gave up after ${core.maxCommitAttempts} commit attempts`,
491
+ 250,
492
+ );
493
+ }
@@ -16,6 +16,7 @@ import { validateParams } from "../params.ts";
16
16
  import { MAX_BATCH_CALLS, METHOD_NAMES, type MethodName, type RpcId } from "../types.ts";
17
17
  import { type Core, toProtocolError } from "./core.ts";
18
18
  import { blocksApply } from "./methods/apply.ts";
19
+ import { changesDiscard, changesGet, changesList } from "./methods/changes.ts";
19
20
  import { blocksList, describe, schemaGet } from "./methods/read.ts";
20
21
 
21
22
  type Envelope = { id: RpcId; method: MethodName; params: unknown };
@@ -57,6 +58,12 @@ async function run(core: Core, envelope: Envelope): Promise<unknown> {
57
58
  return blocksList(core, validateParams("blocks.list", envelope.params));
58
59
  case "blocks.apply":
59
60
  return blocksApply(core, validateParams("blocks.apply", envelope.params));
61
+ case "changes.list":
62
+ return changesList(core, validateParams("changes.list", envelope.params));
63
+ case "changes.get":
64
+ return changesGet(core, validateParams("changes.get", envelope.params));
65
+ case "changes.discard":
66
+ return changesDiscard(core, validateParams("changes.discard", envelope.params));
60
67
  }
61
68
  }
62
69