@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,238 @@
1
+ /**
2
+ * `@decocms/blocks/protocol/storage/memory`: an in-memory `ContentStorage`.
3
+ *
4
+ * A reference implementation of the storage contract, including durable
5
+ * request-key receipts persisted atomically with each commit, and a fixture
6
+ * for tests: its state can be dumped and restored to simulate a restart, and
7
+ * hooks let a test change files between a snapshot and a commit. Browser-safe.
8
+ */
9
+ import { suffixedAssetName } from "../assets";
10
+ import { sha256Hex } from "../canonical";
11
+ import { isBlockFileName } from "../keys";
12
+ import {
13
+ type CommitAttempt,
14
+ type CommitResult,
15
+ type ContentStorage,
16
+ type StorageDescription,
17
+ StorageInvalidFileError,
18
+ StorageNotFoundError,
19
+ type StorageSnapshot,
20
+ type StoredFileBody,
21
+ type StoredReceipt,
22
+ type StoredSchema,
23
+ } from "../storage";
24
+
25
+ const DAY_MS = 24 * 60 * 60 * 1000;
26
+
27
+ /** Everything a memory storage holds; JSON-serializable, so it survives a "restart". */
28
+ export interface MemoryStorageState {
29
+ /** Saved-block files, by file name, with their content. */
30
+ files: Record<string, string>;
31
+ /** The content of `schema.gen.json`, or `null` without one. */
32
+ schema: string | null;
33
+ /** The content of `meta.gen.json`, the fallback schema, or `null`. */
34
+ legacySchema?: string | null;
35
+ secretsPublicKey: string | null;
36
+ receipts: Record<string, StoredReceipt & { createdAt: number }>;
37
+ assets: Record<string, string>;
38
+ /** `false` simulates an app root with no `.deco` folder at all. */
39
+ hasDecoFolder: boolean;
40
+ }
41
+
42
+ export interface MemoryStorageOptions {
43
+ state?: Partial<MemoryStorageState>;
44
+ /** Overrides parts of what `describe` reports. */
45
+ description?: Partial<StorageDescription>;
46
+ /** Clock for receipt retention (default `Date.now`). */
47
+ now?: () => number;
48
+ /** Runs after each file body is read; a test can change files here, mid-read. */
49
+ afterRead?: (file: string, storage: MemoryStorage) => void | Promise<void>;
50
+ /** Runs before each commit attempt's checks; a test can change files here. */
51
+ beforeCommit?: (attempt: CommitAttempt, storage: MemoryStorage) => void | Promise<void>;
52
+ }
53
+
54
+ export interface MemoryStorage extends ContentStorage {
55
+ /** A deep copy of the current state. */
56
+ dump(): MemoryStorageState;
57
+ /** Writes or deletes (`null`) a file directly, as an outside edit would. */
58
+ setFile(file: string, content: string | null): void;
59
+ /** Replaces `schema.gen.json` (`null` removes it). */
60
+ setSchema(schema: string | object | null): void;
61
+ /** How many commits landed. */
62
+ readonly commits: number;
63
+ }
64
+
65
+ const version = (content: string) => sha256Hex(content);
66
+
67
+ export function createMemoryStorage(options: MemoryStorageOptions = {}): MemoryStorage {
68
+ const now = options.now ?? Date.now;
69
+ const state: MemoryStorageState = structuredClone({
70
+ files: {},
71
+ schema: null,
72
+ legacySchema: null,
73
+ secretsPublicKey: null,
74
+ receipts: {},
75
+ assets: {},
76
+ hasDecoFolder: true,
77
+ ...options.state,
78
+ });
79
+ const description: StorageDescription = {
80
+ kind: "git",
81
+ root: ".",
82
+ readOnly: false,
83
+ refs: null,
84
+ assets: { dir: "public/assets", maxBytes: 25 * 1024 * 1024 },
85
+ idempotency: { retentionMs: DAY_MS },
86
+ ...options.description,
87
+ };
88
+ let commits = 0;
89
+
90
+ async function currentVersions(): Promise<Map<string, string>> {
91
+ const entries = await Promise.all(
92
+ Object.entries(state.files).map(
93
+ async ([file, content]) => [file, await version(content)] as const,
94
+ ),
95
+ );
96
+ return new Map(entries);
97
+ }
98
+
99
+ async function schemaVersion(): Promise<string | null> {
100
+ const text = state.schema ?? state.legacySchema ?? null;
101
+ return text === null ? null : version(text);
102
+ }
103
+
104
+ async function revisionOf(versions: Map<string, string>): Promise<string> {
105
+ const listing = [...versions].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
106
+ return sha256Hex(listing.map(([file, v]) => `${file}\0${v}`).join("\n"));
107
+ }
108
+
109
+ let commitQueue: Promise<unknown> = Promise.resolve();
110
+
111
+ async function commitNow(attempt: CommitAttempt): Promise<CommitResult> {
112
+ await options.beforeCommit?.(attempt, storage);
113
+ for (const file of [
114
+ ...Object.keys(attempt.put),
115
+ ...attempt.delete,
116
+ ...Object.keys(attempt.expected),
117
+ ]) {
118
+ if (!isBlockFileName(file)) throw new StorageInvalidFileError(file);
119
+ }
120
+ if (!state.hasDecoFolder) throw new StorageNotFoundError("no .deco folder");
121
+ if (attempt.receipt && state.receipts[attempt.receipt.key]) return { status: "stale" };
122
+ if (
123
+ attempt.expectedSchemaVersion !== undefined &&
124
+ (await schemaVersion()) !== attempt.expectedSchemaVersion
125
+ ) {
126
+ return { status: "stale" };
127
+ }
128
+ const versions = await currentVersions();
129
+ for (const [file, expected] of Object.entries(attempt.expected)) {
130
+ if ((versions.get(file) ?? null) !== expected) return { status: "stale" };
131
+ }
132
+ // Validate everything before mutating, so the commit is all or nothing.
133
+ const written: Record<string, string> = {};
134
+ for (const [file, content] of Object.entries(attempt.put))
135
+ written[file] = await version(content);
136
+ for (const file of attempt.delete) delete state.files[file];
137
+ for (const [file, content] of Object.entries(attempt.put)) state.files[file] = content;
138
+ for (const [file, v] of Object.entries(written)) versions.set(file, v);
139
+ for (const file of attempt.delete) if (!(file in attempt.put)) versions.delete(file);
140
+ const revision = await revisionOf(versions);
141
+ if (attempt.receipt) {
142
+ state.receipts[attempt.receipt.key] = {
143
+ digest: attempt.receipt.digest,
144
+ revision,
145
+ versions: written,
146
+ deleted: [...attempt.delete],
147
+ createdAt: now(),
148
+ };
149
+ }
150
+ commits++;
151
+ return { status: "committed", revision, versions: written };
152
+ }
153
+
154
+ const storage: MemoryStorage = {
155
+ get commits() {
156
+ return commits;
157
+ },
158
+
159
+ describe: () => description,
160
+
161
+ async snapshot(): Promise<StorageSnapshot> {
162
+ if (!state.hasDecoFolder) throw new StorageNotFoundError("no .deco folder");
163
+ const versions = await currentVersions();
164
+ return {
165
+ revision: await revisionOf(versions),
166
+ resolvedRef: null,
167
+ files: [...versions].map(([file, v]) => ({
168
+ file,
169
+ version: v,
170
+ size: new TextEncoder().encode(state.files[file]).byteLength,
171
+ })),
172
+ };
173
+ },
174
+
175
+ async readFiles(_snapshot, files) {
176
+ const out: Record<string, StoredFileBody> = Object.create(null);
177
+ for (const file of files) {
178
+ if (!(file in state.files)) continue;
179
+ const text = state.files[file];
180
+ out[file] = { text, version: await version(text) };
181
+ await options.afterRead?.(file, storage);
182
+ }
183
+ return out;
184
+ },
185
+
186
+ async readSchema(): Promise<StoredSchema | null> {
187
+ if (!state.hasDecoFolder) return null;
188
+ const text = state.schema ?? state.legacySchema ?? null;
189
+ if (text === null) return null;
190
+ return { version: await version(text), text, resolvedRef: null };
191
+ },
192
+
193
+ async readSecretsPublicKey() {
194
+ return state.secretsPublicKey;
195
+ },
196
+
197
+ commit(attempt): Promise<CommitResult> {
198
+ // Serialized, so a commit's checks and its mutation are one atomic step.
199
+ const run = commitQueue.then(() => commitNow(attempt));
200
+ commitQueue = run.catch(() => {});
201
+ return run;
202
+ },
203
+
204
+ async getReceipt(key) {
205
+ const receipt = state.receipts[key];
206
+ if (!receipt) return null;
207
+ if (
208
+ description.idempotency &&
209
+ now() - receipt.createdAt > description.idempotency.retentionMs
210
+ ) {
211
+ delete state.receipts[key];
212
+ return null;
213
+ }
214
+ const { createdAt: _createdAt, ...stored } = receipt;
215
+ return stored;
216
+ },
217
+
218
+ async putAsset(name, body) {
219
+ let candidate = name;
220
+ while (candidate in state.assets) candidate = suffixedAssetName(name);
221
+ state.assets[candidate] = Array.from(body, (b) => String.fromCharCode(b)).join("");
222
+ return { name: candidate };
223
+ },
224
+
225
+ dump: () => structuredClone(state),
226
+
227
+ setFile(file, content) {
228
+ if (content === null) delete state.files[file];
229
+ else state.files[file] = content;
230
+ },
231
+
232
+ setSchema(schema) {
233
+ state.schema =
234
+ schema === null || typeof schema === "string" ? schema : JSON.stringify(schema);
235
+ },
236
+ };
237
+ return storage;
238
+ }
@@ -0,0 +1,182 @@
1
+ /**
2
+ * The storage interface a content-protocol backend implements.
3
+ *
4
+ * A storage is deliberately small: a snapshot of file names and versions,
5
+ * reading file bodies, reading the schema, and one atomic commit attempt.
6
+ * The protocol core (`createContentHandler`) owns everything else: the
7
+ * JSON-RPC layer, validation, the file-name rule, the secret guard, limits and
8
+ * retries. Storages deal in *files* inside `<root>/.deco/blocks`; entry names
9
+ * are the core's business.
10
+ *
11
+ * Browser-safe: types and small error classes only.
12
+ */
13
+ import type { Limits, StorageKind } from "./types";
14
+
15
+ /** What a storage tells `describe`. */
16
+ export interface StorageDescription {
17
+ kind: StorageKind;
18
+ /** The app root, relative to the repository root (`"."` when they're the same). */
19
+ root: string;
20
+ readOnly: boolean;
21
+ /** Branch support; `null` when the storage has no refs (`ref` params are then Unsupported). */
22
+ refs: null | { default: string; autoCreate: boolean };
23
+ /** Where uploads go; `null` when read-only or uploads go elsewhere. */
24
+ assets: null | { dir: string; maxBytes: number };
25
+ /**
26
+ * Durable request-key receipts. Advertise only when `getReceipt` is
27
+ * implemented and `commit` persists `attempt.receipt` with the mutation.
28
+ */
29
+ idempotency: null | { retentionMs: number };
30
+ /** Overrides the poll interval (default: 2000 for a working tree, 30000 for git). */
31
+ pollIntervalMs?: number;
32
+ /** Lowers the protocol's default limits. Higher values are ignored. */
33
+ limits?: Partial<Limits>;
34
+ }
35
+
36
+ /** One saved-block file in a snapshot. */
37
+ export interface StorageFile {
38
+ /** The file name inside `.deco/blocks`, such as `pages-Home.json`. */
39
+ file: string;
40
+ /** An opaque version of the file's content, compared only for equality. */
41
+ version: string;
42
+ /** The file's size in bytes, when the storage knows it without reading the body. */
43
+ size?: number;
44
+ }
45
+
46
+ /** Every saved-block file at one point in time. */
47
+ export interface StorageSnapshot {
48
+ /** An opaque revision of the whole set, compared only for equality. */
49
+ revision: string;
50
+ /** The ref actually read (it can differ from the requested one); `null` without refs. */
51
+ resolvedRef: string | null;
52
+ files: StorageFile[];
53
+ }
54
+
55
+ /** A file body as read, with the version of the bytes actually read. */
56
+ export interface StoredFileBody {
57
+ /** The file's UTF-8 content. */
58
+ text: string;
59
+ /**
60
+ * The version of exactly these bytes, computed the way snapshots compute
61
+ * versions. It differs from the snapshot's when the file changed in between.
62
+ */
63
+ version: string;
64
+ }
65
+
66
+ /** The schema file, as stored. */
67
+ export interface StoredSchema {
68
+ /** An opaque version of the schema bytes. */
69
+ version: string;
70
+ /** The raw file content (`schema.gen.json`, else `meta.gen.json`). */
71
+ text: string;
72
+ resolvedRef: string | null;
73
+ }
74
+
75
+ /** A durable receipt for one `blocks.apply` request key. */
76
+ export interface StoredReceipt {
77
+ /** The canonical digest of the request the key was first used with. */
78
+ digest: string;
79
+ /** The revision that commit produced. */
80
+ revision: string;
81
+ /** The versions of the files that commit wrote. */
82
+ versions: Record<string, string>;
83
+ /** The files that commit deleted (`attempt.delete`), so a replay reports the same names. */
84
+ deleted?: string[];
85
+ }
86
+
87
+ /** One atomic commit attempt. */
88
+ export interface CommitAttempt {
89
+ ref?: string;
90
+ /** The snapshot the core validated against. */
91
+ base: StorageSnapshot;
92
+ /** Files to write, by file name, with their full content. */
93
+ put: Record<string, string>;
94
+ /** Files to delete. A file that's already gone is fine. */
95
+ delete: string[];
96
+ /**
97
+ * Versions the files must still have for the commit to land (`null` = must
98
+ * not exist). A storage MUST reject the attempt as stale when any of them
99
+ * changed, and MAY reject it when anything else changed since `base`.
100
+ */
101
+ expected: Record<string, string | null>;
102
+ /**
103
+ * The schema version the core validated against (`null` = no schema), when
104
+ * the write depends on it (`ifSchemaMatch`, or the secret guard). When set,
105
+ * a storage MUST reject the attempt as stale if the schema's version at
106
+ * commit time differs, checked atomically with `expected`.
107
+ */
108
+ expectedSchemaVersion?: string | null;
109
+ /**
110
+ * Persist this receipt atomically with the mutation (only when idempotency
111
+ * is advertised). The key also reserves the request: a storage MUST reject
112
+ * the attempt as stale when a receipt for `receipt.key` already exists,
113
+ * including one written concurrently by another replica, so two requests
114
+ * with the same key never both commit.
115
+ */
116
+ receipt?: { key: string; digest: string };
117
+ }
118
+
119
+ export type CommitResult =
120
+ | {
121
+ status: "committed";
122
+ revision: string;
123
+ /** The new version of every file in `put`. */
124
+ versions: Record<string, string>;
125
+ }
126
+ | { status: "stale" };
127
+
128
+ export interface ContentStorage {
129
+ describe(): StorageDescription | Promise<StorageDescription>;
130
+ /**
131
+ * Lists the saved-block files. Throws `StorageNotFoundError` when there's no
132
+ * `.deco` folder at all, or the ref can't be read.
133
+ */
134
+ snapshot(options: { ref?: string }): Promise<StorageSnapshot>;
135
+ /**
136
+ * Reads file bodies (UTF-8 text) from a snapshot, each with the version of
137
+ * the bytes read. A file that vanished is left out. A storage that can't
138
+ * read at the snapshot (a working tree) returns current bytes; the core
139
+ * compares versions to notice.
140
+ */
141
+ readFiles(snapshot: StorageSnapshot, files: string[]): Promise<Record<string, StoredFileBody>>;
142
+ /** Reads `schema.gen.json`, falling back to `meta.gen.json`; `null` when neither exists. */
143
+ readSchema(options: { ref?: string }): Promise<StoredSchema | null>;
144
+ /** Reads `<root>/.deco/secrets.pub`; `null` without one. */
145
+ readSecretsPublicKey(): Promise<string | null>;
146
+ /** One all-or-nothing commit attempt; durable when it resolves. */
147
+ commit(attempt: CommitAttempt): Promise<CommitResult>;
148
+ /** Looks up a receipt by its scoped key; `null` when unknown or expired. */
149
+ getReceipt?(key: string): Promise<StoredReceipt | null>;
150
+ /** Stores an uploaded file, never overwriting one; returns the stored file name. */
151
+ putAsset?(name: string, body: Uint8Array): Promise<{ name: string }>;
152
+ }
153
+
154
+ /** Thrown by a storage when there's no `.deco` folder, or a ref can't be read or created. */
155
+ export class StorageNotFoundError extends Error {
156
+ constructor(message: string) {
157
+ super(message);
158
+ this.name = "StorageNotFoundError";
159
+ }
160
+ }
161
+
162
+ /**
163
+ * Thrown by a storage asked to touch a file that can't be a saved block (a
164
+ * dotfile, a path). The core refuses those names first; this is the backstop.
165
+ */
166
+ export class StorageInvalidFileError extends Error {
167
+ constructor(readonly file: string) {
168
+ super(`not a saved-block file name: ${JSON.stringify(file)}`);
169
+ this.name = "StorageInvalidFileError";
170
+ }
171
+ }
172
+
173
+ /** Thrown by a storage when it failed or is rate-limited. */
174
+ export class StorageUnavailableError extends Error {
175
+ readonly retryAfterMs: number | undefined;
176
+
177
+ constructor(message: string, retryAfterMs?: number) {
178
+ super(message);
179
+ this.name = "StorageUnavailableError";
180
+ this.retryAfterMs = retryAfterMs;
181
+ }
182
+ }
@@ -0,0 +1,172 @@
1
+ /**
2
+ * The content protocol's method types: JSON-RPC 2.0 over one HTTP endpoint,
3
+ * four methods (`describe`, `schema.get`, `blocks.list`, `blocks.apply`).
4
+ */
5
+
6
+ export const PROTOCOL_NAME = "deco-content";
7
+
8
+ /** Minors only add; a client refuses an unknown major. */
9
+ export const PROTOCOL_VERSION = { major: 1, minor: 0 } as const;
10
+
11
+ export const SCHEMA_FORMAT = "deco-meta@1";
12
+
13
+ /** The path the local server (`deco serve`) mounts the endpoint at. */
14
+ export const RPC_PATH = "/rpc";
15
+
16
+ /** The longest batch a request may carry. */
17
+ export const MAX_BATCH_CALLS = 10;
18
+
19
+ /** The URL prefix every uploaded asset is stored under in a field. */
20
+ export const ASSETS_URL_PREFIX = "/assets/";
21
+
22
+ export interface Limits {
23
+ /** Names (set plus delete) in one `blocks.apply`. */
24
+ maxOpsPerApply: number;
25
+ /** Bytes of one stored entry. */
26
+ maxBlockBytes: number;
27
+ /** Bytes of one HTTP request body, uncompressed. */
28
+ maxRequestBytes: number;
29
+ /** Uncompressed bytes of the whole block list. */
30
+ maxListBytes: number;
31
+ /** Uncompressed bytes of the schema. */
32
+ maxSchemaBytes: number;
33
+ /** Uncompressed bytes of a whole batch response. */
34
+ maxBatchResponseBytes: number;
35
+ }
36
+
37
+ const MiB = 1024 * 1024;
38
+
39
+ /** The protocol's default limits. A storage or a server can lower them. */
40
+ export const DEFAULT_LIMITS: Readonly<Limits> = Object.freeze({
41
+ maxOpsPerApply: 500,
42
+ maxBlockBytes: 1 * MiB,
43
+ maxRequestBytes: 8 * MiB,
44
+ maxListBytes: 16 * MiB,
45
+ maxSchemaBytes: 16 * MiB,
46
+ maxBatchResponseBytes: 32 * MiB,
47
+ });
48
+
49
+ export type StorageKind = "working-tree" | "git";
50
+
51
+ export interface DescribeResult {
52
+ protocol: typeof PROTOCOL_NAME;
53
+ version: { major: 1; minor: number };
54
+ server: { name: string; version: string };
55
+ /** The site editor hides publish and draft UI for a working tree. */
56
+ kind: StorageKind;
57
+ readOnly: boolean;
58
+ /** The app root: the folder that contains `.deco/`, relative to the repository root. */
59
+ root: string;
60
+ schemaFormat: typeof SCHEMA_FORMAT;
61
+ /** Branches; `null` on the local server. */
62
+ refs: null | { default: string; autoCreate: boolean };
63
+ writes: { idempotency: null | { retentionMs: number }; schemaPreconditions: boolean };
64
+ /** Local: 2000; git: 30000, plus on window focus. */
65
+ pollIntervalMs: number;
66
+ limits: Limits;
67
+ /**
68
+ * The app the site editor shows in its Preview tab (and where "open the real
69
+ * page" points); the local server reports `deco serve --preview`. `null`: no preview.
70
+ */
71
+ preview: null | { url: string };
72
+ /** Dir relative to the repository root; `null` when read-only or uploads go to hosted storage. */
73
+ assets: null | { dir: string; urlPrefix: typeof ASSETS_URL_PREFIX; maxBytes: number };
74
+ /** The contents of `<root>/.deco/secrets.pub`; `null` without one. */
75
+ secrets: null | { publicKey: string };
76
+ }
77
+
78
+ /** The schema file, in the site editor's `deco-meta@1` format. */
79
+ export interface DecoMeta {
80
+ manifest?: { blocks?: Record<string, Record<string, unknown>> };
81
+ schema?: { definitions?: Record<string, unknown>; root?: Record<string, unknown> };
82
+ [key: string]: unknown;
83
+ }
84
+
85
+ export interface ReadParams {
86
+ ref?: string;
87
+ ifNoneMatch?: string;
88
+ }
89
+
90
+ export type SchemaGetParams = ReadParams;
91
+
92
+ export type SchemaGetResult =
93
+ | { notModified: true; version: string }
94
+ | { notModified: false; version: string; resolvedRef: string | null; schema: DecoMeta };
95
+
96
+ export type BlocksListParams = ReadParams;
97
+
98
+ /** A file `blocks.list` skipped or shadowed. */
99
+ export interface Diagnostic {
100
+ /** The file name inside `.deco/blocks`. */
101
+ file: string;
102
+ kind: "invalid-json" | "not-an-object" | "too-large" | "shadowed";
103
+ message: string;
104
+ /** For `shadowed`: the entry the file is a spelling of. */
105
+ name?: string;
106
+ /** For `shadowed`: the file that won. */
107
+ winner?: string;
108
+ }
109
+
110
+ export type BlocksListResult =
111
+ | { notModified: true; revision: string; resolvedRef: string | null }
112
+ | {
113
+ notModified: false;
114
+ revision: string;
115
+ resolvedRef: string | null;
116
+ /** Every saved block, by name. */
117
+ blocks: Record<string, Record<string, unknown>>;
118
+ /** One opaque version per entry. */
119
+ versions: Record<string, string>;
120
+ /** Files skipped or shadowed. */
121
+ diagnostics: Diagnostic[];
122
+ };
123
+
124
+ export interface BlocksApplyParams {
125
+ ref?: string;
126
+ /** Retry the same logical write; only when advertised. */
127
+ requestKey?: string;
128
+ /** Reject if the schema changed; only when advertised. */
129
+ ifSchemaMatch?: string;
130
+ /** Whole-entry replace (create or update). */
131
+ set?: Record<string, Record<string, unknown>>;
132
+ /** A missing name counts as deleted. */
133
+ delete?: string[];
134
+ /** A version the entry must have; `null` = must not exist. */
135
+ ifMatch?: Record<string, string | null>;
136
+ }
137
+
138
+ export interface BlocksApplyResult {
139
+ revision: string;
140
+ versions: Record<string, string | null>;
141
+ }
142
+
143
+ /** The four methods, by wire name. */
144
+ export interface Methods {
145
+ describe: { params: Record<string, never> | undefined; result: DescribeResult };
146
+ "schema.get": { params: SchemaGetParams | undefined; result: SchemaGetResult };
147
+ "blocks.list": { params: BlocksListParams | undefined; result: BlocksListResult };
148
+ "blocks.apply": { params: BlocksApplyParams; result: BlocksApplyResult };
149
+ }
150
+
151
+ export type MethodName = keyof Methods;
152
+
153
+ export const METHOD_NAMES: readonly MethodName[] = [
154
+ "describe",
155
+ "schema.get",
156
+ "blocks.list",
157
+ "blocks.apply",
158
+ ];
159
+
160
+ /** A JSON-RPC request id. The protocol requires one on every request. */
161
+ export type RpcId = string | number;
162
+
163
+ export interface RpcRequest<M extends MethodName = MethodName> {
164
+ jsonrpc: "2.0";
165
+ id: RpcId;
166
+ method: M;
167
+ params?: Methods[M]["params"];
168
+ }
169
+
170
+ export type RpcResponse<R = unknown> =
171
+ | { jsonrpc: "2.0"; id: RpcId | null; result: R }
172
+ | { jsonrpc: "2.0"; id: RpcId | null; error: { code: number; message: string; data?: unknown } };
@@ -272,6 +272,53 @@ export function tagBucket(
272
272
  return res;
273
273
  }
