@decocms/blocks 8.1.2 → 8.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/protocol/client.d.ts +17 -4
- package/dist/protocol/client.d.ts.map +1 -1
- package/dist/protocol/client.js +46 -10
- package/dist/protocol/client.js.map +1 -1
- package/dist/protocol/conformance/cases/changes.d.ts +3 -0
- package/dist/protocol/conformance/cases/changes.d.ts.map +1 -0
- package/dist/protocol/conformance/cases/changes.js +295 -0
- package/dist/protocol/conformance/cases/changes.js.map +1 -0
- package/dist/protocol/conformance/context.d.ts +14 -0
- package/dist/protocol/conformance/context.d.ts.map +1 -1
- package/dist/protocol/conformance/context.js.map +1 -1
- package/dist/protocol/conformance/index.d.ts.map +1 -1
- package/dist/protocol/conformance/index.js +4 -1
- package/dist/protocol/conformance/index.js.map +1 -1
- package/dist/protocol/errors.d.ts +26 -0
- package/dist/protocol/errors.d.ts.map +1 -1
- package/dist/protocol/errors.js.map +1 -1
- package/dist/protocol/index.d.ts +4 -2
- package/dist/protocol/index.d.ts.map +1 -1
- package/dist/protocol/index.js +4 -2
- package/dist/protocol/index.js.map +1 -1
- package/dist/protocol/params.d.ts +4 -2
- package/dist/protocol/params.d.ts.map +1 -1
- package/dist/protocol/params.js +11 -1
- package/dist/protocol/params.js.map +1 -1
- package/dist/protocol/server/assets.d.ts +1 -1
- package/dist/protocol/server/assets.js +1 -1
- package/dist/protocol/server/core.d.ts +12 -1
- package/dist/protocol/server/core.d.ts.map +1 -1
- package/dist/protocol/server/core.js +8 -0
- package/dist/protocol/server/core.js.map +1 -1
- package/dist/protocol/server/index.d.ts +1 -1
- package/dist/protocol/server/index.js +1 -1
- package/dist/protocol/server/methods/apply.d.ts +37 -0
- package/dist/protocol/server/methods/apply.d.ts.map +1 -1
- package/dist/protocol/server/methods/apply.js +4 -3
- package/dist/protocol/server/methods/apply.js.map +1 -1
- package/dist/protocol/server/methods/changes.d.ts +6 -0
- package/dist/protocol/server/methods/changes.d.ts.map +1 -0
- package/dist/protocol/server/methods/changes.js +381 -0
- package/dist/protocol/server/methods/changes.js.map +1 -0
- package/dist/protocol/server/rpc.d.ts.map +1 -1
- package/dist/protocol/server/rpc.js +7 -0
- package/dist/protocol/server/rpc.js.map +1 -1
- package/dist/protocol/storage/fs/git.d.ts +51 -0
- package/dist/protocol/storage/fs/git.d.ts.map +1 -0
- package/dist/protocol/storage/fs/git.js +274 -0
- package/dist/protocol/storage/fs/git.js.map +1 -0
- package/dist/protocol/storage/fs/index.d.ts +2 -0
- package/dist/protocol/storage/fs/index.d.ts.map +1 -1
- package/dist/protocol/storage/fs/index.js +34 -0
- package/dist/protocol/storage/fs/index.js.map +1 -1
- package/dist/protocol/storage/memory.d.ts +10 -0
- package/dist/protocol/storage/memory.d.ts.map +1 -1
- package/dist/protocol/storage/memory.js +45 -0
- package/dist/protocol/storage/memory.js.map +1 -1
- package/dist/protocol/storage.d.ts +49 -1
- package/dist/protocol/storage.d.ts.map +1 -1
- package/dist/protocol/storage.js.map +1 -1
- package/dist/protocol/types.d.ts +105 -4
- package/dist/protocol/types.d.ts.map +1 -1
- package/dist/protocol/types.js +16 -3
- package/dist/protocol/types.js.map +1 -1
- package/dist/v8/cli/run.d.ts.map +1 -1
- package/dist/v8/cli/run.js +2 -1
- package/dist/v8/cli/run.js.map +1 -1
- package/dist/v8/cli/serve/server.d.ts +2 -0
- package/dist/v8/cli/serve/server.d.ts.map +1 -1
- package/dist/v8/cli/serve/server.js +37 -2
- package/dist/v8/cli/serve/server.js.map +1 -1
- package/package.json +1 -1
- package/src/protocol/client.ts +81 -13
- package/src/protocol/conformance/cases/changes.ts +362 -0
- package/src/protocol/conformance/context.ts +12 -0
- package/src/protocol/conformance/index.ts +4 -1
- package/src/protocol/errors.ts +17 -0
- package/src/protocol/index.ts +4 -2
- package/src/protocol/params.ts +26 -3
- package/src/protocol/server/assets.ts +1 -1
- package/src/protocol/server/core.ts +9 -0
- package/src/protocol/server/index.ts +1 -1
- package/src/protocol/server/methods/apply.ts +8 -4
- package/src/protocol/server/methods/changes.ts +489 -0
- package/src/protocol/server/rpc.ts +7 -0
- package/src/protocol/storage/fs/git.ts +307 -0
- package/src/protocol/storage/fs/index.ts +40 -0
- package/src/protocol/storage/memory.ts +57 -0
- package/src/protocol/storage.ts +51 -1
- package/src/protocol/types.ts +106 -4
- package/src/v8/cli/run.ts +2 -1
- package/src/v8/cli/serve/server.ts +46 -2
|
@@ -0,0 +1,362 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `changes.list`, `changes.get` and `changes.discard` (protocol 1.1): what
|
|
3
|
+
* differs from the base, both sides of an entry, and dropping a change back
|
|
4
|
+
* to the base. The suite only reasons about its own names, plus the
|
|
5
|
+
* harness's `baseEntry` (which it always puts back), so other content on the
|
|
6
|
+
* endpoint doesn't matter.
|
|
7
|
+
*/
|
|
8
|
+
import { ErrorCode } from "../../errors.ts";
|
|
9
|
+
import { MAX_NAMES_PER_GET } from "../../server/core.ts";
|
|
10
|
+
import type { BlocksListResult, ChangesListResult } from "../../types.ts";
|
|
11
|
+
import { REQUIRED_PROTOCOL_MINOR } from "../../types.ts";
|
|
12
|
+
import {
|
|
13
|
+
assert,
|
|
14
|
+
assertEqual,
|
|
15
|
+
type ConformanceContext,
|
|
16
|
+
expectError,
|
|
17
|
+
rawErrorCode,
|
|
18
|
+
} from "../context.ts";
|
|
19
|
+
import type { ConformanceCase } from "./types.ts";
|
|
20
|
+
|
|
21
|
+
type FullChanges = Extract<ChangesListResult, { notModified: false }>;
|
|
22
|
+
type FullList = Extract<BlocksListResult, { notModified: false }>;
|
|
23
|
+
|
|
24
|
+
async function changes(ctx: ConformanceContext): Promise<FullChanges> {
|
|
25
|
+
const result = await ctx.client.changesList();
|
|
26
|
+
assert(!result.notModified, "an unconditional changes.list returns the changes");
|
|
27
|
+
return result;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
async function list(ctx: ConformanceContext): Promise<FullList> {
|
|
31
|
+
const result = await ctx.client.blocksList();
|
|
32
|
+
assert(!result.notModified, "an unconditional list returns the map");
|
|
33
|
+
return result;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
async function writable(ctx: ConformanceContext) {
|
|
37
|
+
const d = await ctx.describe();
|
|
38
|
+
if (d.readOnly) return ctx.skip("read-only endpoint");
|
|
39
|
+
return d;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** The harness's base entry, unchanged, with its current value and version. */
|
|
43
|
+
async function baseEntry(ctx: ConformanceContext) {
|
|
44
|
+
await writable(ctx);
|
|
45
|
+
const name = ctx.options.baseEntry?.name;
|
|
46
|
+
if (name === undefined) return ctx.skip("no baseEntry");
|
|
47
|
+
const blocks = await list(ctx);
|
|
48
|
+
assert(name in blocks.blocks, `the baseEntry "${name}" exists`);
|
|
49
|
+
const before = await changes(ctx);
|
|
50
|
+
assert(!(name in before.changes), `the baseEntry "${name}" starts unchanged`);
|
|
51
|
+
return { name, value: blocks.blocks[name]!, version: blocks.versions[name]! };
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const req = (id: number, method: string, params?: unknown) => ({
|
|
55
|
+
jsonrpc: "2.0",
|
|
56
|
+
id,
|
|
57
|
+
method,
|
|
58
|
+
params: params ?? {},
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
export const changesCases: ConformanceCase[] = [
|
|
62
|
+
{
|
|
63
|
+
id: "changes/version",
|
|
64
|
+
title: "the endpoint speaks protocol 1.1 or newer and knows the three changes methods",
|
|
65
|
+
async run(ctx) {
|
|
66
|
+
const d = await ctx.describe();
|
|
67
|
+
assert(
|
|
68
|
+
d.version.major === 1 && d.version.minor >= REQUIRED_PROTOCOL_MINOR,
|
|
69
|
+
`describe reports ${d.version.major}.${d.version.minor}`,
|
|
70
|
+
);
|
|
71
|
+
const response = await ctx.rpc([
|
|
72
|
+
req(1, "changes.list"),
|
|
73
|
+
req(2, "changes.get", { names: [] }),
|
|
74
|
+
req(3, "changes.discard", { names: [] }),
|
|
75
|
+
]);
|
|
76
|
+
const bodies = response.body as unknown[];
|
|
77
|
+
assert(Array.isArray(bodies) && bodies.length === 3, "three responses");
|
|
78
|
+
for (const body of bodies) {
|
|
79
|
+
assert(
|
|
80
|
+
rawErrorCode(body) !== ErrorCode.MethodNotFound,
|
|
81
|
+
`a changes method answered Method not found: ${JSON.stringify(body)}`,
|
|
82
|
+
);
|
|
83
|
+
}
|
|
84
|
+
},
|
|
85
|
+
},
|
|
86
|
+
{
|
|
87
|
+
id: "changes/list",
|
|
88
|
+
title: "changes.list reports the base and a revision that answers ifNoneMatch",
|
|
89
|
+
async run(ctx) {
|
|
90
|
+
const first = await changes(ctx);
|
|
91
|
+
assert(typeof first.revision === "string" && first.revision.length > 0, "a revision");
|
|
92
|
+
assert(typeof first.base?.revision === "string", "base.revision is a string");
|
|
93
|
+
assert(
|
|
94
|
+
first.base.resolvedRef === null || typeof first.base.resolvedRef === "string",
|
|
95
|
+
"base.resolvedRef is a string or null",
|
|
96
|
+
);
|
|
97
|
+
assert(typeof first.changes === "object" && first.changes !== null, "a changes map");
|
|
98
|
+
for (const [name, change] of Object.entries(first.changes)) {
|
|
99
|
+
assert(change.kind === "set" || change.kind === "delete", `${name}: kind`);
|
|
100
|
+
if (change.kind === "delete") assertEqual(change.version, null, `${name}: version`);
|
|
101
|
+
else assert(typeof change.version === "string", `${name}: a version`);
|
|
102
|
+
}
|
|
103
|
+
const poll = await ctx.client.changesList({ ifNoneMatch: first.revision });
|
|
104
|
+
assert(poll.notModified, "polling with the returned revision is 'not modified'");
|
|
105
|
+
assertEqual(poll.revision, first.revision, "the same revision");
|
|
106
|
+
assertEqual(poll.base, first.base, "'not modified' carries the base");
|
|
107
|
+
if ((await ctx.describe()).readOnly) return;
|
|
108
|
+
await ctx.client.blocksApply({ set: { [ctx.name("moves")]: { v: 1 } } });
|
|
109
|
+
const moved = await ctx.client.changesList({ ifNoneMatch: first.revision });
|
|
110
|
+
assert(!moved.notModified, "a write moves the changes' revision");
|
|
111
|
+
},
|
|
112
|
+
},
|
|
113
|
+
{
|
|
114
|
+
id: "changes/create-and-discard",
|
|
115
|
+
title: "a new entry is a set change with no base version; discarding it deletes it",
|
|
116
|
+
async run(ctx) {
|
|
117
|
+
await writable(ctx);
|
|
118
|
+
const name = ctx.name("new");
|
|
119
|
+
const value = { __resolveType: "hero", title: "Olá" };
|
|
120
|
+
const applied = await ctx.client.blocksApply({ set: { [name]: value } });
|
|
121
|
+
const listed = (await changes(ctx)).changes[name];
|
|
122
|
+
assertEqual(
|
|
123
|
+
listed,
|
|
124
|
+
{ kind: "set", version: applied.versions[name], baseVersion: null },
|
|
125
|
+
"the listed change",
|
|
126
|
+
);
|
|
127
|
+
|
|
128
|
+
const detail = await ctx.client.changesGet({ names: [name] });
|
|
129
|
+
assertEqual(
|
|
130
|
+
detail.entries[name],
|
|
131
|
+
{
|
|
132
|
+
kind: "set",
|
|
133
|
+
before: null,
|
|
134
|
+
after: value,
|
|
135
|
+
version: applied.versions[name],
|
|
136
|
+
baseVersion: null,
|
|
137
|
+
},
|
|
138
|
+
"both sides of the new entry",
|
|
139
|
+
);
|
|
140
|
+
assertEqual(detail.diagnostics, [], "no diagnostics");
|
|
141
|
+
|
|
142
|
+
const discarded = await ctx.client.changesDiscard({
|
|
143
|
+
names: [name],
|
|
144
|
+
ifMatch: { [name]: applied.versions[name]! },
|
|
145
|
+
});
|
|
146
|
+
assertEqual(discarded.versions[name], null, "a discarded new entry's version is null");
|
|
147
|
+
const after = await list(ctx);
|
|
148
|
+
assert(!(name in after.blocks), "the entry is gone from blocks.list");
|
|
149
|
+
assertEqual(after.revision, discarded.revision, "the result's revision is blocks.list's");
|
|
150
|
+
assert(!(name in (await changes(ctx)).changes), "the entry is no longer a change");
|
|
151
|
+
},
|
|
152
|
+
},
|
|
153
|
+
{
|
|
154
|
+
id: "changes/discard-conflict",
|
|
155
|
+
title: "a discard whose ifMatch fails is a Conflict and changes nothing",
|
|
156
|
+
async run(ctx) {
|
|
157
|
+
await writable(ctx);
|
|
158
|
+
const name = ctx.name("guarded");
|
|
159
|
+
const first = await ctx.client.blocksApply({ set: { [name]: { v: 1 } } });
|
|
160
|
+
const second = await ctx.client.blocksApply({ set: { [name]: { v: 2 } } });
|
|
161
|
+
const error = await expectError(
|
|
162
|
+
ctx.client.changesDiscard({ names: [name], ifMatch: { [name]: first.versions[name]! } }),
|
|
163
|
+
ErrorCode.Conflict,
|
|
164
|
+
"a stale ifMatch",
|
|
165
|
+
);
|
|
166
|
+
assertEqual(
|
|
167
|
+
(error.data as { entries?: unknown })?.entries,
|
|
168
|
+
{ [name]: { expected: first.versions[name], actual: second.versions[name] } },
|
|
169
|
+
"the conflict's entries",
|
|
170
|
+
);
|
|
171
|
+
const after = await list(ctx);
|
|
172
|
+
assertEqual(after.blocks[name], { v: 2 }, "nothing was discarded");
|
|
173
|
+
await expectError(
|
|
174
|
+
ctx.client.changesDiscard({ names: [name], ifMatch: { [name]: null } }),
|
|
175
|
+
ErrorCode.Conflict,
|
|
176
|
+
"ifMatch null on an entry that exists",
|
|
177
|
+
);
|
|
178
|
+
},
|
|
179
|
+
},
|
|
180
|
+
{
|
|
181
|
+
id: "changes/discard-noop",
|
|
182
|
+
title: "discarding a name without a change, or no names, writes nothing",
|
|
183
|
+
async run(ctx) {
|
|
184
|
+
await writable(ctx);
|
|
185
|
+
const name = ctx.name("absent");
|
|
186
|
+
const before = await list(ctx);
|
|
187
|
+
const none = await ctx.client.changesDiscard({ names: [] });
|
|
188
|
+
assertEqual(none.versions, {}, "no names, no versions");
|
|
189
|
+
assertEqual(none.revision, before.revision, "the revision is unchanged");
|
|
190
|
+
const absent = await ctx.client.changesDiscard({ names: [name] });
|
|
191
|
+
assertEqual(absent.versions, { [name]: null }, "an absent entry's version is null");
|
|
192
|
+
assertEqual((await list(ctx)).revision, before.revision, "nothing was written");
|
|
193
|
+
},
|
|
194
|
+
},
|
|
195
|
+
{
|
|
196
|
+
id: "changes/get-params",
|
|
197
|
+
title: "changes.get leaves out unknown names and refuses bad params",
|
|
198
|
+
async run(ctx) {
|
|
199
|
+
const unknown = await ctx.client.changesGet({ names: [ctx.name("nowhere")] });
|
|
200
|
+
assertEqual(unknown.entries, {}, "an unknown name is absent");
|
|
201
|
+
assert(typeof unknown.base?.revision === "string", "the base is reported");
|
|
202
|
+
for (const params of [
|
|
203
|
+
{},
|
|
204
|
+
{ names: "x" },
|
|
205
|
+
{ names: [""] },
|
|
206
|
+
{ names: [], extra: true },
|
|
207
|
+
{ name: "x" },
|
|
208
|
+
]) {
|
|
209
|
+
const response = await ctx.rpc(req(1, "changes.get", params));
|
|
210
|
+
assertEqual(
|
|
211
|
+
rawErrorCode(response.body),
|
|
212
|
+
ErrorCode.InvalidParams,
|
|
213
|
+
`changes.get(${JSON.stringify(params)})`,
|
|
214
|
+
);
|
|
215
|
+
}
|
|
216
|
+
const many = Array.from({ length: MAX_NAMES_PER_GET + 1 }, (_, i) => `${ctx.prefix}-${i}`);
|
|
217
|
+
await expectError(
|
|
218
|
+
ctx.client.changesGet({ names: many }),
|
|
219
|
+
ErrorCode.LimitExceeded,
|
|
220
|
+
"more names than changes.get takes",
|
|
221
|
+
);
|
|
222
|
+
const discard = await ctx.rpc(req(2, "changes.discard", { names: [], force: true }));
|
|
223
|
+
assertEqual(rawErrorCode(discard.body), ErrorCode.InvalidParams, "an unknown discard param");
|
|
224
|
+
},
|
|
225
|
+
},
|
|
226
|
+
{
|
|
227
|
+
id: "changes/batch",
|
|
228
|
+
title: "changes calls batch like any other method, results in order",
|
|
229
|
+
async run(ctx) {
|
|
230
|
+
const outcomes = await ctx.client.batch([
|
|
231
|
+
{ method: "changes.list" },
|
|
232
|
+
{ method: "changes.get", params: { names: [ctx.name("x")] } },
|
|
233
|
+
{ method: "blocks.list" },
|
|
234
|
+
]);
|
|
235
|
+
assert(
|
|
236
|
+
outcomes.every((o) => o.ok),
|
|
237
|
+
"every call succeeds",
|
|
238
|
+
);
|
|
239
|
+
assert(
|
|
240
|
+
typeof (outcomes[0] as { result: { base?: unknown } }).result.base === "object",
|
|
241
|
+
"the first result is changes.list's",
|
|
242
|
+
);
|
|
243
|
+
assert(
|
|
244
|
+
"entries" in (outcomes[1] as { result: object }).result,
|
|
245
|
+
"the second is changes.get's",
|
|
246
|
+
);
|
|
247
|
+
assert("blocks" in (outcomes[2] as { result: object }).result, "the third is blocks.list's");
|
|
248
|
+
},
|
|
249
|
+
},
|
|
250
|
+
{
|
|
251
|
+
id: "changes/read-only",
|
|
252
|
+
title: "a read-only endpoint lists and reads changes but refuses a discard",
|
|
253
|
+
async run(ctx) {
|
|
254
|
+
const d = await ctx.describe();
|
|
255
|
+
if (!d.readOnly) return ctx.skip("writable endpoint");
|
|
256
|
+
await changes(ctx);
|
|
257
|
+
await ctx.client.changesGet({ names: [ctx.name("x")] });
|
|
258
|
+
await expectError(
|
|
259
|
+
ctx.client.changesDiscard({ names: [ctx.name("x")] }),
|
|
260
|
+
ErrorCode.ReadOnly,
|
|
261
|
+
"a discard on a read-only endpoint",
|
|
262
|
+
);
|
|
263
|
+
},
|
|
264
|
+
},
|
|
265
|
+
{
|
|
266
|
+
id: "changes/base-modify",
|
|
267
|
+
title: "a modified base entry shows both sides; a discard restores it",
|
|
268
|
+
async run(ctx) {
|
|
269
|
+
const base = await baseEntry(ctx);
|
|
270
|
+
const modified = { ...base.value, conformance: ctx.prefix };
|
|
271
|
+
try {
|
|
272
|
+
const applied = await ctx.client.blocksApply({ set: { [base.name]: modified } });
|
|
273
|
+
const listed = (await changes(ctx)).changes[base.name];
|
|
274
|
+
assert(listed !== undefined, "the modified entry is listed");
|
|
275
|
+
assertEqual(listed!.kind, "set", "kind");
|
|
276
|
+
assertEqual(listed!.version, applied.versions[base.name], "version");
|
|
277
|
+
assert(typeof listed!.baseVersion === "string", "a base version");
|
|
278
|
+
|
|
279
|
+
const detail = (await ctx.client.changesGet({ names: [base.name] })).entries[base.name];
|
|
280
|
+
assertEqual(detail?.before, base.value, "before is the base");
|
|
281
|
+
assertEqual(detail?.after, modified, "after is the modified entry");
|
|
282
|
+
|
|
283
|
+
const discarded = await ctx.client.changesDiscard({
|
|
284
|
+
names: [base.name],
|
|
285
|
+
ifMatch: { [base.name]: applied.versions[base.name]! },
|
|
286
|
+
});
|
|
287
|
+
assert(typeof discarded.versions[base.name] === "string", "a version after the discard");
|
|
288
|
+
const after = await list(ctx);
|
|
289
|
+
assertEqual(after.blocks[base.name], base.value, "the base value is back");
|
|
290
|
+
assertEqual(after.versions[base.name], discarded.versions[base.name], "the listed version");
|
|
291
|
+
assert(!(base.name in (await changes(ctx)).changes), "no longer a change");
|
|
292
|
+
} finally {
|
|
293
|
+
await ctx.client.changesDiscard({ names: [base.name] }).catch(() => {});
|
|
294
|
+
}
|
|
295
|
+
},
|
|
296
|
+
},
|
|
297
|
+
{
|
|
298
|
+
id: "changes/base-delete",
|
|
299
|
+
title: "a deleted base entry is a delete change; a discard brings it back",
|
|
300
|
+
async run(ctx) {
|
|
301
|
+
const base = await baseEntry(ctx);
|
|
302
|
+
try {
|
|
303
|
+
await ctx.client.blocksApply({ delete: [base.name] });
|
|
304
|
+
const listed = (await changes(ctx)).changes[base.name];
|
|
305
|
+
assert(listed !== undefined, "the deleted entry is listed");
|
|
306
|
+
assertEqual(listed!.kind, "delete", "kind");
|
|
307
|
+
assertEqual(listed!.version, null, "version");
|
|
308
|
+
assert(typeof listed!.baseVersion === "string", "a base version");
|
|
309
|
+
|
|
310
|
+
const detail = (await ctx.client.changesGet({ names: [base.name] })).entries[base.name];
|
|
311
|
+
assertEqual(detail?.after, null, "after is null");
|
|
312
|
+
assertEqual(detail?.before, base.value, "before is the base");
|
|
313
|
+
|
|
314
|
+
await ctx.client.changesDiscard({ names: [base.name], ifMatch: { [base.name]: null } });
|
|
315
|
+
const after = await list(ctx);
|
|
316
|
+
assertEqual(after.blocks[base.name], base.value, "the entry is back");
|
|
317
|
+
assert(!(base.name in (await changes(ctx)).changes), "no longer a change");
|
|
318
|
+
} finally {
|
|
319
|
+
await ctx.client.changesDiscard({ names: [base.name] }).catch(() => {});
|
|
320
|
+
}
|
|
321
|
+
},
|
|
322
|
+
},
|
|
323
|
+
{
|
|
324
|
+
id: "changes/unchanged-entry",
|
|
325
|
+
title: "changes.get on an unchanged entry answers kind null with equal sides",
|
|
326
|
+
async run(ctx) {
|
|
327
|
+
const base = await baseEntry(ctx);
|
|
328
|
+
const detail = (await ctx.client.changesGet({ names: [base.name] })).entries[base.name];
|
|
329
|
+
assertEqual(
|
|
330
|
+
detail,
|
|
331
|
+
{
|
|
332
|
+
kind: null,
|
|
333
|
+
before: base.value,
|
|
334
|
+
after: base.value,
|
|
335
|
+
version: base.version,
|
|
336
|
+
baseVersion: base.version,
|
|
337
|
+
},
|
|
338
|
+
"an unchanged entry",
|
|
339
|
+
);
|
|
340
|
+
},
|
|
341
|
+
},
|
|
342
|
+
{
|
|
343
|
+
id: "changes/empty-base",
|
|
344
|
+
title: "with an empty base, every entry is a new set change",
|
|
345
|
+
async run(ctx) {
|
|
346
|
+
if (!ctx.options.emptyBase) return ctx.skip("the base isn't empty");
|
|
347
|
+
await writable(ctx);
|
|
348
|
+
const name = ctx.name("fresh");
|
|
349
|
+
await ctx.client.blocksApply({ set: { [name]: { v: 1 } } });
|
|
350
|
+
const all = await changes(ctx);
|
|
351
|
+
const blocks = await list(ctx);
|
|
352
|
+
for (const entry of Object.keys(blocks.blocks)) {
|
|
353
|
+
assertEqual(all.changes[entry]?.kind, "set", `${entry} is a set change`);
|
|
354
|
+
assertEqual(all.changes[entry]?.baseVersion, null, `${entry} has no base version`);
|
|
355
|
+
}
|
|
356
|
+
const detail = (await ctx.client.changesGet({ names: [name] })).entries[name];
|
|
357
|
+
assertEqual(detail?.before, null, "no base side");
|
|
358
|
+
await ctx.client.changesDiscard({ names: [name] });
|
|
359
|
+
assert(!(name in (await list(ctx)).blocks), "discarding deletes it");
|
|
360
|
+
},
|
|
361
|
+
},
|
|
362
|
+
];
|
|
@@ -33,6 +33,18 @@ export interface ConformanceOptions {
|
|
|
33
33
|
assetsEndpoint?: string | URL;
|
|
34
34
|
/** Prefix of every name the suite creates (default `conformance-<random>`). */
|
|
35
35
|
namePrefix?: string;
|
|
36
|
+
/**
|
|
37
|
+
* An entry the harness put in the endpoint's base (for `deco serve`: a
|
|
38
|
+
* block committed to `HEAD`) and left unchanged, for the `changes.*` cases
|
|
39
|
+
* that modify, delete and restore a base entry. Each case puts it back.
|
|
40
|
+
* Leave out to skip those cases.
|
|
41
|
+
*/
|
|
42
|
+
baseEntry?: { name: string };
|
|
43
|
+
/**
|
|
44
|
+
* The endpoint's base holds no saved blocks (such as a repository with no
|
|
45
|
+
* commits yet), so every entry is a change. Enables the empty-base case.
|
|
46
|
+
*/
|
|
47
|
+
emptyBase?: boolean;
|
|
36
48
|
}
|
|
37
49
|
|
|
38
50
|
/** Thrown by `ctx.skip()`: the case doesn't apply to this endpoint. */
|
|
@@ -15,11 +15,13 @@
|
|
|
15
15
|
*
|
|
16
16
|
* or collect a report with `runConformance(options)`. The suite writes only
|
|
17
17
|
* names under its own prefix and deletes them after each case (uploads, which
|
|
18
|
-
* the protocol can't delete, stay in the asset folder
|
|
18
|
+
* the protocol can't delete, stay in the asset folder; a `baseEntry` is put
|
|
19
|
+
* back with `changes.discard`). Cases that
|
|
19
20
|
* don't apply to an endpoint (a read-only one, one without a schema) skip
|
|
20
21
|
* themselves. Browser-safe: it only needs `fetch`.
|
|
21
22
|
*/
|
|
22
23
|
import { assetCases } from "./cases/assets.ts";
|
|
24
|
+
import { changesCases } from "./cases/changes.ts";
|
|
23
25
|
import { guardCases } from "./cases/guards.ts";
|
|
24
26
|
import { readCases } from "./cases/reads.ts";
|
|
25
27
|
import type { ConformanceCase } from "./cases/types.ts";
|
|
@@ -37,6 +39,7 @@ export const conformanceCases: readonly ConformanceCase[] = [
|
|
|
37
39
|
...readCases,
|
|
38
40
|
...writeCases,
|
|
39
41
|
...guardCases,
|
|
42
|
+
...changesCases,
|
|
40
43
|
...assetCases,
|
|
41
44
|
];
|
|
42
45
|
|
package/src/protocol/errors.ts
CHANGED
|
@@ -66,6 +66,23 @@ export interface UnavailableData {
|
|
|
66
66
|
retryAfterMs?: number;
|
|
67
67
|
}
|
|
68
68
|
|
|
69
|
+
/**
|
|
70
|
+
* `error.data` of the Unsupported (-32006) a client raises for an endpoint it
|
|
71
|
+
* can't talk to. `outdated`: same major, an older minor than the client needs
|
|
72
|
+
* (such as an 8.1.x `deco serve`, or a server that answered a `changes.*`
|
|
73
|
+
* call with MethodNotFound): update the server. `major`: another major.
|
|
74
|
+
* `protocol`: not a `deco-content` endpoint.
|
|
75
|
+
*/
|
|
76
|
+
export interface UnsupportedEndpointData {
|
|
77
|
+
reason: "outdated" | "major" | "protocol";
|
|
78
|
+
/** The protocol version this client needs. */
|
|
79
|
+
required: { major: number; minor: number };
|
|
80
|
+
/** What the endpoint reported (`describe`'s `protocol` and `version`), when it did. */
|
|
81
|
+
actual?: { protocol: unknown; major: unknown; minor: unknown };
|
|
82
|
+
/** The endpoint's `describe().server`, when it reported one. */
|
|
83
|
+
server?: { name: string; version: string };
|
|
84
|
+
}
|
|
85
|
+
|
|
69
86
|
/**
|
|
70
87
|
* An error a method fails with. The server turns it into the JSON-RPC
|
|
71
88
|
* `error` object; the client throws it back.
|
package/src/protocol/index.ts
CHANGED
|
@@ -3,8 +3,10 @@
|
|
|
3
3
|
* client and file-name rule. Browser-safe.
|
|
4
4
|
*
|
|
5
5
|
* The protocol is how the site editor reads and writes saved blocks without
|
|
6
|
-
* running a site's code: JSON-RPC 2.0 over one HTTP endpoint with
|
|
7
|
-
* methods — `describe`, `schema.get`, `blocks.list
|
|
6
|
+
* running a site's code: JSON-RPC 2.0 over one HTTP endpoint with seven
|
|
7
|
+
* methods — `describe`, `schema.get`, `blocks.list`, `blocks.apply`, and
|
|
8
|
+
* `changes.list`, `changes.get` and `changes.discard` (protocol 1.1: what
|
|
9
|
+
* differs from the base, both sides of an entry, and dropping a change).
|
|
8
10
|
*
|
|
9
11
|
* Subpaths:
|
|
10
12
|
* - `@decocms/blocks/protocol/keys` — the file-name rule (also re-exported here)
|
package/src/protocol/params.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Parameter validation for the
|
|
2
|
+
* Parameter validation for the seven methods. `params` is always an object;
|
|
3
3
|
* unknown parameters are rejected, so a guard the server doesn't understand
|
|
4
4
|
* never turns into an unguarded write.
|
|
5
5
|
*
|
|
@@ -8,7 +8,13 @@
|
|
|
8
8
|
*/
|
|
9
9
|
import { z } from "zod";
|
|
10
10
|
import { invalidParams } from "./errors.ts";
|
|
11
|
-
import type {
|
|
11
|
+
import type {
|
|
12
|
+
BlocksApplyParams,
|
|
13
|
+
ChangesDiscardParams,
|
|
14
|
+
ChangesGetParams,
|
|
15
|
+
MethodName,
|
|
16
|
+
ReadParams,
|
|
17
|
+
} from "./types.ts";
|
|
12
18
|
|
|
13
19
|
const opaque = z.string().min(1).max(1024);
|
|
14
20
|
|
|
@@ -23,11 +29,23 @@ const applyParams = z.strictObject({
|
|
|
23
29
|
ifMatch: z.record(z.string(), opaque.nullable()).optional(),
|
|
24
30
|
});
|
|
25
31
|
|
|
32
|
+
const namesParams = z.strictObject({
|
|
33
|
+
names: z.array(z.string()),
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
const discardParams = z.strictObject({
|
|
37
|
+
names: z.array(z.string()),
|
|
38
|
+
ifMatch: z.record(z.string(), opaque.nullable()).optional(),
|
|
39
|
+
});
|
|
40
|
+
|
|
26
41
|
const schemas: Record<MethodName, z.ZodType> = {
|
|
27
42
|
describe: z.strictObject({}),
|
|
28
43
|
"schema.get": readParams,
|
|
29
44
|
"blocks.list": readParams,
|
|
30
45
|
"blocks.apply": applyParams,
|
|
46
|
+
"changes.list": readParams,
|
|
47
|
+
"changes.get": namesParams,
|
|
48
|
+
"changes.discard": discardParams,
|
|
31
49
|
};
|
|
32
50
|
|
|
33
51
|
function describeIssues(error: z.ZodError): string {
|
|
@@ -49,8 +67,13 @@ function describeIssues(error: z.ZodError): string {
|
|
|
49
67
|
* Throws Invalid params (-32602) when it doesn't fit.
|
|
50
68
|
*/
|
|
51
69
|
export function validateParams(method: "describe", params: unknown): Record<string, never>;
|
|
52
|
-
export function validateParams(
|
|
70
|
+
export function validateParams(
|
|
71
|
+
method: "schema.get" | "blocks.list" | "changes.list",
|
|
72
|
+
params: unknown,
|
|
73
|
+
): ReadParams;
|
|
53
74
|
export function validateParams(method: "blocks.apply", params: unknown): BlocksApplyParams;
|
|
75
|
+
export function validateParams(method: "changes.get", params: unknown): ChangesGetParams;
|
|
76
|
+
export function validateParams(method: "changes.discard", params: unknown): ChangesDiscardParams;
|
|
54
77
|
export function validateParams(method: MethodName, params: unknown): unknown;
|
|
55
78
|
export function validateParams(method: MethodName, params: unknown): unknown {
|
|
56
79
|
const value = params === undefined ? {} : params;
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* `createAssetHandler(storage)`: uploads beside the content protocol.
|
|
3
3
|
*
|
|
4
|
-
* Uploads aren't one of the
|
|
4
|
+
* Uploads aren't one of the protocol's methods. The site editor sends each file to
|
|
5
5
|
* `PUT /assets/<name>`; on that path the
|
|
6
6
|
* file's own image, video, font or PDF content type is accepted instead of
|
|
7
7
|
* JSON, and the name's extension must match it (`banner.html` sent as
|
|
@@ -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
|
|
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
|
|
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(
|
|
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) {
|