@gusto/baerly-storage 0.6.0 → 0.7.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 (218) hide show
  1. package/README.md +47 -124
  2. package/dist/API.md +161 -512
  3. package/dist/CHANGELOG.md +1137 -378
  4. package/dist/RECIPES.md +398 -80
  5. package/dist/THIRD-PARTY-LICENSES.txt +5 -26
  6. package/dist/{app-config-DyiFK3_k.d.ts → app-config-C6qW7m8S.d.ts} +119 -111
  7. package/dist/app-config.d.ts +31 -1
  8. package/dist/app-config.js +1 -2
  9. package/dist/app-config.js.map +1 -1
  10. package/dist/auth.d.ts +33 -28
  11. package/dist/auth.js +549 -985
  12. package/dist/auth.js.map +1 -1
  13. package/dist/baerly.js +130 -138
  14. package/dist/baerly.js.map +1 -1
  15. package/dist/baerly.spec.json +97 -22
  16. package/dist/capacity-warning-header-BlVopyiI.js +16 -0
  17. package/dist/capacity-warning-header-BlVopyiI.js.map +1 -0
  18. package/dist/{client-ypCm3zjt.d.ts → client-CHQTXpef.d.ts} +121 -36
  19. package/dist/client-react.d.ts +67 -20
  20. package/dist/client-react.js +240 -54
  21. package/dist/client-react.js.map +1 -1
  22. package/dist/client.d.ts +5 -4
  23. package/dist/client.js +51 -16
  24. package/dist/client.js.map +1 -1
  25. package/dist/{cloudflare-wrVYf4bb.js → cloudflare-CKHYXccw.js} +61 -82
  26. package/dist/cloudflare-CKHYXccw.js.map +1 -0
  27. package/dist/cloudflare.d.ts +106 -71
  28. package/dist/cloudflare.js +334 -271
  29. package/dist/cloudflare.js.map +1 -1
  30. package/dist/code-resolution-CL_7L0wS.js +22 -0
  31. package/dist/code-resolution-CL_7L0wS.js.map +1 -0
  32. package/dist/collection-api-DbyhLAY8.d.ts +1001 -0
  33. package/dist/config-DEzInG6M.js +4035 -0
  34. package/dist/config-DEzInG6M.js.map +1 -0
  35. package/dist/constants-D3GSH3tc.js +469 -0
  36. package/dist/constants-D3GSH3tc.js.map +1 -0
  37. package/dist/{context-DRZ3tZ5l.js → context-rlpSnHFA.js} +17 -17
  38. package/dist/context-rlpSnHFA.js.map +1 -0
  39. package/dist/cost-B52llVDx.js +330 -0
  40. package/dist/cost-B52llVDx.js.map +1 -0
  41. package/dist/{current-json-C6nhPOm1.js → current-json-CC6lE4Aj.js} +115 -32
  42. package/dist/current-json-CC6lE4Aj.js.map +1 -0
  43. package/dist/db-plFUNTSF.d.ts +130 -0
  44. package/dist/db-read-seams-BSs0m1z1.js +3261 -0
  45. package/dist/db-read-seams-BSs0m1z1.js.map +1 -0
  46. package/dist/{deploy-Di_Q01qx.js → deploy-Obj4nE-Z.js} +10 -14
  47. package/dist/deploy-Obj4nE-Z.js.map +1 -0
  48. package/dist/{dev-banner-CWHIk8tH.d.ts → dev-banner-B5AUHmu1.d.ts} +1 -4
  49. package/dist/dev-landing-BI5UdmOb.d.ts +32 -0
  50. package/dist/dev-landing-CD-si4dW.js +50 -0
  51. package/dist/dev-landing-CD-si4dW.js.map +1 -0
  52. package/dist/dev-vite.d.ts +9 -14
  53. package/dist/dev-vite.js +11 -10
  54. package/dist/dev-vite.js.map +1 -1
  55. package/dist/dev.d.ts +3 -2
  56. package/dist/dev.js +2 -1
  57. package/dist/doctor-BA0i-YAN.js +270 -0
  58. package/dist/doctor-BA0i-YAN.js.map +1 -0
  59. package/dist/dump-D1vX8ozg.js +133 -0
  60. package/dist/dump-D1vX8ozg.js.map +1 -0
  61. package/dist/errors-7Rk1HGCE.js +160 -0
  62. package/dist/errors-7Rk1HGCE.js.map +1 -0
  63. package/dist/{validate-DtljsCh1.js → export-BVL2EvYE.js} +409 -19
  64. package/dist/export-BVL2EvYE.js.map +1 -0
  65. package/dist/fsck-BWkPgov4.js +145 -0
  66. package/dist/fsck-BWkPgov4.js.map +1 -0
  67. package/dist/{gcs-admin-Bx6xSNJj.d.ts → gcs-admin-Dso1HWQj.d.ts} +18 -14
  68. package/dist/gcs.d.ts +19 -7
  69. package/dist/gcs.js +1 -2
  70. package/dist/{goog4-signer-Z7KnJ1su.js → goog4-signer-CeLIABoE.js} +102 -92
  71. package/dist/goog4-signer-CeLIABoE.js.map +1 -0
  72. package/dist/{http-7zT29K3P.js → http-Z5rZyYMX.js} +898 -271
  73. package/dist/http-Z5rZyYMX.js.map +1 -0
  74. package/dist/http-transport-DNUM8kU-.js +1299 -0
  75. package/dist/http-transport-DNUM8kU-.js.map +1 -0
  76. package/dist/http.d.ts +366 -294
  77. package/dist/http.js +2 -2
  78. package/dist/index-JJrIu1pO.d.ts +135 -0
  79. package/dist/index-LEgHN0qJ.d.ts +50 -0
  80. package/dist/{index-DP3ClvcA.d.ts → index-RiEYj8t0.d.ts} +291 -78
  81. package/dist/index.d.ts +27 -6
  82. package/dist/index.js +3 -5
  83. package/dist/inspect-BTsVYZKd.js +196 -0
  84. package/dist/inspect-BTsVYZKd.js.map +1 -0
  85. package/dist/{key-Di6yyxFu.js → key-C4FPZ9Io.js} +3 -4
  86. package/dist/{key-Di6yyxFu.js.map → key-C4FPZ9Io.js.map} +1 -1
  87. package/dist/ledger-Dj_bGgo0.js +192 -0
  88. package/dist/ledger-Dj_bGgo0.js.map +1 -0
  89. package/dist/legacy-names-DgZBtgOh.js +47 -0
  90. package/dist/legacy-names-DgZBtgOh.js.map +1 -0
  91. package/dist/log-C9W15Dfo.d.ts +94 -0
  92. package/dist/log-tail-DWJbneBF.js +142 -0
  93. package/dist/log-tail-DWJbneBF.js.map +1 -0
  94. package/dist/log-walk-C-vA-WGJ.js +111 -0
  95. package/dist/log-walk-C-vA-WGJ.js.map +1 -0
  96. package/dist/maintenance-Dd-Yakqj.js +1709 -0
  97. package/dist/maintenance-Dd-Yakqj.js.map +1 -0
  98. package/dist/maintenance-DevB6z4e.js +2237 -0
  99. package/dist/maintenance-DevB6z4e.js.map +1 -0
  100. package/dist/maintenance.d.ts +100 -3
  101. package/dist/maintenance.js +1 -3
  102. package/dist/node.d.ts +119 -92
  103. package/dist/node.js +3 -3
  104. package/dist/{observability-Ch-VQJyE.js → observability-C-ISCCLE.js} +1247 -326
  105. package/dist/observability-C-ISCCLE.js.map +1 -0
  106. package/dist/observability.d.ts +27 -3
  107. package/dist/observability.js +3 -3
  108. package/dist/path-segment-DBXG26PW.js +363 -0
  109. package/dist/path-segment-DBXG26PW.js.map +1 -0
  110. package/dist/{plan-C4qgiXSg.js → plan-BvQbaNMe.js} +19 -11
  111. package/dist/plan-BvQbaNMe.js.map +1 -0
  112. package/dist/request-CRWiTrza.js +272 -0
  113. package/dist/request-CRWiTrza.js.map +1 -0
  114. package/dist/restore-U6Im8V1V.js +1467 -0
  115. package/dist/restore-U6Im8V1V.js.map +1 -0
  116. package/dist/retry-OBtLB2GC.js +126 -0
  117. package/dist/retry-OBtLB2GC.js.map +1 -0
  118. package/dist/rolldown-runtime-D3KUYPsf.js +12 -0
  119. package/dist/{runtime-spec--LykAdl1.js → runtime-spec-B5mg3pHF.js} +189 -28
  120. package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
  121. package/dist/{s3-http-DD5gDc7t.d.ts → s3-http-DBC_wiCL.d.ts} +14 -8
  122. package/dist/s3.d.ts +20 -7
  123. package/dist/s3.js +4 -5
  124. package/dist/s3.js.map +1 -1
  125. package/dist/{sha256-CqcKTjw9.js → sha256-4FfGQNPw.js} +9 -9
  126. package/dist/sha256-4FfGQNPw.js.map +1 -0
  127. package/dist/{shared-secret-DgEicd3x.js → shared-secret-Vkur-8r0.js} +27 -15
  128. package/dist/shared-secret-Vkur-8r0.js.map +1 -0
  129. package/dist/{aws4fetch.esm-CXE5ZbAa.js → sigv4-sign-5IUflUD_.js} +143 -96
  130. package/dist/sigv4-sign-5IUflUD_.js.map +1 -0
  131. package/dist/snapshot-CknzkDM0.js +148 -0
  132. package/dist/snapshot-CknzkDM0.js.map +1 -0
  133. package/dist/{src-BMFfDUI2.js → src-Actga-bO.js} +949 -363
  134. package/dist/src-Actga-bO.js.map +1 -0
  135. package/dist/src-D0MQfvOp.js +812 -0
  136. package/dist/src-D0MQfvOp.js.map +1 -0
  137. package/dist/src-Dr9uo3dc.js +501 -0
  138. package/dist/src-Dr9uo3dc.js.map +1 -0
  139. package/dist/{subcommand-BV68pqwJ.js → subcommand-BLoF66dG.js} +89 -16
  140. package/dist/subcommand-BLoF66dG.js.map +1 -0
  141. package/dist/{time-DUqvFMHq.js → time-DRxTP9iv.js} +15 -34
  142. package/dist/time-DRxTP9iv.js.map +1 -0
  143. package/dist/types-suVbsEWS.d.ts +116 -0
  144. package/dist/{usage-BMZR8o6U.js → usage-CPzVhrQr.js} +40 -45
  145. package/dist/usage-CPzVhrQr.js.map +1 -0
  146. package/dist/uuid-BuT_c404.js +333 -0
  147. package/dist/uuid-BuT_c404.js.map +1 -0
  148. package/dist/verifier-Bmlmndzo.d.ts +95 -0
  149. package/dist/{wire-izfGZDvr.js → wire-DndvKU-K.js} +2 -3
  150. package/dist/wire-DndvKU-K.js.map +1 -0
  151. package/package.json +90 -69
  152. package/dist/aws4fetch.esm-CXE5ZbAa.js.map +0 -1
  153. package/dist/bytes-BXdamO3L.js +0 -11
  154. package/dist/bytes-BXdamO3L.js.map +0 -1
  155. package/dist/cloudflare-wrVYf4bb.js.map +0 -1
  156. package/dist/config-B6nTy8e2.js +0 -3095
  157. package/dist/config-B6nTy8e2.js.map +0 -1
  158. package/dist/constants-CfeMWQWk.js +0 -222
  159. package/dist/constants-CfeMWQWk.js.map +0 -1
  160. package/dist/context-DRZ3tZ5l.js.map +0 -1
  161. package/dist/cost-_SE_SVgZ.js +0 -203
  162. package/dist/cost-_SE_SVgZ.js.map +0 -1
  163. package/dist/current-json-C6nhPOm1.js.map +0 -1
  164. package/dist/db-DjjthkTi.d.ts +0 -254
  165. package/dist/deploy-Di_Q01qx.js.map +0 -1
  166. package/dist/doctor-RWVRpvat.js +0 -102
  167. package/dist/doctor-RWVRpvat.js.map +0 -1
  168. package/dist/dump-m2vEYDNY.js +0 -94
  169. package/dist/dump-m2vEYDNY.js.map +0 -1
  170. package/dist/errors-Dfa3p78c.js +0 -78
  171. package/dist/errors-Dfa3p78c.js.map +0 -1
  172. package/dist/export-DenKwEQu.js +0 -401
  173. package/dist/export-DenKwEQu.js.map +0 -1
  174. package/dist/fsck-2Vq-7-e2.js +0 -279
  175. package/dist/fsck-2Vq-7-e2.js.map +0 -1
  176. package/dist/goog4-signer-Z7KnJ1su.js.map +0 -1
  177. package/dist/http-7zT29K3P.js.map +0 -1
  178. package/dist/http-transport-BTgVCY5r.js +0 -1250
  179. package/dist/http-transport-BTgVCY5r.js.map +0 -1
  180. package/dist/index-BHz92Acj.d.ts +0 -162
  181. package/dist/index-CEZKQsKt.d.ts +0 -1113
  182. package/dist/index-uE-w2dgj.d.ts +0 -115
  183. package/dist/indexes-Dn9hbGQG.d.ts +0 -22
  184. package/dist/inspect-BpYbH1DM.js +0 -133
  185. package/dist/inspect-BpYbH1DM.js.map +0 -1
  186. package/dist/log-tail-QWU4wlu-.js +0 -514
  187. package/dist/log-tail-QWU4wlu-.js.map +0 -1
  188. package/dist/maintenance-BGHGt2Yg.d.ts +0 -537
  189. package/dist/maintenance-DULFcpd1.js +0 -2144
  190. package/dist/maintenance-DULFcpd1.js.map +0 -1
  191. package/dist/maintenance-fEi-UZ2o.js +0 -1412
  192. package/dist/maintenance-fEi-UZ2o.js.map +0 -1
  193. package/dist/normalize-rjnZLwS4.js +0 -133
  194. package/dist/normalize-rjnZLwS4.js.map +0 -1
  195. package/dist/observability-Ch-VQJyE.js.map +0 -1
  196. package/dist/plan-C4qgiXSg.js.map +0 -1
  197. package/dist/query-C43r-6ib.js +0 -1773
  198. package/dist/query-C43r-6ib.js.map +0 -1
  199. package/dist/rebuild-index-BH1dc1p6.js +0 -81
  200. package/dist/rebuild-index-BH1dc1p6.js.map +0 -1
  201. package/dist/request-u0M51mhJ.js +0 -72
  202. package/dist/request-u0M51mhJ.js.map +0 -1
  203. package/dist/restore-D0VYWzfP.js +0 -778
  204. package/dist/restore-D0VYWzfP.js.map +0 -1
  205. package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
  206. package/dist/runtime-spec--LykAdl1.js.map +0 -1
  207. package/dist/sha256-CqcKTjw9.js.map +0 -1
  208. package/dist/shared-secret-DgEicd3x.js.map +0 -1
  209. package/dist/src-BMFfDUI2.js.map +0 -1
  210. package/dist/src-DYZ4H1aF.js +0 -392
  211. package/dist/src-DYZ4H1aF.js.map +0 -1
  212. package/dist/src-DvbTEya2.js +0 -536
  213. package/dist/src-DvbTEya2.js.map +0 -1
  214. package/dist/subcommand-BV68pqwJ.js.map +0 -1
  215. package/dist/time-DUqvFMHq.js.map +0 -1
  216. package/dist/usage-BMZR8o6U.js.map +0 -1
  217. package/dist/validate-DtljsCh1.js.map +0 -1
  218. package/dist/wire-izfGZDvr.js.map +0 -1