274
274
 
275
+ /**
276
+ * A `TransformStream` that rewrites every occurrence of `search` in a UTF-8 text
277
+ * stream, without ever holding the whole body in memory.
278
+ *
279
+ * Two hazards it exists to handle:
280
+ *
281
+ * - **A match straddling a chunk boundary.** Each pass holds back the last
282
+ * `search.length - 1` characters and prepends them to the next chunk. The
283
+ * held-back slice is taken from the RAW input, never from already-replaced
284
+ * output — otherwise a replacement ending in a prefix of `search` could join
285
+ * the next chunk and be replaced a second time.
286
+ * - **A multi-byte character split across chunks.** `TextDecoder` with
287
+ * `{ stream: true }` carries the partial code point across `decode` calls.
288
+ *
289
+ * Peak memory is one chunk plus `search.length - 1` characters, not the body.
290
+ */
291
+ export function createReplaceStream(search: string, replace: string): TransformStream<Uint8Array, Uint8Array> {
292
+ const decoder = new TextDecoder("utf-8");
293
+ const encoder = new TextEncoder();
294
+ if (!search) return new TransformStream<Uint8Array, Uint8Array>();
295
+ const keep = search.length - 1;
296
+ let tail = "";
297
+
298
+ return new TransformStream<Uint8Array, Uint8Array>({
299
+ transform(chunk, controller) {
300
+ const buffer = tail + decoder.decode(chunk, { stream: true });
301
+ // Consume complete matches first (left to right, non-overlapping — same
302
+ // as replaceAll), then hold back only the last `search.length - 1` chars
303
+ // of what follows the last match: a not-yet-complete match can only
304
+ // start there. Cutting before consuming matches can slice a complete,
305
+ // self-overlapping match ("aaa" in "xaaaa") in half.
306
+ let end = 0;
307
+ for (let i = buffer.indexOf(search); i !== -1; i = buffer.indexOf(search, end)) {
308
+ end = i + search.length;
309
+ }
310
+ const cut = Math.max(end, buffer.length - keep);
311
+ tail = buffer.slice(cut);
312
+ const head = buffer.slice(0, cut);
313
+ if (head) controller.enqueue(encoder.encode(head.replaceAll(search, replace)));
314
+ },
315
+ flush(controller) {
316
+ const rest = tail + decoder.decode();
317
+ if (rest) controller.enqueue(encoder.encode(rest.replaceAll(search, replace)));
318
+ },
319
+ });
320
+ }
321
+
275
322
  /**
276
323
  * Proxy a request to the fallback origin with full hostname rewriting.
277
324
  *
@@ -330,18 +377,28 @@ export async function proxyToFallback(
330
377
  // would consume the stream needlessly and could throw on non-text
331
378
  // content. The Location header is rewritten separately further down.
332
379
  let body: BodyInit | null = response.body;
380
+ let rewrote = false;
333
381
  if (
334
382
  isText &&
335
383
  response.body &&
336
384
  response.status >= 200 &&
337
- response.status < 300
385
+ response.status < 300 &&
386
+ fallbackOrigin.length > 0
338
387
  ) {
339
- const text = await response.text();
340
- body = text.replaceAll(fallbackOrigin, url.hostname);
388
+ // Streamed, not buffered. `response.text()` held the entire body as a
389
+ // JS string (two bytes per character) plus the replaced copy — multiple
390
+ // megabytes of a 128MB isolate budget for a hostname substitution.
391
+ body = response.body.pipeThrough(createReplaceStream(fallbackOrigin, url.hostname));
392
+ rewrote = true;
341
393
  }
342
394
 
343
395
  const rewritten = new Response(body, response);
344
396
 
397
+ // The rewrite changes the body length, so the upstream `content-length` is
398
+ // now a lie — and a streamed body has no length to state. (This was already
399
+ // wrong on the buffered path; it just never had to be chunked.)
400
+ if (rewrote) rewritten.headers.delete("content-length");
401
+
345
402
  const setCookies = response.headers.getSetCookie?.() ?? [];
346
403
  if (setCookies.length > 0) {
347
404
  rewritten.headers.delete("set-cookie");