@decocms/blocks 8.0.0 → 8.1.0-next.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (220) hide show
  1. package/bin/deco.js +13 -0
  2. package/package.json +32 -82
  3. package/src/index.ts +35 -8
  4. package/src/protocol/assets.ts +124 -0
  5. package/src/protocol/canonical.ts +7 -0
  6. package/src/protocol/ciphertext.ts +6 -0
  7. package/src/protocol/client.ts +170 -0
  8. package/src/protocol/conformance/cases/assets.ts +81 -0
  9. package/src/protocol/conformance/cases/guards.ts +314 -0
  10. package/src/protocol/conformance/cases/reads.ts +168 -0
  11. package/src/protocol/conformance/cases/types.ts +9 -0
  12. package/src/protocol/conformance/cases/wire.ts +138 -0
  13. package/src/protocol/conformance/cases/writes.ts +345 -0
  14. package/src/protocol/conformance/contentHashFixtures.ts +79 -0
  15. package/src/protocol/conformance/context.ts +222 -0
  16. package/src/protocol/conformance/index.ts +140 -0
  17. package/src/protocol/errors.ts +142 -0
  18. package/src/protocol/index.ts +39 -0
  19. package/src/protocol/keys.ts +279 -0
  20. package/src/protocol/params.ts +67 -0
  21. package/src/protocol/secrets.ts +231 -0
  22. package/src/protocol/server/assets.ts +119 -0
  23. package/src/protocol/server/auth.ts +49 -0
  24. package/src/protocol/server/bodyCache.ts +84 -0
  25. package/src/protocol/server/content.ts +175 -0
  26. package/src/protocol/server/core.ts +112 -0
  27. package/src/protocol/server/handler.ts +102 -0
  28. package/src/protocol/server/http.ts +139 -0
  29. package/src/protocol/server/index.ts +11 -0
  30. package/src/protocol/server/methods/apply.ts +341 -0
  31. package/src/protocol/server/methods/read.ts +156 -0
  32. package/src/protocol/server/rpc.ts +136 -0
  33. package/src/protocol/storage/fs/hash.ts +21 -0
  34. package/src/protocol/storage/fs/index.ts +338 -0
  35. package/src/protocol/storage/fs/lock.ts +68 -0
  36. package/src/protocol/storage/fs/transaction.ts +183 -0
  37. package/src/protocol/storage/fs/unsupported.ts +15 -0
  38. package/src/protocol/storage/memory.ts +238 -0
  39. package/src/protocol/storage.ts +182 -0
  40. package/src/protocol/types.ts +172 -0
  41. package/src/v8/analytics.ts +50 -0
  42. package/src/v8/background.ts +107 -0
  43. package/src/v8/builtins/data.ts +23 -0
  44. package/src/v8/builtins/index.ts +26 -0
  45. package/src/v8/builtins/lazy.ts +23 -0
  46. package/src/v8/builtins/legacy.ts +65 -0
  47. package/src/v8/builtins/matchers.ts +31 -0
  48. package/src/v8/builtins/multivariate.ts +25 -0
  49. package/src/v8/builtins/secret.ts +82 -0
  50. package/src/v8/canonical.ts +117 -0
  51. package/src/v8/ciphertext.ts +158 -0
  52. package/src/v8/cli/builtins.ts +20 -0
  53. package/src/v8/cli/check/index.ts +774 -0
  54. package/src/v8/cli/check/messages.ts +168 -0
  55. package/src/v8/cli/content.ts +287 -0
  56. package/src/v8/cli/index.ts +17 -0
  57. package/src/v8/cli/log.ts +18 -0
  58. package/src/v8/cli/main.ts +12 -0
  59. package/src/v8/cli/root.ts +66 -0
  60. package/src/v8/cli/run.ts +236 -0
  61. package/src/v8/cli/schema/builtinSchemas.ts +236 -0
  62. package/src/v8/cli/schema/generate.ts +507 -0
  63. package/src/v8/cli/schema/index.ts +63 -0
  64. package/src/v8/cli/schema/tsProgram.ts +497 -0
  65. package/src/v8/cli/schema/typeToSchema.ts +689 -0
  66. package/src/v8/cli/serve/server.ts +303 -0
  67. package/src/v8/cli/watch.ts +86 -0
  68. package/src/v8/client.ts +147 -0
  69. package/src/v8/cms.ts +237 -0
  70. package/src/v8/content.ts +195 -0
  71. package/src/v8/draft.ts +136 -0
  72. package/src/v8/errors.ts +59 -0
  73. package/src/v8/fetch.ts +133 -0
  74. package/src/v8/identity.ts +65 -0
  75. package/src/v8/index.ts +39 -0
  76. package/src/v8/json.ts +74 -0
  77. package/src/v8/matchRoute.ts +204 -0
  78. package/src/v8/remoteLoader.ts +282 -0
  79. package/src/v8/resolver.ts +278 -0
  80. package/src/v8/secrets.ts +17 -0
  81. package/src/v8/telemetry.ts +533 -0
  82. package/src/v8/types.ts +240 -0
  83. package/src/cms/applySectionConventions.ts +0 -124
  84. package/src/cms/blockSource.test.ts +0 -76
  85. package/src/cms/blockSource.ts +0 -191
  86. package/src/cms/client.browserBundle.test.ts +0 -44
  87. package/src/cms/client.ts +0 -80
  88. package/src/cms/draftSource.test.ts +0 -343
  89. package/src/cms/draftSource.ts +0 -362
  90. package/src/cms/index.ts +0 -151
  91. package/src/cms/layoutCacheRace.test.ts +0 -181
  92. package/src/cms/loadDecofileDirectory.test.ts +0 -109
  93. package/src/cms/loadDecofileDirectory.ts +0 -89
  94. package/src/cms/loader.test.ts +0 -200
  95. package/src/cms/loader.ts +0 -304
  96. package/src/cms/registry.test.ts +0 -110
  97. package/src/cms/registry.ts +0 -242
  98. package/src/cms/resolve.test.ts +0 -980
  99. package/src/cms/resolve.ts +0 -2282
  100. package/src/cms/schema.test.ts +0 -356
  101. package/src/cms/schema.ts +0 -1215
  102. package/src/cms/sectionLoaderContext.test.ts +0 -111
  103. package/src/cms/sectionLoaderContext.ts +0 -113
  104. package/src/cms/sectionLoaders.test.ts +0 -533
  105. package/src/cms/sectionLoaders.ts +0 -636
  106. package/src/cms/sectionMixins.test.ts +0 -167
  107. package/src/cms/sectionMixins.ts +0 -153
  108. package/src/cms/stickyFlags.test.ts +0 -117
  109. package/src/flags/audience.ts +0 -56
  110. package/src/flags/everyone.ts +0 -29
  111. package/src/flags/flag.ts +0 -15
  112. package/src/flags/flags.test.ts +0 -148
  113. package/src/flags/multivariate/image.ts +0 -11
  114. package/src/flags/multivariate/message.ts +0 -11
  115. package/src/flags/multivariate/page.ts +0 -16
  116. package/src/flags/multivariate/section.ts +0 -16
  117. package/src/flags/multivariate.ts +0 -1
  118. package/src/flags/types.ts +0 -59
  119. package/src/flags/utils/multivariate.ts +0 -20
  120. package/src/hooks/Image.test.ts +0 -100
  121. package/src/hooks/Image.tsx +0 -250
  122. package/src/hooks/JsonLd.tsx +0 -353
  123. package/src/hooks/LazySection.tsx +0 -121
  124. package/src/hooks/LiveControls.tsx +0 -122
  125. package/src/hooks/Picture.tsx +0 -127
  126. package/src/hooks/RenderSection.test.tsx +0 -81
  127. package/src/hooks/RenderSection.tsx +0 -91
  128. package/src/hooks/SectionErrorFallback.tsx +0 -97
  129. package/src/hooks/index.ts +0 -30
  130. package/src/matchers/builtins.test.ts +0 -318
  131. package/src/matchers/builtins.ts +0 -459
  132. package/src/matchers/countryNames.ts +0 -104
  133. package/src/matchers/override.test.ts +0 -205
  134. package/src/matchers/override.ts +0 -136
  135. package/src/matchers/posthog.ts +0 -154
  136. package/src/middleware/decoState.ts +0 -55
  137. package/src/middleware/healthMetrics.ts +0 -133
  138. package/src/middleware/hydrationContext.test.ts +0 -61
  139. package/src/middleware/hydrationContext.ts +0 -79
  140. package/src/middleware/index.ts +0 -88
  141. package/src/middleware/liveness.ts +0 -21
  142. package/src/middleware/observability.test.ts +0 -242
  143. package/src/middleware/observability.ts +0 -643
  144. package/src/middleware/validateSection.test.ts +0 -147
  145. package/src/middleware/validateSection.ts +0 -100
  146. package/src/sdk/abTesting.test.ts +0 -326
  147. package/src/sdk/abTesting.ts +0 -499
  148. package/src/sdk/analytics.ts +0 -77
  149. package/src/sdk/cacheHeaders.test.ts +0 -115
  150. package/src/sdk/cacheHeaders.ts +0 -433
  151. package/src/sdk/cachedLoader.test.ts +0 -122
  152. package/src/sdk/cachedLoader.ts +0 -503
  153. package/src/sdk/cachedLoaderModule.test.ts +0 -209
  154. package/src/sdk/clx.ts +0 -5
  155. package/src/sdk/cn.test.ts +0 -34
  156. package/src/sdk/cn.ts +0 -28
  157. package/src/sdk/composite.test.ts +0 -121
  158. package/src/sdk/composite.ts +0 -114
  159. package/src/sdk/cookie.test.ts +0 -108
  160. package/src/sdk/cookie.ts +0 -129
  161. package/src/sdk/crypto.ts +0 -185
  162. package/src/sdk/csp.ts +0 -59
  163. package/src/sdk/detectDevice.ts +0 -45
  164. package/src/sdk/djb2.ts +0 -20
  165. package/src/sdk/encoding.test.ts +0 -71
  166. package/src/sdk/encoding.ts +0 -47
  167. package/src/sdk/env.test.ts +0 -33
  168. package/src/sdk/env.ts +0 -54
  169. package/src/sdk/flags.test.ts +0 -91
  170. package/src/sdk/flags.ts +0 -108
  171. package/src/sdk/http.test.ts +0 -71
  172. package/src/sdk/http.ts +0 -124
  173. package/src/sdk/index.ts +0 -90
  174. package/src/sdk/inflightTimeout.test.ts +0 -35
  175. package/src/sdk/inflightTimeout.ts +0 -53
  176. package/src/sdk/instrumentedFetch.test.ts +0 -559
  177. package/src/sdk/instrumentedFetch.ts +0 -339
  178. package/src/sdk/invoke.test.ts +0 -115
  179. package/src/sdk/invoke.ts +0 -298
  180. package/src/sdk/logger.test.ts +0 -432
  181. package/src/sdk/logger.ts +0 -304
  182. package/src/sdk/mergeCacheControl.ts +0 -150
  183. package/src/sdk/normalizeUrls.ts +0 -91
  184. package/src/sdk/observability.ts +0 -109
  185. package/src/sdk/otel.test.ts +0 -526
  186. package/src/sdk/otel.ts +0 -1012
  187. package/src/sdk/otelAdapters/clickhouseCollector.ts +0 -65
  188. package/src/sdk/otelAdapters.test.ts +0 -89
  189. package/src/sdk/otelAdapters.ts +0 -144
  190. package/src/sdk/otelHttpLog.test.ts +0 -457
  191. package/src/sdk/otelHttpLog.ts +0 -419
  192. package/src/sdk/otelHttpMeter.test.ts +0 -292
  193. package/src/sdk/otelHttpMeter.ts +0 -506
  194. package/src/sdk/otelHttpTracer.test.ts +0 -474
  195. package/src/sdk/otelHttpTracer.ts +0 -543
  196. package/src/sdk/redirects.ts +0 -228
  197. package/src/sdk/requestContext.ts +0 -281
  198. package/src/sdk/requestContextStorage.browser.test.ts +0 -29
  199. package/src/sdk/requestContextStorage.browser.ts +0 -43
  200. package/src/sdk/requestContextStorage.ts +0 -35
  201. package/src/sdk/retry.ts +0 -45
  202. package/src/sdk/serverTimings.ts +0 -68
  203. package/src/sdk/signal.ts +0 -42
  204. package/src/sdk/sitemap.ts +0 -160
  205. package/src/sdk/urlRedaction.test.ts +0 -73
  206. package/src/sdk/urlRedaction.ts +0 -82
  207. package/src/sdk/urlUtils.ts +0 -134
  208. package/src/sdk/useDevice.test.ts +0 -130
  209. package/src/sdk/useDevice.ts +0 -89
  210. package/src/sdk/useDeviceContext.tsx +0 -108
  211. package/src/sdk/useId.ts +0 -7
  212. package/src/sdk/useScript.test.ts +0 -128
  213. package/src/sdk/useScript.ts +0 -210
  214. package/src/sdk/useSuggestions.test.ts +0 -230
  215. package/src/sdk/useSuggestions.ts +0 -188
  216. package/src/sdk/wrapCaughtErrors.ts +0 -107
  217. package/src/setup.ts +0 -120
  218. package/src/types/index.ts +0 -53
  219. package/src/types/widgets.ts +0 -14
  220. 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
+ }