@gusto/baerly-storage 0.1.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 (115) hide show
  1. package/README.md +97 -0
  2. package/dist/API.md +850 -0
  3. package/dist/app-config-Cb5dO2s9.d.ts +480 -0
  4. package/dist/app-config.d.ts +2 -0
  5. package/dist/app-config.js +8 -0
  6. package/dist/app-config.js.map +1 -0
  7. package/dist/auth.d.ts +237 -0
  8. package/dist/auth.js +1335 -0
  9. package/dist/auth.js.map +1 -0
  10. package/dist/baerly.js +761 -0
  11. package/dist/baerly.js.map +1 -0
  12. package/dist/bucket-uri-BrDEYvzy.js +4922 -0
  13. package/dist/bucket-uri-BrDEYvzy.js.map +1 -0
  14. package/dist/chunk-EAsCxrDo.js +14 -0
  15. package/dist/client-BLf3Ae5s.d.ts +233 -0
  16. package/dist/client-react.d.ts +131 -0
  17. package/dist/client-react.js +559 -0
  18. package/dist/client-react.js.map +1 -0
  19. package/dist/client.d.ts +4 -0
  20. package/dist/client.js +160 -0
  21. package/dist/client.js.map +1 -0
  22. package/dist/cloudflare-CINJPKCW.js +911 -0
  23. package/dist/cloudflare-CINJPKCW.js.map +1 -0
  24. package/dist/cloudflare.d.ts +211 -0
  25. package/dist/cloudflare.js +445 -0
  26. package/dist/cloudflare.js.map +1 -0
  27. package/dist/config-Bsg8wgwo.js +198 -0
  28. package/dist/config-Bsg8wgwo.js.map +1 -0
  29. package/dist/context-Oj7ffwD-.js +187 -0
  30. package/dist/context-Oj7ffwD-.js.map +1 -0
  31. package/dist/cost-B1WiZxlf.js +203 -0
  32. package/dist/cost-B1WiZxlf.js.map +1 -0
  33. package/dist/current-json-BkatBzF7.js +252 -0
  34. package/dist/current-json-BkatBzF7.js.map +1 -0
  35. package/dist/db-D62JguBc.d.ts +336 -0
  36. package/dist/deploy-BB-wqbhf.js +83 -0
  37. package/dist/deploy-BB-wqbhf.js.map +1 -0
  38. package/dist/dev-banner-CWHIk8tH.d.ts +26 -0
  39. package/dist/dev-vite.d.ts +146 -0
  40. package/dist/dev-vite.js +223 -0
  41. package/dist/dev-vite.js.map +1 -0
  42. package/dist/dev.d.ts +3 -0
  43. package/dist/dev.js +2 -0
  44. package/dist/doctor-B8h9GCN9.js +331 -0
  45. package/dist/doctor-B8h9GCN9.js.map +1 -0
  46. package/dist/dump-BHo_sIMZ.js +116 -0
  47. package/dist/dump-BHo_sIMZ.js.map +1 -0
  48. package/dist/errors-DOdL95kK.js +58 -0
  49. package/dist/errors-DOdL95kK.js.map +1 -0
  50. package/dist/export-Dz2PZKSR.js +423 -0
  51. package/dist/export-Dz2PZKSR.js.map +1 -0
  52. package/dist/fsck-DEz9lyCy.js +293 -0
  53. package/dist/fsck-DEz9lyCy.js.map +1 -0
  54. package/dist/http-CjUO1Bec.js +1756 -0
  55. package/dist/http-CjUO1Bec.js.map +1 -0
  56. package/dist/http.d.ts +1619 -0
  57. package/dist/http.js +2 -0
  58. package/dist/index-BGC-ENnj.d.ts +1065 -0
  59. package/dist/index-BYv0hb8M.d.ts +1457 -0
  60. package/dist/index-BquQkhJi.d.ts +112 -0
  61. package/dist/index-COsQ-Mlz.d.ts +146 -0
  62. package/dist/index.d.ts +6 -0
  63. package/dist/index.js +6 -0
  64. package/dist/indexes-BXn7a06a.js +297 -0
  65. package/dist/indexes-BXn7a06a.js.map +1 -0
  66. package/dist/indexes-DwOXkn1Y.d.ts +22 -0
  67. package/dist/inspect-x02aFWnh.js +149 -0
  68. package/dist/inspect-x02aFWnh.js.map +1 -0
  69. package/dist/log-walk-DIru96UT.js +260 -0
  70. package/dist/log-walk-DIru96UT.js.map +1 -0
  71. package/dist/maintenance-Bn6ul9aV.js +758 -0
  72. package/dist/maintenance-Bn6ul9aV.js.map +1 -0
  73. package/dist/maintenance.d.ts +323 -0
  74. package/dist/maintenance.js +2 -0
  75. package/dist/node.d.ts +422 -0
  76. package/dist/node.js +2 -0
  77. package/dist/normalize-XWY25_sG.js +133 -0
  78. package/dist/normalize-XWY25_sG.js.map +1 -0
  79. package/dist/observability-2IDYRuZK.js +2333 -0
  80. package/dist/observability-2IDYRuZK.js.map +1 -0
  81. package/dist/observability.d.ts +3 -0
  82. package/dist/observability.js +3 -0
  83. package/dist/plan-Cs17VqjU.js +224 -0
  84. package/dist/plan-Cs17VqjU.js.map +1 -0
  85. package/dist/query-DcSbFLJt.js +1880 -0
  86. package/dist/query-DcSbFLJt.js.map +1 -0
  87. package/dist/rebuild-index-C5gTXryd.js +119 -0
  88. package/dist/rebuild-index-C5gTXryd.js.map +1 -0
  89. package/dist/rebuild-index-DwXM0WfA.js +104 -0
  90. package/dist/rebuild-index-DwXM0WfA.js.map +1 -0
  91. package/dist/request-BEF_OvMh.js +72 -0
  92. package/dist/request-BEF_OvMh.js.map +1 -0
  93. package/dist/restore-CbKVMMpm.js +847 -0
  94. package/dist/restore-CbKVMMpm.js.map +1 -0
  95. package/dist/shared-secret-BJdSwpgw.js +71 -0
  96. package/dist/shared-secret-BJdSwpgw.js.map +1 -0
  97. package/dist/snapshot-D7C4_FSl.js +71 -0
  98. package/dist/snapshot-D7C4_FSl.js.map +1 -0
  99. package/dist/snapshot-z_N9hpTe.js +917 -0
  100. package/dist/snapshot-z_N9hpTe.js.map +1 -0
  101. package/dist/src-Chafbw8r.js +522 -0
  102. package/dist/src-Chafbw8r.js.map +1 -0
  103. package/dist/src-DyET_VPP.js +6199 -0
  104. package/dist/src-DyET_VPP.js.map +1 -0
  105. package/dist/src-n0Te1r98.js +352 -0
  106. package/dist/src-n0Te1r98.js.map +1 -0
  107. package/dist/subcommand-BWs6K7zb.js +110 -0
  108. package/dist/subcommand-BWs6K7zb.js.map +1 -0
  109. package/dist/usage-RVUQMLop.js +339 -0
  110. package/dist/usage-RVUQMLop.js.map +1 -0
  111. package/dist/validate-DhH1lO8I.js +377 -0
  112. package/dist/validate-DhH1lO8I.js.map +1 -0
  113. package/dist/wire-izfGZDvr.js +7 -0
  114. package/dist/wire-izfGZDvr.js.map +1 -0
  115. package/package.json +189 -0
