@gusto/baerly-storage 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +97 -0
- package/dist/API.md +850 -0
- package/dist/app-config-Cb5dO2s9.d.ts +480 -0
- package/dist/app-config.d.ts +2 -0
- package/dist/app-config.js +8 -0
- package/dist/app-config.js.map +1 -0
- package/dist/auth.d.ts +237 -0
- package/dist/auth.js +1335 -0
- package/dist/auth.js.map +1 -0
- package/dist/baerly.js +761 -0
- package/dist/baerly.js.map +1 -0
- package/dist/bucket-uri-BrDEYvzy.js +4922 -0
- package/dist/bucket-uri-BrDEYvzy.js.map +1 -0
- package/dist/chunk-EAsCxrDo.js +14 -0
- package/dist/client-BLf3Ae5s.d.ts +233 -0
- package/dist/client-react.d.ts +131 -0
- package/dist/client-react.js +559 -0
- package/dist/client-react.js.map +1 -0
- package/dist/client.d.ts +4 -0
- package/dist/client.js +160 -0
- package/dist/client.js.map +1 -0
- package/dist/cloudflare-CINJPKCW.js +911 -0
- package/dist/cloudflare-CINJPKCW.js.map +1 -0
- package/dist/cloudflare.d.ts +211 -0
- package/dist/cloudflare.js +445 -0
- package/dist/cloudflare.js.map +1 -0
- package/dist/config-Bsg8wgwo.js +198 -0
- package/dist/config-Bsg8wgwo.js.map +1 -0
- package/dist/context-Oj7ffwD-.js +187 -0
- package/dist/context-Oj7ffwD-.js.map +1 -0
- package/dist/cost-B1WiZxlf.js +203 -0
- package/dist/cost-B1WiZxlf.js.map +1 -0
- package/dist/current-json-BkatBzF7.js +252 -0
- package/dist/current-json-BkatBzF7.js.map +1 -0
- package/dist/db-D62JguBc.d.ts +336 -0
- package/dist/deploy-BB-wqbhf.js +83 -0
- package/dist/deploy-BB-wqbhf.js.map +1 -0
- package/dist/dev-banner-CWHIk8tH.d.ts +26 -0
- package/dist/dev-vite.d.ts +146 -0
- package/dist/dev-vite.js +223 -0
- package/dist/dev-vite.js.map +1 -0
- package/dist/dev.d.ts +3 -0
- package/dist/dev.js +2 -0
- package/dist/doctor-B8h9GCN9.js +331 -0
- package/dist/doctor-B8h9GCN9.js.map +1 -0
- package/dist/dump-BHo_sIMZ.js +116 -0
- package/dist/dump-BHo_sIMZ.js.map +1 -0
- package/dist/errors-DOdL95kK.js +58 -0
- package/dist/errors-DOdL95kK.js.map +1 -0
- package/dist/export-Dz2PZKSR.js +423 -0
- package/dist/export-Dz2PZKSR.js.map +1 -0
- package/dist/fsck-DEz9lyCy.js +293 -0
- package/dist/fsck-DEz9lyCy.js.map +1 -0
- package/dist/http-CjUO1Bec.js +1756 -0
- package/dist/http-CjUO1Bec.js.map +1 -0
- package/dist/http.d.ts +1619 -0
- package/dist/http.js +2 -0
- package/dist/index-BGC-ENnj.d.ts +1065 -0
- package/dist/index-BYv0hb8M.d.ts +1457 -0
- package/dist/index-BquQkhJi.d.ts +112 -0
- package/dist/index-COsQ-Mlz.d.ts +146 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.js +6 -0
- package/dist/indexes-BXn7a06a.js +297 -0
- package/dist/indexes-BXn7a06a.js.map +1 -0
- package/dist/indexes-DwOXkn1Y.d.ts +22 -0
- package/dist/inspect-x02aFWnh.js +149 -0
- package/dist/inspect-x02aFWnh.js.map +1 -0
- package/dist/log-walk-DIru96UT.js +260 -0
- package/dist/log-walk-DIru96UT.js.map +1 -0
- package/dist/maintenance-Bn6ul9aV.js +758 -0
- package/dist/maintenance-Bn6ul9aV.js.map +1 -0
- package/dist/maintenance.d.ts +323 -0
- package/dist/maintenance.js +2 -0
- package/dist/node.d.ts +422 -0
- package/dist/node.js +2 -0
- package/dist/normalize-XWY25_sG.js +133 -0
- package/dist/normalize-XWY25_sG.js.map +1 -0
- package/dist/observability-2IDYRuZK.js +2333 -0
- package/dist/observability-2IDYRuZK.js.map +1 -0
- package/dist/observability.d.ts +3 -0
- package/dist/observability.js +3 -0
- package/dist/plan-Cs17VqjU.js +224 -0
- package/dist/plan-Cs17VqjU.js.map +1 -0
- package/dist/query-DcSbFLJt.js +1880 -0
- package/dist/query-DcSbFLJt.js.map +1 -0
- package/dist/rebuild-index-C5gTXryd.js +119 -0
- package/dist/rebuild-index-C5gTXryd.js.map +1 -0
- package/dist/rebuild-index-DwXM0WfA.js +104 -0
- package/dist/rebuild-index-DwXM0WfA.js.map +1 -0
- package/dist/request-BEF_OvMh.js +72 -0
- package/dist/request-BEF_OvMh.js.map +1 -0
- package/dist/restore-CbKVMMpm.js +847 -0
- package/dist/restore-CbKVMMpm.js.map +1 -0
- package/dist/shared-secret-BJdSwpgw.js +71 -0
- package/dist/shared-secret-BJdSwpgw.js.map +1 -0
- package/dist/snapshot-D7C4_FSl.js +71 -0
- package/dist/snapshot-D7C4_FSl.js.map +1 -0
- package/dist/snapshot-z_N9hpTe.js +917 -0
- package/dist/snapshot-z_N9hpTe.js.map +1 -0
- package/dist/src-Chafbw8r.js +522 -0
- package/dist/src-Chafbw8r.js.map +1 -0
- package/dist/src-DyET_VPP.js +6199 -0
- package/dist/src-DyET_VPP.js.map +1 -0
- package/dist/src-n0Te1r98.js +352 -0
- package/dist/src-n0Te1r98.js.map +1 -0
- package/dist/subcommand-BWs6K7zb.js +110 -0
- package/dist/subcommand-BWs6K7zb.js.map +1 -0
- package/dist/usage-RVUQMLop.js +339 -0
- package/dist/usage-RVUQMLop.js.map +1 -0
- package/dist/validate-DhH1lO8I.js +377 -0
- package/dist/validate-DhH1lO8I.js.map +1 -0
- package/dist/wire-izfGZDvr.js +7 -0
- package/dist/wire-izfGZDvr.js.map +1 -0
- package/package.json +189 -0
|
@@ -0,0 +1,1880 @@
|
|
|
1
|
+
import { c as MANIFEST_POINTER_EMPTY_SNAPSHOT, f as decodeJsonBytes, i as FORBIDDEN_MERGE_KEYS, n as logSeqStartOf, p as encodeJsonBytes, r as readCurrentJson, t as createCurrentJson } from "./current-json-BkatBzF7.js";
|
|
2
|
+
import { t as BaerlyError } from "./errors-DOdL95kK.js";
|
|
3
|
+
import { a as readLogEntry, c as encodeIndexValue, f as versionFromContent, g as deepEqualDocumentValue, h as matchesWire, i as foldLogEntriesOnto, m as assertWireSatisfiable, n as loadSnapshotAsMap, o as walkLogRange, p as validateWire, s as allIndexKeysFor, u as validateIndexDefinition } from "./snapshot-z_N9hpTe.js";
|
|
4
|
+
import { t as normalizePredicateArg } from "./normalize-XWY25_sG.js";
|
|
5
|
+
import { i as noopMetricsRecorder, n as getCurrentContext } from "./context-Oj7ffwD-.js";
|
|
6
|
+
//#region packages/protocol/src/json.ts
|
|
7
|
+
const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
8
|
+
/**
|
|
9
|
+
* JSON Merge Patch (RFC 7396).
|
|
10
|
+
*
|
|
11
|
+
* Update `target` with a merge patch. Plain-object values recurse
|
|
12
|
+
* key-by-key; primitives, arrays, and type-mismatched values replace
|
|
13
|
+
* the target wholesale. A `null` value in `patch` deletes the key.
|
|
14
|
+
*
|
|
15
|
+
* RFC 7396 explicitly treats arrays as opaque values: an array in a
|
|
16
|
+
* patch replaces the target array — there is no element-wise merge.
|
|
17
|
+
*/
|
|
18
|
+
function merge(target, patch) {
|
|
19
|
+
if (patch === void 0) return target;
|
|
20
|
+
if (patch === null) return;
|
|
21
|
+
if (!isPlainObject(patch)) return patch;
|
|
22
|
+
if (!isPlainObject(target)) return patch;
|
|
23
|
+
const combined = { ...target };
|
|
24
|
+
for (const key of Object.keys(patch)) {
|
|
25
|
+
if (FORBIDDEN_MERGE_KEYS.has(key)) continue;
|
|
26
|
+
if (patch[key] === null) delete combined[key];
|
|
27
|
+
else combined[key] = merge(target[key], patch[key]);
|
|
28
|
+
}
|
|
29
|
+
return combined;
|
|
30
|
+
}
|
|
31
|
+
//#endregion
|
|
32
|
+
//#region packages/protocol/src/query/merge.ts
|
|
33
|
+
/**
|
|
34
|
+
* AND-merge two validated wire predicates. Powers chained
|
|
35
|
+
* `Query<T>.where(...).where(...)`: each new clause set AND's with
|
|
36
|
+
* the existing wire by clause-list concatenation; the per-field
|
|
37
|
+
* satisfiability check runs across the combined list.
|
|
38
|
+
*
|
|
39
|
+
* Companion modules: `./validate.ts`, `./matches.ts`, `./wire.ts`.
|
|
40
|
+
*/
|
|
41
|
+
/**
|
|
42
|
+
* AND-merge two validated wire predicates. The result accepts a
|
|
43
|
+
* document iff both `a` and `b` would accept it.
|
|
44
|
+
*
|
|
45
|
+
* Wire-level: clause lists concatenate. The per-field satisfiability
|
|
46
|
+
* check runs across the combined list, surfacing
|
|
47
|
+
* `BaerlyError{code:"UnsatisfiablePredicate"}` on empty residual
|
|
48
|
+
* intervals / empty `in()` intersections / `eq` outside the merged
|
|
49
|
+
* interval, and `BaerlyError{code:"InvalidConfig"}` on conflicting
|
|
50
|
+
* `eq` clauses for the same field (mirrors the pre-redesign
|
|
51
|
+
* conflict-on-shared-keys semantics).
|
|
52
|
+
*
|
|
53
|
+
* @example
|
|
54
|
+
* ```ts
|
|
55
|
+
* mergePredicateWires(
|
|
56
|
+
* { clauses: [{ op: "eq", field: "status", value: "open" }] },
|
|
57
|
+
* { clauses: [{ op: "eq", field: "priority", value: "p1" }] },
|
|
58
|
+
* );
|
|
59
|
+
* // → { clauses: [
|
|
60
|
+
* // { op: "eq", field: "status", value: "open" },
|
|
61
|
+
* // { op: "eq", field: "priority", value: "p1" },
|
|
62
|
+
* // ] }
|
|
63
|
+
*
|
|
64
|
+
* mergePredicateWires(
|
|
65
|
+
* { clauses: [{ op: "eq", field: "status", value: "open" }] },
|
|
66
|
+
* { clauses: [{ op: "eq", field: "status", value: "closed" }] },
|
|
67
|
+
* );
|
|
68
|
+
* // throws BaerlyError{InvalidConfig}: conflicting equality clauses on "status"
|
|
69
|
+
*
|
|
70
|
+
* mergePredicateWires(
|
|
71
|
+
* { clauses: [{ op: "gt", field: "x", value: 10 }] },
|
|
72
|
+
* { clauses: [{ op: "lt", field: "x", value: 5 }] },
|
|
73
|
+
* );
|
|
74
|
+
* // throws BaerlyError{UnsatisfiablePredicate}: empty interval
|
|
75
|
+
* ```
|
|
76
|
+
*/
|
|
77
|
+
const mergePredicateWires = (a, b) => {
|
|
78
|
+
const merged = { clauses: [...a.clauses, ...b.clauses] };
|
|
79
|
+
assertWireSatisfiable(merged);
|
|
80
|
+
return merged;
|
|
81
|
+
};
|
|
82
|
+
//#endregion
|
|
83
|
+
//#region packages/protocol/src/types.ts
|
|
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
|
+
};
|
|
114
|
+
/**
|
|
115
|
+
* Mint the trailing seq segment of an LSN (`<base32-time>_<sess>_<seq>`).
|
|
116
|
+
* `COUNT_BIT_WIDTH = 10` (matches `packages/protocol/src/log.ts:145`)
|
|
117
|
+
* gives a 2-char descending base-32 string with a domain of 0..1023.
|
|
118
|
+
*
|
|
119
|
+
* Used together with {@link timestamp} (the descending base-32
|
|
120
|
+
* encoding of millis-since-epoch). See {@link uint2strDesc} for the
|
|
121
|
+
* lex-reversal property both rely on.
|
|
122
|
+
*/
|
|
123
|
+
const countKey = (number) => uint2strDesc(number, 10);
|
|
124
|
+
const uint2str = (num, bits) => {
|
|
125
|
+
const maxBase32Length = Math.ceil(bits / 5);
|
|
126
|
+
return num.toString(32).padStart(maxBase32Length, "0");
|
|
127
|
+
};
|
|
128
|
+
/**
|
|
129
|
+
* Lex-reversed base-32 encoder for an unsigned integer in `[0, 2^bits)`.
|
|
130
|
+
* Pads to `Math.ceil(bits/5)` chars so all values in the domain compare
|
|
131
|
+
* lex against each other.
|
|
132
|
+
*
|
|
133
|
+
* **Order-reversal property:** for any pair of integers `a < b` (with
|
|
134
|
+
* `a, b ∈ [0, 2^bits)`), `uint2strDesc(a, bits) > uint2strDesc(b, bits)`
|
|
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".
|
|
151
|
+
*/
|
|
152
|
+
const uint2strDesc = (num, bits) => {
|
|
153
|
+
return uint2str(Math.pow(2, bits) - 1 - num, bits);
|
|
154
|
+
};
|
|
155
|
+
const str2uintDesc = (str, bits) => {
|
|
156
|
+
return Math.pow(2, bits) - 1 - parseInt(str, 32);
|
|
157
|
+
};
|
|
158
|
+
//#endregion
|
|
159
|
+
//#region packages/protocol/src/time.ts
|
|
160
|
+
const timestamp = (epoch = 0) => uint2strDesc(epoch, 42);
|
|
161
|
+
/**
|
|
162
|
+
* Delay for `ms` milliseconds, with optional cancellation. If
|
|
163
|
+
* `signal` aborts before the delay elapses, the returned promise
|
|
164
|
+
* rejects with `signal.reason`. Used by `S3HttpStorage`'s retry
|
|
165
|
+
* loop so shutdown can interrupt an in-flight backoff instead of
|
|
166
|
+
* waiting for it to complete.
|
|
167
|
+
*/
|
|
168
|
+
const delay = (ms, signal) => new Promise((resolve, reject) => {
|
|
169
|
+
if (signal?.aborted) {
|
|
170
|
+
reject(signal.reason);
|
|
171
|
+
return;
|
|
172
|
+
}
|
|
173
|
+
const timer = setTimeout(resolve, ms);
|
|
174
|
+
signal?.addEventListener("abort", () => {
|
|
175
|
+
clearTimeout(timer);
|
|
176
|
+
reject(signal.reason);
|
|
177
|
+
}, { once: true });
|
|
178
|
+
});
|
|
179
|
+
//#endregion
|
|
180
|
+
//#region packages/protocol/src/log.ts
|
|
181
|
+
const COUNT_BIT_WIDTH = 10;
|
|
182
|
+
/**
|
|
183
|
+
* Extract the `session` and `seq` embedded in an `lsn` of shape
|
|
184
|
+
* `<base32-time>_<session>_<seq>`. The seq portion is decoded as a
|
|
185
|
+
* descending base-32 integer (matches `countKey` in `./types`).
|
|
186
|
+
*
|
|
187
|
+
* Use this at the `/v1/since` cursor-decoding boundary, where a
|
|
188
|
+
* client resumes from an opaque `SinceResponse.next_cursor` and no
|
|
189
|
+
* `LogEntry` is in scope. When iterating `LogEntry` records, read
|
|
190
|
+
* `entry.session` / `entry.seq` directly instead.
|
|
191
|
+
*
|
|
192
|
+
* Throws on malformed input; callers should pass only lsns minted
|
|
193
|
+
* by `Writer.commit` (see
|
|
194
|
+
* `packages/server/src/writer.ts`).
|
|
195
|
+
*/
|
|
196
|
+
const lsnParts = (lsn) => {
|
|
197
|
+
const parts = lsn.split("_");
|
|
198
|
+
if (parts.length !== 3) throw new BaerlyError("InvalidResponse", `invalid lsn shape: ${lsn}`);
|
|
199
|
+
return {
|
|
200
|
+
session: parts[1],
|
|
201
|
+
seq: str2uintDesc(parts[2], COUNT_BIT_WIDTH)
|
|
202
|
+
};
|
|
203
|
+
};
|
|
204
|
+
//#endregion
|
|
205
|
+
//#region packages/server/src/log-conflict-adoption.ts
|
|
206
|
+
/**
|
|
207
|
+
* Decide whether the entry already at `/log/<seq>.json` is the
|
|
208
|
+
* writer's own prior in-flight attempt and may be adopted. Pure
|
|
209
|
+
* function; no I/O. The caller performs the GET (when the log PUT
|
|
210
|
+
* surfaces 412) and passes the read-back body in `ctx.existing`.
|
|
211
|
+
*
|
|
212
|
+
* @see {@link AdoptionDecision} for the return shape.
|
|
213
|
+
* @see The soundness invariant in this module's header docstring.
|
|
214
|
+
*/
|
|
215
|
+
const tryAdoptOwnSessionLogEntry = (ctx) => {
|
|
216
|
+
if (ctx.batchSize !== 1) return {
|
|
217
|
+
adopt: false,
|
|
218
|
+
reason: "batch"
|
|
219
|
+
};
|
|
220
|
+
if (ctx.existing.session !== ctx.self.session) return {
|
|
221
|
+
adopt: false,
|
|
222
|
+
reason: "foreign-session"
|
|
223
|
+
};
|
|
224
|
+
if (ctx.existing.seq !== ctx.self.seq) return {
|
|
225
|
+
adopt: false,
|
|
226
|
+
reason: "wrong-seq"
|
|
227
|
+
};
|
|
228
|
+
return {
|
|
229
|
+
adopt: true,
|
|
230
|
+
entry: ctx.existing
|
|
231
|
+
};
|
|
232
|
+
};
|
|
233
|
+
//#endregion
|
|
234
|
+
//#region packages/server/src/writer.ts
|
|
235
|
+
/**
|
|
236
|
+
* `Writer` — stateless multi-instance write engine.
|
|
237
|
+
*
|
|
238
|
+
* Each {@link Writer.commit} call reads `current.json` FRESH from
|
|
239
|
+
* the bucket, mints the next {@link LogEntry}, PUTs the content body
|
|
240
|
+
* and the log entry, and CAS-advances `current.json` with `If-Match`.
|
|
241
|
+
* Up to {@link S3_REQUEST_MAX_RETRIES} attempts on contention before
|
|
242
|
+
* surfacing `BaerlyError{code:"Conflict"}`. The optional integrity
|
|
243
|
+
* walk over the live log tail is gated by
|
|
244
|
+
* {@link WriterOptions.verifyLogIntegrityOnCommit} (default off
|
|
245
|
+
* — see the option's docstring).
|
|
246
|
+
*
|
|
247
|
+
* The instance carries no per-write cache: every commit re-reads
|
|
248
|
+
* `current.json`, so N stateless server instances writing the same
|
|
249
|
+
* tenant prefix contend at exactly one place — the conditional PUT
|
|
250
|
+
* on `current.json` — and one loses cleanly with a 412.
|
|
251
|
+
*
|
|
252
|
+
* **Manifest-first ordering is REVERSED relative to the legacy
|
|
253
|
+
* `src/syncer.ts` write loop.** Old loop: PUT manifest → PUT content
|
|
254
|
+
* → CAS. New loop: PUT content → PUT log entry → CAS-advance
|
|
255
|
+
* `current.json`. A crashed mid-loop writer leaves an unreferenced
|
|
256
|
+
* content body (no log entry points at it), not an orphan log entry
|
|
257
|
+
* with missing content. The compactor sweeps the orphan content
|
|
258
|
+
* later.
|
|
259
|
+
*
|
|
260
|
+
* **`LogEntry` shape.** Emitted entries follow the contract in
|
|
261
|
+
* `packages/protocol/src/log.ts` (see {@link LogEntry}) and
|
|
262
|
+
* `docs/spec/log-entry-shape.md`. The on-bucket key is
|
|
263
|
+
* `log/<seq>.json` (the integer `seq` is the load-bearing
|
|
264
|
+
* identifier; the `lsn` string is schema-only).
|
|
265
|
+
*
|
|
266
|
+
* @see docs/spec/sync-protocol.md for the protocol invariants this
|
|
267
|
+
* loop preserves.
|
|
268
|
+
* @see docs/spec/log-entry-shape.md for the per-field contract.
|
|
269
|
+
*/
|
|
270
|
+
const ctxMetrics = () => getCurrentContext()?.recorder ?? noopMetricsRecorder;
|
|
271
|
+
const DEFAULT_INITIAL_BACKOFF_MS = 25;
|
|
272
|
+
const MAX_BACKOFF_MS = 1500;
|
|
273
|
+
const APPLICATION_JSON = "application/json";
|
|
274
|
+
/**
|
|
275
|
+
* Empty body for index entries. Each index entry is a fact ("doc
|
|
276
|
+
* `<docId>` has `<field> = <value>`"), not data — readers list the
|
|
277
|
+
* prefix, extract the doc id, then GET the content body separately.
|
|
278
|
+
* Pre-allocated module-level constant so every index PUT shares one
|
|
279
|
+
* zero-length buffer.
|
|
280
|
+
*/
|
|
281
|
+
const EMPTY_BODY = new Uint8Array(0);
|
|
282
|
+
/**
|
|
283
|
+
* Stateless write engine for the multi-instance core.
|
|
284
|
+
*
|
|
285
|
+
* Construction is cheap and performs zero I/O — adapters build a
|
|
286
|
+
* fresh `Writer` per request and discard it. All real work
|
|
287
|
+
* happens in {@link commit}.
|
|
288
|
+
*
|
|
289
|
+
* @example
|
|
290
|
+
* ```ts
|
|
291
|
+
* import { Writer } from "@gusto/baerly-storage";
|
|
292
|
+
* import { MemoryStorage } from "@gusto/baerly-storage";
|
|
293
|
+
*
|
|
294
|
+
* const writer = new Writer({
|
|
295
|
+
* storage: new MemoryStorage(),
|
|
296
|
+
* currentJsonKey: "app/tickets/tenant/acme/manifests/tickets/current.json",
|
|
297
|
+
* });
|
|
298
|
+
*
|
|
299
|
+
* const result = await writer.commit({
|
|
300
|
+
* op: "I",
|
|
301
|
+
* collection: "tickets",
|
|
302
|
+
* docId: "doc-1",
|
|
303
|
+
* body: { _id: "doc-1", title: "hello" },
|
|
304
|
+
* });
|
|
305
|
+
* console.log(result.entry.seq, result.attempts);
|
|
306
|
+
* ```
|
|
307
|
+
*/
|
|
308
|
+
var Writer = class {
|
|
309
|
+
#storage;
|
|
310
|
+
#currentJsonKey;
|
|
311
|
+
#maxRetries;
|
|
312
|
+
#initialBackoffMs;
|
|
313
|
+
#random;
|
|
314
|
+
#indexes;
|
|
315
|
+
#verifyLogIntegrityOnCommit;
|
|
316
|
+
constructor(opts) {
|
|
317
|
+
this.#storage = opts.storage;
|
|
318
|
+
this.#currentJsonKey = opts.currentJsonKey;
|
|
319
|
+
this.#maxRetries = opts.options?.maxRetries ?? 8;
|
|
320
|
+
this.#initialBackoffMs = opts.options?.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS;
|
|
321
|
+
this.#random = opts.options?.random ?? Math.random;
|
|
322
|
+
const indexes = opts.options?.indexes ?? [];
|
|
323
|
+
for (const def of indexes) validateIndexDefinition(def);
|
|
324
|
+
this.#indexes = indexes;
|
|
325
|
+
this.#verifyLogIntegrityOnCommit = opts.options?.verifyLogIntegrityOnCommit ?? false;
|
|
326
|
+
}
|
|
327
|
+
/**
|
|
328
|
+
* Atomically commit one mutation. Reads `current.json` fresh, mints
|
|
329
|
+
* the next log entry at `seq = current.next_seq`, PUTs the content
|
|
330
|
+
* body and the log entry, then CAS-advances `current.json` with
|
|
331
|
+
* `If-Match`. Retries on conflict up to `maxRetries`.
|
|
332
|
+
*
|
|
333
|
+
* The hot-path cost under no contention is 1 GET + 3 PUTs (4 ops);
|
|
334
|
+
* an in-flight peer write costs one extra GET + the backoff sleep
|
|
335
|
+
* per retry.
|
|
336
|
+
*
|
|
337
|
+
* Idempotency: PUT content uses `If-None-Match: "*"`, so a retry of
|
|
338
|
+
* the same logical write produces the same content key and the
|
|
339
|
+
* second PUT no-ops. PUT log entry also uses `If-None-Match: "*"`,
|
|
340
|
+
* so two writers racing the same `next_seq` cause exactly one PUT
|
|
341
|
+
* to land — the loser falls into the CAS retry path.
|
|
342
|
+
*
|
|
343
|
+
* @throws BaerlyError code="Conflict" when the retry budget is
|
|
344
|
+
* exhausted (genuine high-contention case), or when the underlying
|
|
345
|
+
* `current.json` CAS PUT lost.
|
|
346
|
+
* @throws BaerlyError code="Conflict" — the writer fence
|
|
347
|
+
* (`current.json.writer_fence.epoch`) was bumped by a concurrent
|
|
348
|
+
* `claimWriter` call between this commit's read of
|
|
349
|
+
* `current.json` and its CAS-advance. The stale writer aborts
|
|
350
|
+
* to honour the new authority — the kernel does NOT retry under
|
|
351
|
+
* the old epoch. See {@link claimWriter} for the rotation
|
|
352
|
+
* recipe.
|
|
353
|
+
* @throws BaerlyError code="Internal" when a log entry expected in
|
|
354
|
+
* `[0, next_seq)` is missing — a protocol-invariant violation
|
|
355
|
+
* (compactor bug or stale `current.json`).
|
|
356
|
+
* @throws BaerlyError code="InvalidResponse" when a log-entry body
|
|
357
|
+
* isn't valid JSON.
|
|
358
|
+
*
|
|
359
|
+
* **Implicit provisioning.** When `current.json` does not exist at
|
|
360
|
+
* `currentJsonKey` (fresh bucket, fresh collection), the writer
|
|
361
|
+
* auto-creates it with a zero-state manifest before the commit
|
|
362
|
+
* lands. The cost is one extra Class A PUT on the very first
|
|
363
|
+
* commit per collection; steady-state cost is unchanged. A peer
|
|
364
|
+
* racing the same first-write loses cleanly on the create CAS
|
|
365
|
+
* and re-reads to pick up the winner's manifest.
|
|
366
|
+
*/
|
|
367
|
+
async commit(input) {
|
|
368
|
+
const session = uuid().slice(0, 6);
|
|
369
|
+
const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
|
|
370
|
+
for (let attempt = 1; attempt <= this.#maxRetries; attempt++) {
|
|
371
|
+
let success;
|
|
372
|
+
try {
|
|
373
|
+
success = await this.#singleAttemptCommit([input], session, logPrefix, "Writer", true);
|
|
374
|
+
} catch (error) {
|
|
375
|
+
if (!isPreconditionFailed(error)) throw error;
|
|
376
|
+
await this.#backoff(attempt);
|
|
377
|
+
continue;
|
|
378
|
+
}
|
|
379
|
+
await this.#verifyFenceUnchanged(success.expectedEpoch, "Writer");
|
|
380
|
+
this.#emitWriteMetrics(input.collection, success.classAOps + (attempt - 1));
|
|
381
|
+
return {
|
|
382
|
+
entry: success.entries[0],
|
|
383
|
+
currentEtag: success.currentEtag,
|
|
384
|
+
attempts: attempt
|
|
385
|
+
};
|
|
386
|
+
}
|
|
387
|
+
throw new BaerlyError("Conflict", `Writer: CAS conflict on ${this.#currentJsonKey} after ${this.#maxRetries} attempts`);
|
|
388
|
+
}
|
|
389
|
+
/**
|
|
390
|
+
* Single-attempt batched commit. Reads `current.json` ONCE, mints
|
|
391
|
+
* `inputs.length` log entries with contiguous `seq` numbers
|
|
392
|
+
* starting at the current `next_seq`, PUTs each content body and
|
|
393
|
+
* each log entry, then CAS-advances `current.json` from
|
|
394
|
+
* `next_seq = N` to `next_seq = N + inputs.length` with
|
|
395
|
+
* `If-Match`.
|
|
396
|
+
*
|
|
397
|
+
* NO retry on CAS loss. On `current.json` 412, throws
|
|
398
|
+
* `BaerlyError{code:"Conflict"}` immediately — the caller (here:
|
|
399
|
+
* `Db.transaction`) decides whether to retry by re-running the
|
|
400
|
+
* body, or to surface to the app. Likewise on a log-entry 412
|
|
401
|
+
* (a peer wrote our seq).
|
|
402
|
+
*
|
|
403
|
+
* Empty `inputs`: returns `{ entries: [], currentEtag: undefined }`
|
|
404
|
+
* after zero storage operations.
|
|
405
|
+
*
|
|
406
|
+
* @throws BaerlyError code="Conflict" — CAS lost on `current.json`,
|
|
407
|
+
* or a log entry already exists at our seq (peer wrote ahead).
|
|
408
|
+
* @throws BaerlyError code="Conflict" — the writer fence
|
|
409
|
+
* (`current.json.writer_fence.epoch`) was bumped by a concurrent
|
|
410
|
+
* `claimWriter` call between this batch's read of
|
|
411
|
+
* `current.json` and its CAS-advance. The stale writer aborts
|
|
412
|
+
* to honour the new authority — the kernel does NOT retry under
|
|
413
|
+
* the old epoch. See {@link claimWriter} for the rotation
|
|
414
|
+
* recipe.
|
|
415
|
+
* @throws BaerlyError code="Internal" — protocol-invariant violation
|
|
416
|
+
* (missing log entry inside `[0, next_seq)`).
|
|
417
|
+
* @throws BaerlyError code="InvalidResponse" — malformed log body.
|
|
418
|
+
*
|
|
419
|
+
* **Implicit provisioning.** Like {@link commit}, this path auto-
|
|
420
|
+
* creates `current.json` with a zero-state manifest on a missing
|
|
421
|
+
* read. Because `commitBatch` does NOT retry on CAS loss, a peer
|
|
422
|
+
* racing the same first-write surfaces `Conflict` to the caller
|
|
423
|
+
* (`Db.transaction` re-runs the body); the manifest is durable
|
|
424
|
+
* regardless of which writer won the create.
|
|
425
|
+
*/
|
|
426
|
+
async commitBatch(inputs) {
|
|
427
|
+
if (inputs.length === 0) return {
|
|
428
|
+
entries: [],
|
|
429
|
+
currentEtag: void 0
|
|
430
|
+
};
|
|
431
|
+
const session = uuid().slice(0, 6);
|
|
432
|
+
const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
|
|
433
|
+
const success = await this.#singleAttemptCommit(inputs, session, logPrefix, "Writer.commitBatch", false);
|
|
434
|
+
await this.#verifyFenceUnchanged(success.expectedEpoch, "Writer.commitBatch");
|
|
435
|
+
this.#emitWriteMetrics(inputs[0].collection, success.classAOps);
|
|
436
|
+
return {
|
|
437
|
+
entries: success.entries,
|
|
438
|
+
currentEtag: success.currentEtag
|
|
439
|
+
};
|
|
440
|
+
}
|
|
441
|
+
/**
|
|
442
|
+
* One full commit attempt — the shared body of {@link commit} and
|
|
443
|
+
* {@link commitBatch}. Reads `current.json`, walks the log, mints N
|
|
444
|
+
* entries, PUTs content + indexes in parallel, PUTs log entries,
|
|
445
|
+
* CAS-advances `current.json`. Returns the success payload + the
|
|
446
|
+
* pre-commit fence epoch so the caller can run
|
|
447
|
+
* {@link #verifyFenceUnchanged} outside the retry-catch arm.
|
|
448
|
+
*
|
|
449
|
+
* Retryable failures (a peer wrote our seq; a peer won the CAS on
|
|
450
|
+
* `current.json`) throw `BaerlyError{code:"Conflict"}`. The caller
|
|
451
|
+
* catches via {@link isPreconditionFailed} and either retries
|
|
452
|
+
* (`commit`) or surfaces (`commitBatch`). Fence-bump and protocol-
|
|
453
|
+
* invariant violations are NOT thrown from this helper — the fence
|
|
454
|
+
* check lives in the caller so its `Conflict` propagates past the
|
|
455
|
+
* retry-catch arm. Other thrown `BaerlyError`s (Internal,
|
|
456
|
+
* InvalidResponse, NetworkError) bypass `isPreconditionFailed` and
|
|
457
|
+
* propagate naturally.
|
|
458
|
+
*
|
|
459
|
+
* Crash safety invariant: content / index PUTs are awaited before
|
|
460
|
+
* log PUTs, which are awaited before the CAS. A crashed mid-attempt
|
|
461
|
+
* writer leaves orphan content / index entries (no log entry
|
|
462
|
+
* references them) — the compactor sweeps the orphans. The
|
|
463
|
+
* inverse — orphan log entry with missing content — is never
|
|
464
|
+
* produced.
|
|
465
|
+
*/
|
|
466
|
+
async #singleAttemptCommit(inputs, session, logPrefix, errorPrefix, adoptOwnSessionOnLogConflict) {
|
|
467
|
+
const read = await readCurrentJson(this.#storage, this.#currentJsonKey) ?? await this.#provisionCurrentJson();
|
|
468
|
+
const current = read.json;
|
|
469
|
+
const baseEtag = read.etag;
|
|
470
|
+
const expectedEpoch = current.writer_fence.epoch;
|
|
471
|
+
if (this.#verifyLogIntegrityOnCommit) await this.#walkLog(logPrefix, logSeqStartOf(current), current.next_seq);
|
|
472
|
+
const entries = [];
|
|
473
|
+
for (let i = 0; i < inputs.length; i++) {
|
|
474
|
+
const input = inputs[i];
|
|
475
|
+
const seq = current.next_seq + i;
|
|
476
|
+
const entry = {
|
|
477
|
+
lsn: `${timestamp(Date.now())}_${session}_${countKey(seq)}`,
|
|
478
|
+
commit_ts: (/* @__PURE__ */ new Date()).toISOString(),
|
|
479
|
+
op: input.op,
|
|
480
|
+
collection: input.collection,
|
|
481
|
+
doc_id: input.docId,
|
|
482
|
+
schema_version: 0,
|
|
483
|
+
session,
|
|
484
|
+
seq,
|
|
485
|
+
...input.op !== "D" && input.body !== void 0 ? {
|
|
486
|
+
new: input.body,
|
|
487
|
+
patch: input.body
|
|
488
|
+
} : {},
|
|
489
|
+
...input.origin !== void 0 ? { origin: input.origin } : {}
|
|
490
|
+
};
|
|
491
|
+
entries.push(entry);
|
|
492
|
+
}
|
|
493
|
+
let contentPutCount = 0;
|
|
494
|
+
let indexClassA = 0;
|
|
495
|
+
const parallelPuts = [];
|
|
496
|
+
const inBatchImage = /* @__PURE__ */ new Map();
|
|
497
|
+
for (const input of inputs) {
|
|
498
|
+
if (input.op !== "D" && input.body !== void 0) {
|
|
499
|
+
contentPutCount++;
|
|
500
|
+
const bytes = encodeJsonBytes(input.body);
|
|
501
|
+
const contentKey = `${logPrefix}/content/${await versionFromContent(bytes)}.json`;
|
|
502
|
+
parallelPuts.push(this.#storage.put(contentKey, bytes, {
|
|
503
|
+
ifNoneMatch: "*",
|
|
504
|
+
contentType: APPLICATION_JSON
|
|
505
|
+
}).catch((error) => {
|
|
506
|
+
this.#observe429(error, input.collection);
|
|
507
|
+
if (isPreconditionFailed(error)) return;
|
|
508
|
+
throw error;
|
|
509
|
+
}));
|
|
510
|
+
}
|
|
511
|
+
if (this.#indexes.length > 0) {
|
|
512
|
+
let newKeys = [];
|
|
513
|
+
let staleKeys = [];
|
|
514
|
+
if (input.op === "I") newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
|
|
515
|
+
else if (input.op === "U") {
|
|
516
|
+
const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(logPrefix, input.collection, input.docId, current.next_seq);
|
|
517
|
+
const oldKeys = allIndexKeysFor(logPrefix, this.#indexes, preImage, input.docId);
|
|
518
|
+
newKeys = allIndexKeysFor(logPrefix, this.#indexes, input.body, input.docId);
|
|
519
|
+
const newSet = new Set(newKeys);
|
|
520
|
+
staleKeys = oldKeys.filter((k) => !newSet.has(k));
|
|
521
|
+
} else {
|
|
522
|
+
const preImage = inBatchImage.has(input.docId) ? inBatchImage.get(input.docId) : await this.#readPreImage(logPrefix, input.collection, input.docId, current.next_seq);
|
|
523
|
+
staleKeys = allIndexKeysFor(logPrefix, this.#indexes, preImage, input.docId);
|
|
524
|
+
}
|
|
525
|
+
for (const k of newKeys) parallelPuts.push(this.#storage.put(k, EMPTY_BODY, {
|
|
526
|
+
ifNoneMatch: "*",
|
|
527
|
+
contentType: APPLICATION_JSON
|
|
528
|
+
}).catch((error) => {
|
|
529
|
+
this.#observe429(error, input.collection);
|
|
530
|
+
if (isPreconditionFailed(error)) return;
|
|
531
|
+
throw error;
|
|
532
|
+
}));
|
|
533
|
+
for (const k of staleKeys) parallelPuts.push(this.#storage.delete(k));
|
|
534
|
+
indexClassA += newKeys.length + staleKeys.length;
|
|
535
|
+
if (newKeys.length + staleKeys.length > 0) ctxMetrics().histogram("db.write.index_ops_per_logical_write", newKeys.length + staleKeys.length, { collection: input.collection });
|
|
536
|
+
inBatchImage.set(input.docId, input.op === "D" ? void 0 : input.body);
|
|
537
|
+
}
|
|
538
|
+
}
|
|
539
|
+
await Promise.all(parallelPuts);
|
|
540
|
+
const logPutOne = async (entry) => {
|
|
541
|
+
const logEntryKey = `${logPrefix}/log/${entry.seq}.json`;
|
|
542
|
+
const logBytes = encodeJsonBytes(entry);
|
|
543
|
+
try {
|
|
544
|
+
await this.#storage.put(logEntryKey, logBytes, {
|
|
545
|
+
ifNoneMatch: "*",
|
|
546
|
+
contentType: APPLICATION_JSON
|
|
547
|
+
});
|
|
548
|
+
return { ok: true };
|
|
549
|
+
} catch (error) {
|
|
550
|
+
this.#observe429(error, entry.collection);
|
|
551
|
+
if (!isPreconditionFailed(error)) throw error;
|
|
552
|
+
ctxMetrics().counter("db.r2.put.412_total", 1, {
|
|
553
|
+
collection: entry.collection,
|
|
554
|
+
step: "log-put"
|
|
555
|
+
});
|
|
556
|
+
return { ok: false };
|
|
557
|
+
}
|
|
558
|
+
};
|
|
559
|
+
const logPutResults = await Promise.all(entries.map(logPutOne));
|
|
560
|
+
let committedEntries = entries;
|
|
561
|
+
const firstConflictIdx = logPutResults.findIndex((r) => !r.ok);
|
|
562
|
+
if (firstConflictIdx !== -1) {
|
|
563
|
+
const conflictedEntry = entries[firstConflictIdx];
|
|
564
|
+
const logEntryKey = `${logPrefix}/log/${conflictedEntry.seq}.json`;
|
|
565
|
+
if (adoptOwnSessionOnLogConflict) {
|
|
566
|
+
const decision = tryAdoptOwnSessionLogEntry({
|
|
567
|
+
self: conflictedEntry,
|
|
568
|
+
existing: await readLogEntry(this.#storage, logEntryKey),
|
|
569
|
+
batchSize: inputs.length
|
|
570
|
+
});
|
|
571
|
+
if (decision.adopt) committedEntries = [decision.entry];
|
|
572
|
+
else throw new BaerlyError("Conflict", `${errorPrefix}: log entry already exists at ${logEntryKey}; ${decision.reason}`);
|
|
573
|
+
} else throw new BaerlyError("Conflict", `${errorPrefix}: log entry already exists at ${logEntryKey}; peer wrote our seq`);
|
|
574
|
+
}
|
|
575
|
+
const nextBody = encodeJsonBytes({
|
|
576
|
+
...current,
|
|
577
|
+
next_seq: current.next_seq + inputs.length
|
|
578
|
+
});
|
|
579
|
+
const putOpts = {
|
|
580
|
+
ifMatch: baseEtag,
|
|
581
|
+
contentType: APPLICATION_JSON
|
|
582
|
+
};
|
|
583
|
+
let result;
|
|
584
|
+
try {
|
|
585
|
+
result = await this.#storage.put(this.#currentJsonKey, nextBody, putOpts);
|
|
586
|
+
} catch (error) {
|
|
587
|
+
this.#observe429(error, inputs[0].collection);
|
|
588
|
+
if (isPreconditionFailed(error)) {
|
|
589
|
+
ctxMetrics().counter("db.r2.put.412_total", 1, {
|
|
590
|
+
collection: inputs[0].collection,
|
|
591
|
+
step: "current-json-cas"
|
|
592
|
+
});
|
|
593
|
+
throw new BaerlyError("Conflict", `${errorPrefix}: CAS conflict on ${this.#currentJsonKey}`);
|
|
594
|
+
}
|
|
595
|
+
throw error;
|
|
596
|
+
}
|
|
597
|
+
const classAOps = contentPutCount + entries.length + indexClassA + 1;
|
|
598
|
+
return {
|
|
599
|
+
entries: committedEntries,
|
|
600
|
+
currentEtag: result.etag,
|
|
601
|
+
classAOps,
|
|
602
|
+
expectedEpoch
|
|
603
|
+
};
|
|
604
|
+
}
|
|
605
|
+
/**
|
|
606
|
+
* Read the pre-image content body for a doc by walking the live
|
|
607
|
+
* log backwards from `currentNextSeq` looking for the
|
|
608
|
+
* most-recent I/U entry on this `(collection, docId)`. Returns
|
|
609
|
+
* `undefined` when:
|
|
610
|
+
*
|
|
611
|
+
* - the doc's most-recent op was `D` (tombstone — no live body);
|
|
612
|
+
* - no entry for this doc lives inside the visible log range
|
|
613
|
+
* `[log_seq_start, currentNextSeq)` (a fresh-insert race or
|
|
614
|
+
* the doc has been folded into the snapshot but is no longer
|
|
615
|
+
* referenced).
|
|
616
|
+
*
|
|
617
|
+
* Used ONLY by the index-emission path on `U` / `D` to compute
|
|
618
|
+
* the stale-key set. Bounded by `log_seq_start`: entries below
|
|
619
|
+
* have been folded into the snapshot and may already be swept
|
|
620
|
+
* off the bucket — a snapshot fold is the rebuild command's job
|
|
621
|
+
* (see `./rebuild-index.ts`), not the writer's.
|
|
622
|
+
*
|
|
623
|
+
* **Cost note:** linear walk, O(snapshot lag). For day-one Phase
|
|
624
|
+
* 8 collections (helpdesk-shape: 100s of docs, <10k log entries)
|
|
625
|
+
* this is fine — the compactor folds the live tail every ~100
|
|
626
|
+
* entries (`packages/server/src/compactor.ts`). A follow-up ticket
|
|
627
|
+
* caches per-doc index head in `current.json` for O(1) lookup.
|
|
628
|
+
* The bound is documented; out of scope here.
|
|
629
|
+
*/
|
|
630
|
+
/**
|
|
631
|
+
* Auto-create the per-collection `current.json` at
|
|
632
|
+
* `this.#currentJsonKey` with a zero-state initial manifest. Called
|
|
633
|
+
* by `#singleAttemptCommit` when the read returned `null` (fresh
|
|
634
|
+
* bucket / fresh collection).
|
|
635
|
+
*
|
|
636
|
+
* Concurrency: `createCurrentJson` uses `If-None-Match: "*"`. If a
|
|
637
|
+
* peer raced us and won, the storage layer surfaces `Conflict`; we
|
|
638
|
+
* recover by re-reading the now-present manifest. We do NOT retry
|
|
639
|
+
* the create — a single recover-via-read covers every race that
|
|
640
|
+
* could have produced our null read.
|
|
641
|
+
*
|
|
642
|
+
* The seed shape (`snapshot: null`, `next_seq: 0`, `log_seq_start:
|
|
643
|
+
* 0`, `writer_fence: { epoch: 0, owner: "", claimed_at: "" }`)
|
|
644
|
+
* matches `ensureTable` and `baerly deploy`'s pre-warm path, so an
|
|
645
|
+
* operator who pre-provisions and a writer who auto-creates land
|
|
646
|
+
* on byte-identical bytes.
|
|
647
|
+
*
|
|
648
|
+
* @throws BaerlyError code="InvalidResponse" — the post-recover
|
|
649
|
+
* re-read also returned null. Defensive guard; in practice
|
|
650
|
+
* unreachable because the Conflict implies the key now exists.
|
|
651
|
+
*/
|
|
652
|
+
async #provisionCurrentJson() {
|
|
653
|
+
const initial = {
|
|
654
|
+
schema_version: 1,
|
|
655
|
+
snapshot: null,
|
|
656
|
+
next_seq: 0,
|
|
657
|
+
log_seq_start: 0,
|
|
658
|
+
writer_fence: {
|
|
659
|
+
epoch: 0,
|
|
660
|
+
owner: "",
|
|
661
|
+
claimed_at: ""
|
|
662
|
+
}
|
|
663
|
+
};
|
|
664
|
+
try {
|
|
665
|
+
return await createCurrentJson(this.#storage, this.#currentJsonKey, initial);
|
|
666
|
+
} catch (error) {
|
|
667
|
+
if (!(error instanceof BaerlyError) || error.code !== "Conflict") throw error;
|
|
668
|
+
}
|
|
669
|
+
const recovered = await readCurrentJson(this.#storage, this.#currentJsonKey);
|
|
670
|
+
if (recovered === null) throw new BaerlyError("InvalidResponse", `Writer: current.json missing at ${this.#currentJsonKey} after auto-create raced and recover read returned null`);
|
|
671
|
+
return recovered;
|
|
672
|
+
}
|
|
673
|
+
async #readPreImage(logPrefix, collection, docId, currentNextSeq) {
|
|
674
|
+
for (let s = currentNextSeq - 1; s >= 0; s--) {
|
|
675
|
+
const logKey = `${logPrefix}/log/${s}.json`;
|
|
676
|
+
const got = await this.#storage.get(logKey);
|
|
677
|
+
if (got === null) continue;
|
|
678
|
+
let entry;
|
|
679
|
+
try {
|
|
680
|
+
entry = decodeJsonBytes(got.body);
|
|
681
|
+
} catch {
|
|
682
|
+
continue;
|
|
683
|
+
}
|
|
684
|
+
if (entry.collection !== collection || entry.doc_id !== docId) continue;
|
|
685
|
+
if (entry.op === "D") return;
|
|
686
|
+
if ((entry.op === "I" || entry.op === "U") && entry.new !== void 0) return entry.new;
|
|
687
|
+
}
|
|
688
|
+
}
|
|
689
|
+
/**
|
|
690
|
+
* Walk `log/<logSeqStart>.json` … `log/<nextSeq - 1>.json` with
|
|
691
|
+
* bounded parallelism via `walkLogRange`. Materialised entries are
|
|
692
|
+
* discarded — the walk's only job is to surface a hole or a
|
|
693
|
+
* malformed body inside the visible range as
|
|
694
|
+
* `BaerlyError{code:"Internal"}` / `"InvalidResponse"`.
|
|
695
|
+
*
|
|
696
|
+
* Gated on `verifyLogIntegrityOnCommit`; default off in production
|
|
697
|
+
* because the per-doc fold already lives in the read path. See the
|
|
698
|
+
* option's docstring for the rationale and the opt-in convention.
|
|
699
|
+
*
|
|
700
|
+
* `logSeqStart` is the boundary set by the compactor on
|
|
701
|
+
* `current.json.log_seq_start`. Entries below it have been folded
|
|
702
|
+
* into the snapshot and may have been swept off the bucket, so the
|
|
703
|
+
* walk MUST NOT GET-require them.
|
|
704
|
+
*/
|
|
705
|
+
async #walkLog(logPrefix, logSeqStart, nextSeq) {
|
|
706
|
+
await walkLogRange(this.#storage, logPrefix, logSeqStart, nextSeq);
|
|
707
|
+
}
|
|
708
|
+
/**
|
|
709
|
+
* Bump the `db.r2.put.429_total` counter when `err` looks like an
|
|
710
|
+
* R2 prefix-partition rate-limit. Best-effort: detected via
|
|
711
|
+
* `BaerlyError{code:"NetworkError"}` with a `429` token in the
|
|
712
|
+
* message. Called from every PUT call site's catch arm; mutually
|
|
713
|
+
* exclusive in practice with `isPreconditionFailed` (412 ≠ 429).
|
|
714
|
+
*/
|
|
715
|
+
#observe429(err, collection) {
|
|
716
|
+
if (is429(err)) ctxMetrics().counter("db.r2.put.429_total", 1, { collection });
|
|
717
|
+
}
|
|
718
|
+
/**
|
|
719
|
+
* Emit the per-logical-write `class_a_ops_per_logical_write`
|
|
720
|
+
* histogram shared by `commit` and `commitBatch`. `classAOps`
|
|
721
|
+
* differs between the two paths (retry-budget vs batch shape),
|
|
722
|
+
* so each caller computes it.
|
|
723
|
+
*/
|
|
724
|
+
#emitWriteMetrics(collection, classAOps) {
|
|
725
|
+
ctxMetrics().histogram("db.write.class_a_ops_per_logical_write", classAOps, { collection });
|
|
726
|
+
}
|
|
727
|
+
/**
|
|
728
|
+
* Re-read `current.json` after a successful CAS and assert the
|
|
729
|
+
* writer-fence epoch is still ours. The CAS only mutated `next_seq`
|
|
730
|
+
* (the fence is preserved from `current`), so a post-write epoch
|
|
731
|
+
* mismatch can only mean another writer claimed the fence between
|
|
732
|
+
* our step-1 read and step-6 PUT — the exact split-brain
|
|
733
|
+
* `WriterFence` prevents. Throws `Conflict`; no retry, since the
|
|
734
|
+
* stale writer must defer to the new authority.
|
|
735
|
+
*
|
|
736
|
+
* The fence-verify GET is Class B and intentionally NOT counted in
|
|
737
|
+
* `class_a_ops_per_logical_write`.
|
|
738
|
+
*/
|
|
739
|
+
async #verifyFenceUnchanged(expectedEpoch, where) {
|
|
740
|
+
const postRead = await readCurrentJson(this.#storage, this.#currentJsonKey);
|
|
741
|
+
if (postRead === null) return;
|
|
742
|
+
if (postRead.json.writer_fence.epoch === expectedEpoch) return;
|
|
743
|
+
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`);
|
|
744
|
+
}
|
|
745
|
+
/**
|
|
746
|
+
* Exponential backoff with full jitter. `25 * 2^(attempt-1)` capped
|
|
747
|
+
* at 1500ms; uniform jitter in `[0, base)` keeps colliding peers
|
|
748
|
+
* from re-racing in lockstep. Worst-case total wait across the
|
|
749
|
+
* default 8 attempts is roughly 2.5 s — well under a typical
|
|
750
|
+
* Worker request budget.
|
|
751
|
+
*/
|
|
752
|
+
async #backoff(attempt) {
|
|
753
|
+
const sleepMs = Math.min(this.#initialBackoffMs * 2 ** (attempt - 1), MAX_BACKOFF_MS) * this.#random();
|
|
754
|
+
if (sleepMs <= 0) return;
|
|
755
|
+
await new Promise((r) => setTimeout(r, sleepMs));
|
|
756
|
+
}
|
|
757
|
+
};
|
|
758
|
+
/**
|
|
759
|
+
* `true` when the underlying storage surfaced a `PreconditionFailed`
|
|
760
|
+
* 412 (or its non-S3 equivalents). Every in-tree {@link Storage} impl
|
|
761
|
+
* surfaces a lost CAS as `BaerlyError{code:"Conflict"}`.
|
|
762
|
+
*/
|
|
763
|
+
const isPreconditionFailed = (err) => err instanceof BaerlyError && err.code === "Conflict";
|
|
764
|
+
/**
|
|
765
|
+
* `true` when the underlying storage surfaced an R2 prefix-partition
|
|
766
|
+
* rate-limit. {@link S3HttpStorage} stamps the upstream HTTP status
|
|
767
|
+
* onto `BaerlyError.cause` as `{ status }`; we discriminate on that
|
|
768
|
+
* structured field rather than regex-matching the message.
|
|
769
|
+
*/
|
|
770
|
+
const is429 = (err) => {
|
|
771
|
+
if (!(err instanceof BaerlyError) || err.code !== "NetworkError") return false;
|
|
772
|
+
return err.cause?.status === 429;
|
|
773
|
+
};
|
|
774
|
+
//#endregion
|
|
775
|
+
//#region packages/server/src/query-planner-implies.ts
|
|
776
|
+
/**
|
|
777
|
+
* Filtered-index implication checker — decides whether every
|
|
778
|
+
* document accepted by a query predicate is also accepted by a
|
|
779
|
+
* filtered index's predicate. The query planner uses the result to
|
|
780
|
+
* rank candidate indexes; see {@link "./query-planner.ts".planQuery}.
|
|
781
|
+
*
|
|
782
|
+
* Pure-function module: no I/O, no `Db` / `Storage` imports. Lives
|
|
783
|
+
* in `@baerly/server` (not in `@baerly/protocol`) because the
|
|
784
|
+
* planner is the only caller.
|
|
785
|
+
*
|
|
786
|
+
* Operates on the wire form: both inputs are {@link PredicateWire}s
|
|
787
|
+
* with clauses already grouped by `(op, field, value)`. The
|
|
788
|
+
* normaliser at `@baerly/protocol`'s `./query/normalize.ts` has
|
|
789
|
+
* already flattened nested literal sub-predicates into dotted-path
|
|
790
|
+
* `eq` clauses, so there is no recursion on nested objects here.
|
|
791
|
+
*/
|
|
792
|
+
/**
|
|
793
|
+
* Group a wire's clauses by `field` so the per-field implication
|
|
794
|
+
* check can reason over one bundle at a time. Inlined small helper
|
|
795
|
+
* (not exported) so the planner module doesn't need to expose its
|
|
796
|
+
* grouping helper as a cross-module contract.
|
|
797
|
+
*/
|
|
798
|
+
const groupByField = (wire) => {
|
|
799
|
+
const groups = /* @__PURE__ */ new Map();
|
|
800
|
+
for (const clause of wire.clauses) {
|
|
801
|
+
const bucket = groups.get(clause.field);
|
|
802
|
+
if (bucket === void 0) groups.set(clause.field, [clause]);
|
|
803
|
+
else bucket.push(clause);
|
|
804
|
+
}
|
|
805
|
+
return groups;
|
|
806
|
+
};
|
|
807
|
+
/**
|
|
808
|
+
* Collapse a per-field clause list into an {@link OperatorBundle}.
|
|
809
|
+
* Returns `"unknown-shape"` when the group has more than one `in`
|
|
810
|
+
* clause (set-intersection at plan time is out of scope) or
|
|
811
|
+
* unrecognised ops slipping through (defensive — the validator
|
|
812
|
+
* already locked the op vocabulary). Multiple `eq` clauses on one
|
|
813
|
+
* field: the validator proves they all agree, so we pick the first.
|
|
814
|
+
* Multiple range clauses on one field: take the strictest bound
|
|
815
|
+
* (tightest `lo` = numerically largest; tightest `hi` = numerically
|
|
816
|
+
* smallest).
|
|
817
|
+
*/
|
|
818
|
+
const decodeGroup = (clauses) => {
|
|
819
|
+
const bundle = {};
|
|
820
|
+
for (const clause of clauses) {
|
|
821
|
+
const v = clause.value;
|
|
822
|
+
if (clause.op === "eq") bundle.eq = v;
|
|
823
|
+
else if (clause.op === "gte") {
|
|
824
|
+
const next = {
|
|
825
|
+
value: v,
|
|
826
|
+
inclusive: true
|
|
827
|
+
};
|
|
828
|
+
bundle.lo = tightestLo(bundle.lo, next);
|
|
829
|
+
} else if (clause.op === "gt") {
|
|
830
|
+
const next = {
|
|
831
|
+
value: v,
|
|
832
|
+
inclusive: false
|
|
833
|
+
};
|
|
834
|
+
bundle.lo = tightestLo(bundle.lo, next);
|
|
835
|
+
} else if (clause.op === "lte") {
|
|
836
|
+
const next = {
|
|
837
|
+
value: v,
|
|
838
|
+
inclusive: true
|
|
839
|
+
};
|
|
840
|
+
bundle.hi = tightestHi(bundle.hi, next);
|
|
841
|
+
} else if (clause.op === "lt") {
|
|
842
|
+
const next = {
|
|
843
|
+
value: v,
|
|
844
|
+
inclusive: false
|
|
845
|
+
};
|
|
846
|
+
bundle.hi = tightestHi(bundle.hi, next);
|
|
847
|
+
} else if (clause.op === "in") {
|
|
848
|
+
if (bundle.in !== void 0) return "unknown-shape";
|
|
849
|
+
if (!Array.isArray(v)) return "unknown-shape";
|
|
850
|
+
bundle.in = v;
|
|
851
|
+
} else return "unknown-shape";
|
|
852
|
+
}
|
|
853
|
+
return bundle;
|
|
854
|
+
};
|
|
855
|
+
const tightestLo = (existing, next) => {
|
|
856
|
+
if (existing === void 0) return next;
|
|
857
|
+
if (typeof existing.value !== typeof next.value) return existing;
|
|
858
|
+
if (next.value > existing.value) return next;
|
|
859
|
+
if (next.value < existing.value) return existing;
|
|
860
|
+
if (!next.inclusive && existing.inclusive) return next;
|
|
861
|
+
return existing;
|
|
862
|
+
};
|
|
863
|
+
const tightestHi = (existing, next) => {
|
|
864
|
+
if (existing === void 0) return next;
|
|
865
|
+
if (typeof existing.value !== typeof next.value) return existing;
|
|
866
|
+
if (next.value < existing.value) return next;
|
|
867
|
+
if (next.value > existing.value) return existing;
|
|
868
|
+
if (!next.inclusive && existing.inclusive) return next;
|
|
869
|
+
return existing;
|
|
870
|
+
};
|
|
871
|
+
/**
|
|
872
|
+
* Does the query's lower bound `loQ` (`undefined` if none) prove that
|
|
873
|
+
* every matching doc satisfies the filter's lower bound `loF`?
|
|
874
|
+
*
|
|
875
|
+
* `loF.inclusive` true → need doc ≥ loF.value; `loF.inclusive` false →
|
|
876
|
+
* need doc > loF.value. A stricter `loQ` (numerically larger or with
|
|
877
|
+
* tighter inclusivity) always implies a looser `loF`.
|
|
878
|
+
*/
|
|
879
|
+
const lowerBoundImplies = (loF, loQ) => {
|
|
880
|
+
if (loQ === void 0) return false;
|
|
881
|
+
if (typeof loF.value !== typeof loQ.value) return false;
|
|
882
|
+
if (loQ.value > loF.value) return true;
|
|
883
|
+
if (loQ.value < loF.value) return false;
|
|
884
|
+
if (loF.inclusive) return true;
|
|
885
|
+
return !loQ.inclusive;
|
|
886
|
+
};
|
|
887
|
+
/** Mirror of lowerBoundImplies for upper bounds. */
|
|
888
|
+
const upperBoundImplies = (hiF, hiQ) => {
|
|
889
|
+
if (hiQ === void 0) return false;
|
|
890
|
+
if (typeof hiF.value !== typeof hiQ.value) return false;
|
|
891
|
+
if (hiQ.value < hiF.value) return true;
|
|
892
|
+
if (hiQ.value > hiF.value) return false;
|
|
893
|
+
if (hiF.inclusive) return true;
|
|
894
|
+
return !hiQ.inclusive;
|
|
895
|
+
};
|
|
896
|
+
const loFromQuery = (q) => {
|
|
897
|
+
if (q.eq !== void 0) return {
|
|
898
|
+
value: q.eq,
|
|
899
|
+
inclusive: true
|
|
900
|
+
};
|
|
901
|
+
if (q.in !== void 0 && q.in.length > 0) return {
|
|
902
|
+
value: q.in.reduce((acc, v) => v < acc ? v : acc, q.in[0]),
|
|
903
|
+
inclusive: true
|
|
904
|
+
};
|
|
905
|
+
return q.lo;
|
|
906
|
+
};
|
|
907
|
+
const hiFromQuery = (q) => {
|
|
908
|
+
if (q.eq !== void 0) return {
|
|
909
|
+
value: q.eq,
|
|
910
|
+
inclusive: true
|
|
911
|
+
};
|
|
912
|
+
if (q.in !== void 0 && q.in.length > 0) return {
|
|
913
|
+
value: q.in.reduce((acc, v) => v > acc ? v : acc, q.in[0]),
|
|
914
|
+
inclusive: true
|
|
915
|
+
};
|
|
916
|
+
return q.hi;
|
|
917
|
+
};
|
|
918
|
+
/**
|
|
919
|
+
* Filtered-index implication checker — decides whether every document
|
|
920
|
+
* accepted by `queryWire` is also accepted by `indexFilterWire`. When
|
|
921
|
+
* `true`, a walk over an index declared with `predicate: indexFilterWire`
|
|
922
|
+
* is **complete** for `queryWire`: no matching doc is missing
|
|
923
|
+
* from the smaller key set, so the planner can prefer it.
|
|
924
|
+
*
|
|
925
|
+
* Implication on `eq`, `gt` / `gte`, `lt` / `lte`, and `in` is
|
|
926
|
+
* sound and complete in pure operator form; combined shapes (e.g.
|
|
927
|
+
* range-on-filter and `in`-on-query) follow the algebra in the body
|
|
928
|
+
* JSDoc.
|
|
929
|
+
*
|
|
930
|
+
* Algorithm — group both wires by `field`, then for every field
|
|
931
|
+
* present in `indexFilterWire`:
|
|
932
|
+
*
|
|
933
|
+
* 1. Decode the filter's clause group into an {@link OperatorBundle}.
|
|
934
|
+
* "unknown-shape" → refuse implication conservatively.
|
|
935
|
+
* 2. The query MUST have at least one clause on that field —
|
|
936
|
+
* otherwise the query says nothing about that field and cannot
|
|
937
|
+
* possibly imply the filter's constraint.
|
|
938
|
+
* 3. Decode the query's clause group on the same field.
|
|
939
|
+
* 4. For each non-empty slot of the filter bundle, the query bundle
|
|
940
|
+
* must establish the constraint:
|
|
941
|
+
* - `eq` → query establishes equality (via its own `eq`).
|
|
942
|
+
* - `in` → query is contained in the set (via `eq` ∈ set or
|
|
943
|
+
* `in` ⊆ set).
|
|
944
|
+
* - `lo` / `hi` → query establishes the bound via `eq`, `in`
|
|
945
|
+
* (then min/max of the set), or its own `lo`/`hi` with the
|
|
946
|
+
* inclusivity rules in {@link lowerBoundImplies} /
|
|
947
|
+
* {@link upperBoundImplies}.
|
|
948
|
+
* Mixed types (e.g. number filter vs string query) refuse
|
|
949
|
+
* implication conservatively.
|
|
950
|
+
*
|
|
951
|
+
* Returns `true` iff every clause was satisfied. An empty
|
|
952
|
+
* `indexFilterWire` is vacuously implied by any `queryWire`.
|
|
953
|
+
*
|
|
954
|
+
* Soundness contract — when this function returns `true`,
|
|
955
|
+
* `matchesWire(queryWire, doc) ⇒ matchesWire(indexFilterWire, doc)` for
|
|
956
|
+
* any document `doc`. Tests pin this property; see
|
|
957
|
+
* `./query-planner-implies.test.ts`.
|
|
958
|
+
*/
|
|
959
|
+
const predicateImplies = (indexFilterWire, queryWire) => {
|
|
960
|
+
const filterGroups = groupByField(indexFilterWire);
|
|
961
|
+
const queryGroups = groupByField(queryWire);
|
|
962
|
+
for (const [field, filterClauses] of filterGroups) {
|
|
963
|
+
const filterBundle = decodeGroup(filterClauses);
|
|
964
|
+
if (filterBundle === "unknown-shape") return false;
|
|
965
|
+
const queryClauses = queryGroups.get(field);
|
|
966
|
+
if (queryClauses === void 0) return false;
|
|
967
|
+
const queryBundle = decodeGroup(queryClauses);
|
|
968
|
+
if (queryBundle === "unknown-shape") return false;
|
|
969
|
+
if (filterBundle.eq !== void 0) {
|
|
970
|
+
if (queryBundle.eq === void 0) return false;
|
|
971
|
+
if (!deepEqualDocumentValue(queryBundle.eq, filterBundle.eq)) return false;
|
|
972
|
+
continue;
|
|
973
|
+
}
|
|
974
|
+
if (filterBundle.in !== void 0) {
|
|
975
|
+
const set = filterBundle.in;
|
|
976
|
+
const contains = (v) => set.some((m) => deepEqualDocumentValue(m, v));
|
|
977
|
+
if (queryBundle.eq !== void 0) {
|
|
978
|
+
if (!contains(queryBundle.eq)) return false;
|
|
979
|
+
} else if (queryBundle.in !== void 0) {
|
|
980
|
+
for (const v of queryBundle.in) if (!contains(v)) return false;
|
|
981
|
+
} else return false;
|
|
982
|
+
continue;
|
|
983
|
+
}
|
|
984
|
+
if (filterBundle.lo !== void 0) {
|
|
985
|
+
if (!lowerBoundImplies(filterBundle.lo, loFromQuery(queryBundle))) return false;
|
|
986
|
+
}
|
|
987
|
+
if (filterBundle.hi !== void 0) {
|
|
988
|
+
if (!upperBoundImplies(filterBundle.hi, hiFromQuery(queryBundle))) return false;
|
|
989
|
+
}
|
|
990
|
+
}
|
|
991
|
+
return true;
|
|
992
|
+
};
|
|
993
|
+
/**
|
|
994
|
+
* Choose a query plan over the wire predicate + declared indexes.
|
|
995
|
+
* Pure function. The executor enforces the I/O semantics; the
|
|
996
|
+
* planner's only contract is "given these inputs, this is the
|
|
997
|
+
* routing decision."
|
|
998
|
+
*
|
|
999
|
+
* Algorithm:
|
|
1000
|
+
* 1. `wire === undefined` or empty → `no-predicate`.
|
|
1001
|
+
* 2. `indexes.length === 0` → `no-indexes-declared`.
|
|
1002
|
+
* 3. Partition wire clauses per field into:
|
|
1003
|
+
* - `equality[f] = v` from `eq` clauses.
|
|
1004
|
+
* - `rangeOps[f] = {lo, hi, loInclusive, hiInclusive}` from
|
|
1005
|
+
* one or more of `gt`/`gte`/`lt`/`lte` clauses on `f`.
|
|
1006
|
+
* - `inOps[f] = [...]` from a single `in` clause on `f`.
|
|
1007
|
+
* - Defensive: any field whose clause group mixes op-channels
|
|
1008
|
+
* (mostly impossible post-validation) is marked unroutable
|
|
1009
|
+
* and skipped — the executor's full-wire `matchesWire(...)`
|
|
1010
|
+
* post-fetch catches the residue automatically.
|
|
1011
|
+
* 4. If no equality / range / `in` candidates exist →
|
|
1012
|
+
* `predicate-uses-operators-only`.
|
|
1013
|
+
* 5. For each `def`, walk `def.on` left-to-right consuming
|
|
1014
|
+
* equality clauses for each indexed field. On the FIRST field
|
|
1015
|
+
* where the equality clause is absent, check whether a range
|
|
1016
|
+
* or `in` clause is available for that field — if so, that's
|
|
1017
|
+
* the "tail slot" of the walk.
|
|
1018
|
+
* 6. Score candidates by `(equalityPrefixLen, hasTailExtension)`.
|
|
1019
|
+
* Longest prefix wins; tail-extension breaks ties. If no
|
|
1020
|
+
* candidate consumed at least one field (equality OR
|
|
1021
|
+
* range/`in`): `no-matching-index`.
|
|
1022
|
+
* 7. `in` FAN-OUT GUARD: if the chosen plan's `in` slot has
|
|
1023
|
+
* `values.length > IN_FANOUT_THRESHOLD`, fall back to
|
|
1024
|
+
* `FullScanPlan{reason:"no-matching-index"}` — N sequential
|
|
1025
|
+
* LISTs cost more than a snapshot+log fold.
|
|
1026
|
+
*
|
|
1027
|
+
* The planner deliberately treats `def.on` as the LITERAL tuple of
|
|
1028
|
+
* field names — top-level only. Dotted paths are out of scope here
|
|
1029
|
+
* (the projector at `indexes.ts:projectIndexValues` is top-level-
|
|
1030
|
+
* only too).
|
|
1031
|
+
*
|
|
1032
|
+
* **Range/`in` is allowed only on the LAST indexed field beyond the
|
|
1033
|
+
* equality prefix** — on a composite `[a, b]`, a range on `a` with
|
|
1034
|
+
* equality on `b` is NOT contiguous under the key encoding (the `b`
|
|
1035
|
+
* slot sits to the right of the varying `a` slot). Clauses landing
|
|
1036
|
+
* outside the tail slot are simply left for the executor's full-
|
|
1037
|
+
* predicate re-check.
|
|
1038
|
+
*/
|
|
1039
|
+
const planQuery = (wire, indexes) => {
|
|
1040
|
+
if (wire === void 0 || wire.clauses.length === 0) return {
|
|
1041
|
+
kind: "full-scan",
|
|
1042
|
+
reason: "no-predicate"
|
|
1043
|
+
};
|
|
1044
|
+
if (indexes.length === 0) return {
|
|
1045
|
+
kind: "full-scan",
|
|
1046
|
+
reason: "no-indexes-declared"
|
|
1047
|
+
};
|
|
1048
|
+
const equality = /* @__PURE__ */ new Map();
|
|
1049
|
+
const rangeOps = /* @__PURE__ */ new Map();
|
|
1050
|
+
const inOps = /* @__PURE__ */ new Map();
|
|
1051
|
+
const unroutable = /* @__PURE__ */ new Set();
|
|
1052
|
+
const rangeAcc = /* @__PURE__ */ new Map();
|
|
1053
|
+
for (const clause of wire.clauses) {
|
|
1054
|
+
const field = clause.field;
|
|
1055
|
+
if (unroutable.has(field)) continue;
|
|
1056
|
+
if (clause.op === "eq") {
|
|
1057
|
+
if (inOps.has(field) || rangeAcc.has(field)) {
|
|
1058
|
+
unroutable.add(field);
|
|
1059
|
+
equality.delete(field);
|
|
1060
|
+
inOps.delete(field);
|
|
1061
|
+
rangeAcc.delete(field);
|
|
1062
|
+
continue;
|
|
1063
|
+
}
|
|
1064
|
+
equality.set(field, clause.value);
|
|
1065
|
+
} else if (clause.op === "in") {
|
|
1066
|
+
if (equality.has(field) || rangeAcc.has(field) || inOps.has(field)) {
|
|
1067
|
+
unroutable.add(field);
|
|
1068
|
+
equality.delete(field);
|
|
1069
|
+
inOps.delete(field);
|
|
1070
|
+
rangeAcc.delete(field);
|
|
1071
|
+
continue;
|
|
1072
|
+
}
|
|
1073
|
+
if (!Array.isArray(clause.value)) {
|
|
1074
|
+
unroutable.add(field);
|
|
1075
|
+
continue;
|
|
1076
|
+
}
|
|
1077
|
+
inOps.set(field, clause.value);
|
|
1078
|
+
} else {
|
|
1079
|
+
if (equality.has(field) || inOps.has(field)) {
|
|
1080
|
+
unroutable.add(field);
|
|
1081
|
+
equality.delete(field);
|
|
1082
|
+
inOps.delete(field);
|
|
1083
|
+
rangeAcc.delete(field);
|
|
1084
|
+
continue;
|
|
1085
|
+
}
|
|
1086
|
+
const acc = rangeAcc.get(field) ?? {
|
|
1087
|
+
loInclusive: false,
|
|
1088
|
+
hiInclusive: false
|
|
1089
|
+
};
|
|
1090
|
+
const v = clause.value;
|
|
1091
|
+
if (clause.op === "gte") {
|
|
1092
|
+
if (acc.lo === void 0 || v > acc.lo) {
|
|
1093
|
+
acc.lo = v;
|
|
1094
|
+
acc.loInclusive = true;
|
|
1095
|
+
} else if (v === acc.lo && !acc.loInclusive) {}
|
|
1096
|
+
} else if (clause.op === "gt") {
|
|
1097
|
+
if (acc.lo === void 0 || v > acc.lo) {
|
|
1098
|
+
acc.lo = v;
|
|
1099
|
+
acc.loInclusive = false;
|
|
1100
|
+
} else if (v === acc.lo) acc.loInclusive = false;
|
|
1101
|
+
} else if (clause.op === "lte") {
|
|
1102
|
+
if (acc.hi === void 0 || v < acc.hi) {
|
|
1103
|
+
acc.hi = v;
|
|
1104
|
+
acc.hiInclusive = true;
|
|
1105
|
+
}
|
|
1106
|
+
} else if (clause.op === "lt") {
|
|
1107
|
+
if (acc.hi === void 0 || v < acc.hi) {
|
|
1108
|
+
acc.hi = v;
|
|
1109
|
+
acc.hiInclusive = false;
|
|
1110
|
+
} else if (v === acc.hi) acc.hiInclusive = false;
|
|
1111
|
+
}
|
|
1112
|
+
rangeAcc.set(field, acc);
|
|
1113
|
+
}
|
|
1114
|
+
}
|
|
1115
|
+
for (const [field, acc] of rangeAcc) rangeOps.set(field, {
|
|
1116
|
+
...acc.lo !== void 0 ? { lo: acc.lo } : {},
|
|
1117
|
+
...acc.hi !== void 0 ? { hi: acc.hi } : {},
|
|
1118
|
+
loInclusive: acc.loInclusive,
|
|
1119
|
+
hiInclusive: acc.hiInclusive
|
|
1120
|
+
});
|
|
1121
|
+
if (equality.size === 0 && rangeOps.size === 0 && inOps.size === 0) return {
|
|
1122
|
+
kind: "full-scan",
|
|
1123
|
+
reason: "predicate-uses-operators-only"
|
|
1124
|
+
};
|
|
1125
|
+
const candidates = [];
|
|
1126
|
+
for (let defIndex = 0; defIndex < indexes.length; defIndex++) {
|
|
1127
|
+
const def = indexes[defIndex];
|
|
1128
|
+
const tuple = typeof def.on === "string" ? [def.on] : def.on;
|
|
1129
|
+
const equalityKeys = [];
|
|
1130
|
+
let tail;
|
|
1131
|
+
for (let i = 0; i < tuple.length; i++) {
|
|
1132
|
+
const field = tuple[i];
|
|
1133
|
+
const v = equality.get(field);
|
|
1134
|
+
if (v !== void 0) {
|
|
1135
|
+
equalityKeys.push(v);
|
|
1136
|
+
continue;
|
|
1137
|
+
}
|
|
1138
|
+
const range = rangeOps.get(field);
|
|
1139
|
+
if (range !== void 0) tail = {
|
|
1140
|
+
kind: "range",
|
|
1141
|
+
field,
|
|
1142
|
+
info: range
|
|
1143
|
+
};
|
|
1144
|
+
else {
|
|
1145
|
+
const inVals = inOps.get(field);
|
|
1146
|
+
if (inVals !== void 0) tail = {
|
|
1147
|
+
kind: "in",
|
|
1148
|
+
field,
|
|
1149
|
+
values: inVals
|
|
1150
|
+
};
|
|
1151
|
+
}
|
|
1152
|
+
break;
|
|
1153
|
+
}
|
|
1154
|
+
const candidateLen = equalityKeys.length + (tail !== void 0 ? 1 : 0);
|
|
1155
|
+
if (candidateLen === 0) continue;
|
|
1156
|
+
candidates.push({
|
|
1157
|
+
def,
|
|
1158
|
+
defIndex,
|
|
1159
|
+
prefixLen: candidateLen,
|
|
1160
|
+
equalityKeys,
|
|
1161
|
+
...tail !== void 0 ? { tail } : {}
|
|
1162
|
+
});
|
|
1163
|
+
}
|
|
1164
|
+
if (candidates.length === 0) return {
|
|
1165
|
+
kind: "full-scan",
|
|
1166
|
+
reason: "no-matching-index"
|
|
1167
|
+
};
|
|
1168
|
+
const rank = (c) => {
|
|
1169
|
+
if (c.def.predicate === void 0) return 1;
|
|
1170
|
+
return predicateImplies(c.def.predicate, wire) ? 0 : 2;
|
|
1171
|
+
};
|
|
1172
|
+
candidates.sort((a, b) => {
|
|
1173
|
+
const aRank = rank(a);
|
|
1174
|
+
const bRank = rank(b);
|
|
1175
|
+
if (aRank !== bRank) return aRank - bRank;
|
|
1176
|
+
if (b.prefixLen !== a.prefixLen) return b.prefixLen - a.prefixLen;
|
|
1177
|
+
return a.defIndex - b.defIndex;
|
|
1178
|
+
});
|
|
1179
|
+
const best = candidates[0];
|
|
1180
|
+
if (best.tail !== void 0 && best.tail.kind === "in") {
|
|
1181
|
+
if (best.tail.values.length > 50) return {
|
|
1182
|
+
kind: "full-scan",
|
|
1183
|
+
reason: "no-matching-index"
|
|
1184
|
+
};
|
|
1185
|
+
}
|
|
1186
|
+
return {
|
|
1187
|
+
kind: "index-walk",
|
|
1188
|
+
indexName: best.def.name,
|
|
1189
|
+
equalityKeys: best.equalityKeys,
|
|
1190
|
+
...best.tail !== void 0 && best.tail.kind === "range" ? { rangeOn: {
|
|
1191
|
+
field: best.tail.field,
|
|
1192
|
+
...best.tail.info.lo !== void 0 ? { lo: best.tail.info.lo } : {},
|
|
1193
|
+
...best.tail.info.hi !== void 0 ? { hi: best.tail.info.hi } : {},
|
|
1194
|
+
loInclusive: best.tail.info.loInclusive,
|
|
1195
|
+
hiInclusive: best.tail.info.hiInclusive
|
|
1196
|
+
} } : {},
|
|
1197
|
+
...best.tail !== void 0 && best.tail.kind === "in" ? { inOn: {
|
|
1198
|
+
field: best.tail.field,
|
|
1199
|
+
values: best.tail.values
|
|
1200
|
+
} } : {}
|
|
1201
|
+
};
|
|
1202
|
+
};
|
|
1203
|
+
//#endregion
|
|
1204
|
+
//#region packages/server/src/schema.ts
|
|
1205
|
+
/**
|
|
1206
|
+
* Schema-validator runtime helper for `Db.insert` / `Query.update` /
|
|
1207
|
+
* `Collection.replace` boundary checks.
|
|
1208
|
+
*
|
|
1209
|
+
* The `SchemaValidator` / `SchemaIssue` TYPES live in
|
|
1210
|
+
* `@baerly/protocol` (cross-platform). This module owns the runtime
|
|
1211
|
+
* helper `validateOrThrow` that runs a validator and raises a
|
|
1212
|
+
* `BaerlyError{code:"SchemaError"}` on failure.
|
|
1213
|
+
*
|
|
1214
|
+
* @example
|
|
1215
|
+
* ```ts
|
|
1216
|
+
* import { z } from "zod";
|
|
1217
|
+
* import { defineConfig } from "@gusto/baerly-storage/config";
|
|
1218
|
+
*
|
|
1219
|
+
* const Ticket = z.object({
|
|
1220
|
+
* _id: z.string(),
|
|
1221
|
+
* status: z.enum(["open", "closed"]),
|
|
1222
|
+
* title: z.string().min(1),
|
|
1223
|
+
* });
|
|
1224
|
+
*
|
|
1225
|
+
* export default defineConfig({
|
|
1226
|
+
* collections: {
|
|
1227
|
+
* tickets: { schema: Ticket },
|
|
1228
|
+
* },
|
|
1229
|
+
* });
|
|
1230
|
+
* ```
|
|
1231
|
+
*/
|
|
1232
|
+
/**
|
|
1233
|
+
* Run a validator and throw `BaerlyError{code:"SchemaError"}` on failure.
|
|
1234
|
+
* On success returns the validator's output (which for transforming
|
|
1235
|
+
* validators may differ from the input).
|
|
1236
|
+
*
|
|
1237
|
+
* Field paths are normalised to `(string | number)[]` so the wire shape
|
|
1238
|
+
* is JSON-clean. Symbol keys (rare; StandardSchemaV1 permits them) are
|
|
1239
|
+
* coerced to `String(sym)` — we never emit `symbol` on the wire.
|
|
1240
|
+
*
|
|
1241
|
+
* The thrown error's `message` carries a one-line summary
|
|
1242
|
+
* (`"<collection>.<verb>: <issuesCount> field(s) failed validation: <first>"`)
|
|
1243
|
+
* for stderr-readable logs; the structured `issues` are on `.issues`.
|
|
1244
|
+
*/
|
|
1245
|
+
const validateOrThrow = async (schema, candidate, context) => {
|
|
1246
|
+
const result = await schema["~standard"].validate(candidate);
|
|
1247
|
+
if (result.issues === void 0) return result.value;
|
|
1248
|
+
const issues = result.issues.map((i) => ({
|
|
1249
|
+
path: (i.path ?? []).map((p) => {
|
|
1250
|
+
const raw = typeof p === "object" && p !== null && "key" in p ? p.key : p;
|
|
1251
|
+
return typeof raw === "number" ? raw : String(raw);
|
|
1252
|
+
}),
|
|
1253
|
+
message: i.message
|
|
1254
|
+
}));
|
|
1255
|
+
const first = issues[0];
|
|
1256
|
+
const summary = first === void 0 ? "schema validation failed (no issues reported)" : `${first.path.length === 0 ? "<root>" : first.path.join(".")}: ${first.message}`;
|
|
1257
|
+
throw new BaerlyError("SchemaError", `${context.collection}.${context.verb}: ${issues.length} field${issues.length === 1 ? "" : "s"} failed validation: ${summary}`, void 0, issues);
|
|
1258
|
+
};
|
|
1259
|
+
//#endregion
|
|
1260
|
+
//#region packages/server/src/query.ts
|
|
1261
|
+
/**
|
|
1262
|
+
* Read engine + mutation terminals: `Query<T>` builder, the
|
|
1263
|
+
* three read terminals (`first`, `all`, `count`) that fold the log
|
|
1264
|
+
* under a fresh `current.json` snapshot, and the four mutation
|
|
1265
|
+
* terminals (`insert`, `update`, `replace`, `delete`) that each
|
|
1266
|
+
* compile to one or more `Writer.commit()` round-trips.
|
|
1267
|
+
*
|
|
1268
|
+
* Every modifier (`.where` / `.order` / `.limit`) returns a NEW
|
|
1269
|
+
* `Query<T>` carrying merged frozen state — the input state is never
|
|
1270
|
+
* mutated. Identity inequality between the original and the returned
|
|
1271
|
+
* builder is intentional: callers cannot share a chain.
|
|
1272
|
+
*
|
|
1273
|
+
* `.where()` AND-merges through `mergePredicateWires` (clause-level
|
|
1274
|
+
* AND on the normalised wire form).
|
|
1275
|
+
* `.order()` and `.limit()` are last-call-wins (state replace).
|
|
1276
|
+
*
|
|
1277
|
+
* Each terminal reads `current.json` FRESH and walks `[0, next_seq)`
|
|
1278
|
+
* directly — no cache, no `list()` round-trip. Per the multi-
|
|
1279
|
+
* instance rules, every read sees a fresh CAS snapshot.
|
|
1280
|
+
*
|
|
1281
|
+
* Mutation terminals are SINGLE-ATTEMPT per call site. CAS contention
|
|
1282
|
+
* retries (up to 8 attempts) live inside `Writer.commit()`; the
|
|
1283
|
+
* verbs do NOT add their own retry loop. On retry-budget exhaustion
|
|
1284
|
+
* `commit()` throws `BaerlyError{code:"Conflict"}` and the verb
|
|
1285
|
+
* surfaces it unchanged — the caller's option is to wrap in
|
|
1286
|
+
* `db.transaction(...)`.
|
|
1287
|
+
*
|
|
1288
|
+
* @see ../../../docs/spec/sync-protocol.md
|
|
1289
|
+
*/
|
|
1290
|
+
/**
|
|
1291
|
+
* Serialise a {@link CurrentJson} head into the wire cursor format
|
|
1292
|
+
* `"<snapshot>@<next_seq>"`. `null` snapshots stringify as
|
|
1293
|
+
* {@link MANIFEST_POINTER_EMPTY_SNAPSHOT} so the cursor is never the
|
|
1294
|
+
* empty string.
|
|
1295
|
+
*
|
|
1296
|
+
* @internal — exported for `query.test.ts`.
|
|
1297
|
+
*/
|
|
1298
|
+
const serializeManifestPointer = (json) => `${json.snapshot ?? "none"}@${json.next_seq}`;
|
|
1299
|
+
/**
|
|
1300
|
+
* Returns the id iff `wire` carries exactly one clause and that
|
|
1301
|
+
* clause is `{op:"eq", field:"_id", value:<string>}` — the shape
|
|
1302
|
+
* `runRead` short-circuits to a single `Map.get`. Any other shape
|
|
1303
|
+
* (multi-clause, non-`eq` op, non-`_id` field, non-string value)
|
|
1304
|
+
* returns `undefined` and falls through to the scan path.
|
|
1305
|
+
*
|
|
1306
|
+
* Kernel-internal `_id`-shaped wires (built by `byId`,
|
|
1307
|
+
* `runByIdWithMeta`, `runInsert`) bypass the wire validator by
|
|
1308
|
+
* design (`_id` at the root is a wire-only rejection); this
|
|
1309
|
+
* recogniser matches the same shape so the fast-path stays
|
|
1310
|
+
* symmetric.
|
|
1311
|
+
*
|
|
1312
|
+
* @internal
|
|
1313
|
+
*/
|
|
1314
|
+
const singleIdFromPredicate = (wire) => {
|
|
1315
|
+
if (wire === void 0) return;
|
|
1316
|
+
if (wire.clauses.length !== 1) return;
|
|
1317
|
+
const clause = wire.clauses[0];
|
|
1318
|
+
if (clause.op !== "eq" || clause.field !== "_id") return;
|
|
1319
|
+
return typeof clause.value === "string" ? clause.value : void 0;
|
|
1320
|
+
};
|
|
1321
|
+
/**
|
|
1322
|
+
* Build a `Query<T>` from a context + frozen state. Every modifier
|
|
1323
|
+
* returns a NEW `Query<T>` carrying merged state — the input state
|
|
1324
|
+
* is never mutated. Identity inequality with the input chain is
|
|
1325
|
+
* intentional.
|
|
1326
|
+
*
|
|
1327
|
+
* Validation happens at the public seams — `Query.where(p)`
|
|
1328
|
+
* normalises + validates the incoming fragment before merging into
|
|
1329
|
+
* `state.wire`. By the time `makeQuery` is reached from elsewhere
|
|
1330
|
+
* (`Collection.where`, `runAllWithMeta`, kernel-internal `_id`-shaped
|
|
1331
|
+
* wires from `byId` / `runByIdWithMeta` / `runInsert`), the wire is
|
|
1332
|
+
* already trusted.
|
|
1333
|
+
*
|
|
1334
|
+
* @example
|
|
1335
|
+
* ```ts
|
|
1336
|
+
* const q = makeQuery<Ticket>(ctx, { wire: undefined, order: undefined, limit: undefined });
|
|
1337
|
+
* const open = await q.where({ status: "open" }).order({ created_at: "desc" }).limit(10).all();
|
|
1338
|
+
* ```
|
|
1339
|
+
*
|
|
1340
|
+
* @internal
|
|
1341
|
+
*/
|
|
1342
|
+
const makeQuery = (ctx, state) => {
|
|
1343
|
+
return {
|
|
1344
|
+
where: (p) => {
|
|
1345
|
+
const incoming = normalizePredicateArg(p);
|
|
1346
|
+
validateWire(incoming);
|
|
1347
|
+
return makeQuery(ctx, {
|
|
1348
|
+
...state,
|
|
1349
|
+
wire: state.wire === void 0 ? incoming : mergePredicateWires(state.wire, incoming)
|
|
1350
|
+
});
|
|
1351
|
+
},
|
|
1352
|
+
order: (s) => makeQuery(ctx, {
|
|
1353
|
+
...state,
|
|
1354
|
+
order: s
|
|
1355
|
+
}),
|
|
1356
|
+
limit: (n) => makeQuery(ctx, {
|
|
1357
|
+
...state,
|
|
1358
|
+
limit: n
|
|
1359
|
+
}),
|
|
1360
|
+
first: async () => {
|
|
1361
|
+
const { rows } = await runRead(ctx, {
|
|
1362
|
+
...state,
|
|
1363
|
+
limit: 1
|
|
1364
|
+
});
|
|
1365
|
+
return rows[0];
|
|
1366
|
+
},
|
|
1367
|
+
all: async () => {
|
|
1368
|
+
return (await runRead(ctx, state)).rows;
|
|
1369
|
+
},
|
|
1370
|
+
count: async () => {
|
|
1371
|
+
return (await runRead(ctx, state)).rows.length;
|
|
1372
|
+
},
|
|
1373
|
+
update: (patch) => runUpdate(ctx, state, patch),
|
|
1374
|
+
delete: () => runDelete(ctx, state)
|
|
1375
|
+
};
|
|
1376
|
+
};
|
|
1377
|
+
/**
|
|
1378
|
+
* Server-internal read entry surfacing the manifest-pointer cursor
|
|
1379
|
+
* and freshness flag alongside the materialised rows. The HTTP
|
|
1380
|
+
* router calls this directly so the read-response handler can pack
|
|
1381
|
+
* `_meta` onto the envelope; the public `Query<T>` terminals
|
|
1382
|
+
* destructure the rows out and discard the cursor to keep the
|
|
1383
|
+
* locked interface signature. Single-row routes (`GET /v1/c/:collection/:id`)
|
|
1384
|
+
* call this with `limit:1` and pick `rows[0]`.
|
|
1385
|
+
*
|
|
1386
|
+
* `state.wire` is assumed already validated — the public seam
|
|
1387
|
+
* (`Query.where(p)` → `normalizePredicateArg` → `validateWire`) is
|
|
1388
|
+
* the wire-arrival contract surface. Router callers parsing
|
|
1389
|
+
* `?where=` run `validateWire` themselves inside `parseWhereParam`,
|
|
1390
|
+
* keeping a single validation pass per wire.
|
|
1391
|
+
*
|
|
1392
|
+
* @internal
|
|
1393
|
+
*/
|
|
1394
|
+
const runAllWithMeta = (ctx, state) => {
|
|
1395
|
+
return runRead(ctx, state);
|
|
1396
|
+
};
|
|
1397
|
+
/**
|
|
1398
|
+
* By-id read entry surfacing the same `ReadResult<T>` shape as
|
|
1399
|
+
* {@link runAllWithMeta} so the HTTP router can preserve the
|
|
1400
|
+
* `_meta` wire envelope while routing through the PK-lookup
|
|
1401
|
+
* fast-path. Mirrors {@link runAllWithMeta}'s signature; the
|
|
1402
|
+
* wire is built internally as a single-clause `{op:"eq",
|
|
1403
|
+
* field:"_id", value:id}` shape (same form as the `byId` helper in
|
|
1404
|
+
* `./collection.ts` and the `runInsert` duplicate-collision check)
|
|
1405
|
+
* which routes through `runRead`'s `singleIdFromPredicate`
|
|
1406
|
+
* short-circuit automatically.
|
|
1407
|
+
*
|
|
1408
|
+
* Bypasses {@link validateWire} — the wire is kernel-constructed,
|
|
1409
|
+
* never wire-submitted, so it would always pass the structural
|
|
1410
|
+
* rules. Skipping the validator also keeps this helper usable
|
|
1411
|
+
* from kernel-internal sites (`Collection<T>.get` etc.) without
|
|
1412
|
+
* tripping the wire-only rule that bans top-level `_id`.
|
|
1413
|
+
*
|
|
1414
|
+
* @internal — router uses this to preserve `_meta` envelope;
|
|
1415
|
+
* mirrors {@link runAllWithMeta} and {@link Collection.get}.
|
|
1416
|
+
*/
|
|
1417
|
+
const runByIdWithMeta = (ctx, id) => {
|
|
1418
|
+
return runRead(ctx, {
|
|
1419
|
+
wire: { clauses: [{
|
|
1420
|
+
op: "eq",
|
|
1421
|
+
field: "_id",
|
|
1422
|
+
value: id
|
|
1423
|
+
}] },
|
|
1424
|
+
order: void 0,
|
|
1425
|
+
limit: 1
|
|
1426
|
+
});
|
|
1427
|
+
};
|
|
1428
|
+
/**
|
|
1429
|
+
* Build a fresh `Writer` bound to this collection's `current.json`.
|
|
1430
|
+
* Construction is zero-I/O (writer.ts:160) so we mint one per
|
|
1431
|
+
* `commit()` rather than caching on the chain — same writer object
|
|
1432
|
+
* shared across N commits would inherit retry-budget state we want
|
|
1433
|
+
* fresh per call.
|
|
1434
|
+
*/
|
|
1435
|
+
const writerFor = (ctx) => new Writer({
|
|
1436
|
+
storage: ctx.storage,
|
|
1437
|
+
currentJsonKey: `${ctx.collectionPrefix}/current.json`,
|
|
1438
|
+
options: { indexes: ctx.indexes }
|
|
1439
|
+
});
|
|
1440
|
+
/**
|
|
1441
|
+
* `Collection.insert` / `Query.insert` implementation. Mints a UUIDv7 `_id`
|
|
1442
|
+
* when the caller omits it (or supplies an empty string); honours a
|
|
1443
|
+
* caller-supplied non-empty `_id`. On collision (the materialised
|
|
1444
|
+
* collection already carries that `_id`) throws
|
|
1445
|
+
* `BaerlyError{code:"Conflict"}` BEFORE issuing the writer round-trip
|
|
1446
|
+
* — matches the locked `Collection.insert` contract
|
|
1447
|
+
* (`packages/protocol/src/collection-api.ts:123–125`).
|
|
1448
|
+
*
|
|
1449
|
+
* The emitted `LogEntry` has `op:"I"` and `new === patch === {...doc, _id}`
|
|
1450
|
+
* (today's per-doc-replace model — `packages/protocol/src/log.ts:67–72`).
|
|
1451
|
+
*
|
|
1452
|
+
* @throws BaerlyError code="Conflict" — `_id` collision (pre-commit check) or
|
|
1453
|
+
* CAS retry budget exhausted inside `Writer.commit()`.
|
|
1454
|
+
* @throws BaerlyError code="SchemaError" — from the per-collection
|
|
1455
|
+
* `SchemaValidator` threaded via {@link Db.collectionReadContext}.
|
|
1456
|
+
*
|
|
1457
|
+
* @internal — exported for `Collection.insert` in `./collection.ts` to delegate
|
|
1458
|
+
* without duplicating the auto-id / collision-check /
|
|
1459
|
+
* commit pipeline.
|
|
1460
|
+
*/
|
|
1461
|
+
const runInsert = async (ctx, doc) => {
|
|
1462
|
+
const supplied = doc["_id"];
|
|
1463
|
+
const _id = typeof supplied === "string" && supplied.length > 0 ? supplied : uuidv7();
|
|
1464
|
+
const body = {
|
|
1465
|
+
...doc,
|
|
1466
|
+
_id
|
|
1467
|
+
};
|
|
1468
|
+
if (ctx.schema !== void 0) await validateOrThrow(ctx.schema, body, {
|
|
1469
|
+
collection: ctx.collectionName,
|
|
1470
|
+
verb: "insert"
|
|
1471
|
+
});
|
|
1472
|
+
if ((await runRead(ctx, {
|
|
1473
|
+
wire: { clauses: [{
|
|
1474
|
+
op: "eq",
|
|
1475
|
+
field: "_id",
|
|
1476
|
+
value: _id
|
|
1477
|
+
}] },
|
|
1478
|
+
order: void 0,
|
|
1479
|
+
limit: 1
|
|
1480
|
+
})).rows.length > 0) throw new BaerlyError("Conflict", `Query.insert: _id ${JSON.stringify(_id)} already exists in collection ${JSON.stringify(ctx.collectionName)}`);
|
|
1481
|
+
if (ctx.txCtx !== void 0) {
|
|
1482
|
+
assertTxBindMatches(ctx);
|
|
1483
|
+
ctx.txCtx.mutations.push({
|
|
1484
|
+
op: "I",
|
|
1485
|
+
docId: _id,
|
|
1486
|
+
body
|
|
1487
|
+
});
|
|
1488
|
+
return { _id };
|
|
1489
|
+
}
|
|
1490
|
+
await writerFor(ctx).commit({
|
|
1491
|
+
op: "I",
|
|
1492
|
+
collection: ctx.collectionName,
|
|
1493
|
+
docId: _id,
|
|
1494
|
+
body
|
|
1495
|
+
});
|
|
1496
|
+
return { _id };
|
|
1497
|
+
};
|
|
1498
|
+
/**
|
|
1499
|
+
* `Query.update` implementation. Materialises the predicate/order/
|
|
1500
|
+
* limit-filtered match set, applies RFC 7386 `merge(prev, patch)`
|
|
1501
|
+
* per row, and emits one `op:"U"` `LogEntry` per affected `doc_id`
|
|
1502
|
+
* — one `Writer.commit()` round-trip apiece.
|
|
1503
|
+
*
|
|
1504
|
+
* Atomicity is per row, not across the N-row batch. The locked
|
|
1505
|
+
* contract (`packages/protocol/src/collection-api.ts:178–184`) is explicit on
|
|
1506
|
+
* this: all-or-nothing across multiple rows is what
|
|
1507
|
+
* `db.transaction(...)` exists to deliver.
|
|
1508
|
+
*
|
|
1509
|
+
* `replica_identity` defaults to `PATCH_ONLY` for every collection
|
|
1510
|
+
* today — emitted `U` entries carry `{ new, patch }` (equal) and
|
|
1511
|
+
* neither `old` nor `key_old`. Consumers rebuilding pre-images
|
|
1512
|
+
* under `PATCH_ONLY` need to maintain a shadow table — see
|
|
1513
|
+
* `packages/protocol/src/log.ts:102–118`.
|
|
1514
|
+
*
|
|
1515
|
+
* @throws BaerlyError code="Conflict" — any one row's CAS retry budget
|
|
1516
|
+
* exhausted inside `Writer.commit()`. The partial-progress
|
|
1517
|
+
* `modified` count is NOT returned in that case.
|
|
1518
|
+
* @throws BaerlyError code="SchemaError" — `merge(prev, patch)` produced
|
|
1519
|
+
* `undefined` (defensive — `Partial<T>` cannot be `null` at the
|
|
1520
|
+
* root in the type system).
|
|
1521
|
+
*/
|
|
1522
|
+
const runUpdate = async (ctx, state, patch) => {
|
|
1523
|
+
const { rows } = await runRead(ctx, state);
|
|
1524
|
+
const tx = ctx.txCtx;
|
|
1525
|
+
if (tx !== void 0) assertTxBindMatches(ctx);
|
|
1526
|
+
let modified = 0;
|
|
1527
|
+
for (const doc of rows) {
|
|
1528
|
+
const merged = merge(doc, patch);
|
|
1529
|
+
if (merged === void 0) throw new BaerlyError("SchemaError", `Query.update: merge produced undefined for doc ${JSON.stringify(doc["_id"])}`);
|
|
1530
|
+
if (ctx.schema !== void 0) await validateOrThrow(ctx.schema, merged, {
|
|
1531
|
+
collection: ctx.collectionName,
|
|
1532
|
+
verb: "update"
|
|
1533
|
+
});
|
|
1534
|
+
if (tx !== void 0) tx.mutations.push({
|
|
1535
|
+
op: "U",
|
|
1536
|
+
docId: String(doc["_id"]),
|
|
1537
|
+
body: merged
|
|
1538
|
+
});
|
|
1539
|
+
else await writerFor(ctx).commit({
|
|
1540
|
+
op: "U",
|
|
1541
|
+
collection: ctx.collectionName,
|
|
1542
|
+
docId: String(doc["_id"]),
|
|
1543
|
+
body: merged
|
|
1544
|
+
});
|
|
1545
|
+
modified++;
|
|
1546
|
+
}
|
|
1547
|
+
return { modified };
|
|
1548
|
+
};
|
|
1549
|
+
/**
|
|
1550
|
+
* `Collection.replace` implementation. Existence check via `runRead` over
|
|
1551
|
+
* a `byId`-shaped wire so the `singleIdFromPredicate` PK fast path
|
|
1552
|
+
* (`Map.get`) fires and any transaction-buffered insert of `id` is
|
|
1553
|
+
* visible. Missing row → `NotFound` directly (no Conflict-string
|
|
1554
|
+
* indirection through the router). Present row → emit a single
|
|
1555
|
+
* `op:"U"` `LogEntry` carrying `doc` as the post-image, with `_id`
|
|
1556
|
+
* forced to the requested `id` so doc identity is preserved across
|
|
1557
|
+
* replaces even if the supplied `doc._id` differs.
|
|
1558
|
+
*
|
|
1559
|
+
* @throws BaerlyError code="NotFound" — no row exists at `id`.
|
|
1560
|
+
* @throws BaerlyError code="SchemaError" — post-image rejected by
|
|
1561
|
+
* the collection's bound validator.
|
|
1562
|
+
* @throws BaerlyError code="Conflict" — writer CAS retry budget
|
|
1563
|
+
* exhausted.
|
|
1564
|
+
*/
|
|
1565
|
+
const runReplaceById = async (ctx, id, doc) => {
|
|
1566
|
+
const { rows } = await runRead(ctx, {
|
|
1567
|
+
wire: { clauses: [{
|
|
1568
|
+
op: "eq",
|
|
1569
|
+
field: "_id",
|
|
1570
|
+
value: id
|
|
1571
|
+
}] },
|
|
1572
|
+
order: void 0,
|
|
1573
|
+
limit: void 0
|
|
1574
|
+
});
|
|
1575
|
+
if (rows.length === 0) throw new BaerlyError("NotFound", `No such row: ${id}`);
|
|
1576
|
+
const body = {
|
|
1577
|
+
...doc,
|
|
1578
|
+
_id: id
|
|
1579
|
+
};
|
|
1580
|
+
if (ctx.schema !== void 0) await validateOrThrow(ctx.schema, body, {
|
|
1581
|
+
collection: ctx.collectionName,
|
|
1582
|
+
verb: "replace"
|
|
1583
|
+
});
|
|
1584
|
+
if (ctx.txCtx !== void 0) {
|
|
1585
|
+
assertTxBindMatches(ctx);
|
|
1586
|
+
ctx.txCtx.mutations.push({
|
|
1587
|
+
op: "U",
|
|
1588
|
+
docId: id,
|
|
1589
|
+
body
|
|
1590
|
+
});
|
|
1591
|
+
return;
|
|
1592
|
+
}
|
|
1593
|
+
await writerFor(ctx).commit({
|
|
1594
|
+
op: "U",
|
|
1595
|
+
collection: ctx.collectionName,
|
|
1596
|
+
docId: id,
|
|
1597
|
+
body
|
|
1598
|
+
});
|
|
1599
|
+
};
|
|
1600
|
+
/**
|
|
1601
|
+
* `Query.delete` implementation. Tombstones every matched row with a
|
|
1602
|
+
* single `op:"D"` `LogEntry` per `doc_id`. `replica_identity` defaults
|
|
1603
|
+
* to `PATCH_ONLY`, so emitted `D` entries carry neither `new`/`patch`
|
|
1604
|
+
* nor `old`/`key_old`.
|
|
1605
|
+
* Consumers rebuilding pre-images under `PATCH_ONLY` need to
|
|
1606
|
+
* maintain a shadow table — see `packages/protocol/src/log.ts:102–118`.
|
|
1607
|
+
*
|
|
1608
|
+
* Atomicity is per row, not across the N-row batch — same shape as
|
|
1609
|
+
* `Query.update`. `db.transaction(...)` is where all-or-nothing
|
|
1610
|
+
* semantics live.
|
|
1611
|
+
*
|
|
1612
|
+
* @throws BaerlyError code="Conflict" — any one row's CAS retry budget
|
|
1613
|
+
* exhausted. The partial-progress `deleted` count is NOT returned
|
|
1614
|
+
* in that case.
|
|
1615
|
+
*/
|
|
1616
|
+
const runDelete = async (ctx, state) => {
|
|
1617
|
+
const { rows } = await runRead(ctx, state);
|
|
1618
|
+
const tx = ctx.txCtx;
|
|
1619
|
+
if (tx !== void 0) assertTxBindMatches(ctx);
|
|
1620
|
+
let deleted = 0;
|
|
1621
|
+
for (const doc of rows) {
|
|
1622
|
+
if (tx !== void 0) tx.mutations.push({
|
|
1623
|
+
op: "D",
|
|
1624
|
+
docId: String(doc["_id"])
|
|
1625
|
+
});
|
|
1626
|
+
else await writerFor(ctx).commit({
|
|
1627
|
+
op: "D",
|
|
1628
|
+
collection: ctx.collectionName,
|
|
1629
|
+
docId: String(doc["_id"])
|
|
1630
|
+
});
|
|
1631
|
+
deleted++;
|
|
1632
|
+
}
|
|
1633
|
+
return { deleted };
|
|
1634
|
+
};
|
|
1635
|
+
/**
|
|
1636
|
+
* Runtime guard for the txCtx-Collection-name binding. The type system
|
|
1637
|
+
* already prevents the legitimate path (the body callback gets one
|
|
1638
|
+
* `Collection<T>`, no `Db`), so this only catches a bug where a stale
|
|
1639
|
+
* `Query<T>` outlives its `Collection<T>` and is somehow re-attached to a
|
|
1640
|
+
* transaction over a different collection.
|
|
1641
|
+
*
|
|
1642
|
+
* @throws BaerlyError code="Internal" — txCtx ↔ Collection name mismatch.
|
|
1643
|
+
*/
|
|
1644
|
+
const assertTxBindMatches = (ctx) => {
|
|
1645
|
+
if (ctx.txCtx === void 0) return;
|
|
1646
|
+
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)}`);
|
|
1647
|
+
};
|
|
1648
|
+
/**
|
|
1649
|
+
* Load `current.json` fresh, walk `[0, next_seq)` in parallel, fold
|
|
1650
|
+
* per-`doc_id`, then apply predicate / order / limit in memory.
|
|
1651
|
+
*
|
|
1652
|
+
* Error mapping:
|
|
1653
|
+
* - `current.json` missing → empty result (collection not provisioned).
|
|
1654
|
+
* - `current.json` malformed → `InvalidResponse` (from `readCurrentJson`).
|
|
1655
|
+
* - log entry missing in `[0, next_seq)` → `Internal`.
|
|
1656
|
+
* - log entry malformed → `InvalidResponse`.
|
|
1657
|
+
*/
|
|
1658
|
+
const runRead = async (ctx, state) => {
|
|
1659
|
+
const currentJsonKey = `${ctx.collectionPrefix}/current.json`;
|
|
1660
|
+
const head = await readCurrentJson(ctx.storage, currentJsonKey);
|
|
1661
|
+
const manifestPointer = head === null ? `${MANIFEST_POINTER_EMPTY_SNAPSHOT}@0` : serializeManifestPointer(head.json);
|
|
1662
|
+
const fresh = true;
|
|
1663
|
+
if (head === null) return {
|
|
1664
|
+
rows: [],
|
|
1665
|
+
manifestPointer,
|
|
1666
|
+
fresh
|
|
1667
|
+
};
|
|
1668
|
+
const plan = planQuery(state.wire, ctx.indexes);
|
|
1669
|
+
if (plan.kind === "index-walk") {
|
|
1670
|
+
let rows = await runIndexWalkPlan(ctx, head.json, state, plan);
|
|
1671
|
+
if (state.order !== void 0) rows = sortByOrderSpec(rows, state.order);
|
|
1672
|
+
if (state.limit !== void 0 && state.limit < rows.length) rows = rows.slice(0, state.limit);
|
|
1673
|
+
return {
|
|
1674
|
+
rows,
|
|
1675
|
+
manifestPointer,
|
|
1676
|
+
fresh
|
|
1677
|
+
};
|
|
1678
|
+
}
|
|
1679
|
+
const nextSeq = head.json.next_seq;
|
|
1680
|
+
const logSeqStart = logSeqStartOf(head.json);
|
|
1681
|
+
const baseDocs = head.json.snapshot === null ? /* @__PURE__ */ new Map() : await loadSnapshotAsMap(ctx.storage, head.json.snapshot, ctx.collectionName);
|
|
1682
|
+
const entries = await walkLogRange(ctx.storage, ctx.collectionPrefix, logSeqStart, nextSeq);
|
|
1683
|
+
const docs = new Map(baseDocs);
|
|
1684
|
+
foldLogEntriesOnto(docs, entries, { collection: ctx.collectionName });
|
|
1685
|
+
const fastId = singleIdFromPredicate(state.wire);
|
|
1686
|
+
let rows;
|
|
1687
|
+
if (fastId !== void 0) {
|
|
1688
|
+
const hit = docs.get(fastId);
|
|
1689
|
+
rows = hit === void 0 ? [] : [hit];
|
|
1690
|
+
} else {
|
|
1691
|
+
rows = Array.from(docs.values());
|
|
1692
|
+
if (state.wire !== void 0) {
|
|
1693
|
+
const w = state.wire;
|
|
1694
|
+
rows = rows.filter((d) => matchesWire(w, d));
|
|
1695
|
+
}
|
|
1696
|
+
}
|
|
1697
|
+
if (state.order !== void 0) rows = sortByOrderSpec(rows, state.order);
|
|
1698
|
+
if (state.limit !== void 0 && state.limit < rows.length) rows = rows.slice(0, state.limit);
|
|
1699
|
+
return {
|
|
1700
|
+
rows,
|
|
1701
|
+
manifestPointer,
|
|
1702
|
+
fresh
|
|
1703
|
+
};
|
|
1704
|
+
};
|
|
1705
|
+
/**
|
|
1706
|
+
* Range-walk exclusive-lower sentinel. `Storage.list({startAfter})`
|
|
1707
|
+
* is strict-greater; to position the cursor PAST every entry whose
|
|
1708
|
+
* value-segment equals `ENCODE(lo)`, append a character that
|
|
1709
|
+
* lex-sorts strictly greater than every base-32 character (the
|
|
1710
|
+
* encoder alphabet is `[0-9a-v]`, topping out at `v` = 0x76) AND
|
|
1711
|
+
* strictly greater than the path separator `/` (0x2F).
|
|
1712
|
+
*
|
|
1713
|
+
* `~` (0x7E) satisfies both. The cursor `${eqPrefix}${ENCODE(lo)}/~`
|
|
1714
|
+
* lex-sorts strictly greater than the LARGEST possible key under
|
|
1715
|
+
* the `lo` value bucket but strictly less than the smallest key
|
|
1716
|
+
* under any bucket with a larger value-segment. The next LIST
|
|
1717
|
+
* result is the first entry with value-segment strictly greater
|
|
1718
|
+
* than `ENCODE(lo)` — exactly the exclusive-lower semantics we
|
|
1719
|
+
* want.
|
|
1720
|
+
*/
|
|
1721
|
+
const RANGE_EXCLUSIVE_LOWER_SENTINEL = "~";
|
|
1722
|
+
/**
|
|
1723
|
+
* Bounded parallelism for `$in` multi-walk LISTs. Each batch of this
|
|
1724
|
+
* many `$in` values dispatches its `list()` calls concurrently; the
|
|
1725
|
+
* loop waits on the batch before starting the next.
|
|
1726
|
+
*
|
|
1727
|
+
* Picked low (8) to stay well under any cloud-provider per-call concurrency
|
|
1728
|
+
* ceiling while still amortising LIST round-trip latency on multi-value
|
|
1729
|
+
* `$in` queries. The planner's `IN_FANOUT_THRESHOLD` (50) caps the total
|
|
1730
|
+
* fan-out independently — see `packages/server/src/query-planner.ts`.
|
|
1731
|
+
*/
|
|
1732
|
+
const IN_FANOUT_PARALLELISM = 8;
|
|
1733
|
+
/**
|
|
1734
|
+
* Execute an {@link IndexWalkPlan} against the bucket. Returns the
|
|
1735
|
+
* post-filtered, fully-resolved row set. The full original
|
|
1736
|
+
* `state.wire` is re-applied via `matchesWire(...)` after fetching
|
|
1737
|
+
* rows — this defends against stale index entries AND consumes the
|
|
1738
|
+
* planner's residue (range clauses, unrelated equality on
|
|
1739
|
+
* non-indexed fields) in one place.
|
|
1740
|
+
*
|
|
1741
|
+
* Storage shape (equality-only walks):
|
|
1742
|
+
* - Single-field walk (`equalityKeys.length === 1`): list
|
|
1743
|
+
* `<collectionPrefix>/index/<name>/<v0-b32>/`; each yielded key has
|
|
1744
|
+
* tail `<docId>.json` (single segment).
|
|
1745
|
+
* - Composite full walk (`equalityKeys.length === def.on.length`):
|
|
1746
|
+
* list `<collectionPrefix>/index/<name>/<v0-b32>/<v1-b32>/.../<vN-b32>/`;
|
|
1747
|
+
* each yielded key has tail `<docId>.json` (single segment).
|
|
1748
|
+
* - Composite partial-prefix walk (`equalityKeys.length <
|
|
1749
|
+
* def.on.length`): list `<collectionPrefix>/index/<name>/<v0-b32>/
|
|
1750
|
+
* .../<vM-b32>/`; each yielded key has tail
|
|
1751
|
+
* `<v{M+1}-b32>/.../<vN-b32>/<docId>.json` — MULTI-segment.
|
|
1752
|
+
* Split on `/` and take the last segment.
|
|
1753
|
+
*
|
|
1754
|
+
* Storage shape (T3, range / `$in` walks):
|
|
1755
|
+
* - Range walk (`plan.rangeOn !== undefined`): list
|
|
1756
|
+
* `<collectionPrefix>/index/<name>/<eq-segs>/` and break on the
|
|
1757
|
+
* first decoded value-segment past the upper bound. Lower
|
|
1758
|
+
* bound is enforced via `startAfter` (exclusive lower) or an
|
|
1759
|
+
* in-loop skip (inclusive lower) — see
|
|
1760
|
+
* {@link RANGE_EXCLUSIVE_LOWER_SENTINEL}.
|
|
1761
|
+
* - `$in` walk (`plan.inOn !== undefined`): one LIST per value,
|
|
1762
|
+
* with the equality prefix prepended to each, dispatched in
|
|
1763
|
+
* batches of {@link IN_FANOUT_PARALLELISM} `Promise.all`-style.
|
|
1764
|
+
* Doc-ids accumulate into a single Set (union semantics).
|
|
1765
|
+
*
|
|
1766
|
+
* Stale-row defence:
|
|
1767
|
+
* - An index entry pointing at a docId whose underlying doc has
|
|
1768
|
+
* since been updated to a different value (rebuild hasn't run)
|
|
1769
|
+
* is dropped by the in-memory `matchesWire(...)` re-check.
|
|
1770
|
+
* - An index entry pointing at a docId whose underlying doc has
|
|
1771
|
+
* been deleted (tombstone in the log) is dropped during the
|
|
1772
|
+
* fold (the `D` op removes it from the materialised set).
|
|
1773
|
+
*
|
|
1774
|
+
* @internal
|
|
1775
|
+
*/
|
|
1776
|
+
const runIndexWalkPlan = async (ctx, head, state, plan) => {
|
|
1777
|
+
const encodedSegments = plan.equalityKeys.map((v) => encodeIndexValue(v));
|
|
1778
|
+
const eqPrefix = encodedSegments.length === 0 ? `${ctx.collectionPrefix}/index/${plan.indexName}/` : `${ctx.collectionPrefix}/index/${plan.indexName}/${encodedSegments.join("/")}/`;
|
|
1779
|
+
const docIdSet = /* @__PURE__ */ new Set();
|
|
1780
|
+
if (plan.rangeOn !== void 0) {
|
|
1781
|
+
const r = plan.rangeOn;
|
|
1782
|
+
const loEncoded = r.lo === void 0 ? void 0 : encodeIndexValue(r.lo);
|
|
1783
|
+
const hiEncoded = r.hi === void 0 ? void 0 : encodeIndexValue(r.hi);
|
|
1784
|
+
const startAfter = r.lo !== void 0 && !r.loInclusive ? `${eqPrefix}${loEncoded}/${RANGE_EXCLUSIVE_LOWER_SENTINEL}` : void 0;
|
|
1785
|
+
const listOpts = startAfter === void 0 ? {} : { startAfter };
|
|
1786
|
+
for await (const entry of ctx.storage.list(eqPrefix, listOpts)) {
|
|
1787
|
+
const tail = entry.key.slice(eqPrefix.length);
|
|
1788
|
+
const firstSlash = tail.indexOf("/");
|
|
1789
|
+
if (firstSlash < 0) continue;
|
|
1790
|
+
const valueSeg = tail.slice(0, firstSlash);
|
|
1791
|
+
if (loEncoded !== void 0 && valueSeg < loEncoded) continue;
|
|
1792
|
+
if (hiEncoded !== void 0) {
|
|
1793
|
+
if (r.hiInclusive ? valueSeg > hiEncoded : valueSeg >= hiEncoded) break;
|
|
1794
|
+
}
|
|
1795
|
+
const lastSlash = tail.lastIndexOf("/");
|
|
1796
|
+
const last = lastSlash === firstSlash ? tail.slice(firstSlash + 1) : tail.slice(lastSlash + 1);
|
|
1797
|
+
if (!last.endsWith(".json")) continue;
|
|
1798
|
+
const docId = last.slice(0, -5);
|
|
1799
|
+
if (docId.length === 0) continue;
|
|
1800
|
+
docIdSet.add(docId);
|
|
1801
|
+
}
|
|
1802
|
+
} else if (plan.inOn !== void 0) {
|
|
1803
|
+
const values = plan.inOn.values;
|
|
1804
|
+
const walkOne = async (value) => {
|
|
1805
|
+
const valPrefix = `${eqPrefix}${encodeIndexValue(value)}/`;
|
|
1806
|
+
const ids = [];
|
|
1807
|
+
for await (const entry of ctx.storage.list(valPrefix)) {
|
|
1808
|
+
const tail = entry.key.slice(valPrefix.length);
|
|
1809
|
+
if (!tail.endsWith(".json")) continue;
|
|
1810
|
+
const lastSlash = tail.lastIndexOf("/");
|
|
1811
|
+
const docId = lastSlash === -1 ? tail.slice(0, -5) : tail.slice(lastSlash + 1, -5);
|
|
1812
|
+
if (docId.length === 0) continue;
|
|
1813
|
+
ids.push(docId);
|
|
1814
|
+
}
|
|
1815
|
+
return ids;
|
|
1816
|
+
};
|
|
1817
|
+
for (let i = 0; i < values.length; i += IN_FANOUT_PARALLELISM) {
|
|
1818
|
+
const batch = values.slice(i, i + IN_FANOUT_PARALLELISM);
|
|
1819
|
+
const results = await Promise.all(batch.map(walkOne));
|
|
1820
|
+
for (const ids of results) for (const id of ids) docIdSet.add(id);
|
|
1821
|
+
}
|
|
1822
|
+
} else for await (const entry of ctx.storage.list(eqPrefix)) {
|
|
1823
|
+
const tail = entry.key.slice(eqPrefix.length);
|
|
1824
|
+
if (!tail.endsWith(".json")) continue;
|
|
1825
|
+
const lastSlash = tail.lastIndexOf("/");
|
|
1826
|
+
const docId = lastSlash === -1 ? tail.slice(0, -5) : tail.slice(lastSlash + 1, -5);
|
|
1827
|
+
if (docId.length === 0) continue;
|
|
1828
|
+
docIdSet.add(docId);
|
|
1829
|
+
}
|
|
1830
|
+
const docIds = Array.from(docIdSet);
|
|
1831
|
+
if (docIds.length === 0) return [];
|
|
1832
|
+
const matched = new Set(docIds);
|
|
1833
|
+
const baseDocs = head.snapshot === null ? /* @__PURE__ */ new Map() : await loadSnapshotAsMap(ctx.storage, head.snapshot, ctx.collectionName);
|
|
1834
|
+
const docs = /* @__PURE__ */ new Map();
|
|
1835
|
+
for (const id of matched) {
|
|
1836
|
+
const seeded = baseDocs.get(id);
|
|
1837
|
+
if (seeded !== void 0) docs.set(id, seeded);
|
|
1838
|
+
}
|
|
1839
|
+
const logSeqStart = logSeqStartOf(head);
|
|
1840
|
+
const nextSeq = head.next_seq;
|
|
1841
|
+
foldLogEntriesOnto(docs, await walkLogRange(ctx.storage, ctx.collectionPrefix, logSeqStart, nextSeq), {
|
|
1842
|
+
collection: ctx.collectionName,
|
|
1843
|
+
docIdFilter: matched
|
|
1844
|
+
});
|
|
1845
|
+
const rows = [];
|
|
1846
|
+
const wire = state.wire;
|
|
1847
|
+
for (const doc of docs.values()) if (wire === void 0 || matchesWire(wire, doc)) rows.push(doc);
|
|
1848
|
+
return rows;
|
|
1849
|
+
};
|
|
1850
|
+
/**
|
|
1851
|
+
* Stable multi-key sort built from an `OrderSpec`. Keys are taken in
|
|
1852
|
+
* the spec's insertion order, which matches the caller's source-order
|
|
1853
|
+
* expectation. `Array.prototype.sort` is stable on Node 24+ and Workerd.
|
|
1854
|
+
*
|
|
1855
|
+
* Top-level fields only (locked at `OrderSpec<T>`).
|
|
1856
|
+
* Values are `DocumentValue` — string / number / boolean / object —
|
|
1857
|
+
* but only the primitive types are sensibly orderable; comparing two
|
|
1858
|
+
* objects falls through to "considered equal," which preserves the
|
|
1859
|
+
* stable-sort order of the input.
|
|
1860
|
+
*/
|
|
1861
|
+
const sortByOrderSpec = (rows, spec) => {
|
|
1862
|
+
const entries = Object.entries(spec);
|
|
1863
|
+
return rows.toSorted((a, b) => {
|
|
1864
|
+
for (const [field, dir] of entries) {
|
|
1865
|
+
const av = a[field];
|
|
1866
|
+
const bv = b[field];
|
|
1867
|
+
if (av === bv) continue;
|
|
1868
|
+
if (av === void 0) return dir === "desc" ? 1 : -1;
|
|
1869
|
+
if (bv === void 0) return dir === "desc" ? -1 : 1;
|
|
1870
|
+
if (typeof av === "object" || typeof bv === "object") continue;
|
|
1871
|
+
const cmp = av < bv ? -1 : 1;
|
|
1872
|
+
return dir === "desc" ? -cmp : cmp;
|
|
1873
|
+
}
|
|
1874
|
+
return 0;
|
|
1875
|
+
});
|
|
1876
|
+
};
|
|
1877
|
+
//#endregion
|
|
1878
|
+
export { runReplaceById as a, lsnParts as c, runInsert as i, delay as l, runAllWithMeta as n, validateOrThrow as o, runByIdWithMeta as r, Writer as s, makeQuery as t };
|
|
1879
|
+
|
|
1880
|
+
//# sourceMappingURL=query-DcSbFLJt.js.map
|