@@ -1,1412 +0,0 @@
1
- import { n as encodeJsonBytes, t as decodeJsonBytes } from "./bytes-BXdamO3L.js";
2
- import { _ as MAINTENANCE_PROFILE_CF_PAID, f as GC_MAX_PENDING_CANDIDATES, g as MAINTENANCE_PROFILE_CF_FREE, l as sha256Hex, p as GC_PENDING_CONTENT_TYPE } from "./config-B6nTy8e2.js";
3
- import { a as walkLogRange, c as loadSnapshotAsMap, d as logObjectKey, f as casUpdateCurrentJson, h as readCurrentJson, l as snapshotKey, m as logSeqStartOf, n as probeTailFrom, o as walkLogRangeWithBytes, r as foldLogEntriesOnto, s as encodeSnapshotBody, u as snapshotHash } from "./log-tail-QWU4wlu-.js";
4
- import { n as matchesWire, t as validateWire } from "./validate-DtljsCh1.js";
5
- import { o as BaerlyError } from "./baerly.js";
6
- import { l as assertNameNotReserved } from "./subcommand-BV68pqwJ.js";
7
- import { AsyncLocalStorage } from "node:async_hooks";
8
- //#region ../protocol/src/coordination/gc-pending.ts
9
- /**
10
- * `gc/pending.json` — the per-collection GC candidate ledger. CAS-
11
- * protected; one per `(tenant, collection)` key — for example
12
- * `<tenant>/<collection>/gc/pending.json`. `runGc()` in
13
- * `packages/server/src/gc.ts` is the single writer that adds and
14
- * removes entries. Stays small in steady state because every
15
- * candidate is deleted once `due_at` passes.
16
- *
17
- * "Mark" appends candidates with a future `due_at`; "sweep" deletes
18
- * candidates whose `due_at` is in the past. The two phases run in
19
- * the same compactor pass — see `runGc()` in
20
- * `packages/server/src/gc.ts`.
21
- *
22
- * Lives next to {@link CurrentJson} in `coordination/` — same shape
23
- * of "CAS-protected small control object." Pure module; no Node
24
- * imports; Worker-bundleable.
25
- *
26
- * @see packages/server/src/gc.ts
27
- */
28
- /**
29
- * Read + parse `gc/pending.json` at `key`. Returns `null` on
30
- * not-found.
31
- *
32
- * @throws BaerlyError{code:"InvalidResponse"} — body is not valid
33
- * JSON, or `schema_version` is unknown, or the shape fails
34
- * the runtime guard.
35
- */
36
- const readGcPending = async (storage, key, opts) => {
37
- const got = await storage.get(key, opts);
38
- if (got === null) return null;
39
- let parsed;
40
- try {
41
- parsed = decodeJsonBytes(got.body);
42
- } catch (error) {
43
- throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: body is not valid JSON`, error);
44
- }
45
- return {
46
- json: assertGcPending(parsed, key),
47
- etag: got.etag
48
- };
49
- };
50
- /**
51
- * Create `gc/pending.json` if-and-only-if it does not exist (S3
52
- * `If-None-Match: "*"`). Use this once per collection at first GC
53
- * run; subsequent updates go through {@link casUpdateGcPending}.
54
- *
55
- * @throws BaerlyError{code:"Conflict"} — the key already exists.
56
- * @throws BaerlyError{code:"InvalidResponse"} — `initial` fails the
57
- * runtime shape guard.
58
- */
59
- const createGcPending = async (storage, key, initial, opts) => {
60
- assertGcPending(initial, key);
61
- const body = encodeJsonBytes(initial);
62
- const putOpts = {
63
- ifNoneMatch: "*",
64
- contentType: GC_PENDING_CONTENT_TYPE,
65
- ...opts?.signal !== void 0 && { signal: opts.signal }
66
- };
67
- let result;
68
- try {
69
- result = await storage.put(key, body, putOpts);
70
- } catch (error) {
71
- throw translateCasError(error, key);
72
- }
73
- return {
74
- json: initial,
75
- etag: result.etag
76
- };
77
- };
78
- /**
79
- * Read-modify-write `gc/pending.json` under CAS, with a bounded retry
80
- * loop. Each attempt re-reads the latest body, hands the `mutator`
81
- * that latest value, and writes the result with
82
- * `If-Match: <latest etag>`. On `Conflict` (a concurrent writer landed
83
- * between this attempt's read and write) the loop re-reads and
84
- * re-applies the mutator, up to {@link GC_PENDING_CAS_MAX_ATTEMPTS}
85
- * total attempts, then surfaces `Conflict`.
86
- *
87
- * `mutator` MUST be a pure, deterministic MERGE of this pass's results
88
- * INTO the `latest` value it is handed — it is called once per attempt
89
- * (so it must not have side effects), and it MUST read `latest` rather
90
- * than ignore it and write a precomputed set. Ignoring `latest` would
91
- * silently overwrite a concurrent pass's candidates: the
92
- * If-Match succeeds (it used the fresh etag), so no conflict is
93
- * raised, and the concurrent marks are lost. See {@link mergeGcPending}.
94
- *
95
- * @throws BaerlyError{code:"Conflict"} — another writer kept landing a
96
- * write between this function's read and write for every
97
- * attempt.
98
- * @throws BaerlyError{code:"InvalidResponse"} — `key` does not exist
99
- * (use {@link createGcPending} instead) or body doesn't
100
- * parse / fails the shape guard.
101
- */
102
- const casUpdateGcPending = async (storage, key, mutator, opts) => {
103
- let lastConflict;
104
- for (let attempt = 0; attempt < 3; attempt++) {
105
- const existing = await readGcPending(storage, key, opts);
106
- if (existing === null) throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key} does not exist; use createGcPending first`);
107
- const next = mutator(structuredClone(existing.json));
108
- assertGcPending(next, key);
109
- const body = encodeJsonBytes(next);
110
- const putOpts = {
111
- ifMatch: existing.etag,
112
- contentType: GC_PENDING_CONTENT_TYPE,
113
- ...opts?.signal !== void 0 && { signal: opts.signal }
114
- };
115
- try {
116
- return {
117
- json: next,
118
- etag: (await storage.put(key, body, putOpts)).etag
119
- };
120
- } catch (error) {
121
- const translated = translateCasError(error, key);
122
- if (translated.code !== "Conflict") throw translated;
123
- lastConflict = translated;
124
- }
125
- }
126
- throw lastConflict;
127
- };
128
- /**
129
- * Pure merge of one GC pass's results INTO the `latest`
130
- * `gc/pending.json` value, used as the {@link casUpdateGcPending}
131
- * mutator. Deterministic, no I/O — the kernel unit + mutation test
132
- * surface. Splitting it out is what makes the CAS write correct under
133
- * concurrency: each retry re-merges against fresh `latest` rather than
134
- * overwriting it with a stale precomputed set.
135
- *
136
- * Semantics:
137
- * - **candidates**: start from `latest.candidates`, DROP any whose key
138
- * this pass already DELETED (`sweptKeys`), then APPEND every fresh
139
- * mark whose key is not already present AND was not itself swept
140
- * this pass (a `graceMillis: 0` pass can mark-and-sweep a key in one
141
- * go — re-adding it to the ledger after deleting it would be wrong;
142
- * dedup also drops a key a concurrent pass already marked). Capped at
143
- * `maxCandidates`.
144
- * - **last_swept_at**: the lexicographically LATER of `latest`'s and
145
- * this pass's (ISO-8601 UTC; `""` sorts lowest so a real timestamp
146
- * always wins). Never regress a concurrent pass's newer sweep time.
147
- * - **content_scan_cursor**: rotation cursor — liveness, not
148
- * correctness; just don't regress forward progress. The two sides
149
- * are NOT symmetric: `pass.nextContentCursor === undefined` means
150
- * THIS pass examined to the END of the keyspace (WRAP — the most-
151
- * advanced position), whereas `latest.content_scan_cursor` absent
152
- * means the stored ledger has no cursor yet (start-from-beginning).
153
- * So:
154
- * - our pass WRAPPED ⇒ result wraps (key omitted) — our pass is
155
- * the most advanced; this is the single-writer rotation reset.
156
- * - else (our pass advanced to a defined cursor):
157
- * - latest cursor defined ⇒ take the lexicographically GREATER
158
- * (don't regress a concurrent pass's advance);
159
- * - latest cursor absent ⇒ keep OUR advance (don't lose it).
160
- */
161
- const mergeGcPending = (latest, pass) => {
162
- const surviving = latest.candidates.filter((c) => !pass.sweptKeys.has(c.key));
163
- const present = new Set(surviving.map((c) => c.key));
164
- const appended = [];
165
- for (const c of pass.newCandidates) if (!pass.sweptKeys.has(c.key) && !present.has(c.key)) {
166
- present.add(c.key);
167
- appended.push(c);
168
- }
169
- const candidates = [...surviving, ...appended].slice(0, pass.maxCandidates);
170
- const lastSweptAt = pass.lastSweptAt > latest.last_swept_at ? pass.lastSweptAt : latest.last_swept_at;
171
- const latestCursor = latest.content_scan_cursor;
172
- const passCursor = pass.nextContentCursor;
173
- let cursor;
174
- if (passCursor === void 0) cursor = void 0;
175
- else if (latestCursor !== void 0) cursor = passCursor > latestCursor ? passCursor : latestCursor;
176
- else cursor = passCursor;
177
- return {
178
- schema_version: 1,
179
- candidates,
180
- last_swept_at: lastSweptAt,
181
- ...cursor !== void 0 && { content_scan_cursor: cursor }
182
- };
183
- };
184
- const VALID_REASONS = /* @__PURE__ */ new Set([
185
- "stale-log",
186
- "orphan-snapshot",
187
- "orphan-content"
188
- ]);
189
- /**
190
- * Runtime guard for `parsed` to be a {@link GcPending}. Throws
191
- * `BaerlyError{code:"InvalidResponse"}` rather than coercing.
192
- */
193
- const assertGcPending = (parsed, key) => {
194
- if (parsed === null || typeof parsed !== "object") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: parsed body is not an object`);
195
- const r = parsed;
196
- if (r["schema_version"] !== 1) throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: unsupported schema_version ${String(r["schema_version"])}; expected 1`);
197
- if (!Array.isArray(r["candidates"])) throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates must be an array`);
198
- for (let i = 0; i < r["candidates"].length; i++) {
199
- const c = r["candidates"][i];
200
- if (c === null || typeof c !== "object") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates[${String(i)}] is not an object`);
201
- const cr = c;
202
- if (typeof cr["key"] !== "string" || cr["key"].length === 0) throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates[${String(i)}].key must be a non-empty string`);
203
- if (typeof cr["due_at"] !== "string") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates[${String(i)}].due_at must be a string`);
204
- if (typeof cr["reason"] !== "string" || !VALID_REASONS.has(cr["reason"])) throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates[${String(i)}].reason must be one of stale-log|orphan-snapshot|orphan-content`);
205
- }
206
- if (typeof r["last_swept_at"] !== "string") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: last_swept_at must be a string`);
207
- if (r["content_scan_cursor"] !== void 0 && typeof r["content_scan_cursor"] !== "string") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: content_scan_cursor must be a string when present`);
208
- return parsed;
209
- };
210
- /**
211
- * Wrap a storage-level error with `gc/pending.json at <key>`
212
- * location context. `Conflict` (the storage layer's CAS-lost signal)
213
- * is re-thrown with an annotated message; other `BaerlyError`s pass
214
- * through; non-`BaerlyError` falls through as `InvalidResponse`.
215
- */
216
- const translateCasError = (e, key) => {
217
- if (e instanceof BaerlyError && e.code === "Conflict") return new BaerlyError("Conflict", `gc/pending.json CAS lost at ${key}: ${e.message}`, e);
218
- if (e instanceof BaerlyError) return e;
219
- return new BaerlyError("InvalidResponse", `gc/pending.json write at ${key} failed: ${String(e)}`, e);
220
- };
221
- //#endregion
222
- //#region ../protocol/src/hashing.ts
223
- /**
224
- * Width of the {@link ContentVersionId} hex strings produced by
225
- * {@link versionFromContent}. 32 hex chars = 128 bits, matching the
226
- * information content of a v4 UUID. Birthday-bound collision probability
227
- * at N=10⁹ writes is ~1.5 × 10⁻²¹ (≈ N² / 2¹²⁹); ample for a
228
- * content-addressed version id. A collision is not detected at runtime —
229
- * two distinct bodies that share a truncated hash would alias to the same
230
- * content key, so a reader could observe the wrong body. The bound above
231
- * is the sole guard, and it sits far below any plausible write volume.
232
- *
233
- * @see docs/spec/log-entry-shape.md §"Content body layout"
234
- */
235
- const VERSION_HEX_LENGTH = 32;
236
- /**
237
- * Content-addressed {@link ContentVersionId}: SHA-256 of `body`,
238
- * lowercase hex, truncated to {@link VERSION_HEX_LENGTH}. Same body
239
- * bytes ⇒ same ContentVersionId — scoped to **single-writer idempotent
240
- * replay** (a crash-recovery rewrite of the same in-memory value by the
241
- * same writer reproduces the content key the manifest already
242
- * referenced). `body` is non-canonical (`JSON.stringify`, insertion
243
- * key order — see `encodeJsonBytes`), so this is NOT cross-writer
244
- * content dedup: different key order ⇒ different key for an equal value.
245
- *
246
- * Async because {@link crypto.subtle.digest} returns an `ArrayBuffer`
247
- * via Promise. Workers and browsers both expose `crypto.subtle`
248
- * synchronously enough that the await fits naturally in the write
249
- * pipeline.
250
- *
251
- * @see docs/spec/log-entry-shape.md §"Content body layout"
252
- */
253
- const versionFromContent = async (body) => {
254
- return (await sha256Hex(body)).slice(0, VERSION_HEX_LENGTH);
255
- };
256
- //#endregion
257
- //#region ../protocol/src/metrics.ts
258
- /**
259
- * No-op recorder. Safe default when no operator sink is wired —
260
- * emission sites that read `getCurrentContext()?.recorder` fall
261
- * back to this outside an active `runWithContext` scope.
262
- */
263
- const noopMetricsRecorder = {
264
- counter: () => {},
265
- gauge: () => {},
266
- histogram: () => {}
267
- };
268
- //#endregion
269
- //#region ../server/src/indexes.ts
270
- /**
271
- * Secondary indexes — declarative collection-config-driven
272
- * index entries that the writer emits inside the same CAS fence as
273
- * the log entry and content body.
274
- *
275
- * The {@link IndexDefinition} TYPE lives in `@baerly/protocol`
276
- * (cross-platform). This module owns the runtime helpers that
277
- * operate on that shape:
278
- *
279
- * - {@link validateIndexDefinition} — synchronous schema check
280
- * for path-segment safety; thrown at `Writer` construction.
281
- * - {@link encodeIndexValue} — value-order-preserving base-32 of a
282
- * type-tagged byte stream (null/bool tag-only, numbers as sortable
283
- * IEEE 754, strings as raw UTF-8, objects as `JSON.stringify`
284
- * bytes for equality only).
285
- * - {@link indexKeyFor} / {@link indexKeyPrefix} — the wire-key
286
- * shape consumed by the writer's index PUTs and the rebuild
287
- * command's idempotent reconciliation.
288
- * - {@link projectIndexValues} / {@link allIndexKeysFor} — pure
289
- * projections from a doc body to the set of index keys it
290
- * produces under a collection's declared indexes.
291
- *
292
- * Wire shape (single-field):
293
- *
294
- * `<logPrefix>/index/<indexName>/<value-b32>/<docId>.json`
295
- *
296
- * Wire shape (composite):
297
- *
298
- * `<logPrefix>/index/<indexName>/<a-b32>/<b-b32>/<docId>.json`
299
- *
300
- * Body is zero bytes. Each entry is a fact ("doc `<docId>` has
301
- * `<field> = <value>`"), not data. Readers list the prefix, extract
302
- * the doc id from each key, then issue a content GET on each.
303
- *
304
- * Encoding is RFC-4648 base-32 (lowercase alphabet `[0-9a-v]`,
305
- * matching `packages/protocol/src/log.ts:str2uintDesc` style) on a
306
- * type-tagged byte stream (see {@link encodeIndexValue}) so that:
307
- *
308
- * - String "5" and number 5 produce distinct encodings
309
- * (type-tag prefix keeps the slots disjoint).
310
- * - Equal-by-value inputs produce byte-equal segments.
311
- * - Lex order under storage `list(prefix)` matches value order:
312
- * `null < false < true < number < string < object`, with
313
- * numeric values ordered by IEEE 754 magnitude (range walks
314
- * and `$in` walks over numeric fields are first-class — no
315
- * planner fall-back to full-scan).
316
- *
317
- * Composite read routing is left-anchored. The planner may consume an
318
- * equality prefix plus a range / `$in` tail slot; predicates that do
319
- * not match a routable prefix fall back to the snapshot+log fold.
320
- *
321
- * @see docs/spec/sync-protocol.md — index emission is hybrid around
322
- * the commit: additive (new) keys are PUT before the committing
323
- * `log/<seq>` create, and stale-key DELETEs land after it.
324
- */
325
- /** Path-safe segment name. */
326
- const INDEX_NAME_RE = /^[a-z][a-z0-9_]*$/;
327
- /**
328
- * Lowercase base-32 alphabet, RFC 4648 variant matching the
329
- * `packages/protocol/src/log.ts:str2uintDesc` style (`[0-9a-v]`).
330
- * Lex-order-preserving under storage `list(prefix)` semantics.
331
- */
332
- const B32_ALPHABET = "0123456789abcdefghijklmnopqrstuv";
333
- /**
334
- * Reject malformed {@link IndexDefinition} shapes synchronously, at
335
- * writer construction. See docs/adr/003-layout-versioning-cordon.md.
336
- *
337
- * @throws BaerlyError code="InvalidConfig" — reserved leading-`_` `name`.
338
- * @throws BaerlyError code="SchemaError" — `name` fails the regex, or `on` is empty.
339
- */
340
- const validateIndexDefinition = (def) => {
341
- assertNameNotReserved(def.name, "index.name");
342
- if (!INDEX_NAME_RE.test(def.name)) throw new BaerlyError("SchemaError", `index.name must match /^[a-z][a-z0-9_]*$/; got ${JSON.stringify(def.name)}`);
343
- if (typeof def.on === "string") {
344
- if (def.on.length === 0) throw new BaerlyError("SchemaError", `index ${def.name}.on must be non-empty`);
345
- } else if (def.on.length === 0) throw new BaerlyError("SchemaError", `index ${def.name}.on must be non-empty array`);
346
- if (def.predicate !== void 0) try {
347
- validateWire(def.predicate);
348
- } catch (error) {
349
- if (error instanceof BaerlyError) throw new BaerlyError("SchemaError", `index ${def.name}.predicate is invalid: ${error.message}`, error);
350
- throw error;
351
- }
352
- };
353
- /**
354
- * Type-tag bytes for the value-order-preserving wire format. The
355
- * tag is the LEADING byte of the encoded payload; the values are
356
- * picked so the type order under byte-wise lex is
357
- * `null < false < true < number < string < object`.
358
- *
359
- * | Type | Byte-prefix | Payload |
360
- * |---------|-------------|----------------------------------------------------|
361
- * | null | 0x10 | (none) |
362
- * | false | 0x20 | (none) |
363
- * | true | 0x21 | (none) |
364
- * | number | 0x30 | 8-byte sortable big-endian IEEE 754 |
365
- * | string | 0x40 | UTF-8 bytes of the string (no quotes, no escapes) |
366
- * | object | 0x50 | UTF-8 bytes of `JSON.stringify(v)` |
367
- *
368
- * Local to the encoder by design — these are wire shape, not
369
- * cross-package protocol constants (see `CLAUDE.md` § "Magic
370
- * values").
371
- */
372
- const TYPE_NULL = 16;
373
- const TYPE_FALSE = 32;
374
- const TYPE_TRUE = 33;
375
- const TYPE_NUMBER = 48;
376
- const TYPE_STRING = 64;
377
- const TYPE_OBJECT = 80;
378
- /**
379
- * Encode a JS double as an 8-byte big-endian sortable IEEE 754
380
- * payload. Byte-wise lex order on the result matches numeric order
381
- * across all finite doubles plus `±Infinity`:
382
- *
383
- * 1. Get the 8-byte big-endian view of the double.
384
- * 2. If the sign bit is `0` (zero or positive), flip the sign bit
385
- * (XOR `0x80` on byte 0) so positives sort above negatives.
386
- * 3. If the sign bit is `1` (negative), flip every bit in all 8
387
- * bytes so more-negative sorts lower.
388
- *
389
- * `NaN` has no order-preserving slot and is rejected — see the
390
- * `encodeIndexValue` JSDoc for the wire-contract rationale.
391
- * `-0` and `+0` collapse because the `n === 0 ? 0 : n` coercion below
392
- * forces both into the positive-zero branch before `setFloat64`.
393
- */
394
- const encodeNumberPayload = (n) => {
395
- if (Number.isNaN(n)) throw new BaerlyError("SchemaError", `encodeIndexValue: NaN is not indexable (the byte encoding has no order-preserving slot for it)`);
396
- const buf = /* @__PURE__ */ new ArrayBuffer(8);
397
- new DataView(buf).setFloat64(0, n === 0 ? 0 : n, false);
398
- const bytes = new Uint8Array(buf);
399
- if ((bytes[0] & 128) === 0) bytes[0] = bytes[0] ^ 128;
400
- else for (let i = 0; i < 8; i++) bytes[i] = bytes[i] ^ 255;
401
- return bytes;
402
- };
403
- /**
404
- * Compose the typed byte stream for one value. The leading byte is
405
- * the type tag (see {@link TYPE_NULL} et al.); the payload shape is
406
- * type-dependent. Strings are emitted as their raw UTF-8 bytes (no
407
- * JSON quoting / escaping) so byte-wise lex order on encoded strings
408
- * matches byte-wise lex order on the source UTF-8. Objects fall back
409
- * to `JSON.stringify` for equality only.
410
- */
411
- const encodeBytes = (v) => {
412
- if (v === null || v === void 0) return new Uint8Array([TYPE_NULL]);
413
- if (v === false) return new Uint8Array([TYPE_FALSE]);
414
- if (v === true) return new Uint8Array([TYPE_TRUE]);
415
- if (typeof v === "number") {
416
- const payload = encodeNumberPayload(v);
417
- const out = new Uint8Array(1 + payload.length);
418
- out[0] = TYPE_NUMBER;
419
- out.set(payload, 1);
420
- return out;
421
- }
422
- if (typeof v === "string") {
423
- const utf8 = new TextEncoder().encode(v);
424
- const out = new Uint8Array(1 + utf8.length);
425
- out[0] = TYPE_STRING;
426
- out.set(utf8, 1);
427
- return out;
428
- }
429
- const utf8 = encodeJsonBytes(v);
430
- const out = new Uint8Array(1 + utf8.length);
431
- out[0] = TYPE_OBJECT;
432
- out.set(utf8, 1);
433
- return out;
434
- };
435
- /**
436
- * Encode an arbitrary `DocumentValue` value as a path-safe segment.
437
- *
438
- * Type-tagged byte stream, base-32-encoded for path safety. Lex
439
- * order on encoded bytes matches:
440
- *
441
- * - **Type order**: `null < false < true < number < string < object`.
442
- * - **Within numbers**: IEEE 754 numeric order (sortable
443
- * big-endian payload, sign-bit-flipped or all-bits-flipped).
444
- * `-Infinity` sorts lowest, `+Infinity` highest.
445
- * - **Within strings**: UTF-8 byte order.
446
- * - **Within objects**: byte-equality only (still
447
- * `JSON.stringify`-insertion-order dependent).
448
- *
449
- * Numbers ARE range-safe under this encoder — `9` sorts below `10`
450
- * as expected. The query planner's old
451
- * `numeric-range-on-byte-encoder` guard has been removed; range
452
- * walks and `$in` walks over numeric fields are routed normally.
453
- *
454
- * `NaN` throws `BaerlyError{code:"SchemaError"}` at write time —
455
- * the byte encoding has no order-preserving slot for it, and a
456
- * silent collapse to the `null` key (as the prior
457
- * `JSON.stringify`-based encoder did, since
458
- * `JSON.stringify(NaN) === "null"`) is a worse failure mode than
459
- * a loud reject.
460
- *
461
- * `-0` and `+0` collapse to the same encoding.
462
- *
463
- * Equal-by-value inputs (e.g. two `{a:1, b:2}` objects with the
464
- * same key insertion order) produce byte-equal segments;
465
- * structurally-different but visually-similar inputs (`"5"` vs `5`)
466
- * are kept apart by the type-tag prefix.
467
- *
468
- * String ranges remain safe: `"2026-05-13" < "2026-05-14"`
469
- * byte-wise matches semantic order. ISO 8601 timestamps,
470
- * alphabetical priorities like `"p1"/"p2"/"p3"`, and any
471
- * fixed-width string encoding are usable as range-walked indexed
472
- * fields.
473
- */
474
- const encodeIndexValue = (v) => {
475
- const bytes = encodeBytes(v);
476
- let out = "";
477
- let bits = 0;
478
- let value = 0;
479
- for (const b of bytes) {
480
- value = value << 8 | b;
481
- bits += 8;
482
- while (bits >= 5) {
483
- bits -= 5;
484
- out += B32_ALPHABET[value >> bits & 31];
485
- }
486
- }
487
- if (bits > 0) out += B32_ALPHABET[value << 5 - bits & 31];
488
- return out;
489
- };
490
- /**
491
- * Storage `list(prefix)` boundary for every entry under one index
492
- * of a collection: `<logPrefix>/index/<name>/`. Used by the rebuild
493
- * command's reconciliation walk and by the read-path index hint.
494
- */
495
- const indexKeyPrefix = (logPrefix, indexName) => `${logPrefix}/index/${indexName}/`;
496
- /**
497
- * Build the per-doc index key for one `(def, values, docId)`.
498
- *
499
- * Single-field: `<logPrefix>/index/<name>/<v0-b32>/<docId>.json`.
500
- * Composite: `<logPrefix>/index/<name>/<v0-b32>/<v1-b32>/.../<docId>.json`.
501
- *
502
- * Composite entries are read-path routable when the planner can consume
503
- * a left-anchored prefix of the indexed tuple.
504
- */
505
- const indexKeyFor = (logPrefix, def, values, docId) => {
506
- const segments = values.map(encodeIndexValue).join("/");
507
- return `${logPrefix}/index/${def.name}/${segments}/${docId}.json`;
508
- };
509
- /**
510
- * Project the value tuple a doc body produces under one index
511
- * definition. Returns `undefined` when any indexed field is
512
- * null / undefined / missing — no index entry for that doc under
513
- * that index (SQL "NULL values don't enter the index" semantics).
514
- *
515
- * @throws BaerlyError code="SchemaError" — `on` contains a dotted
516
- * path, or the indexed field's value is an array. Both restrictions
517
- * are current 0.x limitations; multi-value (array) indexes are a follow-up.
518
- */
519
- const projectIndexValues = (def, body) => {
520
- if (body === void 0) return;
521
- const fields = typeof def.on === "string" ? [def.on] : def.on;
522
- const values = [];
523
- for (const field of fields) {
524
- if (field.includes(".")) throw new BaerlyError("SchemaError", `index ${def.name}: dotted-path "on" fields not yet supported (got ${JSON.stringify(field)})`);
525
- const v = body[field];
526
- if (v === null || v === void 0) return;
527
- if (Array.isArray(v)) throw new BaerlyError("SchemaError", `index ${def.name}: cannot index array field "${field}" — multi-value indexes are not supported yet`);
528
- values.push(v);
529
- }
530
- return values;
531
- };
532
- /**
533
- * Compute the full index-key set a single doc produces under every
534
- * declared index of its collection. Skips indexes whose projection
535
- * yields `undefined` (null/missing indexed field). Used by both
536
- * the writer (to PUT new keys) and the rebuild command (to compute
537
- * the expected key set across the live doc map).
538
- *
539
- * Filter-aware (T4): when `def.predicate !== undefined`, the doc
540
- * must satisfy `matchesWire(def.predicate, body)` or the def contributes
541
- * zero keys. The writer's diff `oldKeys` vs `newKeys` then covers
542
- * all four U-quadrants automatically — see the JSDoc on
543
- * `writer.ts` above the index-emission block. `body ===
544
- * undefined` short-circuits ahead of the filter check (no keys for
545
- * an unknown pre-image, regardless of filter), preserving the prior
546
- * D-quadrant behaviour.
547
- */
548
- const allIndexKeysFor = (logPrefix, defs, body, docId) => {
549
- const keys = [];
550
- for (const def of defs) {
551
- if (def.predicate !== void 0 && body !== void 0) {
552
- if (!matchesWire(def.predicate, body)) continue;
553
- }
554
- const values = projectIndexValues(def, body);
555
- if (values !== void 0) keys.push(indexKeyFor(logPrefix, def, values, docId));
556
- }
557
- return keys;
558
- };
559
- //#endregion
560
- //#region ../server/src/observability/context.ts
561
- /**
562
- * Per-request observability context.
563
- *
564
- * One `ObservabilityContext` is created at the entry of each unit-of-
565
- * work (HTTP request, maintenance tick, GC sweep, rebuild run) and
566
- * carried through the call tree via {@link runWithContext} /
567
- * {@link getCurrentContext}, which delegates to a single module-level
568
- * `AsyncLocalStorage` instance.
569
- *
570
- * The context is intentionally tiny: an externally-set
571
- * {@link request_id}, a high-resolution `started_at`, and a mutable
572
- * {@link fields} bag used to accumulate canonical-line attributes
573
- * during the unit's lifecycle.
574
- *
575
- * The context shape is `readonly` everywhere it can be — only the
576
- * contents of `fields` are intended to mutate during a request. The
577
- * {@link fields} map itself is not `readonly` because callers (the
578
- * canonical-line emitter, middleware, the collection API once Dispatch
579
- * 3+ wires it up) need to set entries.
580
- *
581
- * The context carries no sampling state — every unit-of-work emits
582
- * one canonical line unconditionally; there is nothing to gate.
583
- *
584
- * ## Time source
585
- *
586
- * `started_at` uses `performance.now()` so durations can be
587
- * computed without worrying about wall-clock skew (NTP step,
588
- * leap-second smearing). `performance.now()` is part of both Node
589
- * 18+ and the Workers Runtime; we don't fall back to `Date.now()`.
590
- *
591
- * @example
592
- * ```ts
593
- * const ctx = createObservabilityContext({});
594
- * await runWithContext(ctx, async () => {
595
- * const inner = getCurrentContext();
596
- * inner?.fields.set("collection", "tickets");
597
- * await doWork();
598
- * });
599
- * ```
600
- */
601
- /**
602
- * Module-level slot. One instance per process — the Workers
603
- * Runtime's `nodejs_compat` flag wires `node:async_hooks` to a
604
- * per-request scope, so cross-request bleed is impossible there.
605
- */
606
- const als = new AsyncLocalStorage();
607
- /** Returns the currently-active context, or `undefined` outside one. */
608
- const getCurrentContext = () => als.getStore();
609
- //#endregion
610
- //#region ../server/src/compactor.ts
611
- /**
612
- * Compactor: fold a prefix of the live log into a content-
613
- * hashed snapshot file and CAS-advance `current.json` to swap the
614
- * pointer.
615
- *
616
- * The hard correctness requirement is **atomic snapshot generation**:
617
- * a compactor that crashes mid-write must not leave a corrupted body
618
- * that readers consume as truth. The design: every snapshot's filename
619
- * embeds the SHA-256 of its body. A crashed mid-PUT leaves a body that
620
- * doesn't match its own filename hash, and readers reject it as
621
- * "missing." The atomic moment is the CAS-swap of
622
- * `current.json.snapshot`, which is a single conditional PUT.
623
- *
624
- * Order of operations: PUT snapshot body → CAS-advance `current.json`.
625
- * A crash before the swap leaves an orphan snapshot file; the swap
626
- * succeeds iff our captured ETag still matches.
627
- *
628
- * Why level-prefixed chunked snapshots over the alternatives: a
629
- * single monolithic snapshot (every compaction rewrites one well-
630
- * known key) makes partial writes catastrophic and serializes every
631
- * writer on one key. WAL-checkpointing in the rqlite / Raft tradition
632
- * requires a consensus layer baerly-storage doesn't have. The Litestream-
633
- * style multi-level scheme — small fixed number of levels, chunked
634
- * files keyed by sequence range — keeps random GETs cheap on
635
- * S3-compatible storage and avoids LIST. Current ship is single-
636
- * level at L9 (one snapshot replaces the prior; no multi-level merge
637
- * yet); the key format is forward-compatible with future L0..L9
638
- * rolling merges without a wire change.
639
- *
640
- * @see ../../../docs/spec/sync-protocol.md
641
- */
642
- const ctxMetrics$2 = () => getCurrentContext()?.recorder ?? noopMetricsRecorder;
643
- const DEFAULT_MAX_PER_RUN = Number.MAX_SAFE_INTEGER;
644
- const DEFAULT_MIN_TO_COMPACT = 100;
645
- const APPLICATION_JSON$1 = "application/json";
646
- /**
647
- * Fold a prefix of the live log into a new snapshot and CAS-advance
648
- * `current.json`. Idempotent: a second run with no new writes is a
649
- * no-op (below-min-threshold).
650
- *
651
- * Single-attempt: on CAS conflict we return
652
- * `{written: false, skippedReason: "cas-lost", newSnapshotKey}` — the
653
- * caller (the cron handler invoking `runScheduledMaintenance` from
654
- * `./maintenance.ts`) decides whether to schedule another run. The
655
- * orphan snapshot file just written will be swept by `runGc()`.
656
- *
657
- * @throws BaerlyError code="InvalidResponse" — `current.json` is
658
- * present but malformed, or a snapshot body fails its schema /
659
- * collection cross-check.
660
- * @throws BaerlyError code="Internal" — protocol-invariant violation:
661
- * a log entry missing inside `[log_seq_start, foldEnd)`, or the
662
- * prior-snapshot pointer resolves to no body / a body whose hash
663
- * doesn't match its filename.
664
- *
665
- * @example
666
- * ```ts
667
- * import { compact } from "@gusto/baerly-storage";
668
- *
669
- * const res = await compact(
670
- * { storage, currentJsonKey: "app/x/tenant/t/manifests/tickets/current.json" },
671
- * { minEntriesToCompact: 100, maxEntriesPerRun: 40 },
672
- * );
673
- * if (res.written) console.log("snapshot landed at", res.newSnapshotKey);
674
- * ```
675
- */
676
- const compact = async (args, options = {}) => {
677
- const { storage, currentJsonKey } = args;
678
- const internal = options;
679
- const maxPerRun = internal.maxEntriesPerRun ?? DEFAULT_MAX_PER_RUN;
680
- const minToCompact = options.minEntriesToCompact ?? DEFAULT_MIN_TO_COMPACT;
681
- const ceilingBytes = internal.ceilingBytes ?? Number.POSITIVE_INFINITY;
682
- const ceilingEntries = internal.ceilingEntries ?? Number.POSITIVE_INFINITY;
683
- const collectionPrefix = currentJsonKey.slice(0, currentJsonKey.lastIndexOf("/"));
684
- const collectionName = collectionPrefix.slice(collectionPrefix.lastIndexOf("/") + 1);
685
- const read = await readCurrentJson(storage, currentJsonKey, options.signal !== void 0 ? { signal: options.signal } : void 0);
686
- if (read === null) return {
687
- written: false,
688
- skippedReason: "current-json-missing",
689
- previousSnapshotKey: null,
690
- logSeqStartBefore: 0,
691
- logSeqStartAfter: 0,
692
- entriesFolded: 0
693
- };
694
- const current = read.json;
695
- const baseEtag = read.etag;
696
- const logSeqStartBefore = logSeqStartOf(current);
697
- const discoveredTail = (await probeTailFrom(storage, collectionPrefix, Math.max(logSeqStartBefore, current.tail_hint, internal.knownTail ?? 0), { ...options.signal !== void 0 && { signal: options.signal } })).tail;
698
- const nextSeq = discoveredTail;
699
- if (nextSeq - logSeqStartBefore < minToCompact) return {
700
- written: false,
701
- skippedReason: "below-min-threshold",
702
- previousSnapshotKey: current.snapshot,
703
- logSeqStartBefore,
704
- logSeqStartAfter: logSeqStartBefore,
705
- entriesFolded: 0
706
- };
707
- const foldEnd = Math.min(nextSeq, logSeqStartBefore + maxPerRun);
708
- const base = current.snapshot === null ? /* @__PURE__ */ new Map() : await loadSnapshotAsMap(storage, current.snapshot, collectionName, options.signal);
709
- const fetched = await walkLogRangeWithBytes(storage, collectionPrefix, logSeqStartBefore, foldEnd, { signal: options.signal });
710
- const foldedSliceBytes = fetched.reduce((sum, f) => sum + f.bytes, 0);
711
- for (const { entry } of fetched) {
712
- if (entry.collection !== collectionName) continue;
713
- if (entry.doc_id === void 0) continue;
714
- switch (entry.op) {
715
- case "I":
716
- case "U":
717
- if (entry.after !== void 0) base.set(entry.doc_id, entry.after);
718
- break;
719
- case "D":
720
- base.delete(entry.doc_id);
721
- break;
722
- }
723
- }
724
- const bodyBytes = encodeSnapshotBody({
725
- schema_version: 1,
726
- min_seq: 0,
727
- max_seq: foldEnd,
728
- collection: collectionName,
729
- docs: Array.from(base.entries()).toSorted(([a], [b]) => {
730
- if (a < b) return -1;
731
- if (a > b) return 1;
732
- return 0;
733
- }).map(([id, body]) => ({
734
- _id: id,
735
- body
736
- }))
737
- });
738
- if (bodyBytes.byteLength > ceilingBytes || base.size > ceilingEntries) {
739
- ctxMetrics$2().counter("db.compaction.deferred_total", 1, {
740
- collection: collectionName,
741
- dimension: bodyBytes.byteLength > ceilingBytes ? "bytes" : "rows"
742
- });
743
- return {
744
- written: false,
745
- skippedReason: "deferred",
746
- deferred: true,
747
- previousSnapshotKey: current.snapshot,
748
- logSeqStartBefore,
749
- logSeqStartAfter: logSeqStartBefore,
750
- entriesFolded: 0
751
- };
752
- }
753
- const newKey = snapshotKey(collectionPrefix, 0, foldEnd, await snapshotHash(bodyBytes));
754
- const putOpts = {
755
- contentType: APPLICATION_JSON$1,
756
- ...options.signal !== void 0 && { signal: options.signal }
757
- };
758
- await storage.put(newKey, bodyBytes, putOpts);
759
- const entriesFolded = foldEnd - logSeqStartBefore;
760
- const nextBody = encodeJsonBytes({
761
- ...current,
762
- snapshot: newKey,
763
- log_seq_start: foldEnd,
764
- tail_hint: Math.max(current.tail_hint, discoveredTail),
765
- snapshot_bytes: bodyBytes.byteLength,
766
- snapshot_rows: base.size,
767
- mean_entry_bytes: entriesFolded > 0 ? Math.round(foldedSliceBytes / entriesFolded) : current.mean_entry_bytes ?? 0
768
- });
769
- const casOpts = {
770
- ifMatch: baseEtag,
771
- contentType: APPLICATION_JSON$1,
772
- ...options.signal !== void 0 && { signal: options.signal }
773
- };
774
- try {
775
- await storage.put(currentJsonKey, nextBody, casOpts);
776
- } catch (error) {
777
- if (isCasConflict(error)) {
778
- ctxMetrics$2().counter("db.compaction.cas_lost_total", 1, { collection: collectionName });
779
- return {
780
- written: false,
781
- skippedReason: "cas-lost",
782
- previousSnapshotKey: current.snapshot,
783
- newSnapshotKey: newKey,
784
- logSeqStartBefore,
785
- logSeqStartAfter: logSeqStartBefore,
786
- entriesFolded: foldEnd - logSeqStartBefore
787
- };
788
- }
789
- throw error;
790
- }
791
- const metrics = ctxMetrics$2();
792
- metrics.histogram("db.compact.entries_folded", entriesFolded, { collection: collectionName });
793
- metrics.gauge("db.manifest.lag_window_depth", discoveredTail - foldEnd, { collection: collectionName });
794
- return {
795
- written: true,
796
- previousSnapshotKey: current.snapshot,
797
- newSnapshotKey: newKey,
798
- logSeqStartBefore,
799
- logSeqStartAfter: foldEnd,
800
- entriesFolded
801
- };
802
- };
803
- /**
804
- * `true` when an `If-Match` CAS guard lost. Every in-tree
805
- * {@link Storage} impl surfaces a lost CAS as
806
- * `BaerlyError{code:"Conflict"}`.
807
- */
808
- const isCasConflict = (err) => err instanceof BaerlyError && err.code === "Conflict";
809
- //#endregion
810
- //#region ../server/src/gc.ts
811
- /**
812
- * GC mark + sweep.
813
- *
814
- * `runGc` is a single-pass garbage collector that:
815
- * 1. Reads `current.json` (and bootstraps `gc/pending.json` on first
816
- * run).
817
- * 2. Marks new orphan candidates by LISTing the three artifact
818
- * prefixes — log, snapshot, content — and classifying each key.
819
- * 3. Sweeps any already-pending candidate whose `due_at` has passed.
820
- * 4. CAS-writes the updated `gc/pending.json`.
821
- *
822
- * Two-phase by design: every candidate sits in `gc/pending.json` for a
823
- * grace period (default 7 days, see {@link GC_GRACE_PERIOD_MILLIS})
824
- * before it is deleted. The grace bounds the worst plausible
825
- * writer-retry window — a paused-process writer that resumes hours
826
- * later still finds its idempotency anchor on the bucket.
827
- *
828
- * Idempotent: same input bucket state ⇒ same `pending.json` output.
829
- * Unbounded by default — the run marks and sweeps the entire eligible
830
- * set in one pass. Callers on the Cloudflare 50-subrequest free-tier
831
- * budget opt INTO caps via the `CLOUDFLARE_FREE_TIER` profile's
832
- * `gc.maxMarksPerRun` / `maxSweepsPerRun` knobs (`InternalRunGcOptions`,
833
- * not on the public `RunGcOptions`).
834
- *
835
- * Three categories of orphan:
836
- * - `stale-log`: `<collectionPrefix>/log/<seq>.json` with
837
- * `seq < log_seq_start`. After `compact()` folds these into a
838
- * snapshot, they're unreferenced.
839
- * - `orphan-snapshot`: a `<collectionPrefix>/snapshot/L<n>/...` key not
840
- * equal to `current.snapshot`. Each compactor run replaces the
841
- * pointer; the prior file becomes unreferenced.
842
- * - `orphan-content`: `<collectionPrefix>/content/<sha>.json` whose
843
- * 32-hex truncated-SHA-256 hash is not in the live content-hash
844
- * set (computed by hashing every live `entry.after` post-image —
845
- * the same hash the writer's step 4 produces). Surfaces writer
846
- * crashes between the content PUT and the log-entry PUT. Because
847
- * content keys are hash-named (random lex order) and live content
848
- * is never deleted, a bounded pass cannot rely on deletion to
849
- * advance its LIST window the way `stale-log` does — so the
850
- * orphan-content LIST carries a persisted rotation cursor
851
- * (`content_scan_cursor` in `gc/pending.json`): each bounded pass
852
- * resumes `startAfter` the prior pass's last examined key and wraps
853
- * at end-of-keyspace, so the whole `content/` keyspace is swept
854
- * over a rotation within the per-pass `maxMarksPerRun` budget.
855
- *
856
- * CAS-lost on `gc/pending.json` is non-fatal: the DELETEs already
857
- * issued are durable, so we return a successful result and the next
858
- * pass will pick up any work this pass lost.
859
- */
860
- const ctxMetrics$1 = () => getCurrentContext()?.recorder ?? noopMetricsRecorder;
861
- const DEFAULT_MAX_MARKS = Number.MAX_SAFE_INTEGER;
862
- const DEFAULT_MAX_SWEEPS = Number.MAX_SAFE_INTEGER;
863
- /**
864
- * Single GC pass — mark new orphans, sweep due-elapsed candidates,
865
- * persist via CAS-update on `gc/pending.json`.
866
- *
867
- * Returns immediately if `current.json` is missing — there's nothing
868
- * to do until a writer has bootstrapped the collection.
869
- *
870
- * @example
871
- * ```ts
872
- * import { runGc } from "@gusto/baerly-storage";
873
- *
874
- * const r = await runGc({ storage, currentJsonKey });
875
- * console.log(`marked ${r.marked.stale_log} stale logs, swept ${r.swept}`);
876
- * ```
877
- */
878
- const runGc = async (args, options = {}) => {
879
- const { storage, currentJsonKey } = args;
880
- const internal = options;
881
- const grace = internal.graceMillis ?? 6048e5;
882
- const maxMarks = internal.maxMarksPerRun ?? DEFAULT_MAX_MARKS;
883
- const maxSweeps = internal.maxSweepsPerRun ?? DEFAULT_MAX_SWEEPS;
884
- const now = internal.now ?? (() => /* @__PURE__ */ new Date());
885
- const collectionPrefix = currentJsonKey.slice(0, currentJsonKey.lastIndexOf("/"));
886
- const collectionName = collectionPrefix.slice(collectionPrefix.lastIndexOf("/") + 1);
887
- const gcPendingKey = `${collectionPrefix}/gc/pending.json`;
888
- const signal = options.signal;
889
- const signalOpts = signal !== void 0 ? { signal } : void 0;
890
- const cur = await readCurrentJson(storage, currentJsonKey, signalOpts);
891
- if (cur === null) return {
892
- marked: {
893
- stale_log: 0,
894
- orphan_snapshot: 0,
895
- orphan_content: 0
896
- },
897
- swept: 0,
898
- pendingDepth: 0
899
- };
900
- const current = cur.json;
901
- const logSeqStart = logSeqStartOf(current);
902
- let pending = await readGcPending(storage, gcPendingKey, signalOpts);
903
- if (pending === null) {
904
- const initial = {
905
- schema_version: 1,
906
- candidates: [],
907
- last_swept_at: ""
908
- };
909
- try {
910
- pending = await createGcPending(storage, gcPendingKey, initial, signalOpts);
911
- } catch (error) {
912
- if (error instanceof BaerlyError && error.code === "Conflict") {
913
- pending = await readGcPending(storage, gcPendingKey, signalOpts);
914
- if (pending === null) throw error;
915
- } else throw error;
916
- }
917
- }
918
- const known = new Set(pending.json.candidates.map((c) => c.key));
919
- const newCandidates = [];
920
- let markedStaleLog = 0;
921
- if (logSeqStart > 0) for await (const entry of listBounded(storage, `${collectionPrefix}/log/`, maxMarks, signal)) {
922
- if (markedStaleLog >= maxMarks) break;
923
- const seq = parseSeqFromLogKey(entry.key);
924
- if (seq === null || seq >= logSeqStart) continue;
925
- if (known.has(entry.key)) continue;
926
- newCandidates.push({
927
- key: entry.key,
928
- due_at: computeDueAt(entry, now, grace),
929
- reason: "stale-log"
930
- });
931
- markedStaleLog++;
932
- }
933
- let markedOrphanSnapshot = 0;
934
- for await (const entry of listBounded(storage, `${collectionPrefix}/snapshot/`, maxMarks, signal)) {
935
- if (markedOrphanSnapshot >= maxMarks) break;
936
- if (entry.key === current.snapshot) continue;
937
- if (known.has(entry.key)) continue;
938
- newCandidates.push({
939
- key: entry.key,
940
- due_at: computeDueAt(entry, now, grace),
941
- reason: "orphan-snapshot"
942
- });
943
- markedOrphanSnapshot++;
944
- }
945
- const liveHashes = await collectLiveContentHashes(storage, collectionPrefix, collectionName, current, logSeqStart, signal);
946
- const cursor = pending.json.content_scan_cursor;
947
- const contentPrefix = `${collectionPrefix}/content/`;
948
- let markedOrphanContent = 0;
949
- let examinedThisPass = 0;
950
- let lastExaminedKey;
951
- const listOpts = {
952
- maxKeys: maxMarks,
953
- ...cursor !== void 0 && { startAfter: cursor },
954
- ...signal !== void 0 && { signal }
955
- };
956
- for await (const entry of storage.list(contentPrefix, listOpts)) {
957
- examinedThisPass++;
958
- lastExaminedKey = entry.key;
959
- const hash = parseHashFromContentKey(entry.key);
960
- if (hash === null || liveHashes.has(hash)) continue;
961
- if (known.has(entry.key)) continue;
962
- newCandidates.push({
963
- key: entry.key,
964
- due_at: computeDueAt(entry, now, grace),
965
- reason: "orphan-content"
966
- });
967
- markedOrphanContent++;
968
- }
969
- const nextContentCursor = examinedThisPass < maxMarks ? void 0 : lastExaminedKey;
970
- const nowMs = now().getTime();
971
- const sweepCandidates = [...pending.json.candidates, ...newCandidates];
972
- const toSweep = [];
973
- const remaining = [];
974
- for (const cand of sweepCandidates) if (toSweep.length < maxSweeps && Date.parse(cand.due_at) <= nowMs) toSweep.push(cand);
975
- else remaining.push(cand);
976
- await Promise.all(toSweep.map((c) => storage.delete(c.key, signalOpts)));
977
- const sweptKeys = new Set(toSweep.map((c) => c.key));
978
- const lastSweptAt = toSweep.length > 0 ? now().toISOString() : "";
979
- const markedSummary = {
980
- stale_log: markedStaleLog,
981
- orphan_snapshot: markedOrphanSnapshot,
982
- orphan_content: markedOrphanContent
983
- };
984
- let pendingDepth;
985
- try {
986
- pendingDepth = (await casUpdateGcPending(storage, gcPendingKey, (latest) => mergeGcPending(latest, {
987
- sweptKeys,
988
- newCandidates,
989
- lastSweptAt,
990
- nextContentCursor,
991
- maxCandidates: GC_MAX_PENDING_CANDIDATES
992
- }), signalOpts)).json.candidates.length;
993
- } catch (error) {
994
- if (error instanceof BaerlyError && error.code === "Conflict") pendingDepth = remaining.length;
995
- else throw error;
996
- }
997
- const labels = { collection: collectionName };
998
- const metrics = ctxMetrics$1();
999
- metrics.gauge("db.orphan.candidate_count", pendingDepth, labels);
1000
- metrics.gauge("db.gc.entries_swept_per_second", toSweep.length, labels);
1001
- if (toSweep.length > 0) {
1002
- const byReason = /* @__PURE__ */ new Map();
1003
- for (const c of toSweep) byReason.set(c.reason, (byReason.get(c.reason) ?? 0) + 1);
1004
- for (const [reason, count] of byReason) metrics.counter("db.gc.swept_total", count, {
1005
- collection: collectionName,
1006
- reason
1007
- });
1008
- }
1009
- return {
1010
- marked: markedSummary,
1011
- swept: toSweep.length,
1012
- pendingDepth
1013
- };
1014
- };
1015
- /**
1016
- * `Storage.list` with a hard ceiling — bounds the I/O cost of a
1017
- * single pass when a runaway prefix has accumulated many keys.
1018
- */
1019
- const listBounded = async function* (storage, prefix, cap, signal) {
1020
- let yielded = 0;
1021
- const opts = signal !== void 0 ? { signal } : void 0;
1022
- for await (const entry of storage.list(prefix, opts)) {
1023
- if (yielded >= cap) return;
1024
- yield entry;
1025
- yielded++;
1026
- }
1027
- };
1028
- /**
1029
- * Parse `<...>/log/<seq>.json` and return `seq`. Returns `null` on
1030
- * any shape that doesn't look like a log entry key — defensively
1031
- * tolerates an unrelated key under the log prefix.
1032
- */
1033
- const parseSeqFromLogKey = (key) => {
1034
- const match = /\/log\/(\d+)\.json$/.exec(key);
1035
- if (match === null) return null;
1036
- const n = Number.parseInt(match[1], 10);
1037
- return Number.isFinite(n) && n >= 0 ? n : null;
1038
- };
1039
- /**
1040
- * Parse `<...>/content/<sha-32>.json` and return the 32-hex hash.
1041
- * Returns `null` on any shape that doesn't match the writer's
1042
- * `versionFromContent`-produced key format.
1043
- */
1044
- const parseHashFromContentKey = (key) => {
1045
- const match = /\/content\/([0-9a-f]{32})\.json$/.exec(key);
1046
- return match === null ? null : match[1];
1047
- };
1048
- /**
1049
- * Anchor `due_at` to `lastModified` when the storage adapter
1050
- * surfaces it; fall back to the injected `now` so a Storage impl
1051
- * without a server clock still GCs after `grace` from the mark
1052
- * moment.
1053
- */
1054
- const computeDueAt = (entry, now, graceMs) => {
1055
- const base = entry.lastModified ?? now();
1056
- return new Date(base.getTime() + graceMs).toISOString();
1057
- };
1058
- /**
1059
- * Build the live content-hash set. The set covers every live
1060
- * post-image: every `entry.after` in `[logSeqStart, tail_hint)` plus
1061
- * every row body in the current snapshot.
1062
- *
1063
- * A snapshot read that throws (corrupt body, hash mismatch) is
1064
- * tolerated — the worst-case effect is missing some live hashes,
1065
- * which could mark a live content blob as orphan. The grace period
1066
- * absorbs the false-positive: a retry that re-PUTs the same hash
1067
- * recreates the key before the sweep deletes it.
1068
- */
1069
- const collectLiveContentHashes = async (storage, collectionPrefix, collectionName, current, logSeqStart, signal) => {
1070
- const hashes = /* @__PURE__ */ new Set();
1071
- const getOpts = signal !== void 0 ? { signal } : void 0;
1072
- const { tail } = await probeTailFrom(storage, collectionPrefix, Math.max(logSeqStart, current.tail_hint), { signal });
1073
- const ingestLogEntry = async (s) => {
1074
- const got = await storage.get(logObjectKey(collectionPrefix, s), getOpts);
1075
- if (got === null) return;
1076
- let entry;
1077
- try {
1078
- entry = decodeJsonBytes(got.body);
1079
- } catch {
1080
- return;
1081
- }
1082
- if (entry.after === void 0) return;
1083
- const bodyBytes = encodeJsonBytes(entry.after);
1084
- hashes.add(await versionFromContent(bodyBytes));
1085
- };
1086
- for (let chunkStart = logSeqStart; chunkStart < tail; chunkStart += 16) {
1087
- signal?.throwIfAborted();
1088
- const chunkEnd = Math.min(chunkStart + 16, tail);
1089
- const chunk = [];
1090
- for (let s = chunkStart; s < chunkEnd; s++) chunk.push(ingestLogEntry(s));
1091
- await Promise.all(chunk);
1092
- }
1093
- if (current.snapshot !== null) try {
1094
- const map = await loadSnapshotAsMap(storage, current.snapshot, collectionName, signal);
1095
- const rowReads = [];
1096
- for (const body of map.values()) rowReads.push((async () => {
1097
- const bytes = encodeJsonBytes(body);
1098
- hashes.add(await versionFromContent(bytes));
1099
- })());
1100
- await Promise.all(rowReads);
1101
- } catch {}
1102
- return hashes;
1103
- };
1104
- //#endregion
1105
- //#region ../server/src/rebuild-index.ts
1106
- /**
1107
- * Idempotent reconciliation for one secondary index.
1108
- *
1109
- * {@link rebuildIndex} folds the live `(snapshot, log_tail)` of a
1110
- * collection into the doc set the writer's index emission would
1111
- * have produced, then PUTs every missing index key and DELETEs every
1112
- * orphaned one. Same-key zero-byte PUTs are no-ops (the entries are
1113
- * content-addressed by composition); same-key DELETEs are
1114
- * contractually idempotent.
1115
- *
1116
- * Invariants:
1117
- *
1118
- * - **Re-running on a healthy index is a no-op.** `added = 0`,
1119
- * `removed = 0`.
1120
- * - **Re-running after a crashed mid-commit** reconciles toward
1121
- * the live `current.json` view — orphans deleted, missing keys
1122
- * PUT.
1123
- * - **Re-running while writes are in flight** is safe up to a
1124
- * race window: a write that lands during the rebuild may
1125
- * produce a transient "orphan" the rebuild sweeps, which the
1126
- * next live write then re-PUTs. The race converges on the next
1127
- * commit.
1128
- *
1129
- * The function reads the same fold the writer / reader use
1130
- * (snapshot via {@link loadSnapshotAsMap}; log tail by direct
1131
- * `get(<logPrefix>/log/<seq>.json)`) so it MUST agree with the
1132
- * writer on the live doc set by construction.
1133
- *
1134
- * @see ./indexes.ts — `IndexDefinition`, `allIndexKeysFor`,
1135
- * `indexKeyPrefix`.
1136
- * @see ./writer.ts — the hybrid index emission path this command
1137
- * reconciles.
1138
- */
1139
- const EMPTY_BODY = /* @__PURE__ */ new Uint8Array(0);
1140
- const APPLICATION_JSON = "application/json";
1141
- /**
1142
- * Idempotently reconcile one secondary index for one collection.
1143
- *
1144
- * @param storage Storage handle (any in-tree `Storage`).
1145
- * @param currentJsonKey The collection's `current.json` key.
1146
- * @param def The index to reconcile. Single-field today;
1147
- * composite definitions are accepted by the
1148
- * key encoder but the read path only consults
1149
- * single-field keys.
1150
- * @param opts Optional knobs — see {@link RebuildIndexOptions}.
1151
- * Strictly additive: existing positional-arg
1152
- * callers compile and behave unchanged when
1153
- * omitted.
1154
- *
1155
- * @throws BaerlyError code="InvalidResponse" — `current.json` missing.
1156
- * @throws BaerlyError code="Internal" — protocol-invariant
1157
- * violation (snapshot hash mismatch, missing log entry inside
1158
- * `[log_seq_start, tail_hint)`).
1159
- */
1160
- const rebuildIndex = async (storage, currentJsonKey, def, opts = {}) => {
1161
- const read = await readCurrentJson(storage, currentJsonKey);
1162
- if (read === null) throw new BaerlyError("InvalidResponse", `rebuildIndex: current.json missing at ${JSON.stringify(currentJsonKey)}`);
1163
- const lastSlash = currentJsonKey.lastIndexOf("/");
1164
- if (lastSlash < 0) throw new BaerlyError("InvalidResponse", `rebuildIndex: currentJsonKey ${JSON.stringify(currentJsonKey)} must contain "/"`);
1165
- const collectionPrefix = currentJsonKey.slice(0, lastSlash);
1166
- const collection = collectionPrefix.slice(collectionPrefix.lastIndexOf("/") + 1);
1167
- const logSeqStart = logSeqStartOf(read.json);
1168
- const hint = read.json.tail_hint;
1169
- const live = read.json.snapshot === null ? /* @__PURE__ */ new Map() : await loadSnapshotAsMap(storage, read.json.snapshot, collection);
1170
- foldLogEntriesOnto(live, await walkLogRange(storage, collectionPrefix, logSeqStart, hint), { collection });
1171
- const probeOpts = opts.signal !== void 0 ? { signal: opts.signal } : void 0;
1172
- foldLogEntriesOnto(live, (await probeTailFrom(storage, collectionPrefix, Math.max(logSeqStart, hint), probeOpts)).entries, { collection });
1173
- const expected = /* @__PURE__ */ new Set();
1174
- for (const [docId, body] of live) for (const k of allIndexKeysFor(collectionPrefix, [def], body, docId)) expected.add(k);
1175
- const actual = /* @__PURE__ */ new Set();
1176
- const listOpts = {};
1177
- if (opts.signal !== void 0) listOpts.signal = opts.signal;
1178
- for await (const entry of storage.list(indexKeyPrefix(collectionPrefix, def.name), listOpts)) actual.add(entry.key);
1179
- const dryRun = opts.dryRun === true;
1180
- let added = 0;
1181
- let removed = 0;
1182
- let kept = 0;
1183
- for (const k of expected) {
1184
- if (actual.has(k)) {
1185
- kept += 1;
1186
- continue;
1187
- }
1188
- if (dryRun) {
1189
- added += 1;
1190
- continue;
1191
- }
1192
- try {
1193
- await storage.put(k, EMPTY_BODY, {
1194
- ifNoneMatch: "*",
1195
- contentType: APPLICATION_JSON
1196
- });
1197
- added += 1;
1198
- } catch (error) {
1199
- if (error instanceof BaerlyError && error.code === "Conflict") kept += 1;
1200
- else throw error;
1201
- }
1202
- }
1203
- for (const k of actual) {
1204
- if (expected.has(k)) continue;
1205
- if (dryRun) {
1206
- removed += 1;
1207
- continue;
1208
- }
1209
- await storage.delete(k);
1210
- removed += 1;
1211
- }
1212
- return {
1213
- added,
1214
- removed,
1215
- kept
1216
- };
1217
- };
1218
- //#endregion
1219
- //#region ../server/src/maintenance.ts
1220
- /**
1221
- * `runScheduledMaintenance` — single-pass compose of `compact()` and
1222
- * `runGc()` over one collection. Designed to fit a single Cloudflare
1223
- * Cron Trigger invocation's 50-subrequest free-tier budget when
1224
- * called with the {@link CLOUDFLARE_FREE_TIER} profile (which the
1225
- * caller pairs with even/odd-minute alternation between compact and
1226
- * GC ticks); unbounded on Node.
1227
- *
1228
- * Single-attempt: returns the combined result. The caller (cron
1229
- * handler) is responsible for scheduling the next invocation; this
1230
- * function does not loop or retry. `compact()` and `runGc()` are
1231
- * already CAS-protected single-attempts — a restart safely retries
1232
- * next tick.
1233
- *
1234
- * Callers that want only one phase to fire this tick should invoke
1235
- * the underlying primitive directly (`compact()` or `runGc()` from
1236
- * this same module's re-exports). The even/odd-minute CF cron
1237
- * pattern uses exactly that.
1238
- */
1239
- const ctxMetrics = () => getCurrentContext()?.recorder ?? noopMetricsRecorder;
1240
- const profileToScheduledOptions = (profile) => ({
1241
- compact: {
1242
- maxEntriesPerRun: profile.maxFoldEntriesPerPass,
1243
- minEntriesToCompact: 50
1244
- },
1245
- gc: {
1246
- maxMarksPerRun: profile.gcMaxMarks,
1247
- maxSweepsPerRun: profile.gcMaxSweeps
1248
- }
1249
- });
1250
- profileToScheduledOptions(MAINTENANCE_PROFILE_CF_FREE);
1251
- profileToScheduledOptions(MAINTENANCE_PROFILE_CF_PAID);
1252
- /**
1253
- * Floor-based GC-cadence boundary crossing. Every commit advances the
1254
- * writer-observed tail by one logical slot; `tail_hint` remains a
1255
- * lower bound and may be refreshed later by maintenance. The floor test
1256
- * trips on any interval boundary inside `(prevSeq, nextSeq]`, so it
1257
- * stays correct whether the observed/probed tail advances by one or
1258
- * catches up by a larger step.
1259
- */
1260
- const crossesGcBoundary = (prevSeq, nextSeq, interval) => Math.floor(prevSeq / interval) !== Math.floor(nextSeq / interval);
1261
- /**
1262
- * Derived live-tail byte size — the ratio TRIGGER input that replaces the
1263
- * formerly-stored exact byte count. `(observedTail − log_seq_start) ×
1264
- * mean_entry_bytes`. `observedTail` is a param so write-tick callers can
1265
- * pass the writer-observed tail and scheduled callers can pass a
1266
- * probe-discovered true tail. Cold-start (no mean yet) falls back to
1267
- * {@link MAINTENANCE_COLD_START_ENTRY_BYTES}, never 0 (see that constant).
1268
- * TRIGGER-only — structurally barred from `foldViable` (the exact-bytes CPU-kill
1269
- * ceiling).
1270
- */
1271
- const estimateTailBytes = (current, observedTail) => Math.max(0, observedTail - current.log_seq_start) * (current.mean_entry_bytes ?? 128);
1272
- /**
1273
- * The cheap DISPATCH gate the writer calls after a commit — zero
1274
- * storage ops; it reads the post-commit {@link CurrentJson} already in
1275
- * scope. Ratio-OR-boundary, WITHOUT the entry floor (the floor is part
1276
- * of the fold-trigger Gate 1 checked inside {@link runBoundedMaintenance}).
1277
- * Returning `false` lets the writer skip the dispatch entirely. Ratio
1278
- * numerator is the DERIVED {@link estimateTailBytes};
1279
- * `observedTail` threads from the caller (the writer's in-memory observed
1280
- * tail `seq+1` under single-write commit). Both the boundary check and the
1281
- * ratio key off `observedTail`, since the stored `tail_hint` is now only a
1282
- * non-authoritative lower bound (compactor-advanced).
1283
- */
1284
- const shouldFireMaintenance = (current, prevSeq, gcInterval, observedTail) => crossesGcBoundary(prevSeq, observedTail, gcInterval) || estimateTailBytes(current, observedTail) / Math.max(current.snapshot_bytes, 65536) >= 1;
1285
- /**
1286
- * The write-tick maintenance runner: a bounded, single-attempt
1287
- * composition of {@link compact} and {@link runGc} for one collection,
1288
- * sized to fit a CPU-killable Cloudflare free-tier isolate by default.
1289
- *
1290
- * INVARIANT: a {@link MaintenanceProfile} changes only maintenance rate +
1291
- * defer threshold — never data/API/query/wire/correctness; reads stay pure.
1292
- * See `maintenance-profile-equivalence.test.ts`.
1293
- *
1294
- * Never throws — the write-tick caller must never see a maintenance
1295
- * failure. Expected signals (CAS contention, an over-ceiling deferral)
1296
- * are swallowed quietly; unexpected throws bump
1297
- * `db.maintenance.unexpected_error_total`, log a stack, and are
1298
- * swallowed.
1299
- *
1300
- * Control flow (fold-priority with a stateless GC-starvation guard):
1301
- * 0. `disabled` → skip fold/GC, but still allow the rate-limited
1302
- * tail_hint refresh that bounds read/write forward-probes.
1303
- * 1. Read `current.json` once.
1304
- * 2. Hard-GC starvation boundary (`"single"` only) → GC slice, skip fold.
1305
- * 3. Gate 1 (ratio AND entry floor) trips → fold if viable, else
1306
- * defer (and metric); on `"single"` a successful fold attempt is
1307
- * this tick's one phase.
1308
- * 4. Otherwise (or on `"both"`) → GC iff the cadence boundary crossed.
1309
- */
1310
- const runBoundedMaintenance = async (args, options) => {
1311
- const { storage, currentJsonKey, prevSeq } = args;
1312
- const profile = options?.profile ?? MAINTENANCE_PROFILE_CF_FREE;
1313
- const { maxFoldEntriesPerPass, gcMaxMarks, gcMaxSweeps, gcInterval } = profile;
1314
- const minEntriesToCompact = options?.minEntriesToCompact ?? 50;
1315
- const phasesPerTick = options?.phasesPerTick ?? "single";
1316
- const signal = options?.signal;
1317
- const C = args.maxFoldBytes ?? profile.maxFoldBytes;
1318
- const E = profile.maxFoldRows;
1319
- const collectionPrefix = currentJsonKey.slice(0, currentJsonKey.lastIndexOf("/"));
1320
- const collection = collectionPrefix.slice(collectionPrefix.lastIndexOf("/") + 1);
1321
- const gcOpts = {
1322
- maxMarksPerRun: gcMaxMarks,
1323
- maxSweepsPerRun: gcMaxSweeps,
1324
- ...signal !== void 0 && { signal },
1325
- ...options?.gcGraceMillis !== void 0 && { graceMillis: options.gcGraceMillis },
1326
- ...options?.now !== void 0 && { now: options.now }
1327
- };
1328
- try {
1329
- const read = await readCurrentJson(storage, currentJsonKey, signal !== void 0 ? { signal } : void 0);
1330
- if (read === null) return;
1331
- const current = read.json;
1332
- const snapshotBytes = current.snapshot_bytes;
1333
- const snapshotRows = current.snapshot_rows;
1334
- const logSeqStart = current.log_seq_start;
1335
- const probeFloor = Math.max(logSeqStart, current.tail_hint);
1336
- let nextSeq;
1337
- if (args.observedTail !== void 0) nextSeq = Math.max(args.observedTail, probeFloor);
1338
- else nextSeq = (await probeTailFrom(storage, collectionPrefix, probeFloor, signal !== void 0 ? { signal } : void 0)).tail;
1339
- const gate1 = estimateTailBytes(current, nextSeq) / Math.max(snapshotBytes, 65536) >= 1 && nextSeq - logSeqStart >= minEntriesToCompact;
1340
- const foldViable = snapshotBytes <= C && snapshotRows + maxFoldEntriesPerPass <= E;
1341
- const gcDue = crossesGcBoundary(prevSeq, nextSeq, gcInterval);
1342
- const refreshTailHintIfNeeded = async () => {
1343
- if (nextSeq - current.tail_hint < 128) return;
1344
- try {
1345
- await casUpdateCurrentJson(storage, currentJsonKey, (c) => ({
1346
- ...c,
1347
- tail_hint: Math.max(c.tail_hint, nextSeq)
1348
- }), signal !== void 0 ? { signal } : void 0);
1349
- } catch {}
1350
- };
1351
- if (args.disabled === true) {
1352
- await refreshTailHintIfNeeded();
1353
- return;
1354
- }
1355
- const hardGc = crossesGcBoundary(prevSeq, nextSeq, gcInterval * 4);
1356
- if (phasesPerTick === "single" && hardGc) {
1357
- await runGc({
1358
- storage,
1359
- currentJsonKey
1360
- }, gcOpts);
1361
- return;
1362
- }
1363
- if (gate1) if (foldViable) {
1364
- await compact({
1365
- storage,
1366
- currentJsonKey
1367
- }, {
1368
- maxEntriesPerRun: maxFoldEntriesPerPass,
1369
- minEntriesToCompact,
1370
- ceilingBytes: C,
1371
- ceilingEntries: E,
1372
- knownTail: nextSeq,
1373
- ...signal !== void 0 && { signal }
1374
- });
1375
- if (phasesPerTick === "single") return;
1376
- } else {
1377
- ctxMetrics().counter("db.compaction.deferred_total", 1, {
1378
- collection,
1379
- dimension: snapshotBytes > C ? "bytes" : "rows"
1380
- });
1381
- await refreshTailHintIfNeeded();
1382
- if (nextSeq - (current.last_warned_seq ?? 0) >= 1e3) {
1383
- console.warn(`baerly-storage: collection "${collection}" is deferring compaction — its snapshot exceeds the fold ceiling (${snapshotBytes > C ? `${C} bytes` : `${E} rows`}), so the tail keeps growing and read amplification will climb. The dataset has outgrown the maintenance envelope. On paid Cloudflare / Node you can raise BAERLY_MAINTENANCE_MAX_FOLD_BYTES — but on Cloudflare a cap above what a single isolate can fold makes folds get CPU-killed mid-flight and silently not land (no clean metric — watch snapshot age / object count); see docs/about/graduation.md. Otherwise, move to a database service (D1 / Postgres).`);
1384
- try {
1385
- await casUpdateCurrentJson(storage, currentJsonKey, (c) => ({
1386
- ...c,
1387
- last_warned_seq: nextSeq
1388
- }), signal !== void 0 ? { signal } : void 0);
1389
- } catch {}
1390
- }
1391
- }
1392
- if (gcDue) await runGc({
1393
- storage,
1394
- currentJsonKey
1395
- }, gcOpts);
1396
- } catch (error) {
1397
- if (error instanceof BaerlyError && error.code === "Conflict") return;
1398
- ctxMetrics().counter("db.maintenance.unexpected_error_total", 1, { collection });
1399
- console.error(error);
1400
- }
1401
- };
1402
- /**
1403
- * Default maintenance dispatcher: run the task inline and await it.
1404
- * Adapters that can keep running after the response (Cloudflare:
1405
- * `ctx.waitUntil`) override this with a fire-and-forget variant that
1406
- * returns `void`.
1407
- */
1408
- const dispatchInlineAwaited = (task) => task();
1409
- //#endregion
1410
- export { getCurrentContext as a, noopMetricsRecorder as c, rebuildIndex as i, versionFromContent as l, runBoundedMaintenance as n, allIndexKeysFor as o, shouldFireMaintenance as r, validateIndexDefinition as s, dispatchInlineAwaited as t };
1411
-
1412
- //# sourceMappingURL=maintenance-fEi-UZ2o.js.map