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