@gusto/baerly-storage 0.6.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 -512
- package/dist/CHANGELOG.md +1137 -378
- 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-ypCm3zjt.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-wrVYf4bb.js → cloudflare-CKHYXccw.js} +61 -82
- 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-Di_Q01qx.js → deploy-Obj4nE-Z.js} +10 -14
- 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 +9 -14
- package/dist/dev-vite.js +11 -10
- 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-Bx6xSNJj.d.ts → gcs-admin-Dso1HWQj.d.ts} +18 -14
- package/dist/gcs.d.ts +19 -7
- package/dist/gcs.js +1 -2
- package/dist/{goog4-signer-Z7KnJ1su.js → goog4-signer-CeLIABoE.js} +102 -92
- package/dist/goog4-signer-CeLIABoE.js.map +1 -0
- package/dist/{http-7zT29K3P.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-DP3ClvcA.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 +119 -92
- package/dist/node.js +3 -3
- package/dist/{observability-Ch-VQJyE.js → observability-C-ISCCLE.js} +1247 -326
- 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-C4qgiXSg.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--LykAdl1.js → runtime-spec-B5mg3pHF.js} +189 -28
- package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
- package/dist/{s3-http-DD5gDc7t.d.ts → s3-http-DBC_wiCL.d.ts} +14 -8
- package/dist/s3.d.ts +20 -7
- package/dist/s3.js +4 -5
- package/dist/s3.js.map +1 -1
- package/dist/{sha256-CqcKTjw9.js → sha256-4FfGQNPw.js} +9 -9
- 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/{aws4fetch.esm-CXE5ZbAa.js → sigv4-sign-5IUflUD_.js} +143 -96
- 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-BMFfDUI2.js → src-Actga-bO.js} +949 -363
- 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-BV68pqwJ.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-BMZR8o6U.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 +90 -69
- package/dist/aws4fetch.esm-CXE5ZbAa.js.map +0 -1
- package/dist/bytes-BXdamO3L.js +0 -11
- package/dist/bytes-BXdamO3L.js.map +0 -1
- package/dist/cloudflare-wrVYf4bb.js.map +0 -1
- package/dist/config-B6nTy8e2.js +0 -3095
- package/dist/config-B6nTy8e2.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-_SE_SVgZ.js +0 -203
- package/dist/cost-_SE_SVgZ.js.map +0 -1
- package/dist/current-json-C6nhPOm1.js.map +0 -1
- package/dist/db-DjjthkTi.d.ts +0 -254
- package/dist/deploy-Di_Q01qx.js.map +0 -1
- package/dist/doctor-RWVRpvat.js +0 -102
- package/dist/doctor-RWVRpvat.js.map +0 -1
- package/dist/dump-m2vEYDNY.js +0 -94
- package/dist/dump-m2vEYDNY.js.map +0 -1
- package/dist/errors-Dfa3p78c.js +0 -78
- package/dist/errors-Dfa3p78c.js.map +0 -1
- package/dist/export-DenKwEQu.js +0 -401
- package/dist/export-DenKwEQu.js.map +0 -1
- package/dist/fsck-2Vq-7-e2.js +0 -279
- package/dist/fsck-2Vq-7-e2.js.map +0 -1
- package/dist/goog4-signer-Z7KnJ1su.js.map +0 -1
- package/dist/http-7zT29K3P.js.map +0 -1
- package/dist/http-transport-BTgVCY5r.js +0 -1250
- package/dist/http-transport-BTgVCY5r.js.map +0 -1
- package/dist/index-BHz92Acj.d.ts +0 -162
- package/dist/index-CEZKQsKt.d.ts +0 -1113
- package/dist/index-uE-w2dgj.d.ts +0 -115
- package/dist/indexes-Dn9hbGQG.d.ts +0 -22
- package/dist/inspect-BpYbH1DM.js +0 -133
- package/dist/inspect-BpYbH1DM.js.map +0 -1
- package/dist/log-tail-QWU4wlu-.js +0 -514
- package/dist/log-tail-QWU4wlu-.js.map +0 -1
- package/dist/maintenance-BGHGt2Yg.d.ts +0 -537
- package/dist/maintenance-DULFcpd1.js +0 -2144
- package/dist/maintenance-DULFcpd1.js.map +0 -1
- package/dist/maintenance-fEi-UZ2o.js +0 -1412
- package/dist/maintenance-fEi-UZ2o.js.map +0 -1
- package/dist/normalize-rjnZLwS4.js +0 -133
- package/dist/normalize-rjnZLwS4.js.map +0 -1
- package/dist/observability-Ch-VQJyE.js.map +0 -1
- package/dist/plan-C4qgiXSg.js.map +0 -1
- package/dist/query-C43r-6ib.js +0 -1773
- package/dist/query-C43r-6ib.js.map +0 -1
- package/dist/rebuild-index-BH1dc1p6.js +0 -81
- package/dist/rebuild-index-BH1dc1p6.js.map +0 -1
- package/dist/request-u0M51mhJ.js +0 -72
- package/dist/request-u0M51mhJ.js.map +0 -1
- package/dist/restore-D0VYWzfP.js +0 -778
- package/dist/restore-D0VYWzfP.js.map +0 -1
- package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
- package/dist/runtime-spec--LykAdl1.js.map +0 -1
- package/dist/sha256-CqcKTjw9.js.map +0 -1
- package/dist/shared-secret-DgEicd3x.js.map +0 -1
- package/dist/src-BMFfDUI2.js.map +0 -1
- package/dist/src-DYZ4H1aF.js +0 -392
- package/dist/src-DYZ4H1aF.js.map +0 -1
- package/dist/src-DvbTEya2.js +0 -536
- package/dist/src-DvbTEya2.js.map +0 -1
- package/dist/subcommand-BV68pqwJ.js.map +0 -1
- package/dist/time-DUqvFMHq.js.map +0 -1
- package/dist/usage-BMZR8o6U.js.map +0 -1
- package/dist/validate-DtljsCh1.js.map +0 -1
- package/dist/wire-izfGZDvr.js.map +0 -1
|
@@ -0,0 +1,3261 @@
|
|
|
1
|
+
import { t as CODE_RESOLUTIONS } from "./code-resolution-CL_7L0wS.js";
|
|
2
|
+
import { c as certifiedDeleteFloor, d as logSeqStartOf, f as mintGeneration, g as encodeJsonBytes, h as decodeJsonBytes, i as assertWellFormedSegment, l as createCurrentJson, n as assertNfcSegment, p as readCurrentJson, r as assertPathSegment, t as assertNameSegment, u as logDeleteFloorOf } from "./path-segment-DBXG26PW.js";
|
|
3
|
+
import { b as MAX_DOCUMENT_BYTES, f as LOG_FORWARD_PROBE_CAP, h as MAINTENANCE_PROFILE_CF_FREE, o as FORBIDDEN_MERGE_KEYS, x as MAX_KEY_BYTES } from "./constants-D3GSH3tc.js";
|
|
4
|
+
import { i as isWriteConflict, t as BaerlyError } from "./errors-7Rk1HGCE.js";
|
|
5
|
+
import { i as assertInsertIdType, n as normalizePredicateArg, r as assertDocumentValues, t as uuidv7 } from "./uuid-BuT_c404.js";
|
|
6
|
+
import { S as logObjectKey, _ as loadSnapshotAsMap, c as rowBytes, f as probeReadTail, g as walkLogRange, h as foldLogEntriesOnto, i as resolveFoldCeilings, l as findLogTail, m as probeTailFrom, n as isFoldViable, o as shouldFireMaintenance, p as probeTailChunk, s as projectSnapshot, t as dispatchWriteTick, v as isOwnCollection, x as markCallerFacing, y as callerFacingCheck } from "./maintenance-DevB6z4e.js";
|
|
7
|
+
import { n as timestamp, o as uuid, r as countKey } from "./time-DRxTP9iv.js";
|
|
8
|
+
import { r as currentRequestLedger } from "./ledger-Dj_bGgo0.js";
|
|
9
|
+
import { a as noopMetricsRecorder, i as runWithContext, r as getCurrentContext } from "./context-rlpSnHFA.js";
|
|
10
|
+
// packages/protocol/src/document-size.ts
|
|
11
|
+
const utf8Encoder = new TextEncoder();
|
|
12
|
+
const DOCUMENT_SIZE_RESOLUTION = `Keep each document at or under ${MAX_DOCUMENT_BYTES} bytes (1 MiB) of JSON: move large or growing data (attachments, long histories, arrays that keep growing) into rows of their own, or store blobs outside the database and keep a reference.`;
|
|
13
|
+
/**
|
|
14
|
+
* UTF-8 byte length of `json` when it is over `limit`, else `undefined`.
|
|
15
|
+
* Skips the encode when the string is short enough to decide it: a UTF-16
|
|
16
|
+
* code unit encodes to at most 3 bytes.
|
|
17
|
+
*/
|
|
18
|
+
const jsonByteLengthAbove = (json, limit) => {
|
|
19
|
+
if (json.length * 3 <= limit) return;
|
|
20
|
+
const bytes = utf8Encoder.encode(json).byteLength;
|
|
21
|
+
return bytes > limit ? bytes : void 0;
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* Refuse a post-image larger than {@link MAX_DOCUMENT_BYTES} once encoded
|
|
25
|
+
* as stored (`encodeJsonBytes`, which sorts nothing, so key order does not
|
|
26
|
+
* change the size). Call it on the whole document a write would commit,
|
|
27
|
+
* not on an update patch: a small patch can still grow a row past the cap.
|
|
28
|
+
* A row already stored larger is not checked here; only a write producing
|
|
29
|
+
* an over-cap post-image is refused.
|
|
30
|
+
*
|
|
31
|
+
* I/O-free. The value must already be in the JSON document domain (see
|
|
32
|
+
* `assertDocumentValues`); a value `JSON.stringify` cannot encode
|
|
33
|
+
* throws its own error.
|
|
34
|
+
*
|
|
35
|
+
* @param verb the calling verb, used as the message prefix.
|
|
36
|
+
* @throws BaerlyError code="InvalidConfig" — the encoded post-image is over
|
|
37
|
+
* the cap. The message states its size and the limit.
|
|
38
|
+
*/
|
|
39
|
+
const assertDocumentSize = (value, verb) => {
|
|
40
|
+
const bytes = jsonByteLengthAbove(JSON.stringify(value), MAX_DOCUMENT_BYTES);
|
|
41
|
+
if (bytes !== void 0) throw new BaerlyError("InvalidConfig", `${verb}: the document encodes to ${bytes} bytes of JSON, over the ${MAX_DOCUMENT_BYTES}-byte (1 MiB) document limit`, { resolution: DOCUMENT_SIZE_RESOLUTION });
|
|
42
|
+
};
|
|
43
|
+
// packages/protocol/src/json.ts
|
|
44
|
+
/**
|
|
45
|
+
* Structural equality of two JSON values.
|
|
46
|
+
*
|
|
47
|
+
* Both inputs must already be JSON-normalized, i.e. the result of a
|
|
48
|
+
* `JSON.parse` — typically `JSON.parse(JSON.stringify(body))` compared
|
|
49
|
+
* against a stored row decoded from JSON. The round-trip drops
|
|
50
|
+
* `undefined` properties (as the write path's encoder does) and turns
|
|
51
|
+
* `-0` into `0`; that normalization is the caller's responsibility.
|
|
52
|
+
* Raw inputs holding `undefined` or `-0` are outside the contract.
|
|
53
|
+
*
|
|
54
|
+
* Uses an explicit work stack so comparison does not consume the
|
|
55
|
+
* JavaScript call stack with each nesting level. No depth cap is enforced.
|
|
56
|
+
*
|
|
57
|
+
* - Object key order is ignored; the key sets must match exactly.
|
|
58
|
+
* - Arrays compare element-wise in order, and an array is never equal
|
|
59
|
+
* to an object (`[1]` vs `{"0":1}` is `false`).
|
|
60
|
+
* - Primitives compare with `===`.
|
|
61
|
+
*
|
|
62
|
+
* Deliberately not `deepEqualDocumentValue`, which cannot tell an array
|
|
63
|
+
* from an index-keyed object.
|
|
64
|
+
*/
|
|
65
|
+
function jsonValueEqual(a, b) {
|
|
66
|
+
const pending = [[a, b]];
|
|
67
|
+
while (pending.length > 0) {
|
|
68
|
+
const [left, right] = pending.pop();
|
|
69
|
+
if (left === right) continue;
|
|
70
|
+
if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) return false;
|
|
71
|
+
if (Array.isArray(left)) {
|
|
72
|
+
if (!Array.isArray(right) || left.length !== right.length) return false;
|
|
73
|
+
for (let i = 0; i < left.length; i++) pending.push([left[i], right[i]]);
|
|
74
|
+
continue;
|
|
75
|
+
}
|
|
76
|
+
if (Array.isArray(right)) return false;
|
|
77
|
+
const keys = Object.keys(left);
|
|
78
|
+
if (keys.length !== Object.keys(right).length) return false;
|
|
79
|
+
for (const key of keys) {
|
|
80
|
+
if (!Object.prototype.hasOwnProperty.call(right, key)) return false;
|
|
81
|
+
pending.push([left[key], right[key]]);
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
return true;
|
|
85
|
+
}
|
|
86
|
+
const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
87
|
+
/**
|
|
88
|
+
* Apply a JSON Merge Patch to a document, exactly as RFC 7396 §2 defines
|
|
89
|
+
* it. This is what `update` commits: `applyMergePatch(row, patch)`.
|
|
90
|
+
*
|
|
91
|
+
* An object patch merges key by key into the target, or into `{}` when
|
|
92
|
+
* the target is absent or not an object. A `null` member deletes that
|
|
93
|
+
* key, at every depth, so a patch never stores a `null` member: under an
|
|
94
|
+
* absent field, `{ meta: { a: 1, b: null } }` stores `meta: { a: 1 }`.
|
|
95
|
+
* A scalar or array patch replaces the target whole; arrays are opaque
|
|
96
|
+
* values, so a `null` inside one is kept. An `undefined` member is
|
|
97
|
+
* absent, as in the patch's JSON form.
|
|
98
|
+
*
|
|
99
|
+
* Two values outside RFC 7396's JSON domain: an `undefined` patch is the
|
|
100
|
+
* identity (returns `target`), and a `null` patch at the root returns
|
|
101
|
+
* `undefined`, since a document cannot be `null`.
|
|
102
|
+
*
|
|
103
|
+
* `__proto__`, `constructor` and `prototype` members are skipped
|
|
104
|
+
* (`FORBIDDEN_MERGE_KEYS`). Recursion follows the patch, whose depth
|
|
105
|
+
* `assertDocumentValues` caps at `MAX_DOCUMENT_DEPTH` before `update`
|
|
106
|
+
* applies it.
|
|
107
|
+
*/
|
|
108
|
+
function applyMergePatch(target, patch) {
|
|
109
|
+
if (patch === void 0) return target;
|
|
110
|
+
if (patch === null) return;
|
|
111
|
+
if (!isPlainObject(patch)) return patch;
|
|
112
|
+
const combined = isPlainObject(target) ? { ...target } : {};
|
|
113
|
+
const members = patch;
|
|
114
|
+
for (const key of Object.keys(members)) {
|
|
115
|
+
if (FORBIDDEN_MERGE_KEYS.has(key)) continue;
|
|
116
|
+
const value = members[key];
|
|
117
|
+
if (value === void 0) continue;
|
|
118
|
+
if (value === null) delete combined[key];
|
|
119
|
+
else combined[key] = applyMergePatch(combined[key], value);
|
|
120
|
+
}
|
|
121
|
+
return combined;
|
|
122
|
+
}
|
|
123
|
+
// packages/protocol/src/query/matches.ts
|
|
124
|
+
/** Follow a split dotted path from `doc`; `undefined` when it cannot be consumed. */
|
|
125
|
+
const walkPath = (doc, segments) => {
|
|
126
|
+
let cursor = doc;
|
|
127
|
+
for (const segment of segments) {
|
|
128
|
+
if (cursor === void 0 || cursor === null || typeof cursor !== "object" || Array.isArray(cursor)) return;
|
|
129
|
+
cursor = cursor[segment];
|
|
130
|
+
}
|
|
131
|
+
return cursor;
|
|
132
|
+
};
|
|
133
|
+
/**
|
|
134
|
+
* Compile a validated wire-form predicate into a per-document test that
|
|
135
|
+
* agrees with {@link matchesWire} on every document. Each dotted clause
|
|
136
|
+
* path is split once here rather than once per document, so a filter
|
|
137
|
+
* over n rows pays one split per clause instead of n. Clause order,
|
|
138
|
+
* path walk and clause matchers are {@link matchesWire}'s.
|
|
139
|
+
*
|
|
140
|
+
* Same pre-condition as {@link matchesWire}: `wire` has passed
|
|
141
|
+
* {@link validateWire}.
|
|
142
|
+
*
|
|
143
|
+
* @example
|
|
144
|
+
* ```ts
|
|
145
|
+
* const open = compileWire({ clauses: [{ op: "eq", field: "meta.state", value: "open" }] });
|
|
146
|
+
* docs.filter(open);
|
|
147
|
+
* ```
|
|
148
|
+
*/
|
|
149
|
+
const compileWire = (wire) => {
|
|
150
|
+
const compiled = wire.clauses.map((clause) => ({
|
|
151
|
+
clause,
|
|
152
|
+
field: clause.field,
|
|
153
|
+
segments: clause.field.includes(".") ? clause.field.split(".") : void 0
|
|
154
|
+
}));
|
|
155
|
+
return (doc) => {
|
|
156
|
+
for (const { clause, field, segments } of compiled) if (!matchesClause(clause, segments === void 0 ? doc[field] : walkPath(doc, segments))) return false;
|
|
157
|
+
return true;
|
|
158
|
+
};
|
|
159
|
+
};
|
|
160
|
+
const matchesClause = (clause, actual) => {
|
|
161
|
+
switch (clause.op) {
|
|
162
|
+
case "eq": return matchesEq(clause.value, actual);
|
|
163
|
+
case "in": return matchesIn(clause.value, actual);
|
|
164
|
+
case "gt": return compareGT(actual, clause.value, false);
|
|
165
|
+
case "gte": return compareGT(actual, clause.value, true);
|
|
166
|
+
case "lt": return compareLT(actual, clause.value, false);
|
|
167
|
+
case "lte": return compareLT(actual, clause.value, true);
|
|
168
|
+
}
|
|
169
|
+
};
|
|
170
|
+
const matchesEq = (expected, actual) => {
|
|
171
|
+
if (typeof expected === "object") {
|
|
172
|
+
if (actual === void 0 || actual === null || typeof actual !== "object" || Array.isArray(actual)) return false;
|
|
173
|
+
for (const subKey of Object.keys(expected)) {
|
|
174
|
+
const subExpected = expected[subKey];
|
|
175
|
+
if (subExpected === void 0) continue;
|
|
176
|
+
const subActual = actual[subKey];
|
|
177
|
+
if (!matchesEq(subExpected, subActual)) return false;
|
|
178
|
+
}
|
|
179
|
+
return true;
|
|
180
|
+
}
|
|
181
|
+
return expected === actual;
|
|
182
|
+
};
|
|
183
|
+
const matchesIn = (members, actual) => {
|
|
184
|
+
for (const m of members) if (typeof m === "object") {
|
|
185
|
+
if (matchesEq(m, actual)) return true;
|
|
186
|
+
} else if (m === actual) return true;
|
|
187
|
+
return false;
|
|
188
|
+
};
|
|
189
|
+
const compareGT = (actual, bound, inclusive) => {
|
|
190
|
+
if (typeof bound === "string") return typeof actual === "string" && (inclusive ? actual >= bound : actual > bound);
|
|
191
|
+
if (typeof bound === "number") return typeof actual === "number" && (inclusive ? actual >= bound : actual > bound);
|
|
192
|
+
return false;
|
|
193
|
+
};
|
|
194
|
+
const compareLT = (actual, bound, inclusive) => {
|
|
195
|
+
if (typeof bound === "string") return typeof actual === "string" && (inclusive ? actual <= bound : actual < bound);
|
|
196
|
+
if (typeof bound === "number") return typeof actual === "number" && (inclusive ? actual <= bound : actual < bound);
|
|
197
|
+
return false;
|
|
198
|
+
};
|
|
199
|
+
// packages/protocol/src/query/_internals.ts
|
|
200
|
+
/** @internal Same primitive type for comparison purposes. */
|
|
201
|
+
const sameComparableType = (a, b) => typeof a === "string" && typeof b === "string" || typeof a === "number" && typeof b === "number";
|
|
202
|
+
/**
|
|
203
|
+
* @internal Returns negative / zero / positive for a<b / a==b / a>b.
|
|
204
|
+
*/
|
|
205
|
+
const compareScalar = (a, b) => {
|
|
206
|
+
if (typeof a === "number" && typeof b === "number") return a - b;
|
|
207
|
+
if (typeof a === "string" && typeof b === "string") {
|
|
208
|
+
if (a < b) return -1;
|
|
209
|
+
if (a > b) return 1;
|
|
210
|
+
return 0;
|
|
211
|
+
}
|
|
212
|
+
return 0;
|
|
213
|
+
};
|
|
214
|
+
/** @internal Render a predicate path for use in error messages. */
|
|
215
|
+
const formatPath = (path) => path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(".");
|
|
216
|
+
/**
|
|
217
|
+
* Recursive structural equality for `DocumentValue` values. Exported so
|
|
218
|
+
* `./satisfiable.ts` and other callers reuse the same comparison rule
|
|
219
|
+
* the validator + merger already trust. Two
|
|
220
|
+
* values `a` and `b` are equal iff:
|
|
221
|
+
*
|
|
222
|
+
* - they are reference-equal (covers primitives and object identity);
|
|
223
|
+
* - or they are both non-`null` objects with the same key set, and
|
|
224
|
+
* every value pair is recursively equal.
|
|
225
|
+
*
|
|
226
|
+
* Arrays are out-of-band for `DocumentValue`; this function rejects
|
|
227
|
+
* them implicitly via the same key-set walk (an array reads as an
|
|
228
|
+
* object with numeric-string keys plus a `length` exposure that
|
|
229
|
+
* `Object.keys` happens to skip — defensive callers should still gate
|
|
230
|
+
* with `Array.isArray` first).
|
|
231
|
+
*/
|
|
232
|
+
const deepEqualDocumentValue = (a, b) => {
|
|
233
|
+
if (a === b) return true;
|
|
234
|
+
if (typeof a !== "object" || typeof b !== "object") return false;
|
|
235
|
+
const aKeys = Object.keys(a);
|
|
236
|
+
const bKeys = Object.keys(b);
|
|
237
|
+
if (aKeys.length !== bKeys.length) return false;
|
|
238
|
+
for (const key of aKeys) {
|
|
239
|
+
if (!(key in b)) return false;
|
|
240
|
+
const aSub = a[key];
|
|
241
|
+
const bSub = b[key];
|
|
242
|
+
if (aSub === void 0 || bSub === void 0) return false;
|
|
243
|
+
if (!deepEqualDocumentValue(aSub, bSub)) return false;
|
|
244
|
+
}
|
|
245
|
+
return true;
|
|
246
|
+
};
|
|
247
|
+
// packages/protocol/src/query/satisfiable.ts
|
|
248
|
+
/**
|
|
249
|
+
* Per-field satisfiability check for a {@link PredicateWire}. Groups
|
|
250
|
+
* clauses by field, then runs the same logic the pre-redesign
|
|
251
|
+
* `assertOpObjectSatisfiable` ran on a single op-object — but
|
|
252
|
+
* generalised across N clauses on the same field (the wire merger
|
|
253
|
+
* concatenates lists without coalescing).
|
|
254
|
+
*
|
|
255
|
+
* Triggers:
|
|
256
|
+
* - Two `eq` clauses on the same field with different values →
|
|
257
|
+
* `InvalidConfig` (the same conflict that pre-redesign
|
|
258
|
+
* `mergePredicates` threw on shared primitive keys).
|
|
259
|
+
* - Range bounds with `lo > hi` (or `lo == hi` with strict on
|
|
260
|
+
* either side) → `UnsatisfiablePredicate`.
|
|
261
|
+
* - `eq` value outside the residual range interval or absent from
|
|
262
|
+
* every `in` set on the same field → `UnsatisfiablePredicate`.
|
|
263
|
+
* - `in` sets that intersect to empty across multiple clauses →
|
|
264
|
+
* `UnsatisfiablePredicate`.
|
|
265
|
+
*
|
|
266
|
+
* Used by both `./validate.ts` (wire-arrival check) and
|
|
267
|
+
* `./merge.ts` (post-merge re-check, kept in lockstep).
|
|
268
|
+
*/
|
|
269
|
+
const groupByField = (wire) => {
|
|
270
|
+
const out = /* @__PURE__ */ new Map();
|
|
271
|
+
for (const clause of wire.clauses) {
|
|
272
|
+
let group = out.get(clause.field);
|
|
273
|
+
if (group === void 0) {
|
|
274
|
+
group = {
|
|
275
|
+
eqs: [],
|
|
276
|
+
ins: []
|
|
277
|
+
};
|
|
278
|
+
out.set(clause.field, group);
|
|
279
|
+
}
|
|
280
|
+
applyClause(group, clause.field, clause);
|
|
281
|
+
}
|
|
282
|
+
return out;
|
|
283
|
+
};
|
|
284
|
+
const applyClause = (group, field, clause) => {
|
|
285
|
+
switch (clause.op) {
|
|
286
|
+
case "eq":
|
|
287
|
+
group.eqs.push(clause.value);
|
|
288
|
+
return;
|
|
289
|
+
case "in":
|
|
290
|
+
group.ins.push(clause.value);
|
|
291
|
+
return;
|
|
292
|
+
case "gt":
|
|
293
|
+
tightenLower(group, field, clause.value, false);
|
|
294
|
+
return;
|
|
295
|
+
case "gte":
|
|
296
|
+
tightenLower(group, field, clause.value, true);
|
|
297
|
+
return;
|
|
298
|
+
case "lt":
|
|
299
|
+
tightenUpper(group, field, clause.value, false);
|
|
300
|
+
return;
|
|
301
|
+
case "lte":
|
|
302
|
+
tightenUpper(group, field, clause.value, true);
|
|
303
|
+
return;
|
|
304
|
+
}
|
|
305
|
+
};
|
|
306
|
+
const tightenLower = (group, field, value, inclusive) => {
|
|
307
|
+
if (group.lo === void 0) {
|
|
308
|
+
group.lo = {
|
|
309
|
+
value,
|
|
310
|
+
inclusive
|
|
311
|
+
};
|
|
312
|
+
return;
|
|
313
|
+
}
|
|
314
|
+
if (!sameComparableType(group.lo.value, value)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} has type-incompatible lower bounds (${JSON.stringify(group.lo.value)} vs ${JSON.stringify(value)}).`);
|
|
315
|
+
const c = compareScalar(group.lo.value, value);
|
|
316
|
+
if (c < 0 || c === 0 && inclusive === false && group.lo.inclusive === true) group.lo = {
|
|
317
|
+
value,
|
|
318
|
+
inclusive
|
|
319
|
+
};
|
|
320
|
+
};
|
|
321
|
+
const tightenUpper = (group, field, value, inclusive) => {
|
|
322
|
+
if (group.hi === void 0) {
|
|
323
|
+
group.hi = {
|
|
324
|
+
value,
|
|
325
|
+
inclusive
|
|
326
|
+
};
|
|
327
|
+
return;
|
|
328
|
+
}
|
|
329
|
+
if (!sameComparableType(group.hi.value, value)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} has type-incompatible upper bounds (${JSON.stringify(group.hi.value)} vs ${JSON.stringify(value)}).`);
|
|
330
|
+
const c = compareScalar(group.hi.value, value);
|
|
331
|
+
if (c > 0 || c === 0 && inclusive === false && group.hi.inclusive === true) group.hi = {
|
|
332
|
+
value,
|
|
333
|
+
inclusive
|
|
334
|
+
};
|
|
335
|
+
};
|
|
336
|
+
const intersectInSets = (sets) => {
|
|
337
|
+
if (sets.length === 0) return [];
|
|
338
|
+
let acc = sets[0];
|
|
339
|
+
for (let i = 1; i < sets.length; i++) {
|
|
340
|
+
const next = [];
|
|
341
|
+
for (const a of acc) for (const b of sets[i]) if (deepEqualDocumentValue(a, b)) {
|
|
342
|
+
next.push(a);
|
|
343
|
+
break;
|
|
344
|
+
}
|
|
345
|
+
acc = next;
|
|
346
|
+
}
|
|
347
|
+
return acc;
|
|
348
|
+
};
|
|
349
|
+
/**
|
|
350
|
+
* Check that every per-field clause group on `wire` is jointly
|
|
351
|
+
* satisfiable. Throws `BaerlyError{code:"UnsatisfiablePredicate"}`
|
|
352
|
+
* (or `"InvalidConfig"` for conflicting `eq` clauses) on the
|
|
353
|
+
* first contradiction. Returns `void` on success.
|
|
354
|
+
*/
|
|
355
|
+
const assertWireSatisfiable = (wire) => {
|
|
356
|
+
const groups = groupByField(wire);
|
|
357
|
+
for (const [field, group] of groups) {
|
|
358
|
+
if (group.eqs.length > 1) {
|
|
359
|
+
for (let i = 1; i < group.eqs.length; i++) if (!deepEqualDocumentValue(group.eqs[0], group.eqs[i])) throw new BaerlyError("InvalidConfig", `Conflicting equality clauses on field ${formatPath([field])} (${JSON.stringify(group.eqs[0])} vs ${JSON.stringify(group.eqs[i])}). Predicate chains must agree on shared equality.`);
|
|
360
|
+
}
|
|
361
|
+
const eq = group.eqs[0];
|
|
362
|
+
if (group.lo !== void 0 && group.hi !== void 0 && sameComparableType(group.lo.value, group.hi.value)) {
|
|
363
|
+
const c = compareScalar(group.lo.value, group.hi.value);
|
|
364
|
+
if (c > 0 || c === 0 && (!group.lo.inclusive || !group.hi.inclusive)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} has empty interval (lo=${JSON.stringify(group.lo.value)} ${group.lo.inclusive ? "gte" : "gt"}, hi=${JSON.stringify(group.hi.value)} ${group.hi.inclusive ? "lte" : "lt"}).`);
|
|
365
|
+
}
|
|
366
|
+
if (eq !== void 0) {
|
|
367
|
+
if (group.lo !== void 0) {
|
|
368
|
+
if (!sameComparableType(eq, group.lo.value)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} (${typeof eq}) is type-incompatible with lower bound ${JSON.stringify(group.lo.value)} (${typeof group.lo.value}); range ops require matching primitive types.`);
|
|
369
|
+
const c = compareScalar(eq, group.lo.value);
|
|
370
|
+
if (c < 0 || c === 0 && !group.lo.inclusive) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} excluded by lower bound ${JSON.stringify(group.lo.value)} (${group.lo.inclusive ? "gte" : "gt"}).`);
|
|
371
|
+
}
|
|
372
|
+
if (group.hi !== void 0) {
|
|
373
|
+
if (!sameComparableType(eq, group.hi.value)) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} (${typeof eq}) is type-incompatible with upper bound ${JSON.stringify(group.hi.value)} (${typeof group.hi.value}); range ops require matching primitive types.`);
|
|
374
|
+
const c = compareScalar(eq, group.hi.value);
|
|
375
|
+
if (c > 0 || c === 0 && !group.hi.inclusive) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} excluded by upper bound ${JSON.stringify(group.hi.value)} (${group.hi.inclusive ? "lte" : "lt"}).`);
|
|
376
|
+
}
|
|
377
|
+
if (group.ins.length > 0) for (const set of group.ins) {
|
|
378
|
+
let found = false;
|
|
379
|
+
for (const m of set) if (deepEqualDocumentValue(eq, m)) {
|
|
380
|
+
found = true;
|
|
381
|
+
break;
|
|
382
|
+
}
|
|
383
|
+
if (!found) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} eq=${JSON.stringify(eq)} not present in in() set.`);
|
|
384
|
+
}
|
|
385
|
+
}
|
|
386
|
+
if (group.ins.length > 1) {
|
|
387
|
+
if (intersectInSets(group.ins).length === 0) throw new BaerlyError("UnsatisfiablePredicate", `Predicate on field ${formatPath([field])} has empty in() intersection across multiple clauses.`);
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
};
|
|
391
|
+
// packages/protocol/src/query/merge.ts
|
|
392
|
+
/**
|
|
393
|
+
* AND-merge two validated wire predicates. Powers chained
|
|
394
|
+
* `Query<T>.where(...).where(...)`.
|
|
395
|
+
*/
|
|
396
|
+
/**
|
|
397
|
+
* AND-merge two validated wire predicates. The result accepts a
|
|
398
|
+
* document iff both `a` and `b` would accept it.
|
|
399
|
+
*
|
|
400
|
+
* Wire-level: clause lists concatenate. The per-field satisfiability
|
|
401
|
+
* check runs across the combined list, surfacing
|
|
402
|
+
* `BaerlyError{code:"UnsatisfiablePredicate"}` on empty residual
|
|
403
|
+
* intervals / empty `in()` intersections / `eq` outside the merged
|
|
404
|
+
* interval, and `BaerlyError{code:"InvalidConfig"}` on conflicting
|
|
405
|
+
* `eq` clauses for the same field (mirrors the pre-redesign
|
|
406
|
+
* conflict-on-shared-keys semantics).
|
|
407
|
+
*
|
|
408
|
+
* @example
|
|
409
|
+
* ```ts
|
|
410
|
+
* mergePredicateWires(
|
|
411
|
+
* { clauses: [{ op: "eq", field: "status", value: "open" }] },
|
|
412
|
+
* { clauses: [{ op: "eq", field: "priority", value: "p1" }] },
|
|
413
|
+
* );
|
|
414
|
+
* // → { clauses: [
|
|
415
|
+
* // { op: "eq", field: "status", value: "open" },
|
|
416
|
+
* // { op: "eq", field: "priority", value: "p1" },
|
|
417
|
+
* // ] }
|
|
418
|
+
*
|
|
419
|
+
* mergePredicateWires(
|
|
420
|
+
* { clauses: [{ op: "eq", field: "status", value: "open" }] },
|
|
421
|
+
* { clauses: [{ op: "eq", field: "status", value: "closed" }] },
|
|
422
|
+
* );
|
|
423
|
+
* // throws BaerlyError{InvalidConfig}: conflicting equality clauses on "status"
|
|
424
|
+
*
|
|
425
|
+
* mergePredicateWires(
|
|
426
|
+
* { clauses: [{ op: "gt", field: "x", value: 10 }] },
|
|
427
|
+
* { clauses: [{ op: "lt", field: "x", value: 5 }] },
|
|
428
|
+
* );
|
|
429
|
+
* // throws BaerlyError{UnsatisfiablePredicate}: empty interval
|
|
430
|
+
* ```
|
|
431
|
+
*/
|
|
432
|
+
const mergePredicateWires = (a, b) => {
|
|
433
|
+
const merged = { clauses: [...a.clauses, ...b.clauses] };
|
|
434
|
+
assertWireSatisfiable(merged);
|
|
435
|
+
return merged;
|
|
436
|
+
};
|
|
437
|
+
// packages/protocol/src/query/validate.ts
|
|
438
|
+
/**
|
|
439
|
+
* Wire predicate validator. Walks a {@link PredicateWire} and throws
|
|
440
|
+
* on a structurally bad clause (`BaerlyError{code:"InvalidConfig"}`)
|
|
441
|
+
* or a per-field clause group that contradicts itself
|
|
442
|
+
* (`BaerlyError{code:"UnsatisfiablePredicate"}`).
|
|
443
|
+
*
|
|
444
|
+
* The object-form normaliser at `./normalize.ts` enforces shape on
|
|
445
|
+
* the way in (rejecting `$`-keys / non-scalars / null / undefined);
|
|
446
|
+
* the callback builder at `./builder.ts` enforces shape via the
|
|
447
|
+
* type system. This validator is the wire-arrival check: it runs
|
|
448
|
+
* over already-normalised clauses, defending against raw-`fetch`
|
|
449
|
+
* callers who bypass the typed seam and submit arbitrary JSON.
|
|
450
|
+
*
|
|
451
|
+
* Companion modules: `./matches.ts` (evaluator), `./merge.ts`
|
|
452
|
+
* (AND-merge). Shared helpers live in `./_internals.ts`.
|
|
453
|
+
*/
|
|
454
|
+
const OP_NAMES = [
|
|
455
|
+
"eq",
|
|
456
|
+
"gt",
|
|
457
|
+
"gte",
|
|
458
|
+
"lt",
|
|
459
|
+
"lte",
|
|
460
|
+
"in"
|
|
461
|
+
];
|
|
462
|
+
const RANGE_OPS = [
|
|
463
|
+
"gt",
|
|
464
|
+
"gte",
|
|
465
|
+
"lt",
|
|
466
|
+
"lte"
|
|
467
|
+
];
|
|
468
|
+
/**
|
|
469
|
+
* Validate a normalised predicate wire. Throws
|
|
470
|
+
* `BaerlyError{code:"InvalidConfig"}` on a structurally bad clause,
|
|
471
|
+
* or `BaerlyError{code:"UnsatisfiablePredicate"}` when a clause
|
|
472
|
+
* group on one field contradicts itself.
|
|
473
|
+
*
|
|
474
|
+
* Returns the wire unchanged on success — callers can thread the
|
|
475
|
+
* validated wire forward.
|
|
476
|
+
*
|
|
477
|
+
* @example
|
|
478
|
+
* ```ts
|
|
479
|
+
* validateWire({ clauses: [{ op: "eq", field: "status", value: "open" }] }); // ok
|
|
480
|
+
* validateWire({ clauses: [{ op: "in", field: "priority", value: [] }] }); // throws UnsatisfiablePredicate
|
|
481
|
+
* validateWire({ clauses: [{ op: "eq", field: "_id", value: "x" }] }); // throws InvalidConfig (top-level _id)
|
|
482
|
+
* ```
|
|
483
|
+
*/
|
|
484
|
+
const validateWire = (wire) => {
|
|
485
|
+
if (wire === null || typeof wire !== "object" || !Array.isArray(wire.clauses)) throw new BaerlyError("InvalidConfig", `Predicate wire must be an object with a "clauses" array.`);
|
|
486
|
+
for (let i = 0; i < wire.clauses.length; i++) validateClause(wire.clauses[i], i);
|
|
487
|
+
assertWireSatisfiable(wire);
|
|
488
|
+
return wire;
|
|
489
|
+
};
|
|
490
|
+
const validateClause = (clause, index) => {
|
|
491
|
+
if (clause === null || typeof clause !== "object") throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} must be an object — got ${JSON.stringify(clause)}.`);
|
|
492
|
+
const { op, field, value } = clause;
|
|
493
|
+
if (typeof op !== "string" || !OP_NAMES.includes(op)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} has unsupported op ${JSON.stringify(op)} — supported: ${OP_NAMES.join(" / ")}.`);
|
|
494
|
+
if (typeof field !== "string" || field.length === 0) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} has empty / non-string field.`);
|
|
495
|
+
if (field === "_id" || field.startsWith("_id.")) throw new BaerlyError("InvalidConfig", "Predicates may not key on \"_id\"; use .get(id) / .update(id, patch) / .replace(id, doc) / .delete(id) instead.");
|
|
496
|
+
if (op === "in") {
|
|
497
|
+
if (!Array.isArray(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} (op="in", field=${JSON.stringify(field)}) must carry an array value.`);
|
|
498
|
+
if (value.length === 0) throw new BaerlyError("UnsatisfiablePredicate", `Predicate clause at index ${index} (op="in", field=${JSON.stringify(field)}) has empty value array — no document can match.`);
|
|
499
|
+
for (let i = 0; i < value.length; i++) validateMemberValue(value[i], field, index, i);
|
|
500
|
+
return;
|
|
501
|
+
}
|
|
502
|
+
if (Array.isArray(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${index} (op=${JSON.stringify(op)}, field=${JSON.stringify(field)}) must carry a primitive value, got an array — only op="in" accepts arrays.`);
|
|
503
|
+
if (RANGE_OPS.includes(op)) {
|
|
504
|
+
validateRangeBound(value, field, index);
|
|
505
|
+
return;
|
|
506
|
+
}
|
|
507
|
+
validateScalar(value, field, index);
|
|
508
|
+
};
|
|
509
|
+
const validateMemberValue = (value, field, clauseIndex, memberIndex) => {
|
|
510
|
+
if (value === null || value === void 0) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (op="in", field=${JSON.stringify(field)}) member ${memberIndex} is ${value === null ? "null" : "undefined"} — members must be string / number / boolean / nested object.`);
|
|
511
|
+
if (Array.isArray(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (op="in", field=${JSON.stringify(field)}) member ${memberIndex} is an array — members must be string / number / boolean / nested object.`);
|
|
512
|
+
const t = typeof value;
|
|
513
|
+
if (t === "object") return;
|
|
514
|
+
if (t !== "string" && t !== "number" && t !== "boolean") throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (op="in", field=${JSON.stringify(field)}) member ${memberIndex} has unsupported type ${JSON.stringify(t)} — must be string / number / boolean / nested object.`);
|
|
515
|
+
if (t === "number" && !Number.isFinite(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (op="in", field=${JSON.stringify(field)}) member ${memberIndex} is ${String(value)} — finite numbers only (NaN / Infinity do not round-trip through JSON).`);
|
|
516
|
+
};
|
|
517
|
+
const validateScalar = (value, field, clauseIndex) => {
|
|
518
|
+
if (value === null || value === void 0) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (field=${JSON.stringify(field)}) value is ${value === null ? "null" : "undefined"} — terminal values must be string / number / boolean / nested object.`);
|
|
519
|
+
const t = typeof value;
|
|
520
|
+
if (t === "object") return;
|
|
521
|
+
if (t !== "string" && t !== "number" && t !== "boolean") throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (field=${JSON.stringify(field)}) value has unsupported type ${JSON.stringify(t)} — must be string / number / boolean / nested object.`);
|
|
522
|
+
if (t === "number" && !Number.isFinite(value)) throw new BaerlyError("InvalidConfig", `Predicate clause at index ${clauseIndex} (field=${JSON.stringify(field)}) value is ${String(value)} — finite numbers only (NaN / Infinity do not round-trip through JSON).`);
|
|
523
|
+
};
|
|
524
|
+
const validateRangeBound = (value, field, clauseIndex) => {
|
|
525
|
+
if (value === null || value === void 0) throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) is ${value === null ? "null" : "undefined"} — range bounds must be string or finite number.`);
|
|
526
|
+
const t = typeof value;
|
|
527
|
+
if (t === "boolean") throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) is a boolean — range bounds must be string or finite number (booleans are not ordered).`);
|
|
528
|
+
if (t === "object") throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) is a nested object — range bounds must be string or finite number.`);
|
|
529
|
+
if (t !== "string" && t !== "number") throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) has unsupported type ${JSON.stringify(t)} — must be string or finite number.`);
|
|
530
|
+
if (t === "number" && !Number.isFinite(value)) throw new BaerlyError("InvalidConfig", `Predicate range bound at clause ${clauseIndex} (field=${JSON.stringify(field)}) is ${String(value)} — finite numbers only (NaN / Infinity do not round-trip through JSON).`);
|
|
531
|
+
};
|
|
532
|
+
// packages/server/src/doc-id.ts
|
|
533
|
+
/**
|
|
534
|
+
* Resolution for a non-NFC `_id`. A row stored under one by an earlier
|
|
535
|
+
* release stays readable and deletable, so it is migrated by copy.
|
|
536
|
+
*/
|
|
537
|
+
const DOC_ID_NFC_RESOLUTION = "Pass id.normalize(\"NFC\") for a new _id. To migrate a stored non-NFC row, insert a copy under a fresh NFC id that is not canonically equivalent to the original (for example, omit _id for a UUID), then delete the original.";
|
|
538
|
+
/**
|
|
539
|
+
* Resolution for an `_id` with an unpaired surrogate. A row stored under
|
|
540
|
+
* one by an earlier release stays readable and deletable in-process, so it
|
|
541
|
+
* is migrated by copy.
|
|
542
|
+
*/
|
|
543
|
+
const DOC_ID_WELL_FORMED_RESOLUTION = "Pass an _id with no unpaired UTF-16 surrogate (id.isWellFormed() is true), or omit _id for a UUID. To migrate a stored row with such an _id, read it by _id, remove _id from the copy so insert generates a fresh UUID, then delete the original.";
|
|
544
|
+
/**
|
|
545
|
+
* Resolution for a point read whose id no row can be stored under.
|
|
546
|
+
*/
|
|
547
|
+
const READ_ID_RESOLUTION = "Pass the _id string of a stored row. A valid _id is non-empty, at most 256 UTF-8 bytes, has no \"/\" or control characters, does not start with \"_\", and is not \".\" or \"..\".";
|
|
548
|
+
/**
|
|
549
|
+
* Guard an `_id` a write is about to store a row under: an insert, a
|
|
550
|
+
* replace, an update, or any `I` / `U` commit. The `_id` analogue of
|
|
551
|
+
* `assertKeySegment` (`db.ts`).
|
|
552
|
+
*
|
|
553
|
+
* Applies {@link assertStoredDocId}, then requires the id to be
|
|
554
|
+
* well-formed UTF-16 (no unpaired surrogate, which no URL or S3 key can
|
|
555
|
+
* carry) and in Unicode Normalization Form C (`id === id.normalize("NFC")`),
|
|
556
|
+
* so each canonical-equivalence class (NFC `é` and NFD `e` + U+0301) has one
|
|
557
|
+
* spelling and one byte form. R2 stores canonically-equivalent keys as one
|
|
558
|
+
* object, so any object a future format keys by `_id` (an index-aware
|
|
559
|
+
* snapshot, say) would otherwise merge two rows whose ids differ only by
|
|
560
|
+
* normalization; the rule keeps that door open, and loosening it later is
|
|
561
|
+
* not a breaking change. Case and compatibility variants (`A` / `a`, `fi` / `fi`)
|
|
562
|
+
* are distinct NFC strings and stay distinct ids.
|
|
563
|
+
*
|
|
564
|
+
* @throws BaerlyError code="InvalidConfig" — the id breaks the key-segment
|
|
565
|
+
* rule, holds an unpaired surrogate, or is not NFC.
|
|
566
|
+
*/
|
|
567
|
+
const assertDocId = (id) => {
|
|
568
|
+
assertStoredDocId(id);
|
|
569
|
+
assertWellFormedSegment(id, "_id", "", DOC_ID_WELL_FORMED_RESOLUTION);
|
|
570
|
+
assertNfcSegment(id, "_id", "", DOC_ID_NFC_RESOLUTION);
|
|
571
|
+
};
|
|
572
|
+
/**
|
|
573
|
+
* Guard an `_id` that names an existing row: the `doc_id` of a delete.
|
|
574
|
+
* Only the key-segment rule applies (the single shared
|
|
575
|
+
* {@link assertPathSegment}: empty / `"/"` / `"."`|`".."` / C0-C1 control
|
|
576
|
+
* chars / leading `"_"` (ADR-003) / overlong, all as
|
|
577
|
+
* `BaerlyError{code:"InvalidConfig"}`), so a row stored under a non-NFC
|
|
578
|
+
* id, or an id with an unpaired surrogate, before {@link assertDocId}
|
|
579
|
+
* refused them can still be deleted.
|
|
580
|
+
*/
|
|
581
|
+
const assertStoredDocId = (id) => {
|
|
582
|
+
assertPathSegment(id, "_id");
|
|
583
|
+
};
|
|
584
|
+
/**
|
|
585
|
+
* Guard the `id` of a point read (`Collection.get`, `GET
|
|
586
|
+
* /v1/c/:collection/:id`) before any I/O. Applies the stored-id rule
|
|
587
|
+
* ({@link assertStoredDocId}), not the NFC or well-formed write rules, so
|
|
588
|
+
* a row an earlier release stored under such an id stays readable. The error is marked
|
|
589
|
+
* caller-facing so HTTP returns its message with the 400.
|
|
590
|
+
*
|
|
591
|
+
* @throws BaerlyError code="InvalidConfig" — `id` is not a string or breaks
|
|
592
|
+
* the key-segment rule.
|
|
593
|
+
*/
|
|
594
|
+
const assertReadDocId = (id) => {
|
|
595
|
+
let message;
|
|
596
|
+
if (typeof id !== "string") message = `get: _id must be a string, got ${typeof id}`;
|
|
597
|
+
else try {
|
|
598
|
+
assertPathSegment(id, "_id", "get");
|
|
599
|
+
} catch (error) {
|
|
600
|
+
if (!(error instanceof BaerlyError)) throw error;
|
|
601
|
+
message = error.message;
|
|
602
|
+
}
|
|
603
|
+
if (message !== void 0) throw markCallerFacing(new BaerlyError("InvalidConfig", message, { resolution: READ_ID_RESOLUTION }));
|
|
604
|
+
};
|
|
605
|
+
/**
|
|
606
|
+
* The `AlreadyExists` an insert throws when a live row holds `docId`.
|
|
607
|
+
* Shared by `runInsert`'s check read (`./query.ts`) and the writer's
|
|
608
|
+
* insert guard (`./writer.ts`), so a caller sees one error whichever
|
|
609
|
+
* side caught the collision. Not retriable; `err._id` is `docId`.
|
|
610
|
+
*/
|
|
611
|
+
const insertAlreadyExists = (collection, docId) => new BaerlyError("AlreadyExists", `insert: _id ${JSON.stringify(docId)} already exists in collection ${JSON.stringify(collection)}`, {
|
|
612
|
+
resolution: CODE_RESOLUTIONS.AlreadyExists,
|
|
613
|
+
_id: docId
|
|
614
|
+
});
|
|
615
|
+
/**
|
|
616
|
+
* `true` when the stored live row `stored` is the row an insert of `body`
|
|
617
|
+
* would have written: structurally equal after the JSON round-trip the
|
|
618
|
+
* write path's encoder applies (key order ignored, `undefined` properties
|
|
619
|
+
* dropped). `body` is the insert's post-image `{ ...doc, _id }`; the
|
|
620
|
+
* stored row carries no other server-stamped field (log metadata lives on
|
|
621
|
+
* the `LogEntry`, not in `after`).
|
|
622
|
+
*
|
|
623
|
+
* Shared by `runInsert`'s check read and the writer's insert guard, so an
|
|
624
|
+
* SDK-minted insert replays on the same rule whichever side found the row.
|
|
625
|
+
*/
|
|
626
|
+
const insertReplaysRow = (body, stored) => stored !== void 0 && jsonValueEqual(JSON.parse(JSON.stringify(body)), stored);
|
|
627
|
+
/**
|
|
628
|
+
* Count an SDK-minted insert answered as a replay of its stored row on
|
|
629
|
+
* `db.write.insert_replayed_total` (labelled by `collection`). A replay
|
|
630
|
+
* commits nothing and records no write metric, so without this counter it
|
|
631
|
+
* is invisible on the canonical line. Shared by `runInsert`'s check read
|
|
632
|
+
* and the writer's insert guard, the two places a replay is decided.
|
|
633
|
+
*/
|
|
634
|
+
const recordInsertReplay = (collection) => {
|
|
635
|
+
getCurrentContext()?.recorder.counter("db.write.insert_replayed_total", 1, { collection });
|
|
636
|
+
};
|
|
637
|
+
// packages/server/src/capacity.ts
|
|
638
|
+
/**
|
|
639
|
+
* Growth refusal at the host's fold ceiling (main-10, rulings G3–G5, G7).
|
|
640
|
+
*
|
|
641
|
+
* The in-band fold can only rebuild a snapshot within the serving host's
|
|
642
|
+
* ceilings: `E` rows (`maxFoldRows`) and `C` bytes (`maxFoldBytes`, or
|
|
643
|
+
* `BAERLY_MAINTENANCE_MAX_FOLD_BYTES`). `compact()` folds the longest
|
|
644
|
+
* prefix of the tail that keeps the snapshot within `E` rows, so it stops
|
|
645
|
+
* at the first entry that would add a row to an `E`-row snapshot, and of
|
|
646
|
+
* that, the longest prefix of its pass that rebuilds within `C` bytes. Past
|
|
647
|
+
* a point no pass can fold, nothing folds, and every read pays one GET per
|
|
648
|
+
* pending tail entry.
|
|
649
|
+
* The write verbs call {@link capacityDecision} after their pre-commit read
|
|
650
|
+
* and before any commit, so a refused write commits nothing, and again
|
|
651
|
+
* inside each commit, before its `log/<seq>` create, whenever another
|
|
652
|
+
* write landed since that read, so concurrent growth writes that each
|
|
653
|
+
* passed cannot together pass the ceiling (G5-race).
|
|
654
|
+
*
|
|
655
|
+
* The decision is a pure function of the state that read already loaded
|
|
656
|
+
* (`current.json`, the snapshot rows, the pending tail) plus the planned
|
|
657
|
+
* writes. Nothing is persisted, so the refusal clears as soon as that
|
|
658
|
+
* state changes.
|
|
659
|
+
*
|
|
660
|
+
* An admitted write that leaves the collection within
|
|
661
|
+
* `CAPACITY_WARN_FRACTION` of that point carries a warning (G7), computed
|
|
662
|
+
* from the same state, so it too needs no persisted flag.
|
|
663
|
+
*
|
|
664
|
+
* Near the ceiling the verbs also drive the fold (G6): an accepted write
|
|
665
|
+
* that leaves the collection at its growth-refusal point forces its
|
|
666
|
+
* write tick, and a refused growth write whose room the pending tail
|
|
667
|
+
* would free dispatches one forced fold and refuses with
|
|
668
|
+
* `MaintenancePending` instead of `CapacityExceeded`.
|
|
669
|
+
*/
|
|
670
|
+
/**
|
|
671
|
+
* The fold ceilings and pass size of the host serving this request,
|
|
672
|
+
* resolved as the write-tick runner resolves them
|
|
673
|
+
* ({@link resolveFoldCeilings}, absent profile ⇒ cf-free) so refusal and
|
|
674
|
+
* folding always agree.
|
|
675
|
+
*/
|
|
676
|
+
const currentFoldCeilings = () => {
|
|
677
|
+
const maint = getCurrentContext()?.maintenance;
|
|
678
|
+
const profile = maint?.options?.profile;
|
|
679
|
+
return {
|
|
680
|
+
...resolveFoldCeilings(profile, maint?.maxFoldBytes),
|
|
681
|
+
maxFoldEntriesPerPass: (profile ?? MAINTENANCE_PROFILE_CF_FREE).maxFoldEntriesPerPass
|
|
682
|
+
};
|
|
683
|
+
};
|
|
684
|
+
/**
|
|
685
|
+
* The refusal message names the state and the app-side remedy only. The
|
|
686
|
+
* host-side route (a larger maintenance profile) is an operator decision:
|
|
687
|
+
* it reaches operators through the `fold_deferred` log line and
|
|
688
|
+
* `graduation.md`, never the app-authoring surface, so an agent reading
|
|
689
|
+
* this error is not invited to retune a host setting.
|
|
690
|
+
*/
|
|
691
|
+
const refuse = (message) => new BaerlyError("CapacityExceeded", message, { resolution: CODE_RESOLUTIONS.CapacityExceeded });
|
|
692
|
+
/**
|
|
693
|
+
* Growth (G3): an insert, or an update whose post-image encodes larger
|
|
694
|
+
* than the row's current body. An update with no known `before` counts as
|
|
695
|
+
* growth, which fails closed.
|
|
696
|
+
*/
|
|
697
|
+
const isGrowth = (write) => {
|
|
698
|
+
if (write.op === "I") return true;
|
|
699
|
+
if (write.op === "D" || write.after === void 0) return false;
|
|
700
|
+
return write.before === void 0 || rowBytes(write.docId, write.after) > rowBytes(write.docId, write.before);
|
|
701
|
+
};
|
|
702
|
+
/**
|
|
703
|
+
* Backpressure for a refused growth write whose room the pending tail
|
|
704
|
+
* frees once it folds (G6). Like `CapacityExceeded`, it names the state
|
|
705
|
+
* and the app-side remedy only.
|
|
706
|
+
*/
|
|
707
|
+
const maintenancePending = (collection) => new BaerlyError("MaintenancePending", `collection ${JSON.stringify(collection)} is waiting on maintenance: this write would grow it past what this host can fold until the pending changes fold, so it was refused and not committed (rows a batch committed before it are kept). Retry after 1s.`, {
|
|
708
|
+
resolution: CODE_RESOLUTIONS.MaintenancePending,
|
|
709
|
+
retryAfter: 1
|
|
710
|
+
});
|
|
711
|
+
/** Canonical-line field carrying {@link CapacityWarning.text}. */
|
|
712
|
+
const CAPACITY_WARNING_FIELD = "capacity_warning";
|
|
713
|
+
/**
|
|
714
|
+
* The warning for a projection peaking at `peakRows` / `peakBytes`, or
|
|
715
|
+
* `undefined` while both dimensions sit under `CAPACITY_WARN_FRACTION` of
|
|
716
|
+
* their limits. The more-used dimension is reported. The text names the
|
|
717
|
+
* state and the app-side remedy only, like the refusal it precedes.
|
|
718
|
+
*/
|
|
719
|
+
const warningFor = (peakRows, peakBytes, maxRows, byteLimit) => {
|
|
720
|
+
const rowFraction = peakRows / maxRows;
|
|
721
|
+
const byteFraction = peakBytes / byteLimit;
|
|
722
|
+
const rows = rowFraction >= byteFraction;
|
|
723
|
+
const fraction = rows ? rowFraction : byteFraction;
|
|
724
|
+
if (!(fraction >= .9) || !Number.isFinite(fraction)) return;
|
|
725
|
+
const used = rows ? peakRows : peakBytes;
|
|
726
|
+
const limit = rows ? maxRows : byteLimit;
|
|
727
|
+
const percent = Math.floor(fraction * 100);
|
|
728
|
+
return {
|
|
729
|
+
dimension: rows ? "rows" : "bytes",
|
|
730
|
+
used,
|
|
731
|
+
limit,
|
|
732
|
+
text: `this collection is at ${percent}% of what this host can hold (${used} of ${limit} ${rows ? "rows" : "bytes"}); inserts and growing updates will be refused at the limit. Delete rows or shrink documents to make room, or export with baerly admin dump.`
|
|
733
|
+
};
|
|
734
|
+
};
|
|
735
|
+
/**
|
|
736
|
+
* Stamp `warning` on the request's canonical line (and so the log record)
|
|
737
|
+
* under {@link CAPACITY_WARNING_FIELD}. The HTTP router copies the same
|
|
738
|
+
* text onto the write response. A no-op without a request context, as for
|
|
739
|
+
* any field setter.
|
|
740
|
+
*/
|
|
741
|
+
const noteCapacityWarning = (warning) => {
|
|
742
|
+
getCurrentContext()?.fields.set(CAPACITY_WARNING_FIELD, warning.text);
|
|
743
|
+
};
|
|
744
|
+
/**
|
|
745
|
+
* Decide whether `writes` must be refused on the host with `ceilings`.
|
|
746
|
+
*
|
|
747
|
+
* - **No progress** (G5): the stored snapshot is over `E` rows or `C`
|
|
748
|
+
* bytes, or the pending tail holds an entry the fold stops at (one that
|
|
749
|
+
* adds a row while the projected snapshot holds `E` rows), or
|
|
750
|
+
* `maxFoldEntriesPerPass` consecutive pending seqs whose folded snapshot
|
|
751
|
+
* each rebuilds past `C`, a run no fold pass can cross. Every write is
|
|
752
|
+
* refused, since anything appended behind that point never folds on this
|
|
753
|
+
* host. A write that would itself complete such a run is refused too.
|
|
754
|
+
* - **Growth** (an insert or a byte-growing update, G3): refused when the
|
|
755
|
+
* projected snapshot, at its peak over every prefix of the pending tail
|
|
756
|
+
* followed by the planned writes up to this one, would reach `E` rows or
|
|
757
|
+
* exceed `C - CAPACITY_BYTES_MARGIN` bytes (G4). The peak counts because
|
|
758
|
+
* a fold can land at any prefix. `foldFreesRoom` (G6) is set when the
|
|
759
|
+
* same writes would be admitted onto the snapshot the whole pending tail
|
|
760
|
+
* folds to, and the whole tail folds within `C`, so folds alone admit
|
|
761
|
+
* the writes.
|
|
762
|
+
* - Anything else (deletes, same-size and shrinking updates) commits, at
|
|
763
|
+
* `E` rows included: the fold drains them in place. `pressure` reports
|
|
764
|
+
* whether the commit forces its write tick (see `forcesTick` inside).
|
|
765
|
+
*
|
|
766
|
+
* A batch is decided whole, before its first row commits. The verbs
|
|
767
|
+
* re-run the decision at each commit over the entries that landed since
|
|
768
|
+
* (G5-race, `admitWrites` in `./query.ts`), for the writes not yet
|
|
769
|
+
* committed.
|
|
770
|
+
*
|
|
771
|
+
* @param head `current.json` as the pre-commit read saw it.
|
|
772
|
+
* @param base The snapshot rows that read loaded (`docId → body`).
|
|
773
|
+
* @param tail Every log entry that read folded on top of `base`, in order.
|
|
774
|
+
*/
|
|
775
|
+
const capacityDecision = (args) => {
|
|
776
|
+
const { collection, head, base, tail, writes, ceilings } = args;
|
|
777
|
+
if (writes.length === 0) return {
|
|
778
|
+
refusal: void 0,
|
|
779
|
+
pressure: false
|
|
780
|
+
};
|
|
781
|
+
const { maxFoldRows: maxRows, maxFoldBytes: maxBytes } = ceilings;
|
|
782
|
+
const byteLimit = maxBytes - 64;
|
|
783
|
+
const noProgress = (why) => ({
|
|
784
|
+
refusal: refuse(`collection ${JSON.stringify(collection)} has outgrown this host (${why}): no fold can make progress here, so every write is refused and reads keep working. The collection needs a larger host or graduation; export it with baerly admin dump.`),
|
|
785
|
+
foldFreesRoom: false
|
|
786
|
+
});
|
|
787
|
+
if (!isFoldViable(head.snapshot_bytes, head.snapshot_rows, ceilings)) return noProgress(`${head.snapshot_rows} rows of ${maxRows}, ${head.snapshot_bytes} bytes of ${maxBytes}`);
|
|
788
|
+
const own = tail.filter((entry) => isOwnCollection(entry.collection, collection));
|
|
789
|
+
const projection = projectSnapshot(head, base, collection);
|
|
790
|
+
const pass = ceilings.maxFoldEntriesPerPass;
|
|
791
|
+
let overRun = 0;
|
|
792
|
+
for (const [i, entry] of tail.entries()) {
|
|
793
|
+
if (isOwnCollection(entry.collection, collection)) {
|
|
794
|
+
if (projection.addsRow(entry.op, entry.doc_id, entry.after) && !(projection.rows < maxRows)) return noProgress(`a pending insert cannot fold onto ${projection.rows} rows of ${maxRows}`);
|
|
795
|
+
projection.apply(entry.op, entry.doc_id, entry.after);
|
|
796
|
+
}
|
|
797
|
+
overRun = projection.bytesAt(head.log_seq_start + i + 1) <= maxBytes ? 0 : overRun + 1;
|
|
798
|
+
if (!(overRun < pass)) return noProgress(`${overRun} pending entries in a row each leave the snapshot past ${maxBytes} bytes`);
|
|
799
|
+
}
|
|
800
|
+
const tailLands = overRun === 0;
|
|
801
|
+
/**
|
|
802
|
+
* Whether an accepted batch forces its write tick (G6), given `p` with
|
|
803
|
+
* the tail and the writes applied. Only at the refusal point (one more
|
|
804
|
+
* inserted row, or one more byte of growth, would be refused), and then
|
|
805
|
+
* only when that fold is worth its full snapshot rebuild:
|
|
806
|
+
*
|
|
807
|
+
* - folding the pending tail frees room for growth (the snapshot it
|
|
808
|
+
* rebuilds to admits one more row and byte), or
|
|
809
|
+
* - the pending tail, these writes included, holds a full pass
|
|
810
|
+
* (`maxFoldEntriesPerPass`).
|
|
811
|
+
*
|
|
812
|
+
* Otherwise the runner's ratio trigger and entry floor apply as usual.
|
|
813
|
+
* The pass floor is the cheapest cadence that keeps the tail bounded at
|
|
814
|
+
* the ceiling: every pending entry costs each read one GET, and on
|
|
815
|
+
* Workers Free the ratio trigger alone would let a collection held at
|
|
816
|
+
* `E - 1` by same-size updates queue ~300 entries. One forced fold per
|
|
817
|
+
* pass also bounds the rebuild cost to one full snapshot per
|
|
818
|
+
* `maxFoldEntriesPerPass` writes, rather than one per write, and with it
|
|
819
|
+
* the snapshots each rebuild orphans: on cf-free that is under one
|
|
820
|
+
* orphan (20-entry pass) per hard-GC interval of 16 writes, against that
|
|
821
|
+
* slice's sweep budget of 10, so GC keeps up even though a forced fold
|
|
822
|
+
* is the tick's only phase.
|
|
823
|
+
*/
|
|
824
|
+
const forcesTick = (p) => {
|
|
825
|
+
if (!(!(Math.max(p.peakRows, p.rows + 1) < maxRows) || !(p.peakBytes < byteLimit))) return false;
|
|
826
|
+
if (!tailLands) return false;
|
|
827
|
+
return p.rows + 1 < maxRows && p.bytes < byteLimit || tail.length + writes.length >= pass;
|
|
828
|
+
};
|
|
829
|
+
/**
|
|
830
|
+
* The first write `p` refuses, applying every write onto `p` from a
|
|
831
|
+
* state `overRun` seqs into a run over `C`: a growth write past the
|
|
832
|
+
* growth limit, or any write that would complete a wall of `pass` seqs
|
|
833
|
+
* over `C` (`stranded`), which it would itself sit behind.
|
|
834
|
+
*/
|
|
835
|
+
const firstRefused = (p, run) => {
|
|
836
|
+
for (const [j, write] of writes.entries()) {
|
|
837
|
+
const growth = isGrowth(write);
|
|
838
|
+
p.apply(write.op, write.docId, write.after);
|
|
839
|
+
if (growth && (!(p.peakRows < maxRows) || !(p.peakBytes <= byteLimit))) return {
|
|
840
|
+
write,
|
|
841
|
+
stranded: false
|
|
842
|
+
};
|
|
843
|
+
run = p.bytesAt(head.log_seq_start + tail.length + j + 1) <= maxBytes ? 0 : run + 1;
|
|
844
|
+
if (!(run < pass)) return {
|
|
845
|
+
write,
|
|
846
|
+
stranded: true
|
|
847
|
+
};
|
|
848
|
+
}
|
|
849
|
+
};
|
|
850
|
+
const first = firstRefused(projection, overRun);
|
|
851
|
+
if (first === void 0) {
|
|
852
|
+
const warning = warningFor(projection.peakRows, projection.peakBytes, maxRows, byteLimit);
|
|
853
|
+
return {
|
|
854
|
+
refusal: void 0,
|
|
855
|
+
pressure: forcesTick(projection),
|
|
856
|
+
...warning !== void 0 && { warning }
|
|
857
|
+
};
|
|
858
|
+
}
|
|
859
|
+
if (first.stranded) return {
|
|
860
|
+
refusal: refuse(`collection ${JSON.stringify(collection)} is waiting on changes this host cannot fold: the pending changes leave it past ${maxBytes} bytes, and this write would leave them stuck there for good, so it was refused and not committed (rows a batch committed before it are kept). A write that brings the collection back within ${maxBytes} bytes still commits; otherwise it needs a larger host or graduation.`),
|
|
861
|
+
foldFreesRoom: false
|
|
862
|
+
};
|
|
863
|
+
const refused = first.write;
|
|
864
|
+
const { peakRows, peakBytes } = projection;
|
|
865
|
+
const detail = !(peakRows < maxRows) ? `${peakRows} rows would reach the ${maxRows}-row ceiling` : `${peakBytes} bytes would pass the ${maxBytes}-byte ceiling`;
|
|
866
|
+
const refusal = refuse(`collection ${JSON.stringify(collection)} is full on this host: ${detail}, so this ${refused.op === "I" ? "insert" : "growing update"} was refused and not committed (rows a batch committed before it are kept). Deletes and same-size or shrinking updates still commit; delete or shrink rows to make room. If the collection must keep growing, it needs a larger host or graduation.`);
|
|
867
|
+
if (own.length === 0 || !tailLands) return {
|
|
868
|
+
refusal,
|
|
869
|
+
foldFreesRoom: false
|
|
870
|
+
};
|
|
871
|
+
const settled = projectSnapshot(head, base, collection);
|
|
872
|
+
for (const entry of own) settled.apply(entry.op, entry.doc_id, entry.after);
|
|
873
|
+
settled.settle(head.log_seq_start + tail.length);
|
|
874
|
+
return {
|
|
875
|
+
refusal,
|
|
876
|
+
foldFreesRoom: firstRefused(settled, 0) === void 0
|
|
877
|
+
};
|
|
878
|
+
};
|
|
879
|
+
// packages/server/src/query-eval.ts
|
|
880
|
+
/**
|
|
881
|
+
* In-memory query evaluation over a folded row map: the predicate
|
|
882
|
+
* filter, the counting pass, `order` with its bounded top-k, and the
|
|
883
|
+
* `limit` cut. `runReadRows`
|
|
884
|
+
* (`./query.ts`) calls these after the snapshot + log fold; they do no
|
|
885
|
+
* I/O.
|
|
886
|
+
*/
|
|
887
|
+
/**
|
|
888
|
+
* The rows of `docs` that satisfy `wire`, in map order, built in one pass.
|
|
889
|
+
* With no predicate, every row.
|
|
890
|
+
*/
|
|
891
|
+
const filterRows = (docs, wire) => {
|
|
892
|
+
if (wire === void 0) return Array.from(docs, ([docId, doc]) => ({
|
|
893
|
+
docId,
|
|
894
|
+
doc
|
|
895
|
+
}));
|
|
896
|
+
const matches = compileWire(wire);
|
|
897
|
+
const rows = [];
|
|
898
|
+
for (const [docId, doc] of docs) if (matches(doc)) rows.push({
|
|
899
|
+
docId,
|
|
900
|
+
doc
|
|
901
|
+
});
|
|
902
|
+
return rows;
|
|
903
|
+
};
|
|
904
|
+
/** How many rows of `docs` satisfy `wire`, without materialising them. */
|
|
905
|
+
const countMatches = (docs, wire) => {
|
|
906
|
+
if (wire === void 0) return docs.size;
|
|
907
|
+
const matches = compileWire(wire);
|
|
908
|
+
let count = 0;
|
|
909
|
+
for (const doc of docs.values()) if (matches(doc)) count++;
|
|
910
|
+
return count;
|
|
911
|
+
};
|
|
912
|
+
/**
|
|
913
|
+
* How many of `n` rows `limit` keeps: the length `rows.slice(0, limit)`
|
|
914
|
+
* would have. Both the row path (which truncates to it) and the count
|
|
915
|
+
* use it, so a count honours `limit` exactly as `all()` does, including
|
|
916
|
+
* a fractional or negative `limit` (`slice` truncates it, and counts a
|
|
917
|
+
* negative end from the back).
|
|
918
|
+
*/
|
|
919
|
+
const limitedLength = (n, limit) => {
|
|
920
|
+
if (limit === void 0 || !(limit < n)) return n;
|
|
921
|
+
const end = Math.trunc(limit) || 0;
|
|
922
|
+
return end < 0 ? Math.max(n + end, 0) : end;
|
|
923
|
+
};
|
|
924
|
+
/**
|
|
925
|
+
* Compare two primitive order-key values under one direction, as
|
|
926
|
+
* {@link sortByOrderSpec} does: a missing value sorts low under `asc`
|
|
927
|
+
* and high under `desc`; otherwise `<`. {@link orderRows} calls it only
|
|
928
|
+
* once its pre-scan has ruled out objects and `null`.
|
|
929
|
+
*/
|
|
930
|
+
const compareKey = (a, b, desc) => {
|
|
931
|
+
if (a === b) return 0;
|
|
932
|
+
if (a === void 0) return desc ? 1 : -1;
|
|
933
|
+
if (b === void 0) return desc ? -1 : 1;
|
|
934
|
+
const cmp = a < b ? -1 : 1;
|
|
935
|
+
return desc ? -cmp : cmp;
|
|
936
|
+
};
|
|
937
|
+
/**
|
|
938
|
+
* Stable multi-key sort built from an `OrderSpec`. Keys are taken in
|
|
939
|
+
* the spec's insertion order, which matches the caller's source-order
|
|
940
|
+
* expectation. `Array.prototype.sort` is stable on Node 26+ and Workerd.
|
|
941
|
+
*
|
|
942
|
+
* Top-level fields only (locked at `OrderSpec<T>`).
|
|
943
|
+
* Values are `DocumentValue` — string / number / boolean / object —
|
|
944
|
+
* but only the primitive types are sensibly orderable; comparing two
|
|
945
|
+
* objects falls through to "considered equal," which preserves the
|
|
946
|
+
* stable-sort order of the input.
|
|
947
|
+
*/
|
|
948
|
+
const sortByOrderSpec = (rows, spec) => {
|
|
949
|
+
const entries = Object.entries(spec);
|
|
950
|
+
return rows.toSorted((a, b) => {
|
|
951
|
+
for (const [field, dir] of entries) {
|
|
952
|
+
const av = a.doc[field];
|
|
953
|
+
const bv = b.doc[field];
|
|
954
|
+
if (av === bv) continue;
|
|
955
|
+
if (av === void 0) return dir === "desc" ? 1 : -1;
|
|
956
|
+
if (bv === void 0) return dir === "desc" ? -1 : 1;
|
|
957
|
+
if (typeof av === "object" || typeof bv === "object") continue;
|
|
958
|
+
const cmp = av < bv ? -1 : 1;
|
|
959
|
+
return dir === "desc" ? -cmp : cmp;
|
|
960
|
+
}
|
|
961
|
+
return 0;
|
|
962
|
+
});
|
|
963
|
+
};
|
|
964
|
+
/**
|
|
965
|
+
* `sortByOrderSpec(rows, spec)` cut by `limit` as the row path cuts it,
|
|
966
|
+
* without sorting every row when `limit` is small.
|
|
967
|
+
*
|
|
968
|
+
* The bounded path runs when `limit` is an integer in
|
|
969
|
+
* `[1, QUERY_TOP_K_MAX]` below `rows.length` (PostgreSQL's bounded
|
|
970
|
+
* top-N heapsort for `ORDER BY … LIMIT` has the same shape). One O(n)
|
|
971
|
+
* pass checks that each order key holds a single primitive type (plus
|
|
972
|
+
* missing values), under which the comparator is a total preorder; a
|
|
973
|
+
* key holding objects, `null` or mixed types falls back to the full
|
|
974
|
+
* sort, whose comparator is not transitive there. The same pass
|
|
975
|
+
* compares adjacent rows:
|
|
976
|
+
*
|
|
977
|
+
* - No row orders before its predecessor: the input is already in
|
|
978
|
+
* order, so the first `limit` rows are the answer.
|
|
979
|
+
* - No row orders after its predecessor: the input is in reverse order,
|
|
980
|
+
* so the answer is read from the end, keeping tied rows in input
|
|
981
|
+
* order.
|
|
982
|
+
* - Otherwise a max-heap keeps the best `limit` rows under the
|
|
983
|
+
* comparator, ties broken by input index, which is the stable sort's
|
|
984
|
+
* order. The heap's result does not depend on the order rows are fed
|
|
985
|
+
* in, so it reads the input from the end when more compared adjacent
|
|
986
|
+
* pairs fall than rise (later rows ordering first), which keeps root
|
|
987
|
+
* replacements rare on nearly reversed input.
|
|
988
|
+
*
|
|
989
|
+
* The output is identical to `sortByOrderSpec(rows, spec).slice(0, limit)`.
|
|
990
|
+
*/
|
|
991
|
+
const orderRows = (rows, spec, limit) => {
|
|
992
|
+
const n = rows.length;
|
|
993
|
+
if (limit === void 0 || !Number.isInteger(limit) || limit < 1 || limit > 64 || limit >= n) return sortByOrderSpec(rows, spec);
|
|
994
|
+
const fields = Object.keys(spec);
|
|
995
|
+
const desc = fields.map((field) => spec[field] === "desc");
|
|
996
|
+
const types = [];
|
|
997
|
+
let prev = [];
|
|
998
|
+
let cur = [];
|
|
999
|
+
let ascents = 0;
|
|
1000
|
+
let descents = 0;
|
|
1001
|
+
for (let i = 0; i < n; i++) {
|
|
1002
|
+
const doc = rows[i].doc;
|
|
1003
|
+
for (let j = 0; j < fields.length; j++) {
|
|
1004
|
+
const value = doc[fields[j]];
|
|
1005
|
+
if (value !== void 0) {
|
|
1006
|
+
const type = typeof value;
|
|
1007
|
+
if (type === "object" || types[j] !== void 0 && types[j] !== type) return sortByOrderSpec(rows, spec).slice(0, limit);
|
|
1008
|
+
types[j] = type;
|
|
1009
|
+
}
|
|
1010
|
+
cur[j] = value;
|
|
1011
|
+
}
|
|
1012
|
+
if (i > 0 && (i <= 64 || ascents === 0 || descents === 0)) {
|
|
1013
|
+
let cmp = 0;
|
|
1014
|
+
for (let j = 0; j < fields.length && cmp === 0; j++) cmp = compareKey(prev[j], cur[j], desc[j]);
|
|
1015
|
+
if (cmp < 0) ascents++;
|
|
1016
|
+
else if (cmp > 0) descents++;
|
|
1017
|
+
}
|
|
1018
|
+
const swap = prev;
|
|
1019
|
+
prev = cur;
|
|
1020
|
+
cur = swap;
|
|
1021
|
+
}
|
|
1022
|
+
if (descents === 0) return rows.slice(0, limit);
|
|
1023
|
+
const compareKeys = (a, b) => {
|
|
1024
|
+
const x = rows[a].doc;
|
|
1025
|
+
const y = rows[b].doc;
|
|
1026
|
+
let cmp = 0;
|
|
1027
|
+
for (let j = 0; j < fields.length && cmp === 0; j++) cmp = compareKey(x[fields[j]], y[fields[j]], desc[j]);
|
|
1028
|
+
return cmp;
|
|
1029
|
+
};
|
|
1030
|
+
if (ascents === 0) {
|
|
1031
|
+
const out = [];
|
|
1032
|
+
let end = n;
|
|
1033
|
+
while (out.length < limit) {
|
|
1034
|
+
let start = end - 1;
|
|
1035
|
+
while (start > 0 && compareKeys(start - 1, start) === 0) start--;
|
|
1036
|
+
for (let i = start; i < end && out.length < limit; i++) out.push(rows[i]);
|
|
1037
|
+
end = start;
|
|
1038
|
+
}
|
|
1039
|
+
return out;
|
|
1040
|
+
}
|
|
1041
|
+
const compare = (a, b) => compareKeys(a, b) || a - b;
|
|
1042
|
+
const heap = [];
|
|
1043
|
+
const siftDown = (pos) => {
|
|
1044
|
+
for (;;) {
|
|
1045
|
+
const left = 2 * pos + 1;
|
|
1046
|
+
if (left >= limit) return;
|
|
1047
|
+
const right = left + 1;
|
|
1048
|
+
const worst = right < limit && compare(heap[right], heap[left]) > 0 ? right : left;
|
|
1049
|
+
if (compare(heap[worst], heap[pos]) < 0) return;
|
|
1050
|
+
[heap[pos], heap[worst]] = [heap[worst], heap[pos]];
|
|
1051
|
+
pos = worst;
|
|
1052
|
+
}
|
|
1053
|
+
};
|
|
1054
|
+
const backward = descents > ascents;
|
|
1055
|
+
for (let x = 0; x < n; x++) {
|
|
1056
|
+
const i = backward ? n - 1 - x : x;
|
|
1057
|
+
if (heap.length < limit) {
|
|
1058
|
+
if (heap.push(i) === limit) for (let pos = (limit >> 1) - 1; pos >= 0; pos--) siftDown(pos);
|
|
1059
|
+
} else if (compare(i, heap[0]) < 0) {
|
|
1060
|
+
heap[0] = i;
|
|
1061
|
+
siftDown(0);
|
|
1062
|
+
}
|
|
1063
|
+
}
|
|
1064
|
+
return heap.toSorted(compare).map((i) => rows[i]);
|
|
1065
|
+
};
|
|
1066
|
+
// packages/server/src/read-admission.ts
|
|
1067
|
+
/**
|
|
1068
|
+
* Staged read admission (main-2): a read whose work falls outside the
|
|
1069
|
+
* serving host's read envelope is refused whole with `CapacityExceeded`,
|
|
1070
|
+
* never truncated, and a read inside it is served exactly as on any other
|
|
1071
|
+
* host (P1). Reads stay pure: a refusal writes nothing and dispatches no
|
|
1072
|
+
* maintenance, so a read never carries `MaintenancePending`.
|
|
1073
|
+
*
|
|
1074
|
+
* Every read, index-covered or not, is a full fold: it takes membership
|
|
1075
|
+
* from the snapshot plus the log tail, never from an index LIST, so its
|
|
1076
|
+
* work is bounded by the full-fold bounds below (I1: materialized =
|
|
1077
|
+
* snapshot rows + tail entries). There is no index-specific bound.
|
|
1078
|
+
*
|
|
1079
|
+
* Two stages, both over the current layout (one snapshot plus the live
|
|
1080
|
+
* log tail):
|
|
1081
|
+
*
|
|
1082
|
+
* 1. **Head.** `current.json` alone refuses a read that is certain not to
|
|
1083
|
+
* fit: its snapshot is over the byte or row bound, or the strict log
|
|
1084
|
+
* range `[log_seq_start, tail_hint)` alone is over the tail or
|
|
1085
|
+
* materialization bound, or the storage calls the read must issue at
|
|
1086
|
+
* least are more than the request ledger has left. `tail_hint` is a
|
|
1087
|
+
* lower bound on the tail, so every head check is a lower bound and
|
|
1088
|
+
* never refuses a read that fits.
|
|
1089
|
+
* 2. **Staged.** The read charges each log body before decoding it (tail
|
|
1090
|
+
* entries, tail bytes, materialized rows), and checks the answer's row
|
|
1091
|
+
* count before returning it. Two buckets with identical heads but different tails are told apart
|
|
1092
|
+
* here. Storage calls are charged by the request ledger at issue
|
|
1093
|
+
* (`retryStorageCall`), retries included.
|
|
1094
|
+
*
|
|
1095
|
+
* Memory: the adapter `GET` has already allocated a body when its length is
|
|
1096
|
+
* checked; the head's `snapshot_bytes` bounds the snapshot before its GET.
|
|
1097
|
+
* A bounded-read `Storage` seam is not needed while each log entry is one
|
|
1098
|
+
* small object.
|
|
1099
|
+
*/
|
|
1100
|
+
/** The serving host's read envelope; unbounded outside a context that sets one. */
|
|
1101
|
+
const currentReadEnvelope = () => getCurrentContext()?.readEnvelope ?? {};
|
|
1102
|
+
/**
|
|
1103
|
+
* Storage calls the active invocation's request ledger still allows on
|
|
1104
|
+
* `pool`; `Infinity` without a ledger.
|
|
1105
|
+
*/
|
|
1106
|
+
const remainingStorageCalls = (pool = "internal") => currentRequestLedger()?.remaining(pool) ?? 1e400;
|
|
1107
|
+
const refuseRead = (collection, bound, why, remedy) => new BaerlyError("CapacityExceeded", `this read of collection ${JSON.stringify(collection)} ${why}, more than one request can do on this host, so it was refused and returned no rows. ${remedy}`, {
|
|
1108
|
+
resolution: remedy,
|
|
1109
|
+
cause: { bound }
|
|
1110
|
+
});
|
|
1111
|
+
/** Only for the output bound: a narrower predicate or a limit shrinks the answer, not the load. */
|
|
1112
|
+
const NARROW = "Do not retry unchanged: narrow the predicate or add a limit.";
|
|
1113
|
+
const TAIL = "Retry once maintenance has absorbed the pending writes: later writes run it as they commit, and so does a scheduled runScheduledMaintenance call. Until then this read is refused.";
|
|
1114
|
+
const OUTGROWN = "Do not retry unchanged: delete or shrink rows, or export the collection with baerly admin dump.";
|
|
1115
|
+
const MATERIALIZED = "Delete or shrink rows, or retry once maintenance has absorbed the pending writes (later writes and scheduled runScheduledMaintenance calls run it). Otherwise export the collection with baerly admin dump.";
|
|
1116
|
+
/**
|
|
1117
|
+
* One read's admission state. Built after the read GETs `current.json`;
|
|
1118
|
+
* {@link admitHead} runs before any other storage call, and the other
|
|
1119
|
+
* methods as the read stages its work. A refusal is always
|
|
1120
|
+
* `CapacityExceeded`, not retriable, whose `resolution` is the remedy for
|
|
1121
|
+
* the bound it hit.
|
|
1122
|
+
*/
|
|
1123
|
+
var ReadBudget = class {
|
|
1124
|
+
#collection;
|
|
1125
|
+
#envelope;
|
|
1126
|
+
#snapshotRows = 0;
|
|
1127
|
+
#tailEntries = 0;
|
|
1128
|
+
#tailBytes = 0;
|
|
1129
|
+
constructor(collection, envelope = currentReadEnvelope()) {
|
|
1130
|
+
this.#collection = collection;
|
|
1131
|
+
this.#envelope = envelope;
|
|
1132
|
+
}
|
|
1133
|
+
/** The pool the host's storage charges; see {@link ReadEnvelope.requestPool}. */
|
|
1134
|
+
get requestPool() {
|
|
1135
|
+
return this.#envelope.requestPool ?? "internal";
|
|
1136
|
+
}
|
|
1137
|
+
/**
|
|
1138
|
+
* Refuse from the head alone when the read cannot fit (stage 1). Every
|
|
1139
|
+
* read folds up front: it loads the snapshot and walks the strict log
|
|
1140
|
+
* range `[log_seq_start, tail_hint)`. Every figure here is a lower bound
|
|
1141
|
+
* on the read's work, because `tail_hint` never passes the true tail.
|
|
1142
|
+
*
|
|
1143
|
+
* @throws BaerlyError code="CapacityExceeded"
|
|
1144
|
+
*/
|
|
1145
|
+
admitHead(head) {
|
|
1146
|
+
const strict = Math.max(0, head.tail_hint - head.log_seq_start);
|
|
1147
|
+
if (strict > (this.#envelope.maxTailEntries ?? 1e400)) throw this.#tailEntriesRefusal(strict);
|
|
1148
|
+
this.admitSnapshot(head, strict);
|
|
1149
|
+
const calls = 1 + strict + (head.snapshot === null ? 0 : 1);
|
|
1150
|
+
const left = remainingStorageCalls(this.requestPool);
|
|
1151
|
+
if (calls > left) throw refuseRead(this.#collection, "headStorageCalls", `must issue at least ${calls} storage calls, over the ${left} this request has left`, TAIL);
|
|
1152
|
+
}
|
|
1153
|
+
/**
|
|
1154
|
+
* Admit loading the snapshot `head` names, before its GET: its bytes and
|
|
1155
|
+
* rows, and its rows plus `pendingEntries` (the tail entries the read
|
|
1156
|
+
* will fold at least, beyond those already charged) toward
|
|
1157
|
+
* materialization.
|
|
1158
|
+
*
|
|
1159
|
+
* @throws BaerlyError code="CapacityExceeded"
|
|
1160
|
+
*/
|
|
1161
|
+
admitSnapshot(head, pendingEntries = 0) {
|
|
1162
|
+
const env = this.#envelope;
|
|
1163
|
+
if (head.snapshot_bytes > (env.maxSnapshotBytes ?? 1e400)) throw refuseRead(this.#collection, "snapshotBytes", `must load a ${head.snapshot_bytes}-byte snapshot, over the ${env.maxSnapshotBytes} bytes it may load`, OUTGROWN);
|
|
1164
|
+
if (head.snapshot_rows > (env.maxSnapshotRows ?? 1e400)) throw refuseRead(this.#collection, "snapshotRows", `must decode ${head.snapshot_rows} snapshot rows, over the ${env.maxSnapshotRows} it may decode`, OUTGROWN);
|
|
1165
|
+
this.#snapshotRows = head.snapshot_rows;
|
|
1166
|
+
this.#checkMaterialized(this.#tailEntries + pendingEntries);
|
|
1167
|
+
}
|
|
1168
|
+
/**
|
|
1169
|
+
* Charge one log entry's stored body before it is decoded (stage 2).
|
|
1170
|
+
* Bound so it can be passed as a callback.
|
|
1171
|
+
*
|
|
1172
|
+
* @throws BaerlyError code="CapacityExceeded"
|
|
1173
|
+
*/
|
|
1174
|
+
chargeTailBody = (bytes) => {
|
|
1175
|
+
const env = this.#envelope;
|
|
1176
|
+
this.#tailEntries += 1;
|
|
1177
|
+
this.#tailBytes += bytes;
|
|
1178
|
+
if (this.#tailEntries > (env.maxTailEntries ?? 1e400)) throw this.#tailEntriesRefusal(this.#tailEntries);
|
|
1179
|
+
if (this.#tailBytes > (env.maxTailBytes ?? 1e400)) throw refuseRead(this.#collection, "tailBytes", `must load more than ${env.maxTailBytes} bytes of pending log entries`, TAIL);
|
|
1180
|
+
this.#checkMaterialized(this.#tailEntries);
|
|
1181
|
+
};
|
|
1182
|
+
/**
|
|
1183
|
+
* The refusal for a forward probe that ran out of request budget before
|
|
1184
|
+
* it found the tail.
|
|
1185
|
+
*/
|
|
1186
|
+
probeRefusal = () => refuseRead(this.#collection, "probeStorageCalls", `must probe more pending log entries than this request has storage calls left`, TAIL);
|
|
1187
|
+
/**
|
|
1188
|
+
* Refuse an answer over the output bound whole, never a truncated one.
|
|
1189
|
+
*
|
|
1190
|
+
* @throws BaerlyError code="CapacityExceeded"
|
|
1191
|
+
*/
|
|
1192
|
+
admitOutput(rows) {
|
|
1193
|
+
const max = this.#envelope.maxOutputRows ?? 1e400;
|
|
1194
|
+
if (rows > max) throw refuseRead(this.#collection, "outputRows", `returns ${rows} rows, over the ${max} it may return`, NARROW);
|
|
1195
|
+
}
|
|
1196
|
+
#checkMaterialized(tailEntries) {
|
|
1197
|
+
const rows = this.#snapshotRows + tailEntries;
|
|
1198
|
+
const max = this.#envelope.maxMaterializedRows ?? 1e400;
|
|
1199
|
+
if (rows > max) throw refuseRead(this.#collection, "materializedRows", `must decode at least ${rows} rows before filtering, over the ${max} it may decode`, MATERIALIZED);
|
|
1200
|
+
}
|
|
1201
|
+
#tailEntriesRefusal(entries) {
|
|
1202
|
+
return refuseRead(this.#collection, "tailEntries", `must load at least ${entries} pending log entries, over the ${this.#envelope.maxTailEntries} it may load`, TAIL);
|
|
1203
|
+
}
|
|
1204
|
+
};
|
|
1205
|
+
// packages/server/src/schema.ts
|
|
1206
|
+
/**
|
|
1207
|
+
* Schema-validator runtime helper for `Db.insert` / `Query.update` /
|
|
1208
|
+
* `Collection.replace` boundary checks.
|
|
1209
|
+
*
|
|
1210
|
+
* The `SchemaValidator` / `SchemaIssue` TYPES live in
|
|
1211
|
+
* `@baerly/protocol` (cross-platform). This module owns the runtime
|
|
1212
|
+
* helper `validateOrThrow` that runs a validator and raises a
|
|
1213
|
+
* `BaerlyError{code:"SchemaError"}` on failure.
|
|
1214
|
+
*
|
|
1215
|
+
* @example
|
|
1216
|
+
* ```ts
|
|
1217
|
+
* import { z } from "zod";
|
|
1218
|
+
* import { defineConfig } from "@gusto/baerly-storage/config";
|
|
1219
|
+
*
|
|
1220
|
+
* const Ticket = z.object({
|
|
1221
|
+
* _id: z.string(),
|
|
1222
|
+
* status: z.enum(["open", "closed"]),
|
|
1223
|
+
* title: z.string().min(1),
|
|
1224
|
+
* });
|
|
1225
|
+
*
|
|
1226
|
+
* export default defineConfig({
|
|
1227
|
+
* collections: {
|
|
1228
|
+
* tickets: { schema: Ticket },
|
|
1229
|
+
* },
|
|
1230
|
+
* });
|
|
1231
|
+
* ```
|
|
1232
|
+
*/
|
|
1233
|
+
/**
|
|
1234
|
+
* Run a validator and throw `BaerlyError{code:"SchemaError"}` on failure.
|
|
1235
|
+
* On success returns the validator's output (which for transforming
|
|
1236
|
+
* validators may differ from the input).
|
|
1237
|
+
*
|
|
1238
|
+
* Field paths are normalised to `(string | number)[]` so the wire shape
|
|
1239
|
+
* is JSON-clean. Symbol keys (rare; StandardSchemaV1 permits them) are
|
|
1240
|
+
* coerced to `String(sym)` — we never emit `symbol` on the wire.
|
|
1241
|
+
*
|
|
1242
|
+
* The thrown error's `message` carries a one-line summary
|
|
1243
|
+
* (`"<collection>.<verb>: <issuesCount> field(s) failed validation: <first>"`)
|
|
1244
|
+
* for stderr-readable logs; the structured `issues` are on `.issues`.
|
|
1245
|
+
*/
|
|
1246
|
+
const validateOrThrow = async (schema, candidate, context) => {
|
|
1247
|
+
const result = await schema["~standard"].validate(candidate);
|
|
1248
|
+
if (result.issues === void 0) return result.value;
|
|
1249
|
+
const issues = result.issues.map((i) => ({
|
|
1250
|
+
path: (i.path ?? []).map((p) => {
|
|
1251
|
+
const raw = typeof p === "object" && p !== null && "key" in p ? p.key : p;
|
|
1252
|
+
return typeof raw === "number" ? raw : String(raw);
|
|
1253
|
+
}),
|
|
1254
|
+
message: i.message
|
|
1255
|
+
}));
|
|
1256
|
+
const first = issues[0];
|
|
1257
|
+
const summary = first === void 0 ? "schema validation failed (no issues reported)" : `${first.path.length === 0 ? "<root>" : first.path.join(".")}: ${first.message}`;
|
|
1258
|
+
throw new BaerlyError("SchemaError", `${context.collection}.${context.verb}: ${issues.length} field${issues.length === 1 ? "" : "s"} failed validation: ${summary}`, { issues });
|
|
1259
|
+
};
|
|
1260
|
+
// packages/server/src/key-limit.ts
|
|
1261
|
+
const utf8 = new TextEncoder();
|
|
1262
|
+
/**
|
|
1263
|
+
* Reject an assembled object key over the S3/R2 full-key ceiling
|
|
1264
|
+
* ({@link MAX_KEY_BYTES}) as `InvalidConfig`. Per-segment caps don't
|
|
1265
|
+
* bound the sum, and index values skip `assertPathSegment` entirely, so
|
|
1266
|
+
* this post-encoding check at the writer's PUT sites is their only
|
|
1267
|
+
* overflow guard. @see docs/spec/storage-compatibility.md
|
|
1268
|
+
*/
|
|
1269
|
+
const assertKeyWithinLimit = (key) => {
|
|
1270
|
+
const bytes = utf8.encode(key).length;
|
|
1271
|
+
if (bytes > 1024) throw new BaerlyError("InvalidConfig", `object key exceeds ${MAX_KEY_BYTES} bytes (got ${bytes}): ${JSON.stringify(key.slice(0, 80))}…`);
|
|
1272
|
+
};
|
|
1273
|
+
// packages/server/src/log-conflict-adoption.ts
|
|
1274
|
+
/**
|
|
1275
|
+
* Decide whether the entry already at `/log/<seq>.json` is the
|
|
1276
|
+
* writer's own prior in-flight attempt and may be adopted. Pure
|
|
1277
|
+
* function; no I/O. The caller performs the GET (when the log PUT
|
|
1278
|
+
* surfaces 412) and passes the read-back body in `ctx.existing`.
|
|
1279
|
+
*
|
|
1280
|
+
* ## Correctness precondition
|
|
1281
|
+
*
|
|
1282
|
+
* A fresh `session` id is minted per `commit()` call, seq-stable
|
|
1283
|
+
* across that call's retries. Adoption compares the writer-minted
|
|
1284
|
+
* intent/body fields as well as session and seq: a dropped-ack retry
|
|
1285
|
+
* reuses the same attempted entry and adopts, while a same-session /
|
|
1286
|
+
* same-seq occupant carrying a different logical mutation is treated as
|
|
1287
|
+
* a conflict and skipped by the caller's forward-probe loop.
|
|
1288
|
+
*
|
|
1289
|
+
* @see {@link AdoptionDecision} for the return shape.
|
|
1290
|
+
* @see The soundness invariant in this module's header docstring.
|
|
1291
|
+
*/
|
|
1292
|
+
const tryAdoptOwnSessionLogEntry = (ctx) => {
|
|
1293
|
+
if (ctx.existing.session !== ctx.self.session) return {
|
|
1294
|
+
adopt: false,
|
|
1295
|
+
reason: "foreign-session"
|
|
1296
|
+
};
|
|
1297
|
+
if (ctx.existing.seq !== ctx.self.seq) return {
|
|
1298
|
+
adopt: false,
|
|
1299
|
+
reason: "wrong-seq"
|
|
1300
|
+
};
|
|
1301
|
+
if (JSON.stringify(ctx.existing) !== JSON.stringify(ctx.self)) return {
|
|
1302
|
+
adopt: false,
|
|
1303
|
+
reason: "intent-mismatch"
|
|
1304
|
+
};
|
|
1305
|
+
return {
|
|
1306
|
+
adopt: true,
|
|
1307
|
+
entry: ctx.existing
|
|
1308
|
+
};
|
|
1309
|
+
};
|
|
1310
|
+
// packages/server/src/post-image-identity.ts
|
|
1311
|
+
const throwBaerlyError = (code, message, cause) => {
|
|
1312
|
+
throw new BaerlyError(code, `post-image: ${message}`, { cause });
|
|
1313
|
+
};
|
|
1314
|
+
/**
|
|
1315
|
+
* Assert that an insert/update post-image names the document it is stored
|
|
1316
|
+
* under: `after` is a plain object (prototype `Object.prototype` or `null`,
|
|
1317
|
+
* not an array) whose own enumerable data property `_id` is a string
|
|
1318
|
+
* `=== docId`.
|
|
1319
|
+
*
|
|
1320
|
+
* This checks identity only. It does not validate `docId` against the
|
|
1321
|
+
* `utf8-scalar-v1` domain, and it does not validate any other field of the
|
|
1322
|
+
* document. Callers that need the scalar domain call `assertSnapshotDocId`
|
|
1323
|
+
* first.
|
|
1324
|
+
*
|
|
1325
|
+
* `code` selects the failure polarity: `InvalidConfig` for caller input,
|
|
1326
|
+
* `InvalidResponse` for stored input. Failures go through `fail` when given,
|
|
1327
|
+
* so a codec keeps its own message prefix; otherwise this throws a
|
|
1328
|
+
* `BaerlyError` with `code`.
|
|
1329
|
+
*/
|
|
1330
|
+
function assertPostImageIdentity(docId, after, code, fail = throwBaerlyError) {
|
|
1331
|
+
if (after === null || typeof after !== "object" || Array.isArray(after)) fail(code, "after must be a document object");
|
|
1332
|
+
const prototype = Object.getPrototypeOf(after);
|
|
1333
|
+
if (prototype !== Object.prototype && prototype !== null) fail(code, "after must be a plain object");
|
|
1334
|
+
const descriptor = Object.getOwnPropertyDescriptor(after, "_id");
|
|
1335
|
+
if (descriptor === void 0 || !descriptor.enumerable || !("value" in descriptor)) fail(code, "after._id must be an own enumerable data property");
|
|
1336
|
+
if (typeof descriptor.value !== "string" || descriptor.value !== docId) fail(code, "after._id must equal doc_id");
|
|
1337
|
+
}
|
|
1338
|
+
// packages/server/src/writer.ts
|
|
1339
|
+
/**
|
|
1340
|
+
* `Writer` — stateless multi-instance write engine (single-write commit).
|
|
1341
|
+
*
|
|
1342
|
+
* Each {@link Writer.commit} reads `current.json` FRESH (for
|
|
1343
|
+
* `log_seq_start` / `tail_hint` as a probe FLOOR — a lower bound, NOT a
|
|
1344
|
+
* CAS precondition), then **creates `log/<seq>` via `If-None-Match: "*"`.
|
|
1345
|
+
* That create IS the commit / linearization point.** The writer writes NOTHING to `current.json` on the commit
|
|
1346
|
+
* path; `tail_hint` advances outside ordinary commits via compaction
|
|
1347
|
+
* folds, write-tick refreshes, and explicit operator/import paths. The
|
|
1348
|
+
* commit model and its invariants are recorded in ADR-004
|
|
1349
|
+
* (`docs/adr/004-single-write-commit.md`). The
|
|
1350
|
+
* optional integrity walk is gated by
|
|
1351
|
+
* {@link WriterOptions.verifyLogIntegrityOnCommit} (default off).
|
|
1352
|
+
*
|
|
1353
|
+
* No per-write cache: every commit re-reads + re-probes, so N stateless
|
|
1354
|
+
* instances contend at one place — the `If-None-Match` create of
|
|
1355
|
+
* `log/<seq>`. The loser gets a 412 and re-probes forward to the next
|
|
1356
|
+
* empty slot. A 412 from the writer's OWN session at the same seq is its
|
|
1357
|
+
* own lost-ack / crashed-but-durable commit → adopted (not retried), so
|
|
1358
|
+
* the write lands at EXACTLY `seq`, never duplicated.
|
|
1359
|
+
*
|
|
1360
|
+
* **First insert wins.** An `I` carrying {@link CommitInput.insertGuard}
|
|
1361
|
+
* reads the log window its caller's absence check could not see and
|
|
1362
|
+
* refuses to commit over a live row a peer's `I` put there
|
|
1363
|
+
* (`AlreadyExists`), so of concurrent inserts of one `doc_id` at most one
|
|
1364
|
+
* commits (exactly one, absent storage failures). See {@link InsertGuard}
|
|
1365
|
+
* and `docs/spec/sync-protocol.md` §"Insert: the first `I` wins".
|
|
1366
|
+
*
|
|
1367
|
+
* **Caller re-decisions.** A {@link CommitAdmission} re-runs the caller's
|
|
1368
|
+
* decision over the same window; its verdict may replace a `U`'s
|
|
1369
|
+
* post-image, which the write verbs use to re-apply an update to the
|
|
1370
|
+
* newest version of its row. See {@link CommitVerdict} and
|
|
1371
|
+
* `docs/spec/sync-protocol.md` §"Update and delete: decided on the newest
|
|
1372
|
+
* row version".
|
|
1373
|
+
*
|
|
1374
|
+
* **Crash safety.** The `log/<seq>` create is the commit's only write.
|
|
1375
|
+
* `LogEntry.after` is the authoritative post-image, so a crash before the
|
|
1376
|
+
* create leaves nothing of the commit on the bucket, and a crash after it
|
|
1377
|
+
* leaves a durable commit. The writer maintains no secondary objects:
|
|
1378
|
+
* declared indexes change no storage call (ADR-004 Q4, superseded in 0.7).
|
|
1379
|
+
*
|
|
1380
|
+
* **`LogEntry` shape.** Emitted entries follow the contract in
|
|
1381
|
+
* `packages/protocol/src/log.ts` (see {@link LogEntry}) and
|
|
1382
|
+
* `docs/spec/log-entry-shape.md`. The on-bucket key is
|
|
1383
|
+
* `log/<seq>.json` (the integer `seq` is the load-bearing
|
|
1384
|
+
* identifier; the `lsn` string is schema-only).
|
|
1385
|
+
*
|
|
1386
|
+
* @see docs/spec/sync-protocol.md for the protocol invariants this
|
|
1387
|
+
* loop preserves.
|
|
1388
|
+
* @see docs/spec/log-entry-shape.md for the per-field contract.
|
|
1389
|
+
*/
|
|
1390
|
+
const ctxMetrics = () => getCurrentContext()?.recorder ?? noopMetricsRecorder;
|
|
1391
|
+
const APPLICATION_JSON = "application/json";
|
|
1392
|
+
/**
|
|
1393
|
+
* Stateless write engine for the multi-instance core.
|
|
1394
|
+
*
|
|
1395
|
+
* Construction is cheap and performs zero I/O — adapters build a
|
|
1396
|
+
* fresh `Writer` per request and discard it. All real work
|
|
1397
|
+
* happens in {@link commit}.
|
|
1398
|
+
*
|
|
1399
|
+
* @example
|
|
1400
|
+
* ```ts
|
|
1401
|
+
* import { Writer } from "@gusto/baerly-storage";
|
|
1402
|
+
* import { MemoryStorage } from "@gusto/baerly-storage";
|
|
1403
|
+
*
|
|
1404
|
+
* const writer = new Writer({
|
|
1405
|
+
* storage: new MemoryStorage(),
|
|
1406
|
+
* currentJsonKey: "app/tickets/tenant/acme/manifests/tickets/current.json",
|
|
1407
|
+
* });
|
|
1408
|
+
*
|
|
1409
|
+
* const result = await writer.commit({
|
|
1410
|
+
* op: "I",
|
|
1411
|
+
* collection: "tickets",
|
|
1412
|
+
* docId: "doc-1",
|
|
1413
|
+
* body: { _id: "doc-1", title: "hello" },
|
|
1414
|
+
* });
|
|
1415
|
+
* console.log(result.entry.seq);
|
|
1416
|
+
* ```
|
|
1417
|
+
*/
|
|
1418
|
+
var Writer = class {
|
|
1419
|
+
#storage;
|
|
1420
|
+
#currentJsonKey;
|
|
1421
|
+
#verifyLogIntegrityOnCommit;
|
|
1422
|
+
constructor(opts) {
|
|
1423
|
+
this.#storage = opts.storage;
|
|
1424
|
+
this.#currentJsonKey = opts.currentJsonKey;
|
|
1425
|
+
this.#verifyLogIntegrityOnCommit = opts.options?.verifyLogIntegrityOnCommit ?? false;
|
|
1426
|
+
}
|
|
1427
|
+
/**
|
|
1428
|
+
* Atomically commit one mutation. Reads `current.json` fresh (as a
|
|
1429
|
+
* probe FLOOR, not a CAS precondition), then creates `log/<seq>` via
|
|
1430
|
+
* `If-None-Match: "*"` — that create IS the commit (single-write
|
|
1431
|
+
* commit; no `current.json` CAS follows it).
|
|
1432
|
+
*
|
|
1433
|
+
* The hot-path cost under no contention is 3 GETs + 1 PUT, whatever
|
|
1434
|
+
* indexes the collection declares: the Step 1 `current.json` read,
|
|
1435
|
+
* `findLogTail`'s forward probe (one 404 GET when `tail_hint` is
|
|
1436
|
+
* accurate, `O(log gap)` GETs when it lags a fold interval), the
|
|
1437
|
+
* committing `log/<seq>` create, and the post-create `current.json`
|
|
1438
|
+
* re-read that rejects a create landing below the certified delete
|
|
1439
|
+
* floor (`#assertCommitAboveDeleteFloor`). A peer that won the slot
|
|
1440
|
+
* costs one occupant readback GET, the forward probe's GETs, and one
|
|
1441
|
+
* more create at the next slot.
|
|
1442
|
+
*
|
|
1443
|
+
* Idempotency: `LogEntry.after` carries the full post-image, and the
|
|
1444
|
+
* `log/<seq>` create uses `If-None-Match: "*"`, so two writers racing
|
|
1445
|
+
* the same tail cause
|
|
1446
|
+
* exactly one create to win; the loser reads back the occupant,
|
|
1447
|
+
* adopts its own lost-ack write or re-probes forward to the next
|
|
1448
|
+
* empty slot.
|
|
1449
|
+
*
|
|
1450
|
+
* **Uncertain commit fate.** If the committing create wins at a
|
|
1451
|
+
* `seq` the collection has already certified deleted — reachable when a
|
|
1452
|
+
* create PUT or a lost-ack retry straddles a fold plus a retirement pass —
|
|
1453
|
+
* the object it wrote is beneath every reader's floor. The commit then fails
|
|
1454
|
+
* with `AmbiguousCommit` rather than acknowledging a mutation no fresh
|
|
1455
|
+
* reader can see. The writer cannot tell whether an earlier attempt of its
|
|
1456
|
+
* own landed and was folded before retirement removed the slot, so the
|
|
1457
|
+
* mutation may or may not have been applied. The same uncertainty exists
|
|
1458
|
+
* when a rejected create cannot be resolved by reading its slot, including
|
|
1459
|
+
* rejections that follow a send of unknown outcome. The Writer never
|
|
1460
|
+
* resends a create at the same slot (the adapter already retried it); it
|
|
1461
|
+
* reads the slot back once instead. A missing readback does not prove that
|
|
1462
|
+
* an earlier send will not land. Exact own-entry readback is adopted; an
|
|
1463
|
+
* unresolved fate throws `AmbiguousCommit` with `err.retriable === false`.
|
|
1464
|
+
* Reconcile state before deliberately retrying: a new logical call can
|
|
1465
|
+
* duplicate work, including minting a second auto-ID document.
|
|
1466
|
+
*
|
|
1467
|
+
* @throws BaerlyError code="AmbiguousCommit" when the committing create
|
|
1468
|
+
* landed below `min(log_delete_floor, log_seq_start)`, or a possibly
|
|
1469
|
+
* durable create could not be resolved. The mutation's fate is unknown;
|
|
1470
|
+
* `err._id` is `input.docId`.
|
|
1471
|
+
* @throws BaerlyError code="Internal" when a log entry expected in
|
|
1472
|
+
* `[0, tail_hint)` is missing — a protocol-invariant violation
|
|
1473
|
+
* (compactor bug or stale `current.json`).
|
|
1474
|
+
* @throws BaerlyError code="InvalidResponse" when a log-entry body
|
|
1475
|
+
* isn't valid JSON.
|
|
1476
|
+
* @throws BaerlyError code="InvalidConfig" when `docId` breaks the
|
|
1477
|
+
* key-segment rule, when an `I` / `U` `docId` is not NFC, when an
|
|
1478
|
+
* `I` / `U` body is not a plain object whose own `_id` is the string
|
|
1479
|
+
* `docId`, when an `I` / `U` post-image encodes to more than
|
|
1480
|
+
* `MAX_DOCUMENT_BYTES`, or when `insertGuard` is set on a non-`I` op.
|
|
1481
|
+
* Checked before any I/O (an admission verdict's replacement
|
|
1482
|
+
* post-image is size-checked when it is returned).
|
|
1483
|
+
* @throws BaerlyError code="AlreadyExists" when `insertGuard` is set and
|
|
1484
|
+
* the log window `[absentBelowSeq, seq)` holds a live `I` / `U` for
|
|
1485
|
+
* this doc (unless `replayIdentical` is set and its `after` equals the
|
|
1486
|
+
* body, which returns that entry instead). Nothing was committed;
|
|
1487
|
+
* `err._id` is `input.docId`.
|
|
1488
|
+
* @throws BaerlyError code="WriteConflict" when `insertGuard` or
|
|
1489
|
+
* `admission` is set and part of its window was folded and retired (or
|
|
1490
|
+
* is longer than `LOG_FORWARD_PROBE_CAP`) before the writer could read
|
|
1491
|
+
* it. Nothing was committed; re-read and retry.
|
|
1492
|
+
* @throws BaerlyError code="CapacityExceeded" when the request ledger
|
|
1493
|
+
* cannot afford this commit's create and `COMMIT_RESOLUTION_RESERVE`,
|
|
1494
|
+
* checked before each create; or when the ledger refused the create
|
|
1495
|
+
* itself before any attempt was sent (`cause.notApplied`), or any
|
|
1496
|
+
* storage call before it. Nothing was committed.
|
|
1497
|
+
* @throws whatever `admission.check` throws (the write verbs throw
|
|
1498
|
+
* `CapacityExceeded` or `MaintenancePending`). Nothing was committed.
|
|
1499
|
+
*
|
|
1500
|
+
* **Window cost.** A commit with `insertGuard` or `admission` probes the
|
|
1501
|
+
* tail linearly from `max(windowFrom, log_seq_start)` with
|
|
1502
|
+
* `probeTailFrom` instead of galloping from
|
|
1503
|
+
* `max(log_seq_start, tail_hint)`. Uncontended, `windowFrom` is the
|
|
1504
|
+
* tail, so that is one 404 GET. Each entry a peer committed after the
|
|
1505
|
+
* caller's read costs one more GET, and if a fold moved `log_seq_start`
|
|
1506
|
+
* past `windowFrom`, each folded slot in between costs one GET too.
|
|
1507
|
+
*
|
|
1508
|
+
* **Implicit provisioning.** When `current.json` does not exist at
|
|
1509
|
+
* `currentJsonKey` (fresh bucket, fresh collection), the writer
|
|
1510
|
+
* auto-creates it with a zero-state manifest before the commit
|
|
1511
|
+
* lands. The cost is one extra Class A PUT on the very first
|
|
1512
|
+
* commit per collection; steady-state cost is unchanged. A peer
|
|
1513
|
+
* racing the same first-write loses cleanly on the create CAS
|
|
1514
|
+
* and re-reads to pick up the winner's manifest.
|
|
1515
|
+
*/
|
|
1516
|
+
async commit(input) {
|
|
1517
|
+
if (input.op === "D") assertStoredDocId(input.docId);
|
|
1518
|
+
else assertDocId(input.docId);
|
|
1519
|
+
if (input.op !== "D") {
|
|
1520
|
+
assertPostImageIdentity(input.docId, input.body, "InvalidConfig");
|
|
1521
|
+
assertDocumentSize(input.body, "Writer");
|
|
1522
|
+
}
|
|
1523
|
+
if (input.insertGuard !== void 0) assertInsertGuardShape(input);
|
|
1524
|
+
if (input.admission !== void 0) assertAdmissionShape(input);
|
|
1525
|
+
const session = uuid().slice(0, 6);
|
|
1526
|
+
const logPrefix = this.#currentJsonKey.slice(0, this.#currentJsonKey.lastIndexOf("/"));
|
|
1527
|
+
const success = await this.#singleAttemptCommit(input, session, logPrefix, "Writer");
|
|
1528
|
+
if (success.replayed) recordInsertReplay(input.collection);
|
|
1529
|
+
else this.#emitWriteMetrics(input.collection, success.classAOps);
|
|
1530
|
+
return {
|
|
1531
|
+
entry: success.entries[0],
|
|
1532
|
+
currentEtag: success.currentEtag
|
|
1533
|
+
};
|
|
1534
|
+
}
|
|
1535
|
+
/**
|
|
1536
|
+
* One full commit attempt — the body of {@link commit}. Reads
|
|
1537
|
+
* `current.json`, then forward-probes the tail and creates `log/<seq>`
|
|
1538
|
+
* once via `If-None-Match: "*"` — the numbered log create IS the commit
|
|
1539
|
+
* (single-write commit; no `current.json` CAS follows it). Returns the
|
|
1540
|
+
* success payload.
|
|
1541
|
+
*
|
|
1542
|
+
* Commits exactly one {@link CommitInput} — the numbered log create is
|
|
1543
|
+
* the single linearization point per call.
|
|
1544
|
+
*
|
|
1545
|
+
* A log-create 412 is disambiguated by session read-back: own session
|
|
1546
|
+
* / own seq ⇒ our crashed-or-lost-ack commit is already durable ⇒
|
|
1547
|
+
* adopt; foreign session ⇒ re-probe forward and create at the next
|
|
1548
|
+
* empty slot. Each slot gets one `Storage.put` and never a same-slot
|
|
1549
|
+
* resend, because the adapter already retried it. A definitive
|
|
1550
|
+
* `AccessDenied` / `InvalidConfig` propagates as-is. A 412 or an uncertain
|
|
1551
|
+
* failure resolves by one occupant readback, because adapters can hide
|
|
1552
|
+
* earlier sends. When the call reports every attempt refused unapplied
|
|
1553
|
+
* (`cause.notApplied`), the same readback runs because a throttle can hide
|
|
1554
|
+
* a lost race: a foreign occupant forward-probes, a slot read back as
|
|
1555
|
+
* empty or unreadable propagates the retriable `NetworkError`: the
|
|
1556
|
+
* adapter already guarantees no attempt applied or can still apply.
|
|
1557
|
+
* Unresolved creates throw non-retriable `AmbiguousCommit`; failures
|
|
1558
|
+
* before the create propagate.
|
|
1559
|
+
*
|
|
1560
|
+
* Crash safety: the create is the attempt's only write. A crash before
|
|
1561
|
+
* it leaves nothing; a crash after it is a durable, committed write at
|
|
1562
|
+
* `seq`, carrying its full post-image in `LogEntry.after`.
|
|
1563
|
+
*/
|
|
1564
|
+
async #singleAttemptCommit(input, session, logPrefix, errorPrefix) {
|
|
1565
|
+
const read = await readCurrentJson(this.#storage, this.#currentJsonKey) ?? await this.#provisionCurrentJson();
|
|
1566
|
+
const current = read.json;
|
|
1567
|
+
const baseEtag = read.etag;
|
|
1568
|
+
if (this.#verifyLogIntegrityOnCommit) await this.#walkLog(logPrefix, logSeqStartOf(current), current.tail_hint);
|
|
1569
|
+
const guard = input.insertGuard;
|
|
1570
|
+
const admission = input.admission;
|
|
1571
|
+
const windowFrom = guard?.absentBelowSeq ?? admission?.fromSeq;
|
|
1572
|
+
const logSeqStart = logSeqStartOf(current);
|
|
1573
|
+
let commitWindow;
|
|
1574
|
+
let admissionForces = false;
|
|
1575
|
+
let body = input.body;
|
|
1576
|
+
const decide = async (window, tail) => {
|
|
1577
|
+
if (admission === void 0) return;
|
|
1578
|
+
const verdict = await admission.check(window, tail);
|
|
1579
|
+
admissionForces = verdict?.forceMaintenance === true;
|
|
1580
|
+
if (verdict?.body !== void 0) {
|
|
1581
|
+
if (input.op !== "U") throw new BaerlyError("InvalidConfig", `${errorPrefix}: an admission verdict may replace only a U post-image; got op ${JSON.stringify(input.op)}`);
|
|
1582
|
+
assertPostImageIdentity(input.docId, verdict.body, "InvalidConfig");
|
|
1583
|
+
assertDocumentSize(verdict.body, errorPrefix);
|
|
1584
|
+
body = verdict.body;
|
|
1585
|
+
}
|
|
1586
|
+
};
|
|
1587
|
+
let preCommitTail;
|
|
1588
|
+
if (windowFrom === void 0) {
|
|
1589
|
+
const probeFloor = Math.max(logSeqStart, current.tail_hint);
|
|
1590
|
+
preCommitTail = await findLogTail(this.#storage, logPrefix, probeFloor);
|
|
1591
|
+
} else {
|
|
1592
|
+
const folded = await this.#readFoldedWindow(logPrefix, windowFrom, logSeqStart, errorPrefix);
|
|
1593
|
+
const probe = await probeTailFrom(this.#storage, logPrefix, Math.max(windowFrom, logSeqStart));
|
|
1594
|
+
commitWindow = [...folded, ...probe.entries];
|
|
1595
|
+
if (guard !== void 0) {
|
|
1596
|
+
const replayed = decideInsertTarget(commitWindow, input);
|
|
1597
|
+
if (replayed !== void 0) return {
|
|
1598
|
+
replayed: true,
|
|
1599
|
+
entries: [replayed],
|
|
1600
|
+
currentEtag: baseEtag
|
|
1601
|
+
};
|
|
1602
|
+
}
|
|
1603
|
+
await decide(commitWindow, probe.tail);
|
|
1604
|
+
preCommitTail = probe.tail;
|
|
1605
|
+
}
|
|
1606
|
+
let seq = preCommitTail;
|
|
1607
|
+
const commitNowMs = Date.now();
|
|
1608
|
+
const commitTs = new Date(commitNowMs).toISOString();
|
|
1609
|
+
const lsnTimestamp = timestamp(commitNowMs);
|
|
1610
|
+
const mintEntry = (atSeq) => ({
|
|
1611
|
+
lsn: `${lsnTimestamp}_${session}_${countKey(atSeq)}`,
|
|
1612
|
+
commit_ts: commitTs,
|
|
1613
|
+
op: input.op,
|
|
1614
|
+
collection: input.collection,
|
|
1615
|
+
doc_id: input.docId,
|
|
1616
|
+
session,
|
|
1617
|
+
seq: atSeq,
|
|
1618
|
+
...input.op !== "D" && body !== void 0 ? { after: body } : {},
|
|
1619
|
+
...input.origin !== void 0 ? { origin: input.origin } : {}
|
|
1620
|
+
});
|
|
1621
|
+
let entry = mintEntry(seq);
|
|
1622
|
+
let committedEntry;
|
|
1623
|
+
let probes = 0;
|
|
1624
|
+
const ambiguous = (cause) => {
|
|
1625
|
+
ctxMetrics().counter("db.write.unresolved_create_total", 1, { collection: entry.collection });
|
|
1626
|
+
return new BaerlyError("AmbiguousCommit", `${errorPrefix}: the committing create at seq ${seq} on ${this.#currentJsonKey} was rejected and its fate could not be resolved; an earlier send may already have landed or may still land, so retrying may duplicate logical work`, {
|
|
1627
|
+
cause,
|
|
1628
|
+
resolution: CODE_RESOLUTIONS.AmbiguousCommit,
|
|
1629
|
+
_id: entry.doc_id
|
|
1630
|
+
});
|
|
1631
|
+
};
|
|
1632
|
+
for (;;) {
|
|
1633
|
+
const outcome = await this.#withCommitHold(errorPrefix, async () => {
|
|
1634
|
+
const logEntryKey = logObjectKey(logPrefix, seq);
|
|
1635
|
+
assertKeyWithinLimit(logEntryKey);
|
|
1636
|
+
const entryBody = encodeJsonBytes(entry);
|
|
1637
|
+
let resolved;
|
|
1638
|
+
let createFailure;
|
|
1639
|
+
let notApplied = false;
|
|
1640
|
+
try {
|
|
1641
|
+
await this.#storage.put(logEntryKey, entryBody, {
|
|
1642
|
+
ifNoneMatch: "*",
|
|
1643
|
+
contentType: APPLICATION_JSON
|
|
1644
|
+
});
|
|
1645
|
+
resolved = entry;
|
|
1646
|
+
} catch (error) {
|
|
1647
|
+
createFailure = error;
|
|
1648
|
+
this.#observe429(error, entry.collection);
|
|
1649
|
+
if (isWriteConflict(error)) ctxMetrics().counter("db.r2.put.412_total", 1, {
|
|
1650
|
+
collection: entry.collection,
|
|
1651
|
+
step: "log-put"
|
|
1652
|
+
});
|
|
1653
|
+
else if (isDefinitiveCreateRejection(error)) throw error;
|
|
1654
|
+
else if (isCreateNotApplied(error)) notApplied = true;
|
|
1655
|
+
}
|
|
1656
|
+
if (resolved === void 0) {
|
|
1657
|
+
let occupant;
|
|
1658
|
+
let decision;
|
|
1659
|
+
try {
|
|
1660
|
+
occupant = await this.#readLogOccupant(logEntryKey);
|
|
1661
|
+
decision = tryAdoptOwnSessionLogEntry({
|
|
1662
|
+
self: entry,
|
|
1663
|
+
existing: occupant
|
|
1664
|
+
});
|
|
1665
|
+
} catch (error) {
|
|
1666
|
+
if (notApplied) throw createFailure;
|
|
1667
|
+
throw ambiguous(new AggregateError([createFailure, error], "The create and its readback could not be resolved"));
|
|
1668
|
+
}
|
|
1669
|
+
if (!decision.adopt) return { foreign: occupant };
|
|
1670
|
+
resolved = decision.entry;
|
|
1671
|
+
}
|
|
1672
|
+
await this.#assertCommitAboveDeleteFloor(logPrefix, seq, input.collection, input.docId, errorPrefix);
|
|
1673
|
+
return { committed: resolved };
|
|
1674
|
+
});
|
|
1675
|
+
if ("committed" in outcome) {
|
|
1676
|
+
committedEntry = outcome.committed;
|
|
1677
|
+
break;
|
|
1678
|
+
}
|
|
1679
|
+
const occupant = outcome.foreign;
|
|
1680
|
+
if (++probes > 1e5) throw new BaerlyError("Internal", `${errorPrefix}: log-tail forward-probe exceeded ${LOG_FORWARD_PROBE_CAP} on ${this.#currentJsonKey}`);
|
|
1681
|
+
if (commitWindow === void 0) seq = await findLogTail(this.#storage, logPrefix, seq + 1);
|
|
1682
|
+
else {
|
|
1683
|
+
commitWindow.push(occupant);
|
|
1684
|
+
const probe = await probeTailFrom(this.#storage, logPrefix, seq + 1);
|
|
1685
|
+
commitWindow.push(...probe.entries);
|
|
1686
|
+
if (guard !== void 0) {
|
|
1687
|
+
const replayed = decideInsertTarget(commitWindow, input);
|
|
1688
|
+
if (replayed !== void 0) return {
|
|
1689
|
+
replayed: true,
|
|
1690
|
+
entries: [replayed],
|
|
1691
|
+
currentEtag: baseEtag
|
|
1692
|
+
};
|
|
1693
|
+
}
|
|
1694
|
+
await decide(commitWindow, probe.tail);
|
|
1695
|
+
seq = probe.tail;
|
|
1696
|
+
}
|
|
1697
|
+
entry = mintEntry(seq);
|
|
1698
|
+
}
|
|
1699
|
+
const committedEntries = [committedEntry];
|
|
1700
|
+
const prevSeq = preCommitTail;
|
|
1701
|
+
const observedTail = seq + 1;
|
|
1702
|
+
const maint = getCurrentContext()?.maintenance;
|
|
1703
|
+
const gcInterval = maint?.options?.profile?.gcInterval ?? MAINTENANCE_PROFILE_CF_FREE.gcInterval;
|
|
1704
|
+
const forceFold = (input.forceMaintenance === true || admissionForces) && maint?.disabled !== true;
|
|
1705
|
+
const foldAtTailEntries = (maint?.options)?.foldAtTailEntries;
|
|
1706
|
+
if (maint?.disabled === true ? observedTail - current.tail_hint >= 128 : forceFold || foldAtTailEntries !== void 0 && observedTail - current.log_seq_start >= foldAtTailEntries || shouldFireMaintenance(current, prevSeq, gcInterval, observedTail)) await dispatchWriteTick({
|
|
1707
|
+
storage: this.#storage,
|
|
1708
|
+
currentJsonKey: this.#currentJsonKey,
|
|
1709
|
+
collection: input.collection,
|
|
1710
|
+
prevSeq,
|
|
1711
|
+
observedTail,
|
|
1712
|
+
...forceFold && { forceFold: true }
|
|
1713
|
+
});
|
|
1714
|
+
return {
|
|
1715
|
+
replayed: false,
|
|
1716
|
+
entries: committedEntries,
|
|
1717
|
+
currentEtag: baseEtag,
|
|
1718
|
+
classAOps: 1
|
|
1719
|
+
};
|
|
1720
|
+
}
|
|
1721
|
+
/**
|
|
1722
|
+
* Auto-create the per-collection `current.json` at
|
|
1723
|
+
* `this.#currentJsonKey` with a zero-state initial manifest. Called
|
|
1724
|
+
* by `#singleAttemptCommit` when the read returned `null` (fresh
|
|
1725
|
+
* bucket / fresh collection).
|
|
1726
|
+
*
|
|
1727
|
+
* Concurrency: `createCurrentJson` uses `If-None-Match: "*"`. If a
|
|
1728
|
+
* peer raced us and won, the storage layer surfaces `WriteConflict`; we
|
|
1729
|
+
* recover by re-reading the now-present manifest. We do NOT retry
|
|
1730
|
+
* the create — a single recover-via-read covers every race that
|
|
1731
|
+
* could have produced our null read.
|
|
1732
|
+
*
|
|
1733
|
+
* The seed shape (`snapshot: null`, `tail_hint: 0`, `log_seq_start:
|
|
1734
|
+
* 0`, `writer_fence: { epoch: 0, owner: "", claimed_at: "" }`)
|
|
1735
|
+
* matches `ensureTable`, so an
|
|
1736
|
+
* operator who pre-provisions and a writer who auto-creates land on
|
|
1737
|
+
* equivalent state. NOT byte-identical any more: `generation` is a
|
|
1738
|
+
* fresh nonce per provisioner. That is harmless — `If-None-Match`
|
|
1739
|
+
* means exactly one of them ever lands, and no reader compares a
|
|
1740
|
+
* generation across provisioners, only against the cursor it minted.
|
|
1741
|
+
*
|
|
1742
|
+
* @throws BaerlyError code="InvalidResponse" — the post-recover
|
|
1743
|
+
* re-read also returned null. Defensive guard; in practice
|
|
1744
|
+
* unreachable because the WriteConflict implies the key now exists.
|
|
1745
|
+
*/
|
|
1746
|
+
async #provisionCurrentJson() {
|
|
1747
|
+
const initial = {
|
|
1748
|
+
schema_version: 3,
|
|
1749
|
+
snapshot: null,
|
|
1750
|
+
tail_hint: 0,
|
|
1751
|
+
log_seq_start: 0,
|
|
1752
|
+
writer_fence: {
|
|
1753
|
+
epoch: 0,
|
|
1754
|
+
owner: "",
|
|
1755
|
+
claimed_at: ""
|
|
1756
|
+
},
|
|
1757
|
+
snapshot_bytes: 0,
|
|
1758
|
+
snapshot_rows: 0,
|
|
1759
|
+
generation: mintGeneration()
|
|
1760
|
+
};
|
|
1761
|
+
let createFailure;
|
|
1762
|
+
try {
|
|
1763
|
+
return await createCurrentJson(this.#storage, this.#currentJsonKey, initial);
|
|
1764
|
+
} catch (error) {
|
|
1765
|
+
if (!isWriteConflict(error) && !isCreateNotApplied(error)) throw error;
|
|
1766
|
+
createFailure = error;
|
|
1767
|
+
}
|
|
1768
|
+
const recovered = await readCurrentJson(this.#storage, this.#currentJsonKey);
|
|
1769
|
+
if (recovered === null && isCreateNotApplied(createFailure)) throw createFailure;
|
|
1770
|
+
if (recovered === null) throw new BaerlyError("InvalidResponse", `Writer: current.json missing at ${this.#currentJsonKey} after auto-create raced and recover read returned null`);
|
|
1771
|
+
return recovered;
|
|
1772
|
+
}
|
|
1773
|
+
/**
|
|
1774
|
+
* Fail the commit if the create landed at a sequence the collection has
|
|
1775
|
+
* already certified deleted.
|
|
1776
|
+
*
|
|
1777
|
+
* **What a sub-floor `seq` proves, and what it does not.** A winning
|
|
1778
|
+
* `If-None-Match: "*"` create means the slot was empty immediately before the
|
|
1779
|
+
* PUT, so the object this commit just wrote sits beneath every reader's floor
|
|
1780
|
+
* and no reader will ever consult it. What a sub-floor `seq` does NOT prove
|
|
1781
|
+
* is that the *logical mutation* is invisible. Two histories reach this
|
|
1782
|
+
* branch: the create re-filled a hole retirement had already certified
|
|
1783
|
+
* deleted (invisible — the defect this check exists for), or it landed in a
|
|
1784
|
+
* live empty slot that a fold and then a retirement pass swept out from under
|
|
1785
|
+
* it (visible through the snapshot). That second history is a real
|
|
1786
|
+
* over-rejection, pinned as contract by a test in
|
|
1787
|
+
* `./log-retirement-aba.test.ts`, not an accident. It is the safe direction,
|
|
1788
|
+
* and "What the caller is being told" below is why guessing between the two
|
|
1789
|
+
* is worse than reporting both as ambiguous.
|
|
1790
|
+
*
|
|
1791
|
+
* **`log_delete_floor <= seq < log_seq_start` is NOT a failure.** Not because
|
|
1792
|
+
* that band is provably safe — it is undecidable in the very same way. A
|
|
1793
|
+
* winning create means the slot was empty just before the PUT, so what a fold
|
|
1794
|
+
* absorbed there was either an earlier attempt of ours (mutation visible) or
|
|
1795
|
+
* a foreign writer's entry (ours invisible), and the fold keeps no writer
|
|
1796
|
+
* identity to tell them apart. The band is accepted because keying the check
|
|
1797
|
+
* on `log_seq_start` would reject ordinary post-fold commits — a far
|
|
1798
|
+
* larger harm than the residual it would catch. That residual is the
|
|
1799
|
+
* invisible half of the undecidable band `docs/spec/sync-protocol.md`
|
|
1800
|
+
* invariant 5 describes; it is not reachable by the certified-floor check,
|
|
1801
|
+
* by construction.
|
|
1802
|
+
*
|
|
1803
|
+
* The floor is clamped to `min(log_delete_floor, log_seq_start)` for the
|
|
1804
|
+
* reason invariant 12 gives: the `<= log_seq_start` bound is
|
|
1805
|
+
* transition-scoped, so an out-of-bound stored floor is readable off disk
|
|
1806
|
+
* and would otherwise fail a perfectly good commit.
|
|
1807
|
+
*
|
|
1808
|
+
* **What the caller is being told.** Not "your write failed" —
|
|
1809
|
+
* `AmbiguousCommit`. An earlier attempt by this same writer may have landed
|
|
1810
|
+
* and been folded before retirement removed the slot, and nothing durable
|
|
1811
|
+
* distinguishes that history from a foreign writer's entry being folded
|
|
1812
|
+
* instead: the fold keeps no writer identity, tombstones are purged,
|
|
1813
|
+
* `current.json` holds no per-writer completion state, and `writer_fence` is
|
|
1814
|
+
* not a replay filter (invariant 11). So the write contract under this fault
|
|
1815
|
+
* is at-least-once, and re-probing-and-re-applying is emphatically not a
|
|
1816
|
+
* safe default: `LogEntry.after` is a full post-image, so a duplicate
|
|
1817
|
+
* clobbers a concurrent newer value and mints a second `lsn` for one logical
|
|
1818
|
+
* mutation.
|
|
1819
|
+
*
|
|
1820
|
+
* The phantom object is DELETEd best-effort, and it is the only thing
|
|
1821
|
+
* standing between a rejected commit and a permanently leaked object.
|
|
1822
|
+
* Nothing reclaims the phantom afterwards: it sits at a seq *below*
|
|
1823
|
+
* `log_delete_floor` — that is the precondition for reaching this branch —
|
|
1824
|
+
* and `computeRetirableRange` (`./log-retention.ts`) *starts* at the
|
|
1825
|
+
* certified floor, so retirement never revisits a slot beneath its own
|
|
1826
|
+
* floor. GC does not reclaim log objects at all. So a `cleanup: "failed"`
|
|
1827
|
+
* on `db.write.ambiguous_commit_total` is a genuine permanent leak, not a
|
|
1828
|
+
* deferral. Deleting it is safe: no reader may read below the certified
|
|
1829
|
+
* floor (invariant 5). A failed cleanup is recorded on the counter and never masks the
|
|
1830
|
+
* throw.
|
|
1831
|
+
*
|
|
1832
|
+
* **A failed manifest read skips the check rather than failing the commit —
|
|
1833
|
+
* except an abort, which propagates.** The check runs over an already-durable
|
|
1834
|
+
* create, and an unreadable manifest is no evidence of a sub-floor `seq`, so a
|
|
1835
|
+
* transient read failure is swallowed. An `AbortError` is rethrown instead: it
|
|
1836
|
+
* is the caller's own cancellation rather than a blip, and it carries none of
|
|
1837
|
+
* the `retriable` re-run hazard that motivates swallowing the rest. The skip
|
|
1838
|
+
* is recorded on `db.write.delete_floor_check_skipped_total` so a sustained
|
|
1839
|
+
* rate is visible to an operator rather than silent.
|
|
1840
|
+
*
|
|
1841
|
+
* Cost: one Class B GET per commit.
|
|
1842
|
+
* `billableClassAOps = puts + lists` excludes GET, so billing is unchanged;
|
|
1843
|
+
* it is one of the calls `COMMIT_RESOLUTION_RESERVE` keeps on the request
|
|
1844
|
+
* ledger.
|
|
1845
|
+
*
|
|
1846
|
+
* @throws BaerlyError code="AmbiguousCommit"
|
|
1847
|
+
*/
|
|
1848
|
+
async #assertCommitAboveDeleteFloor(logPrefix, seq, collection, docId, errorPrefix) {
|
|
1849
|
+
let read;
|
|
1850
|
+
try {
|
|
1851
|
+
read = await readCurrentJson(this.#storage, this.#currentJsonKey);
|
|
1852
|
+
} catch (error) {
|
|
1853
|
+
if (isAbortError(error)) throw error;
|
|
1854
|
+
ctxMetrics().counter("db.write.delete_floor_check_skipped_total", 1, { collection });
|
|
1855
|
+
countPostCommitRefusal(error, collection, "delete-floor-check");
|
|
1856
|
+
return;
|
|
1857
|
+
}
|
|
1858
|
+
if (read === null) return;
|
|
1859
|
+
const deleteFloor = certifiedDeleteFloor(read.json);
|
|
1860
|
+
if (deleteFloor <= 0 || seq >= deleteFloor) return;
|
|
1861
|
+
let cleanup = "deleted";
|
|
1862
|
+
await this.#storage.delete(logObjectKey(logPrefix, seq)).catch(() => {
|
|
1863
|
+
cleanup = "failed";
|
|
1864
|
+
});
|
|
1865
|
+
ctxMetrics().counter("db.write.ambiguous_commit_total", 1, {
|
|
1866
|
+
collection,
|
|
1867
|
+
cleanup
|
|
1868
|
+
});
|
|
1869
|
+
throw new BaerlyError("AmbiguousCommit", `${errorPrefix}: the committing create at seq ${seq} on ${this.#currentJsonKey} landed below the certified delete floor ${deleteFloor}; that log object is beneath every reader's floor, and this mutation may or may not have been applied by an earlier attempt — retry is at-least-once`, {
|
|
1870
|
+
resolution: CODE_RESOLUTIONS.AmbiguousCommit,
|
|
1871
|
+
_id: docId
|
|
1872
|
+
});
|
|
1873
|
+
}
|
|
1874
|
+
/**
|
|
1875
|
+
* Run one commit slot's attempt, `fn` (the committing create and the
|
|
1876
|
+
* calls that resolve it), under a hold on the active request ledger of
|
|
1877
|
+
* everything it may spend: the create at full retries, plus
|
|
1878
|
+
* {@link COMMIT_RESOLUTION_RESERVE} for the readback and the delete-floor
|
|
1879
|
+
* check. `fn` runs in a child observability context carrying the hold, so
|
|
1880
|
+
* only its own storage calls draw on it; work outside that context (a
|
|
1881
|
+
* `ctx.waitUntil` write tick of an earlier row, the read cache) sees the
|
|
1882
|
+
* ledger net of it and cannot spend it. The hold is released when `fn`
|
|
1883
|
+
* settles.
|
|
1884
|
+
*
|
|
1885
|
+
* Refuses, before `fn` sends anything, when the ledger's room is short
|
|
1886
|
+
* of the hold. No create of this commit has landed or can land then:
|
|
1887
|
+
* before the first slot nothing was sent, and before a later one a
|
|
1888
|
+
* foreign occupant holds the slot this commit's only send targeted. A host without request
|
|
1889
|
+
* limits (Node, or no ledger) never refuses and takes no hold.
|
|
1890
|
+
*
|
|
1891
|
+
* @throws BaerlyError code="CapacityExceeded", cause `{ refused: true }`.
|
|
1892
|
+
*/
|
|
1893
|
+
/**
|
|
1894
|
+
* The collection segment of `current.json`'s key, for messages that
|
|
1895
|
+
* reach HTTP callers unscrubbed (`CapacityExceeded` is `public`), which
|
|
1896
|
+
* must not carry the storage key.
|
|
1897
|
+
*/
|
|
1898
|
+
#collectionName() {
|
|
1899
|
+
const parts = this.#currentJsonKey.split("/");
|
|
1900
|
+
return parts[parts.length - 2] ?? "";
|
|
1901
|
+
}
|
|
1902
|
+
async #withCommitHold(errorPrefix, fn) {
|
|
1903
|
+
const ctx = getCurrentContext();
|
|
1904
|
+
const ledger = ctx?.ledger;
|
|
1905
|
+
const remaining = ledger?.storageRemaining() ?? 1e400;
|
|
1906
|
+
if (ctx === void 0 || ledger === void 0 || remaining === 1e400) return await fn();
|
|
1907
|
+
const needed = 9;
|
|
1908
|
+
if (remaining < needed) throw new BaerlyError("CapacityExceeded", `${errorPrefix}: this request has ${String(remaining)} storage calls left, fewer than the ${String(needed)} a commit to collection ${JSON.stringify(this.#collectionName())} may need (the committing create, with retries, plus resolving it), so nothing was committed; the work this request needs does not fit in one request on this host`, { cause: {
|
|
1909
|
+
refused: true,
|
|
1910
|
+
needed,
|
|
1911
|
+
remaining
|
|
1912
|
+
} });
|
|
1913
|
+
const hold = ledger.hold(needed);
|
|
1914
|
+
try {
|
|
1915
|
+
return await runWithContext({
|
|
1916
|
+
...ctx,
|
|
1917
|
+
hold
|
|
1918
|
+
}, fn);
|
|
1919
|
+
} finally {
|
|
1920
|
+
hold.release();
|
|
1921
|
+
}
|
|
1922
|
+
}
|
|
1923
|
+
/**
|
|
1924
|
+
* Walk `log/<logSeqStart>.json` … `log/<nextSeq - 1>.json` with
|
|
1925
|
+
* bounded parallelism via `walkLogRange`. Materialised entries are
|
|
1926
|
+
* discarded — the walk's only job is to surface a hole or a
|
|
1927
|
+
* malformed body inside the visible range as
|
|
1928
|
+
* `BaerlyError{code:"Internal"}` / `"InvalidResponse"`.
|
|
1929
|
+
*
|
|
1930
|
+
* Gated on `verifyLogIntegrityOnCommit`; default off in production
|
|
1931
|
+
* because the per-doc fold already lives in the read path. See the
|
|
1932
|
+
* option's docstring for the rationale and the opt-in convention.
|
|
1933
|
+
*
|
|
1934
|
+
* `logSeqStart` is the boundary set by the compactor on
|
|
1935
|
+
* `current.json.log_seq_start`. Entries below it have been folded
|
|
1936
|
+
* into the snapshot and may have been swept off the bucket, so the
|
|
1937
|
+
* walk MUST NOT GET-require them.
|
|
1938
|
+
*/
|
|
1939
|
+
async #walkLog(logPrefix, logSeqStart, nextSeq) {
|
|
1940
|
+
await walkLogRange(this.#storage, logPrefix, logSeqStart, nextSeq);
|
|
1941
|
+
}
|
|
1942
|
+
/**
|
|
1943
|
+
* Read `[fromSeq, logSeqStart)` for a windowed commit (insert guard or
|
|
1944
|
+
* admission) whose window starts below the floor of this commit's
|
|
1945
|
+
* manifest read: a fold absorbed those entries after the caller's read. Slots below the floor stay
|
|
1946
|
+
* readable until log retirement deletes them, so a missing slot means
|
|
1947
|
+
* this commit can no longer check its window: `WriteConflict`, nothing
|
|
1948
|
+
* committed, and the caller's next read sees the folded state. A window
|
|
1949
|
+
* longer than {@link LOG_FORWARD_PROBE_CAP} is refused the same way
|
|
1950
|
+
* rather than spending an unbounded run of GETs on the write path.
|
|
1951
|
+
*
|
|
1952
|
+
* @throws BaerlyError code="WriteConflict" — a slot is missing, or the
|
|
1953
|
+
* range exceeds the cap.
|
|
1954
|
+
* @throws BaerlyError code="InvalidResponse" — a slot's body is not JSON.
|
|
1955
|
+
*/
|
|
1956
|
+
async #readFoldedWindow(logPrefix, fromSeq, logSeqStart, errorPrefix) {
|
|
1957
|
+
if (fromSeq >= logSeqStart) return [];
|
|
1958
|
+
const refuse = (detail) => new BaerlyError("WriteConflict", `${errorPrefix}: commit window [${fromSeq}, ${logSeqStart}) on ${this.#currentJsonKey} ${detail}; nothing was committed`);
|
|
1959
|
+
if (logSeqStart - fromSeq > 1e5) throw refuse(`exceeds ${LOG_FORWARD_PROBE_CAP} folded entries`);
|
|
1960
|
+
const entries = [];
|
|
1961
|
+
for (let chunk = fromSeq; chunk < logSeqStart; chunk += 16) {
|
|
1962
|
+
const end = Math.min(chunk + 16, logSeqStart);
|
|
1963
|
+
const keys = Array.from({ length: end - chunk }, (_, i) => logObjectKey(logPrefix, chunk + i));
|
|
1964
|
+
const bodies = await Promise.all(keys.map((key) => this.#storage.get(key)));
|
|
1965
|
+
for (let i = 0; i < bodies.length; i++) {
|
|
1966
|
+
const got = bodies[i];
|
|
1967
|
+
if (got === null || got === void 0) throw refuse(`was retired at seq ${chunk + i} before it could be checked`);
|
|
1968
|
+
try {
|
|
1969
|
+
entries.push(decodeJsonBytes(got.body));
|
|
1970
|
+
} catch (error) {
|
|
1971
|
+
throw new BaerlyError("InvalidResponse", `${errorPrefix}: malformed log entry at ${keys[i]}`, { cause: error });
|
|
1972
|
+
}
|
|
1973
|
+
}
|
|
1974
|
+
}
|
|
1975
|
+
return entries;
|
|
1976
|
+
}
|
|
1977
|
+
/**
|
|
1978
|
+
* Read the occupant of a slot whose committing create was rejected, with
|
|
1979
|
+
* one `Storage.get` (the adapter retries it; the Writer does not). A failed
|
|
1980
|
+
* read, an empty slot, or an occupant without a writer identity throws:
|
|
1981
|
+
* none of them proves the slot holds a foreign entry rather than a pending
|
|
1982
|
+
* send of our own.
|
|
1983
|
+
*/
|
|
1984
|
+
async #readLogOccupant(key) {
|
|
1985
|
+
const got = await this.#storage.get(key);
|
|
1986
|
+
if (got === null) throw new BaerlyError("NotFound", `Writer: ${key} is empty after its create was rejected`);
|
|
1987
|
+
let existing;
|
|
1988
|
+
try {
|
|
1989
|
+
existing = decodeJsonBytes(got.body);
|
|
1990
|
+
} catch (error) {
|
|
1991
|
+
throw new BaerlyError("InvalidResponse", `Writer: malformed log occupant at ${key}`, { cause: error });
|
|
1992
|
+
}
|
|
1993
|
+
if (!hasWriterIdentity(existing)) throw new BaerlyError("InvalidResponse", `Writer: malformed log occupant at ${key}`);
|
|
1994
|
+
return existing;
|
|
1995
|
+
}
|
|
1996
|
+
/**
|
|
1997
|
+
* Bump the `db.r2.put.429_total` counter when `err` looks like an
|
|
1998
|
+
* R2 prefix-partition rate-limit. Best-effort: detected via
|
|
1999
|
+
* `BaerlyError{code:"NetworkError"}` with a `429` token in the
|
|
2000
|
+
* message. Called from every PUT call site's catch arm; mutually
|
|
2001
|
+
* exclusive in practice with `isWriteConflict` (412 ≠ 429).
|
|
2002
|
+
*/
|
|
2003
|
+
#observe429(err, collection) {
|
|
2004
|
+
if (is429(err)) ctxMetrics().counter("db.r2.put.429_total", 1, { collection });
|
|
2005
|
+
}
|
|
2006
|
+
/**
|
|
2007
|
+
* Emit the per-logical-write `class_a_ops_per_logical_write`
|
|
2008
|
+
* histogram for `commit`. `classAOps` is the committing create, computed
|
|
2009
|
+
* by `#singleAttemptCommit`.
|
|
2010
|
+
*/
|
|
2011
|
+
#emitWriteMetrics(collection, classAOps) {
|
|
2012
|
+
ctxMetrics().histogram("db.write.class_a_ops_per_logical_write", classAOps, { collection });
|
|
2013
|
+
}
|
|
2014
|
+
};
|
|
2015
|
+
/**
|
|
2016
|
+
* `true` when a create rejection proves the create did not land. Under the
|
|
2017
|
+
* `Storage.put` contract an adapter that retried internally reports such a
|
|
2018
|
+
* rejection as `NetworkError`, so these codes describe the only attempt.
|
|
2019
|
+
*/
|
|
2020
|
+
const isDefinitiveCreateRejection = (err) => err instanceof BaerlyError && (err.code === "AccessDenied" || err.code === "InvalidConfig");
|
|
2021
|
+
/**
|
|
2022
|
+
* `true` when a create-only put reports, per the `Storage.put` contract,
|
|
2023
|
+
* that no attempt of the call was applied: a `NetworkError` after every
|
|
2024
|
+
* attempt was throttled or refused before issue, or the request ledger's
|
|
2025
|
+
* `CapacityExceeded` when it refused the call before any attempt of
|
|
2026
|
+
* unknown outcome. `cause.notApplied` is the proof either way.
|
|
2027
|
+
*/
|
|
2028
|
+
const isCreateNotApplied = (err) => err instanceof BaerlyError && (err.code === "NetworkError" || err.code === "CapacityExceeded") && err.cause?.notApplied === true;
|
|
2029
|
+
/**
|
|
2030
|
+
* Count a post-commit step the request ledger refused on
|
|
2031
|
+
* `db.write.post_commit_refused_total`. The step runs after a known
|
|
2032
|
+
* commit and swallows its failure, so the refusal leaves the commit
|
|
2033
|
+
* acknowledged; `phase` names the step that went without (the delete-floor
|
|
2034
|
+
* check is the only one).
|
|
2035
|
+
*/
|
|
2036
|
+
const countPostCommitRefusal = (err, collection, phase) => {
|
|
2037
|
+
if (err instanceof BaerlyError && err.code === "CapacityExceeded" && err.cause?.refused === true) ctxMetrics().counter("db.write.post_commit_refused_total", 1, {
|
|
2038
|
+
collection,
|
|
2039
|
+
phase
|
|
2040
|
+
});
|
|
2041
|
+
};
|
|
2042
|
+
/**
|
|
2043
|
+
* Reject an `insertGuard` on anything but an `I`, or with an
|
|
2044
|
+
* `absentBelowSeq` that is not a log seq. Runs before any I/O.
|
|
2045
|
+
*/
|
|
2046
|
+
const assertInsertGuardShape = (input) => {
|
|
2047
|
+
if (input.op !== "I") throw new BaerlyError("InvalidConfig", `Writer: insertGuard is valid only with op "I"; got op ${JSON.stringify(input.op)}`);
|
|
2048
|
+
const seq = input.insertGuard?.absentBelowSeq;
|
|
2049
|
+
if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 0) throw new BaerlyError("InvalidConfig", `Writer: insertGuard.absentBelowSeq must be a non-negative safe integer; got ${String(seq)}`);
|
|
2050
|
+
const replay = input.insertGuard?.replayIdentical;
|
|
2051
|
+
if (replay !== void 0 && typeof replay !== "boolean") throw new BaerlyError("InvalidConfig", `Writer: insertGuard.replayIdentical must be a boolean; got ${typeof replay}`);
|
|
2052
|
+
};
|
|
2053
|
+
/**
|
|
2054
|
+
* Reject an `admission` whose `fromSeq` is not a log seq, or differs from
|
|
2055
|
+
* the insert guard's window start. Runs before any I/O.
|
|
2056
|
+
*/
|
|
2057
|
+
const assertAdmissionShape = (input) => {
|
|
2058
|
+
const seq = input.admission?.fromSeq;
|
|
2059
|
+
if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 0) throw new BaerlyError("InvalidConfig", `Writer: admission.fromSeq must be a non-negative safe integer; got ${String(seq)}`);
|
|
2060
|
+
if (typeof input.admission?.check !== "function") throw new BaerlyError("InvalidConfig", "Writer: admission.check must be a function");
|
|
2061
|
+
const guarded = input.insertGuard?.absentBelowSeq;
|
|
2062
|
+
if (guarded !== void 0 && guarded !== seq) throw new BaerlyError("InvalidConfig", `Writer: admission.fromSeq ${seq} must equal insertGuard.absentBelowSeq ${guarded}`);
|
|
2063
|
+
};
|
|
2064
|
+
/**
|
|
2065
|
+
* Window decision for a guarded insert. `window` holds the log entries
|
|
2066
|
+
* in `[absentBelowSeq, seq)` in seq order, unfiltered. The LAST entry for
|
|
2067
|
+
* this `(collection, doc_id)` decides: a `D`, or no entry, means the row
|
|
2068
|
+
* is absent and the insert may commit (`undefined`). An `I` or `U` means a
|
|
2069
|
+
* row is live: with `replayIdentical` set and that entry's `after` equal
|
|
2070
|
+
* to the body, the insert is a replay of its own earlier success and the
|
|
2071
|
+
* entry is returned; otherwise the insert throws `AlreadyExists`.
|
|
2072
|
+
*
|
|
2073
|
+
* @throws BaerlyError code="AlreadyExists"
|
|
2074
|
+
*/
|
|
2075
|
+
const decideInsertTarget = (window, input) => {
|
|
2076
|
+
for (let i = window.length - 1; i >= 0; i--) {
|
|
2077
|
+
const e = window[i];
|
|
2078
|
+
if (!isOwnCollection(e.collection, input.collection) || e.doc_id !== input.docId) continue;
|
|
2079
|
+
if (e.op === "D") return;
|
|
2080
|
+
if (input.insertGuard?.replayIdentical === true && input.body !== void 0 && insertReplaysRow(input.body, e.after)) return e;
|
|
2081
|
+
throw insertAlreadyExists(input.collection, input.docId);
|
|
2082
|
+
}
|
|
2083
|
+
};
|
|
2084
|
+
/** `true` when a decoded log occupant carries the identity adoption compares. */
|
|
2085
|
+
const hasWriterIdentity = (value) => {
|
|
2086
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
|
|
2087
|
+
const { session, seq } = value;
|
|
2088
|
+
return typeof session === "string" && session.length > 0 && typeof seq === "number" && Number.isSafeInteger(seq) && seq >= 0;
|
|
2089
|
+
};
|
|
2090
|
+
/**
|
|
2091
|
+
* `true` when a rejection is an `AbortError` — the caller's own cancellation
|
|
2092
|
+
* through an `AbortSignal`, never a transient storage failure. Matched
|
|
2093
|
+
* structurally on `name` rather than `instanceof DOMException` because a host
|
|
2094
|
+
* may surface an abort as a plain `Error` so named (as `Storage` impls and the
|
|
2095
|
+
* test fixtures do). `@baerly/client` carries the same predicate; it is
|
|
2096
|
+
* duplicated rather than shared because `server` may not import `client`
|
|
2097
|
+
* (`scripts/lint-package-layers.mjs`) and one predicate does not earn a new
|
|
2098
|
+
* module in `@baerly/protocol`.
|
|
2099
|
+
*/
|
|
2100
|
+
const isAbortError = (err) => typeof err === "object" && err !== null && "name" in err && err.name === "AbortError";
|
|
2101
|
+
/**
|
|
2102
|
+
* `true` when the underlying storage surfaced an R2 prefix-partition
|
|
2103
|
+
* rate-limit. {@link S3HttpStorage} stamps the upstream HTTP status
|
|
2104
|
+
* onto `BaerlyError.cause` as `{ status }`; we discriminate on that
|
|
2105
|
+
* structured field rather than regex-matching the message.
|
|
2106
|
+
*/
|
|
2107
|
+
const is429 = (err) => {
|
|
2108
|
+
if (!(err instanceof BaerlyError) || err.code !== "NetworkError") return false;
|
|
2109
|
+
return err.cause?.status === 429;
|
|
2110
|
+
};
|
|
2111
|
+
// packages/server/src/query.ts
|
|
2112
|
+
/**
|
|
2113
|
+
* Read engine + mutation terminals: `Query<T>` builder, the
|
|
2114
|
+
* three read terminals (`first`, `all`, `count`) that fold the log
|
|
2115
|
+
* under a fresh `current.json` snapshot, and the four mutation
|
|
2116
|
+
* terminals (`insert`, `update`, `replace`, `delete`). Each mutation
|
|
2117
|
+
* verb compiles to exactly one `Writer.commit()` call.
|
|
2118
|
+
*
|
|
2119
|
+
* Every modifier (`.where` / `.order` / `.limit`) returns a NEW
|
|
2120
|
+
* `Query<T>` carrying merged frozen state — the input state is never
|
|
2121
|
+
* mutated. Identity inequality between the original and the returned
|
|
2122
|
+
* builder is intentional: callers cannot share a chain.
|
|
2123
|
+
*
|
|
2124
|
+
* `.where()` AND-merges through `mergePredicateWires` (clause-level
|
|
2125
|
+
* AND on the normalised wire form).
|
|
2126
|
+
* `.order()` and `.limit()` are last-call-wins (state replace).
|
|
2127
|
+
*
|
|
2128
|
+
* Each terminal reads `current.json` FRESH, loads the snapshot it names,
|
|
2129
|
+
* and walks `[log_seq_start, tail_hint)` directly — no cache, no
|
|
2130
|
+
* `list()` round-trip for the log. Per the multi-instance rules, every
|
|
2131
|
+
* read sees a fresh CAS snapshot.
|
|
2132
|
+
*
|
|
2133
|
+
* Mutation terminals are SINGLE-ATTEMPT per call site. Contention on the
|
|
2134
|
+
* committing log create is resolved inside `Writer.commit()` (occupant
|
|
2135
|
+
* readback, then a bounded forward probe); the verbs do NOT add their
|
|
2136
|
+
* own retry loop. Errors from `commit()` surface unchanged — the caller
|
|
2137
|
+
* decides whether to re-run.
|
|
2138
|
+
*
|
|
2139
|
+
* @see ../../../docs/spec/sync-protocol.md
|
|
2140
|
+
*/
|
|
2141
|
+
const PATCH_ID_RESOLUTION = "Omit `_id` from the patch, or pass the row's own `_id`.";
|
|
2142
|
+
/**
|
|
2143
|
+
* Serialise a {@link CurrentJson} head into an opaque wire cursor.
|
|
2144
|
+
* `tail` is the DISCOVERED tail (defaults to `json.tail_hint` when no
|
|
2145
|
+
* probe has run). Physical snapshot keys feed the digest but never
|
|
2146
|
+
* cross the HTTP boundary.
|
|
2147
|
+
*
|
|
2148
|
+
* @internal — exported for `query.test.ts`.
|
|
2149
|
+
*/
|
|
2150
|
+
const manifestPointerDigest = (seed) => {
|
|
2151
|
+
let hash = 14695981039346656037n;
|
|
2152
|
+
for (let i = 0; i < seed.length; i++) {
|
|
2153
|
+
hash ^= BigInt(seed.charCodeAt(i));
|
|
2154
|
+
hash = hash * 1099511628211n & 18446744073709551615n;
|
|
2155
|
+
}
|
|
2156
|
+
return hash.toString(36).padStart(13, "0");
|
|
2157
|
+
};
|
|
2158
|
+
const serializeManifestPointer = (json, tail = json.tail_hint) => `m1:${manifestPointerDigest([
|
|
2159
|
+
json.snapshot ?? "none",
|
|
2160
|
+
json.log_seq_start,
|
|
2161
|
+
json.tail_hint,
|
|
2162
|
+
json.snapshot_bytes,
|
|
2163
|
+
json.snapshot_rows,
|
|
2164
|
+
tail
|
|
2165
|
+
].join("|"))}`;
|
|
2166
|
+
/**
|
|
2167
|
+
* Returns the id iff `wire` carries exactly one clause and that
|
|
2168
|
+
* clause is `{op:"eq", field:"_id", value:<string>}` — the shape
|
|
2169
|
+
* `runRead` short-circuits to a single `Map.get`. Any other shape
|
|
2170
|
+
* (multi-clause, non-`eq` op, non-`_id` field, non-string value)
|
|
2171
|
+
* returns `undefined` and falls through to the scan path.
|
|
2172
|
+
*
|
|
2173
|
+
* Kernel-internal `_id`-shaped wires (built by `byId`,
|
|
2174
|
+
* `runByIdWithMeta`, `runInsert`) bypass the wire validator by
|
|
2175
|
+
* design (`_id` at the root is a wire-only rejection); this
|
|
2176
|
+
* recogniser matches the same shape so the fast-path stays
|
|
2177
|
+
* symmetric.
|
|
2178
|
+
*
|
|
2179
|
+
* @internal
|
|
2180
|
+
*/
|
|
2181
|
+
const singleIdFromPredicate = (wire) => {
|
|
2182
|
+
if (wire === void 0) return;
|
|
2183
|
+
if (wire.clauses.length !== 1) return;
|
|
2184
|
+
const clause = wire.clauses[0];
|
|
2185
|
+
if (clause.op !== "eq" || clause.field !== "_id") return;
|
|
2186
|
+
return typeof clause.value === "string" ? clause.value : void 0;
|
|
2187
|
+
};
|
|
2188
|
+
/**
|
|
2189
|
+
* Build a `Query<T>` from a context + frozen state. Every modifier
|
|
2190
|
+
* returns a NEW `Query<T>` carrying merged state — the input state
|
|
2191
|
+
* is never mutated. Identity inequality with the input chain is
|
|
2192
|
+
* intentional.
|
|
2193
|
+
*
|
|
2194
|
+
* Validation happens at the public seams — `Query.where(p)`
|
|
2195
|
+
* normalises + validates the incoming fragment before merging into
|
|
2196
|
+
* `state.wire`. By the time `makeQuery` is reached from elsewhere
|
|
2197
|
+
* (`Collection.where`, `runAllWithMeta`, kernel-internal `_id`-shaped
|
|
2198
|
+
* wires from `byId` / `runByIdWithMeta` / `runInsert`), the wire is
|
|
2199
|
+
* already trusted.
|
|
2200
|
+
*
|
|
2201
|
+
* @example
|
|
2202
|
+
* ```ts
|
|
2203
|
+
* const q = makeQuery<Ticket>(ctx, { wire: undefined, order: undefined, limit: undefined });
|
|
2204
|
+
* const open = await q.where({ status: "open" }).order({ created_at: "desc" }).limit(10).all();
|
|
2205
|
+
* ```
|
|
2206
|
+
*
|
|
2207
|
+
* @internal
|
|
2208
|
+
*/
|
|
2209
|
+
const makeQuery = (ctx, state) => {
|
|
2210
|
+
return {
|
|
2211
|
+
where: (p) => {
|
|
2212
|
+
const incoming = normalizePredicateArg(p);
|
|
2213
|
+
validateWire(incoming);
|
|
2214
|
+
return makeQuery(ctx, {
|
|
2215
|
+
...state,
|
|
2216
|
+
wire: state.wire === void 0 ? incoming : mergePredicateWires(state.wire, incoming)
|
|
2217
|
+
});
|
|
2218
|
+
},
|
|
2219
|
+
order: (s) => makeQuery(ctx, {
|
|
2220
|
+
...state,
|
|
2221
|
+
order: s
|
|
2222
|
+
}),
|
|
2223
|
+
limit: (n) => makeQuery(ctx, {
|
|
2224
|
+
...state,
|
|
2225
|
+
limit: n
|
|
2226
|
+
}),
|
|
2227
|
+
first: async () => {
|
|
2228
|
+
const { rows } = await runRead(ctx, {
|
|
2229
|
+
...state,
|
|
2230
|
+
limit: 1
|
|
2231
|
+
});
|
|
2232
|
+
return rows[0];
|
|
2233
|
+
},
|
|
2234
|
+
all: async () => {
|
|
2235
|
+
return (await runRead(ctx, state)).rows;
|
|
2236
|
+
},
|
|
2237
|
+
count: async () => {
|
|
2238
|
+
return (await runRead(ctx, state, { countOnly: true })).count;
|
|
2239
|
+
},
|
|
2240
|
+
update: (patch) => runUpdate(ctx, state, patch),
|
|
2241
|
+
delete: () => runDelete(ctx, state)
|
|
2242
|
+
};
|
|
2243
|
+
};
|
|
2244
|
+
/**
|
|
2245
|
+
* Server-internal read entry surfacing the manifest-pointer cursor
|
|
2246
|
+
* and freshness flag alongside the materialised rows. The HTTP
|
|
2247
|
+
* router calls this directly so the read-response handler can pack
|
|
2248
|
+
* `_meta` onto the envelope; the public `Query<T>` terminals
|
|
2249
|
+
* destructure the rows out and discard the cursor to keep the
|
|
2250
|
+
* locked interface signature. Single-row routes (`GET /v1/c/:collection/:id`)
|
|
2251
|
+
* call this with `limit:1` and pick `rows[0]`.
|
|
2252
|
+
*
|
|
2253
|
+
* `state.wire` is assumed already validated — the public seam
|
|
2254
|
+
* (`Query.where(p)` → `normalizePredicateArg` → `validateWire`) is
|
|
2255
|
+
* the wire-arrival contract surface. Router callers parsing
|
|
2256
|
+
* `?where=` run `validateWire` themselves inside `parseWhereParam`,
|
|
2257
|
+
* keeping a single validation pass per wire.
|
|
2258
|
+
*
|
|
2259
|
+
* @internal
|
|
2260
|
+
*/
|
|
2261
|
+
const runAllWithMeta = (ctx, state, opts) => {
|
|
2262
|
+
return runRead(ctx, state, opts);
|
|
2263
|
+
};
|
|
2264
|
+
/**
|
|
2265
|
+
* By-id read entry surfacing the same `ReadResult<T>` shape as
|
|
2266
|
+
* {@link runAllWithMeta} so the HTTP router can preserve the
|
|
2267
|
+
* `_meta` wire envelope while routing through the PK-lookup
|
|
2268
|
+
* fast-path. Mirrors {@link runAllWithMeta}'s signature; the
|
|
2269
|
+
* wire is built internally as a single-clause `{op:"eq",
|
|
2270
|
+
* field:"_id", value:id}` shape (same form as the `byId` helper in
|
|
2271
|
+
* `./collection.ts` and the `runInsert` duplicate-collision check)
|
|
2272
|
+
* which routes through `runRead`'s `singleIdFromPredicate`
|
|
2273
|
+
* short-circuit automatically.
|
|
2274
|
+
*
|
|
2275
|
+
* Bypasses {@link validateWire} — the wire is kernel-constructed,
|
|
2276
|
+
* never wire-submitted, so it would always pass the structural
|
|
2277
|
+
* rules. Skipping the validator also keeps this helper usable
|
|
2278
|
+
* from kernel-internal sites (`Collection<T>.get` etc.) without
|
|
2279
|
+
* tripping the wire-only rule that bans top-level `_id`.
|
|
2280
|
+
*
|
|
2281
|
+
* `id` is checked by {@link assertReadDocId} before any I/O.
|
|
2282
|
+
*
|
|
2283
|
+
* @internal — router uses this to preserve `_meta` envelope;
|
|
2284
|
+
* mirrors {@link runAllWithMeta} and {@link Collection.get}.
|
|
2285
|
+
*/
|
|
2286
|
+
const runByIdWithMeta = async (ctx, id) => {
|
|
2287
|
+
assertReadDocId(id);
|
|
2288
|
+
return await runRead(ctx, {
|
|
2289
|
+
wire: { clauses: [{
|
|
2290
|
+
op: "eq",
|
|
2291
|
+
field: "_id",
|
|
2292
|
+
value: id
|
|
2293
|
+
}] },
|
|
2294
|
+
order: void 0,
|
|
2295
|
+
limit: 1
|
|
2296
|
+
});
|
|
2297
|
+
};
|
|
2298
|
+
/**
|
|
2299
|
+
* Build a fresh `Writer` bound to this collection's `current.json`.
|
|
2300
|
+
* Construction is zero-I/O (writer.ts:160) so we mint one per
|
|
2301
|
+
* `commit()` rather than caching on the chain; the writer holds no
|
|
2302
|
+
* per-commit state, so this costs nothing.
|
|
2303
|
+
*/
|
|
2304
|
+
const writerFor = (ctx) => new Writer({
|
|
2305
|
+
storage: ctx.storage,
|
|
2306
|
+
currentJsonKey: `${ctx.collectionPrefix}/current.json`
|
|
2307
|
+
});
|
|
2308
|
+
/**
|
|
2309
|
+
* Throw the refusal `decision` carries: `MaintenancePending` when the
|
|
2310
|
+
* pending tail would make room once it folds, after dispatching one forced
|
|
2311
|
+
* fold pass (G6, fold-then-refuse) through the request's maintenance
|
|
2312
|
+
* dispatch, so on Cloudflare it runs in `ctx.waitUntil` like any write
|
|
2313
|
+
* tick; otherwise `CapacityExceeded`. Under `BAERLY_MAINTENANCE_DISABLE`
|
|
2314
|
+
* nothing can fold, so the refusal stays `CapacityExceeded`.
|
|
2315
|
+
*
|
|
2316
|
+
* @param tail The log tail the decision folded through.
|
|
2317
|
+
*/
|
|
2318
|
+
const throwRefusal = async (ctx, decision, tail) => {
|
|
2319
|
+
if (decision.foldFreesRoom && getCurrentContext()?.maintenance?.disabled !== true) {
|
|
2320
|
+
await dispatchWriteTick({
|
|
2321
|
+
storage: ctx.storage,
|
|
2322
|
+
currentJsonKey: `${ctx.collectionPrefix}/current.json`,
|
|
2323
|
+
collection: ctx.collectionName,
|
|
2324
|
+
prevSeq: tail,
|
|
2325
|
+
observedTail: tail,
|
|
2326
|
+
forceFold: true
|
|
2327
|
+
});
|
|
2328
|
+
throw maintenancePending(ctx.collectionName);
|
|
2329
|
+
}
|
|
2330
|
+
throw decision.refusal;
|
|
2331
|
+
};
|
|
2332
|
+
/**
|
|
2333
|
+
* Thrown from an admission check when the row a planned `U` / `D` targets
|
|
2334
|
+
* was deleted after the verb's read, or no longer qualifies for it. The
|
|
2335
|
+
* writer propagates it before the committing create, so nothing commits;
|
|
2336
|
+
* the verb that planned the write catches it (`update` / `delete` leave the
|
|
2337
|
+
* row out of their count, `replace` throws `NotFound`). Never escapes
|
|
2338
|
+
* `query.ts`.
|
|
2339
|
+
*/
|
|
2340
|
+
var RowSkipped = class extends Error {
|
|
2341
|
+
constructor(docId) {
|
|
2342
|
+
super(`row ${JSON.stringify(docId)} changed under the write`);
|
|
2343
|
+
this.name = "RowSkipped";
|
|
2344
|
+
}
|
|
2345
|
+
};
|
|
2346
|
+
/**
|
|
2347
|
+
* The newest version of `docId` among `entries` (every entry committed
|
|
2348
|
+
* after the verb's read, in seq order): `"gone"` when any of them deletes
|
|
2349
|
+
* it, its newest post-image when one rewrote it, `undefined` when none
|
|
2350
|
+
* touched it.
|
|
2351
|
+
*/
|
|
2352
|
+
const newestVersion = (entries, collection, docId) => {
|
|
2353
|
+
let newest;
|
|
2354
|
+
for (const entry of entries) {
|
|
2355
|
+
if (!isOwnCollection(entry.collection, collection) || entry.doc_id !== docId) continue;
|
|
2356
|
+
if (entry.op === "D" || entry.after === void 0) return "gone";
|
|
2357
|
+
newest = entry.after;
|
|
2358
|
+
}
|
|
2359
|
+
return newest;
|
|
2360
|
+
};
|
|
2361
|
+
/** A never-provisioned collection: no snapshot, nothing folded. */
|
|
2362
|
+
const EMPTY_HEAD = {
|
|
2363
|
+
snapshot_rows: 0,
|
|
2364
|
+
snapshot_bytes: 0,
|
|
2365
|
+
log_seq_start: 0
|
|
2366
|
+
};
|
|
2367
|
+
/**
|
|
2368
|
+
* Admit `writes` against the serving host's fold ceiling before any commit
|
|
2369
|
+
* (see `./capacity.ts`), throwing as {@link throwRefusal} does when they
|
|
2370
|
+
* would grow the collection past it.
|
|
2371
|
+
*
|
|
2372
|
+
* The returned admission re-runs the verb's decisions at commit time.
|
|
2373
|
+
* Each commit passes `next()` to `Writer.commit`, which hands back every
|
|
2374
|
+
* log entry in `[fromSeq, seq)`: the entries this decision has not seen.
|
|
2375
|
+
*
|
|
2376
|
+
* - **Row (EvalPlanQual).** A planned `U` / `D` whose row any entry
|
|
2377
|
+
* committed after the read touched (in this window, or in an earlier
|
|
2378
|
+
* row's window of the same batch) is re-decided from the newest version,
|
|
2379
|
+
* or skipped; see {@link VerbWrite}. A rebased post-image is the verdict's `body`,
|
|
2380
|
+
* so the writer commits it.
|
|
2381
|
+
* - **Capacity (main-10 G5-race).** An empty window with no rebase means
|
|
2382
|
+
* nothing intervened, so the decision stands as made and nothing is
|
|
2383
|
+
* recomputed. Otherwise the decision re-runs over the read's tail plus
|
|
2384
|
+
* the window, for the planned writes not yet committed (this one with
|
|
2385
|
+
* its rebased post-image), and a refusal throws before the committing
|
|
2386
|
+
* create, so concurrent growth writes that each passed this check cannot
|
|
2387
|
+
* together pass the ceiling.
|
|
2388
|
+
*
|
|
2389
|
+
* Each `committed(entry)` moves `fromSeq` past this batch's own commit, so
|
|
2390
|
+
* the writer reads only entries this decision has not seen.
|
|
2391
|
+
*
|
|
2392
|
+
* With no folded state (an unprovisioned collection), the collection is empty,
|
|
2393
|
+
* so the pre-commit check is skipped; a re-check starts from an empty
|
|
2394
|
+
* collection.
|
|
2395
|
+
*
|
|
2396
|
+
* @param read The pre-commit read: its folded state, and `tail`, the
|
|
2397
|
+
* first empty log slot it folded through.
|
|
2398
|
+
*/
|
|
2399
|
+
const admitWrites = async (ctx, read, verbWrites) => {
|
|
2400
|
+
const { folded } = read;
|
|
2401
|
+
const writes = verbWrites.map((w) => w.planned);
|
|
2402
|
+
let forceMaintenance = false;
|
|
2403
|
+
let warning;
|
|
2404
|
+
if (folded !== void 0) {
|
|
2405
|
+
const decision = capacityDecision({
|
|
2406
|
+
collection: ctx.collectionName,
|
|
2407
|
+
head: folded.head,
|
|
2408
|
+
base: folded.base,
|
|
2409
|
+
tail: folded.tail,
|
|
2410
|
+
writes,
|
|
2411
|
+
ceilings: currentFoldCeilings()
|
|
2412
|
+
});
|
|
2413
|
+
if (decision.refusal !== void 0) return await throwRefusal(ctx, decision, read.tail);
|
|
2414
|
+
forceMaintenance = decision.pressure;
|
|
2415
|
+
warning = decision.warning;
|
|
2416
|
+
}
|
|
2417
|
+
const head = folded?.head ?? EMPTY_HEAD;
|
|
2418
|
+
const base = folded?.base ?? /* @__PURE__ */ new Map();
|
|
2419
|
+
const seen = [...folded?.tail ?? []];
|
|
2420
|
+
const sinceRead = [];
|
|
2421
|
+
let fromSeq = read.tail;
|
|
2422
|
+
let pending = 0;
|
|
2423
|
+
let lastWindow = [];
|
|
2424
|
+
let pressure = forceMaintenance;
|
|
2425
|
+
let lastCommitted;
|
|
2426
|
+
let lastSkipped = false;
|
|
2427
|
+
const check = async (window, tail) => {
|
|
2428
|
+
lastWindow = window;
|
|
2429
|
+
const { planned, rebase, stillMatches } = verbWrites[pending];
|
|
2430
|
+
let rebased;
|
|
2431
|
+
if (planned.op !== "I") {
|
|
2432
|
+
const newest = newestVersion([...sinceRead, ...window], ctx.collectionName, planned.docId);
|
|
2433
|
+
if (newest === "gone") throw new RowSkipped(planned.docId);
|
|
2434
|
+
if (newest !== void 0 && stillMatches !== void 0 && !stillMatches(newest)) throw new RowSkipped(planned.docId);
|
|
2435
|
+
if (newest !== void 0 && rebase !== void 0) {
|
|
2436
|
+
rebased = await rebase(newest);
|
|
2437
|
+
if (rebased === void 0) throw new RowSkipped(planned.docId);
|
|
2438
|
+
}
|
|
2439
|
+
}
|
|
2440
|
+
if (window.length === 0 && rebased === void 0) return;
|
|
2441
|
+
const tailNow = [
|
|
2442
|
+
...seen,
|
|
2443
|
+
...sinceRead,
|
|
2444
|
+
...window
|
|
2445
|
+
];
|
|
2446
|
+
const remaining = writes.slice(pending);
|
|
2447
|
+
if (rebased !== void 0) remaining[0] = {
|
|
2448
|
+
...planned,
|
|
2449
|
+
after: rebased
|
|
2450
|
+
};
|
|
2451
|
+
const decision = capacityDecision({
|
|
2452
|
+
collection: ctx.collectionName,
|
|
2453
|
+
head,
|
|
2454
|
+
base,
|
|
2455
|
+
tail: tailNow,
|
|
2456
|
+
writes: remaining.map((write) => withLiveBefore(write, ctx.collectionName, tailNow)),
|
|
2457
|
+
ceilings: currentFoldCeilings()
|
|
2458
|
+
});
|
|
2459
|
+
if (decision.refusal !== void 0) return await throwRefusal(ctx, decision, tail);
|
|
2460
|
+
warning = decision.warning;
|
|
2461
|
+
pressure = decision.pressure;
|
|
2462
|
+
return {
|
|
2463
|
+
forceMaintenance: decision.pressure && pending === writes.length - 1,
|
|
2464
|
+
...rebased !== void 0 && { body: rebased }
|
|
2465
|
+
};
|
|
2466
|
+
};
|
|
2467
|
+
return {
|
|
2468
|
+
forceMaintenance,
|
|
2469
|
+
next: () => {
|
|
2470
|
+
lastWindow = [];
|
|
2471
|
+
return {
|
|
2472
|
+
fromSeq,
|
|
2473
|
+
check
|
|
2474
|
+
};
|
|
2475
|
+
},
|
|
2476
|
+
committed: (entry) => {
|
|
2477
|
+
sinceRead.push(...lastWindow, entry);
|
|
2478
|
+
fromSeq = entry.seq + 1;
|
|
2479
|
+
pending++;
|
|
2480
|
+
lastCommitted = entry;
|
|
2481
|
+
lastSkipped = false;
|
|
2482
|
+
},
|
|
2483
|
+
skipped: () => {
|
|
2484
|
+
pending++;
|
|
2485
|
+
lastSkipped = true;
|
|
2486
|
+
},
|
|
2487
|
+
settle: async () => {
|
|
2488
|
+
if (!lastSkipped || lastCommitted === void 0 || !pressure || getCurrentContext()?.maintenance?.disabled === true) return;
|
|
2489
|
+
await dispatchWriteTick({
|
|
2490
|
+
storage: ctx.storage,
|
|
2491
|
+
currentJsonKey: `${ctx.collectionPrefix}/current.json`,
|
|
2492
|
+
collection: ctx.collectionName,
|
|
2493
|
+
prevSeq: lastCommitted.seq,
|
|
2494
|
+
observedTail: lastCommitted.seq + 1,
|
|
2495
|
+
forceFold: true
|
|
2496
|
+
});
|
|
2497
|
+
},
|
|
2498
|
+
warn: () => {
|
|
2499
|
+
if (warning !== void 0 && writes.length > 0) noteCapacityWarning(warning);
|
|
2500
|
+
}
|
|
2501
|
+
};
|
|
2502
|
+
};
|
|
2503
|
+
/**
|
|
2504
|
+
* `write` with `before` re-read from the latest entry for its row in
|
|
2505
|
+
* `tail`, when there is one: an intervening commit may have changed the
|
|
2506
|
+
* row, so growth (G3) is judged against the row as it now stands. A row an
|
|
2507
|
+
* intervening `D` removed has no `before`, which counts as growth (fails
|
|
2508
|
+
* closed).
|
|
2509
|
+
*/
|
|
2510
|
+
const withLiveBefore = (write, collection, tail) => {
|
|
2511
|
+
if (write.op !== "U") return write;
|
|
2512
|
+
for (let i = tail.length - 1; i >= 0; i--) {
|
|
2513
|
+
const entry = tail[i];
|
|
2514
|
+
if (isOwnCollection(entry.collection, collection) && entry.doc_id === write.docId) {
|
|
2515
|
+
const { before: _stale, ...rest } = write;
|
|
2516
|
+
return entry.op === "D" || entry.after === void 0 ? rest : {
|
|
2517
|
+
...rest,
|
|
2518
|
+
before: entry.after
|
|
2519
|
+
};
|
|
2520
|
+
}
|
|
2521
|
+
}
|
|
2522
|
+
return write;
|
|
2523
|
+
};
|
|
2524
|
+
/**
|
|
2525
|
+
* `Collection.insert` implementation. Mints a UUIDv7 `_id`
|
|
2526
|
+
* when the caller omits it (or supplies an empty string); honours a
|
|
2527
|
+
* caller-supplied non-empty `_id`. The first `I` for an `_id` wins:
|
|
2528
|
+
* when a live row already holds the `_id`, the insert throws
|
|
2529
|
+
* non-retriable `BaerlyError{code:"AlreadyExists"}` and commits nothing.
|
|
2530
|
+
* A row committed before the pre-commit check read is caught there,
|
|
2531
|
+
* without a writer round-trip; one committed concurrently, after that
|
|
2532
|
+
* read, is caught by the writer's insert guard, which reads the log
|
|
2533
|
+
* window the check could not see. So of concurrent inserts of one `_id`,
|
|
2534
|
+
* at most one commits (exactly one, absent storage failures) and the
|
|
2535
|
+
* others throw `AlreadyExists` — matches the
|
|
2536
|
+
* locked `Collection.insert` contract
|
|
2537
|
+
* (`packages/protocol/src/collection-api.ts`).
|
|
2538
|
+
*
|
|
2539
|
+
* The emitted `LogEntry` has `op:"I"` and `after === {...doc, _id}`
|
|
2540
|
+
* (today's per-doc-replace model).
|
|
2541
|
+
*
|
|
2542
|
+
* **SDK-minted replay.** `opts.mintedId` marks `_id` as minted by an SDK
|
|
2543
|
+
* client rather than chosen by the caller; only the HTTP insert route
|
|
2544
|
+
* sets it (from the body's `mintedId`), and `Collection.insert` never
|
|
2545
|
+
* does. With it set, a live row for `_id` equal to `{...doc, _id}`
|
|
2546
|
+
* (`insertReplaysRow`: key order ignored) is this insert's own earlier
|
|
2547
|
+
* success, resent after a lost response: the call returns `{ _id }` and
|
|
2548
|
+
* commits nothing, whether the check read or the writer's insert guard
|
|
2549
|
+
* finds the row. A live row with any other body still throws
|
|
2550
|
+
* `AlreadyExists`. "Live" covers a `U`: a body equal to a later update's
|
|
2551
|
+
* post-image also replays. A caller-chosen `_id` never replays, even onto
|
|
2552
|
+
* an identical row, so a run-once guard like
|
|
2553
|
+
* `insert({ _id: "migration-x", done: true })` has at most one winner.
|
|
2554
|
+
*
|
|
2555
|
+
* @throws BaerlyError code="AlreadyExists" — a live row holds `_id`,
|
|
2556
|
+
* committed before or concurrently with this call (and, with
|
|
2557
|
+
* `mintedId`, its body differs). `err._id` is the `_id`. Not retriable.
|
|
2558
|
+
* @throws BaerlyError code="InvalidConfig" — `doc` holds a value JSON
|
|
2559
|
+
* cannot store as written (see `assertDocumentValues`), the post-image
|
|
2560
|
+
* `{ ...doc, _id }` encodes to more than `MAX_DOCUMENT_BYTES` (see
|
|
2561
|
+
* `assertDocumentSize`), the supplied
|
|
2562
|
+
* `_id` is present and not a string (`null` included), the resolved `_id` fails
|
|
2563
|
+
* {@link assertDocId} (key-segment rule, an unpaired surrogate, or not NFC), or `opts.mintedId`
|
|
2564
|
+
* is set and is not the resolved `_id`. Checked before I/O.
|
|
2565
|
+
* @throws BaerlyError code="WriteConflict" — a rejected storage precondition
|
|
2566
|
+
* `Writer.commit()` does not resolve, or log retention retired part of the
|
|
2567
|
+
* window the insert guard had to read; nothing was committed. Retriable.
|
|
2568
|
+
* @throws BaerlyError code="AmbiguousCommit" — a committing create may be
|
|
2569
|
+
* durable, but its outcome could not be resolved. The row may or may not
|
|
2570
|
+
* have been inserted. Not retriable-by-default; see `Writer.commit`.
|
|
2571
|
+
* @throws BaerlyError code="SchemaError" — `doc` nests deeper than
|
|
2572
|
+
* `MAX_DOCUMENT_DEPTH` (see `assertDocumentValues`), checked before I/O;
|
|
2573
|
+
* or from the per-collection `SchemaValidator` threaded via
|
|
2574
|
+
* `collectionReadContext`.
|
|
2575
|
+
*
|
|
2576
|
+
* @internal — exported for `Collection.insert` in `./collection.ts` to delegate
|
|
2577
|
+
* without duplicating the auto-id / collision-check /
|
|
2578
|
+
* commit pipeline.
|
|
2579
|
+
*/
|
|
2580
|
+
const runInsert = async (ctx, doc, opts) => {
|
|
2581
|
+
const supplied = doc["_id"];
|
|
2582
|
+
callerFacingCheck(() => {
|
|
2583
|
+
assertInsertIdType(supplied);
|
|
2584
|
+
assertDocumentValues(doc, "insert");
|
|
2585
|
+
});
|
|
2586
|
+
const _id = typeof supplied === "string" && supplied.length > 0 ? supplied : uuidv7();
|
|
2587
|
+
callerFacingCheck(() => assertDocId(_id));
|
|
2588
|
+
const mintedId = opts?.mintedId;
|
|
2589
|
+
if (mintedId !== void 0 && mintedId !== _id) throw new BaerlyError("InvalidConfig", `insert: mintedId ${JSON.stringify(mintedId)} is not the document _id ${JSON.stringify(_id)}`);
|
|
2590
|
+
const body = {
|
|
2591
|
+
...doc,
|
|
2592
|
+
_id
|
|
2593
|
+
};
|
|
2594
|
+
callerFacingCheck(() => assertDocumentSize(body, "insert"));
|
|
2595
|
+
if (ctx.schema !== void 0) await validateOrThrow(ctx.schema, body, {
|
|
2596
|
+
collection: ctx.collectionName,
|
|
2597
|
+
verb: "insert"
|
|
2598
|
+
});
|
|
2599
|
+
const existing = await runReadRows(ctx, {
|
|
2600
|
+
wire: { clauses: [{
|
|
2601
|
+
op: "eq",
|
|
2602
|
+
field: "_id",
|
|
2603
|
+
value: _id
|
|
2604
|
+
}] },
|
|
2605
|
+
order: void 0,
|
|
2606
|
+
limit: 1
|
|
2607
|
+
});
|
|
2608
|
+
const live = existing.rows[0];
|
|
2609
|
+
if (live !== void 0) {
|
|
2610
|
+
if (mintedId !== void 0 && insertReplaysRow(body, live.doc)) {
|
|
2611
|
+
recordInsertReplay(ctx.collectionName);
|
|
2612
|
+
return { _id };
|
|
2613
|
+
}
|
|
2614
|
+
throw insertAlreadyExists(ctx.collectionName, _id);
|
|
2615
|
+
}
|
|
2616
|
+
const admission = await admitWrites(ctx, existing, [{ planned: {
|
|
2617
|
+
op: "I",
|
|
2618
|
+
docId: _id,
|
|
2619
|
+
after: body
|
|
2620
|
+
} }]);
|
|
2621
|
+
await writerFor(ctx).commit({
|
|
2622
|
+
op: "I",
|
|
2623
|
+
collection: ctx.collectionName,
|
|
2624
|
+
docId: _id,
|
|
2625
|
+
body,
|
|
2626
|
+
insertGuard: {
|
|
2627
|
+
absentBelowSeq: existing.tail,
|
|
2628
|
+
replayIdentical: mintedId !== void 0
|
|
2629
|
+
},
|
|
2630
|
+
admission: admission.next(),
|
|
2631
|
+
...admission.forceMaintenance && { forceMaintenance: true }
|
|
2632
|
+
});
|
|
2633
|
+
admission.warn();
|
|
2634
|
+
return { _id };
|
|
2635
|
+
};
|
|
2636
|
+
/**
|
|
2637
|
+
* The `doc_id` that `update` / `delete` commit a materialised row under,
|
|
2638
|
+
* after checking that the row's own `_id` is that same string. Every
|
|
2639
|
+
* stored `I` / `U` post-image names its storage key; a row whose `_id` is
|
|
2640
|
+
* missing, not a string, or a different id is stored corruption (an older
|
|
2641
|
+
* release let a patch strip or re-key `_id`). Committing it anyway would
|
|
2642
|
+
* duplicate the row under its `_id`, or tombstone a key that does not
|
|
2643
|
+
* hold it, so it fails loud instead. `replace(id, doc)` repairs such a
|
|
2644
|
+
* row: it forces `_id` to `id`.
|
|
2645
|
+
*
|
|
2646
|
+
* @throws BaerlyError code="InvalidResponse" — the row's `_id` is not the
|
|
2647
|
+
* string it is stored under.
|
|
2648
|
+
*/
|
|
2649
|
+
const storedRowId = (row, verb) => {
|
|
2650
|
+
const id = row.doc["_id"];
|
|
2651
|
+
if (id !== row.docId) throw new BaerlyError("InvalidResponse", `Query.${verb}: stored row ${JSON.stringify(row.docId)} carries _id ${typeof id === "string" ? JSON.stringify(id) : `of type ${typeof id}`}; repair it with replace(id, doc)`);
|
|
2652
|
+
return row.docId;
|
|
2653
|
+
};
|
|
2654
|
+
/**
|
|
2655
|
+
* Reject a merge patch that would change a row's `_id`. A patch whose
|
|
2656
|
+
* top-level `_id` is present (not `undefined`, which `merge` treats as
|
|
2657
|
+
* absent) must equal the row's id: an equal `_id` keeps a full-document
|
|
2658
|
+
* round-trip patch working, while any other value — including `null`,
|
|
2659
|
+
* which would strip `_id` — is a caller bug. Unlike `replace`, which takes
|
|
2660
|
+
* the id as a separate argument and forces it onto the document, a patch
|
|
2661
|
+
* has no separate id to fall back on, so forcing it would hide the bug.
|
|
2662
|
+
*
|
|
2663
|
+
* @throws BaerlyError code="InvalidConfig" — the patch names a different `_id`.
|
|
2664
|
+
*/
|
|
2665
|
+
const assertPatchKeepsId = (patch, docId) => {
|
|
2666
|
+
if (patch === null || typeof patch !== "object" || Array.isArray(patch)) return;
|
|
2667
|
+
if (!Object.hasOwn(patch, "_id")) return;
|
|
2668
|
+
const patchId = patch["_id"];
|
|
2669
|
+
if (patchId !== void 0 && patchId !== docId) throw markCallerFacing(new BaerlyError("InvalidConfig", `Query.update: a patch cannot change _id (row ${JSON.stringify(docId)}); omit _id from the patch`, { resolution: PATCH_ID_RESOLUTION }));
|
|
2670
|
+
};
|
|
2671
|
+
/**
|
|
2672
|
+
* `applyMergePatch(row, patch)` as `update` commits it, validated against the
|
|
2673
|
+
* collection's schema.
|
|
2674
|
+
*
|
|
2675
|
+
* @throws BaerlyError code="InvalidConfig" — the post-image holds a value
|
|
2676
|
+
* JSON cannot store as written (see `assertDocumentValues`), or encodes
|
|
2677
|
+
* to more than `MAX_DOCUMENT_BYTES` (see `assertDocumentSize`).
|
|
2678
|
+
* @throws BaerlyError code="SchemaError" — the merge produced `undefined`,
|
|
2679
|
+
* the post-image nests deeper than `MAX_DOCUMENT_DEPTH`, or the schema
|
|
2680
|
+
* rejected the post-image.
|
|
2681
|
+
*/
|
|
2682
|
+
const mergeAndValidate = async (ctx, row, patch) => {
|
|
2683
|
+
const merged = applyMergePatch(row, patch);
|
|
2684
|
+
if (merged === void 0) throw new BaerlyError("SchemaError", `Query.update: merge produced undefined for doc ${JSON.stringify(row["_id"])}`);
|
|
2685
|
+
callerFacingCheck(() => assertDocumentValues(merged, "update", { undefinedMembersAbsent: true }));
|
|
2686
|
+
callerFacingCheck(() => assertDocumentSize(merged, "update"));
|
|
2687
|
+
if (ctx.schema !== void 0) await validateOrThrow(ctx.schema, merged, {
|
|
2688
|
+
collection: ctx.collectionName,
|
|
2689
|
+
verb: "update"
|
|
2690
|
+
});
|
|
2691
|
+
return merged;
|
|
2692
|
+
};
|
|
2693
|
+
/**
|
|
2694
|
+
* `Query.update` implementation. Materialises the predicate/order/
|
|
2695
|
+
* limit-filtered match set, applies RFC 7396 `applyMergePatch(prev, patch)`
|
|
2696
|
+
* per row, and emits one `op:"U"` `LogEntry` per affected `doc_id`
|
|
2697
|
+
* — one `Writer.commit()` round-trip apiece.
|
|
2698
|
+
*
|
|
2699
|
+
* Atomicity is per row, not across the N-row batch: each affected row
|
|
2700
|
+
* commits independently — the document is the atomic unit; there is no
|
|
2701
|
+
* multi-row batch.
|
|
2702
|
+
*
|
|
2703
|
+
* **Concurrent writes to a matched row (EvalPlanQual).** When another
|
|
2704
|
+
* write to a matched row commits between this read and the row's own
|
|
2705
|
+
* commit, the patch is re-applied to that newest version and the
|
|
2706
|
+
* predicate re-evaluated on it (`limit` / `order` are not); a row that
|
|
2707
|
+
* was deleted there, or no longer matches, is skipped and not counted in
|
|
2708
|
+
* `modified`. See {@link VerbWrite}.
|
|
2709
|
+
*
|
|
2710
|
+
* `replica_identity` defaults to `PATCH_ONLY` for every collection
|
|
2711
|
+
* today — emitted `U` entries carry `{ after }` (the full post-image)
|
|
2712
|
+
* and neither `before` nor `key_old`. Consumers rebuilding pre-images
|
|
2713
|
+
* under `PATCH_ONLY` need to maintain a shadow table — see
|
|
2714
|
+
* `packages/protocol/src/log.ts:102–118`.
|
|
2715
|
+
*
|
|
2716
|
+
* @throws BaerlyError code="WriteConflict" — one row's commit hit a rejected
|
|
2717
|
+
* storage precondition `Writer.commit()` does not resolve. The
|
|
2718
|
+
* partial-progress `modified` count is NOT returned in that case.
|
|
2719
|
+
* @throws BaerlyError code="AmbiguousCommit" — one row's committing create
|
|
2720
|
+
* may be durable, but its outcome could not be resolved. Rows before it in
|
|
2721
|
+
* the batch are already applied and that row's own fate is unknown; the
|
|
2722
|
+
* partial-progress `modified` count is NOT returned. Re-read rows by `_id`
|
|
2723
|
+
* before deciding whether to resume; absence does not prove a create failed.
|
|
2724
|
+
* See `Writer.commit`.
|
|
2725
|
+
* @throws BaerlyError code="SchemaError" — `applyMergePatch(prev, patch)` produced
|
|
2726
|
+
* `undefined` (defensive — `MergePatch<T>` cannot be `null` at the
|
|
2727
|
+
* root in the type system), the patch (checked before I/O) or a merged
|
|
2728
|
+
* post-image nests deeper than `MAX_DOCUMENT_DEPTH`, or the schema
|
|
2729
|
+
* rejected a post-image; at a
|
|
2730
|
+
* row's commit (re-applied to a newer version) rows before it are
|
|
2731
|
+
* already applied.
|
|
2732
|
+
* @throws BaerlyError code="InvalidConfig" — the patch (checked before
|
|
2733
|
+
* I/O) or a merged post-image holds a value JSON cannot store as written
|
|
2734
|
+
* (see `assertDocumentValues`; an `undefined` member is absent), a merged
|
|
2735
|
+
* post-image encodes to more than `MAX_DOCUMENT_BYTES` (see
|
|
2736
|
+
* `assertDocumentSize`; a row stored larger may still shrink), or the
|
|
2737
|
+
* patch names an `_id` other than the row's (see {@link assertPatchKeepsId}), or the row's
|
|
2738
|
+
* `_id` holds an unpaired surrogate or is not NFC (see {@link assertDocId}). Checked for every matched
|
|
2739
|
+
* row, with schema validation, before any row commits.
|
|
2740
|
+
* @throws BaerlyError code="CapacityExceeded" — the batch would grow the
|
|
2741
|
+
* collection past the serving host's fold ceiling (see `./capacity.ts`);
|
|
2742
|
+
* decided before any row commits, and re-checked at each row's commit
|
|
2743
|
+
* when a concurrent write landed since (see {@link admitWrites}), in
|
|
2744
|
+
* which case rows before it are already applied. Also thrown when the
|
|
2745
|
+
* request's storage budget runs out (the request ledger, including the
|
|
2746
|
+
* writer's commit-resolution reserve): rows before the refused one are
|
|
2747
|
+
* applied, it and the rows after it are not, and nothing is ambiguous.
|
|
2748
|
+
* The partial-progress `modified` count is NOT returned.
|
|
2749
|
+
* @throws BaerlyError code="InvalidResponse" — a matched stored row's
|
|
2750
|
+
* `_id` is not the string it is stored under.
|
|
2751
|
+
*/
|
|
2752
|
+
const runUpdate = async (ctx, state, patch) => {
|
|
2753
|
+
callerFacingCheck(() => assertDocumentValues(patch, "update", { undefinedMembersAbsent: true }));
|
|
2754
|
+
const read = await runReadRows(ctx, state);
|
|
2755
|
+
const { rows } = read;
|
|
2756
|
+
const planned = [];
|
|
2757
|
+
for (const row of rows) {
|
|
2758
|
+
const doc = row.doc;
|
|
2759
|
+
const docId = storedRowId(row, "update");
|
|
2760
|
+
assertPatchKeepsId(patch, docId);
|
|
2761
|
+
assertDocId(docId);
|
|
2762
|
+
const merged = await mergeAndValidate(ctx, doc, patch);
|
|
2763
|
+
planned.push({
|
|
2764
|
+
docId,
|
|
2765
|
+
before: doc,
|
|
2766
|
+
merged
|
|
2767
|
+
});
|
|
2768
|
+
}
|
|
2769
|
+
const stillMatches = state.wire === void 0 ? void 0 : compileWire(state.wire);
|
|
2770
|
+
const rebase = async (latest) => {
|
|
2771
|
+
if (stillMatches !== void 0 && !stillMatches(latest)) return;
|
|
2772
|
+
return await mergeAndValidate(ctx, latest, patch);
|
|
2773
|
+
};
|
|
2774
|
+
const admission = await admitWrites(ctx, read, planned.map((p) => ({
|
|
2775
|
+
planned: {
|
|
2776
|
+
op: "U",
|
|
2777
|
+
docId: p.docId,
|
|
2778
|
+
after: p.merged,
|
|
2779
|
+
before: p.before
|
|
2780
|
+
},
|
|
2781
|
+
rebase
|
|
2782
|
+
})));
|
|
2783
|
+
let modified = 0;
|
|
2784
|
+
for (const [i, { docId, merged }] of planned.entries()) {
|
|
2785
|
+
let entry;
|
|
2786
|
+
try {
|
|
2787
|
+
({entry} = await writerFor(ctx).commit({
|
|
2788
|
+
op: "U",
|
|
2789
|
+
collection: ctx.collectionName,
|
|
2790
|
+
docId,
|
|
2791
|
+
body: merged,
|
|
2792
|
+
admission: admission.next(),
|
|
2793
|
+
...admission.forceMaintenance && i === planned.length - 1 && { forceMaintenance: true }
|
|
2794
|
+
}));
|
|
2795
|
+
} catch (error) {
|
|
2796
|
+
if (error instanceof RowSkipped) {
|
|
2797
|
+
admission.skipped();
|
|
2798
|
+
continue;
|
|
2799
|
+
}
|
|
2800
|
+
throw error;
|
|
2801
|
+
}
|
|
2802
|
+
admission.committed(entry);
|
|
2803
|
+
modified++;
|
|
2804
|
+
}
|
|
2805
|
+
await admission.settle();
|
|
2806
|
+
admission.warn();
|
|
2807
|
+
return { modified };
|
|
2808
|
+
};
|
|
2809
|
+
/**
|
|
2810
|
+
* `Collection.replace` implementation. Existence check via `runRead` over
|
|
2811
|
+
* a `byId`-shaped wire so the `singleIdFromPredicate` PK fast path
|
|
2812
|
+
* (`Map.get`) fires. Missing row → `NotFound` directly (no conflict-string
|
|
2813
|
+
* indirection through the router). Present row → emit a single
|
|
2814
|
+
* `op:"U"` `LogEntry` carrying `doc` as the post-image, with `_id`
|
|
2815
|
+
* forced to the requested `id` so doc identity is preserved across
|
|
2816
|
+
* replaces even if the supplied `doc._id` differs.
|
|
2817
|
+
*
|
|
2818
|
+
* A replace racing another write to the row stays last-writer-wins: an
|
|
2819
|
+
* update committed after this read is overwritten. A delete committed
|
|
2820
|
+
* there is not undone: the replace commits nothing and throws `NotFound`
|
|
2821
|
+
* (see {@link VerbWrite}).
|
|
2822
|
+
*
|
|
2823
|
+
* @throws BaerlyError code="NotFound" — no row exists at `id`, including
|
|
2824
|
+
* one a concurrent delete removed after this call's read.
|
|
2825
|
+
* @throws BaerlyError code="InvalidConfig" — `id` fails
|
|
2826
|
+
* {@link assertDocId} (key-segment rule, an unpaired surrogate, or not NFC), or `doc` holds a
|
|
2827
|
+
* value JSON cannot store as written (see `assertDocumentValues`), or
|
|
2828
|
+
* `{ ...doc, _id: id }` encodes to more than `MAX_DOCUMENT_BYTES` (see
|
|
2829
|
+
* `assertDocumentSize`). Checked before I/O.
|
|
2830
|
+
* @throws BaerlyError code="SchemaError" — `doc` nests deeper than
|
|
2831
|
+
* `MAX_DOCUMENT_DEPTH` (checked before I/O), or the post-image is
|
|
2832
|
+
* rejected by the collection's bound validator.
|
|
2833
|
+
* @throws BaerlyError code="WriteConflict" — a rejected storage precondition
|
|
2834
|
+
* `Writer.commit()` does not resolve; nothing was committed.
|
|
2835
|
+
* @throws BaerlyError code="AmbiguousCommit" — a committing create may be
|
|
2836
|
+
* durable, but its outcome could not be resolved, so the replace may or may
|
|
2837
|
+
* not have been applied. Re-read the row by `id` before deciding whether to
|
|
2838
|
+
* retry; absence does not prove the create failed. See `Writer.commit`.
|
|
2839
|
+
*/
|
|
2840
|
+
const runReplaceById = async (ctx, id, doc) => {
|
|
2841
|
+
callerFacingCheck(() => assertDocId(id));
|
|
2842
|
+
callerFacingCheck(() => assertDocumentValues(doc, "replace"));
|
|
2843
|
+
const body = {
|
|
2844
|
+
...doc,
|
|
2845
|
+
_id: id
|
|
2846
|
+
};
|
|
2847
|
+
callerFacingCheck(() => assertDocumentSize(body, "replace"));
|
|
2848
|
+
const read = await runReadRows(ctx, {
|
|
2849
|
+
wire: { clauses: [{
|
|
2850
|
+
op: "eq",
|
|
2851
|
+
field: "_id",
|
|
2852
|
+
value: id
|
|
2853
|
+
}] },
|
|
2854
|
+
order: void 0,
|
|
2855
|
+
limit: void 0
|
|
2856
|
+
});
|
|
2857
|
+
const current = read.rows[0];
|
|
2858
|
+
if (current === void 0) throw new BaerlyError("NotFound", `No such row: ${id}`);
|
|
2859
|
+
if (ctx.schema !== void 0) await validateOrThrow(ctx.schema, body, {
|
|
2860
|
+
collection: ctx.collectionName,
|
|
2861
|
+
verb: "replace"
|
|
2862
|
+
});
|
|
2863
|
+
const admission = await admitWrites(ctx, read, [{ planned: {
|
|
2864
|
+
op: "U",
|
|
2865
|
+
docId: id,
|
|
2866
|
+
after: body,
|
|
2867
|
+
before: current.doc
|
|
2868
|
+
} }]);
|
|
2869
|
+
try {
|
|
2870
|
+
await writerFor(ctx).commit({
|
|
2871
|
+
op: "U",
|
|
2872
|
+
collection: ctx.collectionName,
|
|
2873
|
+
docId: id,
|
|
2874
|
+
body,
|
|
2875
|
+
admission: admission.next(),
|
|
2876
|
+
...admission.forceMaintenance && { forceMaintenance: true }
|
|
2877
|
+
});
|
|
2878
|
+
} catch (error) {
|
|
2879
|
+
if (error instanceof RowSkipped) throw new BaerlyError("NotFound", `No such row: ${id}`);
|
|
2880
|
+
throw error;
|
|
2881
|
+
}
|
|
2882
|
+
admission.warn();
|
|
2883
|
+
};
|
|
2884
|
+
/**
|
|
2885
|
+
* `Query.delete` implementation. Tombstones every matched row with a
|
|
2886
|
+
* single `op:"D"` `LogEntry` per `doc_id`. `replica_identity` defaults
|
|
2887
|
+
* to `PATCH_ONLY`, so emitted `D` entries carry no body fields
|
|
2888
|
+
* (no `after`, no `before`/`key_old`).
|
|
2889
|
+
* Consumers rebuilding pre-images under `PATCH_ONLY` need to
|
|
2890
|
+
* maintain a shadow table — see `packages/protocol/src/log.ts:102–118`.
|
|
2891
|
+
*
|
|
2892
|
+
* Atomicity is per row, not across the N-row batch — same shape as
|
|
2893
|
+
* `Query.update`. The document is the atomic unit; there is no
|
|
2894
|
+
* multi-row batch.
|
|
2895
|
+
*
|
|
2896
|
+
* **Concurrent writes to a matched row (EvalPlanQual).** As in
|
|
2897
|
+
* `runUpdate`: when another write to a matched row commits between this
|
|
2898
|
+
* read and the row's own commit, the predicate is re-evaluated on that
|
|
2899
|
+
* newest version. A row deleted there (including by a racing delete, or
|
|
2900
|
+
* deleted and re-inserted), or no longer matching, is skipped and not
|
|
2901
|
+
* counted in `deleted`. See {@link VerbWrite}.
|
|
2902
|
+
*
|
|
2903
|
+
* @throws BaerlyError code="WriteConflict" — one row's commit hit a rejected
|
|
2904
|
+
* storage precondition `Writer.commit()` does not resolve. The
|
|
2905
|
+
* partial-progress `deleted` count is NOT returned
|
|
2906
|
+
* in that case.
|
|
2907
|
+
* @throws BaerlyError code="AmbiguousCommit" — one row's committing create
|
|
2908
|
+
* may be durable, but its outcome could not be resolved. Rows before it in
|
|
2909
|
+
* the batch are already tombstoned and that row's own fate is unknown; the
|
|
2910
|
+
* partial-progress `deleted` count is NOT returned. Re-read rows by `_id`
|
|
2911
|
+
* before deciding whether to resume. See `Writer.commit`.
|
|
2912
|
+
* @throws BaerlyError code="CapacityExceeded" — as in `runUpdate`: the
|
|
2913
|
+
* batch would grow past the fold ceiling (a delete can when a pending
|
|
2914
|
+
* fold cannot make progress), or the request's storage budget ran out
|
|
2915
|
+
* part-way. Rows before the refused one are tombstoned, it and the rows
|
|
2916
|
+
* after it are not; the partial-progress `deleted` count is NOT returned.
|
|
2917
|
+
* @throws BaerlyError code="InvalidResponse" — a matched stored row's
|
|
2918
|
+
* `_id` is not the string it is stored under.
|
|
2919
|
+
*/
|
|
2920
|
+
const runDelete = async (ctx, state) => {
|
|
2921
|
+
const read = await runReadRows(ctx, state);
|
|
2922
|
+
const docIds = read.rows.map((row) => storedRowId(row, "delete"));
|
|
2923
|
+
const stillMatches = state.wire === void 0 ? void 0 : compileWire(state.wire);
|
|
2924
|
+
const admission = await admitWrites(ctx, read, docIds.map((docId) => ({
|
|
2925
|
+
planned: {
|
|
2926
|
+
op: "D",
|
|
2927
|
+
docId
|
|
2928
|
+
},
|
|
2929
|
+
stillMatches
|
|
2930
|
+
})));
|
|
2931
|
+
let deleted = 0;
|
|
2932
|
+
for (const [i, docId] of docIds.entries()) {
|
|
2933
|
+
let entry;
|
|
2934
|
+
try {
|
|
2935
|
+
({entry} = await writerFor(ctx).commit({
|
|
2936
|
+
op: "D",
|
|
2937
|
+
collection: ctx.collectionName,
|
|
2938
|
+
docId,
|
|
2939
|
+
admission: admission.next(),
|
|
2940
|
+
...admission.forceMaintenance && i === docIds.length - 1 && { forceMaintenance: true }
|
|
2941
|
+
}));
|
|
2942
|
+
} catch (error) {
|
|
2943
|
+
if (error instanceof RowSkipped) {
|
|
2944
|
+
admission.skipped();
|
|
2945
|
+
continue;
|
|
2946
|
+
}
|
|
2947
|
+
throw error;
|
|
2948
|
+
}
|
|
2949
|
+
admission.committed(entry);
|
|
2950
|
+
deleted++;
|
|
2951
|
+
}
|
|
2952
|
+
await admission.settle();
|
|
2953
|
+
admission.warn();
|
|
2954
|
+
return { deleted };
|
|
2955
|
+
};
|
|
2956
|
+
/**
|
|
2957
|
+
* Load `current.json` fresh, walk `[log_seq_start, tail_hint)` in parallel, fold
|
|
2958
|
+
* per-`doc_id`, then apply predicate / order / limit in memory.
|
|
2959
|
+
*
|
|
2960
|
+
* Error mapping:
|
|
2961
|
+
* - `current.json` missing → empty result (collection not provisioned).
|
|
2962
|
+
* - `current.json` malformed → `InvalidResponse` (from `readCurrentJson`).
|
|
2963
|
+
* - log entry missing in `[log_seq_start, tail_hint)` → `Internal`.
|
|
2964
|
+
* - log entry malformed → `InvalidResponse`.
|
|
2965
|
+
*/
|
|
2966
|
+
const runRead = async (ctx, state, opts) => {
|
|
2967
|
+
const budget = new ReadBudget(ctx.collectionName);
|
|
2968
|
+
const countOnly = opts?.countOnly === true;
|
|
2969
|
+
const { rows, count, manifestPointer, fresh } = await runReadRows(ctx, state, budget, countOnly);
|
|
2970
|
+
if (!countOnly) budget.admitOutput(rows.length);
|
|
2971
|
+
return {
|
|
2972
|
+
rows: rows.map((row) => row.doc),
|
|
2973
|
+
count,
|
|
2974
|
+
manifestPointer,
|
|
2975
|
+
fresh
|
|
2976
|
+
};
|
|
2977
|
+
};
|
|
2978
|
+
/**
|
|
2979
|
+
* {@link runRead}, keeping each row's storage key. Every call, a write
|
|
2980
|
+
* verb's pre-commit read included, records its work (see
|
|
2981
|
+
* {@link recordReadWork}).
|
|
2982
|
+
*/
|
|
2983
|
+
const runReadRows = async (ctx, state, budget = new ReadBudget(ctx.collectionName, {}), countOnly = false) => {
|
|
2984
|
+
const currentJsonKey = `${ctx.collectionPrefix}/current.json`;
|
|
2985
|
+
const head = await readCurrentJson(ctx.storage, currentJsonKey);
|
|
2986
|
+
const fresh = true;
|
|
2987
|
+
if (head === null) {
|
|
2988
|
+
recordReadWork(ctx.collectionName, 0, 0, 0);
|
|
2989
|
+
return {
|
|
2990
|
+
rows: [],
|
|
2991
|
+
count: 0,
|
|
2992
|
+
manifestPointer: "m1:0000000000000",
|
|
2993
|
+
fresh,
|
|
2994
|
+
tail: 0
|
|
2995
|
+
};
|
|
2996
|
+
}
|
|
2997
|
+
budget.admitHead(head.json);
|
|
2998
|
+
const hint = head.json.tail_hint;
|
|
2999
|
+
const logSeqStart = logSeqStartOf(head.json);
|
|
3000
|
+
const baseDocs = head.json.snapshot === null ? /* @__PURE__ */ new Map() : await loadSnapshotAsMap(ctx.storage, head.json.snapshot, ctx.collectionName);
|
|
3001
|
+
const probeFrom = Math.max(logSeqStart, hint);
|
|
3002
|
+
const entries = await walkLogRange(ctx.storage, ctx.collectionPrefix, logSeqStart, hint, { onBody: budget.chargeTailBody });
|
|
3003
|
+
const probe = await probeReadTail(ctx.storage, ctx.collectionPrefix, probeFrom, {
|
|
3004
|
+
pool: budget.requestPool,
|
|
3005
|
+
onBody: budget.chargeTailBody,
|
|
3006
|
+
refusal: budget.probeRefusal
|
|
3007
|
+
});
|
|
3008
|
+
const tail = probe.tail;
|
|
3009
|
+
const docs = new Map(baseDocs);
|
|
3010
|
+
foldLogEntriesOnto(docs, entries, { collection: ctx.collectionName });
|
|
3011
|
+
foldLogEntriesOnto(docs, probe.entries, { collection: ctx.collectionName });
|
|
3012
|
+
const fastId = singleIdFromPredicate(state.wire);
|
|
3013
|
+
let rows = [];
|
|
3014
|
+
let count;
|
|
3015
|
+
if (countOnly && fastId === void 0) count = limitedLength(countMatches(docs, state.wire), state.limit);
|
|
3016
|
+
else {
|
|
3017
|
+
if (fastId !== void 0) {
|
|
3018
|
+
const hit = docs.get(fastId);
|
|
3019
|
+
rows = hit === void 0 ? [] : [{
|
|
3020
|
+
docId: fastId,
|
|
3021
|
+
doc: hit
|
|
3022
|
+
}];
|
|
3023
|
+
} else rows = filterRows(docs, state.wire);
|
|
3024
|
+
if (state.order !== void 0) rows = orderRows(rows, state.order, state.limit);
|
|
3025
|
+
count = rows.length = limitedLength(rows.length, state.limit);
|
|
3026
|
+
}
|
|
3027
|
+
recordReadWork(ctx.collectionName, baseDocs.size + entries.length + probe.entries.length, docs.size, count);
|
|
3028
|
+
return {
|
|
3029
|
+
rows,
|
|
3030
|
+
count,
|
|
3031
|
+
manifestPointer: serializeManifestPointer(head.json, tail),
|
|
3032
|
+
fresh,
|
|
3033
|
+
tail,
|
|
3034
|
+
folded: {
|
|
3035
|
+
head: head.json,
|
|
3036
|
+
base: baseDocs,
|
|
3037
|
+
tail: [...entries, ...probe.entries]
|
|
3038
|
+
}
|
|
3039
|
+
};
|
|
3040
|
+
};
|
|
3041
|
+
/**
|
|
3042
|
+
* Emit one read's work onto the request's canonical line (the
|
|
3043
|
+
* `db.read.*` counters; units in `@baerly/protocol`'s `MetricsRecorder`
|
|
3044
|
+
* catalog). Takes counts the read already holds, so it adds no storage
|
|
3045
|
+
* call and no pass over the rows. Outside an observability scope it
|
|
3046
|
+
* returns before allocating anything; inside one it adds three
|
|
3047
|
+
* recorder rows per read.
|
|
3048
|
+
*
|
|
3049
|
+
* @param decoded Snapshot rows plus log entries decoded by the fold.
|
|
3050
|
+
* @param live Documents live after the fold, before predicate and limit.
|
|
3051
|
+
* @param returned Rows left after predicate, order and limit.
|
|
3052
|
+
*/
|
|
3053
|
+
const recordReadWork = (collection, decoded, live, returned) => {
|
|
3054
|
+
const recorder = getCurrentContext()?.recorder;
|
|
3055
|
+
if (recorder === void 0) return;
|
|
3056
|
+
const labels = { collection };
|
|
3057
|
+
recorder.counter("db.read.decoded_entries_total", decoded, labels);
|
|
3058
|
+
recorder.counter("db.read.live_documents_total", live, labels);
|
|
3059
|
+
recorder.counter("db.read.returned_rows_total", returned, labels);
|
|
3060
|
+
};
|
|
3061
|
+
// packages/server/src/db-read-seams.ts
|
|
3062
|
+
/**
|
|
3063
|
+
* Manifest and log read seams over a {@link Db}: the collection read
|
|
3064
|
+
* context the HTTP router drives, and the `current.json` / log reads the
|
|
3065
|
+
* `/v1/since` handler makes. Module functions rather than `Db` methods so
|
|
3066
|
+
* the manifest and probe types stay off the public `Db` class; reached
|
|
3067
|
+
* outside this package through `@baerly/server/_internal/kernel`.
|
|
3068
|
+
*
|
|
3069
|
+
* Kept apart from `./db.ts` so the HTTP entry imports these without
|
|
3070
|
+
* pulling in the `Db` class and the collection API.
|
|
3071
|
+
*/
|
|
3072
|
+
/**
|
|
3073
|
+
* Physical-key prefix for a `(app, tenant)` pair. Trailing slash is
|
|
3074
|
+
* part of the prefix so a caller's `list("")` resolves to
|
|
3075
|
+
* `list("app/<app>/tenant/<tenant>/")` and cannot enumerate a sibling
|
|
3076
|
+
* tenant whose name shares a prefix.
|
|
3077
|
+
*/
|
|
3078
|
+
const physicalPrefixFor = (app, tenant) => `app/${app}/tenant/${tenant}/`;
|
|
3079
|
+
/** Private-field accessor, registered by the `Db` static block. */
|
|
3080
|
+
let internalsOf;
|
|
3081
|
+
/** Called once, from the `Db` static block. */
|
|
3082
|
+
const registerDbInternals = (accessor) => {
|
|
3083
|
+
internalsOf = accessor;
|
|
3084
|
+
};
|
|
3085
|
+
/**
|
|
3086
|
+
* Build a freshly-seeded {@link CollectionReadContext} for `name`. The
|
|
3087
|
+
* HTTP router uses this so it can drive `runAllWithMeta` directly
|
|
3088
|
+
* (the return shape carries the manifest-pointer cursor used to
|
|
3089
|
+
* pack `_meta` onto the read response envelope). Application
|
|
3090
|
+
* callers should keep using
|
|
3091
|
+
* {@link Db.collection}; the chainable terminals destructure the cursor
|
|
3092
|
+
* out and discard it to keep the locked `Query<T>` signature.
|
|
3093
|
+
*
|
|
3094
|
+
* Runs the same `name`-validation guard as {@link Db.collection}.
|
|
3095
|
+
*
|
|
3096
|
+
* @throws BaerlyError code="InvalidConfig" when `name` is empty,
|
|
3097
|
+
* contains `/`, is `"."` or `".."`, contains control characters,
|
|
3098
|
+
* starts with the reserved `"_"` prefix, exceeds 256 bytes, or is
|
|
3099
|
+
* not in Unicode Normalization Form C.
|
|
3100
|
+
* @internal
|
|
3101
|
+
*/
|
|
3102
|
+
const collectionReadContext = (db, name) => {
|
|
3103
|
+
assertKeySegment(name, "collection", "Db.collection");
|
|
3104
|
+
const schema = internalsOf(db).schemas.get(name);
|
|
3105
|
+
return {
|
|
3106
|
+
storage: internalsOf(db).storage,
|
|
3107
|
+
collectionPrefix: `${physicalPrefixFor(db.app, db.tenant)}manifests/${name}`,
|
|
3108
|
+
collectionName: name,
|
|
3109
|
+
...schema !== void 0 ? { schema } : {}
|
|
3110
|
+
};
|
|
3111
|
+
};
|
|
3112
|
+
/**
|
|
3113
|
+
* Read + parse this `Db`'s `manifests/<collection>/current.json`. Returns
|
|
3114
|
+
* `null` when the collection has not been provisioned yet (no
|
|
3115
|
+
* `current.json` exists). Throws `BaerlyError{code:"InvalidResponse"}`
|
|
3116
|
+
* on a malformed body — same contract as the underlying
|
|
3117
|
+
* {@link readCurrentJson} helper in `@baerly/protocol`.
|
|
3118
|
+
*
|
|
3119
|
+
* Backs the `/v1/since` long-poll handler in
|
|
3120
|
+
* `packages/server/src/http/since.ts`; that handler needs the parsed
|
|
3121
|
+
* `CurrentJson` plus an ETag for the follow-up reads.
|
|
3122
|
+
*
|
|
3123
|
+
* @internal — typed seam for the HTTP handler; app code should use
|
|
3124
|
+
* the collection API.
|
|
3125
|
+
*/
|
|
3126
|
+
const getCurrentJson = async (db, collection, opts) => {
|
|
3127
|
+
assertNameSegment(collection, "collection");
|
|
3128
|
+
const key = `${physicalPrefixFor(db.app, db.tenant)}manifests/${collection}/current.json`;
|
|
3129
|
+
return readCurrentJson(internalsOf(db).storage, key, opts);
|
|
3130
|
+
};
|
|
3131
|
+
/**
|
|
3132
|
+
* Read + parse one `LogEntry` by `seq` from
|
|
3133
|
+
* `manifests/<collection>/log/<seq>.json`. Returns `null`
|
|
3134
|
+
* when the entry is missing — this typically means the GC sweeper
|
|
3135
|
+
* deleted the entry between a `readCurrentJson` and this GET (the
|
|
3136
|
+
* `/v1/since` handler treats the race as silent and skips the
|
|
3137
|
+
* entry). Throws `BaerlyError{code:"InvalidResponse"}` on a body
|
|
3138
|
+
* that isn't valid JSON.
|
|
3139
|
+
*
|
|
3140
|
+
* `current` is the manifest this read is floored against — pass the
|
|
3141
|
+
* same one the `seq` was derived from. It is a parameter rather than
|
|
3142
|
+
* caller-enforced discipline so a new caller cannot introduce a
|
|
3143
|
+
* sub-floor read: entries below `current.log_seq_start` are folded
|
|
3144
|
+
* into the snapshot and may already be reclaimed (invariant 5 in
|
|
3145
|
+
* `docs/spec/sync-protocol.md`).
|
|
3146
|
+
*
|
|
3147
|
+
* @throws BaerlyError code="Internal" — `seq` is below
|
|
3148
|
+
* `current.log_seq_start`, or below the certified prefix bound
|
|
3149
|
+
* `current.log_delete_floor` (a distinct message: the object is
|
|
3150
|
+
* gone, not merely reclaimable).
|
|
3151
|
+
*
|
|
3152
|
+
* @throws BaerlyError code="InvalidConfig" — the entry names a
|
|
3153
|
+
* canonically-equivalent but byte-different collection (a
|
|
3154
|
+
* legacy non-NFC spelling on R2); see `isOwnCollection`.
|
|
3155
|
+
*
|
|
3156
|
+
* @internal — typed seam for the HTTP handler; app code should use
|
|
3157
|
+
* the collection API.
|
|
3158
|
+
*/
|
|
3159
|
+
const getLogEntry = async (db, collection, seq, current, opts) => {
|
|
3160
|
+
assertNameSegment(collection, "collection");
|
|
3161
|
+
assertAtOrAboveLogFloor("getLogEntry", seq, current);
|
|
3162
|
+
const key = logObjectKey(`${physicalPrefixFor(db.app, db.tenant)}manifests/${collection}`, seq);
|
|
3163
|
+
const got = await internalsOf(db).storage.get(key, opts);
|
|
3164
|
+
if (got === null) return null;
|
|
3165
|
+
let parsed;
|
|
3166
|
+
try {
|
|
3167
|
+
parsed = decodeJsonBytes(got.body);
|
|
3168
|
+
} catch (error) {
|
|
3169
|
+
throw new BaerlyError("InvalidResponse", `log entry at ${key}: body is not valid JSON`, { cause: error });
|
|
3170
|
+
}
|
|
3171
|
+
const entry = parsed;
|
|
3172
|
+
isOwnCollection(entry.collection, collection);
|
|
3173
|
+
return entry;
|
|
3174
|
+
};
|
|
3175
|
+
/**
|
|
3176
|
+
* Forward-probe at most `cap` committed log entries from `hint` and
|
|
3177
|
+
* return them. Unlike {@link probeLogTail}, reaching `cap` is not an
|
|
3178
|
+
* error: the chunk comes back as `kind: "at-least"`, a prefix of the
|
|
3179
|
+
* entries past `hint`, so a caller with a bounded request budget can
|
|
3180
|
+
* deliver it and resume after its last entry. A slot GET the request
|
|
3181
|
+
* ledger refuses ends the chunk the same way, keeping the entries read
|
|
3182
|
+
* before it. Each slot is one GET; size `cap` with `forwardProbeCap`.
|
|
3183
|
+
*
|
|
3184
|
+
* @throws BaerlyError code="Internal" — `hint` is below the floor, as
|
|
3185
|
+
* for {@link probeLogTail}.
|
|
3186
|
+
* @throws BaerlyError code="InvalidResponse" — an occupied slot does
|
|
3187
|
+
* not hold valid JSON.
|
|
3188
|
+
* @throws BaerlyError code="InvalidConfig" — an entry names a
|
|
3189
|
+
* canonically-equivalent but byte-different collection, as for
|
|
3190
|
+
* {@link getLogEntry}.
|
|
3191
|
+
*
|
|
3192
|
+
* @internal — typed seam for the HTTP handler.
|
|
3193
|
+
*/
|
|
3194
|
+
const probeLogChunk = async (db, collection, hint, current, opts) => {
|
|
3195
|
+
assertNameSegment(collection, "collection");
|
|
3196
|
+
assertAtOrAboveLogFloor("probeLogChunk", hint, current);
|
|
3197
|
+
const logPrefix = `${physicalPrefixFor(db.app, db.tenant)}manifests/${collection}`;
|
|
3198
|
+
const chunk = await probeTailChunk(internalsOf(db).storage, logPrefix, hint, {
|
|
3199
|
+
...opts,
|
|
3200
|
+
stopOnRefusal: true
|
|
3201
|
+
});
|
|
3202
|
+
for (const entry of chunk.entries) isOwnCollection(entry.collection, collection);
|
|
3203
|
+
return chunk;
|
|
3204
|
+
};
|
|
3205
|
+
/**
|
|
3206
|
+
* Guard a log-read seq against both floors on the manifest it was
|
|
3207
|
+
* derived from.
|
|
3208
|
+
*
|
|
3209
|
+
* Entries below `log_seq_start` have been folded into the snapshot
|
|
3210
|
+
* (invariant 5 in `docs/spec/sync-protocol.md`) and may be reclaimed at
|
|
3211
|
+
* any time, so a sub-floor read is never a legitimate request — it is
|
|
3212
|
+
* either a stale seq the caller failed to screen, or a caller that
|
|
3213
|
+
* never screened at all. Both are protocol-invariant violations by
|
|
3214
|
+
* internal code, hence `Internal` rather than `InvalidConfig`: no
|
|
3215
|
+
* client input reaches these seams unscreened (`/v1/since` rejects a
|
|
3216
|
+
* sub-floor cursor with `CursorExpired` before ever getting here).
|
|
3217
|
+
*
|
|
3218
|
+
* Below `log_delete_floor` the contiguous prefix is certified deleted,
|
|
3219
|
+
* so the object is not merely *reclaimable* but already *reclaimed*.
|
|
3220
|
+
* The two floors get distinct messages. Same code, because both are the
|
|
3221
|
+
* same class of caller bug; different wording, because an operator
|
|
3222
|
+
* reading the throw has to know whether the bytes are recoverable.
|
|
3223
|
+
*
|
|
3224
|
+
* The floors arrive as the whole `CurrentJson` rather than as bare
|
|
3225
|
+
* numbers so neither can be invented independently of the manifest.
|
|
3226
|
+
*
|
|
3227
|
+
* Loud on purpose. PostgreSQL removed `old_snapshot_threshold` in PG17
|
|
3228
|
+
* because a fixed reclamation window that let a reader proceed
|
|
3229
|
+
* *silently* produced wrong answers; Oracle's `ORA-01555` is the same
|
|
3230
|
+
* trade and survives because it throws.
|
|
3231
|
+
*/
|
|
3232
|
+
const assertAtOrAboveLogFloor = (seam, seq, current) => {
|
|
3233
|
+
const floor = logSeqStartOf(current);
|
|
3234
|
+
const storedDeleteFloor = logDeleteFloorOf(current);
|
|
3235
|
+
const deleteFloor = certifiedDeleteFloor(current);
|
|
3236
|
+
if (deleteFloor > 0 && seq < deleteFloor) {
|
|
3237
|
+
const clamped = storedDeleteFloor === deleteFloor ? "" : ` (stored log_delete_floor=${storedDeleteFloor}, clamped to log_seq_start=${floor})`;
|
|
3238
|
+
throw new BaerlyError("Internal", `${seam}: seq ${seq} is below the certified delete floor ${deleteFloor}${clamped}; the log object is GONE — it has been reclaimed, not merely made reclaimable`);
|
|
3239
|
+
}
|
|
3240
|
+
if (seq < floor) throw new BaerlyError("Internal", `${seam}: seq ${seq} is below the fold floor log_seq_start=${floor}; entries beneath the floor are folded into the snapshot and may already be reclaimed`);
|
|
3241
|
+
};
|
|
3242
|
+
/**
|
|
3243
|
+
* Guard an app, tenant, or collection name used as a path-segment in the
|
|
3244
|
+
* bucket-key encoding. Routes through {@link assertNameSegment}: the
|
|
3245
|
+
* shared {@link assertPathSegment} rule (empty / `"/"` / `"."`|`".."` /
|
|
3246
|
+
* C0-C1 control / leading `"_"` (ADR-003) / overlong) plus Unicode
|
|
3247
|
+
* Normalization Form C, all as `BaerlyError{code:"InvalidConfig"}`.
|
|
3248
|
+
* `role` and `verb` are baked into the message so the caller doesn't
|
|
3249
|
+
* need to format their own.
|
|
3250
|
+
*
|
|
3251
|
+
* Used by {@link Db.create} (twice — `app`, `tenant`) and
|
|
3252
|
+
* {@link collectionReadContext} (once — `name`).
|
|
3253
|
+
*
|
|
3254
|
+
* @internal
|
|
3255
|
+
*/
|
|
3256
|
+
const assertKeySegment = (value, role, verb) => {
|
|
3257
|
+
assertNameSegment(value, role, verb);
|
|
3258
|
+
};
|
|
3259
|
+
export { probeLogChunk as a, runAllWithMeta as c, runReplaceById as d, CAPACITY_WARNING_FIELD as f, getLogEntry as i, runByIdWithMeta as l, validateWire as m, collectionReadContext as n, registerDbInternals as o, assertReadDocId as p, getCurrentJson as r, makeQuery as s, assertKeySegment as t, runInsert as u };
|
|
3260
|
+
|
|
3261
|
+
//# sourceMappingURL=db-read-seams-BSs0m1z1.js.map
|