@gusto/baerly-storage 0.1.1 → 0.2.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 +27 -3
- package/dist/API.md +103 -22
- package/dist/{app-config-Dj_nGBfj.d.ts → app-config-C0Bbw_Z6.d.ts} +9 -9
- package/dist/app-config.d.ts +1 -1
- package/dist/auth.d.ts +1 -1
- package/dist/baerly.js +10 -10
- package/dist/baerly.js.map +1 -1
- package/dist/bytes-BXdamO3L.js +11 -0
- package/dist/bytes-BXdamO3L.js.map +1 -0
- package/dist/{client-CC5yVs1S.d.ts → client-DYZfoZb9.d.ts} +3 -3
- package/dist/client-react.d.ts +76 -85
- package/dist/client-react.js +95 -53
- package/dist/client-react.js.map +1 -1
- package/dist/client.d.ts +3 -3
- package/dist/cloudflare.d.ts +31 -4
- package/dist/cloudflare.js +72 -6
- package/dist/cloudflare.js.map +1 -1
- package/dist/{config-Bsg8wgwo.js → config-DVfDGyw1.js} +82 -2
- package/dist/config-DVfDGyw1.js.map +1 -0
- package/dist/{context-Oj7ffwD-.js → context-DRZ3tZ5l.js} +3 -2
- package/dist/{context-Oj7ffwD-.js.map → context-DRZ3tZ5l.js.map} +1 -1
- package/dist/{cost-B1WiZxlf.js → cost-CQt1YRkA.js} +3 -4
- package/dist/{cost-B1WiZxlf.js.map → cost-CQt1YRkA.js.map} +1 -1
- package/dist/{current-json-BkatBzF7.js → current-json-C-EyJqs0.js} +107 -5
- package/dist/current-json-C-EyJqs0.js.map +1 -0
- package/dist/{db-aRMK_0R0.d.ts → db-BM3y2JQw.d.ts} +3 -3
- package/dist/{deploy-BB-wqbhf.js → deploy-CrAbfgCq.js} +2 -2
- package/dist/{deploy-BB-wqbhf.js.map → deploy-CrAbfgCq.js.map} +1 -1
- package/dist/dev-vite.d.ts +3 -3
- package/dist/dev-vite.js +3 -3
- package/dist/dev.d.ts +1 -1
- package/dist/dev.js +1 -1
- package/dist/{doctor-B8h9GCN9.js → doctor-Db-hzPmE.js} +144 -7
- package/dist/doctor-Db-hzPmE.js.map +1 -0
- package/dist/{dump-BHo_sIMZ.js → dump-BYA55NLP.js} +3 -4
- package/dist/{dump-BHo_sIMZ.js.map → dump-BYA55NLP.js.map} +1 -1
- package/dist/errors-DOdL95kK.js.map +1 -1
- package/dist/{export-Dz2PZKSR.js → export-Bhbz90-z.js} +4 -5
- package/dist/{export-Dz2PZKSR.js.map → export-Bhbz90-z.js.map} +1 -1
- package/dist/{fsck-DEz9lyCy.js → fsck-CPPZWt9p.js} +5 -8
- package/dist/fsck-CPPZWt9p.js.map +1 -0
- package/dist/{http-DeJEeUcO.js → http-Cw8p6y5b.js} +5 -5
- package/dist/{http-DeJEeUcO.js.map → http-Cw8p6y5b.js.map} +1 -1
- package/dist/http.d.ts +3 -3
- package/dist/http.js +1 -1
- package/dist/{index-m6pY8iRU.d.ts → index-C3JAH1Yo.d.ts} +14 -2
- package/dist/{index-5lX_5NxZ.d.ts → index-DSvwEUeF.d.ts} +63 -54
- package/dist/{index-DPaQhAro.d.ts → index-DwDTWPSU.d.ts} +2 -2
- package/dist/{index-spCBsIwm.d.ts → index-cUY-36AN.d.ts} +3 -3
- package/dist/index.d.ts +5 -5
- package/dist/index.js +3 -3
- package/dist/{indexes-BIH73Uv4.d.ts → indexes-DAu2AkTW.d.ts} +2 -2
- package/dist/{inspect-x02aFWnh.js → inspect-Bdbzvi-_.js} +5 -6
- package/dist/{inspect-x02aFWnh.js.map → inspect-Bdbzvi-_.js.map} +1 -1
- package/dist/maintenance-BRrThz8V.d.ts +449 -0
- package/dist/maintenance-BvOv6BMM.js +1295 -0
- package/dist/maintenance-BvOv6BMM.js.map +1 -0
- package/dist/maintenance-ClzBC1Vv.js +1895 -0
- package/dist/maintenance-ClzBC1Vv.js.map +1 -0
- package/dist/maintenance.d.ts +2 -323
- package/dist/maintenance.js +2 -2
- package/dist/node.d.ts +20 -79
- package/dist/node.js +2 -2
- package/dist/{observability-2IDYRuZK.js → observability-CpOiEN0k.js} +2 -2
- package/dist/{observability-2IDYRuZK.js.map → observability-CpOiEN0k.js.map} +1 -1
- package/dist/observability.d.ts +2 -2
- package/dist/observability.js +2 -2
- package/dist/{plan-Cs17VqjU.js → plan-DOTl21vq.js} +3 -4
- package/dist/{plan-Cs17VqjU.js.map → plan-DOTl21vq.js.map} +1 -1
- package/dist/{query-DcSbFLJt.js → query-BmiQy328.js} +58 -26
- package/dist/query-BmiQy328.js.map +1 -0
- package/dist/{rebuild-index-DwXM0WfA.js → rebuild-index-DC_nR6wP.js} +4 -5
- package/dist/{rebuild-index-DwXM0WfA.js.map → rebuild-index-DC_nR6wP.js.map} +1 -1
- package/dist/{restore-CbKVMMpm.js → restore-C6IcmLeA.js} +44 -120
- package/dist/restore-C6IcmLeA.js.map +1 -0
- package/dist/{log-walk-DIru96UT.js → snapshot-SS8USDUF.js} +187 -20
- package/dist/snapshot-SS8USDUF.js.map +1 -0
- package/dist/{src-Cr9C7_tT.js → src-DU1sCMlr.js} +315 -278
- package/dist/src-DU1sCMlr.js.map +1 -0
- package/dist/{src-n0Te1r98.js → src-QQ7jDeL2.js} +25 -6
- package/dist/src-QQ7jDeL2.js.map +1 -0
- package/dist/{src-Chafbw8r.js → src-zhEAmmF7.js} +35 -4
- package/dist/src-zhEAmmF7.js.map +1 -0
- package/dist/{bucket-uri-BrDEYvzy.js → subcommand-DZcHcsYp.js} +222 -22
- package/dist/subcommand-DZcHcsYp.js.map +1 -0
- package/dist/{usage-RVUQMLop.js → usage-CLjirdD-.js} +4 -4
- package/dist/{usage-RVUQMLop.js.map → usage-CLjirdD-.js.map} +1 -1
- package/dist/{validate-DhH1lO8I.js → validate-DCq_0DIn.js} +2 -2
- package/dist/validate-DCq_0DIn.js.map +1 -0
- package/package.json +13 -6
- package/dist/bucket-uri-BrDEYvzy.js.map +0 -1
- package/dist/config-Bsg8wgwo.js.map +0 -1
- package/dist/current-json-BkatBzF7.js.map +0 -1
- package/dist/doctor-B8h9GCN9.js.map +0 -1
- package/dist/fsck-DEz9lyCy.js.map +0 -1
- package/dist/indexes-BXn7a06a.js +0 -297
- package/dist/indexes-BXn7a06a.js.map +0 -1
- package/dist/log-walk-DIru96UT.js.map +0 -1
- package/dist/maintenance-Bn6ul9aV.js +0 -758
- package/dist/maintenance-Bn6ul9aV.js.map +0 -1
- package/dist/query-DcSbFLJt.js.map +0 -1
- package/dist/rebuild-index-C5gTXryd.js +0 -119
- package/dist/rebuild-index-C5gTXryd.js.map +0 -1
- package/dist/restore-CbKVMMpm.js.map +0 -1
- package/dist/snapshot-D7C4_FSl.js +0 -71
- package/dist/snapshot-D7C4_FSl.js.map +0 -1
- package/dist/snapshot-z_N9hpTe.js +0 -917
- package/dist/snapshot-z_N9hpTe.js.map +0 -1
- package/dist/src-Chafbw8r.js.map +0 -1
- package/dist/src-Cr9C7_tT.js.map +0 -1
- package/dist/src-n0Te1r98.js.map +0 -1
- package/dist/subcommand-BWs6K7zb.js +0 -110
- package/dist/subcommand-BWs6K7zb.js.map +0 -1
- package/dist/validate-DhH1lO8I.js.map +0 -1
package/dist/maintenance.d.ts
CHANGED
|
@@ -1,323 +1,2 @@
|
|
|
1
|
-
import { d as
|
|
2
|
-
|
|
3
|
-
//#region packages/server/src/compactor.d.ts
|
|
4
|
-
/**
|
|
5
|
-
* Public configuration knobs for {@link compact}. All optional; the
|
|
6
|
-
* engine works unbounded by default. Opt into a per-run cap via the
|
|
7
|
-
* `CLOUDFLARE_FREE_TIER` profile (from `./maintenance.ts`) or by
|
|
8
|
-
* reaching for {@link InternalCompactOptions} via the
|
|
9
|
-
* `@baerly/server/_internal/testing` subpath.
|
|
10
|
-
*/
|
|
11
|
-
interface CompactOptions {
|
|
12
|
-
/**
|
|
13
|
-
* Minimum log-tail length to compact. Skips work when there are
|
|
14
|
-
* fewer than this many live entries past the last snapshot.
|
|
15
|
-
* Default 100.
|
|
16
|
-
*/
|
|
17
|
-
readonly minEntriesToCompact?: number;
|
|
18
|
-
/** Optional AbortSignal forwarded to every storage call. */
|
|
19
|
-
readonly signal?: AbortSignal;
|
|
20
|
-
}
|
|
21
|
-
/**
|
|
22
|
-
* Internal-only widening of {@link CompactOptions}. Surfaced via the
|
|
23
|
-
* `@baerly/server/_internal/testing` subpath (NOT in the published
|
|
24
|
-
* `publishConfig.exports`); production callers should use
|
|
25
|
-
* {@link CompactOptions}.
|
|
26
|
-
*
|
|
27
|
-
* @internal
|
|
28
|
-
*/
|
|
29
|
-
interface InternalCompactOptions extends CompactOptions {
|
|
30
|
-
/**
|
|
31
|
-
* @internal Budget cap for the CF free-tier subrequest budget;
|
|
32
|
-
* `CLOUDFLARE_FREE_TIER` sets it. Tests also set it to exercise
|
|
33
|
-
* the cap path. The compactor's I/O profile is
|
|
34
|
-
* `maxEntriesPerRun + 3` subrequests (N GETs + 1 PUT snapshot +
|
|
35
|
-
* 1 GET current + 1 PUT current). The default is effectively
|
|
36
|
-
* unbounded (`Number.MAX_SAFE_INTEGER`).
|
|
37
|
-
*/
|
|
38
|
-
readonly maxEntriesPerRun?: number;
|
|
39
|
-
}
|
|
40
|
-
interface CompactResult {
|
|
41
|
-
/** `true` iff a new snapshot landed and `current.json` was advanced. */
|
|
42
|
-
readonly written: boolean;
|
|
43
|
-
/** Reason `written === false`. */
|
|
44
|
-
readonly skippedReason?: "below-min-threshold" | "current-json-missing" | "cas-lost";
|
|
45
|
-
/** Prior snapshot key (`null` if no prior snapshot existed). */
|
|
46
|
-
readonly previousSnapshotKey: string | null;
|
|
47
|
-
/** New snapshot key (`undefined` if `written === false` and no PUT happened). */
|
|
48
|
-
readonly newSnapshotKey?: string;
|
|
49
|
-
/** `log_seq_start` before the run. */
|
|
50
|
-
readonly logSeqStartBefore: number;
|
|
51
|
-
/** `log_seq_start` after the run. */
|
|
52
|
-
readonly logSeqStartAfter: number;
|
|
53
|
-
/** Number of log entries folded into the new snapshot. */
|
|
54
|
-
readonly entriesFolded: number;
|
|
55
|
-
}
|
|
56
|
-
/**
|
|
57
|
-
* Fold a prefix of the live log into a new snapshot and CAS-advance
|
|
58
|
-
* `current.json`. Idempotent: a second run with no new writes is a
|
|
59
|
-
* no-op (below-min-threshold).
|
|
60
|
-
*
|
|
61
|
-
* Single-attempt: on CAS conflict we return
|
|
62
|
-
* `{written: false, skippedReason: "cas-lost", newSnapshotKey}` — the
|
|
63
|
-
* caller (the cron handler invoking `runScheduledMaintenance` from
|
|
64
|
-
* `./maintenance.ts`) decides whether to schedule another run. The
|
|
65
|
-
* orphan snapshot file just written will be swept by `runGc()`.
|
|
66
|
-
*
|
|
67
|
-
* @throws BaerlyError code="InvalidResponse" — `current.json` is
|
|
68
|
-
* present but malformed, or a snapshot body fails its schema /
|
|
69
|
-
* collection cross-check.
|
|
70
|
-
* @throws BaerlyError code="Internal" — protocol-invariant violation:
|
|
71
|
-
* a log entry missing inside `[log_seq_start, foldEnd)`, or the
|
|
72
|
-
* prior-snapshot pointer resolves to no body / a body whose hash
|
|
73
|
-
* doesn't match its filename.
|
|
74
|
-
*
|
|
75
|
-
* @example
|
|
76
|
-
* ```ts
|
|
77
|
-
* import { compact } from "@gusto/baerly-storage";
|
|
78
|
-
*
|
|
79
|
-
* const res = await compact(
|
|
80
|
-
* { storage, currentJsonKey: "app/x/tenant/t/manifests/tickets/current.json" },
|
|
81
|
-
* { minEntriesToCompact: 100, maxEntriesPerRun: 40 },
|
|
82
|
-
* );
|
|
83
|
-
* if (res.written) console.log("snapshot landed at", res.newSnapshotKey);
|
|
84
|
-
* ```
|
|
85
|
-
*/
|
|
86
|
-
declare const compact: (args: {
|
|
87
|
-
storage: Storage; /** Full bucket-relative key of the CAS pointer. */
|
|
88
|
-
currentJsonKey: string;
|
|
89
|
-
}, options?: CompactOptions) => Promise<CompactResult>;
|
|
90
|
-
//#endregion
|
|
91
|
-
//#region packages/server/src/gc.d.ts
|
|
92
|
-
/**
|
|
93
|
-
* Public tunables for {@link runGc}. All optional; the engine works
|
|
94
|
-
* unbounded by default. Opt into per-run caps via the
|
|
95
|
-
* `CLOUDFLARE_FREE_TIER` profile (from `./maintenance.ts`) or by
|
|
96
|
-
* reaching for {@link InternalRunGcOptions} via the
|
|
97
|
-
* `@baerly/server/_internal/testing` subpath.
|
|
98
|
-
*/
|
|
99
|
-
interface RunGcOptions {
|
|
100
|
-
readonly signal?: AbortSignal;
|
|
101
|
-
}
|
|
102
|
-
/**
|
|
103
|
-
* Internal-only widening of {@link RunGcOptions}. Surfaced via the
|
|
104
|
-
* `@baerly/server/_internal/testing` subpath (NOT in the published
|
|
105
|
-
* `publishConfig.exports`); production callers should use
|
|
106
|
-
* {@link RunGcOptions}.
|
|
107
|
-
*
|
|
108
|
-
* @internal
|
|
109
|
-
*/
|
|
110
|
-
interface InternalRunGcOptions extends RunGcOptions {
|
|
111
|
-
/**
|
|
112
|
-
* @internal Override grace-period for tests. Defaults to
|
|
113
|
-
* {@link GC_GRACE_PERIOD_MILLIS} (7 days). Tests use `0` to bypass
|
|
114
|
-
* the grace and exercise the sweep path in one pass.
|
|
115
|
-
*/
|
|
116
|
-
readonly graceMillis?: number;
|
|
117
|
-
/**
|
|
118
|
-
* @internal Budget cap on candidates marked per category per run.
|
|
119
|
-
* `CLOUDFLARE_FREE_TIER` sets it; bounds LIST + classification
|
|
120
|
-
* cost per pass. The default is effectively unbounded
|
|
121
|
-
* (`Number.MAX_SAFE_INTEGER`).
|
|
122
|
-
*/
|
|
123
|
-
readonly maxMarksPerRun?: number;
|
|
124
|
-
/**
|
|
125
|
-
* @internal Budget cap on keys deleted per run.
|
|
126
|
-
* `CLOUDFLARE_FREE_TIER` sets it — CF free-tier safe when paired
|
|
127
|
-
* with `compact()` in the same scheduled handler. The default is
|
|
128
|
-
* effectively unbounded (`Number.MAX_SAFE_INTEGER`).
|
|
129
|
-
*/
|
|
130
|
-
readonly maxSweepsPerRun?: number;
|
|
131
|
-
/**
|
|
132
|
-
* @internal Clock injection for tests. Defaults to
|
|
133
|
-
* `() => new Date()`. The function is invoked at mark time (to
|
|
134
|
-
* compute `due_at` when `lastModified` is absent) and at sweep
|
|
135
|
-
* time (to compare against candidate `due_at`).
|
|
136
|
-
*/
|
|
137
|
-
readonly now?: () => Date;
|
|
138
|
-
}
|
|
139
|
-
/**
|
|
140
|
-
* Return shape of {@link runGc}.
|
|
141
|
-
*/
|
|
142
|
-
interface RunGcResult {
|
|
143
|
-
/** Per-category counts of newly-marked candidates in this pass. */
|
|
144
|
-
readonly marked: {
|
|
145
|
-
readonly stale_log: number;
|
|
146
|
-
readonly orphan_snapshot: number;
|
|
147
|
-
readonly orphan_content: number;
|
|
148
|
-
};
|
|
149
|
-
/** Number of keys deleted in this pass. */
|
|
150
|
-
readonly swept: number;
|
|
151
|
-
/**
|
|
152
|
-
* Depth of `gc/pending.json` after this pass. Drives the
|
|
153
|
-
* `db.orphan.candidate_count` metric. Best-effort on `cas-lost` —
|
|
154
|
-
* see module JSDoc.
|
|
155
|
-
*/
|
|
156
|
-
readonly pendingDepth: number;
|
|
157
|
-
}
|
|
158
|
-
/**
|
|
159
|
-
* Single GC pass — mark new orphans, sweep due-elapsed candidates,
|
|
160
|
-
* persist via CAS-update on `gc/pending.json`.
|
|
161
|
-
*
|
|
162
|
-
* Returns immediately if `current.json` is missing — there's nothing
|
|
163
|
-
* to do until a writer has bootstrapped the collection.
|
|
164
|
-
*
|
|
165
|
-
* @example
|
|
166
|
-
* ```ts
|
|
167
|
-
* import { runGc } from "@gusto/baerly-storage";
|
|
168
|
-
*
|
|
169
|
-
* const r = await runGc({ storage, currentJsonKey });
|
|
170
|
-
* console.log(`marked ${r.marked.stale_log} stale logs, swept ${r.swept}`);
|
|
171
|
-
* ```
|
|
172
|
-
*/
|
|
173
|
-
declare const runGc: (args: {
|
|
174
|
-
storage: Storage;
|
|
175
|
-
currentJsonKey: string;
|
|
176
|
-
}, options?: RunGcOptions) => Promise<RunGcResult>;
|
|
177
|
-
//#endregion
|
|
178
|
-
//#region packages/server/src/rebuild-index.d.ts
|
|
179
|
-
/**
|
|
180
|
-
* Reconciliation summary.
|
|
181
|
-
*
|
|
182
|
-
* In a normal (mutating) run, the counts describe what was actually
|
|
183
|
-
* PUT / DELETEd. In `dryRun` mode ({@link RebuildIndexOptions.dryRun}),
|
|
184
|
-
* `added` / `removed` report the counts that a real rebuild *would*
|
|
185
|
-
* have produced — storage is unchanged. `kept` counts pre-existing
|
|
186
|
-
* intersection keys (`expected ∩ actual`) at function entry. In a real
|
|
187
|
-
* run, `kept` may also include keys promoted from `added` via the
|
|
188
|
-
* Conflict-race fallback (a PUT with `ifNoneMatch:"*"` returned 412
|
|
189
|
-
* because a peer wrote the same key first, so the key was already
|
|
190
|
-
* in place by the time we observed it); dryRun mode never issues
|
|
191
|
-
* those PUTs and therefore does not observe that race.
|
|
192
|
-
*/
|
|
193
|
-
interface RebuildIndexResult {
|
|
194
|
-
/**
|
|
195
|
-
* Keys PUT because they were missing on storage. In `dryRun` mode,
|
|
196
|
-
* the predicted PUT count — no writes were issued.
|
|
197
|
-
*/
|
|
198
|
-
readonly added: number;
|
|
199
|
-
/**
|
|
200
|
-
* Keys DELETEd because the doc no longer exists / no longer projects
|
|
201
|
-
* them. In `dryRun` mode, the predicted DELETE count — no deletes
|
|
202
|
-
* were issued.
|
|
203
|
-
*/
|
|
204
|
-
readonly removed: number;
|
|
205
|
-
/** Keys already in place. The healthy-index re-run reports this as the full expected count. */
|
|
206
|
-
readonly kept: number;
|
|
207
|
-
}
|
|
208
|
-
/**
|
|
209
|
-
* Optional knobs accepted by {@link rebuildIndex}. Every field is
|
|
210
|
-
* optional; the function behaves identically to the older
|
|
211
|
-
* positional-arg shape when `opts` is omitted.
|
|
212
|
-
*
|
|
213
|
-
* @public — surfaced from `baerly-storage` so admin tooling and the
|
|
214
|
-
* observability layer can opt in.
|
|
215
|
-
*/
|
|
216
|
-
interface RebuildIndexOptions {
|
|
217
|
-
/**
|
|
218
|
-
* Cancellation signal. Forwarded to every storage `list` call so
|
|
219
|
-
* long-running rebuilds over large collections can be cut short
|
|
220
|
-
* by admin tooling. Storage `get` / `put` / `delete` calls inside
|
|
221
|
-
* the reconciliation loop do not currently honour the signal
|
|
222
|
-
* (the per-call durations are short enough that cooperative
|
|
223
|
-
* cancellation between calls suffices); future tightening can
|
|
224
|
-
* forward it through without breaking callers.
|
|
225
|
-
*/
|
|
226
|
-
readonly signal?: AbortSignal;
|
|
227
|
-
/**
|
|
228
|
-
* When `true`, walk the expected-vs-actual diff and return the
|
|
229
|
-
* counts that a real rebuild would have produced WITHOUT issuing
|
|
230
|
-
* any PUT or DELETE. Used by `baerly admin fsck --indexes`
|
|
231
|
-
* to report drift cheaply. Defaults to `false`.
|
|
232
|
-
*
|
|
233
|
-
* `kept` is reported as the pre-existing intersection
|
|
234
|
-
* (`expected ∩ actual`); a real run can additionally fold
|
|
235
|
-
* Conflict-race-demoted PUTs into `kept`, which dryRun does not
|
|
236
|
-
* observe. See {@link RebuildIndexResult}.
|
|
237
|
-
*/
|
|
238
|
-
readonly dryRun?: boolean;
|
|
239
|
-
}
|
|
240
|
-
/**
|
|
241
|
-
* Idempotently reconcile one secondary index for one collection.
|
|
242
|
-
*
|
|
243
|
-
* @param storage Storage handle (any in-tree `Storage`).
|
|
244
|
-
* @param currentJsonKey The collection's `current.json` key.
|
|
245
|
-
* @param def The index to reconcile. Single-field today;
|
|
246
|
-
* composite definitions are accepted by the
|
|
247
|
-
* key encoder but the read path only consults
|
|
248
|
-
* single-field keys.
|
|
249
|
-
* @param opts Optional knobs — see {@link RebuildIndexOptions}.
|
|
250
|
-
* Strictly additive: existing positional-arg
|
|
251
|
-
* callers compile and behave unchanged when
|
|
252
|
-
* omitted.
|
|
253
|
-
*
|
|
254
|
-
* @throws BaerlyError code="InvalidResponse" — `current.json` missing.
|
|
255
|
-
* @throws BaerlyError code="Internal" — protocol-invariant
|
|
256
|
-
* violation (snapshot hash mismatch, missing log entry inside
|
|
257
|
-
* `[log_seq_start, next_seq)`).
|
|
258
|
-
*/
|
|
259
|
-
declare const rebuildIndex: (storage: Storage, currentJsonKey: string, def: IndexDefinition, opts?: RebuildIndexOptions) => Promise<RebuildIndexResult>;
|
|
260
|
-
//#endregion
|
|
261
|
-
//#region packages/server/src/maintenance.d.ts
|
|
262
|
-
interface MaintenanceArgs {
|
|
263
|
-
readonly storage: Storage;
|
|
264
|
-
/** Full bucket-relative key of the CAS pointer for the target collection. */
|
|
265
|
-
readonly currentJsonKey: string;
|
|
266
|
-
}
|
|
267
|
-
interface MaintenanceOptions {
|
|
268
|
-
/** Forwarded to `compact()`. */
|
|
269
|
-
readonly compact?: CompactOptions;
|
|
270
|
-
/** Forwarded to `runGc()`. */
|
|
271
|
-
readonly gc?: RunGcOptions;
|
|
272
|
-
/** Forwarded to both primitives. */
|
|
273
|
-
readonly signal?: AbortSignal;
|
|
274
|
-
}
|
|
275
|
-
/**
|
|
276
|
-
* Internal-only widening of {@link MaintenanceOptions}. Surfaced via
|
|
277
|
-
* the `@baerly/server/_internal/testing` subpath (NOT in the
|
|
278
|
-
* published `publishConfig.exports`); production callers should use
|
|
279
|
-
* {@link MaintenanceOptions}.
|
|
280
|
-
*
|
|
281
|
-
* @internal
|
|
282
|
-
*/
|
|
283
|
-
interface InternalMaintenanceOptions extends MaintenanceOptions {
|
|
284
|
-
/** @internal Internal compact options (budget caps). */
|
|
285
|
-
readonly compact?: InternalCompactOptions;
|
|
286
|
-
/** @internal Internal GC options (budget caps + clock seam + grace). */
|
|
287
|
-
readonly gc?: InternalRunGcOptions;
|
|
288
|
-
}
|
|
289
|
-
interface MaintenanceResult {
|
|
290
|
-
readonly compact: CompactResult;
|
|
291
|
-
readonly gc: RunGcResult;
|
|
292
|
-
}
|
|
293
|
-
/**
|
|
294
|
-
* Single maintenance pass for one collection. Runs `compact()` then
|
|
295
|
-
* `runGc()` (in that order; the compactor's advance of
|
|
296
|
-
* `log_seq_start` produces the stale-log candidates the GC then
|
|
297
|
-
* marks). Callers wanting a single phase per tick invoke
|
|
298
|
-
* `compact()` or `runGc()` directly instead.
|
|
299
|
-
*
|
|
300
|
-
* Errors propagate — the caller's cron handler is responsible for
|
|
301
|
-
* logging them. The Cloudflare runtime ships uncaught Worker errors
|
|
302
|
-
* to the dashboard; Node operators wrap their `node-cron` callbacks
|
|
303
|
-
* themselves.
|
|
304
|
-
*
|
|
305
|
-
* @example
|
|
306
|
-
* ```ts
|
|
307
|
-
* import { runScheduledMaintenance, CLOUDFLARE_FREE_TIER } from "@gusto/baerly-storage/maintenance";
|
|
308
|
-
*
|
|
309
|
-
* // Node (unbounded — defaults fold the entire live tail):
|
|
310
|
-
* const res = await runScheduledMaintenance(
|
|
311
|
-
* { storage, currentJsonKey: "app/x/tenant/t/manifests/tickets/current.json" },
|
|
312
|
-
* );
|
|
313
|
-
* console.log("compacted:", res.compact.entriesFolded, "swept:", res.gc.swept);
|
|
314
|
-
*
|
|
315
|
-
* // Cloudflare free tier (50-subrequest cap, single phase per tick):
|
|
316
|
-
* await runScheduledMaintenance({ storage, currentJsonKey }, CLOUDFLARE_FREE_TIER);
|
|
317
|
-
* ```
|
|
318
|
-
*/
|
|
319
|
-
declare const runScheduledMaintenance: (args: MaintenanceArgs, options?: MaintenanceOptions) => Promise<MaintenanceResult>;
|
|
320
|
-
declare const CLOUDFLARE_FREE_TIER: MaintenanceOptions;
|
|
321
|
-
//#endregion
|
|
322
|
-
export { CLOUDFLARE_FREE_TIER, type CompactOptions, type CompactResult, InternalMaintenanceOptions, MaintenanceArgs, MaintenanceOptions, MaintenanceResult, type RebuildIndexOptions, type RebuildIndexResult, type RunGcOptions, type RunGcResult, compact, rebuildIndex, runGc, runScheduledMaintenance };
|
|
323
|
-
//# sourceMappingURL=maintenance.d.ts.map
|
|
1
|
+
import { _ as RunGcResult, a as MaintenanceDispatch, b as CompactResult, c as crossesGcBoundary, d as runScheduledMaintenance, f as shouldFireMaintenance, g as RunGcOptions, h as rebuildIndex, i as MaintenanceArgs, l as dispatchInlineAwaited, m as RebuildIndexResult, n as CLOUDFLARE_FREE_TIER, o as MaintenanceOptions, p as RebuildIndexOptions, r as InternalMaintenanceOptions, s as MaintenanceResult, t as BoundedMaintenanceOptions, u as runBoundedMaintenance, v as runGc, x as compact, y as CompactOptions } from "./maintenance-BRrThz8V.js";
|
|
2
|
+
export { BoundedMaintenanceOptions, CLOUDFLARE_FREE_TIER, type CompactOptions, type CompactResult, InternalMaintenanceOptions, MaintenanceArgs, MaintenanceDispatch, MaintenanceOptions, MaintenanceResult, type RebuildIndexOptions, type RebuildIndexResult, type RunGcOptions, type RunGcResult, compact, crossesGcBoundary, dispatchInlineAwaited, rebuildIndex, runBoundedMaintenance, runGc, runScheduledMaintenance, shouldFireMaintenance };
|
package/dist/maintenance.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import { a as
|
|
2
|
-
export { CLOUDFLARE_FREE_TIER, compact, rebuildIndex, runGc, runScheduledMaintenance };
|
|
1
|
+
import { a as runScheduledMaintenance, c as runGc, i as runBoundedMaintenance, l as compact, n as crossesGcBoundary, o as shouldFireMaintenance, r as dispatchInlineAwaited, s as rebuildIndex, t as CLOUDFLARE_FREE_TIER } from "./maintenance-ClzBC1Vv.js";
|
|
2
|
+
export { CLOUDFLARE_FREE_TIER, compact, crossesGcBoundary, dispatchInlineAwaited, rebuildIndex, runBoundedMaintenance, runGc, runScheduledMaintenance, shouldFireMaintenance };
|
package/dist/node.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import { n as BaerlyAppConfig } from "./app-config-
|
|
2
|
-
import { _ as
|
|
3
|
-
import { i as DevLandingOptions } from "./index-
|
|
4
|
-
import { d as ObservabilityConfig } from "./index-
|
|
1
|
+
import { n as BaerlyAppConfig } from "./app-config-C0Bbw_Z6.js";
|
|
2
|
+
import { _ as StorageGetResult, b as StoragePutResult, g as StorageGetOptions, h as Storage, r as Verifier, v as StorageListEntry, y as StoragePutOptions } from "./index-DSvwEUeF.js";
|
|
3
|
+
import { i as DevLandingOptions } from "./index-DwDTWPSU.js";
|
|
4
|
+
import { d as ObservabilityConfig } from "./index-C3JAH1Yo.js";
|
|
5
5
|
|
|
6
6
|
//#region packages/adapter-node/src/s3-http.d.ts
|
|
7
7
|
/**
|
|
@@ -59,44 +59,6 @@ declare class S3HttpStorage implements Storage {
|
|
|
59
59
|
}): AsyncIterable<StorageListEntry>;
|
|
60
60
|
}
|
|
61
61
|
//#endregion
|
|
62
|
-
//#region packages/adapter-node/src/server.d.ts
|
|
63
|
-
/**
|
|
64
|
-
* Options for {@link runMaintenanceTick}.
|
|
65
|
-
*/
|
|
66
|
-
interface NodeMaintenanceOptions {
|
|
67
|
-
/** Any {@link Storage} impl — `S3HttpStorage`, `LocalFsStorage`, etc. */
|
|
68
|
-
readonly storage: Storage;
|
|
69
|
-
/** Full bucket-relative key of the CAS pointer for the target collection. */
|
|
70
|
-
readonly currentJsonKey: string;
|
|
71
|
-
/** Forwarded to both `compact()` and `runGc()` underneath. */
|
|
72
|
-
readonly signal?: AbortSignal;
|
|
73
|
-
}
|
|
74
|
-
/**
|
|
75
|
-
* Run one pass of compaction + GC for one collection. Node hosts have
|
|
76
|
-
* no subrequest cap, so this uses the engine defaults (unbounded) —
|
|
77
|
-
* a single pass folds the entire live tail and sweeps every aged-out
|
|
78
|
-
* candidate.
|
|
79
|
-
*
|
|
80
|
-
* Pair with `node-cron`, systemd timers, or k8s CronJobs — this
|
|
81
|
-
* function is a single-shot callable that does not loop. Errors
|
|
82
|
-
* propagate; the caller decides retry semantics.
|
|
83
|
-
*
|
|
84
|
-
* `compact()` and `runGc()` are each CAS-protected single-attempts:
|
|
85
|
-
* a crash or restart between phases is safe because the next tick
|
|
86
|
-
* picks up where the previous one left off.
|
|
87
|
-
*
|
|
88
|
-
* @example
|
|
89
|
-
* ```ts
|
|
90
|
-
* import cron from "node-cron";
|
|
91
|
-
* import { runMaintenanceTick } from "@gusto/baerly-storage/node";
|
|
92
|
-
*
|
|
93
|
-
* cron.schedule("0 * * * *", async () => { // hourly
|
|
94
|
-
* await runMaintenanceTick({ storage, currentJsonKey: "..." });
|
|
95
|
-
* });
|
|
96
|
-
* ```
|
|
97
|
-
*/
|
|
98
|
-
declare const runMaintenanceTick: (opts: NodeMaintenanceOptions) => Promise<void>;
|
|
99
|
-
//#endregion
|
|
100
62
|
//#region packages/adapter-node/src/credentials/types.d.ts
|
|
101
63
|
/**
|
|
102
64
|
* Temporary or static AWS-shaped credentials. Field shape matches
|
|
@@ -280,25 +242,11 @@ declare function fromEksPodIdentity(opts?: {
|
|
|
280
242
|
}): CredentialsProvider;
|
|
281
243
|
//#endregion
|
|
282
244
|
//#region packages/adapter-node/src/baerly-node.d.ts
|
|
283
|
-
/**
|
|
284
|
-
* Multi-collection maintenance schedule. Each tick spawns one
|
|
285
|
-
* {@link runMaintenanceTick} call per `(tenant, collection)` pair. The
|
|
286
|
-
* cross-product is computed once at startup; deletions / additions
|
|
287
|
-
* at runtime require restarting the process.
|
|
288
|
-
*
|
|
289
|
-
* `intervalMs` defaults to one hour, matching the per-template
|
|
290
|
-
* `setInterval` cadence the helper replaces.
|
|
291
|
-
*/
|
|
292
|
-
interface BaerlyNodeMaintenance {
|
|
293
|
-
readonly collections: readonly string[];
|
|
294
|
-
readonly tenants: readonly string[];
|
|
295
|
-
readonly intervalMs?: number;
|
|
296
|
-
}
|
|
297
245
|
/**
|
|
298
246
|
* Options for {@link baerlyNode}. Composes the {@link createApp}
|
|
299
247
|
* surface (same `app` / `storage` / `verifier` / `webRoot` / etc.)
|
|
300
|
-
* with
|
|
301
|
-
*
|
|
248
|
+
* with a `node:http` server lifecycle (`listen` / `close` +
|
|
249
|
+
* SIGTERM/SIGINT handling).
|
|
302
250
|
*
|
|
303
251
|
* Mirrors `baerlyWorker` in `@baerly/adapter-cloudflare`.
|
|
304
252
|
*/
|
|
@@ -339,13 +287,6 @@ interface BaerlyNodeOptions {
|
|
|
339
287
|
readonly webRoot?: string;
|
|
340
288
|
readonly sinceTimeoutMs?: number;
|
|
341
289
|
readonly sincePollIntervalMs?: number;
|
|
342
|
-
/**
|
|
343
|
-
* Multi-collection maintenance schedule. Each tick fires one
|
|
344
|
-
* {@link runMaintenanceTick} per `(tenant, collection)` pair. Omit
|
|
345
|
-
* to skip the in-process maintenance loop (operator wires their own
|
|
346
|
-
* scheduler — k8s CronJob, systemd timer, etc).
|
|
347
|
-
*/
|
|
348
|
-
readonly maintenance?: BaerlyNodeMaintenance;
|
|
349
290
|
}
|
|
350
291
|
/**
|
|
351
292
|
* Handle returned by {@link baerlyNode}. Composes a running
|
|
@@ -363,9 +304,9 @@ interface BaerlyNodeOptions {
|
|
|
363
304
|
* handlers that call `close()` and exit `0`, and resolves once
|
|
364
305
|
* the server is actually listening (after Node's `'listening'`
|
|
365
306
|
* event fires). Throws on `'error'` from the server.
|
|
366
|
-
* - `close()` closes the server
|
|
367
|
-
*
|
|
368
|
-
*
|
|
307
|
+
* - `close()` closes the server and removes the signal handlers.
|
|
308
|
+
* Resolves once `Server.close` callback fires. Safe to call
|
|
309
|
+
* multiple times.
|
|
369
310
|
*/
|
|
370
311
|
interface BaerlyNodeHandle {
|
|
371
312
|
readonly fetch: (request: Request) => Response | Promise<Response>;
|
|
@@ -380,19 +321,20 @@ interface BaerlyNodeHandle {
|
|
|
380
321
|
* - {@link createApp} → exposed as `handle.fetch` for in-process
|
|
381
322
|
* embedding; wrapped in `@hono/node-server.serve({ fetch, createServer })`
|
|
382
323
|
* lazily when `listen()` is called.
|
|
383
|
-
* - Optional maintenance loop: each `intervalMs` tick fires one
|
|
384
|
-
* {@link runMaintenanceTick} per `(tenant, collection)` pair
|
|
385
|
-
* (cross-product of `opts.maintenance.tenants` × `.collections`).
|
|
386
|
-
* The `currentJsonKey` is composed as
|
|
387
|
-
* `app/<app>/tenant/<tenant>/manifests/<collection>/current.json` —
|
|
388
|
-
* the canonical layout from the sync protocol.
|
|
389
324
|
* - SIGTERM + SIGINT handlers installed on `listen()` that call
|
|
390
325
|
* `close()` and `process.exit(0)`. On any error during close,
|
|
391
326
|
* `process.exit(1)`.
|
|
392
327
|
*
|
|
393
|
-
*
|
|
394
|
-
*
|
|
395
|
-
* a
|
|
328
|
+
* **Maintenance is in-band, not scheduled.** There is no `setInterval`,
|
|
329
|
+
* no cron, and no `maintenance:` option: the kernel maintains itself on
|
|
330
|
+
* a bare bucket with zero operator infrastructure. Compaction + GC run
|
|
331
|
+
* INLINE on the (rare) write that crosses a maintenance trigger —
|
|
332
|
+
* `createFetchHandler` threads a Node-tier `MaintenanceDispatch`
|
|
333
|
+
* onto the per-request observability context, which the writer reads at
|
|
334
|
+
* its post-CAS dispatch point. Reads never tick. Tune via the
|
|
335
|
+
* `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` / `BAERLY_MAINTENANCE_DISABLE`
|
|
336
|
+
* env vars; for an explicit out-of-band sweep, call
|
|
337
|
+
* `runScheduledMaintenance` from `@gusto/baerly-storage` directly.
|
|
396
338
|
*
|
|
397
339
|
* @example
|
|
398
340
|
* ```ts
|
|
@@ -411,12 +353,11 @@ interface BaerlyNodeHandle {
|
|
|
411
353
|
* }),
|
|
412
354
|
* // No verifier needed when config.auth is "none" or "shared-secret".
|
|
413
355
|
* webRoot: "./dist/client",
|
|
414
|
-
* maintenance: { collections: ["tickets", "comments"], tenants: ["acme"] },
|
|
415
356
|
* });
|
|
416
357
|
* await handle.listen(Number(process.env["PORT"] ?? 8080));
|
|
417
358
|
* ```
|
|
418
359
|
*/
|
|
419
360
|
declare function baerlyNode(opts: BaerlyNodeOptions): BaerlyNodeHandle;
|
|
420
361
|
//#endregion
|
|
421
|
-
export { type BaerlyNodeHandle, type
|
|
362
|
+
export { type BaerlyNodeHandle, type BaerlyNodeOptions, type Credentials, type CredentialsProvider, S3HttpStorage, type S3HttpStorageOptions, baerlyNode, fromEksPodIdentity, gcsStorage, minioStorage, r2Storage, s3Storage };
|
|
422
363
|
//# sourceMappingURL=node.d.ts.map
|
package/dist/node.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import { a as minioStorage, c as
|
|
2
|
-
export { S3HttpStorage, baerlyNode, fromEksPodIdentity, gcsStorage, minioStorage, r2Storage,
|
|
1
|
+
import { a as minioStorage, c as S3HttpStorage, i as gcsStorage, o as r2Storage, r as fromEksPodIdentity, s as s3Storage, t as baerlyNode } from "./src-DU1sCMlr.js";
|
|
2
|
+
export { S3HttpStorage, baerlyNode, fromEksPodIdentity, gcsStorage, minioStorage, r2Storage, s3Storage };
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { n as __exportAll } from "./chunk-EAsCxrDo.js";
|
|
2
2
|
import { t as BaerlyError } from "./errors-DOdL95kK.js";
|
|
3
|
-
import { i as noopMetricsRecorder, n as getCurrentContext, r as runWithContext, t as createObservabilityContext } from "./context-
|
|
3
|
+
import { i as noopMetricsRecorder, n as getCurrentContext, r as runWithContext, t as createObservabilityContext } from "./context-DRZ3tZ5l.js";
|
|
4
4
|
//#region packages/server/src/contract.ts
|
|
5
5
|
/**
|
|
6
6
|
* Single drift surface for the {@link HttpErrorEnvelope} shape. The
|
|
@@ -2330,4 +2330,4 @@ const observableStorage = (inner) => {
|
|
|
2330
2330
|
//#endregion
|
|
2331
2331
|
export { withHttpObservability as a, configureObservability as c, serializeError as i, getLogger as l, flushCanonicalLine as n, deriveOutcome as o, flushUnauthorizedAndRespond as r, CATEGORY as s, observableStorage as t, errorEnvelope as u };
|
|
2332
2332
|
|
|
2333
|
-
//# sourceMappingURL=observability-
|
|
2333
|
+
//# sourceMappingURL=observability-CpOiEN0k.js.map
|