@gusto/baerly-storage 0.2.0 → 0.4.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 +176 -70
- package/dist/API.md +213 -139
- package/dist/CHANGELOG.md +434 -0
- package/dist/RECIPES.md +125 -0
- package/dist/THIRD-PARTY-LICENSES.txt +238 -0
- package/dist/{app-config-C0Bbw_Z6.d.ts → app-config-DyiFK3_k.d.ts} +55 -11
- package/dist/app-config.d.ts +1 -1
- package/dist/auth.d.ts +1 -1
- package/dist/auth.js +301 -301
- package/dist/auth.js.map +1 -1
- package/dist/aws4fetch.esm-p7eEzLCs.js +1702 -0
- package/dist/aws4fetch.esm-p7eEzLCs.js.map +1 -0
- package/dist/baerly.js +35 -15
- package/dist/baerly.js.map +1 -1
- package/dist/baerly.spec.json +342 -0
- package/dist/bytes-BXdamO3L.js.map +1 -1
- package/dist/{client-DYZfoZb9.d.ts → client-Fe8CwB73.d.ts} +10 -10
- package/dist/client-react.d.ts +3 -3
- package/dist/client-react.js +4 -4
- package/dist/client-react.js.map +1 -1
- package/dist/client.d.ts +4 -4
- package/dist/client.js +3 -3
- package/dist/client.js.map +1 -1
- package/dist/{cloudflare-CINJPKCW.js → cloudflare-DzKBrUlg.js} +178 -2
- package/dist/cloudflare-DzKBrUlg.js.map +1 -0
- package/dist/cloudflare.d.ts +49 -6
- package/dist/cloudflare.js +59 -26
- package/dist/cloudflare.js.map +1 -1
- package/dist/config-1tv0-Yzm.js +2693 -0
- package/dist/config-1tv0-Yzm.js.map +1 -0
- package/dist/constants-CfeMWQWk.js +222 -0
- package/dist/constants-CfeMWQWk.js.map +1 -0
- package/dist/context-DRZ3tZ5l.js.map +1 -1
- package/dist/{cost-CQt1YRkA.js → cost-DSMIVqzL.js} +43 -42
- package/dist/cost-DSMIVqzL.js.map +1 -0
- package/dist/current-json-C6nhPOm1.js +190 -0
- package/dist/current-json-C6nhPOm1.js.map +1 -0
- package/dist/{db-BM3y2JQw.d.ts → db-DsPkOVEH.d.ts} +26 -108
- package/dist/{deploy-CrAbfgCq.js → deploy-DonTr-CV.js} +12 -5
- package/dist/deploy-DonTr-CV.js.map +1 -0
- package/dist/dev-vite.d.ts +11 -7
- package/dist/dev-vite.js +7 -6
- 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-DSIyCDg_.js} +14 -136
- package/dist/doctor-DSIyCDg_.js.map +1 -0
- package/dist/{dump-BYA55NLP.js → dump-Bh5k26VQ.js} +10 -31
- package/dist/dump-Bh5k26VQ.js.map +1 -0
- package/dist/{errors-DOdL95kK.js → errors-Dfa3p78c.js} +25 -5
- package/dist/errors-Dfa3p78c.js.map +1 -0
- package/dist/{export-Bhbz90-z.js → export-DtF5tDIM.js} +11 -32
- package/dist/{export-Bhbz90-z.js.map → export-DtF5tDIM.js.map} +1 -1
- package/dist/{fsck-CPPZWt9p.js → fsck-D_djMO5D.js} +28 -39
- package/dist/fsck-D_djMO5D.js.map +1 -0
- package/dist/{http-Cw8p6y5b.js → http-DxM9MflO.js} +151 -79
- package/dist/http-DxM9MflO.js.map +1 -0
- package/dist/http.d.ts +42 -26
- package/dist/http.js +3 -2
- package/dist/{index-DwDTWPSU.d.ts → index-0rZcMBwy.d.ts} +10 -7
- package/dist/{index-C3JAH1Yo.d.ts → index-B6oexfOB.d.ts} +9 -9
- package/dist/{index-cUY-36AN.d.ts → index-BNRh23K9.d.ts} +21 -5
- package/dist/{index-DSvwEUeF.d.ts → index-BYk9oCNf.d.ts} +240 -202
- package/dist/index.d.ts +6 -6
- package/dist/index.js +5 -5
- package/dist/{indexes-DAu2AkTW.d.ts → indexes-Dn9hbGQG.d.ts} +2 -2
- package/dist/{inspect-Bdbzvi-_.js → inspect-6WZ-pC7-.js} +21 -36
- package/dist/inspect-6WZ-pC7-.js.map +1 -0
- package/dist/key-Di6yyxFu.js +35 -0
- package/dist/key-Di6yyxFu.js.map +1 -0
- package/dist/{snapshot-SS8USDUF.js → log-tail-D98U1JBo.js} +179 -84
- package/dist/log-tail-D98U1JBo.js.map +1 -0
- package/dist/{maintenance-ClzBC1Vv.js → maintenance-B4Dki6Ig.js} +438 -176
- package/dist/maintenance-B4Dki6Ig.js.map +1 -0
- package/dist/{maintenance-BRrThz8V.d.ts → maintenance-B_e0T99L.d.ts} +114 -26
- package/dist/{maintenance-BvOv6BMM.js → maintenance-C7coQp4c.js} +217 -94
- package/dist/maintenance-C7coQp4c.js.map +1 -0
- package/dist/maintenance.d.ts +3 -2
- package/dist/maintenance.js +3 -2
- package/dist/node.d.ts +176 -68
- package/dist/node.js +3 -2
- package/dist/{normalize-XWY25_sG.js → normalize-rjnZLwS4.js} +2 -2
- package/dist/normalize-rjnZLwS4.js.map +1 -0
- package/dist/{observability-CpOiEN0k.js → observability-wzs3-BL_.js} +279 -109
- package/dist/observability-wzs3-BL_.js.map +1 -0
- package/dist/observability.d.ts +3 -3
- package/dist/observability.js +1 -1
- package/dist/{plan-DOTl21vq.js → plan-a7PJHBCy.js} +7 -4
- package/dist/plan-a7PJHBCy.js.map +1 -0
- package/dist/{query-BmiQy328.js → query-rAtXNQQB.js} +1063 -1202
- package/dist/query-rAtXNQQB.js.map +1 -0
- package/dist/{rebuild-index-DC_nR6wP.js → rebuild-index-BVzQSZlm.js} +10 -32
- package/dist/rebuild-index-BVzQSZlm.js.map +1 -0
- package/dist/{request-BEF_OvMh.js → request-u0M51mhJ.js} +3 -3
- package/dist/{request-BEF_OvMh.js.map → request-u0M51mhJ.js.map} +1 -1
- package/dist/restore-R-4rbciV.js +778 -0
- package/dist/restore-R-4rbciV.js.map +1 -0
- package/dist/runtime-spec-qL3_lTTU.js +391 -0
- package/dist/runtime-spec-qL3_lTTU.js.map +1 -0
- package/dist/s3-http-B-z8th6O.d.ts +60 -0
- package/dist/s3.d.ts +47 -0
- package/dist/s3.js +45 -0
- package/dist/s3.js.map +1 -0
- package/dist/{shared-secret-BJdSwpgw.js → shared-secret-DgEicd3x.js} +13 -5
- package/dist/shared-secret-DgEicd3x.js.map +1 -0
- package/dist/src-BG20LZs7.js +2271 -0
- package/dist/src-BG20LZs7.js.map +1 -0
- package/dist/{src-zhEAmmF7.js → src-CYHFDrKz.js} +82 -99
- package/dist/src-CYHFDrKz.js.map +1 -0
- package/dist/{src-QQ7jDeL2.js → src-DYZ4H1aF.js} +44 -23
- package/dist/src-DYZ4H1aF.js.map +1 -0
- package/dist/subcommand-DoDA-K7d.js +197 -0
- package/dist/subcommand-DoDA-K7d.js.map +1 -0
- package/dist/time-DUqvFMHq.js +119 -0
- package/dist/time-DUqvFMHq.js.map +1 -0
- package/dist/{usage-CLjirdD-.js → usage-DBV1eQHC.js} +7 -22
- package/dist/usage-DBV1eQHC.js.map +1 -0
- 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/dist/wire-izfGZDvr.js.map +1 -1
- package/package.json +77 -42
- 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 +0 -354
- 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/errors-DOdL95kK.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/normalize-XWY25_sG.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 +0 -771
- package/dist/restore-C6IcmLeA.js.map +0 -1
- package/dist/shared-secret-BJdSwpgw.js.map +0 -1
- package/dist/snapshot-SS8USDUF.js.map +0 -1
- package/dist/src-DU1sCMlr.js +0 -6236
- 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 +0 -5122
- package/dist/subcommand-DZcHcsYp.js.map +0 -1
- package/dist/usage-CLjirdD-.js.map +0 -1
- /package/dist/{chunk-EAsCxrDo.js → rolldown-runtime-EAsCxrDo.js} +0 -0
|
@@ -1,7 +1,9 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
1
|
+
import { a as decodeJsonBytes, i as readCurrentJson, n as createCurrentJson, o as encodeJsonBytes, r as logSeqStartOf } from "./current-json-C6nhPOm1.js";
|
|
2
|
+
import { l as MAINTENANCE_PROFILE_CF_FREE, m as MAX_KEY_BYTES, r as FORBIDDEN_MERGE_KEYS, s as LOG_FORWARD_PROBE_CAP } from "./constants-CfeMWQWk.js";
|
|
3
|
+
import { t as BaerlyError } from "./errors-Dfa3p78c.js";
|
|
4
|
+
import { A as deepEqualDocumentValue, C as findLogTail, D as validateWire, E as versionFromContent, O as assertWireSatisfiable, S as assertNameNotReserved, T as logObjectKey, _ as encodeIndexValue, b as loadSnapshotAsMap, g as allIndexKeysFor, h as walkLogRange, i as dispatchInlineAwaited, k as matchesWire, l as shouldFireMaintenance, m as readLogEntry, p as foldLogEntriesOnto, s as runBoundedMaintenance, v as validateIndexDefinition, w as probeTailFrom } from "./maintenance-B4Dki6Ig.js";
|
|
5
|
+
import { t as normalizePredicateArg } from "./normalize-rjnZLwS4.js";
|
|
6
|
+
import { a as uuid, n as timestamp, o as uuidv7, r as countKey } from "./time-DUqvFMHq.js";
|
|
5
7
|
import { i as noopMetricsRecorder, n as getCurrentContext } from "./context-DRZ3tZ5l.js";
|
|
6
8
|
//#region packages/protocol/src/json.ts
|
|
7
9
|
const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
@@ -79,1214 +81,1084 @@ const mergePredicateWires = (a, b) => {
|
|
|
79
81
|
assertWireSatisfiable(merged);
|
|
80
82
|
return merged;
|
|
81
83
|
};
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
/**
|
|
85
|
-
* Mint a fresh {@link UUID}. The cast lives here so callers don't sprinkle
|
|
86
|
-
* `<UUID>crypto.randomUUID()` throughout the codebase.
|
|
87
|
-
*/
|
|
88
|
-
const uuid = () => crypto.randomUUID();
|
|
89
|
-
/**
|
|
90
|
-
* Mint a UUIDv7 — 48-bit Unix-millis prefix + 74 bits of randomness,
|
|
91
|
-
* formatted as a standard 8-4-4-4-12 UUID string per RFC 9562 §5.7.
|
|
92
|
-
* Lex-sortable by mint time, so it pairs well with object-storage
|
|
93
|
-
* list semantics. Returns a branded {@link UUID}.
|
|
94
|
-
*
|
|
95
|
-
* Uses `crypto.getRandomValues` which is universally available
|
|
96
|
-
* (Node 19+, Workerd, Bun, browsers).
|
|
97
|
-
*
|
|
98
|
-
* @example
|
|
99
|
-
* ```ts
|
|
100
|
-
* const id = uuidv7();
|
|
101
|
-
* // e.g. "01956cad-4cc8-7abc-9def-0123456789ab"
|
|
102
|
-
* ```
|
|
103
|
-
*/
|
|
104
|
-
const uuidv7 = () => {
|
|
105
|
-
const millis = Date.now();
|
|
106
|
-
const rand = new Uint8Array(10);
|
|
107
|
-
crypto.getRandomValues(rand);
|
|
108
|
-
rand[0] = rand[0] & 15 | 112;
|
|
109
|
-
rand[2] = rand[2] & 63 | 128;
|
|
110
|
-
const millisHex = millis.toString(16).padStart(12, "0");
|
|
111
|
-
const b = Array.from(rand, (n) => n.toString(16).padStart(2, "0")).join("");
|
|
112
|
-
return `${millisHex.slice(0, 8)}-${millisHex.slice(8, 12)}-${b.slice(0, 4)}-${b.slice(4, 8)}-${b.slice(8, 20)}`;
|
|
113
|
-
};
|
|
84
|
+
const utf8$1 = new TextEncoder();
|
|
85
|
+
const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/;
|
|
114
86
|
/**
|
|
115
|
-
*
|
|
116
|
-
* `
|
|
117
|
-
*
|
|
118
|
-
*
|
|
119
|
-
*
|
|
120
|
-
*
|
|
121
|
-
*
|
|
87
|
+
* The single validation rule for every caller-controlled key segment
|
|
88
|
+
* (`_id`, `collection`, `app`, `tenant`) before it becomes a written
|
|
89
|
+
* key segment or `LocalFsStorage` path. Rejects empty / `"/"` /
|
|
90
|
+
* `"."`|`".."` / C0-C1 control / leading `"_"` (ADR-003) / `> MAX_SEGMENT_BYTES`,
|
|
91
|
+
* all as `BaerlyError{code:"InvalidConfig"}`.
|
|
92
|
+
*
|
|
93
|
+
* @param role human label for the segment ("_id" | "collection" | "app" | "tenant").
|
|
94
|
+
* @param verb optional calling-context label for the message.
|
|
122
95
|
*/
|
|
123
|
-
const
|
|
124
|
-
const
|
|
125
|
-
|
|
126
|
-
|
|
96
|
+
const assertPathSegment = (value, role, verb = "") => {
|
|
97
|
+
const where = verb === "" ? role : `${verb}: ${role}`;
|
|
98
|
+
if (value.length === 0) throw new BaerlyError("InvalidConfig", `${where} must be a non-empty string`);
|
|
99
|
+
if (value.includes("/")) throw new BaerlyError("InvalidConfig", `${where} may not contain "/": ${JSON.stringify(value)}`);
|
|
100
|
+
if (value === "." || value === "..") throw new BaerlyError("InvalidConfig", `${where} may not be "." or "..": ${JSON.stringify(value)}`);
|
|
101
|
+
if (CONTROL_CHARS.test(value)) throw new BaerlyError("InvalidConfig", `${where} may not contain control characters`);
|
|
102
|
+
if (utf8$1.encode(value).length > 256) throw new BaerlyError("InvalidConfig", `${where} is too long (> 256 bytes)`);
|
|
103
|
+
assertNameNotReserved(value, where);
|
|
127
104
|
};
|
|
105
|
+
//#endregion
|
|
106
|
+
//#region packages/server/src/doc-id.ts
|
|
128
107
|
/**
|
|
129
|
-
*
|
|
130
|
-
*
|
|
131
|
-
*
|
|
132
|
-
*
|
|
133
|
-
*
|
|
134
|
-
*
|
|
135
|
-
* lexicographically. Composed into an LSN of shape
|
|
136
|
-
* `<base32-time>_<session>_<seq>` (where both `<base32-time>` and
|
|
137
|
-
* `<seq>` use this encoder), a forward `Storage.list(prefix)`
|
|
138
|
-
* returns log entries in reverse-causal order — newer entries first.
|
|
139
|
-
*
|
|
140
|
-
* This is the structural property the read path leans on:
|
|
141
|
-
* `ListObjectsV2` is forward-only on S3, but the descending encoding
|
|
142
|
-
* makes "fetch the K newest entries" a single bounded LIST with
|
|
143
|
-
* `maxKeys=K` instead of a full-population LIST + in-memory reverse.
|
|
144
|
-
*
|
|
145
|
-
* Behaviourally verified across randomized populations in
|
|
146
|
-
* `packages/protocol/src/lsn-reverse-list.test.ts`. Quantified
|
|
147
|
-
* bytes-listed reduction is in
|
|
148
|
-
* `docs/spec/attachments/lsn-reverse-walk-baseline.json`
|
|
149
|
-
* (run `pnpm bench:lsn-reverse-walk` to reproduce). Spec rationale:
|
|
150
|
-
* `docs/spec/sync-protocol.md` §"Subtleties of the manifest key".
|
|
108
|
+
* Guard a caller-supplied `_id` before it becomes a written key segment
|
|
109
|
+
* (index keys, log `doc_id`) or filesystem path (`LocalFsStorage`). The
|
|
110
|
+
* `_id` analogue of `assertKeySegment` (`db.ts`). Routes through the
|
|
111
|
+
* single shared {@link assertPathSegment} rule (empty / `"/"` /
|
|
112
|
+
* `"."`|`".."` / C0-C1 control chars / leading `"_"` (ADR-003) / overlong,
|
|
113
|
+
* all as `BaerlyError{code:"InvalidConfig"}`).
|
|
151
114
|
*/
|
|
152
|
-
const
|
|
153
|
-
|
|
154
|
-
};
|
|
155
|
-
const str2uintDesc = (str, bits) => {
|
|
156
|
-
return Math.pow(2, bits) - 1 - parseInt(str, 32);
|
|
115
|
+
const assertDocId = (id) => {
|
|
116
|
+
assertPathSegment(id, "_id");
|
|
157
117
|
};
|
|
158
118
|
//#endregion
|
|
159
|
-
//#region packages/
|
|
119
|
+
//#region packages/server/src/query-planner-implies.ts
|
|
160
120
|
/**
|
|
161
|
-
*
|
|
162
|
-
*
|
|
163
|
-
*
|
|
164
|
-
*
|
|
165
|
-
*
|
|
166
|
-
*
|
|
167
|
-
*
|
|
168
|
-
*
|
|
169
|
-
*
|
|
170
|
-
*
|
|
171
|
-
*
|
|
121
|
+
* Filtered-index implication checker — decides whether every
|
|
122
|
+
* document accepted by a query predicate is also accepted by a
|
|
123
|
+
* filtered index's predicate. The query planner uses the result to
|
|
124
|
+
* rank candidate indexes; see {@link "./query-planner.ts".planQuery}.
|
|
125
|
+
*
|
|
126
|
+
* Pure-function module: no I/O, no `Db` / `Storage` imports. Lives
|
|
127
|
+
* in `@baerly/server` (not in `@baerly/protocol`) because the
|
|
128
|
+
* planner is the only caller.
|
|
129
|
+
*
|
|
130
|
+
* Operates on the wire form: both inputs are {@link PredicateWire}s
|
|
131
|
+
* with clauses already grouped by `(op, field, value)`. The
|
|
132
|
+
* normaliser at `@baerly/protocol`'s `./query/normalize.ts` has
|
|
133
|
+
* already flattened nested literal sub-predicates into dotted-path
|
|
134
|
+
* `eq` clauses, so there is no recursion on nested objects here.
|
|
172
135
|
*/
|
|
173
|
-
const timestamp = (epoch) => {
|
|
174
|
-
if (!Number.isInteger(epoch) || epoch < 0 || epoch >= 2 ** 42) throw new BaerlyError("Internal", `timestamp(): epoch must be a non-negative integer < 2^42 (got ${epoch})`);
|
|
175
|
-
return uint2strDesc(epoch, 42);
|
|
176
|
-
};
|
|
177
136
|
/**
|
|
178
|
-
*
|
|
179
|
-
*
|
|
180
|
-
*
|
|
181
|
-
*
|
|
182
|
-
* waiting for it to complete.
|
|
137
|
+
* Group a wire's clauses by `field` so the per-field implication
|
|
138
|
+
* check can reason over one bundle at a time. Inlined small helper
|
|
139
|
+
* (not exported) so the planner module doesn't need to expose its
|
|
140
|
+
* grouping helper as a cross-module contract.
|
|
183
141
|
*/
|
|
184
|
-
const
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
142
|
+
const groupByField = (wire) => {
|
|
143
|
+
const groups = /* @__PURE__ */ new Map();
|
|
144
|
+
for (const clause of wire.clauses) {
|
|
145
|
+
const bucket = groups.get(clause.field);
|
|
146
|
+
if (bucket === void 0) groups.set(clause.field, [clause]);
|
|
147
|
+
else bucket.push(clause);
|
|
188
148
|
}
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
clearTimeout(timer);
|
|
192
|
-
reject(signal.reason);
|
|
193
|
-
}, { once: true });
|
|
194
|
-
});
|
|
195
|
-
//#endregion
|
|
196
|
-
//#region packages/protocol/src/log.ts
|
|
197
|
-
const COUNT_BIT_WIDTH = 10;
|
|
149
|
+
return groups;
|
|
150
|
+
};
|
|
198
151
|
/**
|
|
199
|
-
*
|
|
200
|
-
*
|
|
201
|
-
*
|
|
202
|
-
*
|
|
203
|
-
*
|
|
204
|
-
*
|
|
205
|
-
*
|
|
206
|
-
* `
|
|
207
|
-
*
|
|
208
|
-
* Throws on malformed input; callers should pass only lsns minted
|
|
209
|
-
* by `Writer.commit` (see
|
|
210
|
-
* `packages/server/src/writer.ts`).
|
|
152
|
+
* Collapse a per-field clause list into an {@link OperatorBundle}.
|
|
153
|
+
* Returns `"unknown-shape"` when the group has more than one `in`
|
|
154
|
+
* clause (set-intersection at plan time is out of scope) or
|
|
155
|
+
* unrecognised ops slipping through (defensive — the validator
|
|
156
|
+
* already locked the op vocabulary). Multiple `eq` clauses on one
|
|
157
|
+
* field: the validator proves they all agree, so we pick the first.
|
|
158
|
+
* Multiple range clauses on one field: take the strictest bound
|
|
159
|
+
* (tightest `lo` = numerically largest; tightest `hi` = numerically
|
|
160
|
+
* smallest).
|
|
211
161
|
*/
|
|
212
|
-
const
|
|
213
|
-
const
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
162
|
+
const decodeGroup = (clauses) => {
|
|
163
|
+
const bundle = {};
|
|
164
|
+
for (const clause of clauses) {
|
|
165
|
+
const v = clause.value;
|
|
166
|
+
if (clause.op === "eq") bundle.eq = v;
|
|
167
|
+
else if (clause.op === "gte") {
|
|
168
|
+
const next = {
|
|
169
|
+
value: v,
|
|
170
|
+
inclusive: true
|
|
171
|
+
};
|
|
172
|
+
bundle.lo = tightestLo(bundle.lo, next);
|
|
173
|
+
} else if (clause.op === "gt") {
|
|
174
|
+
const next = {
|
|
175
|
+
value: v,
|
|
176
|
+
inclusive: false
|
|
177
|
+
};
|
|
178
|
+
bundle.lo = tightestLo(bundle.lo, next);
|
|
179
|
+
} else if (clause.op === "lte") {
|
|
180
|
+
const next = {
|
|
181
|
+
value: v,
|
|
182
|
+
inclusive: true
|
|
183
|
+
};
|
|
184
|
+
bundle.hi = tightestHi(bundle.hi, next);
|
|
185
|
+
} else if (clause.op === "lt") {
|
|
186
|
+
const next = {
|
|
187
|
+
value: v,
|
|
188
|
+
inclusive: false
|
|
189
|
+
};
|
|
190
|
+
bundle.hi = tightestHi(bundle.hi, next);
|
|
191
|
+
} else if (clause.op === "in") {
|
|
192
|
+
if (bundle.in !== void 0) return "unknown-shape";
|
|
193
|
+
if (!Array.isArray(v)) return "unknown-shape";
|
|
194
|
+
bundle.in = v;
|
|
195
|
+
} else return "unknown-shape";
|
|
196
|
+
}
|
|
197
|
+
return bundle;
|
|
198
|
+
};
|
|
199
|
+
const tightestLo = (existing, next) => {
|
|
200
|
+
if (existing === void 0) return next;
|
|
201
|
+
if (typeof existing.value !== typeof next.value) return existing;
|
|
202
|
+
if (next.value > existing.value) return next;
|
|
203
|
+
if (next.value < existing.value) return existing;
|
|
204
|
+
if (!next.inclusive && existing.inclusive) return next;
|
|
205
|
+
return existing;
|
|
206
|
+
};
|
|
207
|
+
const tightestHi = (existing, next) => {
|
|
208
|
+
if (existing === void 0) return next;
|
|
209
|
+
if (typeof existing.value !== typeof next.value) return existing;
|
|
210
|
+
if (next.value < existing.value) return next;
|
|
211
|
+
if (next.value > existing.value) return existing;
|
|
212
|
+
if (!next.inclusive && existing.inclusive) return next;
|
|
213
|
+
return existing;
|
|
219
214
|
};
|
|
220
|
-
//#endregion
|
|
221
|
-
//#region packages/server/src/log-conflict-adoption.ts
|
|
222
215
|
/**
|
|
223
|
-
*
|
|
224
|
-
*
|
|
225
|
-
* function; no I/O. The caller performs the GET (when the log PUT
|
|
226
|
-
* surfaces 412) and passes the read-back body in `ctx.existing`.
|
|
216
|
+
* Does the query's lower bound `loQ` (`undefined` if none) prove that
|
|
217
|
+
* every matching doc satisfies the filter's lower bound `loF`?
|
|
227
218
|
*
|
|
228
|
-
*
|
|
229
|
-
*
|
|
219
|
+
* `loF.inclusive` true → need doc ≥ loF.value; `loF.inclusive` false →
|
|
220
|
+
* need doc > loF.value. A stricter `loQ` (numerically larger or with
|
|
221
|
+
* tighter inclusivity) always implies a looser `loF`.
|
|
230
222
|
*/
|
|
231
|
-
const
|
|
232
|
-
if (
|
|
233
|
-
|
|
234
|
-
|
|
223
|
+
const lowerBoundImplies = (loF, loQ) => {
|
|
224
|
+
if (loQ === void 0) return false;
|
|
225
|
+
if (typeof loF.value !== typeof loQ.value) return false;
|
|
226
|
+
if (loQ.value > loF.value) return true;
|
|
227
|
+
if (loQ.value < loF.value) return false;
|
|
228
|
+
if (loF.inclusive) return true;
|
|
229
|
+
return !loQ.inclusive;
|
|
230
|
+
};
|
|
231
|
+
/** Mirror of lowerBoundImplies for upper bounds. */
|
|
232
|
+
const upperBoundImplies = (hiF, hiQ) => {
|
|
233
|
+
if (hiQ === void 0) return false;
|
|
234
|
+
if (typeof hiF.value !== typeof hiQ.value) return false;
|
|
235
|
+
if (hiQ.value < hiF.value) return true;
|
|
236
|
+
if (hiQ.value > hiF.value) return false;
|
|
237
|
+
if (hiF.inclusive) return true;
|
|
238
|
+
return !hiQ.inclusive;
|
|
239
|
+
};
|
|
240
|
+
const loFromQuery = (q) => {
|
|
241
|
+
if (q.eq !== void 0) return {
|
|
242
|
+
value: q.eq,
|
|
243
|
+
inclusive: true
|
|
235
244
|
};
|
|
236
|
-
if (
|
|
237
|
-
|
|
238
|
-
|
|
245
|
+
if (q.in !== void 0 && q.in.length > 0) return {
|
|
246
|
+
value: q.in.reduce((acc, v) => v < acc ? v : acc, q.in[0]),
|
|
247
|
+
inclusive: true
|
|
239
248
|
};
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
249
|
+
return q.lo;
|
|
250
|
+
};
|
|
251
|
+
const hiFromQuery = (q) => {
|
|
252
|
+
if (q.eq !== void 0) return {
|
|
253
|
+
value: q.eq,
|
|
254
|
+
inclusive: true
|
|
243
255
|
};
|
|
244
|
-
return {
|
|
245
|
-
|
|
246
|
-
|
|
256
|
+
if (q.in !== void 0 && q.in.length > 0) return {
|
|
257
|
+
value: q.in.reduce((acc, v) => v > acc ? v : acc, q.in[0]),
|
|
258
|
+
inclusive: true
|
|
247
259
|
};
|
|
260
|
+
return q.hi;
|
|
248
261
|
};
|
|
249
|
-
//#endregion
|
|
250
|
-
//#region packages/server/src/writer.ts
|
|
251
262
|
/**
|
|
252
|
-
*
|
|
253
|
-
*
|
|
254
|
-
*
|
|
255
|
-
*
|
|
256
|
-
*
|
|
257
|
-
* Up to {@link S3_REQUEST_MAX_RETRIES} attempts on contention before
|
|
258
|
-
* surfacing `BaerlyError{code:"Conflict"}`. The optional integrity
|
|
259
|
-
* walk over the live log tail is gated by
|
|
260
|
-
* {@link WriterOptions.verifyLogIntegrityOnCommit} (default off
|
|
261
|
-
* — see the option's docstring).
|
|
262
|
-
*
|
|
263
|
-
* The instance carries no per-write cache: every commit re-reads
|
|
264
|
-
* `current.json`, so N stateless server instances writing the same
|
|
265
|
-
* tenant prefix contend at exactly one place — the conditional PUT
|
|
266
|
-
* on `current.json` — and one loses cleanly with a 412.
|
|
267
|
-
*
|
|
268
|
-
* **Manifest-first ordering is REVERSED relative to the legacy
|
|
269
|
-
* `src/syncer.ts` write loop.** Old loop: PUT manifest → PUT content
|
|
270
|
-
* → CAS. New loop: PUT content → PUT log entry → CAS-advance
|
|
271
|
-
* `current.json`. A crashed mid-loop writer leaves an unreferenced
|
|
272
|
-
* content body (no log entry points at it), not an orphan log entry
|
|
273
|
-
* with missing content. The compactor sweeps the orphan content
|
|
274
|
-
* later.
|
|
275
|
-
*
|
|
276
|
-
* **`LogEntry` shape.** Emitted entries follow the contract in
|
|
277
|
-
* `packages/protocol/src/log.ts` (see {@link LogEntry}) and
|
|
278
|
-
* `docs/spec/log-entry-shape.md`. The on-bucket key is
|
|
279
|
-
* `log/<seq>.json` (the integer `seq` is the load-bearing
|
|
280
|
-
* identifier; the `lsn` string is schema-only).
|
|
263
|
+
* Filtered-index implication checker — decides whether every document
|
|
264
|
+
* accepted by `queryWire` is also accepted by `indexFilterWire`. When
|
|
265
|
+
* `true`, a walk over an index declared with `predicate: indexFilterWire`
|
|
266
|
+
* is **complete** for `queryWire`: no matching doc is missing
|
|
267
|
+
* from the smaller key set, so the planner can prefer it.
|
|
281
268
|
*
|
|
282
|
-
*
|
|
283
|
-
*
|
|
284
|
-
*
|
|
285
|
-
|
|
286
|
-
const ctxMetrics = () => getCurrentContext()?.recorder ?? noopMetricsRecorder;
|
|
287
|
-
const DEFAULT_INITIAL_BACKOFF_MS = 25;
|
|
288
|
-
const MAX_BACKOFF_MS = 1500;
|
|
289
|
-
const APPLICATION_JSON = "application/json";
|
|
290
|
-
/**
|
|
291
|
-
* Empty body for index entries. Each index entry is a fact ("doc
|
|
292
|
-
* `<docId>` has `<field> = <value>`"), not data — readers list the
|
|
293
|
-
* prefix, extract the doc id, then GET the content body separately.
|
|
294
|
-
* Pre-allocated module-level constant so every index PUT shares one
|
|
295
|
-
* zero-length buffer.
|
|
296
|
-
*/
|
|
297
|
-
const EMPTY_BODY = new Uint8Array(0);
|
|
298
|
-
/**
|
|
299
|
-
* Stateless write engine for the multi-instance core.
|
|
269
|
+
* Implication on `eq`, `gt` / `gte`, `lt` / `lte`, and `in` is
|
|
270
|
+
* sound and complete in pure operator form; combined shapes (e.g.
|
|
271
|
+
* range-on-filter and `in`-on-query) follow the algebra in the body
|
|
272
|
+
* JSDoc.
|
|
300
273
|
*
|
|
301
|
-
*
|
|
302
|
-
*
|
|
303
|
-
* happens in {@link commit}.
|
|
274
|
+
* Algorithm — group both wires by `field`, then for every field
|
|
275
|
+
* present in `indexFilterWire`:
|
|
304
276
|
*
|
|
305
|
-
* @
|
|
306
|
-
*
|
|
307
|
-
*
|
|
308
|
-
*
|
|
277
|
+
* 1. Decode the filter's clause group into an {@link OperatorBundle}.
|
|
278
|
+
* "unknown-shape" → refuse implication conservatively.
|
|
279
|
+
* 2. The query MUST have at least one clause on that field —
|
|
280
|
+
* otherwise the query says nothing about that field and cannot
|
|
281
|
+
* possibly imply the filter's constraint.
|
|
282
|
+
* 3. Decode the query's clause group on the same field.
|
|
283
|
+
* 4. For each non-empty slot of the filter bundle, the query bundle
|
|
284
|
+
* must establish the constraint:
|
|
285
|
+
* - `eq` → query establishes equality (via its own `eq`).
|
|
286
|
+
* - `in` → query is contained in the set (via `eq` ∈ set or
|
|
287
|
+
* `in` ⊆ set).
|
|
288
|
+
* - `lo` / `hi` → query establishes the bound via `eq`, `in`
|
|
289
|
+
* (then min/max of the set), or its own `lo`/`hi` with the
|
|
290
|
+
* inclusivity rules in {@link lowerBoundImplies} /
|
|
291
|
+
* {@link upperBoundImplies}.
|
|
292
|
+
* Mixed types (e.g. number filter vs string query) refuse
|
|
293
|
+
* implication conservatively.
|
|
309
294
|
*
|
|
310
|
-
*
|
|
311
|
-
*
|
|
312
|
-
* currentJsonKey: "app/tickets/tenant/acme/manifests/tickets/current.json",
|
|
313
|
-
* });
|
|
295
|
+
* Returns `true` iff every clause was satisfied. An empty
|
|
296
|
+
* `indexFilterWire` is vacuously implied by any `queryWire`.
|
|
314
297
|
*
|
|
315
|
-
*
|
|
316
|
-
*
|
|
317
|
-
*
|
|
318
|
-
*
|
|
319
|
-
* body: { _id: "doc-1", title: "hello" },
|
|
320
|
-
* });
|
|
321
|
-
* console.log(result.entry.seq, result.attempts);
|
|
322
|
-
* ```
|
|
298
|
+
* Soundness contract — when this function returns `true`,
|
|
299
|
+
* `matchesWire(queryWire, doc) ⇒ matchesWire(indexFilterWire, doc)` for
|
|
300
|
+
* any document `doc`. Tests pin this property; see
|
|
301
|
+
* `./query-planner-implies.test.ts`.
|
|
323
302
|
*/
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
303
|
+
const predicateImplies = (indexFilterWire, queryWire) => {
|
|
304
|
+
const filterGroups = groupByField(indexFilterWire);
|
|
305
|
+
const queryGroups = groupByField(queryWire);
|
|
306
|
+
for (const [field, filterClauses] of filterGroups) {
|
|
307
|
+
const filterBundle = decodeGroup(filterClauses);
|
|
308
|
+
if (filterBundle === "unknown-shape") return false;
|
|
309
|
+
const queryClauses = queryGroups.get(field);
|
|
310
|
+
if (queryClauses === void 0) return false;
|
|
311
|
+
const queryBundle = decodeGroup(queryClauses);
|
|
312
|
+
if (queryBundle === "unknown-shape") return false;
|
|
313
|
+
if (filterBundle.eq !== void 0) {
|
|
314
|
+
if (queryBundle.eq === void 0) return false;
|
|
315
|
+
if (!deepEqualDocumentValue(queryBundle.eq, filterBundle.eq)) return false;
|
|
316
|
+
continue;
|
|
317
|
+
}
|
|
318
|
+
if (filterBundle.in !== void 0) {
|
|
319
|
+
const set = filterBundle.in;
|
|
320
|
+
const contains = (v) => set.some((m) => deepEqualDocumentValue(m, v));
|
|
321
|
+
if (queryBundle.eq !== void 0) {
|
|
322
|
+
if (!contains(queryBundle.eq)) return false;
|
|
323
|
+
} else if (queryBundle.in !== void 0) {
|
|
324
|
+
for (const v of queryBundle.in) if (!contains(v)) return false;
|
|
325
|
+
} else return false;
|
|
326
|
+
continue;
|
|
327
|
+
}
|
|
328
|
+
if (filterBundle.lo !== void 0) {
|
|
329
|
+
if (!lowerBoundImplies(filterBundle.lo, loFromQuery(queryBundle))) return false;
|
|
330
|
+
}
|
|
331
|
+
if (filterBundle.hi !== void 0) {
|
|
332
|
+
if (!upperBoundImplies(filterBundle.hi, hiFromQuery(queryBundle))) return false;
|
|
333
|
+
}
|
|
342
334
|
}
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
335
|
+
return true;
|
|
336
|
+
};
|
|
337
|
+
/**
|
|
338
|
+
* Choose a query plan over the wire predicate + declared indexes.
|
|
339
|
+
* Pure function. The executor enforces the I/O semantics; the
|
|
340
|
+
* planner's only contract is "given these inputs, this is the
|
|
341
|
+
* routing decision."
|
|
342
|
+
*
|
|
343
|
+
* Algorithm:
|
|
344
|
+
* 1. `wire === undefined` or empty → `no-predicate`.
|
|
345
|
+
* 2. `indexes.length === 0` → `no-indexes-declared`.
|
|
346
|
+
* 3. Partition wire clauses per field into:
|
|
347
|
+
* - `equality[f] = v` from `eq` clauses.
|
|
348
|
+
* - `rangeOps[f] = {lo, hi, loInclusive, hiInclusive}` from
|
|
349
|
+
* one or more of `gt`/`gte`/`lt`/`lte` clauses on `f`.
|
|
350
|
+
* - `inOps[f] = [...]` from a single `in` clause on `f`.
|
|
351
|
+
* - Defensive: any field whose clause group mixes op-channels
|
|
352
|
+
* (mostly impossible post-validation) is marked unroutable
|
|
353
|
+
* and skipped — the executor's full-wire `matchesWire(...)`
|
|
354
|
+
* post-fetch catches the residue automatically.
|
|
355
|
+
* 4. If no equality / range / `in` candidates exist →
|
|
356
|
+
* `predicate-uses-operators-only`.
|
|
357
|
+
* 5. For each `def`, walk `def.on` left-to-right consuming
|
|
358
|
+
* equality clauses for each indexed field. On the FIRST field
|
|
359
|
+
* where the equality clause is absent, check whether a range
|
|
360
|
+
* or `in` clause is available for that field — if so, that's
|
|
361
|
+
* the "tail slot" of the walk.
|
|
362
|
+
* 6. Score candidates by `(equalityPrefixLen, hasTailExtension)`.
|
|
363
|
+
* Longest prefix wins; tail-extension breaks ties. If no
|
|
364
|
+
* candidate consumed at least one field (equality OR
|
|
365
|
+
* range/`in`): `no-matching-index`.
|
|
366
|
+
* 7. `in` FAN-OUT GUARD: if the chosen plan's `in` slot has
|
|
367
|
+
* `values.length > IN_FANOUT_THRESHOLD`, fall back to
|
|
368
|
+
* `FullScanPlan{reason:"no-matching-index"}` — N sequential
|
|
369
|
+
* LISTs cost more than a snapshot+log fold.
|
|
370
|
+
*
|
|
371
|
+
* The planner deliberately treats `def.on` as the LITERAL tuple of
|
|
372
|
+
* field names — top-level only. Dotted paths are out of scope here
|
|
373
|
+
* (the projector at `indexes.ts:projectIndexValues` is top-level-
|
|
374
|
+
* only too).
|
|
375
|
+
*
|
|
376
|
+
* **Range/`in` is allowed only on the LAST indexed field beyond the
|
|
377
|
+
* equality prefix** — on a composite `[a, b]`, a range on `a` with
|
|
378
|
+
* equality on `b` is NOT contiguous under the key encoding (the `b`
|
|
379
|
+
* slot sits to the right of the varying `a` slot). Clauses landing
|
|
380
|
+
* outside the tail slot are simply left for the executor's full-
|
|
381
|
+
* predicate re-check.
|
|
382
|
+
*/
|
|
383
|
+
const planQuery = (wire, indexes) => {
|
|
384
|
+
if (wire === void 0 || wire.clauses.length === 0) return {
|
|
385
|
+
kind: "full-scan",
|
|
386
|
+
reason: "no-predicate"
|
|
387
|
+
};
|
|
388
|
+
if (indexes.length === 0) return {
|
|
389
|
+
kind: "full-scan",
|
|
390
|
+
reason: "no-indexes-declared"
|
|
391
|
+
};
|
|
392
|
+
const equality = /* @__PURE__ */ new Map();
|
|
393
|
+
const rangeOps = /* @__PURE__ */ new Map();
|
|
394
|
+
const inOps = /* @__PURE__ */ new Map();
|
|
395
|
+
const unroutable = /* @__PURE__ */ new Set();
|
|
396
|
+
const rangeAcc = /* @__PURE__ */ new Map();
|
|
397
|
+
for (const clause of wire.clauses) {
|
|
398
|
+
const field = clause.field;
|
|
399
|
+
if (unroutable.has(field)) continue;
|
|
400
|
+
if (clause.op === "eq") {
|
|
401
|
+
if (inOps.has(field) || rangeAcc.has(field)) {
|
|
402
|
+
unroutable.add(field);
|
|
403
|
+
equality.delete(field);
|
|
404
|
+
inOps.delete(field);
|
|
405
|
+
rangeAcc.delete(field);
|
|
393
406
|
continue;
|
|
394
407
|
}
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
throw new BaerlyError("Conflict", `Writer: CAS conflict on ${this.#currentJsonKey} after ${this.#maxRetries} attempts`);
|
|
404
|
-
}
|
|
405
|
-
/**
|
|
406
|
-
* Single-attempt batched commit. Reads `current.json` ONCE, mints
|
|
407
|
-
* `inputs.length` log entries with contiguous `seq` numbers
|
|
408
|
-
* starting at the current `next_seq`, PUTs each content body and
|
|
409
|
-
* each log entry, then CAS-advances `current.json` from
|
|
410
|
-
* `next_seq = N` to `next_seq = N + inputs.length` with
|
|
411
|
-
* `If-Match`.
|
|
412
|
-
*
|
|
413
|
-
* NO retry on CAS loss. On `current.json` 412, throws
|
|
414
|
-
* `BaerlyError{code:"Conflict"}` immediately — the caller (here:
|
|
415
|
-
* `Db.transaction`) decides whether to retry by re-running the
|
|
416
|
-
* body, or to surface to the app. Likewise on a log-entry 412
|
|
417
|
-
* (a peer wrote our seq).
|
|
418
|
-
*
|
|
419
|
-
* Empty `inputs`: returns `{ entries: [], currentEtag: undefined }`
|
|
420
|
-
* after zero storage operations.
|
|
421
|
-
*
|
|
422
|
-
* @throws BaerlyError code="Conflict" — CAS lost on `current.json`,
|
|
423
|
-
* or a log entry already exists at our seq (peer wrote ahead).
|
|
424
|
-
* @throws BaerlyError code="Conflict" — the writer fence
|
|
425
|
-
* (`current.json.writer_fence.epoch`) was bumped by a concurrent
|
|
426
|
-
* `claimWriter` call between this batch's read of
|
|
427
|
-
* `current.json` and its CAS-advance. The stale writer aborts
|
|
428
|
-
* to honour the new authority — the kernel does NOT retry under
|
|
429
|
-
* the old epoch. See {@link claimWriter} for the rotation
|
|
430
|
-
* recipe.
|
|
431
|
-
* @throws BaerlyError code="Internal" — protocol-invariant violation
|
|
432
|
-
* (missing log entry inside `[0, next_seq)`).
|
|
433
|
-
* @throws BaerlyError code="InvalidResponse" — malformed log body.
|
|
434
|
-
*
|
|
435
|
-
* **Implicit provisioning.** Like {@link commit}, this path auto-
|
|
436
|
-
* creates `current.json` with a zero-state manifest on a missing
|
|
437
|
-
* read. Because `commitBatch` does NOT retry on CAS loss, a peer
|
|
438
|
-
* racing the same first-write surfaces `Conflict` to the caller
|
|
439
|
-
* (`Db.transaction` re-runs the body); the manifest is durable
|
|
440
|
-
* regardless of which writer won the create.
|
|
441
|
-
*/
|
|
442
|
-
async commitBatch(inputs) {
|
|
443
|
-
if (inputs.length === 0) return {
|
|
444
|
-
entries: [],
|
|
445
|
-
currentEtag: void 0
|
|
446
|
-
};
|
|
447
|
-
const session = uuid().slice(0, 6);
|
|
448
|
-
const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
|
|
449
|
-
const success = await this.#singleAttemptCommit(inputs, session, logPrefix, "Writer.commitBatch", false);
|
|
450
|
-
await this.#verifyFenceUnchanged(success.expectedEpoch, "Writer.commitBatch");
|
|
451
|
-
this.#emitWriteMetrics(inputs[0].collection, success.classAOps);
|
|
452
|
-
return {
|
|
453
|
-
entries: success.entries,
|
|
454
|
-
currentEtag: success.currentEtag
|
|
455
|
-
};
|
|
456
|
-
}
|
|
457
|
-
/**
|
|
458
|
-
* One full commit attempt — the shared body of {@link commit} and
|
|
459
|
-
* {@link commitBatch}. Reads `current.json`, walks the log, mints N
|
|
460
|
-
* entries, PUTs content + indexes in parallel, PUTs log entries,
|
|
461
|
-
* CAS-advances `current.json`. Returns the success payload + the
|
|
462
|
-
* pre-commit fence epoch so the caller can run
|
|
463
|
-
* {@link #verifyFenceUnchanged} outside the retry-catch arm.
|
|
464
|
-
*
|
|
465
|
-
* Retryable failures (a peer wrote our seq; a peer won the CAS on
|
|
466
|
-
* `current.json`) throw `BaerlyError{code:"Conflict"}`. The caller
|
|
467
|
-
* catches via {@link isPreconditionFailed} and either retries
|
|
468
|
-
* (`commit`) or surfaces (`commitBatch`). Fence-bump and protocol-
|
|
469
|
-
* invariant violations are NOT thrown from this helper — the fence
|
|
470
|
-
* check lives in the caller so its `Conflict` propagates past the
|
|
471
|
-
* retry-catch arm. Other thrown `BaerlyError`s (Internal,
|
|
472
|
-
* InvalidResponse, NetworkError) bypass `isPreconditionFailed` and
|
|
473
|
-
* propagate naturally.
|
|
474
|
-
*
|
|
475
|
-
* Crash safety invariant: content / index PUTs are awaited before
|
|
476
|
-
* log PUTs, which are awaited before the CAS. A crashed mid-attempt
|
|
477
|
-
* writer leaves orphan content / index entries (no log entry
|
|
478
|
-
* references them) — the compactor sweeps the orphans. The
|
|
479
|
-
* inverse — orphan log entry with missing content — is never
|
|
480
|
-
* produced.
|
|
481
|
-
*/
|
|
482
|
-
async #singleAttemptCommit(inputs, session, logPrefix, errorPrefix, adoptOwnSessionOnLogConflict) {
|
|
483
|
-
const read = await readCurrentJson(this.#storage, this.#currentJsonKey) ?? await this.#provisionCurrentJson();
|
|
484
|
-
const current = read.json;
|
|
485
|
-
const baseEtag = read.etag;
|
|
486
|
-
const expectedEpoch = current.writer_fence.epoch;
|
|
487
|
-
if (this.#verifyLogIntegrityOnCommit) await this.#walkLog(logPrefix, logSeqStartOf(current), current.next_seq);
|
|
488
|
-
const commitNowMs = Date.now();
|
|
489
|
-
const commitTs = new Date(commitNowMs).toISOString();
|
|
490
|
-
const lsnTimestamp = timestamp(commitNowMs);
|
|
491
|
-
const entries = [];
|
|
492
|
-
for (let i = 0; i < inputs.length; i++) {
|
|
493
|
-
const input = inputs[i];
|
|
494
|
-
const seq = current.next_seq + i;
|
|
495
|
-
const entry = {
|
|
496
|
-
lsn: `${lsnTimestamp}_${session}_${countKey(seq)}`,
|
|
497
|
-
commit_ts: commitTs,
|
|
498
|
-
op: input.op,
|
|
499
|
-
collection: input.collection,
|
|
500
|
-
doc_id: input.docId,
|
|
501
|
-
session,
|
|
502
|
-
seq,
|
|
503
|
-
...input.op !== "D" && input.body !== void 0 ? { after: input.body } : {},
|
|
504
|
-
...input.origin !== void 0 ? { origin: input.origin } : {}
|
|
505
|
-
};
|
|
506
|
-
entries.push(entry);
|
|
507
|
-
}
|
|
508
|
-
let contentPutCount = 0;
|
|
509
|
-
let indexClassA = 0;
|
|
510
|
-
const parallelPuts = [];
|
|
511
|
-
const inBatchImage = /* @__PURE__ */ new Map();
|
|
512
|
-
for (const input of inputs) {
|
|
513
|
-
if (input.op !== "D" && input.body !== void 0) {
|
|
514
|
-
contentPutCount++;
|
|
515
|
-
const bytes = encodeJsonBytes(input.body);
|
|
516
|
-
const contentKey = `${logPrefix}/content/${await versionFromContent(bytes)}.json`;
|
|
517
|
-
parallelPuts.push(this.#storage.put(contentKey, bytes, {
|
|
518
|
-
ifNoneMatch: "*",
|
|
519
|
-
contentType: APPLICATION_JSON
|
|
520
|
-
}).catch((error) => {
|
|
521
|
-
this.#observe429(error, input.collection);
|
|
522
|
-
if (isPreconditionFailed(error)) return;
|
|
523
|
-
throw error;
|
|
524
|
-
}));
|
|
408
|
+
equality.set(field, clause.value);
|
|
409
|
+
} else if (clause.op === "in") {
|
|
410
|
+
if (equality.has(field) || rangeAcc.has(field) || inOps.has(field)) {
|
|
411
|
+
unroutable.add(field);
|
|
412
|
+
equality.delete(field);
|
|
413
|
+
inOps.delete(field);
|
|
414
|
+
rangeAcc.delete(field);
|
|
415
|
+
continue;
|
|
525
416
|
}
|
|
526
|
-
if (
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
if (input.op === "I") newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
|
|
530
|
-
else if (input.op === "U") {
|
|
531
|
-
const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(logPrefix, input.collection, input.docId, current.next_seq);
|
|
532
|
-
const oldKeys = allIndexKeysFor(logPrefix, this.#indexes, preImage, input.docId);
|
|
533
|
-
newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
|
|
534
|
-
const newSet = new Set(newKeys);
|
|
535
|
-
staleKeys = oldKeys.filter((k) => !newSet.has(k));
|
|
536
|
-
} else {
|
|
537
|
-
const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(logPrefix, input.collection, input.docId, current.next_seq);
|
|
538
|
-
staleKeys = allIndexKeysFor(logPrefix, this.#indexes, preImage, input.docId);
|
|
539
|
-
}
|
|
540
|
-
for (const k of newKeys) parallelPuts.push(this.#storage.put(k, EMPTY_BODY, {
|
|
541
|
-
ifNoneMatch: "*",
|
|
542
|
-
contentType: APPLICATION_JSON
|
|
543
|
-
}).catch((error) => {
|
|
544
|
-
this.#observe429(error, input.collection);
|
|
545
|
-
if (isPreconditionFailed(error)) return;
|
|
546
|
-
throw error;
|
|
547
|
-
}));
|
|
548
|
-
for (const k of staleKeys) parallelPuts.push(this.#storage.delete(k));
|
|
549
|
-
indexClassA += newKeys.length + staleKeys.length;
|
|
550
|
-
if (newKeys.length + staleKeys.length > 0) ctxMetrics().histogram("db.write.index_ops_per_logical_write", newKeys.length + staleKeys.length, { collection: input.collection });
|
|
551
|
-
inBatchImage.set(input.docId, input.op === "D" ? void 0 : input.body);
|
|
417
|
+
if (!Array.isArray(clause.value)) {
|
|
418
|
+
unroutable.add(field);
|
|
419
|
+
continue;
|
|
552
420
|
}
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
contentType: APPLICATION_JSON
|
|
562
|
-
});
|
|
563
|
-
return { ok: true };
|
|
564
|
-
} catch (error) {
|
|
565
|
-
this.#observe429(error, entry.collection);
|
|
566
|
-
if (!isPreconditionFailed(error)) throw error;
|
|
567
|
-
ctxMetrics().counter("db.r2.put.412_total", 1, {
|
|
568
|
-
collection: entry.collection,
|
|
569
|
-
step: "log-put"
|
|
570
|
-
});
|
|
571
|
-
return { ok: false };
|
|
421
|
+
inOps.set(field, clause.value);
|
|
422
|
+
} else {
|
|
423
|
+
if (equality.has(field) || inOps.has(field)) {
|
|
424
|
+
unroutable.add(field);
|
|
425
|
+
equality.delete(field);
|
|
426
|
+
inOps.delete(field);
|
|
427
|
+
rangeAcc.delete(field);
|
|
428
|
+
continue;
|
|
572
429
|
}
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
else
|
|
588
|
-
} else
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
const putOpts = {
|
|
599
|
-
ifMatch: baseEtag,
|
|
600
|
-
contentType: APPLICATION_JSON
|
|
601
|
-
};
|
|
602
|
-
let result;
|
|
603
|
-
try {
|
|
604
|
-
result = await this.#storage.put(this.#currentJsonKey, nextBody, putOpts);
|
|
605
|
-
} catch (error) {
|
|
606
|
-
this.#observe429(error, inputs[0].collection);
|
|
607
|
-
if (isPreconditionFailed(error)) {
|
|
608
|
-
ctxMetrics().counter("db.r2.put.412_total", 1, {
|
|
609
|
-
collection: inputs[0].collection,
|
|
610
|
-
step: "current-json-cas"
|
|
611
|
-
});
|
|
612
|
-
throw new BaerlyError("Conflict", `${errorPrefix}: CAS conflict on ${this.#currentJsonKey}`);
|
|
430
|
+
const acc = rangeAcc.get(field) ?? {
|
|
431
|
+
loInclusive: false,
|
|
432
|
+
hiInclusive: false
|
|
433
|
+
};
|
|
434
|
+
const v = clause.value;
|
|
435
|
+
if (clause.op === "gte") {
|
|
436
|
+
if (acc.lo === void 0 || v > acc.lo) {
|
|
437
|
+
acc.lo = v;
|
|
438
|
+
acc.loInclusive = true;
|
|
439
|
+
} else if (v === acc.lo && !acc.loInclusive) {}
|
|
440
|
+
} else if (clause.op === "gt") {
|
|
441
|
+
if (acc.lo === void 0 || v > acc.lo) {
|
|
442
|
+
acc.lo = v;
|
|
443
|
+
acc.loInclusive = false;
|
|
444
|
+
} else if (v === acc.lo) acc.loInclusive = false;
|
|
445
|
+
} else if (clause.op === "lte") {
|
|
446
|
+
if (acc.hi === void 0 || v < acc.hi) {
|
|
447
|
+
acc.hi = v;
|
|
448
|
+
acc.hiInclusive = true;
|
|
449
|
+
}
|
|
450
|
+
} else if (clause.op === "lt") {
|
|
451
|
+
if (acc.hi === void 0 || v < acc.hi) {
|
|
452
|
+
acc.hi = v;
|
|
453
|
+
acc.hiInclusive = false;
|
|
454
|
+
} else if (v === acc.hi) acc.hiInclusive = false;
|
|
613
455
|
}
|
|
614
|
-
|
|
615
|
-
}
|
|
616
|
-
const prevSeq = current.next_seq;
|
|
617
|
-
const maint = getCurrentContext()?.maintenance;
|
|
618
|
-
if (maint?.disabled !== true) {
|
|
619
|
-
if (shouldFireMaintenance(next, prevSeq, maint?.options?.gcInterval ?? 4)) await (maint?.dispatch ?? dispatchInlineAwaited)(() => runBoundedMaintenance({
|
|
620
|
-
storage: this.#storage,
|
|
621
|
-
currentJsonKey: this.#currentJsonKey,
|
|
622
|
-
prevSeq,
|
|
623
|
-
...maint?.maxFoldBytes !== void 0 && { maxFoldBytes: maint.maxFoldBytes }
|
|
624
|
-
}, maint?.options).then(() => {}, () => {}));
|
|
625
|
-
}
|
|
626
|
-
const classAOps = contentPutCount + entries.length + indexClassA + 1;
|
|
627
|
-
return {
|
|
628
|
-
entries: committedEntries,
|
|
629
|
-
currentEtag: result.etag,
|
|
630
|
-
classAOps,
|
|
631
|
-
expectedEpoch
|
|
632
|
-
};
|
|
633
|
-
}
|
|
634
|
-
/**
|
|
635
|
-
* Read the pre-image content body for a doc by walking the live
|
|
636
|
-
* log backwards from `currentNextSeq` looking for the
|
|
637
|
-
* most-recent I/U entry on this `(collection, docId)`. Returns
|
|
638
|
-
* `undefined` when:
|
|
639
|
-
*
|
|
640
|
-
* - the doc's most-recent op was `D` (tombstone — no live body);
|
|
641
|
-
* - no entry for this doc lives inside the visible log range
|
|
642
|
-
* `[log_seq_start, currentNextSeq)` (a fresh-insert race or
|
|
643
|
-
* the doc has been folded into the snapshot but is no longer
|
|
644
|
-
* referenced).
|
|
645
|
-
*
|
|
646
|
-
* Used ONLY by the index-emission path on `U` / `D` to compute
|
|
647
|
-
* the stale-key set. Bounded by `log_seq_start`: entries below
|
|
648
|
-
* have been folded into the snapshot and may already be swept
|
|
649
|
-
* off the bucket — a snapshot fold is the rebuild command's job
|
|
650
|
-
* (see `./rebuild-index.ts`), not the writer's.
|
|
651
|
-
*
|
|
652
|
-
* **Cost note:** linear walk, O(snapshot lag). For day-one Phase
|
|
653
|
-
* 8 collections (helpdesk-shape: 100s of docs, <10k log entries)
|
|
654
|
-
* this is fine — the compactor folds the live tail every ~100
|
|
655
|
-
* entries (`packages/server/src/compactor.ts`). A follow-up ticket
|
|
656
|
-
* caches per-doc index head in `current.json` for O(1) lookup.
|
|
657
|
-
* The bound is documented; out of scope here.
|
|
658
|
-
*/
|
|
659
|
-
/**
|
|
660
|
-
* Auto-create the per-collection `current.json` at
|
|
661
|
-
* `this.#currentJsonKey` with a zero-state initial manifest. Called
|
|
662
|
-
* by `#singleAttemptCommit` when the read returned `null` (fresh
|
|
663
|
-
* bucket / fresh collection).
|
|
664
|
-
*
|
|
665
|
-
* Concurrency: `createCurrentJson` uses `If-None-Match: "*"`. If a
|
|
666
|
-
* peer raced us and won, the storage layer surfaces `Conflict`; we
|
|
667
|
-
* recover by re-reading the now-present manifest. We do NOT retry
|
|
668
|
-
* the create — a single recover-via-read covers every race that
|
|
669
|
-
* could have produced our null read.
|
|
670
|
-
*
|
|
671
|
-
* The seed shape (`snapshot: null`, `next_seq: 0`, `log_seq_start:
|
|
672
|
-
* 0`, `writer_fence: { epoch: 0, owner: "", claimed_at: "" }`)
|
|
673
|
-
* matches `ensureTable` and `baerly deploy`'s pre-warm path, so an
|
|
674
|
-
* operator who pre-provisions and a writer who auto-creates land
|
|
675
|
-
* on byte-identical bytes.
|
|
676
|
-
*
|
|
677
|
-
* @throws BaerlyError code="InvalidResponse" — the post-recover
|
|
678
|
-
* re-read also returned null. Defensive guard; in practice
|
|
679
|
-
* unreachable because the Conflict implies the key now exists.
|
|
680
|
-
*/
|
|
681
|
-
async #provisionCurrentJson() {
|
|
682
|
-
const initial = {
|
|
683
|
-
schema_version: 2,
|
|
684
|
-
snapshot: null,
|
|
685
|
-
next_seq: 0,
|
|
686
|
-
log_seq_start: 0,
|
|
687
|
-
writer_fence: {
|
|
688
|
-
epoch: 0,
|
|
689
|
-
owner: "",
|
|
690
|
-
claimed_at: ""
|
|
691
|
-
},
|
|
692
|
-
tail_bytes: 0,
|
|
693
|
-
snapshot_bytes: 0,
|
|
694
|
-
snapshot_rows: 0
|
|
695
|
-
};
|
|
696
|
-
try {
|
|
697
|
-
return await createCurrentJson(this.#storage, this.#currentJsonKey, initial);
|
|
698
|
-
} catch (error) {
|
|
699
|
-
if (!(error instanceof BaerlyError) || error.code !== "Conflict") throw error;
|
|
456
|
+
rangeAcc.set(field, acc);
|
|
700
457
|
}
|
|
701
|
-
const recovered = await readCurrentJson(this.#storage, this.#currentJsonKey);
|
|
702
|
-
if (recovered === null) throw new BaerlyError("InvalidResponse", `Writer: current.json missing at ${this.#currentJsonKey} after auto-create raced and recover read returned null`);
|
|
703
|
-
return recovered;
|
|
704
458
|
}
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
459
|
+
for (const [field, acc] of rangeAcc) rangeOps.set(field, {
|
|
460
|
+
...acc.lo !== void 0 ? { lo: acc.lo } : {},
|
|
461
|
+
...acc.hi !== void 0 ? { hi: acc.hi } : {},
|
|
462
|
+
loInclusive: acc.loInclusive,
|
|
463
|
+
hiInclusive: acc.hiInclusive
|
|
464
|
+
});
|
|
465
|
+
if (equality.size === 0 && rangeOps.size === 0 && inOps.size === 0) return {
|
|
466
|
+
kind: "full-scan",
|
|
467
|
+
reason: "predicate-uses-operators-only"
|
|
468
|
+
};
|
|
469
|
+
const candidates = [];
|
|
470
|
+
for (let defIndex = 0; defIndex < indexes.length; defIndex++) {
|
|
471
|
+
const def = indexes[defIndex];
|
|
472
|
+
const tuple = typeof def.on === "string" ? [def.on] : def.on;
|
|
473
|
+
const equalityKeys = [];
|
|
474
|
+
let tail;
|
|
475
|
+
for (let i = 0; i < tuple.length; i++) {
|
|
476
|
+
const field = tuple[i];
|
|
477
|
+
const v = equality.get(field);
|
|
478
|
+
if (v !== void 0) {
|
|
479
|
+
equalityKeys.push(v);
|
|
714
480
|
continue;
|
|
715
481
|
}
|
|
716
|
-
|
|
717
|
-
if (
|
|
718
|
-
|
|
482
|
+
const range = rangeOps.get(field);
|
|
483
|
+
if (range !== void 0) tail = {
|
|
484
|
+
kind: "range",
|
|
485
|
+
field,
|
|
486
|
+
info: range
|
|
487
|
+
};
|
|
488
|
+
else {
|
|
489
|
+
const inVals = inOps.get(field);
|
|
490
|
+
if (inVals !== void 0) tail = {
|
|
491
|
+
kind: "in",
|
|
492
|
+
field,
|
|
493
|
+
values: inVals
|
|
494
|
+
};
|
|
495
|
+
}
|
|
496
|
+
break;
|
|
719
497
|
}
|
|
498
|
+
const candidateLen = equalityKeys.length + (tail !== void 0 ? 1 : 0);
|
|
499
|
+
if (candidateLen === 0) continue;
|
|
500
|
+
candidates.push({
|
|
501
|
+
def,
|
|
502
|
+
defIndex,
|
|
503
|
+
prefixLen: candidateLen,
|
|
504
|
+
equalityKeys,
|
|
505
|
+
...tail !== void 0 ? { tail } : {}
|
|
506
|
+
});
|
|
720
507
|
}
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
* R2 prefix-partition rate-limit. Best-effort: detected via
|
|
743
|
-
* `BaerlyError{code:"NetworkError"}` with a `429` token in the
|
|
744
|
-
* message. Called from every PUT call site's catch arm; mutually
|
|
745
|
-
* exclusive in practice with `isPreconditionFailed` (412 ≠ 429).
|
|
746
|
-
*/
|
|
747
|
-
#observe429(err, collection) {
|
|
748
|
-
if (is429(err)) ctxMetrics().counter("db.r2.put.429_total", 1, { collection });
|
|
749
|
-
}
|
|
750
|
-
/**
|
|
751
|
-
* Emit the per-logical-write `class_a_ops_per_logical_write`
|
|
752
|
-
* histogram shared by `commit` and `commitBatch`. `classAOps`
|
|
753
|
-
* differs between the two paths (retry-budget vs batch shape),
|
|
754
|
-
* so each caller computes it.
|
|
755
|
-
*/
|
|
756
|
-
#emitWriteMetrics(collection, classAOps) {
|
|
757
|
-
ctxMetrics().histogram("db.write.class_a_ops_per_logical_write", classAOps, { collection });
|
|
758
|
-
}
|
|
759
|
-
/**
|
|
760
|
-
* Re-read `current.json` after a successful CAS and assert the
|
|
761
|
-
* writer-fence epoch is still ours. The CAS only mutated `next_seq`
|
|
762
|
-
* (the fence is preserved from `current`), so a post-write epoch
|
|
763
|
-
* mismatch can only mean another writer claimed the fence between
|
|
764
|
-
* our step-1 read and step-6 PUT — the exact split-brain
|
|
765
|
-
* `WriterFence` prevents. Throws `Conflict`; no retry, since the
|
|
766
|
-
* stale writer must defer to the new authority.
|
|
767
|
-
*
|
|
768
|
-
* The fence-verify GET is Class B and intentionally NOT counted in
|
|
769
|
-
* `class_a_ops_per_logical_write`.
|
|
770
|
-
*/
|
|
771
|
-
async #verifyFenceUnchanged(expectedEpoch, where) {
|
|
772
|
-
const postRead = await readCurrentJson(this.#storage, this.#currentJsonKey);
|
|
773
|
-
if (postRead === null) return;
|
|
774
|
-
if (postRead.json.writer_fence.epoch === expectedEpoch) return;
|
|
775
|
-
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`);
|
|
776
|
-
}
|
|
777
|
-
/**
|
|
778
|
-
* Exponential backoff with full jitter. `25 * 2^(attempt-1)` capped
|
|
779
|
-
* at 1500ms; uniform jitter in `[0, base)` keeps colliding peers
|
|
780
|
-
* from re-racing in lockstep. Worst-case total wait across the
|
|
781
|
-
* default 8 attempts is roughly 2.5 s — well under a typical
|
|
782
|
-
* Worker request budget.
|
|
783
|
-
*/
|
|
784
|
-
async #backoff(attempt) {
|
|
785
|
-
const sleepMs = Math.min(this.#initialBackoffMs * 2 ** (attempt - 1), MAX_BACKOFF_MS) * this.#random();
|
|
786
|
-
if (sleepMs <= 0) return;
|
|
787
|
-
await new Promise((r) => setTimeout(r, sleepMs));
|
|
508
|
+
if (candidates.length === 0) return {
|
|
509
|
+
kind: "full-scan",
|
|
510
|
+
reason: "no-matching-index"
|
|
511
|
+
};
|
|
512
|
+
const rank = (c) => {
|
|
513
|
+
if (c.def.predicate === void 0) return 1;
|
|
514
|
+
return predicateImplies(c.def.predicate, wire) ? 0 : 2;
|
|
515
|
+
};
|
|
516
|
+
candidates.sort((a, b) => {
|
|
517
|
+
const aRank = rank(a);
|
|
518
|
+
const bRank = rank(b);
|
|
519
|
+
if (aRank !== bRank) return aRank - bRank;
|
|
520
|
+
if (b.prefixLen !== a.prefixLen) return b.prefixLen - a.prefixLen;
|
|
521
|
+
return a.defIndex - b.defIndex;
|
|
522
|
+
});
|
|
523
|
+
const best = candidates[0];
|
|
524
|
+
if (best.tail !== void 0 && best.tail.kind === "in") {
|
|
525
|
+
if (best.tail.values.length > 50) return {
|
|
526
|
+
kind: "full-scan",
|
|
527
|
+
reason: "no-matching-index"
|
|
528
|
+
};
|
|
788
529
|
}
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
530
|
+
return {
|
|
531
|
+
kind: "index-walk",
|
|
532
|
+
indexName: best.def.name,
|
|
533
|
+
equalityKeys: best.equalityKeys,
|
|
534
|
+
...best.tail !== void 0 && best.tail.kind === "range" ? { rangeOn: {
|
|
535
|
+
field: best.tail.field,
|
|
536
|
+
...best.tail.info.lo !== void 0 ? { lo: best.tail.info.lo } : {},
|
|
537
|
+
...best.tail.info.hi !== void 0 ? { hi: best.tail.info.hi } : {},
|
|
538
|
+
loInclusive: best.tail.info.loInclusive,
|
|
539
|
+
hiInclusive: best.tail.info.hiInclusive
|
|
540
|
+
} } : {},
|
|
541
|
+
...best.tail !== void 0 && best.tail.kind === "in" ? { inOn: {
|
|
542
|
+
field: best.tail.field,
|
|
543
|
+
values: best.tail.values
|
|
544
|
+
} } : {}
|
|
545
|
+
};
|
|
805
546
|
};
|
|
806
547
|
//#endregion
|
|
807
|
-
//#region packages/server/src/
|
|
548
|
+
//#region packages/server/src/schema.ts
|
|
808
549
|
/**
|
|
809
|
-
*
|
|
810
|
-
*
|
|
811
|
-
* filtered index's predicate. The query planner uses the result to
|
|
812
|
-
* rank candidate indexes; see {@link "./query-planner.ts".planQuery}.
|
|
550
|
+
* Schema-validator runtime helper for `Db.insert` / `Query.update` /
|
|
551
|
+
* `Collection.replace` boundary checks.
|
|
813
552
|
*
|
|
814
|
-
*
|
|
815
|
-
*
|
|
816
|
-
*
|
|
553
|
+
* The `SchemaValidator` / `SchemaIssue` TYPES live in
|
|
554
|
+
* `@baerly/protocol` (cross-platform). This module owns the runtime
|
|
555
|
+
* helper `validateOrThrow` that runs a validator and raises a
|
|
556
|
+
* `BaerlyError{code:"SchemaError"}` on failure.
|
|
817
557
|
*
|
|
818
|
-
*
|
|
819
|
-
*
|
|
820
|
-
*
|
|
821
|
-
*
|
|
822
|
-
*
|
|
558
|
+
* @example
|
|
559
|
+
* ```ts
|
|
560
|
+
* import { z } from "zod";
|
|
561
|
+
* import { defineConfig } from "@gusto/baerly-storage/config";
|
|
562
|
+
*
|
|
563
|
+
* const Ticket = z.object({
|
|
564
|
+
* _id: z.string(),
|
|
565
|
+
* status: z.enum(["open", "closed"]),
|
|
566
|
+
* title: z.string().min(1),
|
|
567
|
+
* });
|
|
568
|
+
*
|
|
569
|
+
* export default defineConfig({
|
|
570
|
+
* collections: {
|
|
571
|
+
* tickets: { schema: Ticket },
|
|
572
|
+
* },
|
|
573
|
+
* });
|
|
574
|
+
* ```
|
|
823
575
|
*/
|
|
824
576
|
/**
|
|
825
|
-
*
|
|
826
|
-
*
|
|
827
|
-
*
|
|
828
|
-
*
|
|
577
|
+
* Run a validator and throw `BaerlyError{code:"SchemaError"}` on failure.
|
|
578
|
+
* On success returns the validator's output (which for transforming
|
|
579
|
+
* validators may differ from the input).
|
|
580
|
+
*
|
|
581
|
+
* Field paths are normalised to `(string | number)[]` so the wire shape
|
|
582
|
+
* is JSON-clean. Symbol keys (rare; StandardSchemaV1 permits them) are
|
|
583
|
+
* coerced to `String(sym)` — we never emit `symbol` on the wire.
|
|
584
|
+
*
|
|
585
|
+
* The thrown error's `message` carries a one-line summary
|
|
586
|
+
* (`"<collection>.<verb>: <issuesCount> field(s) failed validation: <first>"`)
|
|
587
|
+
* for stderr-readable logs; the structured `issues` are on `.issues`.
|
|
829
588
|
*/
|
|
830
|
-
const
|
|
831
|
-
const
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
589
|
+
const validateOrThrow = async (schema, candidate, context) => {
|
|
590
|
+
const result = await schema["~standard"].validate(candidate);
|
|
591
|
+
if (result.issues === void 0) return result.value;
|
|
592
|
+
const issues = result.issues.map((i) => ({
|
|
593
|
+
path: (i.path ?? []).map((p) => {
|
|
594
|
+
const raw = typeof p === "object" && p !== null && "key" in p ? p.key : p;
|
|
595
|
+
return typeof raw === "number" ? raw : String(raw);
|
|
596
|
+
}),
|
|
597
|
+
message: i.message
|
|
598
|
+
}));
|
|
599
|
+
const first = issues[0];
|
|
600
|
+
const summary = first === void 0 ? "schema validation failed (no issues reported)" : `${first.path.length === 0 ? "<root>" : first.path.join(".")}: ${first.message}`;
|
|
601
|
+
throw new BaerlyError("SchemaError", `${context.collection}.${context.verb}: ${issues.length} field${issues.length === 1 ? "" : "s"} failed validation: ${summary}`, void 0, issues);
|
|
838
602
|
};
|
|
603
|
+
//#endregion
|
|
604
|
+
//#region packages/server/src/key-limit.ts
|
|
605
|
+
const utf8 = new TextEncoder();
|
|
839
606
|
/**
|
|
840
|
-
*
|
|
841
|
-
*
|
|
842
|
-
*
|
|
843
|
-
*
|
|
844
|
-
*
|
|
845
|
-
* field: the validator proves they all agree, so we pick the first.
|
|
846
|
-
* Multiple range clauses on one field: take the strictest bound
|
|
847
|
-
* (tightest `lo` = numerically largest; tightest `hi` = numerically
|
|
848
|
-
* smallest).
|
|
607
|
+
* Reject an assembled object key over the S3/R2 full-key ceiling
|
|
608
|
+
* ({@link MAX_KEY_BYTES}) as `InvalidConfig`. Per-segment caps don't
|
|
609
|
+
* bound the sum, and index values skip `assertPathSegment` entirely, so
|
|
610
|
+
* this post-encoding check at the writer's PUT sites is their only
|
|
611
|
+
* overflow guard. @see docs/spec/storage-compatibility.md
|
|
849
612
|
*/
|
|
850
|
-
const
|
|
851
|
-
const
|
|
852
|
-
|
|
853
|
-
const v = clause.value;
|
|
854
|
-
if (clause.op === "eq") bundle.eq = v;
|
|
855
|
-
else if (clause.op === "gte") {
|
|
856
|
-
const next = {
|
|
857
|
-
value: v,
|
|
858
|
-
inclusive: true
|
|
859
|
-
};
|
|
860
|
-
bundle.lo = tightestLo(bundle.lo, next);
|
|
861
|
-
} else if (clause.op === "gt") {
|
|
862
|
-
const next = {
|
|
863
|
-
value: v,
|
|
864
|
-
inclusive: false
|
|
865
|
-
};
|
|
866
|
-
bundle.lo = tightestLo(bundle.lo, next);
|
|
867
|
-
} else if (clause.op === "lte") {
|
|
868
|
-
const next = {
|
|
869
|
-
value: v,
|
|
870
|
-
inclusive: true
|
|
871
|
-
};
|
|
872
|
-
bundle.hi = tightestHi(bundle.hi, next);
|
|
873
|
-
} else if (clause.op === "lt") {
|
|
874
|
-
const next = {
|
|
875
|
-
value: v,
|
|
876
|
-
inclusive: false
|
|
877
|
-
};
|
|
878
|
-
bundle.hi = tightestHi(bundle.hi, next);
|
|
879
|
-
} else if (clause.op === "in") {
|
|
880
|
-
if (bundle.in !== void 0) return "unknown-shape";
|
|
881
|
-
if (!Array.isArray(v)) return "unknown-shape";
|
|
882
|
-
bundle.in = v;
|
|
883
|
-
} else return "unknown-shape";
|
|
884
|
-
}
|
|
885
|
-
return bundle;
|
|
886
|
-
};
|
|
887
|
-
const tightestLo = (existing, next) => {
|
|
888
|
-
if (existing === void 0) return next;
|
|
889
|
-
if (typeof existing.value !== typeof next.value) return existing;
|
|
890
|
-
if (next.value > existing.value) return next;
|
|
891
|
-
if (next.value < existing.value) return existing;
|
|
892
|
-
if (!next.inclusive && existing.inclusive) return next;
|
|
893
|
-
return existing;
|
|
894
|
-
};
|
|
895
|
-
const tightestHi = (existing, next) => {
|
|
896
|
-
if (existing === void 0) return next;
|
|
897
|
-
if (typeof existing.value !== typeof next.value) return existing;
|
|
898
|
-
if (next.value < existing.value) return next;
|
|
899
|
-
if (next.value > existing.value) return existing;
|
|
900
|
-
if (!next.inclusive && existing.inclusive) return next;
|
|
901
|
-
return existing;
|
|
613
|
+
const assertKeyWithinLimit = (key) => {
|
|
614
|
+
const bytes = utf8.encode(key).length;
|
|
615
|
+
if (bytes > 1024) throw new BaerlyError("InvalidConfig", `object key exceeds ${MAX_KEY_BYTES} bytes (got ${bytes}): ${JSON.stringify(key.slice(0, 80))}…`);
|
|
902
616
|
};
|
|
617
|
+
//#endregion
|
|
618
|
+
//#region packages/server/src/log-conflict-adoption.ts
|
|
903
619
|
/**
|
|
904
|
-
*
|
|
905
|
-
*
|
|
620
|
+
* Decide whether the entry already at `/log/<seq>.json` is the
|
|
621
|
+
* writer's own prior in-flight attempt and may be adopted. Pure
|
|
622
|
+
* function; no I/O. The caller performs the GET (when the log PUT
|
|
623
|
+
* surfaces 412) and passes the read-back body in `ctx.existing`.
|
|
906
624
|
*
|
|
907
|
-
*
|
|
908
|
-
*
|
|
909
|
-
*
|
|
625
|
+
* ## Correctness precondition
|
|
626
|
+
*
|
|
627
|
+
* A fresh `session` id is minted per `commit()` call, seq-stable
|
|
628
|
+
* across that call's retries. Adoption compares the writer-minted
|
|
629
|
+
* intent/body fields as well as session and seq: a dropped-ack retry
|
|
630
|
+
* reuses the same attempted entry and adopts, while a same-session /
|
|
631
|
+
* same-seq occupant carrying a different logical mutation is treated as
|
|
632
|
+
* a conflict and skipped by the caller's forward-probe loop.
|
|
633
|
+
*
|
|
634
|
+
* @see {@link AdoptionDecision} for the return shape.
|
|
635
|
+
* @see The soundness invariant in this module's header docstring.
|
|
910
636
|
*/
|
|
911
|
-
const
|
|
912
|
-
if (
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
if (loQ.value < loF.value) return false;
|
|
916
|
-
if (loF.inclusive) return true;
|
|
917
|
-
return !loQ.inclusive;
|
|
918
|
-
};
|
|
919
|
-
/** Mirror of lowerBoundImplies for upper bounds. */
|
|
920
|
-
const upperBoundImplies = (hiF, hiQ) => {
|
|
921
|
-
if (hiQ === void 0) return false;
|
|
922
|
-
if (typeof hiF.value !== typeof hiQ.value) return false;
|
|
923
|
-
if (hiQ.value < hiF.value) return true;
|
|
924
|
-
if (hiQ.value > hiF.value) return false;
|
|
925
|
-
if (hiF.inclusive) return true;
|
|
926
|
-
return !hiQ.inclusive;
|
|
927
|
-
};
|
|
928
|
-
const loFromQuery = (q) => {
|
|
929
|
-
if (q.eq !== void 0) return {
|
|
930
|
-
value: q.eq,
|
|
931
|
-
inclusive: true
|
|
637
|
+
const tryAdoptOwnSessionLogEntry = (ctx) => {
|
|
638
|
+
if (ctx.existing.session !== ctx.self.session) return {
|
|
639
|
+
adopt: false,
|
|
640
|
+
reason: "foreign-session"
|
|
932
641
|
};
|
|
933
|
-
if (
|
|
934
|
-
|
|
935
|
-
|
|
642
|
+
if (ctx.existing.seq !== ctx.self.seq) return {
|
|
643
|
+
adopt: false,
|
|
644
|
+
reason: "wrong-seq"
|
|
936
645
|
};
|
|
937
|
-
return
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
if (q.eq !== void 0) return {
|
|
941
|
-
value: q.eq,
|
|
942
|
-
inclusive: true
|
|
646
|
+
if (JSON.stringify(ctx.existing) !== JSON.stringify(ctx.self)) return {
|
|
647
|
+
adopt: false,
|
|
648
|
+
reason: "intent-mismatch"
|
|
943
649
|
};
|
|
944
|
-
|
|
945
|
-
|
|
946
|
-
|
|
650
|
+
return {
|
|
651
|
+
adopt: true,
|
|
652
|
+
entry: ctx.existing
|
|
947
653
|
};
|
|
948
|
-
return q.hi;
|
|
949
654
|
};
|
|
655
|
+
//#endregion
|
|
656
|
+
//#region packages/server/src/writer.ts
|
|
950
657
|
/**
|
|
951
|
-
*
|
|
952
|
-
*
|
|
953
|
-
*
|
|
954
|
-
*
|
|
955
|
-
*
|
|
956
|
-
*
|
|
957
|
-
*
|
|
958
|
-
*
|
|
959
|
-
*
|
|
960
|
-
*
|
|
961
|
-
*
|
|
962
|
-
*
|
|
963
|
-
*
|
|
964
|
-
*
|
|
965
|
-
*
|
|
966
|
-
*
|
|
967
|
-
*
|
|
968
|
-
*
|
|
969
|
-
*
|
|
970
|
-
*
|
|
971
|
-
*
|
|
972
|
-
*
|
|
973
|
-
*
|
|
974
|
-
*
|
|
975
|
-
*
|
|
976
|
-
*
|
|
977
|
-
*
|
|
978
|
-
*
|
|
979
|
-
*
|
|
980
|
-
*
|
|
981
|
-
*
|
|
658
|
+
* `Writer` — stateless multi-instance write engine (single-write commit).
|
|
659
|
+
*
|
|
660
|
+
* Each {@link Writer.commit} reads `current.json` FRESH (for
|
|
661
|
+
* `log_seq_start` / `tail_hint` as a probe FLOOR — a lower bound, NOT a
|
|
662
|
+
* CAS precondition), PUTs the content body, then **creates `log/<seq>`
|
|
663
|
+
* via `If-None-Match: "*"`. That create IS the commit / linearization
|
|
664
|
+
* point.** The writer writes NOTHING to `current.json` on the commit
|
|
665
|
+
* path; `tail_hint` advances outside ordinary commits via compaction
|
|
666
|
+
* folds, write-tick refreshes, and explicit operator/import paths. The
|
|
667
|
+
* commit model and its invariants are recorded in ADR-004
|
|
668
|
+
* (`docs/adr/004-single-write-commit.md`). The
|
|
669
|
+
* optional integrity walk is gated by
|
|
670
|
+
* {@link WriterOptions.verifyLogIntegrityOnCommit} (default off).
|
|
671
|
+
*
|
|
672
|
+
* No per-write cache: every commit re-reads + re-probes, so N stateless
|
|
673
|
+
* instances contend at one place — the `If-None-Match` create of
|
|
674
|
+
* `log/<seq>`. The loser gets a 412 and re-probes forward to the next
|
|
675
|
+
* empty slot. A 412 from the writer's OWN session at the same seq is its
|
|
676
|
+
* own lost-ack / crashed-but-durable commit → adopted (not retried), so
|
|
677
|
+
* the write lands at EXACTLY `seq`, never duplicated.
|
|
678
|
+
*
|
|
679
|
+
* **Crash safety.** Order is content + additive index `newKeys` →
|
|
680
|
+
* `log/<seq>` create → stale index-key DELETEs. A crash before the
|
|
681
|
+
* create leaves an unreferenced content body + orphan additive index
|
|
682
|
+
* keys (no log entry references them), not an orphan log entry with
|
|
683
|
+
* missing content — the compactor sweeps the content, and a stray
|
|
684
|
+
* additive key only ever yields a false-POSITIVE candidate that
|
|
685
|
+
* `matchesWire` (read path) drops. Emitting `newKeys` before the commit
|
|
686
|
+
* means a committed row is ALWAYS index-findable; the stale-key DELETE
|
|
687
|
+
* stays after the commit so a crash can never de-index a committed
|
|
688
|
+
* doc. See `index-emit-order.test.ts` and ADR-004 Q4.
|
|
982
689
|
*
|
|
983
|
-
*
|
|
984
|
-
* `
|
|
690
|
+
* **`LogEntry` shape.** Emitted entries follow the contract in
|
|
691
|
+
* `packages/protocol/src/log.ts` (see {@link LogEntry}) and
|
|
692
|
+
* `docs/spec/log-entry-shape.md`. The on-bucket key is
|
|
693
|
+
* `log/<seq>.json` (the integer `seq` is the load-bearing
|
|
694
|
+
* identifier; the `lsn` string is schema-only).
|
|
985
695
|
*
|
|
986
|
-
*
|
|
987
|
-
*
|
|
988
|
-
*
|
|
989
|
-
* `./query-planner-implies.test.ts`.
|
|
696
|
+
* @see docs/spec/sync-protocol.md for the protocol invariants this
|
|
697
|
+
* loop preserves.
|
|
698
|
+
* @see docs/spec/log-entry-shape.md for the per-field contract.
|
|
990
699
|
*/
|
|
991
|
-
const
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
|
|
1003
|
-
|
|
1004
|
-
continue;
|
|
1005
|
-
}
|
|
1006
|
-
if (filterBundle.in !== void 0) {
|
|
1007
|
-
const set = filterBundle.in;
|
|
1008
|
-
const contains = (v) => set.some((m) => deepEqualDocumentValue(m, v));
|
|
1009
|
-
if (queryBundle.eq !== void 0) {
|
|
1010
|
-
if (!contains(queryBundle.eq)) return false;
|
|
1011
|
-
} else if (queryBundle.in !== void 0) {
|
|
1012
|
-
for (const v of queryBundle.in) if (!contains(v)) return false;
|
|
1013
|
-
} else return false;
|
|
1014
|
-
continue;
|
|
1015
|
-
}
|
|
1016
|
-
if (filterBundle.lo !== void 0) {
|
|
1017
|
-
if (!lowerBoundImplies(filterBundle.lo, loFromQuery(queryBundle))) return false;
|
|
1018
|
-
}
|
|
1019
|
-
if (filterBundle.hi !== void 0) {
|
|
1020
|
-
if (!upperBoundImplies(filterBundle.hi, hiFromQuery(queryBundle))) return false;
|
|
1021
|
-
}
|
|
1022
|
-
}
|
|
1023
|
-
return true;
|
|
1024
|
-
};
|
|
700
|
+
const CAS_CONFLICT_RESOLUTION = "Re-read and retry.";
|
|
701
|
+
const ctxMetrics = () => getCurrentContext()?.recorder ?? noopMetricsRecorder;
|
|
702
|
+
const DEFAULT_INITIAL_BACKOFF_MS = 25;
|
|
703
|
+
const MAX_BACKOFF_MS = 1500;
|
|
704
|
+
const APPLICATION_JSON = "application/json";
|
|
705
|
+
/**
|
|
706
|
+
* Empty body for index entries. Each index entry is a fact ("doc
|
|
707
|
+
* `<docId>` has `<field> = <value>`"), not data — readers list the
|
|
708
|
+
* prefix, extract the doc id, then GET the content body separately.
|
|
709
|
+
* Pre-allocated module-level constant so every index PUT shares one
|
|
710
|
+
* zero-length buffer.
|
|
711
|
+
*/
|
|
712
|
+
const EMPTY_BODY = /* @__PURE__ */ new Uint8Array(0);
|
|
1025
713
|
/**
|
|
1026
|
-
*
|
|
1027
|
-
* Pure function. The executor enforces the I/O semantics; the
|
|
1028
|
-
* planner's only contract is "given these inputs, this is the
|
|
1029
|
-
* routing decision."
|
|
714
|
+
* Stateless write engine for the multi-instance core.
|
|
1030
715
|
*
|
|
1031
|
-
*
|
|
1032
|
-
*
|
|
1033
|
-
*
|
|
1034
|
-
* 3. Partition wire clauses per field into:
|
|
1035
|
-
* - `equality[f] = v` from `eq` clauses.
|
|
1036
|
-
* - `rangeOps[f] = {lo, hi, loInclusive, hiInclusive}` from
|
|
1037
|
-
* one or more of `gt`/`gte`/`lt`/`lte` clauses on `f`.
|
|
1038
|
-
* - `inOps[f] = [...]` from a single `in` clause on `f`.
|
|
1039
|
-
* - Defensive: any field whose clause group mixes op-channels
|
|
1040
|
-
* (mostly impossible post-validation) is marked unroutable
|
|
1041
|
-
* and skipped — the executor's full-wire `matchesWire(...)`
|
|
1042
|
-
* post-fetch catches the residue automatically.
|
|
1043
|
-
* 4. If no equality / range / `in` candidates exist →
|
|
1044
|
-
* `predicate-uses-operators-only`.
|
|
1045
|
-
* 5. For each `def`, walk `def.on` left-to-right consuming
|
|
1046
|
-
* equality clauses for each indexed field. On the FIRST field
|
|
1047
|
-
* where the equality clause is absent, check whether a range
|
|
1048
|
-
* or `in` clause is available for that field — if so, that's
|
|
1049
|
-
* the "tail slot" of the walk.
|
|
1050
|
-
* 6. Score candidates by `(equalityPrefixLen, hasTailExtension)`.
|
|
1051
|
-
* Longest prefix wins; tail-extension breaks ties. If no
|
|
1052
|
-
* candidate consumed at least one field (equality OR
|
|
1053
|
-
* range/`in`): `no-matching-index`.
|
|
1054
|
-
* 7. `in` FAN-OUT GUARD: if the chosen plan's `in` slot has
|
|
1055
|
-
* `values.length > IN_FANOUT_THRESHOLD`, fall back to
|
|
1056
|
-
* `FullScanPlan{reason:"no-matching-index"}` — N sequential
|
|
1057
|
-
* LISTs cost more than a snapshot+log fold.
|
|
716
|
+
* Construction is cheap and performs zero I/O — adapters build a
|
|
717
|
+
* fresh `Writer` per request and discard it. All real work
|
|
718
|
+
* happens in {@link commit}.
|
|
1058
719
|
*
|
|
1059
|
-
*
|
|
1060
|
-
*
|
|
1061
|
-
*
|
|
1062
|
-
*
|
|
720
|
+
* @example
|
|
721
|
+
* ```ts
|
|
722
|
+
* import { Writer } from "@gusto/baerly-storage";
|
|
723
|
+
* import { MemoryStorage } from "@gusto/baerly-storage";
|
|
1063
724
|
*
|
|
1064
|
-
*
|
|
1065
|
-
*
|
|
1066
|
-
*
|
|
1067
|
-
*
|
|
1068
|
-
*
|
|
1069
|
-
*
|
|
725
|
+
* const writer = new Writer({
|
|
726
|
+
* storage: new MemoryStorage(),
|
|
727
|
+
* currentJsonKey: "app/tickets/tenant/acme/manifests/tickets/current.json",
|
|
728
|
+
* });
|
|
729
|
+
*
|
|
730
|
+
* const result = await writer.commit({
|
|
731
|
+
* op: "I",
|
|
732
|
+
* collection: "tickets",
|
|
733
|
+
* docId: "doc-1",
|
|
734
|
+
* body: { _id: "doc-1", title: "hello" },
|
|
735
|
+
* });
|
|
736
|
+
* console.log(result.entry.seq, result.attempts);
|
|
737
|
+
* ```
|
|
1070
738
|
*/
|
|
1071
|
-
|
|
1072
|
-
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
1086
|
-
const
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
|
|
1090
|
-
|
|
1091
|
-
|
|
1092
|
-
|
|
1093
|
-
|
|
739
|
+
var Writer = class {
|
|
740
|
+
#storage;
|
|
741
|
+
#currentJsonKey;
|
|
742
|
+
#maxRetries;
|
|
743
|
+
#initialBackoffMs;
|
|
744
|
+
#random;
|
|
745
|
+
#indexes;
|
|
746
|
+
#verifyLogIntegrityOnCommit;
|
|
747
|
+
constructor(opts) {
|
|
748
|
+
this.#storage = opts.storage;
|
|
749
|
+
this.#currentJsonKey = opts.currentJsonKey;
|
|
750
|
+
this.#maxRetries = opts.options?.maxRetries ?? 8;
|
|
751
|
+
this.#initialBackoffMs = opts.options?.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS;
|
|
752
|
+
this.#random = opts.options?.random ?? Math.random;
|
|
753
|
+
const indexes = opts.options?.indexes ?? [];
|
|
754
|
+
for (const def of indexes) validateIndexDefinition(def);
|
|
755
|
+
this.#indexes = indexes;
|
|
756
|
+
this.#verifyLogIntegrityOnCommit = opts.options?.verifyLogIntegrityOnCommit ?? false;
|
|
757
|
+
}
|
|
758
|
+
/**
|
|
759
|
+
* Atomically commit one mutation. Reads `current.json` fresh (as a
|
|
760
|
+
* probe FLOOR, not a CAS precondition), PUTs the content body and any
|
|
761
|
+
* additive index `newKeys`, then creates `log/<seq>` via
|
|
762
|
+
* `If-None-Match: "*"` — that create IS the commit (single-write
|
|
763
|
+
* commit; no `current.json` CAS follows it). Stale index keys are
|
|
764
|
+
* DELETE'd after the commit.
|
|
765
|
+
*
|
|
766
|
+
* The hot-path cost under no contention on an unindexed collection is
|
|
767
|
+
* 1 GET + 2 PUTs (content + the committing `log/<seq>` create); each
|
|
768
|
+
* declared index that projects a key on this write adds one PUT
|
|
769
|
+
* (new key, before the commit) and, on U/D, up to one DELETE (stale
|
|
770
|
+
* key, after the commit). An in-flight peer write costs one extra GET
|
|
771
|
+
* + the backoff sleep per retry.
|
|
772
|
+
*
|
|
773
|
+
* Idempotency: PUT content uses `If-None-Match: "*"`, so a retry of
|
|
774
|
+
* the same logical write produces the same content key and the
|
|
775
|
+
* second PUT no-ops. The `log/<seq>` create also uses
|
|
776
|
+
* `If-None-Match: "*"`, so two writers racing the same tail cause
|
|
777
|
+
* exactly one create to win; the loser reads back the occupant,
|
|
778
|
+
* adopts its own lost-ack write or re-probes forward to the next
|
|
779
|
+
* empty slot.
|
|
780
|
+
*
|
|
781
|
+
* @throws BaerlyError code="Conflict" when a retryable conflict
|
|
782
|
+
* escapes the single-attempt helper and exhausts the retry budget
|
|
783
|
+
* (presently unreachable on the log-create 412 path).
|
|
784
|
+
* @throws BaerlyError code="Internal" when a log entry expected in
|
|
785
|
+
* `[0, tail_hint)` is missing — a protocol-invariant violation
|
|
786
|
+
* (compactor bug or stale `current.json`).
|
|
787
|
+
* @throws BaerlyError code="InvalidResponse" when a log-entry body
|
|
788
|
+
* isn't valid JSON.
|
|
789
|
+
*
|
|
790
|
+
* **Implicit provisioning.** When `current.json` does not exist at
|
|
791
|
+
* `currentJsonKey` (fresh bucket, fresh collection), the writer
|
|
792
|
+
* auto-creates it with a zero-state manifest before the commit
|
|
793
|
+
* lands. The cost is one extra Class A PUT on the very first
|
|
794
|
+
* commit per collection; steady-state cost is unchanged. A peer
|
|
795
|
+
* racing the same first-write loses cleanly on the create CAS
|
|
796
|
+
* and re-reads to pick up the winner's manifest.
|
|
797
|
+
*/
|
|
798
|
+
async commit(input) {
|
|
799
|
+
assertDocId(input.docId);
|
|
800
|
+
const session = uuid().slice(0, 6);
|
|
801
|
+
const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
|
|
802
|
+
for (let attempt = 1; attempt <= this.#maxRetries; attempt++) {
|
|
803
|
+
let success;
|
|
804
|
+
try {
|
|
805
|
+
success = await this.#singleAttemptCommit(input, session, logPrefix, "Writer");
|
|
806
|
+
} catch (error) {
|
|
807
|
+
if (!isPreconditionFailed(error)) throw error;
|
|
808
|
+
await this.#backoff(attempt);
|
|
1094
809
|
continue;
|
|
1095
810
|
}
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
|
|
1099
|
-
|
|
1100
|
-
|
|
1101
|
-
|
|
1102
|
-
|
|
1103
|
-
|
|
811
|
+
this.#emitWriteMetrics(input.collection, success.classAOps + (attempt - 1));
|
|
812
|
+
return {
|
|
813
|
+
entry: success.entries[0],
|
|
814
|
+
currentEtag: success.currentEtag,
|
|
815
|
+
attempts: attempt
|
|
816
|
+
};
|
|
817
|
+
}
|
|
818
|
+
throw new BaerlyError("Conflict", `Writer: CAS conflict on ${this.#currentJsonKey} after ${this.#maxRetries} attempts`, void 0, void 0, void 0, CAS_CONFLICT_RESOLUTION, true);
|
|
819
|
+
}
|
|
820
|
+
/**
|
|
821
|
+
* One full commit attempt — the body of {@link commit}. Reads
|
|
822
|
+
* `current.json`, PUTs content + additive index `newKeys` in parallel,
|
|
823
|
+
* then forward-probes the tail and creates `log/<seq>` once via
|
|
824
|
+
* `If-None-Match: "*"` — the numbered log create IS the commit
|
|
825
|
+
* (single-write commit; no `current.json` CAS follows it). Stale index
|
|
826
|
+
* keys are DELETE'd after the commit. Returns the success payload.
|
|
827
|
+
*
|
|
828
|
+
* Commits exactly one {@link CommitInput} — the numbered log create is
|
|
829
|
+
* the single linearization point per call.
|
|
830
|
+
*
|
|
831
|
+
* A log-create 412 is disambiguated by session read-back: own session
|
|
832
|
+
* / own seq ⇒ our crashed-or-lost-ack commit is already durable ⇒
|
|
833
|
+
* adopt; foreign session ⇒ re-probe forward and retry at the next
|
|
834
|
+
* empty slot. Thrown `BaerlyError`s (Internal, InvalidResponse,
|
|
835
|
+
* NetworkError) propagate.
|
|
836
|
+
*
|
|
837
|
+
* Crash safety invariant: content + additive index `newKeys` PUTs are
|
|
838
|
+
* awaited before the log create. A crash before the create leaves
|
|
839
|
+
* orphan content + additive index keys (no log entry references them)
|
|
840
|
+
* — the compactor sweeps the content, and a stray additive key only
|
|
841
|
+
* yields a false-positive candidate that `matchesWire` drops. A crash
|
|
842
|
+
* AFTER the create is a durable, committed write at `seq` whose index
|
|
843
|
+
* `newKeys` are already present (so it's index-findable); the only
|
|
844
|
+
* residual is a possibly-undeleted stale OLD-value key, dropped by
|
|
845
|
+
* `matchesWire` and cleaned by a later write / `rebuild-index`. The
|
|
846
|
+
* inverse — committed log entry with missing content, or a de-indexed
|
|
847
|
+
* committed doc — is never produced.
|
|
848
|
+
*/
|
|
849
|
+
async #singleAttemptCommit(input, session, logPrefix, errorPrefix) {
|
|
850
|
+
const read = await readCurrentJson(this.#storage, this.#currentJsonKey) ?? await this.#provisionCurrentJson();
|
|
851
|
+
const current = read.json;
|
|
852
|
+
const baseEtag = read.etag;
|
|
853
|
+
if (this.#verifyLogIntegrityOnCommit) await this.#walkLog(logPrefix, logSeqStartOf(current), current.tail_hint);
|
|
854
|
+
const probeFloor = Math.max(logSeqStartOf(current), current.tail_hint);
|
|
855
|
+
const preCommitTail = await findLogTail(this.#storage, logPrefix, probeFloor);
|
|
856
|
+
let seq = preCommitTail;
|
|
857
|
+
const commitNowMs = Date.now();
|
|
858
|
+
const commitTs = new Date(commitNowMs).toISOString();
|
|
859
|
+
const lsnTimestamp = timestamp(commitNowMs);
|
|
860
|
+
const mintEntry = (atSeq) => ({
|
|
861
|
+
lsn: `${lsnTimestamp}_${session}_${countKey(atSeq)}`,
|
|
862
|
+
commit_ts: commitTs,
|
|
863
|
+
op: input.op,
|
|
864
|
+
collection: input.collection,
|
|
865
|
+
doc_id: input.docId,
|
|
866
|
+
session,
|
|
867
|
+
seq: atSeq,
|
|
868
|
+
...input.op !== "D" && input.body !== void 0 ? { after: input.body } : {},
|
|
869
|
+
...input.origin !== void 0 ? { origin: input.origin } : {}
|
|
870
|
+
});
|
|
871
|
+
let entry = mintEntry(seq);
|
|
872
|
+
let contentPutCount = 0;
|
|
873
|
+
let newKeysClassA = 0;
|
|
874
|
+
const parallelPuts = [];
|
|
875
|
+
if (input.op !== "D" && input.body !== void 0) {
|
|
876
|
+
contentPutCount++;
|
|
877
|
+
const bytes = encodeJsonBytes(input.body);
|
|
878
|
+
const contentKey = `${logPrefix}/content/${await versionFromContent(bytes)}.json`;
|
|
879
|
+
assertKeyWithinLimit(contentKey);
|
|
880
|
+
parallelPuts.push(this.#storage.put(contentKey, bytes, {
|
|
881
|
+
ifNoneMatch: "*",
|
|
882
|
+
contentType: APPLICATION_JSON
|
|
883
|
+
}).catch((error) => {
|
|
884
|
+
this.#observe429(error, input.collection);
|
|
885
|
+
if (isPreconditionFailed(error)) return;
|
|
886
|
+
throw error;
|
|
887
|
+
}));
|
|
888
|
+
}
|
|
889
|
+
if (this.#indexes.length > 0 && input.op !== "D") {
|
|
890
|
+
const newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
|
|
891
|
+
for (const k of newKeys) {
|
|
892
|
+
assertKeyWithinLimit(k);
|
|
893
|
+
newKeysClassA++;
|
|
894
|
+
parallelPuts.push(this.#storage.put(k, EMPTY_BODY, {
|
|
895
|
+
ifNoneMatch: "*",
|
|
896
|
+
contentType: APPLICATION_JSON
|
|
897
|
+
}).catch((error) => {
|
|
898
|
+
this.#observe429(error, input.collection);
|
|
899
|
+
if (isPreconditionFailed(error)) return;
|
|
900
|
+
throw error;
|
|
901
|
+
}));
|
|
1104
902
|
}
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
|
|
903
|
+
}
|
|
904
|
+
await Promise.all(parallelPuts);
|
|
905
|
+
let committedEntry = entry;
|
|
906
|
+
let probes = 0;
|
|
907
|
+
let transientRetries = 0;
|
|
908
|
+
for (;;) {
|
|
909
|
+
const logEntryKey = logObjectKey(logPrefix, seq);
|
|
910
|
+
assertKeyWithinLimit(logEntryKey);
|
|
911
|
+
let conflicted = false;
|
|
912
|
+
try {
|
|
913
|
+
await this.#storage.put(logEntryKey, encodeJsonBytes(entry), {
|
|
914
|
+
ifNoneMatch: "*",
|
|
915
|
+
contentType: APPLICATION_JSON
|
|
916
|
+
});
|
|
917
|
+
} catch (error) {
|
|
918
|
+
this.#observe429(error, entry.collection);
|
|
919
|
+
if (isPreconditionFailed(error)) {
|
|
920
|
+
ctxMetrics().counter("db.r2.put.412_total", 1, {
|
|
921
|
+
collection: entry.collection,
|
|
922
|
+
step: "log-put"
|
|
923
|
+
});
|
|
924
|
+
conflicted = true;
|
|
925
|
+
} else if (isTransientWrite(error) && transientRetries < this.#maxRetries) {
|
|
926
|
+
transientRetries++;
|
|
927
|
+
await this.#backoff(transientRetries);
|
|
928
|
+
continue;
|
|
929
|
+
} else throw error;
|
|
1108
930
|
}
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
unroutable.add(field);
|
|
1113
|
-
equality.delete(field);
|
|
1114
|
-
inOps.delete(field);
|
|
1115
|
-
rangeAcc.delete(field);
|
|
1116
|
-
continue;
|
|
931
|
+
if (!conflicted) {
|
|
932
|
+
committedEntry = entry;
|
|
933
|
+
break;
|
|
1117
934
|
}
|
|
1118
|
-
const
|
|
1119
|
-
|
|
1120
|
-
|
|
1121
|
-
|
|
1122
|
-
|
|
1123
|
-
if (
|
|
1124
|
-
|
|
1125
|
-
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
|
-
|
|
1135
|
-
|
|
1136
|
-
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1140
|
-
|
|
1141
|
-
|
|
1142
|
-
|
|
935
|
+
const existing = await readLogEntry(this.#storage, logEntryKey);
|
|
936
|
+
const decision = tryAdoptOwnSessionLogEntry({
|
|
937
|
+
self: entry,
|
|
938
|
+
existing
|
|
939
|
+
});
|
|
940
|
+
if (decision.adopt) {
|
|
941
|
+
committedEntry = decision.entry;
|
|
942
|
+
break;
|
|
943
|
+
}
|
|
944
|
+
if (++probes > 1e5) throw new BaerlyError("Internal", `${errorPrefix}: log-tail forward-probe exceeded ${LOG_FORWARD_PROBE_CAP} on ${this.#currentJsonKey}`);
|
|
945
|
+
seq = await findLogTail(this.#storage, logPrefix, seq + 1);
|
|
946
|
+
entry = mintEntry(seq);
|
|
947
|
+
}
|
|
948
|
+
const committedEntries = [committedEntry];
|
|
949
|
+
const staleKeysClassA = await this.#cleanupStaleIndexKeysBestEffort({
|
|
950
|
+
input,
|
|
951
|
+
logPrefix,
|
|
952
|
+
seq
|
|
953
|
+
});
|
|
954
|
+
const indexClassA = newKeysClassA + staleKeysClassA;
|
|
955
|
+
if (this.#indexes.length > 0 && indexClassA > 0) ctxMetrics().histogram("db.write.index_ops_per_logical_write", indexClassA, { collection: input.collection });
|
|
956
|
+
const prevSeq = preCommitTail;
|
|
957
|
+
const observedTail = seq + 1;
|
|
958
|
+
const maint = getCurrentContext()?.maintenance;
|
|
959
|
+
const gcInterval = maint?.options?.profile?.gcInterval ?? MAINTENANCE_PROFILE_CF_FREE.gcInterval;
|
|
960
|
+
if (maint?.disabled === true ? observedTail - current.tail_hint >= 128 : shouldFireMaintenance(current, prevSeq, gcInterval, observedTail)) await (maint?.dispatch ?? dispatchInlineAwaited)(() => runBoundedMaintenance({
|
|
961
|
+
storage: this.#storage,
|
|
962
|
+
currentJsonKey: this.#currentJsonKey,
|
|
963
|
+
prevSeq,
|
|
964
|
+
observedTail,
|
|
965
|
+
...maint?.disabled === true && { disabled: true },
|
|
966
|
+
...maint?.maxFoldBytes !== void 0 && { maxFoldBytes: maint.maxFoldBytes }
|
|
967
|
+
}, maint?.options).then(() => {}, () => {}));
|
|
968
|
+
return {
|
|
969
|
+
entries: committedEntries,
|
|
970
|
+
currentEtag: baseEtag,
|
|
971
|
+
classAOps: contentPutCount + 1 + indexClassA
|
|
972
|
+
};
|
|
973
|
+
}
|
|
974
|
+
/**
|
|
975
|
+
* Auto-create the per-collection `current.json` at
|
|
976
|
+
* `this.#currentJsonKey` with a zero-state initial manifest. Called
|
|
977
|
+
* by `#singleAttemptCommit` when the read returned `null` (fresh
|
|
978
|
+
* bucket / fresh collection).
|
|
979
|
+
*
|
|
980
|
+
* Concurrency: `createCurrentJson` uses `If-None-Match: "*"`. If a
|
|
981
|
+
* peer raced us and won, the storage layer surfaces `Conflict`; we
|
|
982
|
+
* recover by re-reading the now-present manifest. We do NOT retry
|
|
983
|
+
* the create — a single recover-via-read covers every race that
|
|
984
|
+
* could have produced our null read.
|
|
985
|
+
*
|
|
986
|
+
* The seed shape (`snapshot: null`, `tail_hint: 0`, `log_seq_start:
|
|
987
|
+
* 0`, `writer_fence: { epoch: 0, owner: "", claimed_at: "" }`)
|
|
988
|
+
* matches `ensureTable` and `baerly deploy`'s pre-warm path, so an
|
|
989
|
+
* operator who pre-provisions and a writer who auto-creates land
|
|
990
|
+
* on byte-identical bytes.
|
|
991
|
+
*
|
|
992
|
+
* @throws BaerlyError code="InvalidResponse" — the post-recover
|
|
993
|
+
* re-read also returned null. Defensive guard; in practice
|
|
994
|
+
* unreachable because the Conflict implies the key now exists.
|
|
995
|
+
*/
|
|
996
|
+
async #provisionCurrentJson() {
|
|
997
|
+
const initial = {
|
|
998
|
+
schema_version: 3,
|
|
999
|
+
snapshot: null,
|
|
1000
|
+
tail_hint: 0,
|
|
1001
|
+
log_seq_start: 0,
|
|
1002
|
+
writer_fence: {
|
|
1003
|
+
epoch: 0,
|
|
1004
|
+
owner: "",
|
|
1005
|
+
claimed_at: ""
|
|
1006
|
+
},
|
|
1007
|
+
snapshot_bytes: 0,
|
|
1008
|
+
snapshot_rows: 0
|
|
1009
|
+
};
|
|
1010
|
+
try {
|
|
1011
|
+
return await createCurrentJson(this.#storage, this.#currentJsonKey, initial);
|
|
1012
|
+
} catch (error) {
|
|
1013
|
+
if (!(error instanceof BaerlyError) || error.code !== "Conflict") throw error;
|
|
1014
|
+
}
|
|
1015
|
+
const recovered = await readCurrentJson(this.#storage, this.#currentJsonKey);
|
|
1016
|
+
if (recovered === null) throw new BaerlyError("InvalidResponse", `Writer: current.json missing at ${this.#currentJsonKey} after auto-create raced and recover read returned null`);
|
|
1017
|
+
return recovered;
|
|
1018
|
+
}
|
|
1019
|
+
async #cleanupStaleIndexKeysBestEffort(args) {
|
|
1020
|
+
if (this.#indexes.length === 0) return 0;
|
|
1021
|
+
const { input } = args;
|
|
1022
|
+
let staleKeys = [];
|
|
1023
|
+
try {
|
|
1024
|
+
if (input.op === "U") {
|
|
1025
|
+
const preImage = await this.#readPreImage(args.logPrefix, input.collection, input.docId, args.seq);
|
|
1026
|
+
const oldKeys = allIndexKeysFor(args.logPrefix, this.#indexes, preImage, input.docId);
|
|
1027
|
+
const newSet = new Set(allIndexKeysFor(args.logPrefix, this.#indexes, input.body, input.docId));
|
|
1028
|
+
staleKeys = oldKeys.filter((k) => !newSet.has(k));
|
|
1029
|
+
} else if (input.op === "D") {
|
|
1030
|
+
const preImage = await this.#readPreImage(args.logPrefix, input.collection, input.docId, args.seq);
|
|
1031
|
+
staleKeys = allIndexKeysFor(args.logPrefix, this.#indexes, preImage, input.docId);
|
|
1143
1032
|
}
|
|
1144
|
-
|
|
1033
|
+
} catch {
|
|
1034
|
+
ctxMetrics().counter("db.write.index_cleanup_errors_total", 1, {
|
|
1035
|
+
collection: input.collection,
|
|
1036
|
+
step: "pre-image-read"
|
|
1037
|
+
});
|
|
1038
|
+
return 0;
|
|
1145
1039
|
}
|
|
1040
|
+
const indexDeletes = [];
|
|
1041
|
+
for (const k of staleKeys) indexDeletes.push(this.#storage.delete(k).catch(() => {
|
|
1042
|
+
ctxMetrics().counter("db.write.index_cleanup_errors_total", 1, {
|
|
1043
|
+
collection: input.collection,
|
|
1044
|
+
step: "delete"
|
|
1045
|
+
});
|
|
1046
|
+
}));
|
|
1047
|
+
await Promise.all(indexDeletes);
|
|
1048
|
+
return staleKeys.length;
|
|
1146
1049
|
}
|
|
1147
|
-
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
1152
|
-
|
|
1153
|
-
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
|
|
1157
|
-
|
|
1158
|
-
|
|
1159
|
-
|
|
1160
|
-
|
|
1161
|
-
|
|
1162
|
-
|
|
1163
|
-
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
|
|
1050
|
+
/**
|
|
1051
|
+
* Read the pre-image content body for a doc by walking the live log
|
|
1052
|
+
* backwards from `currentNextSeq` looking for the most-recent I/U
|
|
1053
|
+
* entry on this `(collection, docId)`. Returns `undefined` when:
|
|
1054
|
+
*
|
|
1055
|
+
* - the doc's most-recent op was `D` (tombstone — no live body);
|
|
1056
|
+
* - no entry for this doc lives inside the visible log range
|
|
1057
|
+
* `[log_seq_start, currentNextSeq)` (a fresh-insert race or the
|
|
1058
|
+
* doc has been folded into the snapshot but is no longer
|
|
1059
|
+
* referenced).
|
|
1060
|
+
*
|
|
1061
|
+
* Used ONLY by the index-emission path's stale-key half (Step 5b, on
|
|
1062
|
+
* `U` / `D`) to compute which OLD-value keys to DELETE. Bounded by
|
|
1063
|
+
* `log_seq_start`: entries below have been folded into the snapshot
|
|
1064
|
+
* and may already be swept off the bucket — a snapshot fold is the
|
|
1065
|
+
* rebuild command's job (see `./rebuild-index.ts`), not the writer's.
|
|
1066
|
+
*
|
|
1067
|
+
* **Cost note:** linear walk, O(snapshot lag). For helpdesk-shape
|
|
1068
|
+
* collections (100s of docs, <10k log entries) this is fine — the
|
|
1069
|
+
* compactor folds the live tail every ~100 entries
|
|
1070
|
+
* (`packages/server/src/compactor.ts`). A follow-up ticket caches
|
|
1071
|
+
* per-doc index head in `current.json` for O(1) lookup.
|
|
1072
|
+
*/
|
|
1073
|
+
async #readPreImage(logPrefix, collection, docId, currentNextSeq) {
|
|
1074
|
+
for (let s = currentNextSeq - 1; s >= 0; s--) {
|
|
1075
|
+
const logKey = logObjectKey(logPrefix, s);
|
|
1076
|
+
const got = await this.#storage.get(logKey);
|
|
1077
|
+
if (got === null) continue;
|
|
1078
|
+
let entry;
|
|
1079
|
+
try {
|
|
1080
|
+
entry = decodeJsonBytes(got.body);
|
|
1081
|
+
} catch {
|
|
1168
1082
|
continue;
|
|
1169
1083
|
}
|
|
1170
|
-
|
|
1171
|
-
if (
|
|
1172
|
-
|
|
1173
|
-
field,
|
|
1174
|
-
info: range
|
|
1175
|
-
};
|
|
1176
|
-
else {
|
|
1177
|
-
const inVals = inOps.get(field);
|
|
1178
|
-
if (inVals !== void 0) tail = {
|
|
1179
|
-
kind: "in",
|
|
1180
|
-
field,
|
|
1181
|
-
values: inVals
|
|
1182
|
-
};
|
|
1183
|
-
}
|
|
1184
|
-
break;
|
|
1084
|
+
if (entry.collection !== collection || entry.doc_id !== docId) continue;
|
|
1085
|
+
if (entry.op === "D") return;
|
|
1086
|
+
if ((entry.op === "I" || entry.op === "U") && entry.after !== void 0) return entry.after;
|
|
1185
1087
|
}
|
|
1186
|
-
const candidateLen = equalityKeys.length + (tail !== void 0 ? 1 : 0);
|
|
1187
|
-
if (candidateLen === 0) continue;
|
|
1188
|
-
candidates.push({
|
|
1189
|
-
def,
|
|
1190
|
-
defIndex,
|
|
1191
|
-
prefixLen: candidateLen,
|
|
1192
|
-
equalityKeys,
|
|
1193
|
-
...tail !== void 0 ? { tail } : {}
|
|
1194
|
-
});
|
|
1195
1088
|
}
|
|
1196
|
-
|
|
1197
|
-
|
|
1198
|
-
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
|
|
1202
|
-
|
|
1203
|
-
|
|
1204
|
-
|
|
1205
|
-
|
|
1206
|
-
|
|
1207
|
-
|
|
1208
|
-
|
|
1209
|
-
|
|
1210
|
-
|
|
1211
|
-
|
|
1212
|
-
|
|
1213
|
-
|
|
1214
|
-
|
|
1215
|
-
|
|
1216
|
-
|
|
1089
|
+
/**
|
|
1090
|
+
* Walk `log/<logSeqStart>.json` … `log/<nextSeq - 1>.json` with
|
|
1091
|
+
* bounded parallelism via `walkLogRange`. Materialised entries are
|
|
1092
|
+
* discarded — the walk's only job is to surface a hole or a
|
|
1093
|
+
* malformed body inside the visible range as
|
|
1094
|
+
* `BaerlyError{code:"Internal"}` / `"InvalidResponse"`.
|
|
1095
|
+
*
|
|
1096
|
+
* Gated on `verifyLogIntegrityOnCommit`; default off in production
|
|
1097
|
+
* because the per-doc fold already lives in the read path. See the
|
|
1098
|
+
* option's docstring for the rationale and the opt-in convention.
|
|
1099
|
+
*
|
|
1100
|
+
* `logSeqStart` is the boundary set by the compactor on
|
|
1101
|
+
* `current.json.log_seq_start`. Entries below it have been folded
|
|
1102
|
+
* into the snapshot and may have been swept off the bucket, so the
|
|
1103
|
+
* walk MUST NOT GET-require them.
|
|
1104
|
+
*/
|
|
1105
|
+
async #walkLog(logPrefix, logSeqStart, nextSeq) {
|
|
1106
|
+
await walkLogRange(this.#storage, logPrefix, logSeqStart, nextSeq);
|
|
1107
|
+
}
|
|
1108
|
+
/**
|
|
1109
|
+
* Bump the `db.r2.put.429_total` counter when `err` looks like an
|
|
1110
|
+
* R2 prefix-partition rate-limit. Best-effort: detected via
|
|
1111
|
+
* `BaerlyError{code:"NetworkError"}` with a `429` token in the
|
|
1112
|
+
* message. Called from every PUT call site's catch arm; mutually
|
|
1113
|
+
* exclusive in practice with `isPreconditionFailed` (412 ≠ 429).
|
|
1114
|
+
*/
|
|
1115
|
+
#observe429(err, collection) {
|
|
1116
|
+
if (is429(err)) ctxMetrics().counter("db.r2.put.429_total", 1, { collection });
|
|
1117
|
+
}
|
|
1118
|
+
/**
|
|
1119
|
+
* Emit the per-logical-write `class_a_ops_per_logical_write`
|
|
1120
|
+
* histogram for `commit`. `classAOps` is the per-attempt base plus
|
|
1121
|
+
* a charge for prior failed attempts (the retry-budget cost model),
|
|
1122
|
+
* computed by the caller.
|
|
1123
|
+
*/
|
|
1124
|
+
#emitWriteMetrics(collection, classAOps) {
|
|
1125
|
+
ctxMetrics().histogram("db.write.class_a_ops_per_logical_write", classAOps, { collection });
|
|
1126
|
+
}
|
|
1127
|
+
/**
|
|
1128
|
+
* Exponential backoff with full jitter. `25 * 2^(attempt-1)` capped
|
|
1129
|
+
* at 1500ms; uniform jitter in `[0, base)` keeps colliding peers
|
|
1130
|
+
* from re-racing in lockstep. Worst-case total wait across the
|
|
1131
|
+
* default 8 attempts is roughly 2.5 s — well under a typical
|
|
1132
|
+
* Worker request budget.
|
|
1133
|
+
*/
|
|
1134
|
+
async #backoff(attempt) {
|
|
1135
|
+
const sleepMs = Math.min(this.#initialBackoffMs * 2 ** (attempt - 1), MAX_BACKOFF_MS) * this.#random();
|
|
1136
|
+
if (sleepMs <= 0) return;
|
|
1137
|
+
await new Promise((r) => setTimeout(r, sleepMs));
|
|
1217
1138
|
}
|
|
1218
|
-
return {
|
|
1219
|
-
kind: "index-walk",
|
|
1220
|
-
indexName: best.def.name,
|
|
1221
|
-
equalityKeys: best.equalityKeys,
|
|
1222
|
-
...best.tail !== void 0 && best.tail.kind === "range" ? { rangeOn: {
|
|
1223
|
-
field: best.tail.field,
|
|
1224
|
-
...best.tail.info.lo !== void 0 ? { lo: best.tail.info.lo } : {},
|
|
1225
|
-
...best.tail.info.hi !== void 0 ? { hi: best.tail.info.hi } : {},
|
|
1226
|
-
loInclusive: best.tail.info.loInclusive,
|
|
1227
|
-
hiInclusive: best.tail.info.hiInclusive
|
|
1228
|
-
} } : {},
|
|
1229
|
-
...best.tail !== void 0 && best.tail.kind === "in" ? { inOn: {
|
|
1230
|
-
field: best.tail.field,
|
|
1231
|
-
values: best.tail.values
|
|
1232
|
-
} } : {}
|
|
1233
|
-
};
|
|
1234
1139
|
};
|
|
1235
|
-
//#endregion
|
|
1236
|
-
//#region packages/server/src/schema.ts
|
|
1237
1140
|
/**
|
|
1238
|
-
*
|
|
1239
|
-
*
|
|
1240
|
-
*
|
|
1241
|
-
* The `SchemaValidator` / `SchemaIssue` TYPES live in
|
|
1242
|
-
* `@baerly/protocol` (cross-platform). This module owns the runtime
|
|
1243
|
-
* helper `validateOrThrow` that runs a validator and raises a
|
|
1244
|
-
* `BaerlyError{code:"SchemaError"}` on failure.
|
|
1245
|
-
*
|
|
1246
|
-
* @example
|
|
1247
|
-
* ```ts
|
|
1248
|
-
* import { z } from "zod";
|
|
1249
|
-
* import { defineConfig } from "@gusto/baerly-storage/config";
|
|
1250
|
-
*
|
|
1251
|
-
* const Ticket = z.object({
|
|
1252
|
-
* _id: z.string(),
|
|
1253
|
-
* status: z.enum(["open", "closed"]),
|
|
1254
|
-
* title: z.string().min(1),
|
|
1255
|
-
* });
|
|
1256
|
-
*
|
|
1257
|
-
* export default defineConfig({
|
|
1258
|
-
* collections: {
|
|
1259
|
-
* tickets: { schema: Ticket },
|
|
1260
|
-
* },
|
|
1261
|
-
* });
|
|
1262
|
-
* ```
|
|
1141
|
+
* `true` when the underlying storage surfaced a `PreconditionFailed`
|
|
1142
|
+
* 412 (or its non-S3 equivalents). Every in-tree {@link Storage} impl
|
|
1143
|
+
* surfaces a lost CAS as `BaerlyError{code:"Conflict"}`.
|
|
1263
1144
|
*/
|
|
1145
|
+
const isPreconditionFailed = (err) => err instanceof BaerlyError && err.code === "Conflict";
|
|
1264
1146
|
/**
|
|
1265
|
-
*
|
|
1266
|
-
*
|
|
1267
|
-
*
|
|
1268
|
-
*
|
|
1269
|
-
* Field paths are normalised to `(string | number)[]` so the wire shape
|
|
1270
|
-
* is JSON-clean. Symbol keys (rare; StandardSchemaV1 permits them) are
|
|
1271
|
-
* coerced to `String(sym)` — we never emit `symbol` on the wire.
|
|
1272
|
-
*
|
|
1273
|
-
* The thrown error's `message` carries a one-line summary
|
|
1274
|
-
* (`"<collection>.<verb>: <issuesCount> field(s) failed validation: <first>"`)
|
|
1275
|
-
* for stderr-readable logs; the structured `issues` are on `.issues`.
|
|
1147
|
+
* `true` when a log-create PUT failed transiently (a `NetworkError`) —
|
|
1148
|
+
* the write may or may not have landed (a dropped ack). Safe to retry
|
|
1149
|
+
* the SAME seq: own-session adoption closes the double-commit window if
|
|
1150
|
+
* it did land. NOT a 412 (that's handled by adoption directly).
|
|
1276
1151
|
*/
|
|
1277
|
-
const
|
|
1278
|
-
|
|
1279
|
-
|
|
1280
|
-
|
|
1281
|
-
|
|
1282
|
-
|
|
1283
|
-
|
|
1284
|
-
|
|
1285
|
-
|
|
1286
|
-
|
|
1287
|
-
const first = issues[0];
|
|
1288
|
-
const summary = first === void 0 ? "schema validation failed (no issues reported)" : `${first.path.length === 0 ? "<root>" : first.path.join(".")}: ${first.message}`;
|
|
1289
|
-
throw new BaerlyError("SchemaError", `${context.collection}.${context.verb}: ${issues.length} field${issues.length === 1 ? "" : "s"} failed validation: ${summary}`, void 0, issues);
|
|
1152
|
+
const isTransientWrite = (err) => err instanceof BaerlyError && err.code === "NetworkError";
|
|
1153
|
+
/**
|
|
1154
|
+
* `true` when the underlying storage surfaced an R2 prefix-partition
|
|
1155
|
+
* rate-limit. {@link S3HttpStorage} stamps the upstream HTTP status
|
|
1156
|
+
* onto `BaerlyError.cause` as `{ status }`; we discriminate on that
|
|
1157
|
+
* structured field rather than regex-matching the message.
|
|
1158
|
+
*/
|
|
1159
|
+
const is429 = (err) => {
|
|
1160
|
+
if (!(err instanceof BaerlyError) || err.code !== "NetworkError") return false;
|
|
1161
|
+
return err.cause?.status === 429;
|
|
1290
1162
|
};
|
|
1291
1163
|
//#endregion
|
|
1292
1164
|
//#region packages/server/src/query.ts
|
|
@@ -1294,8 +1166,8 @@ const validateOrThrow = async (schema, candidate, context) => {
|
|
|
1294
1166
|
* Read engine + mutation terminals: `Query<T>` builder, the
|
|
1295
1167
|
* three read terminals (`first`, `all`, `count`) that fold the log
|
|
1296
1168
|
* under a fresh `current.json` snapshot, and the four mutation
|
|
1297
|
-
* terminals (`insert`, `update`, `replace`, `delete`)
|
|
1298
|
-
*
|
|
1169
|
+
* terminals (`insert`, `update`, `replace`, `delete`). Each mutation
|
|
1170
|
+
* verb compiles to exactly one `Writer.commit()` call.
|
|
1299
1171
|
*
|
|
1300
1172
|
* Every modifier (`.where` / `.order` / `.limit`) returns a NEW
|
|
1301
1173
|
* `Query<T>` carrying merged frozen state — the input state is never
|
|
@@ -1306,28 +1178,44 @@ const validateOrThrow = async (schema, candidate, context) => {
|
|
|
1306
1178
|
* AND on the normalised wire form).
|
|
1307
1179
|
* `.order()` and `.limit()` are last-call-wins (state replace).
|
|
1308
1180
|
*
|
|
1309
|
-
* Each terminal reads `current.json` FRESH
|
|
1310
|
-
* directly — no cache, no
|
|
1311
|
-
*
|
|
1181
|
+
* Each terminal reads `current.json` FRESH, loads the snapshot it names,
|
|
1182
|
+
* and walks `[log_seq_start, tail_hint)` directly — no cache, no
|
|
1183
|
+
* `list()` round-trip for the log. Per the multi-instance rules, every
|
|
1184
|
+
* read sees a fresh CAS snapshot.
|
|
1312
1185
|
*
|
|
1313
1186
|
* Mutation terminals are SINGLE-ATTEMPT per call site. CAS contention
|
|
1314
1187
|
* retries (up to 8 attempts) live inside `Writer.commit()`; the
|
|
1315
1188
|
* verbs do NOT add their own retry loop. On retry-budget exhaustion
|
|
1316
1189
|
* `commit()` throws `BaerlyError{code:"Conflict"}` and the verb
|
|
1317
|
-
* surfaces it unchanged — the caller
|
|
1318
|
-
* `db.transaction(...)`.
|
|
1190
|
+
* surfaces it unchanged — the caller decides whether to re-run.
|
|
1319
1191
|
*
|
|
1320
1192
|
* @see ../../../docs/spec/sync-protocol.md
|
|
1321
1193
|
*/
|
|
1194
|
+
const DUPLICATE_ID_RESOLUTION = "Use different `_id` or omit it.";
|
|
1322
1195
|
/**
|
|
1323
|
-
* Serialise a {@link CurrentJson} head into
|
|
1324
|
-
* `
|
|
1325
|
-
*
|
|
1326
|
-
*
|
|
1196
|
+
* Serialise a {@link CurrentJson} head into an opaque wire cursor.
|
|
1197
|
+
* `tail` is the DISCOVERED tail (defaults to `json.tail_hint` when no
|
|
1198
|
+
* probe has run). Physical snapshot keys feed the digest but never
|
|
1199
|
+
* cross the HTTP boundary.
|
|
1327
1200
|
*
|
|
1328
1201
|
* @internal — exported for `query.test.ts`.
|
|
1329
1202
|
*/
|
|
1330
|
-
const
|
|
1203
|
+
const manifestPointerDigest = (seed) => {
|
|
1204
|
+
let hash = 14695981039346656037n;
|
|
1205
|
+
for (let i = 0; i < seed.length; i++) {
|
|
1206
|
+
hash ^= BigInt(seed.charCodeAt(i));
|
|
1207
|
+
hash = hash * 1099511628211n & 18446744073709551615n;
|
|
1208
|
+
}
|
|
1209
|
+
return hash.toString(36).padStart(13, "0");
|
|
1210
|
+
};
|
|
1211
|
+
const serializeManifestPointer = (json, tail = json.tail_hint) => `m1:${manifestPointerDigest([
|
|
1212
|
+
json.snapshot ?? "none",
|
|
1213
|
+
json.log_seq_start,
|
|
1214
|
+
json.tail_hint,
|
|
1215
|
+
json.snapshot_bytes,
|
|
1216
|
+
json.snapshot_rows,
|
|
1217
|
+
tail
|
|
1218
|
+
].join("|"))}`;
|
|
1331
1219
|
/**
|
|
1332
1220
|
* Returns the id iff `wire` carries exactly one clause and that
|
|
1333
1221
|
* clause is `{op:"eq", field:"_id", value:<string>}` — the shape
|
|
@@ -1493,6 +1381,7 @@ const writerFor = (ctx) => new Writer({
|
|
|
1493
1381
|
const runInsert = async (ctx, doc) => {
|
|
1494
1382
|
const supplied = doc["_id"];
|
|
1495
1383
|
const _id = typeof supplied === "string" && supplied.length > 0 ? supplied : uuidv7();
|
|
1384
|
+
assertDocId(_id);
|
|
1496
1385
|
const body = {
|
|
1497
1386
|
...doc,
|
|
1498
1387
|
_id
|
|
@@ -1509,16 +1398,7 @@ const runInsert = async (ctx, doc) => {
|
|
|
1509
1398
|
}] },
|
|
1510
1399
|
order: void 0,
|
|
1511
1400
|
limit: 1
|
|
1512
|
-
})).rows.length > 0) throw new BaerlyError("Conflict", `Query.insert: _id ${JSON.stringify(_id)} already exists in collection ${JSON.stringify(ctx.collectionName)}
|
|
1513
|
-
if (ctx.txCtx !== void 0) {
|
|
1514
|
-
assertTxBindMatches(ctx);
|
|
1515
|
-
ctx.txCtx.mutations.push({
|
|
1516
|
-
op: "I",
|
|
1517
|
-
docId: _id,
|
|
1518
|
-
body
|
|
1519
|
-
});
|
|
1520
|
-
return { _id };
|
|
1521
|
-
}
|
|
1401
|
+
})).rows.length > 0) throw new BaerlyError("Conflict", `Query.insert: _id ${JSON.stringify(_id)} already exists in collection ${JSON.stringify(ctx.collectionName)}`, void 0, void 0, void 0, DUPLICATE_ID_RESOLUTION, false);
|
|
1522
1402
|
await writerFor(ctx).commit({
|
|
1523
1403
|
op: "I",
|
|
1524
1404
|
collection: ctx.collectionName,
|
|
@@ -1535,8 +1415,8 @@ const runInsert = async (ctx, doc) => {
|
|
|
1535
1415
|
*
|
|
1536
1416
|
* Atomicity is per row, not across the N-row batch. The locked
|
|
1537
1417
|
* contract (`packages/protocol/src/collection-api.ts:178–184`) is explicit on
|
|
1538
|
-
* this:
|
|
1539
|
-
*
|
|
1418
|
+
* this: each affected row commits independently — the document is the
|
|
1419
|
+
* atomic unit; there is no multi-row batch.
|
|
1540
1420
|
*
|
|
1541
1421
|
* `replica_identity` defaults to `PATCH_ONLY` for every collection
|
|
1542
1422
|
* today — emitted `U` entries carry `{ after }` (the full post-image)
|
|
@@ -1553,8 +1433,6 @@ const runInsert = async (ctx, doc) => {
|
|
|
1553
1433
|
*/
|
|
1554
1434
|
const runUpdate = async (ctx, state, patch) => {
|
|
1555
1435
|
const { rows } = await runRead(ctx, state);
|
|
1556
|
-
const tx = ctx.txCtx;
|
|
1557
|
-
if (tx !== void 0) assertTxBindMatches(ctx);
|
|
1558
1436
|
let modified = 0;
|
|
1559
1437
|
for (const doc of rows) {
|
|
1560
1438
|
const merged = merge(doc, patch);
|
|
@@ -1563,12 +1441,7 @@ const runUpdate = async (ctx, state, patch) => {
|
|
|
1563
1441
|
collection: ctx.collectionName,
|
|
1564
1442
|
verb: "update"
|
|
1565
1443
|
});
|
|
1566
|
-
|
|
1567
|
-
op: "U",
|
|
1568
|
-
docId: String(doc["_id"]),
|
|
1569
|
-
body: merged
|
|
1570
|
-
});
|
|
1571
|
-
else await writerFor(ctx).commit({
|
|
1444
|
+
await writerFor(ctx).commit({
|
|
1572
1445
|
op: "U",
|
|
1573
1446
|
collection: ctx.collectionName,
|
|
1574
1447
|
docId: String(doc["_id"]),
|
|
@@ -1581,8 +1454,7 @@ const runUpdate = async (ctx, state, patch) => {
|
|
|
1581
1454
|
/**
|
|
1582
1455
|
* `Collection.replace` implementation. Existence check via `runRead` over
|
|
1583
1456
|
* a `byId`-shaped wire so the `singleIdFromPredicate` PK fast path
|
|
1584
|
-
* (`Map.get`) fires
|
|
1585
|
-
* visible. Missing row → `NotFound` directly (no Conflict-string
|
|
1457
|
+
* (`Map.get`) fires. Missing row → `NotFound` directly (no Conflict-string
|
|
1586
1458
|
* indirection through the router). Present row → emit a single
|
|
1587
1459
|
* `op:"U"` `LogEntry` carrying `doc` as the post-image, with `_id`
|
|
1588
1460
|
* forced to the requested `id` so doc identity is preserved across
|
|
@@ -1595,6 +1467,7 @@ const runUpdate = async (ctx, state, patch) => {
|
|
|
1595
1467
|
* exhausted.
|
|
1596
1468
|
*/
|
|
1597
1469
|
const runReplaceById = async (ctx, id, doc) => {
|
|
1470
|
+
assertDocId(id);
|
|
1598
1471
|
const { rows } = await runRead(ctx, {
|
|
1599
1472
|
wire: { clauses: [{
|
|
1600
1473
|
op: "eq",
|
|
@@ -1613,15 +1486,6 @@ const runReplaceById = async (ctx, id, doc) => {
|
|
|
1613
1486
|
collection: ctx.collectionName,
|
|
1614
1487
|
verb: "replace"
|
|
1615
1488
|
});
|
|
1616
|
-
if (ctx.txCtx !== void 0) {
|
|
1617
|
-
assertTxBindMatches(ctx);
|
|
1618
|
-
ctx.txCtx.mutations.push({
|
|
1619
|
-
op: "U",
|
|
1620
|
-
docId: id,
|
|
1621
|
-
body
|
|
1622
|
-
});
|
|
1623
|
-
return;
|
|
1624
|
-
}
|
|
1625
1489
|
await writerFor(ctx).commit({
|
|
1626
1490
|
op: "U",
|
|
1627
1491
|
collection: ctx.collectionName,
|
|
@@ -1638,8 +1502,8 @@ const runReplaceById = async (ctx, id, doc) => {
|
|
|
1638
1502
|
* maintain a shadow table — see `packages/protocol/src/log.ts:102–118`.
|
|
1639
1503
|
*
|
|
1640
1504
|
* Atomicity is per row, not across the N-row batch — same shape as
|
|
1641
|
-
* `Query.update`.
|
|
1642
|
-
*
|
|
1505
|
+
* `Query.update`. The document is the atomic unit; there is no
|
|
1506
|
+
* multi-row batch.
|
|
1643
1507
|
*
|
|
1644
1508
|
* @throws BaerlyError code="Conflict" — any one row's CAS retry budget
|
|
1645
1509
|
* exhausted. The partial-progress `deleted` count is NOT returned
|
|
@@ -1647,15 +1511,9 @@ const runReplaceById = async (ctx, id, doc) => {
|
|
|
1647
1511
|
*/
|
|
1648
1512
|
const runDelete = async (ctx, state) => {
|
|
1649
1513
|
const { rows } = await runRead(ctx, state);
|
|
1650
|
-
const tx = ctx.txCtx;
|
|
1651
|
-
if (tx !== void 0) assertTxBindMatches(ctx);
|
|
1652
1514
|
let deleted = 0;
|
|
1653
1515
|
for (const doc of rows) {
|
|
1654
|
-
|
|
1655
|
-
op: "D",
|
|
1656
|
-
docId: String(doc["_id"])
|
|
1657
|
-
});
|
|
1658
|
-
else await writerFor(ctx).commit({
|
|
1516
|
+
await writerFor(ctx).commit({
|
|
1659
1517
|
op: "D",
|
|
1660
1518
|
collection: ctx.collectionName,
|
|
1661
1519
|
docId: String(doc["_id"])
|
|
@@ -1665,55 +1523,46 @@ const runDelete = async (ctx, state) => {
|
|
|
1665
1523
|
return { deleted };
|
|
1666
1524
|
};
|
|
1667
1525
|
/**
|
|
1668
|
-
*
|
|
1669
|
-
* already prevents the legitimate path (the body callback gets one
|
|
1670
|
-
* `Collection<T>`, no `Db`), so this only catches a bug where a stale
|
|
1671
|
-
* `Query<T>` outlives its `Collection<T>` and is somehow re-attached to a
|
|
1672
|
-
* transaction over a different collection.
|
|
1673
|
-
*
|
|
1674
|
-
* @throws BaerlyError code="Internal" — txCtx ↔ Collection name mismatch.
|
|
1675
|
-
*/
|
|
1676
|
-
const assertTxBindMatches = (ctx) => {
|
|
1677
|
-
if (ctx.txCtx === void 0) return;
|
|
1678
|
-
if (ctx.txCtx.collection !== ctx.collectionName) throw new BaerlyError("Internal", `Transaction context bound to ${JSON.stringify(ctx.txCtx.collection)} but mutation issued on collection ${JSON.stringify(ctx.collectionName)}`);
|
|
1679
|
-
};
|
|
1680
|
-
/**
|
|
1681
|
-
* Load `current.json` fresh, walk `[0, next_seq)` in parallel, fold
|
|
1526
|
+
* Load `current.json` fresh, walk `[log_seq_start, tail_hint)` in parallel, fold
|
|
1682
1527
|
* per-`doc_id`, then apply predicate / order / limit in memory.
|
|
1683
1528
|
*
|
|
1684
1529
|
* Error mapping:
|
|
1685
1530
|
* - `current.json` missing → empty result (collection not provisioned).
|
|
1686
1531
|
* - `current.json` malformed → `InvalidResponse` (from `readCurrentJson`).
|
|
1687
|
-
* - log entry missing in `[
|
|
1532
|
+
* - log entry missing in `[log_seq_start, tail_hint)` → `Internal`.
|
|
1688
1533
|
* - log entry malformed → `InvalidResponse`.
|
|
1689
1534
|
*/
|
|
1690
1535
|
const runRead = async (ctx, state) => {
|
|
1691
1536
|
const currentJsonKey = `${ctx.collectionPrefix}/current.json`;
|
|
1692
1537
|
const head = await readCurrentJson(ctx.storage, currentJsonKey);
|
|
1693
|
-
const manifestPointer = head === null ? `${MANIFEST_POINTER_EMPTY_SNAPSHOT}@0` : serializeManifestPointer(head.json);
|
|
1694
1538
|
const fresh = true;
|
|
1695
1539
|
if (head === null) return {
|
|
1696
1540
|
rows: [],
|
|
1697
|
-
manifestPointer,
|
|
1541
|
+
manifestPointer: "m1:0000000000000",
|
|
1698
1542
|
fresh
|
|
1699
1543
|
};
|
|
1700
1544
|
const plan = planQuery(state.wire, ctx.indexes);
|
|
1701
1545
|
if (plan.kind === "index-walk") {
|
|
1702
|
-
|
|
1546
|
+
const walk = await runIndexWalkPlan(ctx, head.json, state, plan);
|
|
1547
|
+
let rows = walk.rows;
|
|
1703
1548
|
if (state.order !== void 0) rows = sortByOrderSpec(rows, state.order);
|
|
1704
1549
|
if (state.limit !== void 0 && state.limit < rows.length) rows = rows.slice(0, state.limit);
|
|
1705
1550
|
return {
|
|
1706
1551
|
rows,
|
|
1707
|
-
manifestPointer,
|
|
1552
|
+
manifestPointer: serializeManifestPointer(head.json, walk.tail),
|
|
1708
1553
|
fresh
|
|
1709
1554
|
};
|
|
1710
1555
|
}
|
|
1711
|
-
const
|
|
1556
|
+
const hint = head.json.tail_hint;
|
|
1712
1557
|
const logSeqStart = logSeqStartOf(head.json);
|
|
1713
1558
|
const baseDocs = head.json.snapshot === null ? /* @__PURE__ */ new Map() : await loadSnapshotAsMap(ctx.storage, head.json.snapshot, ctx.collectionName);
|
|
1714
|
-
const
|
|
1559
|
+
const probeFrom = Math.max(logSeqStart, hint);
|
|
1560
|
+
const entries = await walkLogRange(ctx.storage, ctx.collectionPrefix, logSeqStart, hint);
|
|
1561
|
+
const probe = await probeTailFrom(ctx.storage, ctx.collectionPrefix, probeFrom);
|
|
1562
|
+
const tail = probe.tail;
|
|
1715
1563
|
const docs = new Map(baseDocs);
|
|
1716
1564
|
foldLogEntriesOnto(docs, entries, { collection: ctx.collectionName });
|
|
1565
|
+
foldLogEntriesOnto(docs, probe.entries, { collection: ctx.collectionName });
|
|
1717
1566
|
const fastId = singleIdFromPredicate(state.wire);
|
|
1718
1567
|
let rows;
|
|
1719
1568
|
if (fastId !== void 0) {
|
|
@@ -1730,7 +1579,7 @@ const runRead = async (ctx, state) => {
|
|
|
1730
1579
|
if (state.limit !== void 0 && state.limit < rows.length) rows = rows.slice(0, state.limit);
|
|
1731
1580
|
return {
|
|
1732
1581
|
rows,
|
|
1733
|
-
manifestPointer,
|
|
1582
|
+
manifestPointer: serializeManifestPointer(head.json, tail),
|
|
1734
1583
|
fresh
|
|
1735
1584
|
};
|
|
1736
1585
|
};
|
|
@@ -1859,8 +1708,15 @@ const runIndexWalkPlan = async (ctx, head, state, plan) => {
|
|
|
1859
1708
|
if (docId.length === 0) continue;
|
|
1860
1709
|
docIdSet.add(docId);
|
|
1861
1710
|
}
|
|
1711
|
+
const logSeqStart = logSeqStartOf(head);
|
|
1712
|
+
const hint = head.tail_hint;
|
|
1713
|
+
const probe = await probeTailFrom(ctx.storage, ctx.collectionPrefix, Math.max(logSeqStart, hint));
|
|
1714
|
+
const tail = probe.tail;
|
|
1862
1715
|
const docIds = Array.from(docIdSet);
|
|
1863
|
-
if (docIds.length === 0) return
|
|
1716
|
+
if (docIds.length === 0) return {
|
|
1717
|
+
rows: [],
|
|
1718
|
+
tail
|
|
1719
|
+
};
|
|
1864
1720
|
const matched = new Set(docIds);
|
|
1865
1721
|
const baseDocs = head.snapshot === null ? /* @__PURE__ */ new Map() : await loadSnapshotAsMap(ctx.storage, head.snapshot, ctx.collectionName);
|
|
1866
1722
|
const docs = /* @__PURE__ */ new Map();
|
|
@@ -1868,16 +1724,21 @@ const runIndexWalkPlan = async (ctx, head, state, plan) => {
|
|
|
1868
1724
|
const seeded = baseDocs.get(id);
|
|
1869
1725
|
if (seeded !== void 0) docs.set(id, seeded);
|
|
1870
1726
|
}
|
|
1871
|
-
|
|
1872
|
-
|
|
1873
|
-
|
|
1727
|
+
foldLogEntriesOnto(docs, await walkLogRange(ctx.storage, ctx.collectionPrefix, logSeqStart, hint), {
|
|
1728
|
+
collection: ctx.collectionName,
|
|
1729
|
+
docIdFilter: matched
|
|
1730
|
+
});
|
|
1731
|
+
foldLogEntriesOnto(docs, probe.entries, {
|
|
1874
1732
|
collection: ctx.collectionName,
|
|
1875
1733
|
docIdFilter: matched
|
|
1876
1734
|
});
|
|
1877
1735
|
const rows = [];
|
|
1878
1736
|
const wire = state.wire;
|
|
1879
1737
|
for (const doc of docs.values()) if (wire === void 0 || matchesWire(wire, doc)) rows.push(doc);
|
|
1880
|
-
return
|
|
1738
|
+
return {
|
|
1739
|
+
rows,
|
|
1740
|
+
tail
|
|
1741
|
+
};
|
|
1881
1742
|
};
|
|
1882
1743
|
/**
|
|
1883
1744
|
* Stable multi-key sort built from an `OrderSpec`. Keys are taken in
|
|
@@ -1907,6 +1768,6 @@ const sortByOrderSpec = (rows, spec) => {
|
|
|
1907
1768
|
});
|
|
1908
1769
|
};
|
|
1909
1770
|
//#endregion
|
|
1910
|
-
export { runReplaceById as a,
|
|
1771
|
+
export { runReplaceById as a, runInsert as i, runAllWithMeta as n, validateOrThrow as o, runByIdWithMeta as r, assertPathSegment as s, makeQuery as t };
|
|
1911
1772
|
|
|
1912
|
-
//# sourceMappingURL=query-
|
|
1773
|
+
//# sourceMappingURL=query-rAtXNQQB.js.map
|