@@ -0,0 +1,847 @@
1
+ import { a as decodeJsonBytes, i as uuid, n as timestamp, o as encodeJsonBytes, r as countKey, t as parseBucketUri } from "./bucket-uri-BrDEYvzy.js";
2
+ import { a as logSeqStartOf, i as createCurrentJson, n as readLogEntry, o as readCurrentJson, r as walkLogRange } from "./log-walk-DIru96UT.js";
3
+ import { o as BaerlyError, r as emitSuccess } from "./baerly.js";
4
+ import { r as validateIndexDefinition, t as allIndexKeysFor } from "./indexes-BXn7a06a.js";
5
+ import { t as defineBaerlySubcommand } from "./subcommand-BWs6K7zb.js";
6
+ import { AsyncLocalStorage } from "node:async_hooks";
7
+ import { createInterface } from "node:readline";
8
+ //#region ../protocol/src/hashing.ts
9
+ /**
10
+ * Width of the {@link ContentVersionId} hex strings produced by
11
+ * {@link versionFromContent}. 32 hex chars = 128 bits, matching the
12
+ * information content of a v4 UUID. Collision probability with
13
+ * N=10⁹ writes is ~3 × 10⁻²⁰; ample for a content-addressed version id.
14
+ *
15
+ * @see docs/spec/log-entry-shape.md §"Content body layout"
16
+ */
17
+ const VERSION_HEX_LENGTH = 32;
18
+ /**
19
+ * Content-addressed {@link ContentVersionId}: SHA-256 of `body`,
20
+ * lowercase hex, truncated to {@link VERSION_HEX_LENGTH}. Same body
21
+ * bytes ⇒ same ContentVersionId — the property `Writer.commit`
22
+ * relies on for idempotent replay (a crash-recovery rewrite of the
23
+ * same logical value produces the same content key the manifest
24
+ * already referenced).
25
+ *
26
+ * Async because {@link crypto.subtle.digest} returns an `ArrayBuffer`
27
+ * via Promise. Workers and browsers both expose `crypto.subtle`
28
+ * synchronously enough that the await fits naturally in the write
29
+ * pipeline.
30
+ *
31
+ * @see docs/spec/log-entry-shape.md §"Content body layout"
32
+ */
33
+ const versionFromContent = async (body) => {
34
+ const view = new Uint8Array(body.byteLength);
35
+ view.set(body);
36
+ const digest = await crypto.subtle.digest("SHA-256", view);
37
+ const bytes = new Uint8Array(digest);
38
+ let hex = "";
39
+ for (let i = 0; i < bytes.length; i++) hex += bytes[i].toString(16).padStart(2, "0");
40
+ return hex.slice(0, VERSION_HEX_LENGTH);
41
+ };
42
+ //#endregion
43
+ //#region ../protocol/src/metrics.ts
44
+ /**
45
+ * No-op recorder. Safe default when no operator sink is wired —
46
+ * emission sites that read `getCurrentContext()?.recorder` fall
47
+ * back to this outside an active `runWithContext` scope.
48
+ */
49
+ const noopMetricsRecorder = {
50
+ counter: () => {},
51
+ gauge: () => {},
52
+ histogram: () => {}
53
+ };
54
+ //#endregion
55
+ //#region ../server/src/log-conflict-adoption.ts
56
+ /**
57
+ * Decide whether the entry already at `/log/<seq>.json` is the
58
+ * writer's own prior in-flight attempt and may be adopted. Pure
59
+ * function; no I/O. The caller performs the GET (when the log PUT
60
+ * surfaces 412) and passes the read-back body in `ctx.existing`.
61
+ *
62
+ * @see {@link AdoptionDecision} for the return shape.
63
+ * @see The soundness invariant in this module's header docstring.
64
+ */
65
+ const tryAdoptOwnSessionLogEntry = (ctx) => {
66
+ if (ctx.batchSize !== 1) return {
67
+ adopt: false,
68
+ reason: "batch"
69
+ };
70
+ if (ctx.existing.session !== ctx.self.session) return {
71
+ adopt: false,
72
+ reason: "foreign-session"
73
+ };
74
+ if (ctx.existing.seq !== ctx.self.seq) return {
75
+ adopt: false,
76
+ reason: "wrong-seq"
77
+ };
78
+ return {
79
+ adopt: true,
80
+ entry: ctx.existing
81
+ };
82
+ };
83
+ //#endregion
84
+ //#region ../server/src/observability/context.ts
85
+ /**
86
+ * Per-request observability context.
87
+ *
88
+ * One `ObservabilityContext` is created at the entry of each unit-of-
89
+ * work (HTTP request, maintenance tick, GC sweep, rebuild run) and
90
+ * carried through the call tree via {@link runWithContext} /
91
+ * {@link getCurrentContext}, which delegates to a single module-level
92
+ * `AsyncLocalStorage` instance.
93
+ *
94
+ * The context is intentionally tiny: an externally-set
95
+ * {@link request_id}, a high-resolution `started_at`, and a mutable
96
+ * {@link fields} bag used to accumulate canonical-line attributes
97
+ * during the unit's lifecycle.
98
+ *
99
+ * The context shape is `readonly` everywhere it can be — only the
100
+ * contents of `fields` are intended to mutate during a request. The
101
+ * {@link fields} map itself is not `readonly` because callers (the
102
+ * canonical-line emitter, middleware, the collection API once Dispatch
103
+ * 3+ wires it up) need to set entries.
104
+ *
105
+ * The context carries no sampling state — every unit-of-work emits
106
+ * one canonical line unconditionally; there is nothing to gate.
107
+ *
108
+ * ## Time source
109
+ *
110
+ * `started_at` uses `performance.now()` so durations can be
111
+ * computed without worrying about wall-clock skew (NTP step,
112
+ * leap-second smearing). `performance.now()` is part of both Node
113
+ * 18+ and the Workers Runtime; we don't fall back to `Date.now()`.
114
+ *
115
+ * @example
116
+ * ```ts
117
+ * const ctx = createObservabilityContext({});
118
+ * await runWithContext(ctx, async () => {
119
+ * const inner = getCurrentContext();
120
+ * inner?.fields.set("collection", "tickets");
121
+ * await doWork();
122
+ * });
123
+ * ```
124
+ */
125
+ /**
126
+ * Module-level slot. One instance per process — the Workers
127
+ * Runtime's `nodejs_compat` flag wires `node:async_hooks` to a
128
+ * per-request scope, so cross-request bleed is impossible there.
129
+ */
130
+ const als = new AsyncLocalStorage();
131
+ /** Returns the currently-active context, or `undefined` outside one. */
132
+ const getCurrentContext = () => als.getStore();
133
+ //#endregion
134
+ //#region ../server/src/writer.ts
135
+ /**
136
+ * `Writer` — stateless multi-instance write engine.
137
+ *
138
+ * Each {@link Writer.commit} call reads `current.json` FRESH from
139
+ * the bucket, mints the next {@link LogEntry}, PUTs the content body
140
+ * and the log entry, and CAS-advances `current.json` with `If-Match`.
141
+ * Up to {@link S3_REQUEST_MAX_RETRIES} attempts on contention before
142
+ * surfacing `BaerlyError{code:"Conflict"}`. The optional integrity
143
+ * walk over the live log tail is gated by
144
+ * {@link WriterOptions.verifyLogIntegrityOnCommit} (default off
145
+ * — see the option's docstring).
146
+ *
147
+ * The instance carries no per-write cache: every commit re-reads
148
+ * `current.json`, so N stateless server instances writing the same
149
+ * tenant prefix contend at exactly one place — the conditional PUT
150
+ * on `current.json` — and one loses cleanly with a 412.
151
+ *
152
+ * **Manifest-first ordering is REVERSED relative to the legacy
153
+ * `src/syncer.ts` write loop.** Old loop: PUT manifest → PUT content
154
+ * → CAS. New loop: PUT content → PUT log entry → CAS-advance
155
+ * `current.json`. A crashed mid-loop writer leaves an unreferenced
156
+ * content body (no log entry points at it), not an orphan log entry
157
+ * with missing content. The compactor sweeps the orphan content
158
+ * later.
159
+ *
160
+ * **`LogEntry` shape.** Emitted entries follow the contract in
161
+ * `packages/protocol/src/log.ts` (see {@link LogEntry}) and
162
+ * `docs/spec/log-entry-shape.md`. The on-bucket key is
163
+ * `log/<seq>.json` (the integer `seq` is the load-bearing
164
+ * identifier; the `lsn` string is schema-only).
165
+ *
166
+ * @see docs/spec/sync-protocol.md for the protocol invariants this
167
+ * loop preserves.
168
+ * @see docs/spec/log-entry-shape.md for the per-field contract.
169
+ */
170
+ const ctxMetrics = () => getCurrentContext()?.recorder ?? noopMetricsRecorder;
171
+ const DEFAULT_INITIAL_BACKOFF_MS = 25;
172
+ const MAX_BACKOFF_MS = 1500;
173
+ const APPLICATION_JSON = "application/json";
174
+ /**
175
+ * Empty body for index entries. Each index entry is a fact ("doc
176
+ * `<docId>` has `<field> = <value>`"), not data — readers list the
177
+ * prefix, extract the doc id, then GET the content body separately.
178
+ * Pre-allocated module-level constant so every index PUT shares one
179
+ * zero-length buffer.
180
+ */
181
+ const EMPTY_BODY = new Uint8Array(0);
182
+ /**
183
+ * Stateless write engine for the multi-instance core.
184
+ *
185
+ * Construction is cheap and performs zero I/O — adapters build a
186
+ * fresh `Writer` per request and discard it. All real work
187
+ * happens in {@link commit}.
188
+ *
189
+ * @example
190
+ * ```ts
191
+ * import { Writer } from "@gusto/baerly-storage";
192
+ * import { MemoryStorage } from "@gusto/baerly-storage";
193
+ *
194
+ * const writer = new Writer({
195
+ * storage: new MemoryStorage(),
196
+ * currentJsonKey: "app/tickets/tenant/acme/manifests/tickets/current.json",
197
+ * });
198
+ *
199
+ * const result = await writer.commit({
200
+ * op: "I",
201
+ * collection: "tickets",
202
+ * docId: "doc-1",
203
+ * body: { _id: "doc-1", title: "hello" },
204
+ * });
205
+ * console.log(result.entry.seq, result.attempts);
206
+ * ```
207
+ */
208
+ var Writer = class {
209
+ #storage;
210
+ #currentJsonKey;
211
+ #maxRetries;
212
+ #initialBackoffMs;
213
+ #random;
214
+ #indexes;
215
+ #verifyLogIntegrityOnCommit;
216
+ constructor(opts) {
217
+ this.#storage = opts.storage;
218
+ this.#currentJsonKey = opts.currentJsonKey;
219
+ this.#maxRetries = opts.options?.maxRetries ?? 8;
220
+ this.#initialBackoffMs = opts.options?.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS;
221
+ this.#random = opts.options?.random ?? Math.random;
222
+ const indexes = opts.options?.indexes ?? [];
223
+ for (const def of indexes) validateIndexDefinition(def);
224
+ this.#indexes = indexes;
225
+ this.#verifyLogIntegrityOnCommit = opts.options?.verifyLogIntegrityOnCommit ?? false;
226
+ }
227
+ /**
228
+ * Atomically commit one mutation. Reads `current.json` fresh, mints
229
+ * the next log entry at `seq = current.next_seq`, PUTs the content
230
+ * body and the log entry, then CAS-advances `current.json` with
231
+ * `If-Match`. Retries on conflict up to `maxRetries`.
232
+ *
233
+ * The hot-path cost under no contention is 1 GET + 3 PUTs (4 ops);
234
+ * an in-flight peer write costs one extra GET + the backoff sleep
235
+ * per retry.
236
+ *
237
+ * Idempotency: PUT content uses `If-None-Match: "*"`, so a retry of
238
+ * the same logical write produces the same content key and the
239
+ * second PUT no-ops. PUT log entry also uses `If-None-Match: "*"`,
240
+ * so two writers racing the same `next_seq` cause exactly one PUT
241
+ * to land — the loser falls into the CAS retry path.
242
+ *
243
+ * @throws BaerlyError code="Conflict" when the retry budget is
244
+ * exhausted (genuine high-contention case), or when the underlying
245
+ * `current.json` CAS PUT lost.
246
+ * @throws BaerlyError code="Conflict" — the writer fence
247
+ * (`current.json.writer_fence.epoch`) was bumped by a concurrent
248
+ * `claimWriter` call between this commit's read of
249
+ * `current.json` and its CAS-advance. The stale writer aborts
250
+ * to honour the new authority — the kernel does NOT retry under
251
+ * the old epoch. See {@link claimWriter} for the rotation
252
+ * recipe.
253
+ * @throws BaerlyError code="Internal" when a log entry expected in
254
+ * `[0, next_seq)` is missing — a protocol-invariant violation
255
+ * (compactor bug or stale `current.json`).
256
+ * @throws BaerlyError code="InvalidResponse" when a log-entry body
257
+ * isn't valid JSON.
258
+ *
259
+ * **Implicit provisioning.** When `current.json` does not exist at
260
+ * `currentJsonKey` (fresh bucket, fresh collection), the writer
261
+ * auto-creates it with a zero-state manifest before the commit
262
+ * lands. The cost is one extra Class A PUT on the very first
263
+ * commit per collection; steady-state cost is unchanged. A peer
264
+ * racing the same first-write loses cleanly on the create CAS
265
+ * and re-reads to pick up the winner's manifest.
266
+ */
267
+ async commit(input) {
268
+ const session = uuid().slice(0, 6);
269
+ const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
270
+ for (let attempt = 1; attempt <= this.#maxRetries; attempt++) {
271
+ let success;
272
+ try {
273
+ success = await this.#singleAttemptCommit([input], session, logPrefix, "Writer", true);
274
+ } catch (error) {
275
+ if (!isPreconditionFailed(error)) throw error;
276
+ await this.#backoff(attempt);
277
+ continue;
278
+ }
279
+ await this.#verifyFenceUnchanged(success.expectedEpoch, "Writer");
280
+ this.#emitWriteMetrics(input.collection, success.classAOps + (attempt - 1));
281
+ return {
282
+ entry: success.entries[0],
283
+ currentEtag: success.currentEtag,
284
+ attempts: attempt
285
+ };
286
+ }
287
+ throw new BaerlyError("Conflict", `Writer: CAS conflict on ${this.#currentJsonKey} after ${this.#maxRetries} attempts`);
288
+ }
289
+ /**
290
+ * Single-attempt batched commit. Reads `current.json` ONCE, mints
291
+ * `inputs.length` log entries with contiguous `seq` numbers
292
+ * starting at the current `next_seq`, PUTs each content body and
293
+ * each log entry, then CAS-advances `current.json` from
294
+ * `next_seq = N` to `next_seq = N + inputs.length` with
295
+ * `If-Match`.
296
+ *
297
+ * NO retry on CAS loss. On `current.json` 412, throws
298
+ * `BaerlyError{code:"Conflict"}` immediately — the caller (here:
299
+ * `Db.transaction`) decides whether to retry by re-running the
300
+ * body, or to surface to the app. Likewise on a log-entry 412
301
+ * (a peer wrote our seq).
302
+ *
303
+ * Empty `inputs`: returns `{ entries: [], currentEtag: undefined }`
304
+ * after zero storage operations.
305
+ *
306
+ * @throws BaerlyError code="Conflict" — CAS lost on `current.json`,
307
+ * or a log entry already exists at our seq (peer wrote ahead).
308
+ * @throws BaerlyError code="Conflict" — the writer fence
309
+ * (`current.json.writer_fence.epoch`) was bumped by a concurrent
310
+ * `claimWriter` call between this batch's read of
311
+ * `current.json` and its CAS-advance. The stale writer aborts
312
+ * to honour the new authority — the kernel does NOT retry under
313
+ * the old epoch. See {@link claimWriter} for the rotation
314
+ * recipe.
315
+ * @throws BaerlyError code="Internal" — protocol-invariant violation
316
+ * (missing log entry inside `[0, next_seq)`).
317
+ * @throws BaerlyError code="InvalidResponse" — malformed log body.
318
+ *
319
+ * **Implicit provisioning.** Like {@link commit}, this path auto-
320
+ * creates `current.json` with a zero-state manifest on a missing
321
+ * read. Because `commitBatch` does NOT retry on CAS loss, a peer
322
+ * racing the same first-write surfaces `Conflict` to the caller
323
+ * (`Db.transaction` re-runs the body); the manifest is durable
324
+ * regardless of which writer won the create.
325
+ */
326
+ async commitBatch(inputs) {
327
+ if (inputs.length === 0) return {
328
+ entries: [],
329
+ currentEtag: void 0
330
+ };
331
+ const session = uuid().slice(0, 6);
332
+ const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
333
+ const success = await this.#singleAttemptCommit(inputs, session, logPrefix, "Writer.commitBatch", false);
334
+ await this.#verifyFenceUnchanged(success.expectedEpoch, "Writer.commitBatch");
335
+ this.#emitWriteMetrics(inputs[0].collection, success.classAOps);
336
+ return {
337
+ entries: success.entries,
338
+ currentEtag: success.currentEtag
339
+ };
340
+ }
341
+ /**
342
+ * One full commit attempt — the shared body of {@link commit} and
343
+ * {@link commitBatch}. Reads `current.json`, walks the log, mints N
344
+ * entries, PUTs content + indexes in parallel, PUTs log entries,
345
+ * CAS-advances `current.json`. Returns the success payload + the
346
+ * pre-commit fence epoch so the caller can run
347
+ * {@link #verifyFenceUnchanged} outside the retry-catch arm.
348
+ *
349
+ * Retryable failures (a peer wrote our seq; a peer won the CAS on
350
+ * `current.json`) throw `BaerlyError{code:"Conflict"}`. The caller
351
+ * catches via {@link isPreconditionFailed} and either retries
352
+ * (`commit`) or surfaces (`commitBatch`). Fence-bump and protocol-
353
+ * invariant violations are NOT thrown from this helper — the fence
354
+ * check lives in the caller so its `Conflict` propagates past the
355
+ * retry-catch arm. Other thrown `BaerlyError`s (Internal,
356
+ * InvalidResponse, NetworkError) bypass `isPreconditionFailed` and
357
+ * propagate naturally.
358
+ *
359
+ * Crash safety invariant: content / index PUTs are awaited before
360
+ * log PUTs, which are awaited before the CAS. A crashed mid-attempt
361
+ * writer leaves orphan content / index entries (no log entry
362
+ * references them) — the compactor sweeps the orphans. The
363
+ * inverse — orphan log entry with missing content — is never
364
+ * produced.
365
+ */
366
+ async #singleAttemptCommit(inputs, session, logPrefix, errorPrefix, adoptOwnSessionOnLogConflict) {
367
+ const read = await readCurrentJson(this.#storage, this.#currentJsonKey) ?? await this.#provisionCurrentJson();
368
+ const current = read.json;
369
+ const baseEtag = read.etag;
370
+ const expectedEpoch = current.writer_fence.epoch;
371
+ if (this.#verifyLogIntegrityOnCommit) await this.#walkLog(logPrefix, logSeqStartOf(current), current.next_seq);
372
+ const entries = [];
373
+ for (let i = 0; i < inputs.length; i++) {
374
+ const input = inputs[i];
375
+ const seq = current.next_seq + i;
376
+ const entry = {
377
+ lsn: `${timestamp(Date.now())}_${session}_${countKey(seq)}`,
378
+ commit_ts: (/* @__PURE__ */ new Date()).toISOString(),
379
+ op: input.op,
380
+ collection: input.collection,
381
+ doc_id: input.docId,
382
+ schema_version: 0,
383
+ session,
384
+ seq,
385
+ ...input.op !== "D" && input.body !== void 0 ? {
386
+ new: input.body,
387
+ patch: input.body
388
+ } : {},
389
+ ...input.origin !== void 0 ? { origin: input.origin } : {}
390
+ };
391
+ entries.push(entry);
392
+ }
393
+ let contentPutCount = 0;
394
+ let indexClassA = 0;
395
+ const parallelPuts = [];
396
+ const inBatchImage = /* @__PURE__ */ new Map();
397
+ for (const input of inputs) {
398
+ if (input.op !== "D" && input.body !== void 0) {
399
+ contentPutCount++;
400
+ const bytes = encodeJsonBytes(input.body);
401
+ const contentKey = `${logPrefix}/content/${await versionFromContent(bytes)}.json`;
402
+ parallelPuts.push(this.#storage.put(contentKey, bytes, {
403
+ ifNoneMatch: "*",
404
+ contentType: APPLICATION_JSON
405
+ }).catch((error) => {
406
+ this.#observe429(error, input.collection);
407
+ if (isPreconditionFailed(error)) return;
408
+ throw error;
409
+ }));
410
+ }
411
+ if (this.#indexes.length > 0) {
412
+ let newKeys = [];
413
+ let staleKeys = [];
414
+ if (input.op === "I") newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
415
+ else if (input.op === "U") {
416
+ const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(logPrefix, input.collection, input.docId, current.next_seq);
417
+ const oldKeys = allIndexKeysFor(logPrefix, this.#indexes, preImage, input.docId);
418
+ newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
419
+ const newSet = new Set(newKeys);
420
+ staleKeys = oldKeys.filter((k) => !newSet.has(k));
421
+ } else {
422
+ const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(logPrefix, input.collection, input.docId, current.next_seq);
423
+ staleKeys = allIndexKeysFor(logPrefix, this.#indexes, preImage, input.docId);
424
+ }
425
+ for (const k of newKeys) parallelPuts.push(this.#storage.put(k, EMPTY_BODY, {
426
+ ifNoneMatch: "*",
427
+ contentType: APPLICATION_JSON
428
+ }).catch((error) => {
429
+ this.#observe429(error, input.collection);
430
+ if (isPreconditionFailed(error)) return;
431
+ throw error;
432
+ }));
433
+ for (const k of staleKeys) parallelPuts.push(this.#storage.delete(k));
434
+ indexClassA += newKeys.length + staleKeys.length;
435
+ if (newKeys.length + staleKeys.length > 0) ctxMetrics().histogram("db.write.index_ops_per_logical_write", newKeys.length + staleKeys.length, { collection: input.collection });
436
+ inBatchImage.set(input.docId, input.op === "D" ? void 0 : input.body);
437
+ }
438
+ }
439
+ await Promise.all(parallelPuts);
440
+ const logPutOne = async (entry) => {
441
+ const logEntryKey = `${logPrefix}/log/${entry.seq}.json`;
442
+ const logBytes = encodeJsonBytes(entry);
443
+ try {
444
+ await this.#storage.put(logEntryKey, logBytes, {
445
+ ifNoneMatch: "*",
446
+ contentType: APPLICATION_JSON
447
+ });
448
+ return { ok: true };
449
+ } catch (error) {
450
+ this.#observe429(error, entry.collection);
451
+ if (!isPreconditionFailed(error)) throw error;
452
+ ctxMetrics().counter("db.r2.put.412_total", 1, {
453
+ collection: entry.collection,
454
+ step: "log-put"
455
+ });
456
+ return { ok: false };
457
+ }
458
+ };
459
+ const logPutResults = await Promise.all(entries.map(logPutOne));
460
+ let committedEntries = entries;
461
+ const firstConflictIdx = logPutResults.findIndex((r) => !r.ok);
462
+ if (firstConflictIdx !== -1) {
463
+ const conflictedEntry = entries[firstConflictIdx];
464
+ const logEntryKey = `${logPrefix}/log/${conflictedEntry.seq}.json`;
465
+ if (adoptOwnSessionOnLogConflict) {
466
+ const decision = tryAdoptOwnSessionLogEntry({
467
+ self: conflictedEntry,
468
+ existing: await readLogEntry(this.#storage, logEntryKey),
469
+ batchSize: inputs.length
470
+ });
471
+ if (decision.adopt) committedEntries = [decision.entry];
472
+ else throw new BaerlyError("Conflict", `${errorPrefix}: log entry already exists at ${logEntryKey}; ${decision.reason}`);
473
+ } else throw new BaerlyError("Conflict", `${errorPrefix}: log entry already exists at ${logEntryKey}; peer wrote our seq`);
474
+ }
475
+ const nextBody = encodeJsonBytes({
476
+ ...current,
477
+ next_seq: current.next_seq + inputs.length
478
+ });
479
+ const putOpts = {
480
+ ifMatch: baseEtag,
481
+ contentType: APPLICATION_JSON
482
+ };
483
+ let result;
484
+ try {
485
+ result = await this.#storage.put(this.#currentJsonKey, nextBody, putOpts);
486
+ } catch (error) {
487
+ this.#observe429(error, inputs[0].collection);
488
+ if (isPreconditionFailed(error)) {
489
+ ctxMetrics().counter("db.r2.put.412_total", 1, {
490
+ collection: inputs[0].collection,
491
+ step: "current-json-cas"
492
+ });
493
+ throw new BaerlyError("Conflict", `${errorPrefix}: CAS conflict on ${this.#currentJsonKey}`);
494
+ }
495
+ throw error;
496
+ }
497
+ const classAOps = contentPutCount + entries.length + indexClassA + 1;
498
+ return {
499
+ entries: committedEntries,
500
+ currentEtag: result.etag,
501
+ classAOps,
502
+ expectedEpoch
503
+ };
504
+ }
505
+ /**
506
+ * Read the pre-image content body for a doc by walking the live
507
+ * log backwards from `currentNextSeq` looking for the
508
+ * most-recent I/U entry on this `(collection, docId)`. Returns
509
+ * `undefined` when:
510
+ *
511
+ * - the doc's most-recent op was `D` (tombstone — no live body);
512
+ * - no entry for this doc lives inside the visible log range
513
+ * `[log_seq_start, currentNextSeq)` (a fresh-insert race or
514
+ * the doc has been folded into the snapshot but is no longer
515
+ * referenced).
516
+ *
517
+ * Used ONLY by the index-emission path on `U` / `D` to compute
518
+ * the stale-key set. Bounded by `log_seq_start`: entries below
519
+ * have been folded into the snapshot and may already be swept
520
+ * off the bucket — a snapshot fold is the rebuild command's job
521
+ * (see `./rebuild-index.ts`), not the writer's.
522
+ *
523
+ * **Cost note:** linear walk, O(snapshot lag). For day-one Phase
524
+ * 8 collections (helpdesk-shape: 100s of docs, <10k log entries)
525
+ * this is fine — the compactor folds the live tail every ~100
526
+ * entries (`packages/server/src/compactor.ts`). A follow-up ticket
527
+ * caches per-doc index head in `current.json` for O(1) lookup.
528
+ * The bound is documented; out of scope here.
529
+ */
530
+ /**
531
+ * Auto-create the per-collection `current.json` at
532
+ * `this.#currentJsonKey` with a zero-state initial manifest. Called
533
+ * by `#singleAttemptCommit` when the read returned `null` (fresh
534
+ * bucket / fresh collection).
535
+ *
536
+ * Concurrency: `createCurrentJson` uses `If-None-Match: "*"`. If a
537
+ * peer raced us and won, the storage layer surfaces `Conflict`; we
538
+ * recover by re-reading the now-present manifest. We do NOT retry
539
+ * the create — a single recover-via-read covers every race that
540
+ * could have produced our null read.
541
+ *
542
+ * The seed shape (`snapshot: null`, `next_seq: 0`, `log_seq_start:
543
+ * 0`, `writer_fence: { epoch: 0, owner: "", claimed_at: "" }`)
544
+ * matches `ensureTable` and `baerly deploy`'s pre-warm path, so an
545
+ * operator who pre-provisions and a writer who auto-creates land
546
+ * on byte-identical bytes.
547
+ *
548
+ * @throws BaerlyError code="InvalidResponse" — the post-recover
549
+ * re-read also returned null. Defensive guard; in practice
550
+ * unreachable because the Conflict implies the key now exists.
551
+ */
552
+ async #provisionCurrentJson() {
553
+ const initial = {
554
+ schema_version: 1,
555
+ snapshot: null,
556
+ next_seq: 0,
557
+ log_seq_start: 0,
558
+ writer_fence: {
559
+ epoch: 0,
560
+ owner: "",
561
+ claimed_at: ""
562
+ }
563
+ };
564
+ try {
565
+ return await createCurrentJson(this.#storage, this.#currentJsonKey, initial);
566
+ } catch (error) {
567
+ if (!(error instanceof BaerlyError) || error.code !== "Conflict") throw error;
568
+ }
569
+ const recovered = await readCurrentJson(this.#storage, this.#currentJsonKey);
570
+ if (recovered === null) throw new BaerlyError("InvalidResponse", `Writer: current.json missing at ${this.#currentJsonKey} after auto-create raced and recover read returned null`);
571
+ return recovered;
572
+ }
573
+ async #readPreImage(logPrefix, collection, docId, currentNextSeq) {
574
+ for (let s = currentNextSeq - 1; s >= 0; s--) {
575
+ const logKey = `${logPrefix}/log/${s}.json`;
576
+ const got = await this.#storage.get(logKey);
577
+ if (got === null) continue;
578
+ let entry;
579
+ try {
580
+ entry = decodeJsonBytes(got.body);
581
+ } catch {
582
+ continue;
583
+ }
584
+ if (entry.collection !== collection || entry.doc_id !== docId) continue;
585
+ if (entry.op === "D") return;
586
+ if ((entry.op === "I" || entry.op === "U") && entry.new !== void 0) return entry.new;
587
+ }
588
+ }
589
+ /**
590
+ * Walk `log/<logSeqStart>.json` … `log/<nextSeq - 1>.json` with
591
+ * bounded parallelism via `walkLogRange`. Materialised entries are
592
+ * discarded — the walk's only job is to surface a hole or a
593
+ * malformed body inside the visible range as
594
+ * `BaerlyError{code:"Internal"}` / `"InvalidResponse"`.
595
+ *
596
+ * Gated on `verifyLogIntegrityOnCommit`; default off in production
597
+ * because the per-doc fold already lives in the read path. See the
598
+ * option's docstring for the rationale and the opt-in convention.
599
+ *
600
+ * `logSeqStart` is the boundary set by the compactor on
601
+ * `current.json.log_seq_start`. Entries below it have been folded
602
+ * into the snapshot and may have been swept off the bucket, so the
603
+ * walk MUST NOT GET-require them.
604
+ */
605
+ async #walkLog(logPrefix, logSeqStart, nextSeq) {
606
+ await walkLogRange(this.#storage, logPrefix, logSeqStart, nextSeq);
607
+ }
608
+ /**
609
+ * Bump the `db.r2.put.429_total` counter when `err` looks like an
610
+ * R2 prefix-partition rate-limit. Best-effort: detected via
611
+ * `BaerlyError{code:"NetworkError"}` with a `429` token in the
612
+ * message. Called from every PUT call site's catch arm; mutually
613
+ * exclusive in practice with `isPreconditionFailed` (412 ≠ 429).
614
+ */
615
+ #observe429(err, collection) {
616
+ if (is429(err)) ctxMetrics().counter("db.r2.put.429_total", 1, { collection });
617
+ }
618
+ /**
619
+ * Emit the per-logical-write `class_a_ops_per_logical_write`
620
+ * histogram shared by `commit` and `commitBatch`. `classAOps`
621
+ * differs between the two paths (retry-budget vs batch shape),
622
+ * so each caller computes it.
623
+ */
624
+ #emitWriteMetrics(collection, classAOps) {
625
+ ctxMetrics().histogram("db.write.class_a_ops_per_logical_write", classAOps, { collection });
626
+ }
627
+ /**
628
+ * Re-read `current.json` after a successful CAS and assert the
629
+ * writer-fence epoch is still ours. The CAS only mutated `next_seq`
630
+ * (the fence is preserved from `current`), so a post-write epoch
631
+ * mismatch can only mean another writer claimed the fence between
632
+ * our step-1 read and step-6 PUT — the exact split-brain
633
+ * `WriterFence` prevents. Throws `Conflict`; no retry, since the
634
+ * stale writer must defer to the new authority.
635
+ *
636
+ * The fence-verify GET is Class B and intentionally NOT counted in
637
+ * `class_a_ops_per_logical_write`.
638
+ */
639
+ async #verifyFenceUnchanged(expectedEpoch, where) {
640
+ const postRead = await readCurrentJson(this.#storage, this.#currentJsonKey);
641
+ if (postRead === null) return;
642
+ if (postRead.json.writer_fence.epoch === expectedEpoch) return;
643
+ throw new BaerlyError("Conflict", `${where}: writer fence bumped from epoch ${expectedEpoch} to ${postRead.json.writer_fence.epoch} during commit on ${this.#currentJsonKey}; stale writer aborting`);
644
+ }
645
+ /**
646
+ * Exponential backoff with full jitter. `25 * 2^(attempt-1)` capped
647
+ * at 1500ms; uniform jitter in `[0, base)` keeps colliding peers
648
+ * from re-racing in lockstep. Worst-case total wait across the
649
+ * default 8 attempts is roughly 2.5 s — well under a typical
650
+ * Worker request budget.
651
+ */
652
+ async #backoff(attempt) {
653
+ const sleepMs = Math.min(this.#initialBackoffMs * 2 ** (attempt - 1), MAX_BACKOFF_MS) * this.#random();
654
+ if (sleepMs <= 0) return;
655
+ await new Promise((r) => setTimeout(r, sleepMs));
656
+ }
657
+ };
658
+ /**
659
+ * `true` when the underlying storage surfaced a `PreconditionFailed`
660
+ * 412 (or its non-S3 equivalents). Every in-tree {@link Storage} impl
661
+ * surfaces a lost CAS as `BaerlyError{code:"Conflict"}`.
662
+ */
663
+ const isPreconditionFailed = (err) => err instanceof BaerlyError && err.code === "Conflict";
664
+ /**
665
+ * `true` when the underlying storage surfaced an R2 prefix-partition
666
+ * rate-limit. {@link S3HttpStorage} stamps the upstream HTTP status
667
+ * onto `BaerlyError.cause` as `{ status }`; we discriminate on that
668
+ * structured field rather than regex-matching the message.
669
+ */
670
+ const is429 = (err) => {
671
+ if (!(err instanceof BaerlyError) || err.code !== "NetworkError") return false;
672
+ return err.cause?.status === 429;
673
+ };
674
+ //#endregion
675
+ //#region src/admin/restore.ts
676
+ /**
677
+ * `baerly admin restore` — bulk-import NDJSON into a fresh collection.
678
+ *
679
+ * Reads NDJSON from stdin, reconstructs each row, and calls
680
+ * `Writer.commit({op:"I"})` per row into the target bucket.
681
+ * Programmatic callers (today: tests + the export round-trip
682
+ * integration test) can divert the input by passing
683
+ * `{ streams: { stdin } }` to {@link runRestore}. Idempotent on a fresh
684
+ * bucket: re-running on a half-completed restore **refuses** unless
685
+ * `--force` is set (which bumps the writer fence and seeds a fresh
686
+ * `current.json` first).
687
+ *
688
+ * Args:
689
+ * --bucket Required. Target bucket URI.
690
+ * --app Required (or via baerly.config.ts).
691
+ * --tenant Required (or via baerly.config.ts).
692
+ * --collection Required. Target collection name.
693
+ * --force Truncate the target if it exists (fence-bump + reseed).
694
+ * --json JSON envelope.
695
+ *
696
+ * stdin: NDJSON, one `{_id, ...}` row per line. Empty lines tolerated.
697
+ * EOF terminates.
698
+ *
699
+ * Cost shape: 1 PUT current.json (initial) + N × (1 PUT log + 1 PUT
700
+ * content + 1 PUT current.json CAS) = 3N + 1 Class A ops for N rows.
701
+ *
702
+ * Partial-restore semantics: a mid-stream Network / Internal / parse
703
+ * error leaves the target in a partial state (some rows committed,
704
+ * `current.json` advanced to wherever the last successful commit
705
+ * landed). Re-run with `--force` to truncate, or hand-clean. The
706
+ * malformed-line case (missing `_id`, bad JSON) fails fast on that
707
+ * line; rows committed BEFORE it survive.
708
+ *
709
+ * Exit codes:
710
+ * 0 — every row committed.
711
+ * 1 — InvalidConfig (bad bucket URI, missing args).
712
+ * 2 — Network / storage error mid-stream, or a malformed NDJSON
713
+ * line (raised as a plain `Error`, not `BaerlyError`).
714
+ * 3 — Conflict from a pre-existing target without --force, or from a
715
+ * concurrent writer when --force was used.
716
+ */
717
+ const RESTORE_OWNER = "baerly-restore";
718
+ const bundle = defineBaerlySubcommand({
719
+ name: "admin.restore",
720
+ meta: { description: "Bulk-import canonical NDJSON into a fresh collection." },
721
+ args: {
722
+ bucket: {
723
+ type: "string",
724
+ required: true,
725
+ description: "Target bucket URI (s3://<bucket>[/<prefix>], file:///<abs>, memory://<bucket>)",
726
+ valueHint: "bucket-uri"
727
+ },
728
+ app: {
729
+ type: "string",
730
+ required: false,
731
+ description: "Application name segment (defaults to baerly.config.ts).",
732
+ valueHint: "app"
733
+ },
734
+ tenant: {
735
+ type: "string",
736
+ required: false,
737
+ description: "Tenant name segment (defaults to baerly.config.ts).",
738
+ valueHint: "tenant"
739
+ },
740
+ collection: {
741
+ type: "string",
742
+ required: true,
743
+ description: "Target collection name.",
744
+ valueHint: "name"
745
+ },
746
+ force: {
747
+ type: "boolean",
748
+ description: "Truncate the target if it exists (bump fence + reseed current.json)."
749
+ },
750
+ json: {
751
+ type: "boolean",
752
+ description: "Emit a structured JSON envelope to stdout (success) or stderr (error)"
753
+ }
754
+ },
755
+ handler: async (args, ctx) => {
756
+ const bucket = await parseBucketUri(args.bucket);
757
+ const { app, tenant } = await ctx.resolveAppTenant({
758
+ app: args.app,
759
+ tenant: args.tenant
760
+ });
761
+ const currentJsonKey = `${bucket.keyPrefix}app/${app}/tenant/${tenant}/manifests/${args.collection}/current.json`;
762
+ const head = await readCurrentJson(bucket.storage, currentJsonKey);
763
+ if (head !== null && args.force !== true) throw new BaerlyError("Conflict", `baerly admin restore: ${currentJsonKey} exists; pass --force to truncate`);
764
+ if (head !== null) {
765
+ const truncatedNext = head.json.next_seq;
766
+ const reseeded = {
767
+ schema_version: 1,
768
+ snapshot: null,
769
+ next_seq: truncatedNext,
770
+ log_seq_start: truncatedNext,
771
+ writer_fence: {
772
+ epoch: head.json.writer_fence.epoch + 1,
773
+ owner: RESTORE_OWNER,
774
+ claimed_at: ""
775
+ }
776
+ };
777
+ try {
778
+ await bucket.storage.put(currentJsonKey, encodeJsonBytes(reseeded), {
779
+ ifMatch: head.etag,
780
+ contentType: "application/json"
781
+ });
782
+ } catch (error) {
783
+ if (error instanceof BaerlyError) throw error;
784
+ throw new BaerlyError("NetworkError", `baerly admin restore: failed to reseed current.json: ${error.message}`);
785
+ }
786
+ } else {
787
+ const seed = {
788
+ schema_version: 1,
789
+ snapshot: null,
790
+ next_seq: 0,
791
+ log_seq_start: 0,
792
+ writer_fence: {
793
+ epoch: 0,
794
+ owner: RESTORE_OWNER,
795
+ claimed_at: ""
796
+ }
797
+ };
798
+ await createCurrentJson(bucket.storage, currentJsonKey, seed);
799
+ }
800
+ const writer = new Writer({
801
+ storage: bucket.storage,
802
+ currentJsonKey
803
+ });
804
+ const rl = createInterface({
805
+ input: ctx.streams?.stdin ?? process.stdin,
806
+ crlfDelay: Infinity
807
+ });
808
+ let count = 0;
809
+ let lineNo = 0;
810
+ for await (const line of rl) {
811
+ lineNo++;
812
+ if (line.length === 0) continue;
813
+ let parsed;
814
+ try {
815
+ parsed = JSON.parse(line);
816
+ } catch (error) {
817
+ throw new Error(`baerly admin restore: line ${lineNo} is not valid JSON: ${error.message}`, { cause: error });
818
+ }
819
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`baerly admin restore: line ${lineNo} is not a JSON object`);
820
+ const row = parsed;
821
+ const id = row["_id"];
822
+ if (typeof id !== "string" || id.length === 0) throw new Error(`baerly admin restore: line ${lineNo} missing non-empty string _id`);
823
+ const body = row;
824
+ await writer.commit({
825
+ op: "I",
826
+ collection: args.collection,
827
+ docId: id,
828
+ body
829
+ });
830
+ count++;
831
+ }
832
+ emitSuccess({
833
+ command: "admin.restore",
834
+ status: "ok",
835
+ collection: args.collection,
836
+ restored: count
837
+ });
838
+ return 0;
839
+ }
840
+ });
841
+ /** citty `defineCommand` block for `baerly admin restore`. */
842
+ const restoreCmd = bundle.cmd;
843
+ bundle.run;
844
+ //#endregion
845
+ export { restoreCmd };
846
+
847
+ //# sourceMappingURL=restore-CbKVMMpm.js.map