@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.
- 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 +385 -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 +63 -0
- package/dist/protocol/storage/fs/git.d.ts.map +1 -0
- package/dist/protocol/storage/fs/git.js +376 -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 +53 -1
- 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 +53 -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 +493 -0
- package/src/protocol/server/rpc.ts +7 -0
- package/src/protocol/storage/fs/git.ts +424 -0
- package/src/protocol/storage/fs/index.ts +59 -1
- package/src/protocol/storage/memory.ts +57 -0
- package/src/protocol/storage.ts +55 -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
package/src/protocol/client.ts
CHANGED
|
@@ -2,13 +2,19 @@
|
|
|
2
2
|
* A small content-protocol client: one method per protocol method, plus
|
|
3
3
|
* batches. Uses `fetch`, so it runs in browsers, on Workers and on Node.
|
|
4
4
|
*/
|
|
5
|
-
import {
|
|
5
|
+
import {
|
|
6
|
+
ContentProtocolError,
|
|
7
|
+
ErrorCode,
|
|
8
|
+
type RpcErrorObject,
|
|
9
|
+
type UnsupportedEndpointData,
|
|
10
|
+
} from "./errors.ts";
|
|
6
11
|
import {
|
|
7
12
|
type DescribeResult,
|
|
8
13
|
type MethodName,
|
|
9
14
|
type Methods,
|
|
10
15
|
PROTOCOL_NAME,
|
|
11
16
|
PROTOCOL_VERSION,
|
|
17
|
+
REQUIRED_PROTOCOL_MINOR,
|
|
12
18
|
type RpcId,
|
|
13
19
|
} from "./types.ts";
|
|
14
20
|
|
|
@@ -32,14 +38,29 @@ export type BatchOutcome =
|
|
|
32
38
|
| { ok: false; error: ContentProtocolError };
|
|
33
39
|
|
|
34
40
|
export interface ContentClient {
|
|
35
|
-
/**
|
|
41
|
+
/**
|
|
42
|
+
* Throws Unsupported when the endpoint speaks another protocol or major
|
|
43
|
+
* version, or an older minor than this client needs (`data.reason`, see
|
|
44
|
+
* `UnsupportedEndpointData`).
|
|
45
|
+
*/
|
|
36
46
|
describe(): Promise<Methods["describe"]["result"]>;
|
|
37
47
|
schemaGet(params?: Methods["schema.get"]["params"]): Promise<Methods["schema.get"]["result"]>;
|
|
38
48
|
blocksList(params?: Methods["blocks.list"]["params"]): Promise<Methods["blocks.list"]["result"]>;
|
|
39
49
|
blocksApply(
|
|
40
50
|
params: Methods["blocks.apply"]["params"],
|
|
41
51
|
): Promise<Methods["blocks.apply"]["result"]>;
|
|
42
|
-
|
|
52
|
+
changesList(
|
|
53
|
+
params?: Methods["changes.list"]["params"],
|
|
54
|
+
): Promise<Methods["changes.list"]["result"]>;
|
|
55
|
+
changesGet(params: Methods["changes.get"]["params"]): Promise<Methods["changes.get"]["result"]>;
|
|
56
|
+
changesDiscard(
|
|
57
|
+
params: Methods["changes.discard"]["params"],
|
|
58
|
+
): Promise<Methods["changes.discard"]["result"]>;
|
|
59
|
+
/**
|
|
60
|
+
* Calls one method by name. Throws `ContentProtocolError` on an error
|
|
61
|
+
* response; a server too old for a `changes.*` method (MethodNotFound)
|
|
62
|
+
* becomes the same Unsupported `describe` raises (`reason: "outdated"`).
|
|
63
|
+
*/
|
|
43
64
|
call<M extends MethodName>(
|
|
44
65
|
method: M,
|
|
45
66
|
params?: Methods[M]["params"],
|
|
@@ -67,27 +88,71 @@ export async function readResponseJson(response: Response): Promise<unknown> {
|
|
|
67
88
|
return JSON.parse(new TextDecoder().decode(bytes));
|
|
68
89
|
}
|
|
69
90
|
|
|
91
|
+
const REQUIRED_VERSION = { major: PROTOCOL_VERSION.major, minor: REQUIRED_PROTOCOL_MINOR };
|
|
92
|
+
|
|
93
|
+
/** The guidance for a server older than this client: update it. */
|
|
94
|
+
const OUTDATED_MESSAGE =
|
|
95
|
+
`the endpoint speaks an older ${PROTOCOL_NAME} than this client needs ` +
|
|
96
|
+
`(${REQUIRED_VERSION.major}.${REQUIRED_VERSION.minor} or newer): update @decocms/blocks in the site ` +
|
|
97
|
+
"(8.2.0 or newer) and start deco serve again";
|
|
98
|
+
|
|
99
|
+
function unsupportedEndpoint(
|
|
100
|
+
message: string,
|
|
101
|
+
reason: UnsupportedEndpointData["reason"],
|
|
102
|
+
description?: Partial<DescribeResult>,
|
|
103
|
+
): ContentProtocolError {
|
|
104
|
+
const data: UnsupportedEndpointData = { reason, required: { ...REQUIRED_VERSION } };
|
|
105
|
+
if (description) {
|
|
106
|
+
data.actual = {
|
|
107
|
+
protocol: description.protocol,
|
|
108
|
+
major: description.version?.major,
|
|
109
|
+
minor: description.version?.minor,
|
|
110
|
+
};
|
|
111
|
+
const server = description.server;
|
|
112
|
+
if (typeof server?.name === "string" && typeof server.version === "string") {
|
|
113
|
+
data.server = { name: server.name, version: server.version };
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
return new ContentProtocolError(ErrorCode.Unsupported, message, data);
|
|
117
|
+
}
|
|
118
|
+
|
|
70
119
|
/**
|
|
71
|
-
* Refuses an endpoint this client can't speak to: another protocol,
|
|
72
|
-
*
|
|
120
|
+
* Refuses an endpoint this client can't speak to: another protocol, another
|
|
121
|
+
* major version, or a minor older than `REQUIRED_PROTOCOL_MINOR` (minors only
|
|
122
|
+
* add, so any newer minor is fine). The error's `data` is an
|
|
123
|
+
* `UnsupportedEndpointData`; `reason: "outdated"` means "update the server".
|
|
73
124
|
*/
|
|
74
125
|
export function assertSupportedEndpoint(description: DescribeResult): DescribeResult {
|
|
75
|
-
const
|
|
126
|
+
const reported = (description ?? {}) as Partial<DescribeResult>;
|
|
127
|
+
const { protocol, version } = reported;
|
|
76
128
|
if (protocol !== PROTOCOL_NAME) {
|
|
77
|
-
throw
|
|
78
|
-
ErrorCode.Unsupported,
|
|
129
|
+
throw unsupportedEndpoint(
|
|
79
130
|
`the endpoint speaks ${JSON.stringify(protocol)}, not ${PROTOCOL_NAME}`,
|
|
131
|
+
"protocol",
|
|
132
|
+
reported,
|
|
80
133
|
);
|
|
81
134
|
}
|
|
82
135
|
if (version?.major !== PROTOCOL_VERSION.major) {
|
|
83
|
-
throw
|
|
84
|
-
ErrorCode.Unsupported,
|
|
136
|
+
throw unsupportedEndpoint(
|
|
85
137
|
`the endpoint speaks ${PROTOCOL_NAME} ${String(version?.major)}.x; this client speaks ${PROTOCOL_VERSION.major}.x`,
|
|
138
|
+
"major",
|
|
139
|
+
reported,
|
|
86
140
|
);
|
|
87
141
|
}
|
|
142
|
+
if (typeof version.minor !== "number" || version.minor < REQUIRED_PROTOCOL_MINOR) {
|
|
143
|
+
throw unsupportedEndpoint(OUTDATED_MESSAGE, "outdated", reported);
|
|
144
|
+
}
|
|
88
145
|
return description;
|
|
89
146
|
}
|
|
90
147
|
|
|
148
|
+
/** A server that doesn't know a `changes.*` method is older than this client. */
|
|
149
|
+
function fromWireError(method: string, error: RpcErrorObject): ContentProtocolError {
|
|
150
|
+
if (error.code === ErrorCode.MethodNotFound && method.startsWith("changes.")) {
|
|
151
|
+
return unsupportedEndpoint(OUTDATED_MESSAGE, "outdated");
|
|
152
|
+
}
|
|
153
|
+
return ContentProtocolError.from(error);
|
|
154
|
+
}
|
|
155
|
+
|
|
91
156
|
export function createContentClient(options: ContentClientOptions): ContentClient {
|
|
92
157
|
const doFetch = options.fetch ?? ((request: Request) => fetch(request));
|
|
93
158
|
let nextId = 1;
|
|
@@ -129,7 +194,7 @@ export function createContentClient(options: ContentClientOptions): ContentClien
|
|
|
129
194
|
method,
|
|
130
195
|
params: params ?? {},
|
|
131
196
|
})) as WireResponse;
|
|
132
|
-
if (response.error) throw
|
|
197
|
+
if (response.error) throw fromWireError(method, response.error);
|
|
133
198
|
return response.result as Methods[M]["result"];
|
|
134
199
|
};
|
|
135
200
|
|
|
@@ -139,6 +204,9 @@ export function createContentClient(options: ContentClientOptions): ContentClien
|
|
|
139
204
|
schemaGet: (params) => call("schema.get", params),
|
|
140
205
|
blocksList: (params) => call("blocks.list", params),
|
|
141
206
|
blocksApply: (params) => call("blocks.apply", params),
|
|
207
|
+
changesList: (params) => call("changes.list", params),
|
|
208
|
+
changesGet: (params) => call("changes.get", params),
|
|
209
|
+
changesDiscard: (params) => call("changes.discard", params),
|
|
142
210
|
async batch(calls) {
|
|
143
211
|
const ids = calls.map(() => nextId++);
|
|
144
212
|
const responses = (await post(
|
|
@@ -150,7 +218,7 @@ export function createContentClient(options: ContentClientOptions): ContentClien
|
|
|
150
218
|
})),
|
|
151
219
|
)) as WireResponse[];
|
|
152
220
|
const byId = new Map(responses.map((r) => [r.id, r]));
|
|
153
|
-
return ids.map((id): BatchOutcome => {
|
|
221
|
+
return ids.map((id, i): BatchOutcome => {
|
|
154
222
|
const response = byId.get(id);
|
|
155
223
|
if (!response) {
|
|
156
224
|
return {
|
|
@@ -159,7 +227,7 @@ export function createContentClient(options: ContentClientOptions): ContentClien
|
|
|
159
227
|
};
|
|
160
228
|
}
|
|
161
229
|
return response.error
|
|
162
|
-
? { ok: false, error:
|
|
230
|
+
? { ok: false, error: fromWireError(calls[i]!.method, response.error) }
|
|
163
231
|
: { ok: true, result: response.result };
|
|
164
232
|
});
|
|
165
233
|
},
|
|
@@ -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
|