@decocms/blocks 8.0.0 → 8.1.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.
Files changed (175) hide show
  1. package/bin/deco.js +13 -0
  2. package/package.json +39 -3
  3. package/src/cms/applySectionConventions.ts +26 -2
  4. package/src/cms/blockSource.ts +37 -0
  5. package/src/cms/client.ts +5 -0
  6. package/src/cms/deferredTrigger.ts +58 -0
  7. package/src/cms/draftSource.ts +171 -57
  8. package/src/cms/index.ts +32 -3
  9. package/src/cms/loader.ts +318 -59
  10. package/src/cms/registry.ts +22 -0
  11. package/src/cms/renderJson.ts +179 -0
  12. package/src/cms/resolve.ts +396 -95
  13. package/src/cms/schema.ts +9 -5
  14. package/src/cms/sectionLoaders.ts +106 -56
  15. package/src/hooks/Image.tsx +70 -6
  16. package/src/hooks/LiveControls.tsx +30 -8
  17. package/src/hooks/Stats.tsx +134 -0
  18. package/src/hooks/index.ts +5 -0
  19. package/src/hooks/useLoadMore.ts +100 -0
  20. package/src/index.ts +37 -0
  21. package/src/middleware/observability.ts +173 -16
  22. package/src/preview/DraftPreviewBadge.tsx +306 -0
  23. package/src/preview/decoMark.ts +11 -0
  24. package/src/preview/index.ts +8 -0
  25. package/src/protocol/assets.ts +124 -0
  26. package/src/protocol/canonical.ts +7 -0
  27. package/src/protocol/ciphertext.ts +6 -0
  28. package/src/protocol/client.ts +170 -0
  29. package/src/protocol/conformance/cases/assets.ts +81 -0
  30. package/src/protocol/conformance/cases/guards.ts +314 -0
  31. package/src/protocol/conformance/cases/reads.ts +168 -0
  32. package/src/protocol/conformance/cases/types.ts +9 -0
  33. package/src/protocol/conformance/cases/wire.ts +138 -0
  34. package/src/protocol/conformance/cases/writes.ts +345 -0
  35. package/src/protocol/conformance/contentHashFixtures.ts +79 -0
  36. package/src/protocol/conformance/context.ts +222 -0
  37. package/src/protocol/conformance/index.ts +140 -0
  38. package/src/protocol/errors.ts +142 -0
  39. package/src/protocol/index.ts +39 -0
  40. package/src/protocol/keys.ts +279 -0
  41. package/src/protocol/params.ts +67 -0
  42. package/src/protocol/secrets.ts +231 -0
  43. package/src/protocol/server/assets.ts +119 -0
  44. package/src/protocol/server/auth.ts +49 -0
  45. package/src/protocol/server/bodyCache.ts +84 -0
  46. package/src/protocol/server/content.ts +175 -0
  47. package/src/protocol/server/core.ts +112 -0
  48. package/src/protocol/server/handler.ts +102 -0
  49. package/src/protocol/server/http.ts +139 -0
  50. package/src/protocol/server/index.ts +11 -0
  51. package/src/protocol/server/methods/apply.ts +341 -0
  52. package/src/protocol/server/methods/read.ts +156 -0
  53. package/src/protocol/server/rpc.ts +136 -0
  54. package/src/protocol/storage/fs/hash.ts +21 -0
  55. package/src/protocol/storage/fs/index.ts +338 -0
  56. package/src/protocol/storage/fs/lock.ts +68 -0
  57. package/src/protocol/storage/fs/transaction.ts +183 -0
  58. package/src/protocol/storage/fs/unsupported.ts +15 -0
  59. package/src/protocol/storage/memory.ts +238 -0
  60. package/src/protocol/storage.ts +182 -0
  61. package/src/protocol/types.ts +172 -0
  62. package/src/sdk/abTesting.ts +60 -3
  63. package/src/sdk/analytics.ts +72 -2
  64. package/src/sdk/cacheHeaders.ts +210 -10
  65. package/src/sdk/cacheStorage.ts +287 -0
  66. package/src/sdk/cachedLoader.ts +143 -90
  67. package/src/sdk/crypto.ts +16 -2
  68. package/src/sdk/deepOmit.ts +52 -0
  69. package/src/sdk/encoding.ts +2 -5
  70. package/src/sdk/experiments.ts +314 -0
  71. package/src/sdk/fetchCache.ts +269 -0
  72. package/src/sdk/fetchTimeout.ts +58 -0
  73. package/src/sdk/flags.ts +38 -8
  74. package/src/sdk/index.ts +7 -0
  75. package/src/sdk/instrumentedFetch.ts +25 -2
  76. package/src/sdk/nonce.ts +46 -0
  77. package/src/sdk/normalizeUrls.ts +2 -2
  78. package/src/sdk/observability.ts +8 -1
  79. package/src/sdk/otel.ts +131 -25
  80. package/src/sdk/otelHttpLog.ts +4 -4
  81. package/src/sdk/otelHttpMeter.ts +39 -13
  82. package/src/sdk/otelHttpTracer.ts +4 -4
  83. package/src/sdk/redirects.ts +113 -5
  84. package/src/sdk/responseCache.ts +82 -0
  85. package/src/sdk/urlUtils.ts +49 -0
  86. package/src/sdk/useSuggestions.ts +1 -1
  87. package/src/v8/analytics.ts +50 -0
  88. package/src/v8/background.ts +107 -0
  89. package/src/v8/builtins/data.ts +23 -0
  90. package/src/v8/builtins/index.ts +26 -0
  91. package/src/v8/builtins/lazy.ts +23 -0
  92. package/src/v8/builtins/legacy.ts +65 -0
  93. package/src/v8/builtins/matchers.ts +31 -0
  94. package/src/v8/builtins/multivariate.ts +25 -0
  95. package/src/v8/builtins/secret.ts +82 -0
  96. package/src/v8/canonical.ts +117 -0
  97. package/src/v8/ciphertext.ts +158 -0
  98. package/src/v8/cli/builtins.ts +20 -0
  99. package/src/v8/cli/check/index.ts +774 -0
  100. package/src/v8/cli/check/messages.ts +168 -0
  101. package/src/v8/cli/content.ts +287 -0
  102. package/src/v8/cli/index.ts +17 -0
  103. package/src/v8/cli/log.ts +18 -0
  104. package/src/v8/cli/main.ts +12 -0
  105. package/src/v8/cli/root.ts +66 -0
  106. package/src/v8/cli/run.ts +236 -0
  107. package/src/v8/cli/schema/builtinSchemas.ts +236 -0
  108. package/src/v8/cli/schema/generate.ts +507 -0
  109. package/src/v8/cli/schema/index.ts +63 -0
  110. package/src/v8/cli/schema/tsProgram.ts +497 -0
  111. package/src/v8/cli/schema/typeToSchema.ts +689 -0
  112. package/src/v8/cli/serve/server.ts +303 -0
  113. package/src/v8/cli/watch.ts +86 -0
  114. package/src/v8/client.ts +147 -0
  115. package/src/v8/cms.ts +237 -0
  116. package/src/v8/content.ts +195 -0
  117. package/src/v8/draft.ts +136 -0
  118. package/src/v8/errors.ts +59 -0
  119. package/src/v8/fetch.ts +152 -0
  120. package/src/v8/identity.ts +65 -0
  121. package/src/v8/index.ts +39 -0
  122. package/src/v8/json.ts +74 -0
  123. package/src/v8/matchRoute.ts +204 -0
  124. package/src/v8/remoteLoader.ts +282 -0
  125. package/src/v8/resolver.ts +278 -0
  126. package/src/v8/secrets.ts +17 -0
  127. package/src/v8/telemetry.ts +533 -0
  128. package/src/v8/types.ts +240 -0
  129. package/src/cms/blockSource.test.ts +0 -76
  130. package/src/cms/client.browserBundle.test.ts +0 -44
  131. package/src/cms/draftSource.test.ts +0 -343
  132. package/src/cms/layoutCacheRace.test.ts +0 -181
  133. package/src/cms/loadDecofileDirectory.test.ts +0 -109
  134. package/src/cms/loader.test.ts +0 -200
  135. package/src/cms/registry.test.ts +0 -110
  136. package/src/cms/resolve.test.ts +0 -980
  137. package/src/cms/schema.test.ts +0 -356
  138. package/src/cms/sectionLoaderContext.test.ts +0 -111
  139. package/src/cms/sectionLoaders.test.ts +0 -533
  140. package/src/cms/sectionMixins.test.ts +0 -167
  141. package/src/cms/stickyFlags.test.ts +0 -117
  142. package/src/flags/flags.test.ts +0 -148
  143. package/src/hooks/Image.test.ts +0 -100
  144. package/src/hooks/RenderSection.test.tsx +0 -81
  145. package/src/matchers/builtins.test.ts +0 -318
  146. package/src/matchers/override.test.ts +0 -205
  147. package/src/middleware/hydrationContext.test.ts +0 -61
  148. package/src/middleware/observability.test.ts +0 -242
  149. package/src/middleware/validateSection.test.ts +0 -147
  150. package/src/sdk/abTesting.test.ts +0 -326
  151. package/src/sdk/cacheHeaders.test.ts +0 -115
  152. package/src/sdk/cachedLoader.test.ts +0 -122
  153. package/src/sdk/cachedLoaderModule.test.ts +0 -209
  154. package/src/sdk/cn.test.ts +0 -34
  155. package/src/sdk/composite.test.ts +0 -121
  156. package/src/sdk/cookie.test.ts +0 -108
  157. package/src/sdk/encoding.test.ts +0 -71
  158. package/src/sdk/env.test.ts +0 -33
  159. package/src/sdk/flags.test.ts +0 -91
  160. package/src/sdk/http.test.ts +0 -71
  161. package/src/sdk/inflightTimeout.test.ts +0 -35
  162. package/src/sdk/instrumentedFetch.test.ts +0 -559
  163. package/src/sdk/invoke.test.ts +0 -115
  164. package/src/sdk/logger.test.ts +0 -432
  165. package/src/sdk/otel.test.ts +0 -526
  166. package/src/sdk/otelAdapters.test.ts +0 -89
  167. package/src/sdk/otelHttpLog.test.ts +0 -457
  168. package/src/sdk/otelHttpMeter.test.ts +0 -292
  169. package/src/sdk/otelHttpTracer.test.ts +0 -474
  170. package/src/sdk/requestContextStorage.browser.test.ts +0 -29
  171. package/src/sdk/urlRedaction.test.ts +0 -73
  172. package/src/sdk/useDevice.test.ts +0 -130
  173. package/src/sdk/useScript.test.ts +0 -128
  174. package/src/sdk/useSuggestions.test.ts +0 -230
  175. package/tsconfig.json +0 -7
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Request authorization shared by the content handler and the asset handler.
3
+ */
4
+ import { bearerToken, timingSafeEqualStrings } from "./http";
5
+
6
+ /**
7
+ * What an `authorize` hook decides:
8
+ * - `true` or `{ scope }` — allowed. `scope` names the tenant and principal,
9
+ * and scopes request-key receipts, so one tenant never replays another's.
10
+ * - `false` or `"unauthorized"` — a missing or invalid bearer token (HTTP 401).
11
+ * - `"forbidden"` — authenticated, but not allowed for this project.
12
+ */
13
+ export type AuthorizeResult = boolean | "unauthorized" | "forbidden" | { scope?: string };
14
+
15
+ export interface AuthOptions {
16
+ /** When set, every request must carry `Authorization: Bearer <token>`. */
17
+ token?: string;
18
+ /** Decides whether a request may proceed (runs after the token check). */
19
+ authorize?: (request: Request) => AuthorizeResult | Promise<AuthorizeResult>;
20
+ }
21
+
22
+ /**
23
+ * Refuses options that would lock every client out by accident: an empty
24
+ * token can never be presented, so every request would be 401.
25
+ */
26
+ export function assertAuthOptions(options: AuthOptions): void {
27
+ if (options.token !== undefined && (typeof options.token !== "string" || options.token === "")) {
28
+ throw new TypeError("token must be a non-empty string; omit it to accept requests without one");
29
+ }
30
+ }
31
+
32
+ type AuthOutcome =
33
+ | { ok: true; scope: string }
34
+ | { ok: false; reason: "unauthorized" | "forbidden" };
35
+
36
+ export async function authenticate(request: Request, options: AuthOptions): Promise<AuthOutcome> {
37
+ if (options.token !== undefined) {
38
+ const presented = bearerToken(request);
39
+ if (presented === null || !(await timingSafeEqualStrings(presented, options.token))) {
40
+ return { ok: false, reason: "unauthorized" };
41
+ }
42
+ }
43
+ if (!options.authorize) return { ok: true, scope: "" };
44
+ const result = await options.authorize(request);
45
+ if (result === true) return { ok: true, scope: "" };
46
+ if (result === false || result === "unauthorized") return { ok: false, reason: "unauthorized" };
47
+ if (result === "forbidden") return { ok: false, reason: "forbidden" };
48
+ return { ok: true, scope: result.scope ?? "" };
49
+ }
@@ -0,0 +1,84 @@
1
+ /**
2
+ * A bounded cache of parsed entry bodies, keyed by file and version.
3
+ *
4
+ * Versions identify content, so a polling client that sees a new revision
5
+ * only costs a read and a parse for the files that actually changed.
6
+ */
7
+
8
+ export type ParsedBody =
9
+ | { ok: true; value: Record<string, unknown>; bytes: number }
10
+ | {
11
+ ok: false;
12
+ kind: "invalid-json" | "not-an-object" | "too-large";
13
+ message: string;
14
+ bytes: number;
15
+ };
16
+
17
+ export class BodyCache {
18
+ private readonly entries = new Map<string, ParsedBody>();
19
+ private total = 0;
20
+
21
+ constructor(private readonly maxBytes: number) {}
22
+
23
+ private static key(file: string, version: string) {
24
+ return `${file}\0${version}`;
25
+ }
26
+
27
+ get(file: string, version: string): ParsedBody | undefined {
28
+ const key = BodyCache.key(file, version);
29
+ const hit = this.entries.get(key);
30
+ if (hit) {
31
+ // Refresh recency.
32
+ this.entries.delete(key);
33
+ this.entries.set(key, hit);
34
+ }
35
+ return hit;
36
+ }
37
+
38
+ set(file: string, version: string, body: ParsedBody): void {
39
+ if (body.bytes > this.maxBytes) return;
40
+ const key = BodyCache.key(file, version);
41
+ const previous = this.entries.get(key);
42
+ if (previous) {
43
+ this.total -= previous.bytes;
44
+ this.entries.delete(key);
45
+ }
46
+ this.entries.set(key, body);
47
+ this.total += body.bytes;
48
+ for (const [oldest, value] of this.entries) {
49
+ if (this.total <= this.maxBytes) break;
50
+ this.entries.delete(oldest);
51
+ this.total -= value.bytes;
52
+ }
53
+ }
54
+ }
55
+
56
+ const utf8 = new TextEncoder();
57
+
58
+ /** Parses one stored entry, enforcing the per-entry byte limit. */
59
+ export function parseBody(text: string, maxBlockBytes: number): ParsedBody {
60
+ const bytes = utf8.encode(text).byteLength;
61
+ if (bytes > maxBlockBytes) {
62
+ return {
63
+ ok: false,
64
+ kind: "too-large",
65
+ bytes,
66
+ message: `the file is over ${maxBlockBytes} bytes`,
67
+ };
68
+ }
69
+ let value: unknown;
70
+ try {
71
+ value = JSON.parse(text);
72
+ } catch (error) {
73
+ return { ok: false, kind: "invalid-json", bytes, message: (error as Error).message };
74
+ }
75
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
76
+ return {
77
+ ok: false,
78
+ kind: "not-an-object",
79
+ bytes,
80
+ message: "the file doesn't hold a JSON object",
81
+ };
82
+ }
83
+ return { ok: true, value: value as Record<string, unknown>, bytes };
84
+ }
@@ -0,0 +1,175 @@
1
+ /**
2
+ * Turns a storage snapshot (files and versions) into the entry map, applying
3
+ * the one file-name rule: decode once, resolve spellings, report the rest.
4
+ * Shared by `blocks.list` (which needs every body) and `blocks.apply` (which
5
+ * needs bodies only to break ties between spellings).
6
+ */
7
+ import { limitExceeded, unavailable } from "../errors";
8
+ import { entryHasPath, fullyDecodeFileName, isBlockFileName, resolveSpellings } from "../keys";
9
+ import type { ContentStorage, StorageFile, StorageSnapshot } from "../storage";
10
+ import type { Diagnostic, Limits } from "../types";
11
+ import { type BodyCache, type ParsedBody, parseBody } from "./bodyCache";
12
+
13
+ export interface LoadedEntry {
14
+ file: string;
15
+ version: string;
16
+ /** The parsed entry; absent when the body wasn't needed. */
17
+ value?: Record<string, unknown>;
18
+ }
19
+
20
+ export interface LoadedContent {
21
+ snapshot: StorageSnapshot;
22
+ /** Every entry, by name, in file-name order of the winning files. */
23
+ entries: Map<string, LoadedEntry>;
24
+ /** Every saved-block file, valid or not, by spelling key. */
25
+ groups: Map<string, StorageFile[]>;
26
+ /** Files skipped or shadowed. */
27
+ diagnostics: Diagnostic[];
28
+ /** Uncompressed bytes of the bodies read. */
29
+ bytes: number;
30
+ /**
31
+ * True when a body read didn't match the snapshot (the file changed or
32
+ * vanished in between): the content isn't one consistent snapshot, so the
33
+ * caller takes a new one.
34
+ */
35
+ moved: boolean;
36
+ }
37
+
38
+ interface Options {
39
+ /** Read every body (`blocks.list`), not only the ones that break ties. */
40
+ readAll: boolean;
41
+ limits: Limits;
42
+ cache: BodyCache;
43
+ }
44
+
45
+ async function loadContent(
46
+ storage: ContentStorage,
47
+ snapshot: StorageSnapshot,
48
+ { readAll, limits, cache }: Options,
49
+ ): Promise<LoadedContent> {
50
+ const files = snapshot.files.filter((f) => isBlockFileName(f.file));
51
+ const groups = new Map<string, StorageFile[]>();
52
+ for (const file of files) {
53
+ const key = fullyDecodeFileName(file.file).name;
54
+ const group = groups.get(key);
55
+ if (group) group.push(file);
56
+ else groups.set(key, [file]);
57
+ }
58
+
59
+ const diagnostics: Diagnostic[] = [];
60
+ let moved = false;
61
+ const parsed = new Map<string, ParsedBody>();
62
+ const toRead: StorageFile[] = [];
63
+ let knownBytes = 0;
64
+ for (const group of groups.values()) {
65
+ if (!readAll && group.length < 2) continue;
66
+ for (const file of group) {
67
+ // An existing file over maxBlockBytes is unreadable, like invalid JSON: it's
68
+ // left out of the map and reported as a `too-large` diagnostic, so one
69
+ // oversized hand edit can't take the whole editor down. The map plus its
70
+ // diagnostics still accounts for every file in the snapshot; only the
71
+ // aggregate (maxListBytes) answers LimitExceeded.
72
+ if (file.size !== undefined && file.size > limits.maxBlockBytes) {
73
+ parsed.set(file.file, {
74
+ ok: false,
75
+ kind: "too-large",
76
+ bytes: file.size,
77
+ message: `the file is over ${limits.maxBlockBytes} bytes`,
78
+ });
79
+ continue;
80
+ }
81
+ knownBytes += file.size ?? 0;
82
+ const hit = cache.get(file.file, file.version);
83
+ if (hit) parsed.set(file.file, hit);
84
+ else toRead.push(file);
85
+ }
86
+ }
87
+ if (readAll && knownBytes > limits.maxListBytes) {
88
+ throw limitExceeded(`the block list is over ${limits.maxListBytes} bytes`, {
89
+ limit: "maxListBytes",
90
+ });
91
+ }
92
+ if (toRead.length > 0) {
93
+ const bodies = await storage.readFiles(
94
+ snapshot,
95
+ toRead.map((f) => f.file),
96
+ );
97
+ for (const file of toRead) {
98
+ const read = bodies[file.file];
99
+ if (read === undefined) {
100
+ moved = true; // vanished since the snapshot
101
+ continue;
102
+ }
103
+ const body = parseBody(read.text, limits.maxBlockBytes);
104
+ // Cache under the version of the bytes actually read, never the snapshot's.
105
+ cache.set(file.file, read.version, body);
106
+ if (read.version !== file.version) {
107
+ moved = true;
108
+ continue;
109
+ }
110
+ parsed.set(file.file, body);
111
+ }
112
+ }
113
+
114
+ let bytes = 0;
115
+ const candidates: Array<StorageFile & { hasPath: boolean; value?: Record<string, unknown> }> = [];
116
+ for (const file of files) {
117
+ const body = parsed.get(file.file);
118
+ if (body === undefined) {
119
+ // Not read: a single spelling whose body wasn't needed, or a file that vanished.
120
+ if (!readAll) candidates.push({ ...file, hasPath: false });
121
+ continue;
122
+ }
123
+ if (!body.ok) {
124
+ diagnostics.push({ file: file.file, kind: body.kind, message: body.message });
125
+ continue;
126
+ }
127
+ bytes += body.bytes;
128
+ candidates.push({ ...file, hasPath: entryHasPath(body.value), value: body.value });
129
+ }
130
+ if (readAll && bytes > limits.maxListBytes) {
131
+ throw limitExceeded(`the block list is over ${limits.maxListBytes} bytes`, {
132
+ limit: "maxListBytes",
133
+ });
134
+ }
135
+
136
+ const entries = new Map<string, LoadedEntry>();
137
+ for (const { name, winner, shadowed } of resolveSpellings(candidates).values()) {
138
+ entries.set(name, { file: winner.file, version: winner.version, value: winner.value });
139
+ for (const loser of shadowed) {
140
+ diagnostics.push({
141
+ file: loser.file,
142
+ kind: "shadowed",
143
+ name,
144
+ winner: winner.file,
145
+ message: `another spelling of "${name}" wins: ${winner.file}`,
146
+ });
147
+ }
148
+ }
149
+ diagnostics.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
150
+ return { snapshot, entries, groups, diagnostics, bytes, moved };
151
+ }
152
+
153
+ /** How many snapshots a read takes before giving up on files that keep changing. */
154
+ const MAX_SNAPSHOT_READS = 3;
155
+
156
+ /**
157
+ * Takes a snapshot and loads its content, taking a new snapshot when a file
158
+ * changed while its body was being read, so the bodies always match the
159
+ * versions and revision they're reported with. `shortCircuit` can end the
160
+ * read right after the snapshot (a conditional read that's "not modified").
161
+ */
162
+ export async function loadCurrentContent(
163
+ storage: ContentStorage,
164
+ ref: string | undefined,
165
+ options: Options,
166
+ shortCircuit?: (snapshot: StorageSnapshot) => boolean,
167
+ ): Promise<{ snapshot: StorageSnapshot; content: LoadedContent | null }> {
168
+ for (let read = 1; read <= MAX_SNAPSHOT_READS; read++) {
169
+ const snapshot = await storage.snapshot({ ref });
170
+ if (shortCircuit?.(snapshot)) return { snapshot, content: null };
171
+ const content = await loadContent(storage, snapshot, options);
172
+ if (!content.moved) return { snapshot, content };
173
+ }
174
+ throw unavailable("saved blocks kept changing while being read; retry shortly", 250);
175
+ }
@@ -0,0 +1,112 @@
1
+ /**
2
+ * The shared state of one content handler: its storage, options and caches.
3
+ */
4
+ import { ContentProtocolError, invalidBlock, notFound, unavailable, unsupported } from "../errors";
5
+ import { blockNameFromFile } from "../keys";
6
+ import {
7
+ type ContentStorage,
8
+ type StorageDescription,
9
+ StorageInvalidFileError,
10
+ StorageNotFoundError,
11
+ StorageUnavailableError,
12
+ } from "../storage";
13
+ import { DEFAULT_LIMITS, type DecoMeta, type Limits } from "../types";
14
+ import type { AuthOptions } from "./auth";
15
+ import { BodyCache } from "./bodyCache";
16
+
17
+ export interface ContentHandlerOptions extends AuthOptions {
18
+ /** Reported by `describe`, such as `{ name: "deco-cli", version: "8.0.0" }`. */
19
+ server?: { name: string; version: string };
20
+ /** Lowers the protocol's default limits. Higher values are ignored. */
21
+ limits?: Partial<Limits>;
22
+ /** Overrides the poll interval the storage suggests. */
23
+ pollIntervalMs?: number;
24
+ /** The app the site editor previews, reported by `describe` (`{ url }`). */
25
+ preview?: { url: string } | null;
26
+ /** How many times `blocks.apply` attempts a commit when storage moved meanwhile (default 3). */
27
+ maxCommitAttempts?: number;
28
+ /**
29
+ * The jittered wait before retrying a commit that found storage moved: a
30
+ * random delay in `[minMs, maxMs]`, times the attempt number (default
31
+ * 50–200 ms), so concurrent writers don't retry in lockstep.
32
+ */
33
+ commitRetryDelayMs?: { minMs: number; maxMs: number };
34
+ /** Bytes of parsed entries kept between requests (default 32 MiB). */
35
+ bodyCacheBytes?: number;
36
+ /** Called with errors that become an Internal error (-32603), for logging. */
37
+ onError?: (error: unknown) => void;
38
+ }
39
+
40
+ const DEFAULT_POLL_MS = { "working-tree": 2000, git: 30000 } as const;
41
+ const DEFAULT_RETRY_DELAY = { minMs: 50, maxMs: 200 };
42
+
43
+ export class Core {
44
+ readonly cache: BodyCache;
45
+ /** Requests in flight per scoped request key, so simultaneous duplicates commit once. */
46
+ readonly inflight = new Map<string, Promise<unknown>>();
47
+ /** The last parsed schema, by version: the secret guard reads it on every write. */
48
+ parsedSchema: { version: string; meta: DecoMeta } | null = null;
49
+
50
+ constructor(
51
+ readonly storage: ContentStorage,
52
+ readonly options: ContentHandlerOptions,
53
+ ) {
54
+ this.cache = new BodyCache(options.bodyCacheBytes ?? 32 * 1024 * 1024);
55
+ }
56
+
57
+ get maxCommitAttempts(): number {
58
+ return Math.max(1, this.options.maxCommitAttempts ?? 3);
59
+ }
60
+
61
+ /** Waits before commit attempt `attempt + 1`: jittered, growing with the attempt. */
62
+ async backoff(attempt: number): Promise<void> {
63
+ const { minMs, maxMs } = this.options.commitRetryDelayMs ?? DEFAULT_RETRY_DELAY;
64
+ const ms = (minMs + Math.random() * Math.max(0, maxMs - minMs)) * attempt;
65
+ if (ms > 0) await new Promise((resolve) => setTimeout(resolve, ms));
66
+ }
67
+
68
+ async description(): Promise<StorageDescription> {
69
+ return this.storage.describe();
70
+ }
71
+
72
+ /** The effective limits: the lowest of the defaults, the storage's and the options'. */
73
+ limits(description: StorageDescription): Limits {
74
+ const out = { ...DEFAULT_LIMITS };
75
+ for (const source of [description.limits, this.options.limits]) {
76
+ if (!source) continue;
77
+ for (const key of Object.keys(out) as (keyof Limits)[]) {
78
+ const value = source[key];
79
+ if (typeof value === "number" && value > 0 && value < out[key]) out[key] = value;
80
+ }
81
+ }
82
+ return out;
83
+ }
84
+
85
+ pollIntervalMs(description: StorageDescription): number {
86
+ return (
87
+ this.options.pollIntervalMs ?? description.pollIntervalMs ?? DEFAULT_POLL_MS[description.kind]
88
+ );
89
+ }
90
+
91
+ /** Refuses a `ref` on a storage without branches. */
92
+ checkRef(description: StorageDescription, ref: string | undefined): void {
93
+ if (ref !== undefined && description.refs === null) {
94
+ throw unsupported("this endpoint has no branches; omit ref");
95
+ }
96
+ }
97
+ }
98
+
99
+ /** Maps storage errors to protocol errors; anything unknown is rethrown. */
100
+ export function toProtocolError(error: unknown): ContentProtocolError | null {
101
+ if (error instanceof ContentProtocolError) return error;
102
+ if (error instanceof StorageNotFoundError) return notFound(error.message);
103
+ if (error instanceof StorageInvalidFileError) {
104
+ const name = blockNameFromFile(error.file);
105
+ return invalidBlock([
106
+ { name, rule: "unsupported-name", message: `this storage can't hold the entry "${name}"` },
107
+ ]);
108
+ }
109
+ if (error instanceof StorageUnavailableError)
110
+ return unavailable(error.message, error.retryAfterMs);
111
+ return null;
112
+ }
@@ -0,0 +1,102 @@
1
+ /**
2
+ * `createContentHandler(storage)`: the content protocol as a fetch handler,
3
+ * `(Request) => Promise<Response>`.
4
+ *
5
+ * `POST <endpoint>` with `Content-Type: application/json` and a body that's
6
+ * one request object or a batch array. Errors come back in the JSON-RPC
7
+ * `error` object with HTTP 200, except a missing or invalid bearer token (401)
8
+ * and a body over the size limit (413), which apply to the whole batch, and
9
+ * requests that aren't the protocol at all: a method other than POST (405),
10
+ * or a body that isn't JSON or uses an unsupported encoding (415). Those carry
11
+ * a JSON-RPC error body too, with a `null` id.
12
+ * Responses are gzip-compressed when the request accepts it.
13
+ *
14
+ * The handler is path-agnostic: mount it where the endpoint lives (`/rpc` on
15
+ * the local server). Transport security that depends on where it runs — CORS,
16
+ * `Host` checks, Chrome's local-network preflight — belongs to the server
17
+ * that mounts it (`deco serve`).
18
+ */
19
+ import {
20
+ type ContentProtocolError,
21
+ forbidden,
22
+ invalidRequest,
23
+ limitExceeded,
24
+ parseError,
25
+ unauthorized,
26
+ } from "../errors";
27
+ import type { ContentStorage } from "../storage";
28
+ import { assertAuthOptions, authenticate } from "./auth";
29
+ import { type ContentHandlerOptions, Core } from "./core";
30
+ import {
31
+ BodyEncodingError,
32
+ BodyTooLargeError,
33
+ isJsonContentType,
34
+ jsonResponse,
35
+ readBody,
36
+ } from "./http";
37
+ import { dispatch } from "./rpc";
38
+
39
+ export type ContentHandler = (request: Request) => Promise<Response>;
40
+
41
+ const errorBody = (error: ContentProtocolError) =>
42
+ JSON.stringify({ jsonrpc: "2.0", id: null, error: error.toJSON() });
43
+
44
+ export function createContentHandler(
45
+ storage: ContentStorage,
46
+ options: ContentHandlerOptions = {},
47
+ ): ContentHandler {
48
+ assertAuthOptions(options);
49
+ const core = new Core(storage, options);
50
+
51
+ return async (request) => {
52
+ if (request.method !== "POST") {
53
+ return jsonResponse(request, errorBody(invalidRequest("use POST")), 405, { allow: "POST" });
54
+ }
55
+ const auth = await authenticate(request, options);
56
+ if (!auth.ok) {
57
+ return auth.reason === "unauthorized"
58
+ ? jsonResponse(request, errorBody(unauthorized()), 401, {
59
+ "www-authenticate": 'Bearer realm="deco-content"',
60
+ })
61
+ : jsonResponse(request, errorBody(forbidden()));
62
+ }
63
+ if (!isJsonContentType(request)) {
64
+ return jsonResponse(
65
+ request,
66
+ errorBody(invalidRequest("Content-Type must be application/json")),
67
+ 415,
68
+ );
69
+ }
70
+
71
+ const limits = core.limits(await core.description());
72
+ let bytes: Uint8Array;
73
+ try {
74
+ bytes = await readBody(request, limits.maxRequestBytes);
75
+ } catch (error) {
76
+ if (error instanceof BodyTooLargeError) {
77
+ return jsonResponse(
78
+ request,
79
+ errorBody(
80
+ limitExceeded(`the request body is over ${limits.maxRequestBytes} bytes`, {
81
+ limit: "maxRequestBytes",
82
+ }),
83
+ ),
84
+ 413,
85
+ );
86
+ }
87
+ if (error instanceof BodyEncodingError) {
88
+ return jsonResponse(request, errorBody(invalidRequest(error.message)), 415);
89
+ }
90
+ throw error;
91
+ }
92
+
93
+ let body: unknown;
94
+ try {
95
+ body = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
96
+ } catch {
97
+ return jsonResponse(request, errorBody(parseError()));
98
+ }
99
+ const response = await dispatch(core, body, auth.scope, limits.maxBatchResponseBytes);
100
+ return jsonResponse(request, response);
101
+ };
102
+ }
@@ -0,0 +1,139 @@
1
+ /**
2
+ * HTTP plumbing for the content handler: bounded body reads (gzip request
3
+ * bodies included), gzip responses and bearer-token checks. Web-standard APIs
4
+ * only (Request, Response, CompressionStream), so it runs on Node, Bun,
5
+ * Workers and Deno.
6
+ */
7
+ import { sha256Hex } from "../canonical";
8
+
9
+ /** The body was larger than allowed (after decompression). */
10
+ export class BodyTooLargeError extends Error {
11
+ constructor(readonly limit: number) {
12
+ super(`the request body is over ${limit} bytes`);
13
+ this.name = "BodyTooLargeError";
14
+ }
15
+ }
16
+
17
+ /** The body claimed an encoding it doesn't have, or one we don't decode. */
18
+ export class BodyEncodingError extends Error {
19
+ constructor(message: string) {
20
+ super(message);
21
+ this.name = "BodyEncodingError";
22
+ }
23
+ }
24
+
25
+ async function readLimited(stream: ReadableStream<Uint8Array>, limit: number): Promise<Uint8Array> {
26
+ const reader = stream.getReader();
27
+ const chunks: Uint8Array[] = [];
28
+ let total = 0;
29
+ try {
30
+ for (;;) {
31
+ const { done, value } = await reader.read();
32
+ if (done) break;
33
+ total += value.byteLength;
34
+ if (total > limit) {
35
+ await reader.cancel().catch(() => {});
36
+ throw new BodyTooLargeError(limit);
37
+ }
38
+ chunks.push(value);
39
+ }
40
+ } finally {
41
+ reader.releaseLock();
42
+ }
43
+ const out = new Uint8Array(total);
44
+ let offset = 0;
45
+ for (const chunk of chunks) {
46
+ out.set(chunk, offset);
47
+ offset += chunk.byteLength;
48
+ }
49
+ return out;
50
+ }
51
+
52
+ /**
53
+ * Reads the request body as bytes, refusing more than `limit` bytes. A
54
+ * `Content-Encoding: gzip` body is decompressed, and the limit applies to the
55
+ * decompressed bytes too, so gzip can't bypass it.
56
+ */
57
+ export async function readBody(request: Request, limit: number): Promise<Uint8Array> {
58
+ const declared = Number(request.headers.get("content-length"));
59
+ const encoding = (request.headers.get("content-encoding") ?? "identity").trim().toLowerCase();
60
+ if (encoding === "identity" && Number.isFinite(declared) && declared > limit) {
61
+ throw new BodyTooLargeError(limit);
62
+ }
63
+ if (!request.body) return new Uint8Array(0);
64
+ if (encoding === "identity") return readLimited(request.body, limit);
65
+ if (encoding !== "gzip")
66
+ throw new BodyEncodingError(`unsupported Content-Encoding "${encoding}"`);
67
+ const decompressed = request.body.pipeThrough(
68
+ new DecompressionStream("gzip") as unknown as ReadableWritablePair<Uint8Array, Uint8Array>,
69
+ );
70
+ try {
71
+ return await readLimited(decompressed, limit);
72
+ } catch (error) {
73
+ if (error instanceof BodyTooLargeError) throw error;
74
+ throw new BodyEncodingError("the gzip body is corrupt");
75
+ }
76
+ }
77
+
78
+ /** True when the request's `Accept-Encoding` accepts gzip. */
79
+ function acceptsGzip(request: Request): boolean {
80
+ const header = request.headers.get("accept-encoding");
81
+ if (!header) return false;
82
+ return header.split(",").some((part) => {
83
+ const [coding = "", ...params] = part.trim().toLowerCase().split(";");
84
+ if (coding.trim() !== "gzip" && coding.trim() !== "*") return false;
85
+ const q = params.map((p) => p.trim()).find((p) => p.startsWith("q="));
86
+ return q === undefined || Number(q.slice(2)) > 0;
87
+ });
88
+ }
89
+
90
+ /** Bodies smaller than this aren't worth compressing. */
91
+ const GZIP_THRESHOLD_BYTES = 1024;
92
+
93
+ /** A JSON response, gzip-compressed when the request accepts it. */
94
+ export function jsonResponse(
95
+ request: Request,
96
+ body: string,
97
+ status = 200,
98
+ headers: Record<string, string> = {},
99
+ ): Response {
100
+ const responseHeaders = new Headers({
101
+ "content-type": "application/json; charset=utf-8",
102
+ "cache-control": "no-store",
103
+ vary: "Accept-Encoding",
104
+ ...headers,
105
+ });
106
+ const bytes = new TextEncoder().encode(body);
107
+ if (bytes.byteLength < GZIP_THRESHOLD_BYTES || !acceptsGzip(request)) {
108
+ return new Response(bytes, { status, headers: responseHeaders });
109
+ }
110
+ responseHeaders.set("content-encoding", "gzip");
111
+ const stream = new Blob([bytes as BlobPart])
112
+ .stream()
113
+ .pipeThrough(
114
+ new CompressionStream("gzip") as unknown as ReadableWritablePair<Uint8Array, Uint8Array>,
115
+ );
116
+ return new Response(stream, { status, headers: responseHeaders });
117
+ }
118
+
119
+ /** True when the request's `Content-Type` is JSON (`application/json`, any parameters). */
120
+ export function isJsonContentType(request: Request): boolean {
121
+ const type = request.headers.get("content-type");
122
+ return type !== null && type.split(";")[0]!.trim().toLowerCase() === "application/json";
123
+ }
124
+
125
+ /** The bearer token of the request, or `null` without one. */
126
+ export function bearerToken(request: Request): string | null {
127
+ const header = request.headers.get("authorization");
128
+ if (!header) return null;
129
+ const match = /^Bearer\s+(\S+)\s*$/i.exec(header);
130
+ return match?.[1] ?? null;
131
+ }
132
+
133
+ /** Compares two strings in time independent of where they differ. */
134
+ export async function timingSafeEqualStrings(a: string, b: string): Promise<boolean> {
135
+ const [ha, hb] = await Promise.all([sha256Hex(a), sha256Hex(b)]);
136
+ let diff = 0;
137
+ for (let i = 0; i < ha.length; i++) diff |= ha.charCodeAt(i) ^ hb.charCodeAt(i);
138
+ return diff === 0;
139
+ }
@@ -0,0 +1,11 @@
1
+ /**
2
+ * `@decocms/blocks/protocol/server`: the content protocol's server core.
3
+ *
4
+ * `createContentHandler(storage)` serves the four methods over any
5
+ * `ContentStorage`. Web-standard APIs only, so it runs on Node, Bun, Workers
6
+ * and Deno. (`deco serve`'s asset uploads use `./assets`, which isn't public.)
7
+ */
8
+
9
+ export type { AuthOptions, AuthorizeResult } from "./auth";
10
+ export type { ContentHandlerOptions } from "./core";
11
+ export { type ContentHandler, createContentHandler } from "./handler";