@gusto/baerly-storage 0.1.2 → 0.3.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.
- package/LICENSE +202 -0
- package/NOTICE +29 -0
- package/README.md +108 -44
- package/dist/API.md +192 -121
- package/dist/CHANGELOG.md +144 -0
- package/dist/THIRD-PARTY-LICENSES.txt +312 -0
- package/dist/{app-config-C0Bbw_Z6.d.ts → app-config-BIzyAKzy.d.ts} +14 -2
- package/dist/app-config.d.ts +1 -1
- package/dist/auth.d.ts +1 -1
- package/dist/auth.js +288 -288
- package/dist/auth.js.map +1 -1
- package/dist/baerly.js +10 -10
- package/dist/baerly.js.map +1 -1
- package/dist/bytes-BXdamO3L.js.map +1 -1
- package/dist/{client-DYZfoZb9.d.ts → client-BJXF3XJA.d.ts} +10 -10
- package/dist/client-react.d.ts +76 -85
- package/dist/client-react.js +95 -53
- package/dist/client-react.js.map +1 -1
- package/dist/client.d.ts +3 -3
- package/dist/client.js.map +1 -1
- package/dist/{cloudflare-CINJPKCW.js → cloudflare-Cn2ibODt.js} +178 -2
- package/dist/cloudflare-Cn2ibODt.js.map +1 -0
- package/dist/cloudflare.d.ts +4 -4
- package/dist/cloudflare.js +10 -11
- package/dist/cloudflare.js.map +1 -1
- package/dist/{subcommand-DZcHcsYp.js → config-CGyBopy3.js} +643 -439
- package/dist/config-CGyBopy3.js.map +1 -0
- package/dist/context-DRZ3tZ5l.js.map +1 -1
- package/dist/{cost-CQt1YRkA.js → cost-BZ_MDBmn.js} +6 -4
- package/dist/cost-BZ_MDBmn.js.map +1 -0
- package/dist/{current-json-C-EyJqs0.js → current-json-DsN7FNY1.js} +47 -13
- package/dist/current-json-DsN7FNY1.js.map +1 -0
- package/dist/{db-BM3y2JQw.d.ts → db-CCT6tDfY.d.ts} +26 -108
- package/dist/{deploy-CrAbfgCq.js → deploy-BKKyGlSJ.js} +11 -4
- package/dist/deploy-BKKyGlSJ.js.map +1 -0
- package/dist/dev-vite.d.ts +5 -5
- package/dist/dev-vite.js +5 -5
- package/dist/dev-vite.js.map +1 -1
- package/dist/dev.d.ts +1 -1
- package/dist/dev.js +1 -1
- package/dist/{doctor-Db-hzPmE.js → doctor-BVU4GNXN.js} +13 -132
- package/dist/doctor-BVU4GNXN.js.map +1 -0
- package/dist/{dump-BYA55NLP.js → dump-DPEAKub6.js} +5 -3
- package/dist/dump-DPEAKub6.js.map +1 -0
- package/dist/errors-DOdL95kK.js.map +1 -1
- package/dist/{export-Bhbz90-z.js → export-BcuCLFFe.js} +6 -4
- package/dist/{export-Bhbz90-z.js.map → export-BcuCLFFe.js.map} +1 -1
- package/dist/{fsck-CPPZWt9p.js → fsck-RXgLOaJG.js} +23 -11
- package/dist/fsck-RXgLOaJG.js.map +1 -0
- package/dist/{http-Cw8p6y5b.js → http-Bd4byR4n.js} +45 -61
- package/dist/http-Bd4byR4n.js.map +1 -0
- package/dist/http.d.ts +15 -15
- package/dist/http.js +1 -1
- package/dist/{index-cUY-36AN.d.ts → index-BDceQQi-.d.ts} +20 -4
- package/dist/{index-C3JAH1Yo.d.ts → index-Cmsxx-ZN.d.ts} +9 -9
- package/dist/{index-DSvwEUeF.d.ts → index-DW7GT6M2.d.ts} +50 -42
- package/dist/{index-DwDTWPSU.d.ts → index-DnBGSeuU.d.ts} +10 -7
- package/dist/index.d.ts +6 -6
- package/dist/index.js +4 -4
- package/dist/{indexes-DAu2AkTW.d.ts → indexes-Cx7uMXm0.d.ts} +2 -2
- package/dist/{inspect-Bdbzvi-_.js → inspect-DhI49PSi.js} +16 -8
- package/dist/inspect-DhI49PSi.js.map +1 -0
- package/dist/{snapshot-SS8USDUF.js → log-tail-DXeDkWEp.js} +154 -83
- package/dist/log-tail-DXeDkWEp.js.map +1 -0
- package/dist/{maintenance-BRrThz8V.d.ts → maintenance-BkhUr72A.d.ts} +91 -26
- package/dist/{maintenance-ClzBC1Vv.js → maintenance-CWBQpZ2y.js} +368 -161
- package/dist/maintenance-CWBQpZ2y.js.map +1 -0
- package/dist/{maintenance-BvOv6BMM.js → maintenance-C_KSkVjd.js} +204 -82
- package/dist/maintenance-C_KSkVjd.js.map +1 -0
- package/dist/maintenance.d.ts +3 -2
- package/dist/maintenance.js +3 -2
- package/dist/node.d.ts +13 -8
- package/dist/node.js +1 -1
- package/dist/normalize-XWY25_sG.js.map +1 -1
- package/dist/{observability-CpOiEN0k.js → observability-BYd-RzEx.js} +63 -55
- package/dist/observability-BYd-RzEx.js.map +1 -0
- package/dist/observability.d.ts +3 -3
- package/dist/observability.js +1 -1
- package/dist/{plan-DOTl21vq.js → plan-DIu_B6fy.js} +7 -4
- package/dist/plan-DIu_B6fy.js.map +1 -0
- package/dist/{query-BmiQy328.js → query-sQNO5vU_.js} +1071 -1099
- package/dist/query-sQNO5vU_.js.map +1 -0
- package/dist/{rebuild-index-DC_nR6wP.js → rebuild-index-DP4CqSSs.js} +5 -4
- package/dist/rebuild-index-DP4CqSSs.js.map +1 -0
- package/dist/{restore-C6IcmLeA.js → restore-DpQYef6r.js} +362 -328
- package/dist/restore-DpQYef6r.js.map +1 -0
- package/dist/shared-secret-BJdSwpgw.js.map +1 -1
- package/dist/{src-QQ7jDeL2.js → src-CWpkSbvJ.js} +40 -20
- package/dist/src-CWpkSbvJ.js.map +1 -0
- package/dist/{src-DU1sCMlr.js → src-D24wDpzR.js} +269 -258
- package/dist/src-D24wDpzR.js.map +1 -0
- package/dist/{src-zhEAmmF7.js → src-Db4-qVtM.js} +36 -96
- package/dist/src-Db4-qVtM.js.map +1 -0
- package/dist/subcommand-CP9NY2J4.js +159 -0
- package/dist/subcommand-CP9NY2J4.js.map +1 -0
- package/dist/{usage-CLjirdD-.js → usage-CTfDq9HR.js} +3 -3
- package/dist/{usage-CLjirdD-.js.map → usage-CTfDq9HR.js.map} +1 -1
- package/dist/{validate-DCq_0DIn.js → validate-DtljsCh1.js} +51 -51
- package/dist/{validate-DCq_0DIn.js.map → validate-DtljsCh1.js.map} +1 -1
- package/package.json +42 -31
- package/dist/cloudflare-CINJPKCW.js.map +0 -1
- package/dist/config-DVfDGyw1.js +0 -278
- package/dist/config-DVfDGyw1.js.map +0 -1
- package/dist/cost-CQt1YRkA.js.map +0 -1
- package/dist/current-json-C-EyJqs0.js.map +0 -1
- package/dist/deploy-CrAbfgCq.js.map +0 -1
- package/dist/doctor-Db-hzPmE.js.map +0 -1
- package/dist/dump-BYA55NLP.js.map +0 -1
- package/dist/fsck-CPPZWt9p.js.map +0 -1
- package/dist/http-Cw8p6y5b.js.map +0 -1
- package/dist/inspect-Bdbzvi-_.js.map +0 -1
- package/dist/maintenance-BvOv6BMM.js.map +0 -1
- package/dist/maintenance-ClzBC1Vv.js.map +0 -1
- package/dist/observability-CpOiEN0k.js.map +0 -1
- package/dist/plan-DOTl21vq.js.map +0 -1
- package/dist/query-BmiQy328.js.map +0 -1
- package/dist/rebuild-index-DC_nR6wP.js.map +0 -1
- package/dist/restore-C6IcmLeA.js.map +0 -1
- package/dist/snapshot-SS8USDUF.js.map +0 -1
- package/dist/src-DU1sCMlr.js.map +0 -1
- package/dist/src-QQ7jDeL2.js.map +0 -1
- package/dist/src-zhEAmmF7.js.map +0 -1
- package/dist/subcommand-DZcHcsYp.js.map +0 -1
|
@@ -1,9 +1,37 @@
|
|
|
1
1
|
import { n as encodeJsonBytes, t as decodeJsonBytes } from "./bytes-BXdamO3L.js";
|
|
2
|
-
import { a as
|
|
3
|
-
import { a as
|
|
4
|
-
import { a as
|
|
2
|
+
import { a as countKey, d as LOG_FORWARD_PROBE_CAP, h as MAX_KEY_BYTES, i as timestamp, o as uuid, p as MAINTENANCE_PROFILE_CF_FREE, r as parseBucketUri } from "./config-CGyBopy3.js";
|
|
3
|
+
import { a as walkLogRange, d as logObjectKey, h as readCurrentJson, i as readLogEntry, m as logSeqStartOf, p as createCurrentJson, t as findLogTail } from "./log-tail-DXeDkWEp.js";
|
|
4
|
+
import { a as getCurrentContext, c as noopMetricsRecorder, l as versionFromContent, n as runBoundedMaintenance, o as allIndexKeysFor, r as shouldFireMaintenance, s as validateIndexDefinition, t as dispatchInlineAwaited } from "./maintenance-C_KSkVjd.js";
|
|
5
5
|
import { o as BaerlyError, r as emitSuccess } from "./baerly.js";
|
|
6
|
+
import { n as defineBaerlySubcommand, r as assertPathSegment, t as assertCollectionArg } from "./subcommand-CP9NY2J4.js";
|
|
6
7
|
import { createInterface } from "node:readline";
|
|
8
|
+
//#region ../server/src/doc-id.ts
|
|
9
|
+
/**
|
|
10
|
+
* Guard a caller-supplied `_id` before it becomes a written key segment
|
|
11
|
+
* (index keys, log `doc_id`) or filesystem path (`LocalFsStorage`). The
|
|
12
|
+
* `_id` analogue of `assertKeySegment` (`db.ts`). Routes through the
|
|
13
|
+
* single shared {@link assertPathSegment} rule (empty / `"/"` /
|
|
14
|
+
* `"."`|`".."` / C0-C1 control chars / leading `"_"` (ADR-007) / overlong,
|
|
15
|
+
* all as `BaerlyError{code:"InvalidConfig"}`).
|
|
16
|
+
*/
|
|
17
|
+
const assertDocId = (id) => {
|
|
18
|
+
assertPathSegment(id, "_id");
|
|
19
|
+
};
|
|
20
|
+
//#endregion
|
|
21
|
+
//#region ../server/src/key-limit.ts
|
|
22
|
+
const utf8 = new TextEncoder();
|
|
23
|
+
/**
|
|
24
|
+
* Reject an assembled object key over the S3/R2 full-key ceiling
|
|
25
|
+
* ({@link MAX_KEY_BYTES}) as `InvalidConfig`. Per-segment caps don't
|
|
26
|
+
* bound the sum, and index values skip `assertPathSegment` entirely, so
|
|
27
|
+
* this post-encoding check at the writer's PUT sites is their only
|
|
28
|
+
* overflow guard. @see docs/spec/storage-compatibility.md
|
|
29
|
+
*/
|
|
30
|
+
const assertKeyWithinLimit = (key) => {
|
|
31
|
+
const bytes = utf8.encode(key).length;
|
|
32
|
+
if (bytes > 1024) throw new BaerlyError("InvalidConfig", `object key exceeds ${MAX_KEY_BYTES} bytes (got ${bytes}): ${JSON.stringify(key.slice(0, 80))}…`);
|
|
33
|
+
};
|
|
34
|
+
//#endregion
|
|
7
35
|
//#region ../server/src/log-conflict-adoption.ts
|
|
8
36
|
/**
|
|
9
37
|
* Decide whether the entry already at `/log/<seq>.json` is the
|
|
@@ -11,6 +39,15 @@ import { createInterface } from "node:readline";
|
|
|
11
39
|
* function; no I/O. The caller performs the GET (when the log PUT
|
|
12
40
|
* surfaces 412) and passes the read-back body in `ctx.existing`.
|
|
13
41
|
*
|
|
42
|
+
* ## Correctness precondition
|
|
43
|
+
*
|
|
44
|
+
* A fresh `session` id is minted per `commit()` call, seq-stable
|
|
45
|
+
* across that call's retries. Adoption compares the writer-minted
|
|
46
|
+
* intent/body fields as well as session and seq: a dropped-ack retry
|
|
47
|
+
* reuses the same attempted entry and adopts, while a same-session /
|
|
48
|
+
* same-seq occupant carrying a different logical mutation is treated as
|
|
49
|
+
* a conflict and skipped by the caller's forward-probe loop.
|
|
50
|
+
*
|
|
14
51
|
* @see {@link AdoptionDecision} for the return shape.
|
|
15
52
|
* @see The soundness invariant in this module's header docstring.
|
|
16
53
|
*/
|
|
@@ -27,6 +64,10 @@ const tryAdoptOwnSessionLogEntry = (ctx) => {
|
|
|
27
64
|
adopt: false,
|
|
28
65
|
reason: "wrong-seq"
|
|
29
66
|
};
|
|
67
|
+
if (JSON.stringify(ctx.existing) !== JSON.stringify(ctx.self)) return {
|
|
68
|
+
adopt: false,
|
|
69
|
+
reason: "intent-mismatch"
|
|
70
|
+
};
|
|
30
71
|
return {
|
|
31
72
|
adopt: true,
|
|
32
73
|
entry: ctx.existing
|
|
@@ -35,29 +76,37 @@ const tryAdoptOwnSessionLogEntry = (ctx) => {
|
|
|
35
76
|
//#endregion
|
|
36
77
|
//#region ../server/src/writer.ts
|
|
37
78
|
/**
|
|
38
|
-
* `Writer` — stateless multi-instance write engine.
|
|
79
|
+
* `Writer` — stateless multi-instance write engine (single-write commit).
|
|
39
80
|
*
|
|
40
|
-
* Each {@link Writer.commit}
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
81
|
+
* Each {@link Writer.commit} reads `current.json` FRESH (for
|
|
82
|
+
* `log_seq_start` / `tail_hint` as a probe FLOOR — a lower bound, NOT a
|
|
83
|
+
* CAS precondition), PUTs the content body, then **creates `log/<seq>`
|
|
84
|
+
* via `If-None-Match: "*"`. That create IS the commit / linearization
|
|
85
|
+
* point.** The writer writes NOTHING to `current.json` on the commit
|
|
86
|
+
* path; `tail_hint` advances outside ordinary commits via compaction
|
|
87
|
+
* folds, write-tick refreshes, and explicit operator/import paths. The
|
|
88
|
+
* commit model and its invariants are recorded in ADR-008
|
|
89
|
+
* (`docs/adr/008-single-write-commit.md`). The
|
|
90
|
+
* optional integrity walk is gated by
|
|
91
|
+
* {@link WriterOptions.verifyLogIntegrityOnCommit} (default off).
|
|
48
92
|
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
93
|
+
* No per-write cache: every commit re-reads + re-probes, so N stateless
|
|
94
|
+
* instances contend at one place — the `If-None-Match` create of
|
|
95
|
+
* `log/<seq>`. The loser gets a 412 and re-probes forward to the next
|
|
96
|
+
* empty slot. A 412 from the writer's OWN session at the same seq is its
|
|
97
|
+
* own lost-ack / crashed-but-durable commit → adopted (not retried), so
|
|
98
|
+
* the write lands at EXACTLY `seq`, never duplicated.
|
|
53
99
|
*
|
|
54
|
-
* **
|
|
55
|
-
* `
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
* content
|
|
59
|
-
*
|
|
60
|
-
*
|
|
100
|
+
* **Crash safety.** Order is content + additive index `newKeys` →
|
|
101
|
+
* `log/<seq>` create → stale index-key DELETEs. A crash before the
|
|
102
|
+
* create leaves an unreferenced content body + orphan additive index
|
|
103
|
+
* keys (no log entry references them), not an orphan log entry with
|
|
104
|
+
* missing content — the compactor sweeps the content, and a stray
|
|
105
|
+
* additive key only ever yields a false-POSITIVE candidate that
|
|
106
|
+
* `matchesWire` (read path) drops. Emitting `newKeys` before the commit
|
|
107
|
+
* means a committed row is ALWAYS index-findable; the stale-key DELETE
|
|
108
|
+
* stays after the commit so a crash can never de-index a committed
|
|
109
|
+
* doc. See `index-emit-order.test.ts` and ADR-008 Q4.
|
|
61
110
|
*
|
|
62
111
|
* **`LogEntry` shape.** Emitted entries follow the contract in
|
|
63
112
|
* `packages/protocol/src/log.ts` (see {@link LogEntry}) and
|
|
@@ -127,33 +176,33 @@ var Writer = class {
|
|
|
127
176
|
this.#verifyLogIntegrityOnCommit = opts.options?.verifyLogIntegrityOnCommit ?? false;
|
|
128
177
|
}
|
|
129
178
|
/**
|
|
130
|
-
* Atomically commit one mutation. Reads `current.json` fresh
|
|
131
|
-
*
|
|
132
|
-
*
|
|
133
|
-
* `If-Match
|
|
179
|
+
* Atomically commit one mutation. Reads `current.json` fresh (as a
|
|
180
|
+
* probe FLOOR, not a CAS precondition), PUTs the content body and any
|
|
181
|
+
* additive index `newKeys`, then creates `log/<seq>` via
|
|
182
|
+
* `If-None-Match: "*"` — that create IS the commit (single-write
|
|
183
|
+
* commit; no `current.json` CAS follows it). Stale index keys are
|
|
184
|
+
* DELETE'd after the commit.
|
|
134
185
|
*
|
|
135
|
-
* The hot-path cost under no contention
|
|
136
|
-
*
|
|
137
|
-
*
|
|
186
|
+
* The hot-path cost under no contention on an unindexed collection is
|
|
187
|
+
* 1 GET + 2 PUTs (content + the committing `log/<seq>` create); each
|
|
188
|
+
* declared index that projects a key on this write adds one PUT
|
|
189
|
+
* (new key, before the commit) and, on U/D, up to one DELETE (stale
|
|
190
|
+
* key, after the commit). An in-flight peer write costs one extra GET
|
|
191
|
+
* + the backoff sleep per retry.
|
|
138
192
|
*
|
|
139
193
|
* Idempotency: PUT content uses `If-None-Match: "*"`, so a retry of
|
|
140
194
|
* the same logical write produces the same content key and the
|
|
141
|
-
* second PUT no-ops.
|
|
142
|
-
* so two writers racing the same
|
|
143
|
-
* to
|
|
195
|
+
* second PUT no-ops. The `log/<seq>` create also uses
|
|
196
|
+
* `If-None-Match: "*"`, so two writers racing the same tail cause
|
|
197
|
+
* exactly one create to win; the loser reads back the occupant,
|
|
198
|
+
* adopts its own lost-ack write or re-probes forward to the next
|
|
199
|
+
* empty slot.
|
|
144
200
|
*
|
|
145
|
-
* @throws BaerlyError code="Conflict" when
|
|
146
|
-
*
|
|
147
|
-
*
|
|
148
|
-
* @throws BaerlyError code="Conflict" — the writer fence
|
|
149
|
-
* (`current.json.writer_fence.epoch`) was bumped by a concurrent
|
|
150
|
-
* `claimWriter` call between this commit's read of
|
|
151
|
-
* `current.json` and its CAS-advance. The stale writer aborts
|
|
152
|
-
* to honour the new authority — the kernel does NOT retry under
|
|
153
|
-
* the old epoch. See {@link claimWriter} for the rotation
|
|
154
|
-
* recipe.
|
|
201
|
+
* @throws BaerlyError code="Conflict" when a retryable conflict
|
|
202
|
+
* escapes the single-attempt helper and exhausts the retry budget
|
|
203
|
+
* (presently unreachable on the log-create 412 path).
|
|
155
204
|
* @throws BaerlyError code="Internal" when a log entry expected in
|
|
156
|
-
* `[0,
|
|
205
|
+
* `[0, tail_hint)` is missing — a protocol-invariant violation
|
|
157
206
|
* (compactor bug or stale `current.json`).
|
|
158
207
|
* @throws BaerlyError code="InvalidResponse" when a log-entry body
|
|
159
208
|
* isn't valid JSON.
|
|
@@ -167,18 +216,18 @@ var Writer = class {
|
|
|
167
216
|
* and re-reads to pick up the winner's manifest.
|
|
168
217
|
*/
|
|
169
218
|
async commit(input) {
|
|
219
|
+
assertDocId(input.docId);
|
|
170
220
|
const session = uuid().slice(0, 6);
|
|
171
221
|
const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
|
|
172
222
|
for (let attempt = 1; attempt <= this.#maxRetries; attempt++) {
|
|
173
223
|
let success;
|
|
174
224
|
try {
|
|
175
|
-
success = await this.#singleAttemptCommit([input], session, logPrefix, "Writer"
|
|
225
|
+
success = await this.#singleAttemptCommit([input], session, logPrefix, "Writer");
|
|
176
226
|
} catch (error) {
|
|
177
227
|
if (!isPreconditionFailed(error)) throw error;
|
|
178
228
|
await this.#backoff(attempt);
|
|
179
229
|
continue;
|
|
180
230
|
}
|
|
181
|
-
await this.#verifyFenceUnchanged(success.expectedEpoch, "Writer");
|
|
182
231
|
this.#emitWriteMetrics(input.collection, success.classAOps + (attempt - 1));
|
|
183
232
|
return {
|
|
184
233
|
entry: success.entries[0],
|
|
@@ -189,117 +238,68 @@ var Writer = class {
|
|
|
189
238
|
throw new BaerlyError("Conflict", `Writer: CAS conflict on ${this.#currentJsonKey} after ${this.#maxRetries} attempts`);
|
|
190
239
|
}
|
|
191
240
|
/**
|
|
192
|
-
*
|
|
193
|
-
* `
|
|
194
|
-
*
|
|
195
|
-
*
|
|
196
|
-
*
|
|
197
|
-
*
|
|
198
|
-
*
|
|
199
|
-
* NO retry on CAS loss. On `current.json` 412, throws
|
|
200
|
-
* `BaerlyError{code:"Conflict"}` immediately — the caller (here:
|
|
201
|
-
* `Db.transaction`) decides whether to retry by re-running the
|
|
202
|
-
* body, or to surface to the app. Likewise on a log-entry 412
|
|
203
|
-
* (a peer wrote our seq).
|
|
241
|
+
* One full commit attempt — the body of {@link commit}. Reads
|
|
242
|
+
* `current.json`, PUTs content + additive index `newKeys` in parallel,
|
|
243
|
+
* then forward-probes the tail and creates `log/<seq>` once via
|
|
244
|
+
* `If-None-Match: "*"` — the numbered log create IS the commit
|
|
245
|
+
* (single-write commit; no `current.json` CAS follows it). Stale index
|
|
246
|
+
* keys are DELETE'd after the commit. Returns the success payload.
|
|
204
247
|
*
|
|
205
|
-
*
|
|
206
|
-
*
|
|
248
|
+
* Called only as `#singleAttemptCommit([input], …)`: the array shape
|
|
249
|
+
* is retained dead-generality (D1.5), but every call commits exactly
|
|
250
|
+
* one entry.
|
|
207
251
|
*
|
|
208
|
-
*
|
|
209
|
-
*
|
|
210
|
-
*
|
|
211
|
-
*
|
|
212
|
-
*
|
|
213
|
-
* `current.json` and its CAS-advance. The stale writer aborts
|
|
214
|
-
* to honour the new authority — the kernel does NOT retry under
|
|
215
|
-
* the old epoch. See {@link claimWriter} for the rotation
|
|
216
|
-
* recipe.
|
|
217
|
-
* @throws BaerlyError code="Internal" — protocol-invariant violation
|
|
218
|
-
* (missing log entry inside `[0, next_seq)`).
|
|
219
|
-
* @throws BaerlyError code="InvalidResponse" — malformed log body.
|
|
252
|
+
* A log-create 412 is disambiguated by session read-back: own session
|
|
253
|
+
* / own seq ⇒ our crashed-or-lost-ack commit is already durable ⇒
|
|
254
|
+
* adopt; foreign session ⇒ re-probe forward and retry at the next
|
|
255
|
+
* empty slot. Thrown `BaerlyError`s (Internal, InvalidResponse,
|
|
256
|
+
* NetworkError) propagate.
|
|
220
257
|
*
|
|
221
|
-
*
|
|
222
|
-
*
|
|
223
|
-
*
|
|
224
|
-
*
|
|
225
|
-
*
|
|
226
|
-
*
|
|
258
|
+
* Crash safety invariant: content + additive index `newKeys` PUTs are
|
|
259
|
+
* awaited before the log create. A crash before the create leaves
|
|
260
|
+
* orphan content + additive index keys (no log entry references them)
|
|
261
|
+
* — the compactor sweeps the content, and a stray additive key only
|
|
262
|
+
* yields a false-positive candidate that `matchesWire` drops. A crash
|
|
263
|
+
* AFTER the create is a durable, committed write at `seq` whose index
|
|
264
|
+
* `newKeys` are already present (so it's index-findable); the only
|
|
265
|
+
* residual is a possibly-undeleted stale OLD-value key, dropped by
|
|
266
|
+
* `matchesWire` and cleaned by a later write / `rebuild-index`. The
|
|
267
|
+
* inverse — committed log entry with missing content, or a de-indexed
|
|
268
|
+
* committed doc — is never produced.
|
|
227
269
|
*/
|
|
228
|
-
async
|
|
229
|
-
if (inputs.length === 0) return {
|
|
230
|
-
entries: [],
|
|
231
|
-
currentEtag: void 0
|
|
232
|
-
};
|
|
233
|
-
const session = uuid().slice(0, 6);
|
|
234
|
-
const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
|
|
235
|
-
const success = await this.#singleAttemptCommit(inputs, session, logPrefix, "Writer.commitBatch", false);
|
|
236
|
-
await this.#verifyFenceUnchanged(success.expectedEpoch, "Writer.commitBatch");
|
|
237
|
-
this.#emitWriteMetrics(inputs[0].collection, success.classAOps);
|
|
238
|
-
return {
|
|
239
|
-
entries: success.entries,
|
|
240
|
-
currentEtag: success.currentEtag
|
|
241
|
-
};
|
|
242
|
-
}
|
|
243
|
-
/**
|
|
244
|
-
* One full commit attempt — the shared body of {@link commit} and
|
|
245
|
-
* {@link commitBatch}. Reads `current.json`, walks the log, mints N
|
|
246
|
-
* entries, PUTs content + indexes in parallel, PUTs log entries,
|
|
247
|
-
* CAS-advances `current.json`. Returns the success payload + the
|
|
248
|
-
* pre-commit fence epoch so the caller can run
|
|
249
|
-
* {@link #verifyFenceUnchanged} outside the retry-catch arm.
|
|
250
|
-
*
|
|
251
|
-
* Retryable failures (a peer wrote our seq; a peer won the CAS on
|
|
252
|
-
* `current.json`) throw `BaerlyError{code:"Conflict"}`. The caller
|
|
253
|
-
* catches via {@link isPreconditionFailed} and either retries
|
|
254
|
-
* (`commit`) or surfaces (`commitBatch`). Fence-bump and protocol-
|
|
255
|
-
* invariant violations are NOT thrown from this helper — the fence
|
|
256
|
-
* check lives in the caller so its `Conflict` propagates past the
|
|
257
|
-
* retry-catch arm. Other thrown `BaerlyError`s (Internal,
|
|
258
|
-
* InvalidResponse, NetworkError) bypass `isPreconditionFailed` and
|
|
259
|
-
* propagate naturally.
|
|
260
|
-
*
|
|
261
|
-
* Crash safety invariant: content / index PUTs are awaited before
|
|
262
|
-
* log PUTs, which are awaited before the CAS. A crashed mid-attempt
|
|
263
|
-
* writer leaves orphan content / index entries (no log entry
|
|
264
|
-
* references them) — the compactor sweeps the orphans. The
|
|
265
|
-
* inverse — orphan log entry with missing content — is never
|
|
266
|
-
* produced.
|
|
267
|
-
*/
|
|
268
|
-
async #singleAttemptCommit(inputs, session, logPrefix, errorPrefix, adoptOwnSessionOnLogConflict) {
|
|
270
|
+
async #singleAttemptCommit(inputs, session, logPrefix, errorPrefix) {
|
|
269
271
|
const read = await readCurrentJson(this.#storage, this.#currentJsonKey) ?? await this.#provisionCurrentJson();
|
|
270
272
|
const current = read.json;
|
|
271
273
|
const baseEtag = read.etag;
|
|
272
|
-
|
|
273
|
-
|
|
274
|
+
if (this.#verifyLogIntegrityOnCommit) await this.#walkLog(logPrefix, logSeqStartOf(current), current.tail_hint);
|
|
275
|
+
const probeFloor = Math.max(logSeqStartOf(current), current.tail_hint);
|
|
276
|
+
const preCommitTail = await findLogTail(this.#storage, logPrefix, probeFloor);
|
|
277
|
+
let seq = preCommitTail;
|
|
274
278
|
const commitNowMs = Date.now();
|
|
275
279
|
const commitTs = new Date(commitNowMs).toISOString();
|
|
276
280
|
const lsnTimestamp = timestamp(commitNowMs);
|
|
277
|
-
const
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
...input.origin !== void 0 ? { origin: input.origin } : {}
|
|
291
|
-
};
|
|
292
|
-
entries.push(entry);
|
|
293
|
-
}
|
|
281
|
+
const input0 = inputs[0];
|
|
282
|
+
const mintEntry = (atSeq) => ({
|
|
283
|
+
lsn: `${lsnTimestamp}_${session}_${countKey(atSeq)}`,
|
|
284
|
+
commit_ts: commitTs,
|
|
285
|
+
op: input0.op,
|
|
286
|
+
collection: input0.collection,
|
|
287
|
+
doc_id: input0.docId,
|
|
288
|
+
session,
|
|
289
|
+
seq: atSeq,
|
|
290
|
+
...input0.op !== "D" && input0.body !== void 0 ? { after: input0.body } : {},
|
|
291
|
+
...input0.origin !== void 0 ? { origin: input0.origin } : {}
|
|
292
|
+
});
|
|
293
|
+
let entry = mintEntry(seq);
|
|
294
294
|
let contentPutCount = 0;
|
|
295
|
-
let
|
|
295
|
+
let newKeysClassA = 0;
|
|
296
296
|
const parallelPuts = [];
|
|
297
|
-
const inBatchImage = /* @__PURE__ */ new Map();
|
|
298
297
|
for (const input of inputs) {
|
|
299
298
|
if (input.op !== "D" && input.body !== void 0) {
|
|
300
299
|
contentPutCount++;
|
|
301
300
|
const bytes = encodeJsonBytes(input.body);
|
|
302
301
|
const contentKey = `${logPrefix}/content/${await versionFromContent(bytes)}.json`;
|
|
302
|
+
assertKeyWithinLimit(contentKey);
|
|
303
303
|
parallelPuts.push(this.#storage.put(contentKey, bytes, {
|
|
304
304
|
ifNoneMatch: "*",
|
|
305
305
|
contentType: APPLICATION_JSON
|
|
@@ -309,140 +309,94 @@ var Writer = class {
|
|
|
309
309
|
throw error;
|
|
310
310
|
}));
|
|
311
311
|
}
|
|
312
|
-
if (this.#indexes.length > 0) {
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
312
|
+
if (this.#indexes.length > 0 && input.op !== "D") {
|
|
313
|
+
const newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
|
|
314
|
+
for (const k of newKeys) {
|
|
315
|
+
assertKeyWithinLimit(k);
|
|
316
|
+
newKeysClassA++;
|
|
317
|
+
parallelPuts.push(this.#storage.put(k, EMPTY_BODY, {
|
|
318
|
+
ifNoneMatch: "*",
|
|
319
|
+
contentType: APPLICATION_JSON
|
|
320
|
+
}).catch((error) => {
|
|
321
|
+
this.#observe429(error, input.collection);
|
|
322
|
+
if (isPreconditionFailed(error)) return;
|
|
323
|
+
throw error;
|
|
324
|
+
}));
|
|
325
325
|
}
|
|
326
|
-
for (const k of newKeys) parallelPuts.push(this.#storage.put(k, EMPTY_BODY, {
|
|
327
|
-
ifNoneMatch: "*",
|
|
328
|
-
contentType: APPLICATION_JSON
|
|
329
|
-
}).catch((error) => {
|
|
330
|
-
this.#observe429(error, input.collection);
|
|
331
|
-
if (isPreconditionFailed(error)) return;
|
|
332
|
-
throw error;
|
|
333
|
-
}));
|
|
334
|
-
for (const k of staleKeys) parallelPuts.push(this.#storage.delete(k));
|
|
335
|
-
indexClassA += newKeys.length + staleKeys.length;
|
|
336
|
-
if (newKeys.length + staleKeys.length > 0) ctxMetrics().histogram("db.write.index_ops_per_logical_write", newKeys.length + staleKeys.length, { collection: input.collection });
|
|
337
|
-
inBatchImage.set(input.docId, input.op === "D" ? void 0 : input.body);
|
|
338
326
|
}
|
|
339
327
|
}
|
|
340
328
|
await Promise.all(parallelPuts);
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
329
|
+
let committedEntry = entry;
|
|
330
|
+
let probes = 0;
|
|
331
|
+
let transientRetries = 0;
|
|
332
|
+
for (;;) {
|
|
333
|
+
const logEntryKey = logObjectKey(logPrefix, seq);
|
|
334
|
+
assertKeyWithinLimit(logEntryKey);
|
|
335
|
+
let conflicted = false;
|
|
344
336
|
try {
|
|
345
|
-
await this.#storage.put(logEntryKey,
|
|
337
|
+
await this.#storage.put(logEntryKey, encodeJsonBytes(entry), {
|
|
346
338
|
ifNoneMatch: "*",
|
|
347
339
|
contentType: APPLICATION_JSON
|
|
348
340
|
});
|
|
349
|
-
return { ok: true };
|
|
350
341
|
} catch (error) {
|
|
351
342
|
this.#observe429(error, entry.collection);
|
|
352
|
-
if (
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
343
|
+
if (isPreconditionFailed(error)) {
|
|
344
|
+
ctxMetrics().counter("db.r2.put.412_total", 1, {
|
|
345
|
+
collection: entry.collection,
|
|
346
|
+
step: "log-put"
|
|
347
|
+
});
|
|
348
|
+
conflicted = true;
|
|
349
|
+
} else if (isTransientWrite(error) && transientRetries < this.#maxRetries) {
|
|
350
|
+
transientRetries++;
|
|
351
|
+
await this.#backoff(transientRetries);
|
|
352
|
+
continue;
|
|
353
|
+
} else throw error;
|
|
358
354
|
}
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
const
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
if (decision.adopt) committedEntries = [decision.entry];
|
|
373
|
-
else throw new BaerlyError("Conflict", `${errorPrefix}: log entry already exists at ${logEntryKey}; ${decision.reason}`);
|
|
374
|
-
} else throw new BaerlyError("Conflict", `${errorPrefix}: log entry already exists at ${logEntryKey}; peer wrote our seq`);
|
|
375
|
-
}
|
|
376
|
-
const batchLogBytes = committedEntries.reduce((sum, e) => sum + encodeJsonBytes(e).byteLength, 0);
|
|
377
|
-
const next = {
|
|
378
|
-
...current,
|
|
379
|
-
next_seq: current.next_seq + inputs.length,
|
|
380
|
-
tail_bytes: current.tail_bytes + batchLogBytes
|
|
381
|
-
};
|
|
382
|
-
if (next.next_seq - current.next_seq !== inputs.length) throw new BaerlyError("Internal", `${errorPrefix}: GC-cadence invariant violated — next_seq advanced by ${next.next_seq - current.next_seq} but ${inputs.length} input(s) were committed on ${this.#currentJsonKey}`);
|
|
383
|
-
const nextBody = encodeJsonBytes(next);
|
|
384
|
-
const putOpts = {
|
|
385
|
-
ifMatch: baseEtag,
|
|
386
|
-
contentType: APPLICATION_JSON
|
|
387
|
-
};
|
|
388
|
-
let result;
|
|
389
|
-
try {
|
|
390
|
-
result = await this.#storage.put(this.#currentJsonKey, nextBody, putOpts);
|
|
391
|
-
} catch (error) {
|
|
392
|
-
this.#observe429(error, inputs[0].collection);
|
|
393
|
-
if (isPreconditionFailed(error)) {
|
|
394
|
-
ctxMetrics().counter("db.r2.put.412_total", 1, {
|
|
395
|
-
collection: inputs[0].collection,
|
|
396
|
-
step: "current-json-cas"
|
|
397
|
-
});
|
|
398
|
-
throw new BaerlyError("Conflict", `${errorPrefix}: CAS conflict on ${this.#currentJsonKey}`);
|
|
355
|
+
if (!conflicted) {
|
|
356
|
+
committedEntry = entry;
|
|
357
|
+
break;
|
|
358
|
+
}
|
|
359
|
+
const existing = await readLogEntry(this.#storage, logEntryKey);
|
|
360
|
+
const decision = tryAdoptOwnSessionLogEntry({
|
|
361
|
+
self: entry,
|
|
362
|
+
existing,
|
|
363
|
+
batchSize: inputs.length
|
|
364
|
+
});
|
|
365
|
+
if (decision.adopt) {
|
|
366
|
+
committedEntry = decision.entry;
|
|
367
|
+
break;
|
|
399
368
|
}
|
|
400
|
-
throw
|
|
369
|
+
if (++probes > 1e5) throw new BaerlyError("Internal", `${errorPrefix}: log-tail forward-probe exceeded ${LOG_FORWARD_PROBE_CAP} on ${this.#currentJsonKey}`);
|
|
370
|
+
seq = await findLogTail(this.#storage, logPrefix, seq + 1);
|
|
371
|
+
entry = mintEntry(seq);
|
|
401
372
|
}
|
|
402
|
-
const
|
|
373
|
+
const committedEntries = [committedEntry];
|
|
374
|
+
const staleKeysClassA = await this.#cleanupStaleIndexKeysBestEffort({
|
|
375
|
+
inputs,
|
|
376
|
+
logPrefix,
|
|
377
|
+
seq
|
|
378
|
+
});
|
|
379
|
+
const indexClassA = newKeysClassA + staleKeysClassA;
|
|
380
|
+
if (this.#indexes.length > 0 && indexClassA > 0) ctxMetrics().histogram("db.write.index_ops_per_logical_write", indexClassA, { collection: input0.collection });
|
|
381
|
+
const prevSeq = preCommitTail;
|
|
382
|
+
const observedTail = seq + 1;
|
|
403
383
|
const maint = getCurrentContext()?.maintenance;
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
384
|
+
const gcInterval = maint?.options?.profile?.gcInterval ?? MAINTENANCE_PROFILE_CF_FREE.gcInterval;
|
|
385
|
+
if (maint?.disabled === true ? observedTail - current.tail_hint >= 128 : shouldFireMaintenance(current, prevSeq, gcInterval, observedTail)) await (maint?.dispatch ?? dispatchInlineAwaited)(() => runBoundedMaintenance({
|
|
386
|
+
storage: this.#storage,
|
|
387
|
+
currentJsonKey: this.#currentJsonKey,
|
|
388
|
+
prevSeq,
|
|
389
|
+
observedTail,
|
|
390
|
+
...maint?.disabled === true && { disabled: true },
|
|
391
|
+
...maint?.maxFoldBytes !== void 0 && { maxFoldBytes: maint.maxFoldBytes }
|
|
392
|
+
}, maint?.options).then(() => {}, () => {}));
|
|
413
393
|
return {
|
|
414
394
|
entries: committedEntries,
|
|
415
|
-
currentEtag:
|
|
416
|
-
classAOps
|
|
417
|
-
expectedEpoch
|
|
395
|
+
currentEtag: baseEtag,
|
|
396
|
+
classAOps: contentPutCount + 1 + indexClassA
|
|
418
397
|
};
|
|
419
398
|
}
|
|
420
399
|
/**
|
|
421
|
-
* Read the pre-image content body for a doc by walking the live
|
|
422
|
-
* log backwards from `currentNextSeq` looking for the
|
|
423
|
-
* most-recent I/U entry on this `(collection, docId)`. Returns
|
|
424
|
-
* `undefined` when:
|
|
425
|
-
*
|
|
426
|
-
* - the doc's most-recent op was `D` (tombstone — no live body);
|
|
427
|
-
* - no entry for this doc lives inside the visible log range
|
|
428
|
-
* `[log_seq_start, currentNextSeq)` (a fresh-insert race or
|
|
429
|
-
* the doc has been folded into the snapshot but is no longer
|
|
430
|
-
* referenced).
|
|
431
|
-
*
|
|
432
|
-
* Used ONLY by the index-emission path on `U` / `D` to compute
|
|
433
|
-
* the stale-key set. Bounded by `log_seq_start`: entries below
|
|
434
|
-
* have been folded into the snapshot and may already be swept
|
|
435
|
-
* off the bucket — a snapshot fold is the rebuild command's job
|
|
436
|
-
* (see `./rebuild-index.ts`), not the writer's.
|
|
437
|
-
*
|
|
438
|
-
* **Cost note:** linear walk, O(snapshot lag). For day-one Phase
|
|
439
|
-
* 8 collections (helpdesk-shape: 100s of docs, <10k log entries)
|
|
440
|
-
* this is fine — the compactor folds the live tail every ~100
|
|
441
|
-
* entries (`packages/server/src/compactor.ts`). A follow-up ticket
|
|
442
|
-
* caches per-doc index head in `current.json` for O(1) lookup.
|
|
443
|
-
* The bound is documented; out of scope here.
|
|
444
|
-
*/
|
|
445
|
-
/**
|
|
446
400
|
* Auto-create the per-collection `current.json` at
|
|
447
401
|
* `this.#currentJsonKey` with a zero-state initial manifest. Called
|
|
448
402
|
* by `#singleAttemptCommit` when the read returned `null` (fresh
|
|
@@ -454,7 +408,7 @@ var Writer = class {
|
|
|
454
408
|
* the create — a single recover-via-read covers every race that
|
|
455
409
|
* could have produced our null read.
|
|
456
410
|
*
|
|
457
|
-
* The seed shape (`snapshot: null`, `
|
|
411
|
+
* The seed shape (`snapshot: null`, `tail_hint: 0`, `log_seq_start:
|
|
458
412
|
* 0`, `writer_fence: { epoch: 0, owner: "", claimed_at: "" }`)
|
|
459
413
|
* matches `ensureTable` and `baerly deploy`'s pre-warm path, so an
|
|
460
414
|
* operator who pre-provisions and a writer who auto-creates land
|
|
@@ -466,16 +420,15 @@ var Writer = class {
|
|
|
466
420
|
*/
|
|
467
421
|
async #provisionCurrentJson() {
|
|
468
422
|
const initial = {
|
|
469
|
-
schema_version:
|
|
423
|
+
schema_version: 3,
|
|
470
424
|
snapshot: null,
|
|
471
|
-
|
|
425
|
+
tail_hint: 0,
|
|
472
426
|
log_seq_start: 0,
|
|
473
427
|
writer_fence: {
|
|
474
428
|
epoch: 0,
|
|
475
429
|
owner: "",
|
|
476
430
|
claimed_at: ""
|
|
477
431
|
},
|
|
478
|
-
tail_bytes: 0,
|
|
479
432
|
snapshot_bytes: 0,
|
|
480
433
|
snapshot_rows: 0
|
|
481
434
|
};
|
|
@@ -488,9 +441,69 @@ var Writer = class {
|
|
|
488
441
|
if (recovered === null) throw new BaerlyError("InvalidResponse", `Writer: current.json missing at ${this.#currentJsonKey} after auto-create raced and recover read returned null`);
|
|
489
442
|
return recovered;
|
|
490
443
|
}
|
|
444
|
+
async #cleanupStaleIndexKeysBestEffort(args) {
|
|
445
|
+
if (this.#indexes.length === 0) return 0;
|
|
446
|
+
let staleKeysClassA = 0;
|
|
447
|
+
const indexDeletes = [];
|
|
448
|
+
const inBatchImage = /* @__PURE__ */ new Map();
|
|
449
|
+
for (const input of args.inputs) {
|
|
450
|
+
let staleKeys = [];
|
|
451
|
+
try {
|
|
452
|
+
if (input.op === "U") {
|
|
453
|
+
const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(args.logPrefix, input.collection, input.docId, args.seq);
|
|
454
|
+
const oldKeys = allIndexKeysFor(args.logPrefix, this.#indexes, preImage, input.docId);
|
|
455
|
+
const newSet = new Set(allIndexKeysFor(args.logPrefix, this.#indexes, input.body, input.docId));
|
|
456
|
+
staleKeys = oldKeys.filter((k) => !newSet.has(k));
|
|
457
|
+
} else if (input.op === "D") {
|
|
458
|
+
const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(args.logPrefix, input.collection, input.docId, args.seq);
|
|
459
|
+
staleKeys = allIndexKeysFor(args.logPrefix, this.#indexes, preImage, input.docId);
|
|
460
|
+
}
|
|
461
|
+
} catch {
|
|
462
|
+
ctxMetrics().counter("db.write.index_cleanup_errors_total", 1, {
|
|
463
|
+
collection: input.collection,
|
|
464
|
+
step: "pre-image-read"
|
|
465
|
+
});
|
|
466
|
+
inBatchImage.set(input.docId, input.op === "D" ? void 0 : input.body);
|
|
467
|
+
continue;
|
|
468
|
+
}
|
|
469
|
+
for (const k of staleKeys) indexDeletes.push(this.#storage.delete(k).catch(() => {
|
|
470
|
+
ctxMetrics().counter("db.write.index_cleanup_errors_total", 1, {
|
|
471
|
+
collection: input.collection,
|
|
472
|
+
step: "delete"
|
|
473
|
+
});
|
|
474
|
+
}));
|
|
475
|
+
staleKeysClassA += staleKeys.length;
|
|
476
|
+
inBatchImage.set(input.docId, input.op === "D" ? void 0 : input.body);
|
|
477
|
+
}
|
|
478
|
+
await Promise.all(indexDeletes);
|
|
479
|
+
return staleKeysClassA;
|
|
480
|
+
}
|
|
481
|
+
/**
|
|
482
|
+
* Read the pre-image content body for a doc by walking the live log
|
|
483
|
+
* backwards from `currentNextSeq` looking for the most-recent I/U
|
|
484
|
+
* entry on this `(collection, docId)`. Returns `undefined` when:
|
|
485
|
+
*
|
|
486
|
+
* - the doc's most-recent op was `D` (tombstone — no live body);
|
|
487
|
+
* - no entry for this doc lives inside the visible log range
|
|
488
|
+
* `[log_seq_start, currentNextSeq)` (a fresh-insert race or the
|
|
489
|
+
* doc has been folded into the snapshot but is no longer
|
|
490
|
+
* referenced).
|
|
491
|
+
*
|
|
492
|
+
* Used ONLY by the index-emission path's stale-key half (Step 5b, on
|
|
493
|
+
* `U` / `D`) to compute which OLD-value keys to DELETE. Bounded by
|
|
494
|
+
* `log_seq_start`: entries below have been folded into the snapshot
|
|
495
|
+
* and may already be swept off the bucket — a snapshot fold is the
|
|
496
|
+
* rebuild command's job (see `./rebuild-index.ts`), not the writer's.
|
|
497
|
+
*
|
|
498
|
+
* **Cost note:** linear walk, O(snapshot lag). For helpdesk-shape
|
|
499
|
+
* collections (100s of docs, <10k log entries) this is fine — the
|
|
500
|
+
* compactor folds the live tail every ~100 entries
|
|
501
|
+
* (`packages/server/src/compactor.ts`). A follow-up ticket caches
|
|
502
|
+
* per-doc index head in `current.json` for O(1) lookup.
|
|
503
|
+
*/
|
|
491
504
|
async #readPreImage(logPrefix, collection, docId, currentNextSeq) {
|
|
492
505
|
for (let s = currentNextSeq - 1; s >= 0; s--) {
|
|
493
|
-
const logKey =
|
|
506
|
+
const logKey = logObjectKey(logPrefix, s);
|
|
494
507
|
const got = await this.#storage.get(logKey);
|
|
495
508
|
if (got === null) continue;
|
|
496
509
|
let entry;
|
|
@@ -535,32 +548,14 @@ var Writer = class {
|
|
|
535
548
|
}
|
|
536
549
|
/**
|
|
537
550
|
* Emit the per-logical-write `class_a_ops_per_logical_write`
|
|
538
|
-
* histogram
|
|
539
|
-
*
|
|
540
|
-
*
|
|
551
|
+
* histogram for `commit`. `classAOps` is the per-attempt base plus
|
|
552
|
+
* a charge for prior failed attempts (the retry-budget cost model),
|
|
553
|
+
* computed by the caller.
|
|
541
554
|
*/
|
|
542
555
|
#emitWriteMetrics(collection, classAOps) {
|
|
543
556
|
ctxMetrics().histogram("db.write.class_a_ops_per_logical_write", classAOps, { collection });
|
|
544
557
|
}
|
|
545
558
|
/**
|
|
546
|
-
* Re-read `current.json` after a successful CAS and assert the
|
|
547
|
-
* writer-fence epoch is still ours. The CAS only mutated `next_seq`
|
|
548
|
-
* (the fence is preserved from `current`), so a post-write epoch
|
|
549
|
-
* mismatch can only mean another writer claimed the fence between
|
|
550
|
-
* our step-1 read and step-6 PUT — the exact split-brain
|
|
551
|
-
* `WriterFence` prevents. Throws `Conflict`; no retry, since the
|
|
552
|
-
* stale writer must defer to the new authority.
|
|
553
|
-
*
|
|
554
|
-
* The fence-verify GET is Class B and intentionally NOT counted in
|
|
555
|
-
* `class_a_ops_per_logical_write`.
|
|
556
|
-
*/
|
|
557
|
-
async #verifyFenceUnchanged(expectedEpoch, where) {
|
|
558
|
-
const postRead = await readCurrentJson(this.#storage, this.#currentJsonKey);
|
|
559
|
-
if (postRead === null) return;
|
|
560
|
-
if (postRead.json.writer_fence.epoch === expectedEpoch) return;
|
|
561
|
-
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`);
|
|
562
|
-
}
|
|
563
|
-
/**
|
|
564
559
|
* Exponential backoff with full jitter. `25 * 2^(attempt-1)` capped
|
|
565
560
|
* at 1500ms; uniform jitter in `[0, base)` keeps colliding peers
|
|
566
561
|
* from re-racing in lockstep. Worst-case total wait across the
|
|
@@ -580,6 +575,13 @@ var Writer = class {
|
|
|
580
575
|
*/
|
|
581
576
|
const isPreconditionFailed = (err) => err instanceof BaerlyError && err.code === "Conflict";
|
|
582
577
|
/**
|
|
578
|
+
* `true` when a log-create PUT failed transiently (a `NetworkError`) —
|
|
579
|
+
* the write may or may not have landed (a dropped ack). Safe to retry
|
|
580
|
+
* the SAME seq: own-session adoption closes the double-commit window if
|
|
581
|
+
* it did land. NOT a 412 (that's handled by adoption directly).
|
|
582
|
+
*/
|
|
583
|
+
const isTransientWrite = (err) => err instanceof BaerlyError && err.code === "NetworkError";
|
|
584
|
+
/**
|
|
583
585
|
* `true` when the underlying storage surfaced an R2 prefix-partition
|
|
584
586
|
* rate-limit. {@link S3HttpStorage} stamps the upstream HTTP status
|
|
585
587
|
* onto `BaerlyError.cause` as `{ status }`; we discriminate on that
|
|
@@ -600,22 +602,25 @@ const is429 = (err) => {
|
|
|
600
602
|
* integration test) can divert the input by passing
|
|
601
603
|
* `{ streams: { stdin } }` to {@link runRestore}. Idempotent on a fresh
|
|
602
604
|
* bucket: re-running on a half-completed restore **refuses** unless
|
|
603
|
-
* `--force` is set (which
|
|
604
|
-
*
|
|
605
|
+
* `--force` is set (which reseeds a fresh `current.json` above the old
|
|
606
|
+
* tail first).
|
|
605
607
|
*
|
|
606
608
|
* Args:
|
|
607
609
|
* --bucket Required. Target bucket URI.
|
|
608
610
|
* --app Required (or via baerly.config.ts).
|
|
609
611
|
* --tenant Required (or via baerly.config.ts).
|
|
610
612
|
* --collection Required. Target collection name.
|
|
611
|
-
* --force Truncate the target if it exists (
|
|
613
|
+
* --force Truncate the target if it exists (reseed above the old tail).
|
|
612
614
|
* --json JSON envelope.
|
|
613
615
|
*
|
|
614
616
|
* stdin: NDJSON, one `{_id, ...}` row per line. Empty lines tolerated.
|
|
615
617
|
* EOF terminates.
|
|
616
618
|
*
|
|
617
|
-
* Cost shape:
|
|
618
|
-
*
|
|
619
|
+
* Cost shape: under single-write commit each `Writer.commit` is 2 Class
|
|
620
|
+
* A PUTs (content + the committing `log/<seq>` create — no per-row
|
|
621
|
+
* `current.json` write). So: 1 PUT current.json (initial seed) + N × 2
|
|
622
|
+
* + 1 PUT current.json (final `tail_hint` stamp) = 2N + 2 Class A ops
|
|
623
|
+
* for N rows.
|
|
619
624
|
*
|
|
620
625
|
* Partial-restore semantics: a mid-stream Network / Internal / parse
|
|
621
626
|
* error leaves the target in a partial state (some rows committed,
|
|
@@ -633,65 +638,81 @@ const is429 = (err) => {
|
|
|
633
638
|
* concurrent writer when --force was used.
|
|
634
639
|
*/
|
|
635
640
|
const RESTORE_OWNER = "baerly-restore";
|
|
641
|
+
const RESTORE_ARGS = {
|
|
642
|
+
bucket: {
|
|
643
|
+
type: "string",
|
|
644
|
+
required: true,
|
|
645
|
+
description: "Target bucket URI (s3://<bucket>[/<prefix>], file:///<abs>, memory://<bucket>)",
|
|
646
|
+
valueHint: "bucket-uri"
|
|
647
|
+
},
|
|
648
|
+
app: {
|
|
649
|
+
type: "string",
|
|
650
|
+
required: false,
|
|
651
|
+
description: "Application name segment (defaults to baerly.config.ts).",
|
|
652
|
+
valueHint: "app"
|
|
653
|
+
},
|
|
654
|
+
tenant: {
|
|
655
|
+
type: "string",
|
|
656
|
+
required: false,
|
|
657
|
+
description: "Tenant name segment (defaults to baerly.config.ts).",
|
|
658
|
+
valueHint: "tenant"
|
|
659
|
+
},
|
|
660
|
+
collection: {
|
|
661
|
+
type: "string",
|
|
662
|
+
required: true,
|
|
663
|
+
description: "Target collection name.",
|
|
664
|
+
valueHint: "name"
|
|
665
|
+
},
|
|
666
|
+
force: {
|
|
667
|
+
type: "boolean",
|
|
668
|
+
description: "Truncate the target if it exists (bump fence + reseed current.json)."
|
|
669
|
+
},
|
|
670
|
+
json: {
|
|
671
|
+
type: "boolean",
|
|
672
|
+
description: "Emit a structured JSON envelope to stdout (success) or stderr (error)"
|
|
673
|
+
}
|
|
674
|
+
};
|
|
675
|
+
const tailFromListedLogKeys = async (storage, collectionPrefix) => {
|
|
676
|
+
const logPrefix = `${collectionPrefix}/log/`;
|
|
677
|
+
let maxSeq = -1;
|
|
678
|
+
for await (const entry of storage.list(logPrefix)) {
|
|
679
|
+
const tail = entry.key.slice(logPrefix.length);
|
|
680
|
+
const match = /^(\d+)\.json$/.exec(tail);
|
|
681
|
+
if (match === null) continue;
|
|
682
|
+
const seq = Number.parseInt(match[1], 10);
|
|
683
|
+
if (Number.isFinite(seq) && seq > maxSeq) maxSeq = seq;
|
|
684
|
+
}
|
|
685
|
+
return maxSeq + 1;
|
|
686
|
+
};
|
|
636
687
|
const bundle = defineBaerlySubcommand({
|
|
637
688
|
name: "admin.restore",
|
|
638
689
|
meta: { description: "Bulk-import canonical NDJSON into a fresh collection." },
|
|
639
|
-
args:
|
|
640
|
-
bucket: {
|
|
641
|
-
type: "string",
|
|
642
|
-
required: true,
|
|
643
|
-
description: "Target bucket URI (s3://<bucket>[/<prefix>], file:///<abs>, memory://<bucket>)",
|
|
644
|
-
valueHint: "bucket-uri"
|
|
645
|
-
},
|
|
646
|
-
app: {
|
|
647
|
-
type: "string",
|
|
648
|
-
required: false,
|
|
649
|
-
description: "Application name segment (defaults to baerly.config.ts).",
|
|
650
|
-
valueHint: "app"
|
|
651
|
-
},
|
|
652
|
-
tenant: {
|
|
653
|
-
type: "string",
|
|
654
|
-
required: false,
|
|
655
|
-
description: "Tenant name segment (defaults to baerly.config.ts).",
|
|
656
|
-
valueHint: "tenant"
|
|
657
|
-
},
|
|
658
|
-
collection: {
|
|
659
|
-
type: "string",
|
|
660
|
-
required: true,
|
|
661
|
-
description: "Target collection name.",
|
|
662
|
-
valueHint: "name"
|
|
663
|
-
},
|
|
664
|
-
force: {
|
|
665
|
-
type: "boolean",
|
|
666
|
-
description: "Truncate the target if it exists (bump fence + reseed current.json)."
|
|
667
|
-
},
|
|
668
|
-
json: {
|
|
669
|
-
type: "boolean",
|
|
670
|
-
description: "Emit a structured JSON envelope to stdout (success) or stderr (error)"
|
|
671
|
-
}
|
|
672
|
-
},
|
|
690
|
+
args: RESTORE_ARGS,
|
|
673
691
|
handler: async (args, ctx) => {
|
|
674
692
|
const bucket = await parseBucketUri(args.bucket);
|
|
675
693
|
const { app, tenant } = await ctx.resolveAppTenant({
|
|
676
694
|
app: args.app,
|
|
677
695
|
tenant: args.tenant
|
|
678
696
|
});
|
|
697
|
+
assertCollectionArg(args.collection, "baerly admin restore");
|
|
679
698
|
const currentJsonKey = `${bucket.keyPrefix}app/${app}/tenant/${tenant}/manifests/${args.collection}/current.json`;
|
|
699
|
+
let baseSeq = 0;
|
|
680
700
|
const head = await readCurrentJson(bucket.storage, currentJsonKey);
|
|
681
701
|
if (head !== null && args.force !== true) throw new BaerlyError("Conflict", `baerly admin restore: ${currentJsonKey} exists; pass --force to truncate`);
|
|
682
702
|
if (head !== null) {
|
|
683
|
-
const
|
|
703
|
+
const collectionPrefix = currentJsonKey.slice(0, currentJsonKey.lastIndexOf("/"));
|
|
704
|
+
const truncatedNext = await tailFromListedLogKeys(bucket.storage, collectionPrefix);
|
|
705
|
+
baseSeq = truncatedNext;
|
|
684
706
|
const reseeded = {
|
|
685
|
-
schema_version:
|
|
707
|
+
schema_version: 3,
|
|
686
708
|
snapshot: null,
|
|
687
|
-
|
|
709
|
+
tail_hint: truncatedNext,
|
|
688
710
|
log_seq_start: truncatedNext,
|
|
689
711
|
writer_fence: {
|
|
690
712
|
epoch: head.json.writer_fence.epoch + 1,
|
|
691
713
|
owner: RESTORE_OWNER,
|
|
692
714
|
claimed_at: ""
|
|
693
715
|
},
|
|
694
|
-
tail_bytes: 0,
|
|
695
716
|
snapshot_bytes: 0,
|
|
696
717
|
snapshot_rows: 0
|
|
697
718
|
};
|
|
@@ -706,16 +727,15 @@ const bundle = defineBaerlySubcommand({
|
|
|
706
727
|
}
|
|
707
728
|
} else {
|
|
708
729
|
const seed = {
|
|
709
|
-
schema_version:
|
|
730
|
+
schema_version: 3,
|
|
710
731
|
snapshot: null,
|
|
711
|
-
|
|
732
|
+
tail_hint: 0,
|
|
712
733
|
log_seq_start: 0,
|
|
713
734
|
writer_fence: {
|
|
714
735
|
epoch: 0,
|
|
715
736
|
owner: RESTORE_OWNER,
|
|
716
737
|
claimed_at: ""
|
|
717
738
|
},
|
|
718
|
-
tail_bytes: 0,
|
|
719
739
|
snapshot_bytes: 0,
|
|
720
740
|
snapshot_rows: 0
|
|
721
741
|
};
|
|
@@ -753,6 +773,20 @@ const bundle = defineBaerlySubcommand({
|
|
|
753
773
|
});
|
|
754
774
|
count++;
|
|
755
775
|
}
|
|
776
|
+
if (count > 0) {
|
|
777
|
+
const afterLoad = await readCurrentJson(bucket.storage, currentJsonKey);
|
|
778
|
+
if (afterLoad !== null) {
|
|
779
|
+
const clampedTail = Math.max(baseSeq + count, afterLoad.json.tail_hint, afterLoad.json.log_seq_start);
|
|
780
|
+
const stamped = {
|
|
781
|
+
...afterLoad.json,
|
|
782
|
+
tail_hint: clampedTail
|
|
783
|
+
};
|
|
784
|
+
await bucket.storage.put(currentJsonKey, encodeJsonBytes(stamped), {
|
|
785
|
+
ifMatch: afterLoad.etag,
|
|
786
|
+
contentType: "application/json"
|
|
787
|
+
});
|
|
788
|
+
}
|
|
789
|
+
}
|
|
756
790
|
emitSuccess({
|
|
757
791
|
command: "admin.restore",
|
|
758
792
|
status: "ok",
|
|
@@ -768,4 +802,4 @@ bundle.run;
|
|
|
768
802
|
//#endregion
|
|
769
803
|
export { restoreCmd };
|
|
770
804
|
|
|
771
|
-
//# sourceMappingURL=restore-
|
|
805
|
+
//# sourceMappingURL=restore-DpQYef6r.js.map
|