@decocms/blocks 7.72.0 → 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,140 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@decocms/blocks/protocol/conformance`: a black-box test suite any
|
|
3
|
+
* content-protocol endpoint runs over HTTP, which is how the filesystem
|
|
4
|
+
* storage, the site editor's GitHub backend and any other backend are kept to
|
|
5
|
+
* the same contract.
|
|
6
|
+
*
|
|
7
|
+
* Run it with any test runner:
|
|
8
|
+
*
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { describe, it } from "vitest";
|
|
11
|
+
* import { defineConformanceSuite } from "@decocms/blocks/protocol/conformance";
|
|
12
|
+
*
|
|
13
|
+
* defineConformanceSuite({ describe, it }, { endpoint: "http://127.0.0.1:4545/rpc", token });
|
|
14
|
+
* ```
|
|
15
|
+
*
|
|
16
|
+
* or collect a report with `runConformance(options)`. The suite writes only
|
|
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). Cases that
|
|
19
|
+
* don't apply to an endpoint (a read-only one, one without request keys)
|
|
20
|
+
* skip themselves. Browser-safe: it only needs `fetch`.
|
|
21
|
+
*/
|
|
22
|
+
import { assetCases } from "./cases/assets";
|
|
23
|
+
import { guardCases } from "./cases/guards";
|
|
24
|
+
import { readCases } from "./cases/reads";
|
|
25
|
+
import type { ConformanceCase } from "./cases/types";
|
|
26
|
+
import { wireCases } from "./cases/wire";
|
|
27
|
+
import { writeCases } from "./cases/writes";
|
|
28
|
+
import { ConformanceContext, type ConformanceOptions, SkipCase } from "./context";
|
|
29
|
+
|
|
30
|
+
export type { ConformanceCase } from "./cases/types";
|
|
31
|
+
export { type ContentHashFixture, contentHashFixtures } from "./contentHashFixtures";
|
|
32
|
+
export type { ConformanceOptions } from "./context";
|
|
33
|
+
|
|
34
|
+
/** Every conformance case, in the order they run. */
|
|
35
|
+
export const conformanceCases: readonly ConformanceCase[] = [
|
|
36
|
+
...wireCases,
|
|
37
|
+
...readCases,
|
|
38
|
+
...writeCases,
|
|
39
|
+
...guardCases,
|
|
40
|
+
...assetCases,
|
|
41
|
+
];
|
|
42
|
+
|
|
43
|
+
function defaultPrefix(): string {
|
|
44
|
+
return `conformance-${Math.random().toString(36).slice(2, 8)}`;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export interface CaseOutcome {
|
|
48
|
+
id: string;
|
|
49
|
+
title: string;
|
|
50
|
+
status: "passed" | "failed" | "skipped";
|
|
51
|
+
/** Why it failed or was skipped. */
|
|
52
|
+
message?: string;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Runs one case with its own names, cleaning them up afterwards. */
|
|
56
|
+
async function runCase(
|
|
57
|
+
testCase: ConformanceCase,
|
|
58
|
+
options: ConformanceOptions,
|
|
59
|
+
prefix: string,
|
|
60
|
+
): Promise<CaseOutcome> {
|
|
61
|
+
const ctx = new ConformanceContext(options, prefix);
|
|
62
|
+
try {
|
|
63
|
+
await testCase.run(ctx);
|
|
64
|
+
return { id: testCase.id, title: testCase.title, status: "passed" };
|
|
65
|
+
} catch (error) {
|
|
66
|
+
if (error instanceof SkipCase) {
|
|
67
|
+
return { id: testCase.id, title: testCase.title, status: "skipped", message: error.message };
|
|
68
|
+
}
|
|
69
|
+
return {
|
|
70
|
+
id: testCase.id,
|
|
71
|
+
title: testCase.title,
|
|
72
|
+
status: "failed",
|
|
73
|
+
message: error instanceof Error ? error.message : String(error),
|
|
74
|
+
};
|
|
75
|
+
} finally {
|
|
76
|
+
await ctx.cleanup();
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
export interface ConformanceReport {
|
|
81
|
+
passed: number;
|
|
82
|
+
failed: number;
|
|
83
|
+
skipped: number;
|
|
84
|
+
outcomes: CaseOutcome[];
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** Runs every case (or the ones `filter` keeps) in order and reports the outcomes. */
|
|
88
|
+
export async function runConformance(
|
|
89
|
+
options: ConformanceOptions,
|
|
90
|
+
filter: (testCase: ConformanceCase) => boolean = () => true,
|
|
91
|
+
): Promise<ConformanceReport> {
|
|
92
|
+
const prefix = options.namePrefix ?? defaultPrefix();
|
|
93
|
+
const outcomes: CaseOutcome[] = [];
|
|
94
|
+
let index = 0;
|
|
95
|
+
for (const testCase of conformanceCases.filter(filter)) {
|
|
96
|
+
outcomes.push(await runCase(testCase, options, `${prefix}-${++index}`));
|
|
97
|
+
}
|
|
98
|
+
const count = (status: CaseOutcome["status"]) =>
|
|
99
|
+
outcomes.filter((o) => o.status === status).length;
|
|
100
|
+
return { passed: count("passed"), failed: count("failed"), skipped: count("skipped"), outcomes };
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/** The parts of a test runner the suite registers itself with (vitest, jest, node:test, bun:test). */
|
|
104
|
+
export interface TestRegistrar {
|
|
105
|
+
describe(name: string, body: () => void): void;
|
|
106
|
+
it(
|
|
107
|
+
name: string,
|
|
108
|
+
body: (context?: { skip?: (note?: string) => void }) => Promise<void>,
|
|
109
|
+
timeout?: number,
|
|
110
|
+
): void;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** Registers one test per conformance case with a test runner. */
|
|
114
|
+
export function defineConformanceSuite(
|
|
115
|
+
runner: TestRegistrar,
|
|
116
|
+
options: ConformanceOptions | (() => ConformanceOptions),
|
|
117
|
+
suiteName = "content protocol conformance",
|
|
118
|
+
filter: (testCase: ConformanceCase) => boolean = () => true,
|
|
119
|
+
): void {
|
|
120
|
+
const resolve = typeof options === "function" ? options : () => options;
|
|
121
|
+
const prefix = defaultPrefix();
|
|
122
|
+
runner.describe(suiteName, () => {
|
|
123
|
+
conformanceCases.filter(filter).forEach((testCase, index) => {
|
|
124
|
+
runner.it(
|
|
125
|
+
`${testCase.id}: ${testCase.title}`,
|
|
126
|
+
async (context) => {
|
|
127
|
+
const resolved = resolve();
|
|
128
|
+
const outcome = await runCase(
|
|
129
|
+
testCase,
|
|
130
|
+
resolved,
|
|
131
|
+
`${resolved.namePrefix ?? prefix}-${index + 1}`,
|
|
132
|
+
);
|
|
133
|
+
if (outcome.status === "failed") throw new Error(outcome.message);
|
|
134
|
+
if (outcome.status === "skipped") context?.skip?.(outcome.message);
|
|
135
|
+
},
|
|
136
|
+
60_000,
|
|
137
|
+
);
|
|
138
|
+
});
|
|
139
|
+
});
|
|
140
|
+
}
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Content-protocol errors. Every failure travels as a JSON-RPC 2.0 `error`
|
|
3
|
+
* object (HTTP 200), except a missing or invalid bearer token (401) and a body
|
|
4
|
+
* over the size limit (413), which apply to the whole batch.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
export const ErrorCode = {
|
|
8
|
+
// Standard JSON-RPC 2.0 codes.
|
|
9
|
+
ParseError: -32700,
|
|
10
|
+
InvalidRequest: -32600,
|
|
11
|
+
MethodNotFound: -32601,
|
|
12
|
+
InvalidParams: -32602,
|
|
13
|
+
InternalError: -32603,
|
|
14
|
+
// Content-protocol codes.
|
|
15
|
+
NotFound: -32001,
|
|
16
|
+
Conflict: -32002,
|
|
17
|
+
InvalidBlock: -32003,
|
|
18
|
+
ReadOnly: -32005,
|
|
19
|
+
Unsupported: -32006,
|
|
20
|
+
LimitExceeded: -32007,
|
|
21
|
+
Unavailable: -32008,
|
|
22
|
+
Unauthorized: -32010,
|
|
23
|
+
Forbidden: -32011,
|
|
24
|
+
} as const;
|
|
25
|
+
|
|
26
|
+
export type ErrorCodeName = keyof typeof ErrorCode;
|
|
27
|
+
export type ErrorCodeValue = (typeof ErrorCode)[ErrorCodeName];
|
|
28
|
+
|
|
29
|
+
/** The JSON-RPC `error` object. */
|
|
30
|
+
export interface RpcErrorObject {
|
|
31
|
+
code: number;
|
|
32
|
+
message: string;
|
|
33
|
+
data?: unknown;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** One entry's failed `ifMatch` guard. */
|
|
37
|
+
export interface VersionMismatch {
|
|
38
|
+
expected: string | null;
|
|
39
|
+
actual: string | null;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** `error.data` of a Conflict (-32002). */
|
|
43
|
+
export interface ConflictData {
|
|
44
|
+
entries?: Record<string, VersionMismatch>;
|
|
45
|
+
schema?: { expected: string; actual: string | null };
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** One rule a `blocks.apply` breaks. */
|
|
49
|
+
export interface BlockViolation {
|
|
50
|
+
/** The entry name the violation is about. */
|
|
51
|
+
name: string;
|
|
52
|
+
/** A JSON Pointer inside the entry, when the violation is about one value. */
|
|
53
|
+
pointer?: string;
|
|
54
|
+
rule: string;
|
|
55
|
+
message: string;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** `error.data` of an InvalidBlock (-32003). */
|
|
59
|
+
export interface InvalidBlockData {
|
|
60
|
+
violations: BlockViolation[];
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** `error.data` of an Unavailable (-32008). */
|
|
64
|
+
export interface UnavailableData {
|
|
65
|
+
retryAfterMs?: number;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* An error a method fails with. The server turns it into the JSON-RPC
|
|
70
|
+
* `error` object; the client throws it back.
|
|
71
|
+
*/
|
|
72
|
+
export class ContentProtocolError extends Error {
|
|
73
|
+
readonly code: number;
|
|
74
|
+
readonly data: unknown;
|
|
75
|
+
|
|
76
|
+
constructor(code: number, message: string, data?: unknown) {
|
|
77
|
+
super(message);
|
|
78
|
+
this.name = "ContentProtocolError";
|
|
79
|
+
this.code = code;
|
|
80
|
+
this.data = data;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
toJSON(): RpcErrorObject {
|
|
84
|
+
return this.data === undefined
|
|
85
|
+
? { code: this.code, message: this.message }
|
|
86
|
+
: { code: this.code, message: this.message, data: this.data };
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
static from(error: RpcErrorObject): ContentProtocolError {
|
|
90
|
+
return new ContentProtocolError(error.code, error.message, error.data);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
export const notFound = (message: string) => new ContentProtocolError(ErrorCode.NotFound, message);
|
|
95
|
+
|
|
96
|
+
export const conflict = (data: ConflictData) =>
|
|
97
|
+
new ContentProtocolError(ErrorCode.Conflict, "a precondition failed", data);
|
|
98
|
+
|
|
99
|
+
export const invalidBlock = (violations: BlockViolation[]) =>
|
|
100
|
+
new ContentProtocolError(
|
|
101
|
+
ErrorCode.InvalidBlock,
|
|
102
|
+
violations.length === 1
|
|
103
|
+
? `invalid block "${violations[0]!.name}": ${violations[0]!.message}`
|
|
104
|
+
: `${violations.length} invalid blocks`,
|
|
105
|
+
{ violations } satisfies InvalidBlockData,
|
|
106
|
+
);
|
|
107
|
+
|
|
108
|
+
export const readOnly = () =>
|
|
109
|
+
new ContentProtocolError(ErrorCode.ReadOnly, "this endpoint is read-only");
|
|
110
|
+
|
|
111
|
+
export const unsupported = (message: string) =>
|
|
112
|
+
new ContentProtocolError(ErrorCode.Unsupported, message);
|
|
113
|
+
|
|
114
|
+
export const limitExceeded = (message: string, data?: Record<string, unknown>) =>
|
|
115
|
+
new ContentProtocolError(ErrorCode.LimitExceeded, message, data);
|
|
116
|
+
|
|
117
|
+
export const unavailable = (message: string, retryAfterMs?: number) =>
|
|
118
|
+
new ContentProtocolError(
|
|
119
|
+
ErrorCode.Unavailable,
|
|
120
|
+
message,
|
|
121
|
+
retryAfterMs === undefined ? undefined : ({ retryAfterMs } satisfies UnavailableData),
|
|
122
|
+
);
|
|
123
|
+
|
|
124
|
+
export const invalidParams = (message: string, data?: unknown) =>
|
|
125
|
+
new ContentProtocolError(ErrorCode.InvalidParams, message, data);
|
|
126
|
+
|
|
127
|
+
export const invalidRequest = (message: string) =>
|
|
128
|
+
new ContentProtocolError(ErrorCode.InvalidRequest, message);
|
|
129
|
+
|
|
130
|
+
export const methodNotFound = (method: string) =>
|
|
131
|
+
new ContentProtocolError(ErrorCode.MethodNotFound, `unknown method "${method}"`);
|
|
132
|
+
|
|
133
|
+
export const parseError = () => new ContentProtocolError(ErrorCode.ParseError, "invalid JSON");
|
|
134
|
+
|
|
135
|
+
export const internalError = () =>
|
|
136
|
+
new ContentProtocolError(ErrorCode.InternalError, "internal error");
|
|
137
|
+
|
|
138
|
+
export const unauthorized = () =>
|
|
139
|
+
new ContentProtocolError(ErrorCode.Unauthorized, "missing or invalid bearer token");
|
|
140
|
+
|
|
141
|
+
export const forbidden = () =>
|
|
142
|
+
new ContentProtocolError(ErrorCode.Forbidden, "not allowed for this project");
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@decocms/blocks/protocol`: the content protocol's method types, errors,
|
|
3
|
+
* client and file-name rule. Browser-safe.
|
|
4
|
+
*
|
|
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 four
|
|
7
|
+
* methods — `describe`, `schema.get`, `blocks.list` and `blocks.apply`.
|
|
8
|
+
*
|
|
9
|
+
* Subpaths:
|
|
10
|
+
* - `@decocms/blocks/protocol/keys` — the file-name rule (also re-exported here)
|
|
11
|
+
* - `@decocms/blocks/protocol/server` — `createContentHandler(storage)`
|
|
12
|
+
* - `@decocms/blocks/protocol/storage/fs` — the filesystem storage (Node only)
|
|
13
|
+
* - `@decocms/blocks/protocol/conformance` — a black-box test suite over HTTP
|
|
14
|
+
*
|
|
15
|
+
* The SDK's runtime never imports the protocol, so it never reaches an app
|
|
16
|
+
* bundle. The canonical hash it re-exports is the SDK's own dependency-free
|
|
17
|
+
* leaf module (see ./canonical.ts).
|
|
18
|
+
*/
|
|
19
|
+
export {
|
|
20
|
+
APPLY_DIGEST_DOMAIN,
|
|
21
|
+
applyRequestDigest,
|
|
22
|
+
CanonicalJsonError,
|
|
23
|
+
CONTENT_HASH_FORMAT,
|
|
24
|
+
canonicalJson,
|
|
25
|
+
computeContentRevision,
|
|
26
|
+
sha256Hex,
|
|
27
|
+
} from "./canonical";
|
|
28
|
+
export {
|
|
29
|
+
assertSupportedEndpoint,
|
|
30
|
+
type BatchCall,
|
|
31
|
+
type BatchOutcome,
|
|
32
|
+
type ContentClient,
|
|
33
|
+
type ContentClientOptions,
|
|
34
|
+
createContentClient,
|
|
35
|
+
} from "./client";
|
|
36
|
+
export * from "./errors";
|
|
37
|
+
export * from "./keys";
|
|
38
|
+
export * from "./storage";
|
|
39
|
+
export * from "./types";
|
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one file-name rule for saved blocks (`@decocms/blocks/protocol/keys`).
|
|
3
|
+
*
|
|
4
|
+
* The site editor, `deco serve` and `deco content` all import this module, so
|
|
5
|
+
* an entry the site editor edits is the entry the app renders:
|
|
6
|
+
*
|
|
7
|
+
* - **Name to file:** `encodeURIComponent(name) + ".json"`, directly in
|
|
8
|
+
* `.deco/blocks` (no subfolders).
|
|
9
|
+
* - **File to name:** decode the file name, without `.json`, exactly once. If
|
|
10
|
+
* decoding fails, the raw name is the entry name.
|
|
11
|
+
* - **Two spellings of one name** (files that decode to the same name after
|
|
12
|
+
* repeated decoding): one wins — the file whose entry has a `path`, then the
|
|
13
|
+
* one that took more decoding, then the lowest file name. The others are
|
|
14
|
+
* reported as diagnostics; a write overwrites the winning spelling and
|
|
15
|
+
* deletes the others in the same commit.
|
|
16
|
+
* - **File content:** `JSON.stringify(entry, null, 2)` plus a newline, UTF-8.
|
|
17
|
+
*
|
|
18
|
+
* Ported from the v7 `blocks-cli/scripts/lib/blocks-dedupe.ts` and
|
|
19
|
+
* `blocks/src/cms/loadDecofileDirectory.ts` (`parseBlockId`), with the mtime
|
|
20
|
+
* tie-break dropped: a fresh clone gives every file the same mtime, and the
|
|
21
|
+
* rule must give the same answer on GitHub, where there is no mtime.
|
|
22
|
+
*
|
|
23
|
+
* Browser-safe: no Node APIs.
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
/** The extension every saved-block file carries. */
|
|
27
|
+
export const BLOCK_FILE_EXTENSION = ".json";
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* The longest encoded name (without `.json`) the site editor can save, so the
|
|
31
|
+
* file fits a 255-byte file-name limit.
|
|
32
|
+
*/
|
|
33
|
+
export const MAX_ENCODED_NAME_BYTES = 250;
|
|
34
|
+
|
|
35
|
+
/** Windows device names: a file whose stem is one of these can't be created on Windows. */
|
|
36
|
+
const WINDOWS_DEVICE_NAMES = new Set([
|
|
37
|
+
"CON",
|
|
38
|
+
"PRN",
|
|
39
|
+
"AUX",
|
|
40
|
+
"NUL",
|
|
41
|
+
...Array.from({ length: 9 }, (_, i) => `COM${i + 1}`),
|
|
42
|
+
...Array.from({ length: 9 }, (_, i) => `LPT${i + 1}`),
|
|
43
|
+
]);
|
|
44
|
+
|
|
45
|
+
/** Extensions of source modules: a saved block ending in one would shadow a module. */
|
|
46
|
+
const SOURCE_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
|
|
47
|
+
|
|
48
|
+
const utf8 = new TextEncoder();
|
|
49
|
+
|
|
50
|
+
/** `encodeURIComponent(name) + ".json"`: the file a saved block named `name` is stored in. */
|
|
51
|
+
export function blockFileName(name: string): string {
|
|
52
|
+
return `${encodeURIComponent(name)}${BLOCK_FILE_EXTENSION}`;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* True when `file` is a saved-block file name: it ends in `.json`, has a stem,
|
|
57
|
+
* isn't in a folder and isn't a dotfile (hidden files are never entries).
|
|
58
|
+
*/
|
|
59
|
+
export function isBlockFileName(file: string): boolean {
|
|
60
|
+
return (
|
|
61
|
+
file.endsWith(BLOCK_FILE_EXTENSION) &&
|
|
62
|
+
!file.startsWith(".") &&
|
|
63
|
+
file.length > BLOCK_FILE_EXTENSION.length &&
|
|
64
|
+
!file.includes("/") &&
|
|
65
|
+
!file.includes("\\")
|
|
66
|
+
);
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
function stem(file: string): string {
|
|
70
|
+
return file.endsWith(BLOCK_FILE_EXTENSION) ? file.slice(0, -BLOCK_FILE_EXTENSION.length) : file;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* The entry name stored in `file`: the stem decoded exactly once. A stem that
|
|
75
|
+
* isn't valid percent-encoding (a page literally named `50% off`) is the name
|
|
76
|
+
* as it stands.
|
|
77
|
+
*/
|
|
78
|
+
export function blockNameFromFile(file: string): string {
|
|
79
|
+
const raw = stem(file);
|
|
80
|
+
try {
|
|
81
|
+
return decodeURIComponent(raw);
|
|
82
|
+
} catch {
|
|
83
|
+
return raw;
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Decodes `file`'s stem repeatedly until it stops changing, returning the
|
|
89
|
+
* fully decoded name (the spelling-group key) and how many decodes it took.
|
|
90
|
+
*/
|
|
91
|
+
export function fullyDecodeFileName(file: string): { name: string; passes: number } {
|
|
92
|
+
let name = stem(file);
|
|
93
|
+
let passes = 0;
|
|
94
|
+
while (name.includes("%")) {
|
|
95
|
+
let next: string;
|
|
96
|
+
try {
|
|
97
|
+
next = decodeURIComponent(name);
|
|
98
|
+
} catch {
|
|
99
|
+
break;
|
|
100
|
+
}
|
|
101
|
+
if (next === name) break;
|
|
102
|
+
name = next;
|
|
103
|
+
passes++;
|
|
104
|
+
}
|
|
105
|
+
return { name, passes };
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** The spelling-group key of a saved-block name: every file of the group decodes to it. */
|
|
109
|
+
export function spellingKey(name: string): string {
|
|
110
|
+
return fullyDecodeFileName(blockFileName(name)).name;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** `JSON.stringify(entry, null, 2)` plus a newline: the bytes a saved block is stored as. */
|
|
114
|
+
export function serializeBlock(entry: unknown): string {
|
|
115
|
+
return `${JSON.stringify(entry, null, 2)}\n`;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** True when a parsed entry is a page-like entry: it has a non-empty string `path`. */
|
|
119
|
+
export function entryHasPath(entry: unknown): boolean {
|
|
120
|
+
return (
|
|
121
|
+
typeof entry === "object" &&
|
|
122
|
+
entry !== null &&
|
|
123
|
+
!Array.isArray(entry) &&
|
|
124
|
+
typeof (entry as { path?: unknown }).path === "string" &&
|
|
125
|
+
(entry as { path: string }).path.length > 0
|
|
126
|
+
);
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/** One file that holds (a spelling of) a saved block. */
|
|
130
|
+
export interface SpellingCandidate {
|
|
131
|
+
file: string;
|
|
132
|
+
/** Whether the file's entry has a non-empty `path`. */
|
|
133
|
+
hasPath: boolean;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** Orders two spellings of one name: negative when `a` wins. */
|
|
137
|
+
export function compareSpellings(a: SpellingCandidate, b: SpellingCandidate): number {
|
|
138
|
+
if (a.hasPath !== b.hasPath) return a.hasPath ? -1 : 1;
|
|
139
|
+
const passesA = fullyDecodeFileName(a.file).passes;
|
|
140
|
+
const passesB = fullyDecodeFileName(b.file).passes;
|
|
141
|
+
if (passesA !== passesB) return passesB - passesA;
|
|
142
|
+
if (a.file === b.file) return 0;
|
|
143
|
+
return a.file < b.file ? -1 : 1;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/** The winner of one spelling group and the files it shadows. */
|
|
147
|
+
export interface ResolvedSpelling<T extends SpellingCandidate = SpellingCandidate> {
|
|
148
|
+
/** The entry name: the winning file's stem decoded exactly once. */
|
|
149
|
+
name: string;
|
|
150
|
+
winner: T;
|
|
151
|
+
/** The other spellings, best first. */
|
|
152
|
+
shadowed: T[];
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* Groups candidate files by spelling key and picks one winner per group.
|
|
157
|
+
* Returns the groups keyed by entry name, in file-name order of the winners.
|
|
158
|
+
*/
|
|
159
|
+
export function resolveSpellings<T extends SpellingCandidate>(
|
|
160
|
+
candidates: readonly T[],
|
|
161
|
+
): Map<string, ResolvedSpelling<T>> {
|
|
162
|
+
const groups = new Map<string, T[]>();
|
|
163
|
+
for (const candidate of candidates) {
|
|
164
|
+
const key = fullyDecodeFileName(candidate.file).name;
|
|
165
|
+
const group = groups.get(key);
|
|
166
|
+
if (group) group.push(candidate);
|
|
167
|
+
else groups.set(key, [candidate]);
|
|
168
|
+
}
|
|
169
|
+
const winners: ResolvedSpelling<T>[] = [];
|
|
170
|
+
for (const group of groups.values()) {
|
|
171
|
+
const [winner, ...shadowed] = [...group].sort(compareSpellings);
|
|
172
|
+
if (!winner) continue;
|
|
173
|
+
winners.push({ name: blockNameFromFile(winner.file), winner, shadowed });
|
|
174
|
+
}
|
|
175
|
+
winners.sort((a, b) =>
|
|
176
|
+
a.winner.file < b.winner.file ? -1 : a.winner.file > b.winner.file ? 1 : 0,
|
|
177
|
+
);
|
|
178
|
+
return new Map(winners.map((w) => [w.name, w]));
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/** Why a name can't be saved. */
|
|
182
|
+
export type NameViolationReason =
|
|
183
|
+
| "empty"
|
|
184
|
+
| "invalid-character"
|
|
185
|
+
| "dot-dot"
|
|
186
|
+
| "leading-dot"
|
|
187
|
+
| "too-long"
|
|
188
|
+
| "case-collision"
|
|
189
|
+
| "device-name"
|
|
190
|
+
| "reserved"
|
|
191
|
+
| "source-extension";
|
|
192
|
+
|
|
193
|
+
export interface NameViolation {
|
|
194
|
+
reason: NameViolationReason;
|
|
195
|
+
message: string;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
export interface NameCheckOptions {
|
|
199
|
+
/**
|
|
200
|
+
* The names of the entries that already exist. A name that isn't one of
|
|
201
|
+
* them is new, and a new name that differs from an existing one only in
|
|
202
|
+
* letter case is refused.
|
|
203
|
+
*/
|
|
204
|
+
existingNames?: Iterable<string>;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/**
|
|
208
|
+
* Checks whether the site editor may save an entry under `name`. Returns
|
|
209
|
+
* every rule the name breaks (empty when it can be saved).
|
|
210
|
+
*/
|
|
211
|
+
export function checkBlockName(name: string, options: NameCheckOptions = {}): NameViolation[] {
|
|
212
|
+
const violations: NameViolation[] = [];
|
|
213
|
+
if (name.length === 0) {
|
|
214
|
+
return [{ reason: "empty", message: "the name is empty" }];
|
|
215
|
+
}
|
|
216
|
+
if (name.includes("\\") || name.includes("\0")) {
|
|
217
|
+
violations.push({
|
|
218
|
+
reason: "invalid-character",
|
|
219
|
+
message: "the name contains a backslash or a NUL character",
|
|
220
|
+
});
|
|
221
|
+
}
|
|
222
|
+
if (name.includes("..")) {
|
|
223
|
+
violations.push({ reason: "dot-dot", message: 'the name contains ".."' });
|
|
224
|
+
}
|
|
225
|
+
if (name.startsWith(".")) {
|
|
226
|
+
violations.push({
|
|
227
|
+
reason: "leading-dot",
|
|
228
|
+
message: 'the name starts with ".", which would make its file hidden',
|
|
229
|
+
});
|
|
230
|
+
}
|
|
231
|
+
if (name === "__proto__") {
|
|
232
|
+
violations.push({ reason: "reserved", message: 'the name "__proto__" is reserved' });
|
|
233
|
+
}
|
|
234
|
+
const encoded = encodeURIComponent(name);
|
|
235
|
+
if (utf8.encode(encoded).byteLength > MAX_ENCODED_NAME_BYTES) {
|
|
236
|
+
violations.push({
|
|
237
|
+
reason: "too-long",
|
|
238
|
+
message: `the encoded name is over ${MAX_ENCODED_NAME_BYTES} bytes`,
|
|
239
|
+
});
|
|
240
|
+
}
|
|
241
|
+
const deviceStem = encoded.split(".")[0]!.toUpperCase();
|
|
242
|
+
if (WINDOWS_DEVICE_NAMES.has(deviceStem)) {
|
|
243
|
+
violations.push({
|
|
244
|
+
reason: "device-name",
|
|
245
|
+
message: `"${deviceStem}" is a Windows device name`,
|
|
246
|
+
});
|
|
247
|
+
}
|
|
248
|
+
const lower = name.toLowerCase();
|
|
249
|
+
const extension = SOURCE_EXTENSIONS.find((ext) => lower.endsWith(ext));
|
|
250
|
+
if (extension) {
|
|
251
|
+
violations.push({
|
|
252
|
+
reason: "source-extension",
|
|
253
|
+
message: `the name ends in "${extension}", which would shadow a source module`,
|
|
254
|
+
});
|
|
255
|
+
}
|
|
256
|
+
if (options.existingNames) {
|
|
257
|
+
let isNew = true;
|
|
258
|
+
let collidesWith: string | undefined;
|
|
259
|
+
for (const existing of options.existingNames) {
|
|
260
|
+
if (existing === name) {
|
|
261
|
+
isNew = false;
|
|
262
|
+
break;
|
|
263
|
+
}
|
|
264
|
+
if (collidesWith === undefined && existing.toLowerCase() === lower) collidesWith = existing;
|
|
265
|
+
}
|
|
266
|
+
if (isNew && collidesWith !== undefined) {
|
|
267
|
+
violations.push({
|
|
268
|
+
reason: "case-collision",
|
|
269
|
+
message: `the name differs from the existing entry "${collidesWith}" only in letter case`,
|
|
270
|
+
});
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
return violations;
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/** Checks a name a write deletes: anything non-empty can be deleted. */
|
|
277
|
+
export function checkDeletedName(name: string): NameViolation[] {
|
|
278
|
+
return name.length === 0 ? [{ reason: "empty", message: "the name is empty" }] : [];
|
|
279
|
+
}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Parameter validation for the four methods. `params` is always an object;
|
|
3
|
+
* unknown parameters are rejected, so a guard the server doesn't understand
|
|
4
|
+
* never turns into an unguarded write.
|
|
5
|
+
*
|
|
6
|
+
* zod only checks the shape: callers keep using the raw object, because a
|
|
7
|
+
* parsed copy of a record would turn an own `__proto__` key into a prototype.
|
|
8
|
+
*/
|
|
9
|
+
import { z } from "zod";
|
|
10
|
+
import { invalidParams } from "./errors";
|
|
11
|
+
import type { BlocksApplyParams, MethodName, ReadParams } from "./types";
|
|
12
|
+
|
|
13
|
+
const opaque = z.string().min(1).max(1024);
|
|
14
|
+
|
|
15
|
+
const readParams = z.strictObject({
|
|
16
|
+
ref: z.string().min(1).max(255).optional(),
|
|
17
|
+
ifNoneMatch: opaque.optional(),
|
|
18
|
+
});
|
|
19
|
+
|
|
20
|
+
const applyParams = z.strictObject({
|
|
21
|
+
ref: z.string().min(1).max(255).optional(),
|
|
22
|
+
requestKey: z.string().min(1).max(256).optional(),
|
|
23
|
+
ifSchemaMatch: opaque.optional(),
|
|
24
|
+
// Entry shapes are checked later and reported as InvalidBlock, all at once.
|
|
25
|
+
set: z.record(z.string(), z.unknown()).optional(),
|
|
26
|
+
delete: z.array(z.string()).optional(),
|
|
27
|
+
ifMatch: z.record(z.string(), opaque.nullable()).optional(),
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
const schemas: Record<MethodName, z.ZodType> = {
|
|
31
|
+
describe: z.strictObject({}),
|
|
32
|
+
"schema.get": readParams,
|
|
33
|
+
"blocks.list": readParams,
|
|
34
|
+
"blocks.apply": applyParams,
|
|
35
|
+
};
|
|
36
|
+
|
|
37
|
+
function describeIssues(error: z.ZodError): string {
|
|
38
|
+
return error.issues
|
|
39
|
+
.map((issue) => {
|
|
40
|
+
const path = issue.path.length ? issue.path.join(".") : "params";
|
|
41
|
+
if (issue.code === "unrecognized_keys") {
|
|
42
|
+
return `unknown parameter${issue.keys.length > 1 ? "s" : ""} ${issue.keys
|
|
43
|
+
.map((k) => `"${k}"`)
|
|
44
|
+
.join(", ")}`;
|
|
45
|
+
}
|
|
46
|
+
return `${path}: ${issue.message}`;
|
|
47
|
+
})
|
|
48
|
+
.join("; ");
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Checks `params` for `method` and returns it as given (never a copy).
|
|
53
|
+
* Throws Invalid params (-32602) when it doesn't fit.
|
|
54
|
+
*/
|
|
55
|
+
export function validateParams(method: "describe", params: unknown): Record<string, never>;
|
|
56
|
+
export function validateParams(method: "schema.get" | "blocks.list", params: unknown): ReadParams;
|
|
57
|
+
export function validateParams(method: "blocks.apply", params: unknown): BlocksApplyParams;
|
|
58
|
+
export function validateParams(method: MethodName, params: unknown): unknown;
|
|
59
|
+
export function validateParams(method: MethodName, params: unknown): unknown {
|
|
60
|
+
const value = params === undefined ? {} : params;
|
|
61
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) {
|
|
62
|
+
throw invalidParams("params must be an object");
|
|
63
|
+
}
|
|
64
|
+
const result = schemas[method].safeParse(value);
|
|
65
|
+
if (!result.success) throw invalidParams(describeIssues(result.error));
|
|
66
|
+
return value;
|
|
67
|
+
}
|