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