@gusto/baerly-storage 0.5.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +47 -124
- package/dist/API.md +161 -511
- package/dist/CHANGELOG.md +1148 -307
- package/dist/RECIPES.md +398 -80
- package/dist/THIRD-PARTY-LICENSES.txt +5 -26
- package/dist/{app-config-DyiFK3_k.d.ts → app-config-C6qW7m8S.d.ts} +119 -111
- package/dist/app-config.d.ts +31 -1
- package/dist/app-config.js +1 -2
- package/dist/app-config.js.map +1 -1
- package/dist/auth.d.ts +33 -28
- package/dist/auth.js +549 -985
- package/dist/auth.js.map +1 -1
- package/dist/baerly.js +130 -138
- package/dist/baerly.js.map +1 -1
- package/dist/baerly.spec.json +97 -22
- package/dist/capacity-warning-header-BlVopyiI.js +16 -0
- package/dist/capacity-warning-header-BlVopyiI.js.map +1 -0
- package/dist/{client-Fe8CwB73.d.ts → client-CHQTXpef.d.ts} +121 -36
- package/dist/client-react.d.ts +67 -20
- package/dist/client-react.js +240 -54
- package/dist/client-react.js.map +1 -1
- package/dist/client.d.ts +5 -4
- package/dist/client.js +51 -16
- package/dist/client.js.map +1 -1
- package/dist/{cloudflare-DzKBrUlg.js → cloudflare-CKHYXccw.js} +504 -124
- package/dist/cloudflare-CKHYXccw.js.map +1 -0
- package/dist/cloudflare.d.ts +106 -71
- package/dist/cloudflare.js +334 -271
- package/dist/cloudflare.js.map +1 -1
- package/dist/code-resolution-CL_7L0wS.js +22 -0
- package/dist/code-resolution-CL_7L0wS.js.map +1 -0
- package/dist/collection-api-DbyhLAY8.d.ts +1001 -0
- package/dist/config-DEzInG6M.js +4035 -0
- package/dist/config-DEzInG6M.js.map +1 -0
- package/dist/constants-D3GSH3tc.js +469 -0
- package/dist/constants-D3GSH3tc.js.map +1 -0
- package/dist/{context-DRZ3tZ5l.js → context-rlpSnHFA.js} +17 -17
- package/dist/context-rlpSnHFA.js.map +1 -0
- package/dist/cost-B52llVDx.js +330 -0
- package/dist/cost-B52llVDx.js.map +1 -0
- package/dist/{current-json-C6nhPOm1.js → current-json-CC6lE4Aj.js} +115 -32
- package/dist/current-json-CC6lE4Aj.js.map +1 -0
- package/dist/db-plFUNTSF.d.ts +130 -0
- package/dist/db-read-seams-BSs0m1z1.js +3261 -0
- package/dist/db-read-seams-BSs0m1z1.js.map +1 -0
- package/dist/{deploy-DonTr-CV.js → deploy-Obj4nE-Z.js} +12 -16
- package/dist/deploy-Obj4nE-Z.js.map +1 -0
- package/dist/{dev-banner-CWHIk8tH.d.ts → dev-banner-B5AUHmu1.d.ts} +1 -4
- package/dist/dev-landing-BI5UdmOb.d.ts +32 -0
- package/dist/dev-landing-CD-si4dW.js +50 -0
- package/dist/dev-landing-CD-si4dW.js.map +1 -0
- package/dist/dev-vite.d.ts +38 -39
- package/dist/dev-vite.js +67 -36
- package/dist/dev-vite.js.map +1 -1
- package/dist/dev.d.ts +3 -2
- package/dist/dev.js +2 -1
- package/dist/doctor-BA0i-YAN.js +270 -0
- package/dist/doctor-BA0i-YAN.js.map +1 -0
- package/dist/dump-D1vX8ozg.js +133 -0
- package/dist/dump-D1vX8ozg.js.map +1 -0
- package/dist/errors-7Rk1HGCE.js +160 -0
- package/dist/errors-7Rk1HGCE.js.map +1 -0
- package/dist/{validate-DtljsCh1.js → export-BVL2EvYE.js} +409 -19
- package/dist/export-BVL2EvYE.js.map +1 -0
- package/dist/fsck-BWkPgov4.js +145 -0
- package/dist/fsck-BWkPgov4.js.map +1 -0
- package/dist/gcs-admin-Dso1HWQj.d.ts +127 -0
- package/dist/gcs.d.ts +30 -0
- package/dist/gcs.js +1 -0
- package/dist/goog4-signer-CeLIABoE.js +331 -0
- package/dist/goog4-signer-CeLIABoE.js.map +1 -0
- package/dist/{http-DGd5tbNs.js → http-Z5rZyYMX.js} +898 -271
- package/dist/http-Z5rZyYMX.js.map +1 -0
- package/dist/http-transport-DNUM8kU-.js +1299 -0
- package/dist/http-transport-DNUM8kU-.js.map +1 -0
- package/dist/http.d.ts +366 -294
- package/dist/http.js +2 -2
- package/dist/index-JJrIu1pO.d.ts +135 -0
- package/dist/index-LEgHN0qJ.d.ts +50 -0
- package/dist/{index-CuA9Mi3K.d.ts → index-RiEYj8t0.d.ts} +291 -78
- package/dist/index.d.ts +27 -6
- package/dist/index.js +3 -5
- package/dist/inspect-BTsVYZKd.js +196 -0
- package/dist/inspect-BTsVYZKd.js.map +1 -0
- package/dist/{key-Di6yyxFu.js → key-C4FPZ9Io.js} +3 -4
- package/dist/{key-Di6yyxFu.js.map → key-C4FPZ9Io.js.map} +1 -1
- package/dist/ledger-Dj_bGgo0.js +192 -0
- package/dist/ledger-Dj_bGgo0.js.map +1 -0
- package/dist/legacy-names-DgZBtgOh.js +47 -0
- package/dist/legacy-names-DgZBtgOh.js.map +1 -0
- package/dist/log-C9W15Dfo.d.ts +94 -0
- package/dist/log-tail-DWJbneBF.js +142 -0
- package/dist/log-tail-DWJbneBF.js.map +1 -0
- package/dist/log-walk-C-vA-WGJ.js +111 -0
- package/dist/log-walk-C-vA-WGJ.js.map +1 -0
- package/dist/maintenance-Dd-Yakqj.js +1709 -0
- package/dist/maintenance-Dd-Yakqj.js.map +1 -0
- package/dist/maintenance-DevB6z4e.js +2237 -0
- package/dist/maintenance-DevB6z4e.js.map +1 -0
- package/dist/maintenance.d.ts +100 -3
- package/dist/maintenance.js +1 -3
- package/dist/node.d.ts +130 -142
- package/dist/node.js +4 -3
- package/dist/{observability-BmflLCdF.js → observability-C-ISCCLE.js} +1275 -332
- package/dist/observability-C-ISCCLE.js.map +1 -0
- package/dist/observability.d.ts +27 -3
- package/dist/observability.js +3 -3
- package/dist/path-segment-DBXG26PW.js +363 -0
- package/dist/path-segment-DBXG26PW.js.map +1 -0
- package/dist/{plan-a7PJHBCy.js → plan-BvQbaNMe.js} +19 -11
- package/dist/plan-BvQbaNMe.js.map +1 -0
- package/dist/request-CRWiTrza.js +272 -0
- package/dist/request-CRWiTrza.js.map +1 -0
- package/dist/restore-U6Im8V1V.js +1467 -0
- package/dist/restore-U6Im8V1V.js.map +1 -0
- package/dist/retry-OBtLB2GC.js +126 -0
- package/dist/retry-OBtLB2GC.js.map +1 -0
- package/dist/rolldown-runtime-D3KUYPsf.js +12 -0
- package/dist/{runtime-spec-Dsw2-n8S.js → runtime-spec-B5mg3pHF.js} +189 -28
- package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
- package/dist/{s3-http-B-z8th6O.d.ts → s3-http-DBC_wiCL.d.ts} +18 -10
- package/dist/s3.d.ts +20 -7
- package/dist/s3.js +4 -5
- package/dist/s3.js.map +1 -1
- package/dist/sha256-4FfGQNPw.js +22 -0
- package/dist/sha256-4FfGQNPw.js.map +1 -0
- package/dist/{shared-secret-DgEicd3x.js → shared-secret-Vkur-8r0.js} +27 -15
- package/dist/shared-secret-Vkur-8r0.js.map +1 -0
- package/dist/sigv4-sign-5IUflUD_.js +507 -0
- package/dist/sigv4-sign-5IUflUD_.js.map +1 -0
- package/dist/snapshot-CknzkDM0.js +148 -0
- package/dist/snapshot-CknzkDM0.js.map +1 -0
- package/dist/{src-BL_JoPTn.js → src-Actga-bO.js} +1004 -378
- package/dist/src-Actga-bO.js.map +1 -0
- package/dist/src-D0MQfvOp.js +812 -0
- package/dist/src-D0MQfvOp.js.map +1 -0
- package/dist/src-Dr9uo3dc.js +501 -0
- package/dist/src-Dr9uo3dc.js.map +1 -0
- package/dist/{subcommand-DoDA-K7d.js → subcommand-BLoF66dG.js} +89 -16
- package/dist/subcommand-BLoF66dG.js.map +1 -0
- package/dist/{time-DUqvFMHq.js → time-DRxTP9iv.js} +15 -34
- package/dist/time-DRxTP9iv.js.map +1 -0
- package/dist/types-suVbsEWS.d.ts +116 -0
- package/dist/{usage-DBV1eQHC.js → usage-CPzVhrQr.js} +40 -45
- package/dist/usage-CPzVhrQr.js.map +1 -0
- package/dist/uuid-BuT_c404.js +333 -0
- package/dist/uuid-BuT_c404.js.map +1 -0
- package/dist/verifier-Bmlmndzo.d.ts +95 -0
- package/dist/{wire-izfGZDvr.js → wire-DndvKU-K.js} +2 -3
- package/dist/wire-DndvKU-K.js.map +1 -0
- package/package.json +96 -69
- package/dist/aws4fetch.esm-p7eEzLCs.js +0 -1702
- package/dist/aws4fetch.esm-p7eEzLCs.js.map +0 -1
- package/dist/bytes-BXdamO3L.js +0 -11
- package/dist/bytes-BXdamO3L.js.map +0 -1
- package/dist/cloudflare-DzKBrUlg.js.map +0 -1
- package/dist/config-1tv0-Yzm.js +0 -2693
- package/dist/config-1tv0-Yzm.js.map +0 -1
- package/dist/constants-CfeMWQWk.js +0 -222
- package/dist/constants-CfeMWQWk.js.map +0 -1
- package/dist/context-DRZ3tZ5l.js.map +0 -1
- package/dist/cost-DSMIVqzL.js +0 -203
- package/dist/cost-DSMIVqzL.js.map +0 -1
- package/dist/current-json-C6nhPOm1.js.map +0 -1
- package/dist/db-DsPkOVEH.d.ts +0 -254
- package/dist/deploy-DonTr-CV.js.map +0 -1
- package/dist/doctor-DSIyCDg_.js +0 -346
- package/dist/doctor-DSIyCDg_.js.map +0 -1
- package/dist/dump-Bh5k26VQ.js +0 -94
- package/dist/dump-Bh5k26VQ.js.map +0 -1
- package/dist/errors-Dfa3p78c.js +0 -78
- package/dist/errors-Dfa3p78c.js.map +0 -1
- package/dist/export-DtF5tDIM.js +0 -401
- package/dist/export-DtF5tDIM.js.map +0 -1
- package/dist/fsck-D_djMO5D.js +0 -279
- package/dist/fsck-D_djMO5D.js.map +0 -1
- package/dist/http-DGd5tbNs.js.map +0 -1
- package/dist/index-0rZcMBwy.d.ts +0 -115
- package/dist/index-BNRh23K9.d.ts +0 -162
- package/dist/index-BYk9oCNf.d.ts +0 -1112
- package/dist/indexes-Dn9hbGQG.d.ts +0 -22
- package/dist/inspect-6WZ-pC7-.js +0 -133
- package/dist/inspect-6WZ-pC7-.js.map +0 -1
- package/dist/log-tail-D98U1JBo.js +0 -522
- package/dist/log-tail-D98U1JBo.js.map +0 -1
- package/dist/maintenance-B4Dki6Ig.js +0 -2157
- package/dist/maintenance-B4Dki6Ig.js.map +0 -1
- package/dist/maintenance-B_e0T99L.d.ts +0 -537
- package/dist/maintenance-C7coQp4c.js +0 -1418
- package/dist/maintenance-C7coQp4c.js.map +0 -1
- package/dist/normalize-rjnZLwS4.js +0 -133
- package/dist/normalize-rjnZLwS4.js.map +0 -1
- package/dist/observability-BmflLCdF.js.map +0 -1
- package/dist/plan-a7PJHBCy.js.map +0 -1
- package/dist/query-rAtXNQQB.js +0 -1773
- package/dist/query-rAtXNQQB.js.map +0 -1
- package/dist/rebuild-index-BVzQSZlm.js +0 -81
- package/dist/rebuild-index-BVzQSZlm.js.map +0 -1
- package/dist/request-u0M51mhJ.js +0 -72
- package/dist/request-u0M51mhJ.js.map +0 -1
- package/dist/restore-R-4rbciV.js +0 -778
- package/dist/restore-R-4rbciV.js.map +0 -1
- package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
- package/dist/runtime-spec-Dsw2-n8S.js.map +0 -1
- package/dist/shared-secret-DgEicd3x.js.map +0 -1
- package/dist/src-BL_JoPTn.js.map +0 -1
- package/dist/src-CYHFDrKz.js +0 -536
- package/dist/src-CYHFDrKz.js.map +0 -1
- package/dist/src-DYZ4H1aF.js +0 -392
- package/dist/src-DYZ4H1aF.js.map +0 -1
- package/dist/subcommand-DoDA-K7d.js.map +0 -1
- package/dist/time-DUqvFMHq.js.map +0 -1
- package/dist/usage-DBV1eQHC.js.map +0 -1
- package/dist/validate-DtljsCh1.js.map +0 -1
- package/dist/wire-izfGZDvr.js.map +0 -1
|
@@ -0,0 +1,2237 @@
|
|
|
1
|
+
import { i as isWriteConflict, t as BaerlyError } from "./errors-7Rk1HGCE.js";
|
|
2
|
+
import { c as certifiedDeleteFloor, d as logSeqStartOf, g as encodeJsonBytes, h as decodeJsonBytes, m as unsupportedSchemaVersionMessage, o as assertCurrentJsonTransition, p as readCurrentJson, s as casUpdateCurrentJson, t as assertNameSegment, u as logDeleteFloorOf } from "./path-segment-DBXG26PW.js";
|
|
3
|
+
import { _ as MAINTENANCE_PROFILE_NODE, c as GC_MARK_LIST_PAGE_KEYS, d as GC_PENDING_CONTENT_TYPE, f as LOG_FORWARD_PROBE_CAP, g as MAINTENANCE_PROFILE_CF_PAID, h as MAINTENANCE_PROFILE_CF_FREE, l as GC_MAX_PENDING_CANDIDATES, m as MAINTENANCE_MIN_LIVE_BYTES, r as CF_PAID_COMPACT_TAIL_PROBE_GETS, u as GC_PASS_GRACE_FRACTION } from "./constants-D3GSH3tc.js";
|
|
4
|
+
import { t as sha256Hex } from "./sha256-4FfGQNPw.js";
|
|
5
|
+
import { r as currentRequestLedger } from "./ledger-Dj_bGgo0.js";
|
|
6
|
+
import { n as ctxMetrics, r as getCurrentContext } from "./context-rlpSnHFA.js";
|
|
7
|
+
// packages/protocol/src/coordination/gc-pending.ts
|
|
8
|
+
/**
|
|
9
|
+
* `gc/pending.json` — the per-collection GC candidate ledger. CAS-
|
|
10
|
+
* protected; one per `(tenant, collection)` key — for example
|
|
11
|
+
* `<tenant>/<collection>/gc/pending.json`. `runGc()` is the single
|
|
12
|
+
* writer that adds and removes entries. Stays small in steady state
|
|
13
|
+
* because every candidate is eventually resolved out of the ledger.
|
|
14
|
+
*
|
|
15
|
+
* "Mark" appends candidates with a future `due_at`; "sweep" revalidates
|
|
16
|
+
* due candidates and either DELETEs the named object or resolves the
|
|
17
|
+
* entry out of the ledger without one. Both run in the same GC pass, not
|
|
18
|
+
* separate passes.
|
|
19
|
+
*
|
|
20
|
+
* Lives next to {@link CurrentJson} in `coordination/` — same shape
|
|
21
|
+
* of "CAS-protected small control object." Pure module; no Node
|
|
22
|
+
* imports; Worker-bundleable.
|
|
23
|
+
*
|
|
24
|
+
* @see packages/server/src/gc.ts
|
|
25
|
+
*/
|
|
26
|
+
/**
|
|
27
|
+
* The single constructor for a `gc/pending.json` key:
|
|
28
|
+
* `<collectionPrefix>/gc/pending.json`. `collectionPrefix` is the
|
|
29
|
+
* `<…>/manifests/<collection>` segment — this helper adds the ledger's
|
|
30
|
+
* relative path. Route all callers here so the key shape lives in one
|
|
31
|
+
* place, mirroring {@link logObjectKey} in `log-key.ts` for the sibling
|
|
32
|
+
* `log/<seq>.json` shape.
|
|
33
|
+
*/
|
|
34
|
+
const gcPendingKey = (collectionPrefix) => `${collectionPrefix}/gc/pending.json`;
|
|
35
|
+
/**
|
|
36
|
+
* Read + parse `gc/pending.json` at `key`. Returns `null` on
|
|
37
|
+
* not-found.
|
|
38
|
+
*
|
|
39
|
+
* @throws BaerlyError{code:"InvalidResponse"} — body is not valid
|
|
40
|
+
* JSON, or `schema_version` is unknown, or the shape fails
|
|
41
|
+
* the runtime guard.
|
|
42
|
+
*/
|
|
43
|
+
const readGcPending = async (storage, key, opts) => {
|
|
44
|
+
const got = await storage.get(key, opts);
|
|
45
|
+
if (got === null) return null;
|
|
46
|
+
let parsed;
|
|
47
|
+
try {
|
|
48
|
+
parsed = decodeJsonBytes(got.body);
|
|
49
|
+
} catch (error) {
|
|
50
|
+
throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: body is not valid JSON`, { cause: error });
|
|
51
|
+
}
|
|
52
|
+
return {
|
|
53
|
+
json: assertGcPending(parsed, key),
|
|
54
|
+
etag: got.etag
|
|
55
|
+
};
|
|
56
|
+
};
|
|
57
|
+
/**
|
|
58
|
+
* Create `gc/pending.json` if-and-only-if it does not exist (S3
|
|
59
|
+
* `If-None-Match: "*"`). Use this once per collection at first GC
|
|
60
|
+
* run; subsequent updates go through {@link casUpdateGcPending}.
|
|
61
|
+
*
|
|
62
|
+
* @throws BaerlyError{code:"WriteConflict"} — the key already exists.
|
|
63
|
+
* @throws BaerlyError{code:"InvalidResponse"} — `initial` fails the
|
|
64
|
+
* runtime shape guard.
|
|
65
|
+
*/
|
|
66
|
+
const createGcPending = async (storage, key, initial, opts) => {
|
|
67
|
+
assertGcPending(initial, key);
|
|
68
|
+
const body = encodeJsonBytes(initial);
|
|
69
|
+
const putOpts = {
|
|
70
|
+
ifNoneMatch: "*",
|
|
71
|
+
contentType: GC_PENDING_CONTENT_TYPE,
|
|
72
|
+
...opts?.signal !== void 0 && { signal: opts.signal }
|
|
73
|
+
};
|
|
74
|
+
let result;
|
|
75
|
+
try {
|
|
76
|
+
result = await storage.put(key, body, putOpts);
|
|
77
|
+
} catch (error) {
|
|
78
|
+
throw translateCasError(error, key);
|
|
79
|
+
}
|
|
80
|
+
return {
|
|
81
|
+
json: initial,
|
|
82
|
+
etag: result.etag
|
|
83
|
+
};
|
|
84
|
+
};
|
|
85
|
+
/**
|
|
86
|
+
* Read-modify-write `gc/pending.json` under CAS, with a bounded retry
|
|
87
|
+
* loop. Each attempt re-reads the latest body, hands the `mutator`
|
|
88
|
+
* that latest value, and writes the result with
|
|
89
|
+
* `If-Match: <latest etag>`. On `WriteConflict` (a concurrent writer landed
|
|
90
|
+
* between this attempt's read and write) the loop re-reads and
|
|
91
|
+
* re-applies the mutator, up to {@link GC_PENDING_CAS_MAX_ATTEMPTS}
|
|
92
|
+
* total attempts, then surfaces `WriteConflict`.
|
|
93
|
+
*
|
|
94
|
+
* `mutator` MUST be a pure, deterministic MERGE of this pass's results
|
|
95
|
+
* INTO the `latest` value it is handed — it is called once per attempt
|
|
96
|
+
* (so it must not have side effects), and it MUST read `latest` rather
|
|
97
|
+
* than ignore it and write a precomputed set. Ignoring `latest` would
|
|
98
|
+
* silently overwrite a concurrent pass's candidates: the
|
|
99
|
+
* If-Match succeeds (it used the fresh etag), so no conflict is
|
|
100
|
+
* raised, and the concurrent marks are lost. See {@link mergeGcPending}.
|
|
101
|
+
*
|
|
102
|
+
* @throws BaerlyError{code:"WriteConflict"} — another writer kept landing a
|
|
103
|
+
* write between this function's read and write for every
|
|
104
|
+
* attempt, OR `key` does not exist. The missing-key case is a
|
|
105
|
+
* CAS precondition failure, not a separate class of fault: the
|
|
106
|
+
* pre-read is an optimisation, and a bare
|
|
107
|
+
* `If-Match: <etag>` PUT against a key another actor deleted
|
|
108
|
+
* would have surfaced `412` → `WriteConflict` from the storage layer
|
|
109
|
+
* anyway. It is deliberately NOT retried — a deleted ledger
|
|
110
|
+
* stays deleted until someone calls {@link createGcPending},
|
|
111
|
+
* which the next `runGc` pass does. `baerly admin restore`
|
|
112
|
+
* deletes `gc/pending.json` on both reseed branches, so a
|
|
113
|
+
* concurrent pass reaches this routinely; `runGc` treats
|
|
114
|
+
* `WriteConflict` as benign best-effort.
|
|
115
|
+
* @throws BaerlyError{code:"InvalidResponse"} — the stored body doesn't
|
|
116
|
+
* parse or fails the shape guard. Kept distinct from the
|
|
117
|
+
* missing-key case on purpose: a caller that tolerates
|
|
118
|
+
* `WriteConflict` as a race must not thereby swallow a corrupt
|
|
119
|
+
* ledger, which fails identically on every future pass.
|
|
120
|
+
*/
|
|
121
|
+
const casUpdateGcPending = async (storage, key, mutator, opts) => {
|
|
122
|
+
let lastConflict;
|
|
123
|
+
for (let attempt = 0; attempt < 3; attempt++) {
|
|
124
|
+
const existing = await readGcPending(storage, key, opts);
|
|
125
|
+
if (existing === null) throw new BaerlyError("WriteConflict", `gc/pending.json at ${key} does not exist; it was deleted concurrently, or was never created — see createGcPending`);
|
|
126
|
+
const next = mutator(structuredClone(existing.json));
|
|
127
|
+
assertGcPending(next, key);
|
|
128
|
+
const body = encodeJsonBytes(next);
|
|
129
|
+
const putOpts = {
|
|
130
|
+
ifMatch: existing.etag,
|
|
131
|
+
contentType: GC_PENDING_CONTENT_TYPE,
|
|
132
|
+
...opts?.signal !== void 0 && { signal: opts.signal }
|
|
133
|
+
};
|
|
134
|
+
try {
|
|
135
|
+
return {
|
|
136
|
+
json: next,
|
|
137
|
+
etag: (await storage.put(key, body, putOpts)).etag
|
|
138
|
+
};
|
|
139
|
+
} catch (error) {
|
|
140
|
+
const translated = translateCasError(error, key);
|
|
141
|
+
if (!isWriteConflict(translated)) throw translated;
|
|
142
|
+
lastConflict = translated;
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
throw lastConflict;
|
|
146
|
+
};
|
|
147
|
+
/**
|
|
148
|
+
* Pure merge of one GC pass's results INTO the `latest`
|
|
149
|
+
* `gc/pending.json` value, used as the {@link casUpdateGcPending}
|
|
150
|
+
* mutator. Deterministic, no I/O — the kernel unit + mutation test
|
|
151
|
+
* surface. Splitting it out is what makes the CAS write correct under
|
|
152
|
+
* concurrency: each retry re-merges against fresh `latest` rather than
|
|
153
|
+
* overwriting it with a stale precomputed set.
|
|
154
|
+
*
|
|
155
|
+
* Semantics:
|
|
156
|
+
* - **candidates**: start from `latest.candidates`, DROP any whose key
|
|
157
|
+
* this pass already RESOLVED (`sweptKeys` carries both object DELETEs
|
|
158
|
+
* and ledger-only drops/evictions), then APPEND every fresh mark whose
|
|
159
|
+
* key is not already present AND was not itself resolved this pass. A
|
|
160
|
+
* `graceMillis: 0` pass can mark-and-sweep a key in one go; re-adding a
|
|
161
|
+
* terminal key would be wrong. Dedup also drops a key a concurrent pass
|
|
162
|
+
* already marked. Capped at `maxCandidates`.
|
|
163
|
+
* - **last_swept_at**: the lexicographically LATER of `latest`'s and
|
|
164
|
+
* this pass's (ISO-8601 UTC; `""` sorts lowest so a real timestamp
|
|
165
|
+
* always wins). Never regress a concurrent pass's newer sweep time.
|
|
166
|
+
*/
|
|
167
|
+
const mergeGcPending = (latest, pass) => {
|
|
168
|
+
const surviving = latest.candidates.filter((c) => !pass.sweptKeys.has(c.key));
|
|
169
|
+
const present = new Set(surviving.map((c) => c.key));
|
|
170
|
+
const appended = [];
|
|
171
|
+
for (const c of pass.newCandidates) if (!pass.sweptKeys.has(c.key) && !present.has(c.key)) {
|
|
172
|
+
present.add(c.key);
|
|
173
|
+
appended.push(c);
|
|
174
|
+
}
|
|
175
|
+
return {
|
|
176
|
+
schema_version: 1,
|
|
177
|
+
candidates: [...surviving, ...appended].slice(0, pass.maxCandidates),
|
|
178
|
+
last_swept_at: pass.lastSweptAt > latest.last_swept_at ? pass.lastSweptAt : latest.last_swept_at
|
|
179
|
+
};
|
|
180
|
+
};
|
|
181
|
+
/**
|
|
182
|
+
* Accepted `reason` values. Only `"orphan-snapshot"` is still emitted; the
|
|
183
|
+
* other two are legacy-ledger inputs with different sweep fates — see
|
|
184
|
+
* {@link GcCandidate.reason}.
|
|
185
|
+
*/
|
|
186
|
+
const VALID_REASONS = /* @__PURE__ */ new Set([
|
|
187
|
+
"stale-log",
|
|
188
|
+
"orphan-snapshot",
|
|
189
|
+
"orphan-content"
|
|
190
|
+
]);
|
|
191
|
+
/**
|
|
192
|
+
* Runtime guard for `parsed` to be a {@link GcPending}. Throws
|
|
193
|
+
* `BaerlyError{code:"InvalidResponse"}` rather than coercing.
|
|
194
|
+
*/
|
|
195
|
+
const assertGcPending = (parsed, key) => {
|
|
196
|
+
if (parsed === null || typeof parsed !== "object") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: parsed body is not an object`);
|
|
197
|
+
const r = parsed;
|
|
198
|
+
if (r["schema_version"] !== 1) throw new BaerlyError("InvalidResponse", unsupportedSchemaVersionMessage(`gc/pending.json at ${key}`, r["schema_version"], 1));
|
|
199
|
+
if (!Array.isArray(r["candidates"])) throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates must be an array`);
|
|
200
|
+
for (let i = 0; i < r["candidates"].length; i++) {
|
|
201
|
+
const c = r["candidates"][i];
|
|
202
|
+
if (c === null || typeof c !== "object") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates[${String(i)}] is not an object`);
|
|
203
|
+
const cr = c;
|
|
204
|
+
if (typeof cr["key"] !== "string" || cr["key"].length === 0) throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates[${String(i)}].key must be a non-empty string`);
|
|
205
|
+
if (typeof cr["due_at"] !== "string") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates[${String(i)}].due_at must be a string`);
|
|
206
|
+
if (typeof cr["reason"] !== "string" || !VALID_REASONS.has(cr["reason"])) throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates[${String(i)}].reason must be one of stale-log|orphan-snapshot|orphan-content`);
|
|
207
|
+
if (cr["generation"] !== void 0 && typeof cr["generation"] !== "string") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: candidates[${String(i)}].generation must be a string when present`);
|
|
208
|
+
}
|
|
209
|
+
if (typeof r["last_swept_at"] !== "string") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: last_swept_at must be a string`);
|
|
210
|
+
if (r["log_scan_cursor"] !== void 0 && typeof r["log_scan_cursor"] !== "string") throw new BaerlyError("InvalidResponse", `gc/pending.json at ${key}: log_scan_cursor must be a string when present`);
|
|
211
|
+
return parsed;
|
|
212
|
+
};
|
|
213
|
+
/**
|
|
214
|
+
* Wrap a storage-level error with `gc/pending.json at <key>`
|
|
215
|
+
* location context. `WriteConflict` (the storage layer's CAS-lost signal)
|
|
216
|
+
* is re-thrown with an annotated message; other `BaerlyError`s pass
|
|
217
|
+
* through; non-`BaerlyError` falls through as `InvalidResponse`.
|
|
218
|
+
*/
|
|
219
|
+
const translateCasError = (e, key) => {
|
|
220
|
+
if (isWriteConflict(e)) return new BaerlyError("WriteConflict", `gc/pending.json CAS lost at ${key}: ${e.message}`, { cause: e });
|
|
221
|
+
if (e instanceof BaerlyError) return e;
|
|
222
|
+
return new BaerlyError("InvalidResponse", `gc/pending.json write at ${key} failed: ${String(e)}`, { cause: e });
|
|
223
|
+
};
|
|
224
|
+
/**
|
|
225
|
+
* The single constructor for a log-object key:
|
|
226
|
+
* `<manifestPrefix>/log/<seq>.json`. `manifestPrefix` is the
|
|
227
|
+
* `<…>/manifests/<collection>` segment — this helper adds `/log/`.
|
|
228
|
+
* `<seq>` is unpadded decimal, so lexicographic LIST order is not numeric
|
|
229
|
+
* order (`log/10.json` precedes `log/2.json`). The descending base-32 LSN
|
|
230
|
+
* encoding applies to LSN values and the LSN half of `/v1/since` cursors,
|
|
231
|
+
* not these keys.
|
|
232
|
+
* Route all callers here so the key shape lives in one place.
|
|
233
|
+
*/
|
|
234
|
+
const logObjectKey = (manifestPrefix, seq) => `${manifestPrefix}/log/${seq}.json`;
|
|
235
|
+
// packages/protocol/src/snapshot-hash.ts
|
|
236
|
+
/**
|
|
237
|
+
* SHA-256 of `bytes` as a 64-char lowercase hex string. Used to seal
|
|
238
|
+
* snapshot filenames so a crashed mid-PUT can't produce a body that
|
|
239
|
+
* readers consume as truth: the filename embeds the hash; readers
|
|
240
|
+
* recompute on load and reject any mismatch as "file missing."
|
|
241
|
+
*
|
|
242
|
+
* Distinct from {@link versionFromContent} (the legacy 32-hex content-key
|
|
243
|
+
* scheme) — snapshot bodies are larger and longer-lived;
|
|
244
|
+
* 256-bit collision resistance matters here.
|
|
245
|
+
*/
|
|
246
|
+
const snapshotHash = (bytes) => sha256Hex(bytes);
|
|
247
|
+
// packages/server/src/caller-facing-error.ts
|
|
248
|
+
/**
|
|
249
|
+
* Errors whose message is written for the caller of the public API rather
|
|
250
|
+
* than for the operator. The HTTP layer exposes a contextual code's message
|
|
251
|
+
* (`InvalidConfig`) only for errors in this set; any other `InvalidConfig`,
|
|
252
|
+
* such as a storage or adapter configuration fault that can carry bucket
|
|
253
|
+
* layout, stays scrubbed.
|
|
254
|
+
*/
|
|
255
|
+
const CALLER_FACING_ERRORS = /* @__PURE__ */ new WeakSet();
|
|
256
|
+
/** Mark `err` as caller input at the point it is thrown, and return it. */
|
|
257
|
+
const markCallerFacing = (err) => {
|
|
258
|
+
CALLER_FACING_ERRORS.add(err);
|
|
259
|
+
return err;
|
|
260
|
+
};
|
|
261
|
+
/** True when `err` was marked with {@link markCallerFacing}. */
|
|
262
|
+
const isCallerFacing = (err) => CALLER_FACING_ERRORS.has(err);
|
|
263
|
+
/**
|
|
264
|
+
* Run a caller-input check, marking any `BaerlyError` it throws with
|
|
265
|
+
* {@link markCallerFacing}. For shared checks (from `@baerly/protocol`)
|
|
266
|
+
* that cannot mark their own errors.
|
|
267
|
+
*/
|
|
268
|
+
const callerFacingCheck = (check) => {
|
|
269
|
+
try {
|
|
270
|
+
check();
|
|
271
|
+
} catch (error) {
|
|
272
|
+
if (error instanceof BaerlyError) markCallerFacing(error);
|
|
273
|
+
throw error;
|
|
274
|
+
}
|
|
275
|
+
};
|
|
276
|
+
// packages/server/src/collection-alias.ts
|
|
277
|
+
const ALIASED_COLLECTION_RESOLUTION = "An earlier release stored this collection under a non-NFC name, and this name addresses the same stored objects, so it cannot be read or written safely. Keep the app on a different NFC name: export the stored data with `baerly admin dump --collection=<stored name>` and restore it with `baerly admin restore` under an NFC name that is not canonically equivalent to either spelling. For a mixed legacy log, dump with --recover-legacy-names selects one exact spelling and requires a matching snapshot or no snapshot.";
|
|
278
|
+
/**
|
|
279
|
+
* `true` when a stored log entry, snapshot, or snapshot manifest that
|
|
280
|
+
* names collection `stored` belongs to collection `expected`. Live
|
|
281
|
+
* folds, compaction, capacity checks, and ordinary exports filter through
|
|
282
|
+
* this guard. Explicit CLI recovery selects exact spellings instead.
|
|
283
|
+
*
|
|
284
|
+
* R2 stores canonically-equivalent keys as one object, so an NFC name
|
|
285
|
+
* addresses the objects a legacy non-NFC name wrote (and vice versa).
|
|
286
|
+
* Those records carry the other spelling. Skipping them would read as an
|
|
287
|
+
* empty collection and let a fold advance the floor past them, after
|
|
288
|
+
* which log retirement deletes them, so a canonically-equivalent but
|
|
289
|
+
* byte-different name throws instead of returning `false`.
|
|
290
|
+
*
|
|
291
|
+
* @throws BaerlyError code="InvalidConfig" — `stored` and `expected`
|
|
292
|
+
* differ but are canonically equivalent. Marked caller-facing.
|
|
293
|
+
*/
|
|
294
|
+
const isOwnCollection = (stored, expected) => {
|
|
295
|
+
if (stored === expected) return true;
|
|
296
|
+
if (typeof stored === "string" && stored.normalize("NFC") === expected.normalize("NFC")) throw markCallerFacing(new BaerlyError("InvalidConfig", `collection ${JSON.stringify(expected)} addresses data stored under the canonically-equivalent name ${JSON.stringify(stored)} (a different Unicode normalization); refusing to read or rewrite it`, { resolution: ALIASED_COLLECTION_RESOLUTION }));
|
|
297
|
+
return false;
|
|
298
|
+
};
|
|
299
|
+
// packages/server/src/snapshot.ts
|
|
300
|
+
/**
|
|
301
|
+
* Snapshot file shape + parse. Lifted out of `./compactor.ts` so that
|
|
302
|
+
* `_internal/kernel.ts` — which re-exports these four symbols to the CLI,
|
|
303
|
+
* bench, and tests — does not transitively pull `withObservability` via
|
|
304
|
+
* `compact()`. `./compactor.ts` imports its own snapshot primitives back
|
|
305
|
+
* from this module.
|
|
306
|
+
*
|
|
307
|
+
* @see ../../../docs/spec/sync-protocol.md
|
|
308
|
+
*/
|
|
309
|
+
/**
|
|
310
|
+
* Single-level snapshot at L9; the level prefix is forward-compatible
|
|
311
|
+
* with future L0..L9 rolling merges without a wire change.
|
|
312
|
+
*/
|
|
313
|
+
const SNAPSHOT_LEVEL = 9;
|
|
314
|
+
/**
|
|
315
|
+
* `minSeq` and `maxSeq` are padded to {@link SEQ_DIGITS} digits so
|
|
316
|
+
* `list(prefix)` returns snapshots in seq order without needing to
|
|
317
|
+
* parse the filename. 12 digits caps at ~10^12 entries per collection;
|
|
318
|
+
* a real bucket hits S3's per-prefix QPS ceiling long before that.
|
|
319
|
+
*/
|
|
320
|
+
const SEQ_DIGITS = 12;
|
|
321
|
+
const MAX_SEQ = 10 ** SEQ_DIGITS - 1;
|
|
322
|
+
const pad = (n) => n.toString().padStart(SEQ_DIGITS, "0");
|
|
323
|
+
/**
|
|
324
|
+
* Build the on-bucket key for a snapshot file. `sha256` must be the
|
|
325
|
+
* lowercase hex digest of the canonical body
|
|
326
|
+
* ({@link encodeSnapshotBody}); the filename embeds it so a crashed
|
|
327
|
+
* mid-PUT body that doesn't match its own filename hash is rejected
|
|
328
|
+
* by readers as "missing."
|
|
329
|
+
*
|
|
330
|
+
* @throws BaerlyError code="InvalidConfig" — `minSeq`/`maxSeq` are
|
|
331
|
+
* out of range or `sha256` is not 64 hex chars.
|
|
332
|
+
*/
|
|
333
|
+
const snapshotKey = (collectionPrefix, minSeq, maxSeq, sha256) => {
|
|
334
|
+
if (!Number.isInteger(minSeq) || !Number.isInteger(maxSeq) || minSeq < 0 || maxSeq < 0 || minSeq > maxSeq || maxSeq > MAX_SEQ) throw new BaerlyError("InvalidConfig", `snapshotKey: invalid range [${minSeq}, ${maxSeq})`);
|
|
335
|
+
if (!/^[0-9a-f]{64}$/.test(sha256)) throw new BaerlyError("InvalidConfig", "snapshotKey: sha256 must be 64 hex chars");
|
|
336
|
+
return `${collectionPrefix}/snapshot/L${SNAPSHOT_LEVEL}/${pad(minSeq)}-${pad(maxSeq)}-${sha256}.json`;
|
|
337
|
+
};
|
|
338
|
+
/**
|
|
339
|
+
* Canonical byte encoding of a {@link SnapshotBody}. Only the
|
|
340
|
+
* compactor produces snapshots, and only this function does the
|
|
341
|
+
* serialisation — so the byte output is deterministic for a given
|
|
342
|
+
* `SnapshotBody` (identical input ⇒ identical bytes ⇒ identical
|
|
343
|
+
* filename hash).
|
|
344
|
+
*/
|
|
345
|
+
const encodeSnapshotBody = (s) => encodeJsonBytes(s);
|
|
346
|
+
/**
|
|
347
|
+
* Load a snapshot file as a `Map<_id, DocumentData>`. Verifies the
|
|
348
|
+
* body hash against the filename, checks the schema version, and
|
|
349
|
+
* cross-checks `body.collection` against the caller's expectation.
|
|
350
|
+
*
|
|
351
|
+
* @example
|
|
352
|
+
* ```ts
|
|
353
|
+
* import { loadSnapshotAsMap } from "@baerly/server/_internal/kernel";
|
|
354
|
+
*
|
|
355
|
+
* const map =
|
|
356
|
+
* srcCurrent.snapshot === null
|
|
357
|
+
* ? new Map<string, DocumentData>()
|
|
358
|
+
* : await loadSnapshotAsMap(src.storage, srcCurrent.snapshot, "tickets");
|
|
359
|
+
* ```
|
|
360
|
+
*
|
|
361
|
+
* @throws BaerlyError code="Internal" — pointer resolves to no body,
|
|
362
|
+
* or the body's SHA-256 doesn't match the hash embedded in the
|
|
363
|
+
* filename. (Protocol invariant violation; a corrupted snapshot
|
|
364
|
+
* the reader cannot continue past.)
|
|
365
|
+
* @throws BaerlyError code="InvalidResponse" — body isn't valid JSON,
|
|
366
|
+
* isn't an object, has an unsupported `schema_version`, or carries a
|
|
367
|
+
* `collection` that doesn't match `expectedCollection`.
|
|
368
|
+
*/
|
|
369
|
+
const loadSnapshotAsMap = async (storage, key, expectedCollection, signal) => {
|
|
370
|
+
const got = await storage.get(key, signal !== void 0 ? { signal } : void 0);
|
|
371
|
+
if (got === null) throw new BaerlyError("Internal", `compact: snapshot pointer ${key} resolves to no body; protocol violation`);
|
|
372
|
+
const filename = key.slice(key.lastIndexOf("/") + 1).replace(/\.json$/, "");
|
|
373
|
+
const lastDash = filename.lastIndexOf("-");
|
|
374
|
+
const expectedHash = filename.slice(lastDash + 1);
|
|
375
|
+
const actualHash = await snapshotHash(got.body);
|
|
376
|
+
if (actualHash !== expectedHash) throw new BaerlyError("Internal", `compact: snapshot ${key} body hash mismatch (got ${actualHash}); protocol violation`);
|
|
377
|
+
let parsed;
|
|
378
|
+
try {
|
|
379
|
+
parsed = decodeJsonBytes(got.body);
|
|
380
|
+
} catch (error) {
|
|
381
|
+
throw new BaerlyError("InvalidResponse", `compact: snapshot ${key} body is not valid JSON`, { cause: error });
|
|
382
|
+
}
|
|
383
|
+
if (parsed === null || typeof parsed !== "object") throw new BaerlyError("InvalidResponse", `compact: snapshot ${key} body is not an object`);
|
|
384
|
+
const body = parsed;
|
|
385
|
+
if (body.schema_version !== 1) throw new BaerlyError("InvalidResponse", unsupportedSchemaVersionMessage(`compact: snapshot ${key}`, body.schema_version, 1));
|
|
386
|
+
if (!isOwnCollection(body.collection, expectedCollection)) throw new BaerlyError("InvalidResponse", `compact: snapshot ${key} carries collection ${body.collection}, expected ${expectedCollection}`);
|
|
387
|
+
if (!Array.isArray(body.docs)) throw new BaerlyError("InvalidResponse", `compact: snapshot ${key} body.docs is not an array`);
|
|
388
|
+
const out = /* @__PURE__ */ new Map();
|
|
389
|
+
for (const row of body.docs) out.set(row._id, row.body);
|
|
390
|
+
return out;
|
|
391
|
+
};
|
|
392
|
+
// packages/server/src/option-guards.ts
|
|
393
|
+
/**
|
|
394
|
+
* Shared pre-I/O validation for the internal maintenance option seams
|
|
395
|
+
* (`InternalCompactOptions`, `InternalRunGcOptions`).
|
|
396
|
+
*
|
|
397
|
+
* Those seams are unvalidated by construction — reached by JS callers,
|
|
398
|
+
* in-repo casts, and the `_internal/testing` subpath — yet their values
|
|
399
|
+
* feed seq arithmetic and range bounds. A non-finite value must fail
|
|
400
|
+
* before the first storage operation, so a rejected run costs nothing
|
|
401
|
+
* durable. `compactor.ts` explains the specific NaN corruption at stake.
|
|
402
|
+
*
|
|
403
|
+
* Zero-import leaf beyond `BaerlyError`: both maintenance entry points
|
|
404
|
+
* already carry that import, so consolidating here removes duplication
|
|
405
|
+
* without widening either closure.
|
|
406
|
+
*/
|
|
407
|
+
/**
|
|
408
|
+
* Throw `InvalidConfig` unless `value` is an integer at or above `min`.
|
|
409
|
+
* `min` is `0` for a seq-shaped or count-shaped option (zero is a
|
|
410
|
+
* meaningful "do nothing" bound) and `1` for one that must make at least
|
|
411
|
+
* one unit of progress to be well-defined.
|
|
412
|
+
*
|
|
413
|
+
* Callers own the `undefined ⇒ default` decision before calling; this
|
|
414
|
+
* guard rejects rather than defaults, so passing an absent option is a
|
|
415
|
+
* caller bug, not a silently-tolerated input.
|
|
416
|
+
*/
|
|
417
|
+
const requireIntegerOption = (fnName, collectionName, optionName, value, min) => {
|
|
418
|
+
if (!Number.isInteger(value) || value < min) throw new BaerlyError("InvalidConfig", `${fnName}(${collectionName}): ${optionName} must be a ${min === 0 ? "non-negative" : "positive"} integer, got ${String(value)}`);
|
|
419
|
+
};
|
|
420
|
+
// packages/server/src/log-walk.ts
|
|
421
|
+
/**
|
|
422
|
+
* Shared log-walk primitives consumed by the read path (`query.ts`),
|
|
423
|
+
* the compactor (`compactor.ts`), and the optional integrity walk in
|
|
424
|
+
* `Writer.#singleAttemptCommit` (`writer.ts`).
|
|
425
|
+
*
|
|
426
|
+
* Two operations: read one log entry, or walk a contiguous range of
|
|
427
|
+
* log entries with bounded parallelism. Each kernel call site
|
|
428
|
+
* previously inlined the same range-build + unbounded `Promise.all`
|
|
429
|
+
* pattern; on a free-tier collection where the compactor lags the
|
|
430
|
+
* tail to 50-100 entries, that fans out 50-100 concurrent GETs per
|
|
431
|
+
* call — and a contended writer multiplies that by its forward
|
|
432
|
+
* probes. `walkLogRange` caps concurrency at
|
|
433
|
+
* {@link MAX_PARALLEL_LOG_READS} so a single call costs at most that
|
|
434
|
+
* many simultaneous GETs against the storage backend.
|
|
435
|
+
*
|
|
436
|
+
* Order invariant: results are returned in seq order regardless of
|
|
437
|
+
* resolution order. The read-side fold is order-sensitive (`U` then
|
|
438
|
+
* `D` on the same doc must apply in that order); callers may iterate
|
|
439
|
+
* the returned array as-is.
|
|
440
|
+
*
|
|
441
|
+
* Signal invariant: when the caller's `AbortSignal` fires, no further
|
|
442
|
+
* chunks dispatch. In-flight reads see the signal via the underlying
|
|
443
|
+
* `Storage.get` call.
|
|
444
|
+
*/
|
|
445
|
+
/**
|
|
446
|
+
* Like {@link readLogEntry}, but also surfaces `bytes` — the
|
|
447
|
+
* byteLength of the STORED log-object body exactly as it was GET back
|
|
448
|
+
* from storage (`got.body.byteLength`).
|
|
449
|
+
*
|
|
450
|
+
* The compactor uses this to sum the byte cost of the folded slice.
|
|
451
|
+
* The stored body byteLength IS what the writer PUT for each entry,
|
|
452
|
+
* so summing `got.body.byteLength` over the folded range yields the
|
|
453
|
+
* exact cost — no re-encode, no round-trip assumption (a re-encode
|
|
454
|
+
* of the parsed `LogEntry` could drift if key-order/whitespace ever
|
|
455
|
+
* diverged from what was PUT).
|
|
456
|
+
*
|
|
457
|
+
* Same error semantics as {@link readLogEntry}.
|
|
458
|
+
*/
|
|
459
|
+
const readLogEntryWithBytes = async (storage, key, opts) => {
|
|
460
|
+
const got = await storage.get(key, opts?.signal !== void 0 ? { signal: opts.signal } : void 0);
|
|
461
|
+
if (got === null) throw new BaerlyError("Internal", `log-walk: missing log entry at ${key}; protocol invariant violation`);
|
|
462
|
+
opts?.onBody?.(got.body.byteLength);
|
|
463
|
+
let entry;
|
|
464
|
+
try {
|
|
465
|
+
entry = decodeJsonBytes(got.body);
|
|
466
|
+
} catch (error) {
|
|
467
|
+
throw new BaerlyError("InvalidResponse", `log-walk: malformed log entry at ${key}`, { cause: error });
|
|
468
|
+
}
|
|
469
|
+
if (typeof entry !== "object" || entry === null || Array.isArray(entry)) throw new BaerlyError("InvalidResponse", `log-walk: log entry at ${key} is not a JSON object`);
|
|
470
|
+
return {
|
|
471
|
+
entry,
|
|
472
|
+
bytes: got.body.byteLength
|
|
473
|
+
};
|
|
474
|
+
};
|
|
475
|
+
/**
|
|
476
|
+
* Walk `[fromSeq, toSeqExclusive)` of `${logPrefix}/log/<seq>.json`
|
|
477
|
+
* in chunks of {@link MAX_PARALLEL_LOG_READS} concurrent GETs.
|
|
478
|
+
* Returns the materialised entries in seq order.
|
|
479
|
+
*
|
|
480
|
+
* Retention precondition: derive `fromSeq` from a fresh `current.json`
|
|
481
|
+
* read and require `fromSeq >= current.log_seq_start`. The floor and
|
|
482
|
+
* starting sequence must come from that same manifest read. Entries below
|
|
483
|
+
* the floor may already be reclaimed; a sub-floor walk that reaches one of
|
|
484
|
+
* those holes throws `Internal` even when later live entries still exist.
|
|
485
|
+
* This storage-level helper intentionally accepts no manifest and cannot
|
|
486
|
+
* enforce the precondition for its caller.
|
|
487
|
+
*
|
|
488
|
+
* Empty range (`fromSeq >= toSeqExclusive`) returns `[]` and issues
|
|
489
|
+
* zero GETs.
|
|
490
|
+
*
|
|
491
|
+
* Same error semantics as {@link readLogEntry}: a missing entry
|
|
492
|
+
* throws `Internal`, a malformed body throws `InvalidResponse`.
|
|
493
|
+
*/
|
|
494
|
+
const walkLogRange = async (storage, logPrefix, fromSeq, toSeqExclusive, opts) => {
|
|
495
|
+
return (await walkLogRangeWithBytes(storage, logPrefix, fromSeq, toSeqExclusive, opts)).map((r) => r.entry);
|
|
496
|
+
};
|
|
497
|
+
/**
|
|
498
|
+
* Like {@link walkLogRange}, but each element also carries `bytes` —
|
|
499
|
+
* the STORED log-object body byteLength (see {@link readLogEntryWithBytes}).
|
|
500
|
+
* Same seq-order, empty-range, error, and bounded-parallelism
|
|
501
|
+
* ({@link MAX_PARALLEL_LOG_READS}) guarantees as {@link walkLogRange};
|
|
502
|
+
* this is the bytes-aware core `walkLogRange` is implemented on top of.
|
|
503
|
+
*
|
|
504
|
+
* The compactor consumes this so it gets BOTH the parsed entries (for
|
|
505
|
+
* the fold) AND the exact byte sum (for `mean_entry_bytes` stamping) from a
|
|
506
|
+
* single walk.
|
|
507
|
+
*/
|
|
508
|
+
const walkLogRangeWithBytes = async (storage, logPrefix, fromSeq, toSeqExclusive, opts) => {
|
|
509
|
+
if (fromSeq >= toSeqExclusive) return [];
|
|
510
|
+
const total = toSeqExclusive - fromSeq;
|
|
511
|
+
const out = Array.from({ length: total });
|
|
512
|
+
for (let chunkStart = 0; chunkStart < total; chunkStart += 16) {
|
|
513
|
+
opts?.signal?.throwIfAborted();
|
|
514
|
+
const chunkEnd = Math.min(chunkStart + 16, total);
|
|
515
|
+
const promises = [];
|
|
516
|
+
for (let i = chunkStart; i < chunkEnd; i++) {
|
|
517
|
+
const seq = fromSeq + i;
|
|
518
|
+
promises.push(readLogEntryWithBytes(storage, logObjectKey(logPrefix, seq), opts));
|
|
519
|
+
}
|
|
520
|
+
const results = await Promise.all(promises);
|
|
521
|
+
for (let i = 0; i < results.length; i++) out[chunkStart + i] = results[i];
|
|
522
|
+
}
|
|
523
|
+
return out;
|
|
524
|
+
};
|
|
525
|
+
/**
|
|
526
|
+
* Fold a sequence of `LogEntry` records onto a doc-id-keyed map,
|
|
527
|
+
* applying the protocol's per-doc-replace semantics:
|
|
528
|
+
*
|
|
529
|
+
* - `I` / `U`: when `entry.after !== undefined`, set
|
|
530
|
+
* `map.set(entry.doc_id, entry.after)`. Entries with `after ===
|
|
531
|
+
* undefined` (the partial-merge writer's future patch-only shape)
|
|
532
|
+
* are ignored — today's writer always emits `after`, so this is a
|
|
533
|
+
* forward-compat guard, not a live branch.
|
|
534
|
+
* - `D`: tombstone — `map.delete(entry.doc_id)`.
|
|
535
|
+
*
|
|
536
|
+
* Entries whose `collection` does not match `opts.collection`, or
|
|
537
|
+
* whose `doc_id` is `undefined`, are skipped.
|
|
538
|
+
*
|
|
539
|
+
* This is the canonical fold used by the read path (`query.ts`).
|
|
540
|
+
* Centralising it keeps the
|
|
541
|
+
* "straight `set` on I/U; tombstone on D" protocol invariant in one place.
|
|
542
|
+
*
|
|
543
|
+
* @see ../../../docs/spec/sync-protocol.md
|
|
544
|
+
*/
|
|
545
|
+
const foldLogEntriesOnto = (map, entries, opts) => {
|
|
546
|
+
const { collection } = opts;
|
|
547
|
+
for (const entry of entries) {
|
|
548
|
+
if (!isOwnCollection(entry.collection, collection)) continue;
|
|
549
|
+
if (entry.doc_id === void 0) continue;
|
|
550
|
+
switch (entry.op) {
|
|
551
|
+
case "I":
|
|
552
|
+
case "U":
|
|
553
|
+
if (entry.after === void 0) continue;
|
|
554
|
+
map.set(entry.doc_id, entry.after);
|
|
555
|
+
break;
|
|
556
|
+
case "D": map.delete(entry.doc_id);
|
|
557
|
+
}
|
|
558
|
+
}
|
|
559
|
+
};
|
|
560
|
+
// packages/server/src/log-tail.ts
|
|
561
|
+
/**
|
|
562
|
+
* Tolerant forward-probe for the true committed log tail. The strict
|
|
563
|
+
* `[log_seq_start, hint)` range is dense (a hole is corruption, owned
|
|
564
|
+
* by `walkLogRange`); this owns only the tolerant `[hint, ∞)` probe,
|
|
565
|
+
* where `hint` is a lower bound — the real tail may sit at or past it.
|
|
566
|
+
*/
|
|
567
|
+
/**
|
|
568
|
+
* The forward-probe cap for a read in the active invocation:
|
|
569
|
+
* `min(LOG_FORWARD_PROBE_CAP, ledger remaining on pool)`. Every read path
|
|
570
|
+
* that probes past `tail_hint` (collection reads, `/v1/since`) sizes its
|
|
571
|
+
* probe here, so a probe never plans more GETs than the request can
|
|
572
|
+
* issue, and running out is a capacity refusal rather than the runaway
|
|
573
|
+
* alarm. Without a ledger (or with one that never refuses, as on Node) the
|
|
574
|
+
* runaway cap applies.
|
|
575
|
+
*/
|
|
576
|
+
const forwardProbeCap = (pool = "internal") => {
|
|
577
|
+
const remaining = currentRequestLedger()?.remaining(pool) ?? 1e400;
|
|
578
|
+
return remaining < 1e5 ? {
|
|
579
|
+
slots: Math.max(0, remaining),
|
|
580
|
+
bound: "request"
|
|
581
|
+
} : {
|
|
582
|
+
slots: LOG_FORWARD_PROBE_CAP,
|
|
583
|
+
bound: "runaway"
|
|
584
|
+
};
|
|
585
|
+
};
|
|
586
|
+
/**
|
|
587
|
+
* A storage call refused before it was sent: the request ledger's
|
|
588
|
+
* `CapacityExceeded`, or a platform subrequest-limit refusal (both carry
|
|
589
|
+
* `cause.refused`). Nothing was read or changed by the refused call.
|
|
590
|
+
*/
|
|
591
|
+
const isStorageRefusal = (error) => error instanceof BaerlyError && error.cause?.refused === true;
|
|
592
|
+
/**
|
|
593
|
+
* Probe a bounded chunk of committed entries from `hint`. An occupied
|
|
594
|
+
* chunk certifies only that the tail is at or past its exclusive bound.
|
|
595
|
+
* Decode failures throw by default. With tolerant occupancy probing,
|
|
596
|
+
* malformed slots remain occupied, `complete` becomes false, and probing
|
|
597
|
+
* continues to the first missing slot or cap.
|
|
598
|
+
*
|
|
599
|
+
* With `stopOnRefusal`, a slot GET refused before it was sent (see
|
|
600
|
+
* {@link isStorageRefusal}) ends the chunk instead of throwing: an
|
|
601
|
+
* "at least" chunk whose `lowerBound` is the refused slot, carrying the
|
|
602
|
+
* entries read before it, so a caller delivering prefixes keeps them.
|
|
603
|
+
*/
|
|
604
|
+
const probeTailChunk = async (storage, logPrefix, hint, opts) => {
|
|
605
|
+
const cap = opts?.cap ?? 1e5;
|
|
606
|
+
const getOpts = opts?.signal !== void 0 ? { signal: opts.signal } : void 0;
|
|
607
|
+
const entries = [];
|
|
608
|
+
let complete = true;
|
|
609
|
+
for (let i = 0; i < cap; i++) {
|
|
610
|
+
const seq = hint + i;
|
|
611
|
+
const key = logObjectKey(logPrefix, seq);
|
|
612
|
+
let got;
|
|
613
|
+
try {
|
|
614
|
+
got = await storage.get(key, getOpts);
|
|
615
|
+
} catch (error) {
|
|
616
|
+
if (opts?.stopOnRefusal === true && isStorageRefusal(error)) return {
|
|
617
|
+
kind: "at-least",
|
|
618
|
+
lowerBound: seq,
|
|
619
|
+
entries,
|
|
620
|
+
complete
|
|
621
|
+
};
|
|
622
|
+
throw error;
|
|
623
|
+
}
|
|
624
|
+
if (got === null) return {
|
|
625
|
+
kind: "exact",
|
|
626
|
+
tail: seq,
|
|
627
|
+
entries,
|
|
628
|
+
complete
|
|
629
|
+
};
|
|
630
|
+
opts?.onBody?.(got.body.byteLength);
|
|
631
|
+
try {
|
|
632
|
+
entries.push(decodeJsonBytes(got.body));
|
|
633
|
+
} catch (error) {
|
|
634
|
+
if (opts?.tolerateMalformed === true) {
|
|
635
|
+
complete = false;
|
|
636
|
+
continue;
|
|
637
|
+
}
|
|
638
|
+
throw new BaerlyError("InvalidResponse", `probeTailChunk: malformed log entry at ${key}: ${error.message}`, { cause: error });
|
|
639
|
+
}
|
|
640
|
+
}
|
|
641
|
+
return {
|
|
642
|
+
kind: "at-least",
|
|
643
|
+
lowerBound: hint + cap,
|
|
644
|
+
entries,
|
|
645
|
+
complete
|
|
646
|
+
};
|
|
647
|
+
};
|
|
648
|
+
/**
|
|
649
|
+
* Discover the true committed tail and fold entries in `[hint, tail)`.
|
|
650
|
+
* `tail` is the first empty seq (>= hint); `entries` are the
|
|
651
|
+
* LogEntries in `[hint, tail)` in seq order.
|
|
652
|
+
*
|
|
653
|
+
* Retention precondition: derive `hint` from a fresh `current.json` read
|
|
654
|
+
* and require `hint >= current.log_seq_start`; the usual start is
|
|
655
|
+
* `Math.max(current.log_seq_start, current.tail_hint)`. The floor and hint
|
|
656
|
+
* must come from that same manifest read. Entries below the floor may
|
|
657
|
+
* already be reclaimed, and this probe interprets the first missing slot
|
|
658
|
+
* as the tail. A sub-floor hint may therefore report a false tail and omit
|
|
659
|
+
* later live entries. This storage-level helper intentionally accepts no
|
|
660
|
+
* manifest and cannot enforce the precondition for its caller.
|
|
661
|
+
*
|
|
662
|
+
* `cap` bounds the walk; exhausting it THROWS `Internal` (never silently
|
|
663
|
+
* truncates) — see the cap-exhaustion comment below.
|
|
664
|
+
*/
|
|
665
|
+
const probeTailFrom = async (storage, logPrefix, hint, opts) => {
|
|
666
|
+
const result = await probeTailChunk(storage, logPrefix, hint, opts);
|
|
667
|
+
if (result.kind === "exact") return {
|
|
668
|
+
tail: result.tail,
|
|
669
|
+
entries: result.entries
|
|
670
|
+
};
|
|
671
|
+
throw new BaerlyError("Internal", `probeTailFrom: forward probe exceeded ${opts?.cap ?? 1e5} from hint ${hint} on ${logPrefix}`);
|
|
672
|
+
};
|
|
673
|
+
/**
|
|
674
|
+
* {@link probeTailFrom} for a read, capped by {@link forwardProbeCap}. When
|
|
675
|
+
* the request ledger set the cap and every capped slot is occupied, the
|
|
676
|
+
* tail is past what this request can probe: throws `refusal()` (a whole
|
|
677
|
+
* `CapacityExceeded` answer) rather than the runaway alarm. `onBody` sees
|
|
678
|
+
* each stored body length before decode, as on {@link probeTailChunk}.
|
|
679
|
+
*
|
|
680
|
+
* @throws the `refusal()` error when the ledger cap is exhausted.
|
|
681
|
+
* @throws BaerlyError code="Internal" when {@link LOG_FORWARD_PROBE_CAP} is.
|
|
682
|
+
*/
|
|
683
|
+
const probeReadTail = async (storage, logPrefix, hint, opts) => {
|
|
684
|
+
const cap = forwardProbeCap(opts.pool);
|
|
685
|
+
const result = await probeTailChunk(storage, logPrefix, hint, {
|
|
686
|
+
cap: cap.slots,
|
|
687
|
+
...opts.onBody !== void 0 && { onBody: opts.onBody },
|
|
688
|
+
...opts.signal !== void 0 && { signal: opts.signal }
|
|
689
|
+
});
|
|
690
|
+
if (result.kind === "exact") return {
|
|
691
|
+
tail: result.tail,
|
|
692
|
+
entries: result.entries
|
|
693
|
+
};
|
|
694
|
+
if (cap.bound === "request") throw opts.refusal();
|
|
695
|
+
throw new BaerlyError("Internal", `probeReadTail: forward probe exceeded ${cap.slots} from hint ${hint} on ${logPrefix}`);
|
|
696
|
+
};
|
|
697
|
+
/**
|
|
698
|
+
* First empty log seq at/after `hint` — the slot a new commit creates —
|
|
699
|
+
* found by galloping search (`O(log gap)` GETs vs `probeTailFrom`'s
|
|
700
|
+
* `O(gap)`). Used by the writer's per-commit tail-find, where `tail_hint`
|
|
701
|
+
* can lag the true tail. Position only; no bodies.
|
|
702
|
+
*
|
|
703
|
+
* PRECONDITION: occupancy MUST be a dense prefix from `hint` (galloping
|
|
704
|
+
* assumes monotone occupied→empty; a hole ABOVE `hint` would be skipped
|
|
705
|
+
* and the gallop could return a tail past live entries). Contrast
|
|
706
|
+
* `probeTailFrom`, which stops at the first 404 and is hole-tolerant.
|
|
707
|
+
*/
|
|
708
|
+
const findLogTail = async (storage, logPrefix, hint, opts) => {
|
|
709
|
+
const getOpts = opts?.signal !== void 0 ? { signal: opts.signal } : void 0;
|
|
710
|
+
const exists = async (seq) => await storage.get(logObjectKey(logPrefix, seq), getOpts) !== null;
|
|
711
|
+
if (!await exists(hint)) return hint;
|
|
712
|
+
let lo = hint;
|
|
713
|
+
let step = 1;
|
|
714
|
+
let hi = hint + step;
|
|
715
|
+
while (await exists(hi)) {
|
|
716
|
+
lo = hi;
|
|
717
|
+
step *= 2;
|
|
718
|
+
hi = lo + step;
|
|
719
|
+
if (step > 1e5) throw new BaerlyError("Internal", `findLogTail: galloping probe exceeded ${LOG_FORWARD_PROBE_CAP} from hint ${hint} on ${logPrefix}`);
|
|
720
|
+
}
|
|
721
|
+
while (hi - lo > 1) {
|
|
722
|
+
const mid = lo + Math.floor((hi - lo) / 2);
|
|
723
|
+
if (await exists(mid)) lo = mid;
|
|
724
|
+
else hi = mid;
|
|
725
|
+
}
|
|
726
|
+
return hi;
|
|
727
|
+
};
|
|
728
|
+
// packages/server/src/collection-key.ts
|
|
729
|
+
/**
|
|
730
|
+
* Splits a `current.json` key (`<collectionPrefix>/current.json`) into the
|
|
731
|
+
* collection's key prefix and its trailing name segment. `compact()`,
|
|
732
|
+
* `runGc()`, `retireLogRange()` and the maintenance runner all take the
|
|
733
|
+
* key and derive these the same way.
|
|
734
|
+
*/
|
|
735
|
+
const collectionFromCurrentJsonKey = (currentJsonKey) => {
|
|
736
|
+
const prefix = currentJsonKey.slice(0, currentJsonKey.lastIndexOf("/"));
|
|
737
|
+
return {
|
|
738
|
+
prefix,
|
|
739
|
+
name: prefix.slice(prefix.lastIndexOf("/") + 1)
|
|
740
|
+
};
|
|
741
|
+
};
|
|
742
|
+
// packages/server/src/snapshot-projection.ts
|
|
743
|
+
/**
|
|
744
|
+
* Byte-exact projection of the snapshot a fold rebuilds, entry by entry,
|
|
745
|
+
* as the compactor encodes it. Shared by the growth-refusal check
|
|
746
|
+
* (`./capacity.ts`) and the compactor's bytes cut (`./compactor.ts`), so
|
|
747
|
+
* the two agree on where a fold can stop; a module of its own because the
|
|
748
|
+
* compactor cannot import `./capacity.ts` without a cycle through
|
|
749
|
+
* `./maintenance.ts`.
|
|
750
|
+
*/
|
|
751
|
+
/** Encoded size of one snapshot row: the `{ _id, body }` element the compactor writes. */
|
|
752
|
+
const rowBytes = (docId, body) => encodeJsonBytes({
|
|
753
|
+
_id: docId,
|
|
754
|
+
body
|
|
755
|
+
}).byteLength;
|
|
756
|
+
/** Separators between `rows` elements of the snapshot's `docs` array. */
|
|
757
|
+
const separators = (rows) => Math.max(rows - 1, 0);
|
|
758
|
+
/**
|
|
759
|
+
* Encoded size of an empty snapshot body for `collection` whose header
|
|
760
|
+
* records `max_seq`. Rows add their own bytes plus one separator between
|
|
761
|
+
* each pair, inside the `docs` array.
|
|
762
|
+
*/
|
|
763
|
+
const headerBytes = (collection, maxSeq) => encodeSnapshotBody({
|
|
764
|
+
schema_version: 1,
|
|
765
|
+
min_seq: 0,
|
|
766
|
+
max_seq: maxSeq,
|
|
767
|
+
collection,
|
|
768
|
+
docs: []
|
|
769
|
+
}).byteLength;
|
|
770
|
+
/**
|
|
771
|
+
* Project the snapshot a fold would build from `head`'s stored figures and
|
|
772
|
+
* its rows (`base`), one entry at a time, byte for byte as the compactor
|
|
773
|
+
* encodes it: each row, one separator between rows, and the header, whose
|
|
774
|
+
* `max_seq` is the fold's end. A stored snapshot's `max_seq` is
|
|
775
|
+
* `log_seq_start` (the compactor writes both from the same fold end); a
|
|
776
|
+
* never-folded collection (`snapshot_bytes === 0`) starts empty at 0.
|
|
777
|
+
*
|
|
778
|
+
* `bytes` keeps the stored header, so a growth check made now does not
|
|
779
|
+
* know the `max_seq` its fold will record; `CAPACITY_BYTES_MARGIN` covers
|
|
780
|
+
* that header growth. `bytesAt` is exact for a fold whose end is known.
|
|
781
|
+
*
|
|
782
|
+
* @internal — exported for `capacity.test.ts`.
|
|
783
|
+
*/
|
|
784
|
+
const projectSnapshot = (head, base, collection) => {
|
|
785
|
+
const overlay = /* @__PURE__ */ new Map();
|
|
786
|
+
const sizeOf = (docId) => {
|
|
787
|
+
const known = overlay.get(docId);
|
|
788
|
+
if (known !== void 0) return known ?? void 0;
|
|
789
|
+
const body = base.get(docId);
|
|
790
|
+
return body === void 0 ? void 0 : rowBytes(docId, body);
|
|
791
|
+
};
|
|
792
|
+
const folded = head.snapshot_bytes !== 0;
|
|
793
|
+
let header = headerBytes(collection, folded ? head.log_seq_start : 0);
|
|
794
|
+
let rows = head.snapshot_rows;
|
|
795
|
+
let rowSum = folded ? head.snapshot_bytes - header - separators(rows) : 0;
|
|
796
|
+
const sizeNow = () => header + rowSum + separators(rows);
|
|
797
|
+
let peakRows = rows;
|
|
798
|
+
let peakBytes = sizeNow();
|
|
799
|
+
return {
|
|
800
|
+
get rows() {
|
|
801
|
+
return rows;
|
|
802
|
+
},
|
|
803
|
+
get bytes() {
|
|
804
|
+
return sizeNow();
|
|
805
|
+
},
|
|
806
|
+
get peakRows() {
|
|
807
|
+
return peakRows;
|
|
808
|
+
},
|
|
809
|
+
get peakBytes() {
|
|
810
|
+
return peakBytes;
|
|
811
|
+
},
|
|
812
|
+
bytesAt(maxSeq) {
|
|
813
|
+
return headerBytes(collection, maxSeq) + rowSum + separators(rows);
|
|
814
|
+
},
|
|
815
|
+
addsRow(op, docId, after) {
|
|
816
|
+
return op !== "D" && after !== void 0 && sizeOf(docId) === void 0;
|
|
817
|
+
},
|
|
818
|
+
apply(op, docId, after) {
|
|
819
|
+
if (op !== "D" && after === void 0) return;
|
|
820
|
+
const before = sizeOf(docId);
|
|
821
|
+
if (op === "D" || after === void 0) {
|
|
822
|
+
if (before !== void 0) {
|
|
823
|
+
rows -= 1;
|
|
824
|
+
rowSum -= before;
|
|
825
|
+
}
|
|
826
|
+
overlay.set(docId, null);
|
|
827
|
+
return;
|
|
828
|
+
}
|
|
829
|
+
const next = rowBytes(docId, after);
|
|
830
|
+
if (before === void 0) rows += 1;
|
|
831
|
+
rowSum += next - (before ?? 0);
|
|
832
|
+
overlay.set(docId, next);
|
|
833
|
+
peakRows = Math.max(peakRows, rows);
|
|
834
|
+
peakBytes = Math.max(peakBytes, sizeNow());
|
|
835
|
+
},
|
|
836
|
+
settle(maxSeq) {
|
|
837
|
+
header = headerBytes(collection, maxSeq);
|
|
838
|
+
peakRows = rows;
|
|
839
|
+
peakBytes = sizeNow();
|
|
840
|
+
}
|
|
841
|
+
};
|
|
842
|
+
};
|
|
843
|
+
// packages/server/src/compactor.ts
|
|
844
|
+
/**
|
|
845
|
+
* Compactor: fold a prefix of the live log into a content-
|
|
846
|
+
* hashed snapshot file and CAS-advance `current.json` to swap the
|
|
847
|
+
* pointer.
|
|
848
|
+
*
|
|
849
|
+
* The hard correctness requirement is **atomic snapshot generation**:
|
|
850
|
+
* a compactor that crashes mid-write must not leave a corrupted body
|
|
851
|
+
* that readers consume as truth. The design: every snapshot's filename
|
|
852
|
+
* embeds the SHA-256 of its body. A crashed mid-PUT leaves a body that
|
|
853
|
+
* doesn't match its own filename hash, and readers reject it as
|
|
854
|
+
* "missing." The atomic moment is the CAS-swap of
|
|
855
|
+
* `current.json.snapshot`, which is a single conditional PUT.
|
|
856
|
+
*
|
|
857
|
+
* Order of operations: PUT snapshot body → CAS-advance `current.json`.
|
|
858
|
+
* A crash before the swap leaves an orphan snapshot file; the swap
|
|
859
|
+
* succeeds iff our captured ETag still matches.
|
|
860
|
+
*
|
|
861
|
+
* Why level-prefixed chunked snapshots over the alternatives: a
|
|
862
|
+
* single monolithic snapshot (every compaction rewrites one well-
|
|
863
|
+
* known key) makes partial writes catastrophic and serializes every
|
|
864
|
+
* writer on one key. WAL-checkpointing in the rqlite / Raft tradition
|
|
865
|
+
* requires a consensus layer baerly-storage doesn't have. The Litestream-
|
|
866
|
+
* style multi-level scheme — small fixed number of levels, chunked
|
|
867
|
+
* files keyed by sequence range — keeps random GETs cheap on
|
|
868
|
+
* S3-compatible storage and avoids LIST. Current ship is single-
|
|
869
|
+
* level at L9 (one snapshot replaces the prior; no multi-level merge
|
|
870
|
+
* yet); the key format is forward-compatible with future L0..L9
|
|
871
|
+
* rolling merges without a wire change.
|
|
872
|
+
*
|
|
873
|
+
* @see ../../../docs/spec/sync-protocol.md
|
|
874
|
+
*/
|
|
875
|
+
const DEFAULT_MAX_PER_RUN = Number.MAX_SAFE_INTEGER;
|
|
876
|
+
const DEFAULT_MIN_TO_COMPACT = 100;
|
|
877
|
+
const APPLICATION_JSON = "application/json";
|
|
878
|
+
/**
|
|
879
|
+
* Fold a prefix of the live log into a new snapshot and CAS-advance
|
|
880
|
+
* `current.json`. Idempotent: a second run with no new writes is a
|
|
881
|
+
* no-op (below-min-threshold).
|
|
882
|
+
*
|
|
883
|
+
* Single-attempt: on CAS conflict we return
|
|
884
|
+
* `{written: false, skippedReason: "cas-lost"}` — the
|
|
885
|
+
* caller (the cron handler invoking `runScheduledMaintenance` from
|
|
886
|
+
* `./maintenance.ts`) decides whether to schedule another run. The
|
|
887
|
+
* orphan snapshot file just written will be swept by `runGc()`.
|
|
888
|
+
*
|
|
889
|
+
* @throws BaerlyError code="InvalidConfig" — `maxEntriesPerRun` or
|
|
890
|
+
* `knownTail` (the `InternalCompactOptions` seam) is not a
|
|
891
|
+
* non-negative integer, or `maxTailProbeGets` is not a positive
|
|
892
|
+
* integer. Checked before any I/O: a non-finite value would otherwise
|
|
893
|
+
* slip the range guards and write an unreadable `current.json`.
|
|
894
|
+
* @throws BaerlyError code="InvalidResponse" — `current.json` is
|
|
895
|
+
* present but malformed, or a snapshot body fails its schema /
|
|
896
|
+
* collection cross-check.
|
|
897
|
+
* @throws BaerlyError code="Internal" — protocol-invariant violation:
|
|
898
|
+
* a log entry missing inside `[log_seq_start, foldEnd)`, or the
|
|
899
|
+
* prior-snapshot pointer resolves to no body / a body whose hash
|
|
900
|
+
* doesn't match its filename.
|
|
901
|
+
*
|
|
902
|
+
* @example
|
|
903
|
+
* ```ts
|
|
904
|
+
* import { compact } from "@baerly/server/_internal/maintenance";
|
|
905
|
+
*
|
|
906
|
+
* const res = await compact(
|
|
907
|
+
* { storage, currentJsonKey: "app/x/tenant/t/manifests/tickets/current.json" },
|
|
908
|
+
* { minEntriesToCompact: 100 },
|
|
909
|
+
* );
|
|
910
|
+
* if (res.written) console.log("folded", res.entriesFolded, "entries");
|
|
911
|
+
* ```
|
|
912
|
+
*/
|
|
913
|
+
const compact = (args, options) => compactInternal(args, options);
|
|
914
|
+
/**
|
|
915
|
+
* {@link compact}, typed to return the {@link InternalCompactResult}
|
|
916
|
+
* snapshot keys. Tests and in-repo tooling reach it via the
|
|
917
|
+
* `@baerly/server/_internal/testing` subpath.
|
|
918
|
+
*
|
|
919
|
+
* @internal
|
|
920
|
+
*/
|
|
921
|
+
const compactInternal = async (args, options = {}) => {
|
|
922
|
+
const { storage, currentJsonKey } = args;
|
|
923
|
+
const internal = options;
|
|
924
|
+
const maxPerRun = internal.maxEntriesPerRun ?? DEFAULT_MAX_PER_RUN;
|
|
925
|
+
const maxTailProbeGets = internal.maxTailProbeGets;
|
|
926
|
+
const minToCompact = options.minEntriesToCompact ?? DEFAULT_MIN_TO_COMPACT;
|
|
927
|
+
const ceilingBytes = internal.ceilingBytes ?? Number.POSITIVE_INFINITY;
|
|
928
|
+
const ceilingEntries = internal.ceilingEntries ?? Number.POSITIVE_INFINITY;
|
|
929
|
+
const { prefix: collectionPrefix, name: collectionName } = collectionFromCurrentJsonKey(currentJsonKey);
|
|
930
|
+
const requireSeqOption = (name, value) => requireIntegerOption("compact", collectionName, name, value, 0);
|
|
931
|
+
requireSeqOption("maxEntriesPerRun", maxPerRun);
|
|
932
|
+
requireSeqOption("knownTail", internal.knownTail ?? 0);
|
|
933
|
+
if (maxTailProbeGets !== void 0) requireIntegerOption("compact", collectionName, "maxTailProbeGets", maxTailProbeGets, 1);
|
|
934
|
+
const read = await readCurrentJson(storage, currentJsonKey, options.signal !== void 0 ? { signal: options.signal } : void 0);
|
|
935
|
+
if (read === null) return {
|
|
936
|
+
written: false,
|
|
937
|
+
skippedReason: "current-json-missing",
|
|
938
|
+
previousSnapshotKey: null,
|
|
939
|
+
logSeqStartBefore: 0,
|
|
940
|
+
logSeqStartAfter: 0,
|
|
941
|
+
entriesFolded: 0
|
|
942
|
+
};
|
|
943
|
+
const current = read.json;
|
|
944
|
+
const baseEtag = read.etag;
|
|
945
|
+
const logSeqStartBefore = logSeqStartOf(current);
|
|
946
|
+
const probeFloor = Math.max(logSeqStartBefore, current.tail_hint, internal.knownTail ?? 0);
|
|
947
|
+
let probe;
|
|
948
|
+
if (maxTailProbeGets === void 0) probe = {
|
|
949
|
+
kind: "exact",
|
|
950
|
+
...await probeTailFrom(storage, collectionPrefix, probeFloor, { ...options.signal !== void 0 && { signal: options.signal } }),
|
|
951
|
+
complete: true
|
|
952
|
+
};
|
|
953
|
+
else {
|
|
954
|
+
const foldReserve = (current.snapshot === null ? 0 : 1) + maxPerRun + 2;
|
|
955
|
+
const requestsLeft = getCurrentContext()?.ledger?.storageRemaining() ?? 1e400;
|
|
956
|
+
probe = await probeTailChunk(storage, collectionPrefix, probeFloor, {
|
|
957
|
+
...options.signal !== void 0 && { signal: options.signal },
|
|
958
|
+
cap: Math.max(0, Math.min(maxTailProbeGets, requestsLeft - foldReserve))
|
|
959
|
+
});
|
|
960
|
+
}
|
|
961
|
+
const tailIsExact = probe.kind === "exact";
|
|
962
|
+
const discoveredTail = probe.kind === "exact" ? probe.tail : probe.lowerBound;
|
|
963
|
+
const nextSeq = discoveredTail;
|
|
964
|
+
const available = nextSeq - logSeqStartBefore;
|
|
965
|
+
if (available < minToCompact) {
|
|
966
|
+
if (!tailIsExact && discoveredTail <= current.tail_hint) return {
|
|
967
|
+
written: false,
|
|
968
|
+
skippedReason: "probe-budget-checkpointed",
|
|
969
|
+
previousSnapshotKey: current.snapshot,
|
|
970
|
+
logSeqStartBefore,
|
|
971
|
+
logSeqStartAfter: logSeqStartBefore,
|
|
972
|
+
entriesFolded: 0
|
|
973
|
+
};
|
|
974
|
+
if (!tailIsExact) {
|
|
975
|
+
const checkpoint = {
|
|
976
|
+
...current,
|
|
977
|
+
tail_hint: Math.max(current.tail_hint, discoveredTail)
|
|
978
|
+
};
|
|
979
|
+
assertCurrentJsonTransition(current, checkpoint, currentJsonKey);
|
|
980
|
+
const checkpointBody = encodeJsonBytes(checkpoint);
|
|
981
|
+
const checkpointCasOpts = {
|
|
982
|
+
ifMatch: baseEtag,
|
|
983
|
+
contentType: APPLICATION_JSON,
|
|
984
|
+
...options.signal !== void 0 && { signal: options.signal }
|
|
985
|
+
};
|
|
986
|
+
try {
|
|
987
|
+
await storage.put(currentJsonKey, checkpointBody, checkpointCasOpts);
|
|
988
|
+
} catch (error) {
|
|
989
|
+
if (isWriteConflict(error)) {
|
|
990
|
+
ctxMetrics().counter("db.compaction.cas_lost_total", 1, { collection: collectionName });
|
|
991
|
+
return {
|
|
992
|
+
written: false,
|
|
993
|
+
skippedReason: "cas-lost",
|
|
994
|
+
previousSnapshotKey: current.snapshot,
|
|
995
|
+
logSeqStartBefore,
|
|
996
|
+
logSeqStartAfter: logSeqStartBefore,
|
|
997
|
+
entriesFolded: 0
|
|
998
|
+
};
|
|
999
|
+
}
|
|
1000
|
+
throw error;
|
|
1001
|
+
}
|
|
1002
|
+
return {
|
|
1003
|
+
written: false,
|
|
1004
|
+
skippedReason: "probe-budget-checkpointed",
|
|
1005
|
+
previousSnapshotKey: current.snapshot,
|
|
1006
|
+
logSeqStartBefore,
|
|
1007
|
+
logSeqStartAfter: logSeqStartBefore,
|
|
1008
|
+
entriesFolded: 0
|
|
1009
|
+
};
|
|
1010
|
+
}
|
|
1011
|
+
if (available > 0) ctxMetrics().counter("db.compaction.below_min_total", 1, { collection: collectionName });
|
|
1012
|
+
return {
|
|
1013
|
+
written: false,
|
|
1014
|
+
skippedReason: "below-min-threshold",
|
|
1015
|
+
previousSnapshotKey: current.snapshot,
|
|
1016
|
+
logSeqStartBefore,
|
|
1017
|
+
logSeqStartAfter: logSeqStartBefore,
|
|
1018
|
+
entriesFolded: 0
|
|
1019
|
+
};
|
|
1020
|
+
}
|
|
1021
|
+
let foldEnd = Math.min(nextSeq, logSeqStartBefore + maxPerRun);
|
|
1022
|
+
const base = current.snapshot === null ? /* @__PURE__ */ new Map() : await loadSnapshotAsMap(storage, current.snapshot, collectionName, options.signal);
|
|
1023
|
+
const fetched = await walkLogRangeWithBytes(storage, collectionPrefix, logSeqStartBefore, foldEnd, { signal: options.signal });
|
|
1024
|
+
const own = (entry) => isOwnCollection(entry.collection, collectionName) && entry.doc_id !== void 0;
|
|
1025
|
+
let applied = fetched.length;
|
|
1026
|
+
let rowsStopped = false;
|
|
1027
|
+
if (ceilingBytes !== Number.POSITIVE_INFINITY || ceilingEntries !== Number.POSITIVE_INFINITY) {
|
|
1028
|
+
const projection = projectSnapshot({
|
|
1029
|
+
...current,
|
|
1030
|
+
snapshot_rows: base.size
|
|
1031
|
+
}, base, collectionName);
|
|
1032
|
+
let rowsEnd = 0;
|
|
1033
|
+
let fits = 0;
|
|
1034
|
+
for (const { entry } of fetched) {
|
|
1035
|
+
if (own(entry)) {
|
|
1036
|
+
if (projection.addsRow(entry.op, entry.doc_id, entry.after) && !(projection.rows < ceilingEntries)) {
|
|
1037
|
+
rowsStopped = true;
|
|
1038
|
+
break;
|
|
1039
|
+
}
|
|
1040
|
+
projection.apply(entry.op, entry.doc_id, entry.after);
|
|
1041
|
+
}
|
|
1042
|
+
rowsEnd++;
|
|
1043
|
+
if (projection.bytesAt(logSeqStartBefore + rowsEnd) <= ceilingBytes) fits = rowsEnd;
|
|
1044
|
+
}
|
|
1045
|
+
applied = fits;
|
|
1046
|
+
if (applied === 0 && fetched.length > 0) {
|
|
1047
|
+
const byRows = rowsStopped && rowsEnd === 0;
|
|
1048
|
+
return {
|
|
1049
|
+
written: false,
|
|
1050
|
+
skippedReason: "deferred",
|
|
1051
|
+
deferred: true,
|
|
1052
|
+
deferral: {
|
|
1053
|
+
dimension: byRows ? "rows" : "bytes",
|
|
1054
|
+
snapshotBytes: byRows ? current.snapshot_bytes : projection.bytesAt(logSeqStartBefore + rowsEnd),
|
|
1055
|
+
snapshotRows: byRows ? base.size : projection.rows
|
|
1056
|
+
},
|
|
1057
|
+
previousSnapshotKey: current.snapshot,
|
|
1058
|
+
logSeqStartBefore,
|
|
1059
|
+
logSeqStartAfter: logSeqStartBefore,
|
|
1060
|
+
entriesFolded: 0
|
|
1061
|
+
};
|
|
1062
|
+
}
|
|
1063
|
+
}
|
|
1064
|
+
for (const { entry } of fetched.slice(0, applied)) {
|
|
1065
|
+
if (!own(entry)) continue;
|
|
1066
|
+
switch (entry.op) {
|
|
1067
|
+
case "I":
|
|
1068
|
+
case "U":
|
|
1069
|
+
if (entry.after !== void 0) base.set(entry.doc_id, entry.after);
|
|
1070
|
+
break;
|
|
1071
|
+
case "D": base.delete(entry.doc_id);
|
|
1072
|
+
}
|
|
1073
|
+
}
|
|
1074
|
+
foldEnd = logSeqStartBefore + applied;
|
|
1075
|
+
const foldedSliceBytes = fetched.slice(0, applied).reduce((sum, f) => sum + f.bytes, 0);
|
|
1076
|
+
const sortedDocs = Array.from(base.entries()).toSorted(([a], [b]) => {
|
|
1077
|
+
if (a < b) return -1;
|
|
1078
|
+
if (a > b) return 1;
|
|
1079
|
+
return 0;
|
|
1080
|
+
}).map(([id, body]) => ({
|
|
1081
|
+
_id: id,
|
|
1082
|
+
body
|
|
1083
|
+
}));
|
|
1084
|
+
const bodyBytes = encodeSnapshotBody({
|
|
1085
|
+
schema_version: 1,
|
|
1086
|
+
min_seq: 0,
|
|
1087
|
+
max_seq: foldEnd,
|
|
1088
|
+
collection: collectionName,
|
|
1089
|
+
docs: sortedDocs
|
|
1090
|
+
});
|
|
1091
|
+
const bytesFit = bodyBytes.byteLength <= ceilingBytes;
|
|
1092
|
+
if (!(bytesFit && base.size <= ceilingEntries)) return {
|
|
1093
|
+
written: false,
|
|
1094
|
+
skippedReason: "deferred",
|
|
1095
|
+
deferred: true,
|
|
1096
|
+
deferral: {
|
|
1097
|
+
dimension: bytesFit ? "rows" : "bytes",
|
|
1098
|
+
snapshotBytes: bodyBytes.byteLength,
|
|
1099
|
+
snapshotRows: base.size
|
|
1100
|
+
},
|
|
1101
|
+
previousSnapshotKey: current.snapshot,
|
|
1102
|
+
logSeqStartBefore,
|
|
1103
|
+
logSeqStartAfter: logSeqStartBefore,
|
|
1104
|
+
entriesFolded: 0
|
|
1105
|
+
};
|
|
1106
|
+
const sha256 = await snapshotHash(bodyBytes);
|
|
1107
|
+
const newKey = snapshotKey(collectionPrefix, 0, foldEnd, sha256);
|
|
1108
|
+
const putOpts = {
|
|
1109
|
+
contentType: APPLICATION_JSON,
|
|
1110
|
+
...options.signal !== void 0 && { signal: options.signal }
|
|
1111
|
+
};
|
|
1112
|
+
await storage.put(newKey, bodyBytes, putOpts);
|
|
1113
|
+
const entriesFolded = foldEnd - logSeqStartBefore;
|
|
1114
|
+
const next = {
|
|
1115
|
+
...current,
|
|
1116
|
+
snapshot: newKey,
|
|
1117
|
+
log_seq_start: foldEnd,
|
|
1118
|
+
tail_hint: Math.max(current.tail_hint, discoveredTail),
|
|
1119
|
+
snapshot_bytes: bodyBytes.byteLength,
|
|
1120
|
+
snapshot_rows: base.size,
|
|
1121
|
+
mean_entry_bytes: entriesFolded > 0 ? Math.round(foldedSliceBytes / entriesFolded) : current.mean_entry_bytes ?? 0
|
|
1122
|
+
};
|
|
1123
|
+
assertCurrentJsonTransition(current, next, currentJsonKey);
|
|
1124
|
+
const nextBody = encodeJsonBytes(next);
|
|
1125
|
+
const casOpts = {
|
|
1126
|
+
ifMatch: baseEtag,
|
|
1127
|
+
contentType: APPLICATION_JSON,
|
|
1128
|
+
...options.signal !== void 0 && { signal: options.signal }
|
|
1129
|
+
};
|
|
1130
|
+
try {
|
|
1131
|
+
await storage.put(currentJsonKey, nextBody, casOpts);
|
|
1132
|
+
} catch (error) {
|
|
1133
|
+
if (isWriteConflict(error)) {
|
|
1134
|
+
ctxMetrics().counter("db.compaction.cas_lost_total", 1, { collection: collectionName });
|
|
1135
|
+
return {
|
|
1136
|
+
written: false,
|
|
1137
|
+
skippedReason: "cas-lost",
|
|
1138
|
+
previousSnapshotKey: current.snapshot,
|
|
1139
|
+
newSnapshotKey: newKey,
|
|
1140
|
+
logSeqStartBefore,
|
|
1141
|
+
logSeqStartAfter: logSeqStartBefore,
|
|
1142
|
+
entriesFolded: foldEnd - logSeqStartBefore
|
|
1143
|
+
};
|
|
1144
|
+
}
|
|
1145
|
+
throw error;
|
|
1146
|
+
}
|
|
1147
|
+
const metrics = ctxMetrics();
|
|
1148
|
+
metrics.histogram("db.compact.entries_folded", entriesFolded, { collection: collectionName });
|
|
1149
|
+
if (tailIsExact) metrics.gauge("db.manifest.lag_window_depth", discoveredTail - foldEnd, { collection: collectionName });
|
|
1150
|
+
return {
|
|
1151
|
+
written: true,
|
|
1152
|
+
previousSnapshotKey: current.snapshot,
|
|
1153
|
+
newSnapshotKey: newKey,
|
|
1154
|
+
logSeqStartBefore,
|
|
1155
|
+
logSeqStartAfter: foldEnd,
|
|
1156
|
+
entriesFolded
|
|
1157
|
+
};
|
|
1158
|
+
};
|
|
1159
|
+
// packages/server/src/gc.ts
|
|
1160
|
+
/**
|
|
1161
|
+
* GC mark + sweep.
|
|
1162
|
+
*
|
|
1163
|
+
* `runGc` is a single-pass garbage collector that:
|
|
1164
|
+
* 1. Reads `current.json` (and bootstraps `gc/pending.json` on first
|
|
1165
|
+
* run).
|
|
1166
|
+
* 2. Marks new orphan candidates by LISTing the snapshot prefix and
|
|
1167
|
+
* classifying each key.
|
|
1168
|
+
* 3. Rescues candidates proven live, then sweeps due candidates that
|
|
1169
|
+
* are safe to classify.
|
|
1170
|
+
* 4. CAS-writes the updated `gc/pending.json`.
|
|
1171
|
+
*
|
|
1172
|
+
* Two-phase by design: each mark sits in `gc/pending.json` for a grace
|
|
1173
|
+
* period (default 7 days, see {@link GC_GRACE_PERIOD_MILLIS}) before
|
|
1174
|
+
* sweep may delete it. The grace bounds the worst plausible writer-retry
|
|
1175
|
+
* window — a paused-process writer that resumes hours later still finds
|
|
1176
|
+
* its idempotency anchor on the bucket. Sweep can also resolve a
|
|
1177
|
+
* candidate OUT of the ledger without deleting it, when a generation or
|
|
1178
|
+
* liveness recheck fails.
|
|
1179
|
+
*
|
|
1180
|
+
* **A pass is bounded by the grace it relies on.** Sweep DELETEs go out
|
|
1181
|
+
* in batches of {@link GC_SWEEP_DELETE_BATCH_KEYS}. Before each batch,
|
|
1182
|
+
* a pass whose sweep-gate `current.json` read is older than
|
|
1183
|
+
* {@link GC_PASS_GRACE_FRACTION} of the grace issues no further DELETEs;
|
|
1184
|
+
* the unissued candidates stay pending, still due, for a later pass.
|
|
1185
|
+
* That bounds how stale a DELETE's liveness proof can be (sync-protocol
|
|
1186
|
+
* invariant 14) without a lease or a scheduler.
|
|
1187
|
+
*
|
|
1188
|
+
* Stale log objects are reclaimed by a sequence window rather than a
|
|
1189
|
+
* timed mark-and-sweep. See `log-retention.ts` for the computed-range
|
|
1190
|
+
* deletion path.
|
|
1191
|
+
*
|
|
1192
|
+
* Unbounded by default — the run marks and sweeps the entire eligible
|
|
1193
|
+
* set in one pass. Callers on a per-invocation request limit (Cloudflare
|
|
1194
|
+
* Workers) opt INTO caps via the `CLOUDFLARE_FREE_TIER` /
|
|
1195
|
+
* `CLOUDFLARE_PAID_TIER` profiles' mark and sweep knobs
|
|
1196
|
+
* (`InternalRunGcOptions`, not on the public `RunGcOptions`); the
|
|
1197
|
+
* per-pass worst cases are on `CLOUDFLARE_FREE_TIER`.
|
|
1198
|
+
*
|
|
1199
|
+
* One category of orphan:
|
|
1200
|
+
* - `orphan-snapshot`: a canonical
|
|
1201
|
+
* `<collectionPrefix>/snapshot/L9/...` key not equal to
|
|
1202
|
+
* `current.snapshot`. Each compactor run replaces the pointer; the
|
|
1203
|
+
* prior file becomes unreferenced. Discovery is scoped to this
|
|
1204
|
+
* binary's owned `snapshot/L9/` namespace. Future L0-L8 layouts
|
|
1205
|
+
* stay opaque to this binary and do not consume the bounded mark
|
|
1206
|
+
* window. Opaque L9 keys are ignored during mark and evicted from
|
|
1207
|
+
* legacy ledgers without a DELETE; no current writer emits one.
|
|
1208
|
+
*
|
|
1209
|
+
* **Mark window rule.** Every pass LISTs `snapshot/L9/` from the
|
|
1210
|
+
* lexicographic start — no persisted cursor, so no orphan can sit
|
|
1211
|
+
* behind a position the scan never revisits (a restore that deletes the
|
|
1212
|
+
* ledger, a stale-generation drop, or a lost CAS simply re-marks on the
|
|
1213
|
+
* next pass). The window is `maxMarks` plus every key the pass will
|
|
1214
|
+
* certainly skip: the snapshot keys already in `gc/pending.json` and the
|
|
1215
|
+
* one live `current.snapshot`. The loop stops after `maxMarks` NEW
|
|
1216
|
+
* marks. Without the widening, older keys sort first and a cohort
|
|
1217
|
+
* waiting out its 7-day grace fills a `maxMarks`-key window, capping
|
|
1218
|
+
* marking at `maxMarks` per grace while folds keep orphaning snapshots.
|
|
1219
|
+
* The widening is capped at {@link GC_MARK_LIST_PAGE_KEYS} (one full
|
|
1220
|
+
* provider page) and never shrinks the window below `maxMarks`, so it
|
|
1221
|
+
* adds no LIST page request beyond what `maxMarks` alone costs: one
|
|
1222
|
+
* request per 1000 keys, more only if the provider truncates a page
|
|
1223
|
+
* short. Marking only adds ledger entries; deletion authority stays with
|
|
1224
|
+
* the sweep gate below.
|
|
1225
|
+
*
|
|
1226
|
+
* Progress: within the protocol-written L9 keyspace at most ONE key is
|
|
1227
|
+
* permanently unmarkable (the live `current.snapshot`), so for any
|
|
1228
|
+
* `maxMarks >= 1` a pass whose ledger has room marks an unpending orphan
|
|
1229
|
+
* if one exists in the window. Opaque L9 keys (non-canonical names) are
|
|
1230
|
+
* skipped but still occupy window slots; no current writer emits one.
|
|
1231
|
+
*
|
|
1232
|
+
* Ceiling: `GC_MAX_PENDING_CANDIDATES` (1000) bounds the in-flight
|
|
1233
|
+
* cohort, so a collection reclaims at most ~1000 replaced snapshots per
|
|
1234
|
+
* 7-day grace — about 143 folds/day. At the cap the window holds only
|
|
1235
|
+
* pending keys and `mergeGcPending` drops appends past the cap, so
|
|
1236
|
+
* marking stops until the oldest cohort comes due and is swept; a
|
|
1237
|
+
* collection folding faster than that accumulates the excess.
|
|
1238
|
+
*
|
|
1239
|
+
* **`content/` is deliberately NOT a category.** Legacy
|
|
1240
|
+
* `<collectionPrefix>/content/<sha>.json` side objects — written by
|
|
1241
|
+
* v0.6.0, and still written by a v0.6.0 node during a mixed rollout —
|
|
1242
|
+
* are inert: no current writer creates one, no reader opens one. GC
|
|
1243
|
+
* never LISTs, reads, or deletes under that prefix, so they cost storage
|
|
1244
|
+
* and nothing else, and an operator who wants the bytes back deletes the
|
|
1245
|
+
* prefix directly (`docs/guide/backups.md`). An `orphan-content` entry
|
|
1246
|
+
* found in a legacy ledger is EVICTED, not swept — see the sweep gate's
|
|
1247
|
+
* legacy arm.
|
|
1248
|
+
*
|
|
1249
|
+
* CAS-lost on `gc/pending.json` is non-fatal: the DELETEs already
|
|
1250
|
+
* issued are durable, so we return a successful result and the next
|
|
1251
|
+
* pass will pick up any work this pass lost.
|
|
1252
|
+
*
|
|
1253
|
+
* **Not fault-isolated, by design.** Every storage call in Steps 1-5 —
|
|
1254
|
+
* the `current.json`/`gc/pending.json` reads, the mark-phase `LIST`s,
|
|
1255
|
+
* the sweep DELETEs — is uncaught within `runGc` itself; a throw from
|
|
1256
|
+
* any of them aborts the whole pass. That's a deliberate fail-safe, not
|
|
1257
|
+
* a gap to close with a `try`/`catch` around one call: Steps 3-4 re-LIST
|
|
1258
|
+
* from scratch every pass rather than trusting partial progress, sweep
|
|
1259
|
+
* DELETEs are idempotent, and the pending-ledger CAS in Step 5 hasn't
|
|
1260
|
+
* happened yet when an earlier step throws — so an abort mid-pass loses
|
|
1261
|
+
* no durable state and deletes nothing it shouldn't. This is fuzz-tested
|
|
1262
|
+
* directly: `maintenance-crash-fuzz.test.ts` aborts the K-th storage op
|
|
1263
|
+
* inside `runGc` and asserts the reader still returns every live row.
|
|
1264
|
+
*/
|
|
1265
|
+
const DEFAULT_MAX_MARKS = Number.MAX_SAFE_INTEGER;
|
|
1266
|
+
const DEFAULT_MAX_SWEEPS = Number.MAX_SAFE_INTEGER;
|
|
1267
|
+
const zeroGcResult = () => ({
|
|
1268
|
+
marked: { orphan_snapshot: 0 },
|
|
1269
|
+
swept: 0,
|
|
1270
|
+
dropped: {
|
|
1271
|
+
stale_generation: 0,
|
|
1272
|
+
still_live: 0
|
|
1273
|
+
},
|
|
1274
|
+
pendingDepth: 0
|
|
1275
|
+
});
|
|
1276
|
+
/**
|
|
1277
|
+
* Single GC pass — mark new orphans, sweep due-elapsed candidates,
|
|
1278
|
+
* persist via CAS-update on `gc/pending.json`.
|
|
1279
|
+
*
|
|
1280
|
+
* Returns immediately if `current.json` is missing — there's nothing
|
|
1281
|
+
* to do until a writer has bootstrapped the collection.
|
|
1282
|
+
*
|
|
1283
|
+
* @example
|
|
1284
|
+
* ```ts
|
|
1285
|
+
* import { runGc } from "@baerly/server/_internal/maintenance";
|
|
1286
|
+
*
|
|
1287
|
+
* const r = await runGc({ storage, currentJsonKey });
|
|
1288
|
+
* console.log(`marked ${r.marked.orphan_snapshot} orphan snapshots, swept ${r.swept}`);
|
|
1289
|
+
* ```
|
|
1290
|
+
*/
|
|
1291
|
+
const runGc = async (args, options = {}) => {
|
|
1292
|
+
const { storage, currentJsonKey } = args;
|
|
1293
|
+
const internal = options;
|
|
1294
|
+
const grace = internal.graceMillis ?? 6048e5;
|
|
1295
|
+
const maxMarks = internal.maxMarksPerRun ?? DEFAULT_MAX_MARKS;
|
|
1296
|
+
const maxSweeps = internal.maxSweepsPerRun ?? DEFAULT_MAX_SWEEPS;
|
|
1297
|
+
const now = internal.now ?? (() => /* @__PURE__ */ new Date());
|
|
1298
|
+
const monotonicNow = internal.monotonicNow ?? (() => performance.now());
|
|
1299
|
+
/** Both clocks at one instant; see {@link elapsedSince}. */
|
|
1300
|
+
const stamp = () => ({
|
|
1301
|
+
wall: now().getTime(),
|
|
1302
|
+
mono: monotonicNow()
|
|
1303
|
+
});
|
|
1304
|
+
/** The larger of the two clocks' elapsed times, so neither can understate it. */
|
|
1305
|
+
const elapsedSince = (from) => Math.max(now().getTime() - from.wall, monotonicNow() - from.mono);
|
|
1306
|
+
const { prefix: collectionPrefix, name: collectionName } = collectionFromCurrentJsonKey(currentJsonKey);
|
|
1307
|
+
const pendingKey = gcPendingKey(collectionPrefix);
|
|
1308
|
+
const signal = options.signal;
|
|
1309
|
+
const signalOpts = signal !== void 0 ? { signal } : void 0;
|
|
1310
|
+
const currentReadAt = stamp();
|
|
1311
|
+
const cur = await readCurrentJson(storage, currentJsonKey, signalOpts);
|
|
1312
|
+
if (cur === null) return zeroGcResult();
|
|
1313
|
+
const current = cur.json;
|
|
1314
|
+
let pending = await readGcPending(storage, pendingKey, signalOpts);
|
|
1315
|
+
if (pending === null) {
|
|
1316
|
+
const initial = {
|
|
1317
|
+
schema_version: 1,
|
|
1318
|
+
candidates: [],
|
|
1319
|
+
last_swept_at: ""
|
|
1320
|
+
};
|
|
1321
|
+
try {
|
|
1322
|
+
pending = await createGcPending(storage, pendingKey, initial, signalOpts);
|
|
1323
|
+
} catch (error) {
|
|
1324
|
+
if (isWriteConflict(error)) {
|
|
1325
|
+
pending = await readGcPending(storage, pendingKey, signalOpts);
|
|
1326
|
+
if (pending === null) throw error;
|
|
1327
|
+
} else throw error;
|
|
1328
|
+
}
|
|
1329
|
+
}
|
|
1330
|
+
const known = new Set(pending.json.candidates.map((c) => c.key));
|
|
1331
|
+
const markGeneration = current.generation !== void 0 ? { generation: current.generation } : {};
|
|
1332
|
+
const newCandidates = [];
|
|
1333
|
+
let markedOrphanSnapshot = 0;
|
|
1334
|
+
const snapshotPrefix = `${collectionPrefix}/snapshot/L9/`;
|
|
1335
|
+
const pendingSnapshotKeys = pending.json.candidates.filter((c) => c.key.startsWith(snapshotPrefix)).length;
|
|
1336
|
+
for await (const entry of storage.list(snapshotPrefix, listWindow(markWindowKeys(maxMarks, pendingSnapshotKeys), void 0, signal))) {
|
|
1337
|
+
if (markedOrphanSnapshot >= maxMarks) break;
|
|
1338
|
+
if (entry.key === current.snapshot) continue;
|
|
1339
|
+
if (parseMaxSeqFromCanonicalSnapshotKey(entry.key, collectionPrefix) === null) continue;
|
|
1340
|
+
if (known.has(entry.key)) continue;
|
|
1341
|
+
newCandidates.push({
|
|
1342
|
+
key: entry.key,
|
|
1343
|
+
due_at: computeDueAt(now, grace),
|
|
1344
|
+
reason: "orphan-snapshot",
|
|
1345
|
+
...markGeneration
|
|
1346
|
+
});
|
|
1347
|
+
markedOrphanSnapshot++;
|
|
1348
|
+
}
|
|
1349
|
+
const nowMs = now().getTime();
|
|
1350
|
+
const sweepCandidates = [...pending.json.candidates, ...newCandidates];
|
|
1351
|
+
const hasDueSnapshot = sweepCandidates.some((candidate) => candidate.reason === "orphan-snapshot" && Date.parse(candidate.due_at) <= nowMs);
|
|
1352
|
+
const freshReadAt = hasDueSnapshot ? stamp() : currentReadAt;
|
|
1353
|
+
const freshCurrent = hasDueSnapshot ? await readCurrentJson(storage, currentJsonKey, signalOpts) : void 0;
|
|
1354
|
+
const fenceCurrent = freshCurrent?.json ?? current;
|
|
1355
|
+
const fenceReadAt = freshCurrent?.json !== void 0 ? freshReadAt : currentReadAt;
|
|
1356
|
+
const fenceGeneration = fenceCurrent.generation ?? "-";
|
|
1357
|
+
const fenceFloor = logSeqStartOf(fenceCurrent);
|
|
1358
|
+
const rescuedKeys = /* @__PURE__ */ new Set();
|
|
1359
|
+
const staleGenerationKeys = /* @__PURE__ */ new Set();
|
|
1360
|
+
const evictedKeys = /* @__PURE__ */ new Set();
|
|
1361
|
+
for (const candidate of sweepCandidates) {
|
|
1362
|
+
if (candidate.reason === "orphan-content") {
|
|
1363
|
+
evictedKeys.add(candidate.key);
|
|
1364
|
+
continue;
|
|
1365
|
+
}
|
|
1366
|
+
if (candidate.reason === "stale-log" && parseSeqFromCanonicalLogKey(candidate.key, collectionPrefix) === null) {
|
|
1367
|
+
evictedKeys.add(candidate.key);
|
|
1368
|
+
continue;
|
|
1369
|
+
}
|
|
1370
|
+
if (candidate.reason === "orphan-snapshot" && parseMaxSeqFromCanonicalSnapshotKey(candidate.key, collectionPrefix) === null) {
|
|
1371
|
+
evictedKeys.add(candidate.key);
|
|
1372
|
+
continue;
|
|
1373
|
+
}
|
|
1374
|
+
if ((candidate.generation ?? "-") !== fenceGeneration) {
|
|
1375
|
+
staleGenerationKeys.add(candidate.key);
|
|
1376
|
+
continue;
|
|
1377
|
+
}
|
|
1378
|
+
if (candidate.reason === "orphan-snapshot" && candidate.key === freshCurrent?.json.snapshot) {
|
|
1379
|
+
rescuedKeys.add(candidate.key);
|
|
1380
|
+
continue;
|
|
1381
|
+
}
|
|
1382
|
+
if (candidate.reason === "stale-log") {
|
|
1383
|
+
const seq = parseSeqFromCanonicalLogKey(candidate.key, collectionPrefix);
|
|
1384
|
+
if (seq !== null && seq >= fenceFloor) rescuedKeys.add(candidate.key);
|
|
1385
|
+
continue;
|
|
1386
|
+
}
|
|
1387
|
+
}
|
|
1388
|
+
const droppedKeys = /* @__PURE__ */ new Set([
|
|
1389
|
+
...staleGenerationKeys,
|
|
1390
|
+
...rescuedKeys,
|
|
1391
|
+
...evictedKeys
|
|
1392
|
+
]);
|
|
1393
|
+
const toSweep = [];
|
|
1394
|
+
const remaining = [];
|
|
1395
|
+
for (const cand of sweepCandidates) {
|
|
1396
|
+
if (droppedKeys.has(cand.key)) continue;
|
|
1397
|
+
if (toSweep.length < maxSweeps && Date.parse(cand.due_at) <= nowMs) {
|
|
1398
|
+
if (cand.reason === "orphan-snapshot") {
|
|
1399
|
+
const maxSeq = parseMaxSeqFromCanonicalSnapshotKey(cand.key, collectionPrefix);
|
|
1400
|
+
if (maxSeq === null || maxSeq >= (freshCurrent?.json.log_seq_start ?? 0)) {
|
|
1401
|
+
remaining.push(cand);
|
|
1402
|
+
continue;
|
|
1403
|
+
}
|
|
1404
|
+
}
|
|
1405
|
+
toSweep.push(cand);
|
|
1406
|
+
} else remaining.push(cand);
|
|
1407
|
+
}
|
|
1408
|
+
const sweepBudgetMillis = grace * GC_PASS_GRACE_FRACTION;
|
|
1409
|
+
const swept = [];
|
|
1410
|
+
for (let start = 0; start < toSweep.length; start += 100) {
|
|
1411
|
+
if (grace > 0 && elapsedSince(fenceReadAt) > sweepBudgetMillis) break;
|
|
1412
|
+
const batch = toSweep.slice(start, start + 100);
|
|
1413
|
+
await Promise.all(batch.map((c) => storage.delete(c.key, signalOpts)));
|
|
1414
|
+
swept.push(...batch);
|
|
1415
|
+
}
|
|
1416
|
+
const abandonedCount = toSweep.length - swept.length;
|
|
1417
|
+
const sweptKeys = /* @__PURE__ */ new Set([...swept.map((candidate) => candidate.key), ...droppedKeys]);
|
|
1418
|
+
const lastSweptAt = swept.length > 0 ? now().toISOString() : "";
|
|
1419
|
+
const markedSummary = { orphan_snapshot: markedOrphanSnapshot };
|
|
1420
|
+
let pendingDepth;
|
|
1421
|
+
try {
|
|
1422
|
+
pendingDepth = (await casUpdateGcPending(storage, pendingKey, (latest) => mergeGcPending(latest, {
|
|
1423
|
+
sweptKeys,
|
|
1424
|
+
newCandidates,
|
|
1425
|
+
lastSweptAt,
|
|
1426
|
+
maxCandidates: GC_MAX_PENDING_CANDIDATES
|
|
1427
|
+
}), signalOpts)).json.candidates.length;
|
|
1428
|
+
} catch (error) {
|
|
1429
|
+
if (isWriteConflict(error)) pendingDepth = remaining.length + abandonedCount;
|
|
1430
|
+
else throw error;
|
|
1431
|
+
}
|
|
1432
|
+
const labels = { collection: collectionName };
|
|
1433
|
+
const metrics = ctxMetrics();
|
|
1434
|
+
metrics.gauge("db.orphan.candidate_count", pendingDepth, labels);
|
|
1435
|
+
metrics.gauge("db.gc.entries_swept_per_second", swept.length, labels);
|
|
1436
|
+
if (swept.length > 0) {
|
|
1437
|
+
const byReason = /* @__PURE__ */ new Map();
|
|
1438
|
+
for (const c of swept) byReason.set(c.reason, (byReason.get(c.reason) ?? 0) + 1);
|
|
1439
|
+
for (const [reason, count] of byReason) metrics.counter("db.gc.swept_total", count, {
|
|
1440
|
+
collection: collectionName,
|
|
1441
|
+
reason
|
|
1442
|
+
});
|
|
1443
|
+
}
|
|
1444
|
+
if (staleGenerationKeys.size > 0) metrics.counter("db.gc.dropped_total", staleGenerationKeys.size, {
|
|
1445
|
+
collection: collectionName,
|
|
1446
|
+
cause: "stale-generation"
|
|
1447
|
+
});
|
|
1448
|
+
if (rescuedKeys.size > 0) metrics.counter("db.gc.dropped_total", rescuedKeys.size, {
|
|
1449
|
+
collection: collectionName,
|
|
1450
|
+
cause: "still-live"
|
|
1451
|
+
});
|
|
1452
|
+
return {
|
|
1453
|
+
marked: markedSummary,
|
|
1454
|
+
swept: swept.length,
|
|
1455
|
+
dropped: {
|
|
1456
|
+
stale_generation: staleGenerationKeys.size,
|
|
1457
|
+
still_live: rescuedKeys.size
|
|
1458
|
+
},
|
|
1459
|
+
pendingDepth
|
|
1460
|
+
};
|
|
1461
|
+
};
|
|
1462
|
+
/**
|
|
1463
|
+
* `Storage.list` options for one bounded rotation window: at most
|
|
1464
|
+
* `maxKeys` keys, resuming strictly after `cursor` when the ledger
|
|
1465
|
+
* carries one. `maxKeys` is a hard cross-page total on every adapter
|
|
1466
|
+
* (`docs/spec/storage-compatibility.md`), which is what makes
|
|
1467
|
+
* "yielded fewer than we asked for ⇒ end of keyspace" a sound wrap
|
|
1468
|
+
* test. `startAfter` is strict-greater on the key VALUE, so a cursor
|
|
1469
|
+
* naming a key this pass already deleted still resumes correctly —
|
|
1470
|
+
* never probe whether it still exists.
|
|
1471
|
+
*/
|
|
1472
|
+
const listWindow = (maxKeys, cursor, signal) => ({
|
|
1473
|
+
maxKeys,
|
|
1474
|
+
...cursor !== void 0 && { startAfter: cursor },
|
|
1475
|
+
...signal !== void 0 && { signal }
|
|
1476
|
+
});
|
|
1477
|
+
/**
|
|
1478
|
+
* `maxKeys` for the orphan-snapshot mark LIST: `maxMarks` plus every key
|
|
1479
|
+
* the pass is certain to skip without marking — the `pendingSnapshotKeys`
|
|
1480
|
+
* already in the ledger under `snapshot/L9/` and the one live
|
|
1481
|
+
* `current.snapshot`. Without the widening, a ledger cohort waiting out
|
|
1482
|
+
* its grace fills the lex-first window and marking stalls at `maxMarks`
|
|
1483
|
+
* per grace period.
|
|
1484
|
+
*
|
|
1485
|
+
* Capped at {@link GC_MARK_LIST_PAGE_KEYS} so the widening never adds a
|
|
1486
|
+
* full LIST page: a pass with `maxMarks` at or under one page fits one
|
|
1487
|
+
* page request unless the provider truncates short. The cap is never
|
|
1488
|
+
* below `maxMarks`, so a bounded pass scans at least what it always did.
|
|
1489
|
+
*/
|
|
1490
|
+
const markWindowKeys = (maxMarks, pendingSnapshotKeys) => Math.max(maxMarks, Math.min(maxMarks + pendingSnapshotKeys + 1, GC_MARK_LIST_PAGE_KEYS));
|
|
1491
|
+
/**
|
|
1492
|
+
* Parse the exact canonical `log/<seq>.json` key for this collection.
|
|
1493
|
+
* Returns `null` for another prefix, malformed or noncanonical decimal,
|
|
1494
|
+
* or a sequence outside JavaScript's safe-integer range.
|
|
1495
|
+
*/
|
|
1496
|
+
const parseSeqFromCanonicalLogKey = (key, collectionPrefix) => {
|
|
1497
|
+
const logPrefix = `${collectionPrefix}/log/`;
|
|
1498
|
+
if (!key.startsWith(logPrefix)) return null;
|
|
1499
|
+
const match = /^(\d+)\.json$/.exec(key.slice(logPrefix.length));
|
|
1500
|
+
if (match === null) return null;
|
|
1501
|
+
const seq = Number(match[1]);
|
|
1502
|
+
return Number.isSafeInteger(seq) && seq >= 0 && logObjectKey(collectionPrefix, seq) === key ? seq : null;
|
|
1503
|
+
};
|
|
1504
|
+
/**
|
|
1505
|
+
* Parse the exclusive `max_seq` from the exact key shape emitted by
|
|
1506
|
+
* `snapshotKey`. Unknown levels/layouts and invalid ranges stay opaque: GC
|
|
1507
|
+
* never deletes the object and never retains its candidate in the bounded
|
|
1508
|
+
* ledger.
|
|
1509
|
+
*/
|
|
1510
|
+
const parseMaxSeqFromCanonicalSnapshotKey = (key, collectionPrefix) => {
|
|
1511
|
+
const snapshotPrefix = `${collectionPrefix}/snapshot/L9/`;
|
|
1512
|
+
if (!key.startsWith(snapshotPrefix)) return null;
|
|
1513
|
+
const match = /^(\d{12})-(\d{12})-[0-9a-f]{64}\.json$/.exec(key.slice(snapshotPrefix.length));
|
|
1514
|
+
if (match === null) return null;
|
|
1515
|
+
const minSeq = Number(match[1]);
|
|
1516
|
+
const maxSeq = Number(match[2]);
|
|
1517
|
+
return minSeq <= maxSeq ? maxSeq : null;
|
|
1518
|
+
};
|
|
1519
|
+
/**
|
|
1520
|
+
* Anchor `due_at` on the MARK: `now() + graceMs`. Grace measures the
|
|
1521
|
+
* writer-retry window from when we judged a key dead, which is
|
|
1522
|
+
* unrelated to when the object was written.
|
|
1523
|
+
*
|
|
1524
|
+
* Never anchor on the object's own timestamp. Doing so made the
|
|
1525
|
+
* effective grace `max(0, graceMs − object age)` — zero past the
|
|
1526
|
+
* 7-day default, for exactly the old objects GC marks. It read a
|
|
1527
|
+
* `lastModified` that only the S3/GCS/R2 adapters populated, so the
|
|
1528
|
+
* suite's backends showed a full window and no test could see it.
|
|
1529
|
+
* `StorageListEntry` no longer carries a timestamp; `gc.test.ts`
|
|
1530
|
+
* still pins the behaviour against an entry that fakes one.
|
|
1531
|
+
*
|
|
1532
|
+
* Called per candidate, not hoisted per pass, so the local-clock
|
|
1533
|
+
* backends keep their exact previous horizon.
|
|
1534
|
+
*/
|
|
1535
|
+
const computeDueAt = (now, graceMs) => new Date(now().getTime() + graceMs).toISOString();
|
|
1536
|
+
// packages/server/src/log-retention.ts
|
|
1537
|
+
/**
|
|
1538
|
+
* Sequence-based log retention.
|
|
1539
|
+
*
|
|
1540
|
+
* Log keys are derivable, so retirement uses a half-open sequence range rather
|
|
1541
|
+
* than LIST-based discovery. This module computes the range and owns the
|
|
1542
|
+
* CAS-then-delete retirement pass. Every maintenance trigger runs it through
|
|
1543
|
+
* the shared `retireLogs` helper in `maintenance.ts`: `runScheduledMaintenance`
|
|
1544
|
+
* after its GC phase, and `runBoundedMaintenance` on the hard-GC early-return
|
|
1545
|
+
* path and as its final step.
|
|
1546
|
+
*/
|
|
1547
|
+
/** Compute the budgeted prefix of the currently retirable log range. */
|
|
1548
|
+
const computeRetirableRange = (current, opts) => {
|
|
1549
|
+
const window = opts?.window ?? 1024;
|
|
1550
|
+
const maxDeletes = opts?.maxDeletes ?? 20;
|
|
1551
|
+
const liveFloor = logSeqStartOf(current);
|
|
1552
|
+
const start = certifiedDeleteFloor(current);
|
|
1553
|
+
const boundary = Math.min(liveFloor - window, liveFloor);
|
|
1554
|
+
return {
|
|
1555
|
+
start,
|
|
1556
|
+
end: Math.max(start, Math.min(boundary, start + maxDeletes))
|
|
1557
|
+
};
|
|
1558
|
+
};
|
|
1559
|
+
/**
|
|
1560
|
+
* Delete a budgeted, computed slice of the stale log prefix and advance
|
|
1561
|
+
* `log_delete_floor` to match. Sequence-based: log keys are derivable, so this
|
|
1562
|
+
* never LISTs.
|
|
1563
|
+
*
|
|
1564
|
+
* **The authorized range is computed inside the CAS mutator, against the state
|
|
1565
|
+
* the CAS validates — do not hoist it out.** {@link casUpdateCurrentJson}
|
|
1566
|
+
* performs its own read and CASes against *that* etag, so a range computed from
|
|
1567
|
+
* an earlier read is a plan the CAS never validated. Computing it in the mutator
|
|
1568
|
+
* makes plan and validation atomic: whatever floor this call publishes is the
|
|
1569
|
+
* floor its own DELETEs are authorized by. If the fresh state yields an empty
|
|
1570
|
+
* range (a `restore --force` reseed lowered `log_seq_start` — the one writer
|
|
1571
|
+
* allowed to, `restore.ts:191-206`), the pass aborts with `WriteConflict` and zero
|
|
1572
|
+
* DELETEs rather than publishing a floor above the live one.
|
|
1573
|
+
*
|
|
1574
|
+
* **CAS before deleting, never after.** Every floor this function publishes
|
|
1575
|
+
* satisfies `end <= log_seq_start - window`, where `window` is the *effective*
|
|
1576
|
+
* window — {@link LOG_RETENTION_SEQ_WINDOW} by default, or `opts.window` when
|
|
1577
|
+
* a caller overrides it (via {@link computeRetirableRange}, which also clamps
|
|
1578
|
+
* a malformed stored floor per `docs/spec/sync-protocol.md` invariant 12).
|
|
1579
|
+
* That bound holds only at the default window: `opts.window` is a test seam
|
|
1580
|
+
* that can shrink or erase the folded entries the window keeps readable for
|
|
1581
|
+
* a windowed commit and steepen the retirement rate it limits (this module's
|
|
1582
|
+
* own `{window: 0}` tests push the floor to `log_seq_start` exactly).
|
|
1583
|
+
* `log_delete_floor` is monotone under the transition validator regardless of
|
|
1584
|
+
* `window`. So by the time a slot is physically deleted, a durable
|
|
1585
|
+
* certificate that it is gone already exists — which is what makes
|
|
1586
|
+
* `log_delete_floor` usable as a witness of "reclaimed" rather than "folded".
|
|
1587
|
+
* A crash between the CAS and the end of the DELETE loop leaks the remaining
|
|
1588
|
+
* slice permanently below the newly-advanced floor: deliberate, and the
|
|
1589
|
+
* fail-safe direction this program picked — leak, never corruption.
|
|
1590
|
+
*
|
|
1591
|
+
* The writer-side counterpart lives on the commit path, not here.
|
|
1592
|
+
* {@link LOG_RETENTION_SEQ_WINDOW} is a cost margin and a rate limit, never a
|
|
1593
|
+
* fence — see its JSDoc. What stops a paused or uncertain writer's create from
|
|
1594
|
+
* being acknowledged in a slot this pass has already retired is
|
|
1595
|
+
* `Writer#assertCommitAboveDeleteFloor`, which re-reads the manifest after the
|
|
1596
|
+
* committing create resolves and fails a sub-floor `seq` with
|
|
1597
|
+
* `BaerlyError{code:"AmbiguousCommit"}`. See
|
|
1598
|
+
* `docs/adr/002-ephemeral-coordination.md` § Closed paths for the two
|
|
1599
|
+
* approaches that were tried and rejected, and why that check is what remains.
|
|
1600
|
+
*
|
|
1601
|
+
* @param opts.signal Threaded to every storage call this makes (the gate
|
|
1602
|
+
* read, the CAS's own read + write, and each DELETE in the loop) — an
|
|
1603
|
+
* already-aborted signal, or one aborted mid-call, rejects the in-flight
|
|
1604
|
+
* {@link Storage} operation.
|
|
1605
|
+
* @param opts.window Test seam that overrides {@link LOG_RETENTION_SEQ_WINDOW}.
|
|
1606
|
+
* NOT a production tuning knob — do not promote this to an env var the way
|
|
1607
|
+
* `BAERLY_MAINTENANCE_*` tunes the fold/GC budgets. Shrinking it (this
|
|
1608
|
+
* module's own tests use `{window: 0}`) erases the pre-image reach and
|
|
1609
|
+
* steepens the retirement rate described above; production call sites
|
|
1610
|
+
* should omit it and take the default.
|
|
1611
|
+
* @param opts.maxDeletes Test seam that overrides
|
|
1612
|
+
* {@link LOG_RETENTION_MAX_DELETES_PER_TICK}. Same caveat as `opts.window`:
|
|
1613
|
+
* a scoped override for exercising the budget boundary in tests, not a
|
|
1614
|
+
* knob meant to reach a config surface.
|
|
1615
|
+
* @throws BaerlyError{code:"WriteConflict"} if the floor CAS loses to another
|
|
1616
|
+
* `current.json` writer, or if the fresh state authorizes nothing. The
|
|
1617
|
+
* maintenance call sites' shared `retireLogs` helper (`maintenance.ts`)
|
|
1618
|
+
* swallows exactly this code and re-throws everything else, matching how
|
|
1619
|
+
* `WriteConflict` from `compact()` / `runGc()` is treated at every call site;
|
|
1620
|
+
* returning it unwrapped here is what keeps that policy in one place.
|
|
1621
|
+
* @throws BaerlyError{code:"Internal"} if the floor CAS completes without
|
|
1622
|
+
* having authorized the range it published — a wiring tripwire, not a
|
|
1623
|
+
* runtime state. `retireLogs` re-throws it into `runBoundedMaintenance`'s
|
|
1624
|
+
* outer catch (`db.maintenance.unexpected_error_total`), so the failure is
|
|
1625
|
+
* observable rather than silent.
|
|
1626
|
+
*/
|
|
1627
|
+
async function retireLogRange(storage, currentJsonKey, opts) {
|
|
1628
|
+
const readOpts = opts?.signal !== void 0 ? { signal: opts.signal } : void 0;
|
|
1629
|
+
const read = await readCurrentJson(storage, currentJsonKey, readOpts);
|
|
1630
|
+
if (read === null) return { deleted: 0 };
|
|
1631
|
+
const gate = computeRetirableRange(read.json, opts);
|
|
1632
|
+
if (gate.start >= gate.end) return { deleted: 0 };
|
|
1633
|
+
let authorized;
|
|
1634
|
+
const cas = await casUpdateCurrentJson(storage, currentJsonKey, (current) => {
|
|
1635
|
+
authorized = computeRetirableRange(current, opts);
|
|
1636
|
+
if (authorized.start >= authorized.end) throw new BaerlyError("WriteConflict", `retireLogRange: ${currentJsonKey} authorizes no retirable range at CAS time; a concurrent writer moved log_seq_start`);
|
|
1637
|
+
return {
|
|
1638
|
+
...current,
|
|
1639
|
+
log_delete_floor: authorized.end
|
|
1640
|
+
};
|
|
1641
|
+
}, readOpts);
|
|
1642
|
+
if (authorized === void 0 || logDeleteFloorOf(cas.json) !== authorized.end) {
|
|
1643
|
+
const published = logDeleteFloorOf(cas.json);
|
|
1644
|
+
const authorizedEnd = authorized === void 0 ? "none" : String(authorized.end);
|
|
1645
|
+
throw new BaerlyError("Internal", `retireLogRange: ${currentJsonKey}: the floor CAS published ${String(published)} against authorized end ${authorizedEnd}; refusing to DELETE a range the CAS never validated`);
|
|
1646
|
+
}
|
|
1647
|
+
const range = authorized;
|
|
1648
|
+
const { prefix: collectionPrefix } = collectionFromCurrentJsonKey(currentJsonKey);
|
|
1649
|
+
await Promise.all(Array.from({ length: range.end - range.start }, (_, i) => storage.delete(logObjectKey(collectionPrefix, range.start + i), readOpts)));
|
|
1650
|
+
return { deleted: range.end - range.start };
|
|
1651
|
+
}
|
|
1652
|
+
// packages/server/src/maintenance.ts
|
|
1653
|
+
/**
|
|
1654
|
+
* Maintenance passes over one collection. `runScheduledMaintenance` is the
|
|
1655
|
+
* published opt-in scheduled pass (addressed by collection, sized by host
|
|
1656
|
+
* tier); `runMaintenancePass` is the internal composition it resolves to,
|
|
1657
|
+
* which the adapters, CLI, bench and tests drive with per-phase knobs;
|
|
1658
|
+
* `runBoundedMaintenance` is the in-band write-tick runner.
|
|
1659
|
+
*
|
|
1660
|
+
* Every pass is a single attempt: `compact()` and `runGc()` are
|
|
1661
|
+
* CAS-protected, so a pass cut short is retried safely by the next one.
|
|
1662
|
+
* The caller schedules the next pass; nothing here loops or retries.
|
|
1663
|
+
*/
|
|
1664
|
+
/**
|
|
1665
|
+
* One log-retirement pass: run {@link retireLogRange} and emit its
|
|
1666
|
+
* counter. Shared by every maintenance trigger that retires stale logs
|
|
1667
|
+
* (`runScheduledMaintenance` and both retirement points inside
|
|
1668
|
+
* `runBoundedMaintenance`), so the metric name, option threading, and
|
|
1669
|
+
* error policy cannot drift between call sites.
|
|
1670
|
+
*
|
|
1671
|
+
* Error policy — deliberately NOT a bare swallow: `WriteConflict` (the floor
|
|
1672
|
+
* CAS lost to another writer, or a concurrent fold moved `log_seq_start`)
|
|
1673
|
+
* is routine contention, swallowed here and retried by the next pass.
|
|
1674
|
+
* Anything else is re-thrown for the caller's own error path, matching
|
|
1675
|
+
* how `compact()` / `runGc()` failures are treated at every call site:
|
|
1676
|
+
* `runBoundedMaintenance`'s outer catch counts
|
|
1677
|
+
* `db.maintenance.unexpected_error_total` and logs the stack, and
|
|
1678
|
+
* `runScheduledMaintenance` propagates per its documented "errors
|
|
1679
|
+
* propagate" contract. Retirement is the only mechanism bounding the
|
|
1680
|
+
* steady-state log-object count — a persistent unexpected failure must
|
|
1681
|
+
* not fail silently while objects accumulate unbounded.
|
|
1682
|
+
*/
|
|
1683
|
+
const retireLogs = async (storage, currentJsonKey, opts) => {
|
|
1684
|
+
const { name: collection } = collectionFromCurrentJsonKey(currentJsonKey);
|
|
1685
|
+
try {
|
|
1686
|
+
const retired = await retireLogRange(storage, currentJsonKey, {
|
|
1687
|
+
...opts?.logRetention,
|
|
1688
|
+
...opts?.signal !== void 0 && { signal: opts.signal }
|
|
1689
|
+
});
|
|
1690
|
+
ctxMetrics().counter("db.log_retention.deleted_total", retired.deleted, { collection });
|
|
1691
|
+
return retired.deleted;
|
|
1692
|
+
} catch (error) {
|
|
1693
|
+
if (isWriteConflict(error)) return 0;
|
|
1694
|
+
throw error;
|
|
1695
|
+
}
|
|
1696
|
+
};
|
|
1697
|
+
/**
|
|
1698
|
+
* One maintenance pass over one collection, addressed by its `current.json`
|
|
1699
|
+
* key: `compact()` then `runGc()` (in that order; the compactor's advance
|
|
1700
|
+
* of `log_seq_start` produces the stale-log candidates the GC then marks),
|
|
1701
|
+
* then log retirement. With {@link CLOUDFLARE_FREE_TIER} the whole pass is
|
|
1702
|
+
* at most 94 storage calls, 282 with every call retried, which fits the 900
|
|
1703
|
+
* a Workers Free invocation may spend through the R2 binding but not the 45
|
|
1704
|
+
* it may spend through `fetch` (see {@link CLOUDFLARE_FREE_TIER}). The
|
|
1705
|
+
* request ledger refuses any call past the invocation's limit before it is
|
|
1706
|
+
* sent, so a pass never exceeds the limit.
|
|
1707
|
+
*
|
|
1708
|
+
* `minEntriesToCompact` defaults to {@link SCHEDULED_MIN_ENTRIES_TO_COMPACT}
|
|
1709
|
+
* (1) here, deliberately NOT `compact()`'s own default (100) or the
|
|
1710
|
+
* write-tick floor ({@link WRITE_TICK_MIN_ENTRIES_TO_COMPACT}, 50), both of
|
|
1711
|
+
* which exist to keep an in-band write from thrashing snapshot rewrites. A
|
|
1712
|
+
* scheduler that fires has already decided it is time to work, so the
|
|
1713
|
+
* scheduled path drains the live tail to zero rather than parking it in a
|
|
1714
|
+
* dead zone between a count floor and the per-entry GET cost every read
|
|
1715
|
+
* pays. An explicit `options.compact.minEntriesToCompact` suppresses this
|
|
1716
|
+
* default; {@link CLOUDFLARE_FREE_TIER} carries 20, which keeps
|
|
1717
|
+
* `minEntriesToCompact <= P` for its bounded tail probe.
|
|
1718
|
+
*
|
|
1719
|
+
* Errors propagate; `WriteConflict` from retirement is swallowed as
|
|
1720
|
+
* routine contention (see `retireLogs`).
|
|
1721
|
+
*
|
|
1722
|
+
* @internal
|
|
1723
|
+
*/
|
|
1724
|
+
const runMaintenancePass = async (args, options = {}) => {
|
|
1725
|
+
return {
|
|
1726
|
+
compact: await compactPhase(args, options),
|
|
1727
|
+
gc: await gcPhase(args, options),
|
|
1728
|
+
retired: await retireLogs(args.storage, args.currentJsonKey, {
|
|
1729
|
+
logRetention: options.logRetention,
|
|
1730
|
+
...options.signal !== void 0 && { signal: options.signal }
|
|
1731
|
+
})
|
|
1732
|
+
};
|
|
1733
|
+
};
|
|
1734
|
+
/** The pass's `compact()` call, with the scheduled fold floor. */
|
|
1735
|
+
const compactPhase = (args, options) => compact(args, {
|
|
1736
|
+
...options.compact,
|
|
1737
|
+
...options.compact?.minEntriesToCompact === void 0 && { minEntriesToCompact: 1 },
|
|
1738
|
+
...options.signal !== void 0 && { signal: options.signal }
|
|
1739
|
+
});
|
|
1740
|
+
/** The pass's `runGc()` call. */
|
|
1741
|
+
const gcPhase = (args, options) => runGc(args, {
|
|
1742
|
+
...options.gc,
|
|
1743
|
+
...options.signal !== void 0 && { signal: options.signal }
|
|
1744
|
+
});
|
|
1745
|
+
const profileToScheduledOptions = (profile, compactMaxTailProbeGets, minEntriesToCompact = 1) => ({
|
|
1746
|
+
compact: {
|
|
1747
|
+
maxEntriesPerRun: profile.maxFoldEntriesPerPass,
|
|
1748
|
+
minEntriesToCompact,
|
|
1749
|
+
...compactMaxTailProbeGets !== void 0 && { maxTailProbeGets: compactMaxTailProbeGets }
|
|
1750
|
+
},
|
|
1751
|
+
gc: {
|
|
1752
|
+
maxMarksPerRun: profile.gcMaxMarks,
|
|
1753
|
+
maxSweepsPerRun: profile.gcMaxSweeps
|
|
1754
|
+
}
|
|
1755
|
+
});
|
|
1756
|
+
const TIER_OPTIONS = {
|
|
1757
|
+
"cf-free": profileToScheduledOptions(MAINTENANCE_PROFILE_CF_FREE, 25, MAINTENANCE_PROFILE_CF_FREE.maxFoldEntriesPerPass),
|
|
1758
|
+
"cf-paid": profileToScheduledOptions(MAINTENANCE_PROFILE_CF_PAID, CF_PAID_COMPACT_TAIL_PROBE_GETS),
|
|
1759
|
+
node: {}
|
|
1760
|
+
};
|
|
1761
|
+
/**
|
|
1762
|
+
* Run one opt-in scheduled maintenance pass over one collection: fold its
|
|
1763
|
+
* recent writes, delete data nothing references any more, and retire old
|
|
1764
|
+
* log entries. Optional: every write already runs bounded maintenance in
|
|
1765
|
+
* band, so a collection that takes writes maintains itself. A schedule is
|
|
1766
|
+
* for collections served mostly read-only, or to keep folding ahead of
|
|
1767
|
+
* the write tick.
|
|
1768
|
+
*
|
|
1769
|
+
* One call does a bounded amount of work and returns; it never loops or
|
|
1770
|
+
* retries, and it is safe to run concurrently with writes and with other
|
|
1771
|
+
* passes. The caller schedules the next pass. Run one collection per
|
|
1772
|
+
* Cloudflare invocation: shard the cron schedule or persist a collection
|
|
1773
|
+
* cursor instead of looping tenants or collections in one invocation.
|
|
1774
|
+
*
|
|
1775
|
+
* `tier` sizes the pass for its host, in the `BAERLY_MAINTENANCE_PROFILE`
|
|
1776
|
+
* vocabulary: `"cf-free"` fits one Workers Free invocation through the R2
|
|
1777
|
+
* binding, `"cf-paid"` one Workers Paid invocation, and `"node"` (the
|
|
1778
|
+
* default) is unbounded. S3 storage on Workers needs Paid, with
|
|
1779
|
+
* `"cf-paid"`.
|
|
1780
|
+
*
|
|
1781
|
+
* Errors propagate; log them from the cron handler. On Cloudflare an
|
|
1782
|
+
* uncaught error reaches the Workers dashboard.
|
|
1783
|
+
*
|
|
1784
|
+
* @throws BaerlyError code="InvalidConfig" when `app`, `tenant` or
|
|
1785
|
+
* `collection` is not a name `Db.create` / `db.collection` accepts, or
|
|
1786
|
+
* `tier` is not one of the listed values, or when an option this
|
|
1787
|
+
* release no longer accepts is passed.
|
|
1788
|
+
*
|
|
1789
|
+
* @example
|
|
1790
|
+
* ```ts
|
|
1791
|
+
* import { runScheduledMaintenance } from "@gusto/baerly-storage/maintenance";
|
|
1792
|
+
*
|
|
1793
|
+
* const target = { storage, app: "helpdesk", tenant: "acme", collection: "tickets" };
|
|
1794
|
+
*
|
|
1795
|
+
* // Node: one unbounded pass.
|
|
1796
|
+
* const res = await runScheduledMaintenance(target);
|
|
1797
|
+
* console.log("folded", res.folded, "deleted", res.gcDeleted);
|
|
1798
|
+
*
|
|
1799
|
+
* // Cloudflare: one bounded pass per invocation.
|
|
1800
|
+
* await runScheduledMaintenance(target, { tier: "cf-paid" });
|
|
1801
|
+
* ```
|
|
1802
|
+
*/
|
|
1803
|
+
const runScheduledMaintenance = async (target, options = {}) => {
|
|
1804
|
+
const { storage, app, tenant, collection } = target;
|
|
1805
|
+
assertNameSegment(app, "app", "runScheduledMaintenance");
|
|
1806
|
+
assertNameSegment(tenant, "tenant", "runScheduledMaintenance");
|
|
1807
|
+
assertNameSegment(collection, "collection", "runScheduledMaintenance");
|
|
1808
|
+
const { tier = "node", signal } = options;
|
|
1809
|
+
const tierOptions = Object.hasOwn(TIER_OPTIONS, tier) ? TIER_OPTIONS[tier] : void 0;
|
|
1810
|
+
if (tierOptions === void 0) throw new BaerlyError("InvalidConfig", `runScheduledMaintenance: tier must be "cf-free", "cf-paid" or "node", got ${JSON.stringify(tier)}`);
|
|
1811
|
+
if (options.phase !== void 0) throw new BaerlyError("InvalidConfig", "runScheduledMaintenance: `phase` was removed in 0.7; each invocation runs one whole maintenance pass — remove the option");
|
|
1812
|
+
const args = {
|
|
1813
|
+
storage,
|
|
1814
|
+
currentJsonKey: `app/${app}/tenant/${tenant}/manifests/${collection}/current.json`
|
|
1815
|
+
};
|
|
1816
|
+
const passOptions = {
|
|
1817
|
+
...tierOptions,
|
|
1818
|
+
...signal !== void 0 && { signal }
|
|
1819
|
+
};
|
|
1820
|
+
return summarize(await runMaintenancePass(args, passOptions));
|
|
1821
|
+
};
|
|
1822
|
+
/**
|
|
1823
|
+
* Compaction skips that leave available work unfolded. The scheduled
|
|
1824
|
+
* tiers set no snapshot ceiling, so the over-ceiling `"deferred"` skip
|
|
1825
|
+
* cannot occur on this path.
|
|
1826
|
+
*/
|
|
1827
|
+
const DEFERRAL_REASONS = {
|
|
1828
|
+
"cas-lost": "contention",
|
|
1829
|
+
"probe-budget-checkpointed": "budget"
|
|
1830
|
+
};
|
|
1831
|
+
/** Format-neutral summary of one whole pass. */
|
|
1832
|
+
const summarize = ({ compact: compactRes, gc: gcRes, retired }) => {
|
|
1833
|
+
const reason = DEFERRAL_REASONS[compactRes.skippedReason ?? ""];
|
|
1834
|
+
return {
|
|
1835
|
+
folded: compactRes.written ? compactRes.entriesFolded : 0,
|
|
1836
|
+
...reason !== void 0 && { deferred: { reason } },
|
|
1837
|
+
gcDeleted: gcRes.swept + retired,
|
|
1838
|
+
pending: gcRes.pendingDepth
|
|
1839
|
+
};
|
|
1840
|
+
};
|
|
1841
|
+
/**
|
|
1842
|
+
* Floor-based GC-cadence boundary crossing. Every commit advances the
|
|
1843
|
+
* writer-observed tail by one logical slot; `tail_hint` remains a
|
|
1844
|
+
* lower bound and may be refreshed later by maintenance. The floor test
|
|
1845
|
+
* trips on any interval boundary inside `(prevSeq, nextSeq]`, so it
|
|
1846
|
+
* stays correct whether the observed/probed tail advances by one or
|
|
1847
|
+
* catches up by a larger step.
|
|
1848
|
+
*/
|
|
1849
|
+
const crossesGcBoundary = (prevSeq, nextSeq, interval) => Math.floor(prevSeq / interval) !== Math.floor(nextSeq / interval);
|
|
1850
|
+
/**
|
|
1851
|
+
* The write-tick runner's pre-fold projection off STORED figures: the
|
|
1852
|
+
* snapshot it would load is within `C` bytes and `E` rows. It does not
|
|
1853
|
+
* project the pass: `compact()` counts real rows as it applies the range
|
|
1854
|
+
* and folds the longest prefix that stays within `E`, so an update/delete
|
|
1855
|
+
* tail keeps folding at the ceiling and only an entry that would add a row
|
|
1856
|
+
* past `E` stops it. The runner, `baerly inspect` and the backlog bench
|
|
1857
|
+
* share this predicate. Both comparisons are written so a NaN ceiling
|
|
1858
|
+
* fails closed.
|
|
1859
|
+
*/
|
|
1860
|
+
const isFoldViable = (snapshotBytes, snapshotRows, ceilings) => snapshotBytes <= ceilings.maxFoldBytes && snapshotRows <= ceilings.maxFoldRows;
|
|
1861
|
+
/**
|
|
1862
|
+
* Resolve the serving host's fold ceilings: `profile` (absent ⇒
|
|
1863
|
+
* {@link MAINTENANCE_PROFILE_CF_FREE}) with `C` overridden by
|
|
1864
|
+
* `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` (`maxFoldBytes`). `E` has no
|
|
1865
|
+
* override. The write-tick runner and growth refusal (`capacity.ts`) both
|
|
1866
|
+
* resolve through here, so a refusal and a fold never see different
|
|
1867
|
+
* ceilings.
|
|
1868
|
+
*/
|
|
1869
|
+
const resolveFoldCeilings = (profile, maxFoldBytes) => {
|
|
1870
|
+
const resolved = profile ?? MAINTENANCE_PROFILE_CF_FREE;
|
|
1871
|
+
return {
|
|
1872
|
+
maxFoldBytes: maxFoldBytes ?? resolved.maxFoldBytes,
|
|
1873
|
+
maxFoldRows: resolved.maxFoldRows
|
|
1874
|
+
};
|
|
1875
|
+
};
|
|
1876
|
+
/**
|
|
1877
|
+
* Derived live-tail byte size — the ratio TRIGGER input that replaces the
|
|
1878
|
+
* formerly-stored exact byte count. `(observedTail − log_seq_start) ×
|
|
1879
|
+
* mean_entry_bytes`. `observedTail` is a param so write-tick callers can
|
|
1880
|
+
* pass the writer-observed tail and scheduled callers can pass a
|
|
1881
|
+
* probe-discovered true tail. Cold-start (no mean yet) falls back to
|
|
1882
|
+
* {@link MAINTENANCE_COLD_START_ENTRY_BYTES}, never 0 (see that constant).
|
|
1883
|
+
* TRIGGER-only — structurally barred from `foldViable` (the exact-bytes fold
|
|
1884
|
+
* ceiling).
|
|
1885
|
+
*/
|
|
1886
|
+
const estimateTailBytes = (current, observedTail) => Math.max(0, observedTail - current.log_seq_start) * (current.mean_entry_bytes ?? 128);
|
|
1887
|
+
/** Derived live-tail bytes over the snapshot's bytes (floored at {@link MAINTENANCE_MIN_LIVE_BYTES}). */
|
|
1888
|
+
const tailRatio = (current, observedTail) => estimateTailBytes(current, observedTail) / Math.max(current.snapshot_bytes, MAINTENANCE_MIN_LIVE_BYTES);
|
|
1889
|
+
/**
|
|
1890
|
+
* The cheap DISPATCH gate the writer calls after a commit — zero
|
|
1891
|
+
* storage ops; it reads the post-commit {@link CurrentJson} already in
|
|
1892
|
+
* scope. Ratio-OR-boundary, WITHOUT the entry floor (the floor is part
|
|
1893
|
+
* of the fold-trigger Gate 1 checked inside {@link runBoundedMaintenance}).
|
|
1894
|
+
* Returning `false` lets the writer skip the dispatch entirely. Ratio
|
|
1895
|
+
* numerator is the DERIVED {@link estimateTailBytes};
|
|
1896
|
+
* `observedTail` threads from the caller (the writer's in-memory observed
|
|
1897
|
+
* tail `seq+1` under single-write commit). Both the boundary check and the
|
|
1898
|
+
* ratio key off `observedTail`, since the stored `tail_hint` is now only a
|
|
1899
|
+
* non-authoritative lower bound (compactor-advanced).
|
|
1900
|
+
*/
|
|
1901
|
+
const shouldFireMaintenance = (current, prevSeq, gcInterval, observedTail) => crossesGcBoundary(prevSeq, observedTail, gcInterval) || tailRatio(current, observedTail) >= 1;
|
|
1902
|
+
/**
|
|
1903
|
+
* Human-readable line for a fold-wall deferral. Names both ceilings, which
|
|
1904
|
+
* arm tripped, that `log_seq_start` and log retention are frozen, and the
|
|
1905
|
+
* remedy that actually applies to that arm — the bytes override does
|
|
1906
|
+
* nothing for rows.
|
|
1907
|
+
*/
|
|
1908
|
+
const foldDeferredWarning = (f) => {
|
|
1909
|
+
const which = f.gate === "rebuild" ? "rebuilt" : "stored";
|
|
1910
|
+
const rowsTripped = f.gate === "rebuild" ? `the rows arm tripped (the next log entry adds a row past E, or the rebuilt snapshot is over E)` : `the rows arm tripped (snapshot_rows > E)`;
|
|
1911
|
+
const tripped = f.dimension === "bytes" ? `the bytes arm tripped (snapshot_bytes > C)` : rowsTripped;
|
|
1912
|
+
const remedy = f.dimension === "bytes" ? `On Workers Paid set BAERLY_MAINTENANCE_PROFILE=cf-paid (C=${MAINTENANCE_PROFILE_CF_PAID.maxFoldBytes}); on paid Cloudflare / Node you can also raise BAERLY_MAINTENANCE_MAX_FOLD_BYTES — but on Cloudflare a cap above the configured default may exceed an invocation's CPU or memory resources, so such folds may not land. Otherwise, move to a database service (D1 / Postgres).` : `E has no env override, and BAERLY_MAINTENANCE_MAX_FOLD_BYTES does not apply to rows. On Cloudflare, move to Workers Paid and set BAERLY_MAINTENANCE_PROFILE=cf-paid (E=${MAINTENANCE_PROFILE_CF_PAID.maxFoldRows}); on Node (E=${MAINTENANCE_PROFILE_NODE.maxFoldRows}) or past the paid ceiling, split the collection or move to a database service (D1 / Postgres).`;
|
|
1913
|
+
return `baerly-storage: collection "${f.collection}" has stopped compacting — the ${which} snapshot is ${f.snapshot_bytes} bytes / ${f.snapshot_rows} rows against this host's fold ceiling C=${f.ceiling_bytes} bytes, E=${f.ceiling_rows} rows, and ${tripped}. Until it folds again log_seq_start stays at ${f.log_seq_start}, log retention is paused, the live tail (${f.live_log_tail} entries) and the bucket grow without bound, and every read replays the tail. ${remedy} See docs/about/graduation.md.`;
|
|
1914
|
+
};
|
|
1915
|
+
/**
|
|
1916
|
+
* The write-tick maintenance runner: a bounded, single-attempt
|
|
1917
|
+
* composition of {@link compact} and {@link runGc} for one collection,
|
|
1918
|
+
* sized by default to a conservative Cloudflare free-tier CPU budget.
|
|
1919
|
+
*
|
|
1920
|
+
* INVARIANT: a {@link MaintenanceProfile} changes only maintenance rate +
|
|
1921
|
+
* defer threshold — never data/API/query/wire/correctness; reads stay pure.
|
|
1922
|
+
* See `maintenance-profile-equivalence.test.ts`.
|
|
1923
|
+
*
|
|
1924
|
+
* Never throws — the write-tick caller must never see a maintenance
|
|
1925
|
+
* failure. CAS contention is swallowed quietly, and so is a call the
|
|
1926
|
+
* invocation's request ledger refused (each phase is sized from the
|
|
1927
|
+
* ledger's remainder first; see the request-budget note inside, and
|
|
1928
|
+
* `docs/spec/sync-protocol.md` "Per-invocation request budget"); an over-ceiling deferral
|
|
1929
|
+
* is not an error but is signalled loudly (see `signalFoldDeferred`
|
|
1930
|
+
* inside); unexpected throws bump
|
|
1931
|
+
* `db.maintenance.unexpected_error_total`, log a stack, and are
|
|
1932
|
+
* swallowed.
|
|
1933
|
+
*
|
|
1934
|
+
* Control flow (fold-priority with a stateless GC-starvation guard):
|
|
1935
|
+
* 0. `disabled` → skip fold/GC, but still allow the rate-limited
|
|
1936
|
+
* tail_hint refresh that bounds read/write forward-probes.
|
|
1937
|
+
* 1. Read `current.json` once.
|
|
1938
|
+
* 2. Hard-GC starvation boundary (`"single"` only) → GC slice, skip fold.
|
|
1939
|
+
* 3. Gate 1 (ratio AND entry floor, or a forced tick) trips → fold if the pre-fold
|
|
1940
|
+
* projection is viable, else defer and signal. On `"single"` a fold
|
|
1941
|
+
* attempt is this tick's one phase — including one that compact()
|
|
1942
|
+
* deferred after rebuilding, which signals the same way and ends the
|
|
1943
|
+
* tick. A pre-fold defer falls through to Step 4.
|
|
1944
|
+
* 4. Otherwise (or on `"both"`) → GC iff the cadence boundary crossed.
|
|
1945
|
+
*
|
|
1946
|
+
* Steps 0, 2, 3-defer, and 4 all take the rate-limited `tail_hint`
|
|
1947
|
+
* refresh, but the tick publishes the hint AT MOST ONCE — a landed fold
|
|
1948
|
+
* (Step-7 CAS) and the refresh itself both count as that publication.
|
|
1949
|
+
* Ordering matters: Step 3's defer refreshes and then falls through to
|
|
1950
|
+
* Step 4, so without the shared guard that one tick would CAS
|
|
1951
|
+
* `current.json` twice with identical bytes.
|
|
1952
|
+
*/
|
|
1953
|
+
const runBoundedMaintenance = async (args, options) => {
|
|
1954
|
+
const { storage, currentJsonKey, prevSeq } = args;
|
|
1955
|
+
const profile = options?.profile ?? MAINTENANCE_PROFILE_CF_FREE;
|
|
1956
|
+
const { maxFoldEntriesPerPass, gcMaxMarks, gcMaxSweeps, gcInterval } = profile;
|
|
1957
|
+
const forceFold = args.forceFold === true;
|
|
1958
|
+
const minEntriesToCompact = forceFold ? 1 : options?.minEntriesToCompact ?? 50;
|
|
1959
|
+
const phasesPerTick = options?.phasesPerTick ?? "single";
|
|
1960
|
+
const signal = options?.signal;
|
|
1961
|
+
const ceilings = resolveFoldCeilings(profile, args.maxFoldBytes);
|
|
1962
|
+
const C = ceilings.maxFoldBytes;
|
|
1963
|
+
const E = ceilings.maxFoldRows;
|
|
1964
|
+
const { prefix: collectionPrefix, name: collection } = collectionFromCurrentJsonKey(currentJsonKey);
|
|
1965
|
+
const gcOpts = {
|
|
1966
|
+
maxMarksPerRun: gcMaxMarks,
|
|
1967
|
+
maxSweepsPerRun: gcMaxSweeps,
|
|
1968
|
+
...signal !== void 0 && { signal },
|
|
1969
|
+
...options?.gcGraceMillis !== void 0 && { graceMillis: options.gcGraceMillis },
|
|
1970
|
+
...options?.now !== void 0 && { now: options.now }
|
|
1971
|
+
};
|
|
1972
|
+
const ledger = getCurrentContext()?.ledger;
|
|
1973
|
+
const requestsLeft = () => ledger?.storageRemaining() ?? 1e400;
|
|
1974
|
+
const skipForBudget = (phase) => {
|
|
1975
|
+
ctxMetrics().counter("db.maintenance.request_budget_skipped_total", 1, {
|
|
1976
|
+
collection,
|
|
1977
|
+
phase
|
|
1978
|
+
});
|
|
1979
|
+
};
|
|
1980
|
+
const retireWithinBudget = async () => {
|
|
1981
|
+
const deletes = Math.floor((requestsLeft() - 7) / 3);
|
|
1982
|
+
if (deletes < 1) {
|
|
1983
|
+
skipForBudget("retire");
|
|
1984
|
+
return;
|
|
1985
|
+
}
|
|
1986
|
+
const logRetention = options?.logRetention;
|
|
1987
|
+
const maxDeletes = logRetention?.maxDeletes ?? 20;
|
|
1988
|
+
await retireLogs(storage, currentJsonKey, {
|
|
1989
|
+
logRetention: deletes < maxDeletes ? {
|
|
1990
|
+
...logRetention,
|
|
1991
|
+
maxDeletes: deletes
|
|
1992
|
+
} : logRetention,
|
|
1993
|
+
...signal !== void 0 && { signal }
|
|
1994
|
+
});
|
|
1995
|
+
};
|
|
1996
|
+
try {
|
|
1997
|
+
const read = await readCurrentJson(storage, currentJsonKey, signal !== void 0 ? { signal } : void 0);
|
|
1998
|
+
if (read === null) return;
|
|
1999
|
+
const current = read.json;
|
|
2000
|
+
const snapshotBytes = current.snapshot_bytes;
|
|
2001
|
+
const snapshotRows = current.snapshot_rows;
|
|
2002
|
+
const logSeqStart = current.log_seq_start;
|
|
2003
|
+
const probeFloor = Math.max(logSeqStart, current.tail_hint);
|
|
2004
|
+
let nextSeq;
|
|
2005
|
+
if (args.observedTail !== void 0) nextSeq = Math.max(args.observedTail, probeFloor);
|
|
2006
|
+
else nextSeq = (await probeTailFrom(storage, collectionPrefix, probeFloor, signal !== void 0 ? { signal } : void 0)).tail;
|
|
2007
|
+
const ratio = tailRatio(current, nextSeq);
|
|
2008
|
+
const foldAtTailEntries = options?.foldAtTailEntries;
|
|
2009
|
+
const gate1 = forceFold || foldAtTailEntries !== void 0 && nextSeq - logSeqStart >= foldAtTailEntries || ratio >= 1 && nextSeq - logSeqStart >= minEntriesToCompact;
|
|
2010
|
+
const foldViable = isFoldViable(snapshotBytes, snapshotRows, ceilings);
|
|
2011
|
+
const gcDue = crossesGcBoundary(prevSeq, nextSeq, gcInterval);
|
|
2012
|
+
let tailHintPublished = false;
|
|
2013
|
+
const refreshTailHintIfNeeded = async (stampWarnedSeq = false) => {
|
|
2014
|
+
if (!stampWarnedSeq) {
|
|
2015
|
+
if (tailHintPublished) return;
|
|
2016
|
+
if (nextSeq - current.tail_hint < 128) return;
|
|
2017
|
+
}
|
|
2018
|
+
tailHintPublished = true;
|
|
2019
|
+
if (requestsLeft() < 2) {
|
|
2020
|
+
skipForBudget("tail_hint");
|
|
2021
|
+
return;
|
|
2022
|
+
}
|
|
2023
|
+
try {
|
|
2024
|
+
await casUpdateCurrentJson(storage, currentJsonKey, (c) => ({
|
|
2025
|
+
...c,
|
|
2026
|
+
tail_hint: Math.max(c.tail_hint, nextSeq),
|
|
2027
|
+
...stampWarnedSeq && { last_warned_seq: nextSeq }
|
|
2028
|
+
}), signal !== void 0 ? { signal } : void 0);
|
|
2029
|
+
} catch {}
|
|
2030
|
+
};
|
|
2031
|
+
/**
|
|
2032
|
+
* The one fold-wall deferral signal, shared by both gates so a
|
|
2033
|
+
* deferral counts once and reads the same wherever it closed:
|
|
2034
|
+
*
|
|
2035
|
+
* - `db.compaction.deferred_total` (labels `collection`, `dimension`,
|
|
2036
|
+
* `gate`) plus `db.compaction.deferred_{bytes,rows}_total` — distinct
|
|
2037
|
+
* names, because the canonical line keys counters by name alone and
|
|
2038
|
+
* drops labels.
|
|
2039
|
+
* - A `fold_deferred` structured warning through the adapter's
|
|
2040
|
+
* {@link MaintenanceDispatch.warn} sink, carrying the human text as
|
|
2041
|
+
* `detail` — or, with no sink or one that throws, that text as a
|
|
2042
|
+
* `console.warn` line. Rate-limited by the SHARED `current.json.last_warned_seq` (not a
|
|
2043
|
+
* per-isolate Set — a fresh isolate must honour it). A collection
|
|
2044
|
+
* that has never warned warns on its first deferral. On Cloudflare
|
|
2045
|
+
* the tick runs in `ctx.waitUntil` after the canonical line flushed,
|
|
2046
|
+
* so the log record is the only signal an operator sees.
|
|
2047
|
+
* - The bounded `tail_hint` refresh (HR-2): a deferring collection
|
|
2048
|
+
* never reaches compact()'s Step-7 CAS, so without it every read
|
|
2049
|
+
* would re-walk the whole growing tail. Write-tick only; reads stay
|
|
2050
|
+
* pure.
|
|
2051
|
+
*/
|
|
2052
|
+
const signalFoldDeferred = async (d) => {
|
|
2053
|
+
const metrics = ctxMetrics();
|
|
2054
|
+
metrics.counter("db.compaction.deferred_total", 1, {
|
|
2055
|
+
collection,
|
|
2056
|
+
dimension: d.dimension,
|
|
2057
|
+
gate: d.gate
|
|
2058
|
+
});
|
|
2059
|
+
metrics.counter(d.dimension === "bytes" ? "db.compaction.deferred_bytes_total" : "db.compaction.deferred_rows_total", 1, {
|
|
2060
|
+
collection,
|
|
2061
|
+
gate: d.gate
|
|
2062
|
+
});
|
|
2063
|
+
const warnDue = current.last_warned_seq === void 0 || nextSeq - current.last_warned_seq >= 1e3;
|
|
2064
|
+
if (warnDue) {
|
|
2065
|
+
const fields = {
|
|
2066
|
+
collection,
|
|
2067
|
+
dimension: d.dimension,
|
|
2068
|
+
gate: d.gate,
|
|
2069
|
+
snapshot_bytes: d.snapshotBytes,
|
|
2070
|
+
snapshot_rows: d.snapshotRows,
|
|
2071
|
+
ceiling_bytes: C,
|
|
2072
|
+
ceiling_rows: E,
|
|
2073
|
+
live_log_tail: nextSeq - logSeqStart,
|
|
2074
|
+
log_seq_start: logSeqStart
|
|
2075
|
+
};
|
|
2076
|
+
const detail = foldDeferredWarning(fields);
|
|
2077
|
+
const sink = getCurrentContext()?.maintenance?.warn;
|
|
2078
|
+
let delivered = false;
|
|
2079
|
+
if (sink !== void 0) try {
|
|
2080
|
+
sink("fold_deferred", {
|
|
2081
|
+
...fields,
|
|
2082
|
+
detail
|
|
2083
|
+
});
|
|
2084
|
+
delivered = true;
|
|
2085
|
+
} catch {}
|
|
2086
|
+
if (!delivered) console.warn(detail);
|
|
2087
|
+
}
|
|
2088
|
+
await refreshTailHintIfNeeded(warnDue);
|
|
2089
|
+
};
|
|
2090
|
+
const runGcAndRefreshTailHint = async () => {
|
|
2091
|
+
const sweeps = requestsLeft() - 6;
|
|
2092
|
+
if (sweeps < 0) skipForBudget("gc");
|
|
2093
|
+
else await runGc({
|
|
2094
|
+
storage,
|
|
2095
|
+
currentJsonKey
|
|
2096
|
+
}, sweeps < gcMaxSweeps ? {
|
|
2097
|
+
...gcOpts,
|
|
2098
|
+
maxSweepsPerRun: sweeps
|
|
2099
|
+
} : gcOpts);
|
|
2100
|
+
await refreshTailHintIfNeeded();
|
|
2101
|
+
};
|
|
2102
|
+
try {
|
|
2103
|
+
if (args.disabled === true) {
|
|
2104
|
+
await refreshTailHintIfNeeded();
|
|
2105
|
+
return;
|
|
2106
|
+
}
|
|
2107
|
+
const hardGc = crossesGcBoundary(prevSeq, nextSeq, gcInterval * 4);
|
|
2108
|
+
if (phasesPerTick === "single" && hardGc) {
|
|
2109
|
+
await runGcAndRefreshTailHint();
|
|
2110
|
+
await retireWithinBudget();
|
|
2111
|
+
return;
|
|
2112
|
+
}
|
|
2113
|
+
const foldFits = requestsLeft() >= 5 + Math.min(maxFoldEntriesPerPass, Math.max(0, nextSeq - logSeqStart));
|
|
2114
|
+
if (gate1 && foldViable && !foldFits) skipForBudget("fold");
|
|
2115
|
+
else if (gate1) {
|
|
2116
|
+
if (foldViable) {
|
|
2117
|
+
const foldRes = await compact({
|
|
2118
|
+
storage,
|
|
2119
|
+
currentJsonKey
|
|
2120
|
+
}, {
|
|
2121
|
+
maxEntriesPerRun: maxFoldEntriesPerPass,
|
|
2122
|
+
minEntriesToCompact: foldAtTailEntries === void 0 ? minEntriesToCompact : Math.min(minEntriesToCompact, foldAtTailEntries),
|
|
2123
|
+
ceilingBytes: C,
|
|
2124
|
+
ceilingEntries: E,
|
|
2125
|
+
knownTail: nextSeq,
|
|
2126
|
+
...signal !== void 0 && { signal }
|
|
2127
|
+
});
|
|
2128
|
+
if (foldRes.written) tailHintPublished = true;
|
|
2129
|
+
if (foldRes.deferral !== void 0) await signalFoldDeferred({
|
|
2130
|
+
gate: "rebuild",
|
|
2131
|
+
dimension: foldRes.deferral.dimension,
|
|
2132
|
+
snapshotBytes: foldRes.deferral.snapshotBytes,
|
|
2133
|
+
snapshotRows: foldRes.deferral.snapshotRows
|
|
2134
|
+
});
|
|
2135
|
+
if (phasesPerTick === "single") return;
|
|
2136
|
+
} else await signalFoldDeferred({
|
|
2137
|
+
gate: "pre-fold",
|
|
2138
|
+
dimension: snapshotBytes > C ? "bytes" : "rows",
|
|
2139
|
+
snapshotBytes,
|
|
2140
|
+
snapshotRows
|
|
2141
|
+
});
|
|
2142
|
+
}
|
|
2143
|
+
if (gcDue) await runGcAndRefreshTailHint();
|
|
2144
|
+
await retireWithinBudget();
|
|
2145
|
+
} finally {
|
|
2146
|
+
await refreshTailHintIfNeeded();
|
|
2147
|
+
}
|
|
2148
|
+
} catch (error) {
|
|
2149
|
+
if (isWriteConflict(error)) return;
|
|
2150
|
+
if (error instanceof BaerlyError && error.code === "CapacityExceeded" && error.cause?.refused === true) {
|
|
2151
|
+
ctxMetrics().counter("db.maintenance.request_budget_refused_total", 1, { collection });
|
|
2152
|
+
return;
|
|
2153
|
+
}
|
|
2154
|
+
ctxMetrics().counter("db.maintenance.unexpected_error_total", 1, { collection });
|
|
2155
|
+
console.error(error);
|
|
2156
|
+
}
|
|
2157
|
+
};
|
|
2158
|
+
/**
|
|
2159
|
+
* Dispatch one write-tick {@link runBoundedMaintenance} through the
|
|
2160
|
+
* request's {@link MaintenanceDispatch}: inline and awaited by default,
|
|
2161
|
+
* `ctx.waitUntil` on Cloudflare. Never throws: the tick swallows its own
|
|
2162
|
+
* failures, and a failing dispatcher bumps
|
|
2163
|
+
* `db.write.maintenance_dispatch_failed_total`. The writer calls it after
|
|
2164
|
+
* a commit; a write refused with `MaintenancePending` calls it with
|
|
2165
|
+
* `forceFold` and nothing committed (`prevSeq === observedTail`).
|
|
2166
|
+
*/
|
|
2167
|
+
const dispatchWriteTick = async (args) => {
|
|
2168
|
+
const maint = getCurrentContext()?.maintenance;
|
|
2169
|
+
const dispatch = maint?.dispatch ?? dispatchInlineAwaited;
|
|
2170
|
+
try {
|
|
2171
|
+
await dispatch(() => runBoundedMaintenance({
|
|
2172
|
+
storage: args.storage,
|
|
2173
|
+
currentJsonKey: args.currentJsonKey,
|
|
2174
|
+
prevSeq: args.prevSeq,
|
|
2175
|
+
observedTail: args.observedTail,
|
|
2176
|
+
...maint?.disabled === true && { disabled: true },
|
|
2177
|
+
...maint?.maxFoldBytes !== void 0 && { maxFoldBytes: maint.maxFoldBytes },
|
|
2178
|
+
...args.forceFold === true && { forceFold: true }
|
|
2179
|
+
}, maint?.options).then(() => {}, () => {}));
|
|
2180
|
+
} catch {
|
|
2181
|
+
ctxMetrics().counter("db.write.maintenance_dispatch_failed_total", 1, { collection: args.collection });
|
|
2182
|
+
}
|
|
2183
|
+
};
|
|
2184
|
+
/**
|
|
2185
|
+
* Default maintenance dispatcher: run the task inline and await it.
|
|
2186
|
+
* Adapters that can keep running after the response (Cloudflare:
|
|
2187
|
+
* `ctx.waitUntil`) override this with a fire-and-forget variant that
|
|
2188
|
+
* returns `void`.
|
|
2189
|
+
*/
|
|
2190
|
+
const dispatchInlineAwaited = (task) => task();
|
|
2191
|
+
/**
|
|
2192
|
+
* Parse the two host-agnostic ops-plane env vars into the
|
|
2193
|
+
* {@link MaintenanceDispatch} overrides. Shared by every host adapter so the
|
|
2194
|
+
* cross-host contract has one source of truth.
|
|
2195
|
+
*
|
|
2196
|
+
* `maxFoldBytes` (`C`) is `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` written as a
|
|
2197
|
+
* plain positive decimal integer (`/^[1-9][0-9]*$/`, at most
|
|
2198
|
+
* `Number.MAX_SAFE_INTEGER`), or undefined when unset or `""` (the active
|
|
2199
|
+
* profile's default applies). Anything else throws, untrimmed: `" 1024"`,
|
|
2200
|
+
* `"0x400"`, `"1e6"`, `"1.5"`, `"8mb"`. A unit-suffixed or mistyped value
|
|
2201
|
+
* would otherwise run silently at the default ceiling; zero or negative
|
|
2202
|
+
* would make `snapshot_bytes <= C` false forever, so the fold would defer
|
|
2203
|
+
* on every tick and the live tail would grow unbounded.
|
|
2204
|
+
*
|
|
2205
|
+
* `disabled` reads `BAERLY_MAINTENANCE_DISABLE`, untrimmed, against a closed,
|
|
2206
|
+
* case-insensitive vocabulary: unset, `""`, `"0"`, `"false"` → `false`;
|
|
2207
|
+
* `"1"`, `"true"` → `true`; anything else throws. The prior truthy-if-
|
|
2208
|
+
* non-empty parsing silently disabled maintenance on `"no"` / `"off"` —
|
|
2209
|
+
* the two most natural ways an operator would try to spell "don't disable".
|
|
2210
|
+
*
|
|
2211
|
+
* @throws {BaerlyError} `InvalidConfig` for a
|
|
2212
|
+
* `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` that is not a plain positive decimal
|
|
2213
|
+
* integer, or a `BAERLY_MAINTENANCE_DISABLE`
|
|
2214
|
+
* value outside the closed vocabulary above.
|
|
2215
|
+
*/
|
|
2216
|
+
const parseMaintenanceEnv = (readEnv) => {
|
|
2217
|
+
const rawFoldBytes = readEnv("BAERLY_MAINTENANCE_MAX_FOLD_BYTES");
|
|
2218
|
+
let maxFoldBytes;
|
|
2219
|
+
if (rawFoldBytes !== void 0 && rawFoldBytes !== "") {
|
|
2220
|
+
const parsedFoldBytes = Number(rawFoldBytes);
|
|
2221
|
+
if (!/^[1-9][0-9]*$/.test(rawFoldBytes) || !Number.isSafeInteger(parsedFoldBytes)) throw new BaerlyError("InvalidConfig", `BAERLY_MAINTENANCE_MAX_FOLD_BYTES must be unset, "", or a positive decimal integer byte count no greater than ${Number.MAX_SAFE_INTEGER}, got ${JSON.stringify(rawFoldBytes)}`);
|
|
2222
|
+
maxFoldBytes = parsedFoldBytes;
|
|
2223
|
+
}
|
|
2224
|
+
const rawDisable = readEnv("BAERLY_MAINTENANCE_DISABLE");
|
|
2225
|
+
const normalizedDisable = rawDisable?.toLowerCase();
|
|
2226
|
+
let disabled;
|
|
2227
|
+
if (rawDisable === void 0 || normalizedDisable === "" || normalizedDisable === "0" || normalizedDisable === "false") disabled = false;
|
|
2228
|
+
else if (normalizedDisable === "1" || normalizedDisable === "true") disabled = true;
|
|
2229
|
+
else throw new BaerlyError("InvalidConfig", `BAERLY_MAINTENANCE_DISABLE must be one of "", "0", "false", "1", "true" (case-insensitive), got ${JSON.stringify(rawDisable)}`);
|
|
2230
|
+
return {
|
|
2231
|
+
...maxFoldBytes !== void 0 && { maxFoldBytes },
|
|
2232
|
+
disabled
|
|
2233
|
+
};
|
|
2234
|
+
};
|
|
2235
|
+
export { logObjectKey as S, loadSnapshotAsMap as _, runScheduledMaintenance as a, isCallerFacing as b, rowBytes as c, isStorageRefusal as d, probeReadTail as f, walkLogRange as g, foldLogEntriesOnto as h, resolveFoldCeilings as i, findLogTail as l, probeTailFrom as m, isFoldViable as n, shouldFireMaintenance as o, probeTailChunk as p, parseMaintenanceEnv as r, projectSnapshot as s, dispatchWriteTick as t, forwardProbeCap as u, isOwnCollection as v, markCallerFacing as x, callerFacingCheck as y };
|
|
2236
|
+
|
|
2237
|
+
//# sourceMappingURL=maintenance-DevB6z4e.js.map
|