@gusto/baerly-storage 0.3.0 → 0.4.1
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 +157 -92
- package/dist/API.md +64 -32
- package/dist/CHANGELOG.md +301 -5
- package/dist/RECIPES.md +125 -0
- package/dist/THIRD-PARTY-LICENSES.txt +22 -96
- package/dist/{app-config-BIzyAKzy.d.ts → app-config-DyiFK3_k.d.ts} +43 -11
- package/dist/app-config.d.ts +1 -1
- package/dist/auth.d.ts +1 -1
- package/dist/auth.js +13 -13
- package/dist/auth.js.map +1 -1
- package/dist/aws4fetch.esm-p7eEzLCs.js +1702 -0
- package/dist/aws4fetch.esm-p7eEzLCs.js.map +1 -0
- package/dist/baerly.js +35 -15
- package/dist/baerly.js.map +1 -1
- package/dist/baerly.spec.json +342 -0
- package/dist/{client-BJXF3XJA.d.ts → client-Fe8CwB73.d.ts} +3 -3
- package/dist/client-react.d.ts +3 -3
- package/dist/client-react.js +4 -4
- package/dist/client-react.js.map +1 -1
- package/dist/client.d.ts +4 -4
- package/dist/client.js +3 -3
- package/dist/{cloudflare-Cn2ibODt.js → cloudflare-DzKBrUlg.js} +2 -2
- package/dist/{cloudflare-Cn2ibODt.js.map → cloudflare-DzKBrUlg.js.map} +1 -1
- package/dist/cloudflare.d.ts +49 -6
- package/dist/cloudflare.js +55 -21
- package/dist/cloudflare.js.map +1 -1
- package/dist/config-1tv0-Yzm.js +2693 -0
- package/dist/config-1tv0-Yzm.js.map +1 -0
- package/dist/constants-CfeMWQWk.js +222 -0
- package/dist/constants-CfeMWQWk.js.map +1 -0
- package/dist/{cost-BZ_MDBmn.js → cost-DSMIVqzL.js} +42 -43
- package/dist/cost-DSMIVqzL.js.map +1 -0
- package/dist/{current-json-DsN7FNY1.js → current-json-C6nhPOm1.js} +6 -204
- package/dist/current-json-C6nhPOm1.js.map +1 -0
- package/dist/{db-CCT6tDfY.d.ts → db-DsPkOVEH.d.ts} +3 -3
- package/dist/{deploy-BKKyGlSJ.js → deploy-DonTr-CV.js} +4 -4
- package/dist/{deploy-BKKyGlSJ.js.map → deploy-DonTr-CV.js.map} +1 -1
- package/dist/dev-vite.d.ts +9 -5
- package/dist/dev-vite.js +5 -4
- package/dist/dev-vite.js.map +1 -1
- package/dist/dev.d.ts +1 -1
- package/dist/dev.js +1 -1
- package/dist/{doctor-BVU4GNXN.js → doctor-DSIyCDg_.js} +5 -8
- package/dist/{doctor-BVU4GNXN.js.map → doctor-DSIyCDg_.js.map} +1 -1
- package/dist/{dump-DPEAKub6.js → dump-Bh5k26VQ.js} +9 -32
- package/dist/dump-Bh5k26VQ.js.map +1 -0
- package/dist/{errors-DOdL95kK.js → errors-Dfa3p78c.js} +25 -5
- package/dist/errors-Dfa3p78c.js.map +1 -0
- package/dist/{export-BcuCLFFe.js → export-DtF5tDIM.js} +9 -32
- package/dist/{export-BcuCLFFe.js.map → export-DtF5tDIM.js.map} +1 -1
- package/dist/{fsck-RXgLOaJG.js → fsck-D_djMO5D.js} +10 -33
- package/dist/fsck-D_djMO5D.js.map +1 -0
- package/dist/{http-Bd4byR4n.js → http-DxM9MflO.js} +123 -35
- package/dist/http-DxM9MflO.js.map +1 -0
- package/dist/http.d.ts +42 -26
- package/dist/http.js +3 -2
- package/dist/{index-DnBGSeuU.d.ts → index-0rZcMBwy.d.ts} +2 -2
- package/dist/{index-Cmsxx-ZN.d.ts → index-B6oexfOB.d.ts} +7 -7
- package/dist/{index-BDceQQi-.d.ts → index-BNRh23K9.d.ts} +4 -4
- package/dist/{index-DW7GT6M2.d.ts → index-BYk9oCNf.d.ts} +193 -163
- package/dist/index.d.ts +6 -6
- package/dist/index.js +4 -4
- package/dist/{indexes-Cx7uMXm0.d.ts → indexes-Dn9hbGQG.d.ts} +2 -2
- package/dist/{inspect-DhI49PSi.js → inspect-6WZ-pC7-.js} +10 -33
- package/dist/inspect-6WZ-pC7-.js.map +1 -0
- package/dist/key-Di6yyxFu.js +35 -0
- package/dist/key-Di6yyxFu.js.map +1 -0
- package/dist/{log-tail-DXeDkWEp.js → log-tail-D98U1JBo.js} +31 -7
- package/dist/log-tail-D98U1JBo.js.map +1 -0
- package/dist/{maintenance-CWBQpZ2y.js → maintenance-B4Dki6Ig.js} +77 -22
- package/dist/maintenance-B4Dki6Ig.js.map +1 -0
- package/dist/{maintenance-BkhUr72A.d.ts → maintenance-B_e0T99L.d.ts} +28 -5
- package/dist/{maintenance-C_KSkVjd.js → maintenance-C7coQp4c.js} +17 -16
- package/dist/maintenance-C7coQp4c.js.map +1 -0
- package/dist/maintenance.d.ts +3 -3
- package/dist/maintenance.js +3 -3
- package/dist/node.d.ts +168 -65
- package/dist/node.js +3 -2
- package/dist/{normalize-XWY25_sG.js → normalize-rjnZLwS4.js} +2 -2
- package/dist/normalize-rjnZLwS4.js.map +1 -0
- package/dist/{observability-BYd-RzEx.js → observability-wzs3-BL_.js} +233 -71
- package/dist/observability-wzs3-BL_.js.map +1 -0
- package/dist/observability.d.ts +2 -2
- package/dist/observability.js +1 -1
- package/dist/{plan-DIu_B6fy.js → plan-a7PJHBCy.js} +2 -2
- package/dist/{plan-DIu_B6fy.js.map → plan-a7PJHBCy.js.map} +1 -1
- package/dist/{query-sQNO5vU_.js → query-rAtXNQQB.js} +96 -207
- package/dist/query-rAtXNQQB.js.map +1 -0
- package/dist/{rebuild-index-DP4CqSSs.js → rebuild-index-BVzQSZlm.js} +9 -32
- package/dist/rebuild-index-BVzQSZlm.js.map +1 -0
- package/dist/{request-BEF_OvMh.js → request-u0M51mhJ.js} +3 -3
- package/dist/{request-BEF_OvMh.js.map → request-u0M51mhJ.js.map} +1 -1
- package/dist/{restore-DpQYef6r.js → restore-R-4rbciV.js} +73 -100
- package/dist/restore-R-4rbciV.js.map +1 -0
- package/dist/runtime-spec-_GTdeSMo.js +391 -0
- package/dist/runtime-spec-_GTdeSMo.js.map +1 -0
- package/dist/s3-http-B-z8th6O.d.ts +60 -0
- package/dist/s3.d.ts +47 -0
- package/dist/s3.js +45 -0
- package/dist/s3.js.map +1 -0
- package/dist/{shared-secret-BJdSwpgw.js → shared-secret-DgEicd3x.js} +13 -5
- package/dist/shared-secret-DgEicd3x.js.map +1 -0
- package/dist/{src-Db4-qVtM.js → src-CYHFDrKz.js} +51 -8
- package/dist/src-CYHFDrKz.js.map +1 -0
- package/dist/{src-CWpkSbvJ.js → src-DYZ4H1aF.js} +6 -5
- package/dist/src-DYZ4H1aF.js.map +1 -0
- package/dist/src-D__mHQmQ.js +2271 -0
- package/dist/src-D__mHQmQ.js.map +1 -0
- package/dist/{subcommand-CP9NY2J4.js → subcommand-DoDA-K7d.js} +44 -6
- package/dist/subcommand-DoDA-K7d.js.map +1 -0
- package/dist/time-DUqvFMHq.js +119 -0
- package/dist/time-DUqvFMHq.js.map +1 -0
- package/dist/{usage-CTfDq9HR.js → usage-DBV1eQHC.js} +7 -22
- package/dist/usage-DBV1eQHC.js.map +1 -0
- package/dist/wire-izfGZDvr.js.map +1 -1
- package/package.json +51 -27
- package/dist/config-CGyBopy3.js +0 -5326
- package/dist/config-CGyBopy3.js.map +0 -1
- package/dist/cost-BZ_MDBmn.js.map +0 -1
- package/dist/current-json-DsN7FNY1.js.map +0 -1
- package/dist/dump-DPEAKub6.js.map +0 -1
- package/dist/errors-DOdL95kK.js.map +0 -1
- package/dist/fsck-RXgLOaJG.js.map +0 -1
- package/dist/http-Bd4byR4n.js.map +0 -1
- package/dist/inspect-DhI49PSi.js.map +0 -1
- package/dist/log-tail-DXeDkWEp.js.map +0 -1
- package/dist/maintenance-CWBQpZ2y.js.map +0 -1
- package/dist/maintenance-C_KSkVjd.js.map +0 -1
- package/dist/normalize-XWY25_sG.js.map +0 -1
- package/dist/observability-BYd-RzEx.js.map +0 -1
- package/dist/query-sQNO5vU_.js.map +0 -1
- package/dist/rebuild-index-DP4CqSSs.js.map +0 -1
- package/dist/restore-DpQYef6r.js.map +0 -1
- package/dist/shared-secret-BJdSwpgw.js.map +0 -1
- package/dist/src-CWpkSbvJ.js.map +0 -1
- package/dist/src-D24wDpzR.js +0 -6247
- package/dist/src-D24wDpzR.js.map +0 -1
- package/dist/src-Db4-qVtM.js.map +0 -1
- package/dist/subcommand-CP9NY2J4.js.map +0 -1
- package/dist/usage-CTfDq9HR.js.map +0 -1
- /package/dist/{chunk-EAsCxrDo.js → rolldown-runtime-EAsCxrDo.js} +0 -0
|
@@ -1,4 +1,165 @@
|
|
|
1
|
-
import { f as DocumentData, m as JSONValue, p as DocumentValue } from "./app-config-
|
|
1
|
+
import { f as DocumentData, m as JSONValue, p as DocumentValue } from "./app-config-DyiFK3_k.js";
|
|
2
|
+
//#region packages/protocol/src/errors.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* Discriminator for {@link BaerlyError}. Strings (not subclasses) so they
|
|
5
|
+
* survive cross-realm boundaries (e.g. a Web Worker) and so callers can
|
|
6
|
+
* pattern-match with grep-friendly equality.
|
|
7
|
+
*/
|
|
8
|
+
type BaerlyErrorCode = /** Caller-provided config or input is invalid (bad bucket, unsupported credential type, malformed URL, bucket not version-enabled when versioning was requested). */"InvalidConfig" /** Generic S3/HTTP transport failure (5xx, unexpected status, retries exhausted). */ | "NetworkError" /** S3 returned 403. Either credentials are wrong or the bucket policy denies the operation. */ | "AccessDenied" /** Server returned data that didn't parse (malformed XML, non-JSON body where JSON expected). */ | "InvalidResponse" /** Internal invariant violation — should not be reachable. File a bug. */ | "Internal"
|
|
9
|
+
/**
|
|
10
|
+
* Document body failed schema validation. Emitted by the table-API
|
|
11
|
+
* write verbs (`Collection.insert`, `Query.update`, `Collection.replace`) when
|
|
12
|
+
* the body is not valid JSON or contains an array where
|
|
13
|
+
* `DocumentValue` is required; also emitted when a collection has a
|
|
14
|
+
* declared `SchemaValidator` (via `Db.create({ collections })`) and
|
|
15
|
+
* the bound schema rejects the doc. In the schema-rejection case the
|
|
16
|
+
* error carries an `issues` array describing each failure. HTTP layer
|
|
17
|
+
* maps this to 400.
|
|
18
|
+
*/
|
|
19
|
+
| "SchemaError"
|
|
20
|
+
/**
|
|
21
|
+
* Write conflicted with current state: CAS retry budget exhausted,
|
|
22
|
+
* duplicate caller-supplied `_id`, or an already-existing guarded
|
|
23
|
+
* storage key. Check `BaerlyError.retriable` to decide whether the
|
|
24
|
+
* same logical operation should be retried.
|
|
25
|
+
*/
|
|
26
|
+
| "Conflict"
|
|
27
|
+
/**
|
|
28
|
+
* `Verifier` returned no identity. HTTP server maps to 401.
|
|
29
|
+
* Code is reserved here so the union locks.
|
|
30
|
+
*/
|
|
31
|
+
| "Unauthorized"
|
|
32
|
+
/**
|
|
33
|
+
* The addressed resource does not exist. HTTP server maps to 404.
|
|
34
|
+
* Emitted by the row-by-id read / update / delete handlers in
|
|
35
|
+
* `packages/server/src/http/router.ts` when the predicate
|
|
36
|
+
* `{ _id }` matches zero rows. Not a protocol invariant —
|
|
37
|
+
* callers may retry after creating the resource or treat as a
|
|
38
|
+
* miss depending on intent. The CLI maps this to the generic
|
|
39
|
+
* exit-2 "storage error" bucket, not the exit-3 "protocol
|
|
40
|
+
* invariant" bucket.
|
|
41
|
+
*/
|
|
42
|
+
| "NotFound"
|
|
43
|
+
/**
|
|
44
|
+
* Request body exceeded the server's size cap. HTTP server maps
|
|
45
|
+
* to 413. Cap is `MAX_BODY_BYTES` (1 MiB today; exported from
|
|
46
|
+
* `packages/server/src/http/router.ts`). The Node adapter
|
|
47
|
+
* enforces during the `node:http` stream pump so the process
|
|
48
|
+
* never materializes a multi-MiB body; Workers also rely on
|
|
49
|
+
* platform-side caps (16 MB free / 100 MB paid).
|
|
50
|
+
*/
|
|
51
|
+
| "PayloadTooLarge"
|
|
52
|
+
/**
|
|
53
|
+
* A predicate is structurally well-formed but contradicts itself —
|
|
54
|
+
* no document can match. Emitted by `validateWire` and
|
|
55
|
+
* `mergePredicateWires`. Triggers:
|
|
56
|
+
* - `{ clauses: [{op:"in", field:"priority", value:[]}] }` (empty `in` set)
|
|
57
|
+
* - an `eq` clause with a value outside the residual interval
|
|
58
|
+
* established by range clauses on the same field
|
|
59
|
+
* - merging `{op:"gt", value:10}` with `{op:"lt", value:5}` on the
|
|
60
|
+
* same field (empty interval)
|
|
61
|
+
* - merging two `in` clauses on the same field with empty intersection
|
|
62
|
+
*
|
|
63
|
+
* Conflicting equality across clauses (`eq:"open"` + `eq:"closed"` on
|
|
64
|
+
* the same field) surfaces as `InvalidConfig` rather than this code —
|
|
65
|
+
* the merger treats it as a caller-side configuration bug, not an
|
|
66
|
+
* algebraic contradiction.
|
|
67
|
+
*
|
|
68
|
+
* The HTTP layer treats this as a 400 (caller error). The distinct
|
|
69
|
+
* code lets downstream code short-circuit empty-by-construction
|
|
70
|
+
* without re-running the validator or parsing messages.
|
|
71
|
+
*/
|
|
72
|
+
| "UnsatisfiablePredicate"
|
|
73
|
+
/**
|
|
74
|
+
* A `useQuery` callback awaited a recorder terminal
|
|
75
|
+
* (`.get`/`.first`/`.all`/`.count`). The recorder runs once per
|
|
76
|
+
* render to capture the chain shape; it cannot survive an `await`
|
|
77
|
+
* because the proxy doesn't proxy across microtask boundaries. The
|
|
78
|
+
* recorder's terminal returns a thenable whose `.then` throws this
|
|
79
|
+
* error synchronously, converting what would otherwise be a silent
|
|
80
|
+
* spinner-hang into a render-time error the hook surfaces as
|
|
81
|
+
* `status: "error"`. Companion `baerly/no-await-in-use-query` lint
|
|
82
|
+
* flags the pattern at edit time. For compound reads, use
|
|
83
|
+
* `Promise.all` (parallel) or compose two `useQuery` calls with
|
|
84
|
+
* `useQuery.skip` (dependent).
|
|
85
|
+
*/
|
|
86
|
+
| "UseQueryAwaitedRecorder"
|
|
87
|
+
/**
|
|
88
|
+
* A write method (`.insert`/`.update`/`.replace`/`.delete`) was
|
|
89
|
+
* called on the recorder inside a `useQuery` callback. Writes
|
|
90
|
+
* inside reads are a programming error; the recorder rejects them
|
|
91
|
+
* synchronously from the discovery pass, before any I/O fires. Use
|
|
92
|
+
* `useMutation()` instead.
|
|
93
|
+
*/
|
|
94
|
+
| "UnexpectedWriteInQuery"
|
|
95
|
+
/**
|
|
96
|
+
* A `useMutation()` callback rejected with a non-`BaerlyError`
|
|
97
|
+
* throwable. The hook wraps the original throw under this code so
|
|
98
|
+
* the `error` slot is always a `BaerlyError`; the original value
|
|
99
|
+
* is preserved on `.cause`.
|
|
100
|
+
*/
|
|
101
|
+
| "MutationFailed";
|
|
102
|
+
/**
|
|
103
|
+
* The single error class thrown by baerly-storage. Discriminate by `code`, not
|
|
104
|
+
* `instanceof`: the code string survives `JSON.stringify` round-trips
|
|
105
|
+
* across Worker / iframe / postMessage realm boundaries, where each
|
|
106
|
+
* realm has its own `BaerlyError` constructor identity. IDB-restored
|
|
107
|
+
* writes can replay across realms, so `instanceof` would spuriously
|
|
108
|
+
* fail on a structurally-identical error from another realm.
|
|
109
|
+
*
|
|
110
|
+
* @example
|
|
111
|
+
* ```ts
|
|
112
|
+
* try {
|
|
113
|
+
* await db.collection("tickets").insert({ title: "hi" });
|
|
114
|
+
* } catch (err) {
|
|
115
|
+
* if (err instanceof BaerlyError && err.code === "Conflict") {
|
|
116
|
+
* // Check err.retriable; CAS can retry, duplicate _id cannot.
|
|
117
|
+
* }
|
|
118
|
+
* throw err;
|
|
119
|
+
* }
|
|
120
|
+
* ```
|
|
121
|
+
*/
|
|
122
|
+
declare class BaerlyError extends Error {
|
|
123
|
+
readonly code: BaerlyErrorCode;
|
|
124
|
+
readonly cause?: unknown;
|
|
125
|
+
/**
|
|
126
|
+
* Structured field-path issues, set only when `code === "SchemaError"`.
|
|
127
|
+
* Each entry's `path` is a dotted-key list (e.g. `["assignee", "team"]`
|
|
128
|
+
* or `["items", 3, "qty"]`) that targets the offending field on the
|
|
129
|
+
* input document. `message` is the validator-emitted human string.
|
|
130
|
+
*
|
|
131
|
+
* The HTTP layer's `mapError` renders these into the 400 body via
|
|
132
|
+
* the existing `HttpErrorEnvelope`; older callers that don't know
|
|
133
|
+
* about `issues` see a plain message-only error and stay correct.
|
|
134
|
+
*/
|
|
135
|
+
readonly issues?: ReadonlyArray<{
|
|
136
|
+
readonly path: ReadonlyArray<string | number>;
|
|
137
|
+
readonly message: string;
|
|
138
|
+
}>;
|
|
139
|
+
/**
|
|
140
|
+
* Raw HTTP status, set only by the client-side wire decoder when
|
|
141
|
+
* inflating an `HttpErrorEnvelope` into this class. Server-side
|
|
142
|
+
* throws never set it (the HTTP layer's `mapError` derives the
|
|
143
|
+
* outbound status from `code`). Useful for diagnostics — e.g. to
|
|
144
|
+
* distinguish 404-as-"no such row" from 404-as-"route not found".
|
|
145
|
+
* Discriminate by `code` for behavior; reach for `status` only when
|
|
146
|
+
* you genuinely need the wire value.
|
|
147
|
+
*/
|
|
148
|
+
readonly status?: number;
|
|
149
|
+
/** Canonical corrective action; crosses the wire via `HttpErrorEnvelope.error.resolution`. */
|
|
150
|
+
readonly resolution?: string;
|
|
151
|
+
private readonly retriableOverride;
|
|
152
|
+
/**
|
|
153
|
+
* Whether this error instance is retriable. Defaults from `code`, but
|
|
154
|
+
* context-sensitive throw sites can override it.
|
|
155
|
+
*/
|
|
156
|
+
get retriable(): boolean;
|
|
157
|
+
constructor(code: BaerlyErrorCode, message: string, cause?: unknown, issues?: ReadonlyArray<{
|
|
158
|
+
readonly path: ReadonlyArray<string | number>;
|
|
159
|
+
readonly message: string;
|
|
160
|
+
}>, status?: number, resolution?: string, retriableOverride?: boolean);
|
|
161
|
+
}
|
|
162
|
+
//#endregion
|
|
2
163
|
//#region packages/protocol/src/storage/types.d.ts
|
|
3
164
|
/**
|
|
4
165
|
* Object-storage abstraction. The protocol kernel writes through
|
|
@@ -267,8 +428,9 @@ interface CurrentJsonRead {
|
|
|
267
428
|
* The methods on this interface ARE the supported operator surface.
|
|
268
429
|
* Vocabulary additions (`or`, `not`, `regex`, `ne`, `exists`, ...)
|
|
269
430
|
* are intentionally absent — calling them is a TS2339 compile
|
|
270
|
-
* error, not a runtime rejection.
|
|
271
|
-
*
|
|
431
|
+
* error, not a runtime rejection. The algebra is conjunction-only in
|
|
432
|
+
* perpetuity — see the API surface lock in
|
|
433
|
+
* docs/contributing/conventions/change-discipline.md.
|
|
272
434
|
*
|
|
273
435
|
* @template T - the document shape the predicate is keyed against.
|
|
274
436
|
*/
|
|
@@ -504,7 +666,7 @@ type _StripIndex<T> = { [K in keyof T as string extends K ? never : K]: T[K] };
|
|
|
504
666
|
* today's open-keyed default behavior.
|
|
505
667
|
* @internal
|
|
506
668
|
*/
|
|
507
|
-
type _AllPaths<T, D extends _PathDepth[number] = 4> = [D] extends [never] ? never : T extends object ? keyof _StripIndex<T> & string extends never ? string : { [K in keyof _StripIndex<T> & string]: _IsPathLeaf<T[K]
|
|
669
|
+
type _AllPaths<T, D extends _PathDepth[number] = 4> = [D] extends [never] ? never : T extends object ? keyof _StripIndex<T> & string extends never ? string : { [K in keyof _StripIndex<T> & string]: _IsPathLeaf<NonNullable<T[K]>> extends true ? K : K | `${K}.${_AllPaths<NonNullable<T[K]>, _PathDepth[D]>}` }[keyof _StripIndex<T> & string] : never;
|
|
508
670
|
/**
|
|
509
671
|
* Legal dotted-path keys over `T`, with the root-level `_id` filtered
|
|
510
672
|
* out so the top-level shape no longer accepts `{ _id: "x" }`. Nested
|
|
@@ -667,158 +829,16 @@ interface Query<T extends DocumentData = DocumentData> {
|
|
|
667
829
|
}>;
|
|
668
830
|
}
|
|
669
831
|
//#endregion
|
|
670
|
-
//#region packages/protocol/src/
|
|
671
|
-
/**
|
|
672
|
-
|
|
673
|
-
* survive cross-realm boundaries (e.g. a Web Worker) and so callers can
|
|
674
|
-
* pattern-match with grep-friendly equality.
|
|
675
|
-
*/
|
|
676
|
-
type BaerlyErrorCode = /** Caller-provided config or input is invalid (bad bucket, unsupported credential type, malformed URL, bucket not version-enabled when versioning was requested). */"InvalidConfig" /** Generic S3/HTTP transport failure (5xx, unexpected status, retries exhausted). */ | "NetworkError" /** S3 returned 403. Either credentials are wrong or the bucket policy denies the operation. */ | "AccessDenied" /** Server returned data that didn't parse (malformed XML, non-JSON body where JSON expected). */ | "InvalidResponse" /** Internal invariant violation — should not be reachable. File a bug. */ | "Internal"
|
|
677
|
-
/**
|
|
678
|
-
* Document body failed schema validation. Emitted by the table-API
|
|
679
|
-
* write verbs (`Collection.insert`, `Query.update`, `Collection.replace`) when
|
|
680
|
-
* the body is not valid JSON or contains an array where
|
|
681
|
-
* `DocumentValue` is required; also emitted when a collection has a
|
|
682
|
-
* declared `SchemaValidator` (via `Db.create({ collections })`) and
|
|
683
|
-
* the bound schema rejects the doc. In the schema-rejection case the
|
|
684
|
-
* error carries an `issues` array describing each failure. HTTP layer
|
|
685
|
-
* maps this to 400.
|
|
686
|
-
*/
|
|
687
|
-
| "SchemaError"
|
|
688
|
-
/**
|
|
689
|
-
* CAS lost on `current.json`. Caller decides whether to retry.
|
|
690
|
-
* Surfaces in the collection API and HTTP layer.
|
|
691
|
-
*/
|
|
692
|
-
| "Conflict"
|
|
693
|
-
/**
|
|
694
|
-
* `Verifier` returned no identity. HTTP server maps to 401.
|
|
695
|
-
* Code is reserved here so the union locks.
|
|
696
|
-
*/
|
|
697
|
-
| "Unauthorized"
|
|
698
|
-
/**
|
|
699
|
-
* The addressed resource does not exist. HTTP server maps to 404.
|
|
700
|
-
* Emitted by the row-by-id read / update / delete handlers in
|
|
701
|
-
* `packages/server/src/http/router.ts` when the predicate
|
|
702
|
-
* `{ _id }` matches zero rows. Not a protocol invariant —
|
|
703
|
-
* callers may retry after creating the resource or treat as a
|
|
704
|
-
* miss depending on intent. The CLI maps this to the generic
|
|
705
|
-
* exit-2 "storage error" bucket, not the exit-3 "protocol
|
|
706
|
-
* invariant" bucket.
|
|
707
|
-
*/
|
|
708
|
-
| "NotFound"
|
|
709
|
-
/**
|
|
710
|
-
* Request body exceeded the server's size cap. HTTP server maps
|
|
711
|
-
* to 413. Cap is `MAX_BODY_BYTES` (1 MiB today; exported from
|
|
712
|
-
* `packages/server/src/http/router.ts`). The Node adapter
|
|
713
|
-
* enforces during the `node:http` stream pump so the process
|
|
714
|
-
* never materializes a multi-MiB body; Workers also rely on
|
|
715
|
-
* platform-side caps (16 MB free / 100 MB paid).
|
|
716
|
-
*/
|
|
717
|
-
| "PayloadTooLarge"
|
|
718
|
-
/**
|
|
719
|
-
* A predicate is structurally well-formed but contradicts itself —
|
|
720
|
-
* no document can match. Emitted by `validateWire` and
|
|
721
|
-
* `mergePredicateWires`. Triggers:
|
|
722
|
-
* - `{ clauses: [{op:"in", field:"priority", value:[]}] }` (empty `in` set)
|
|
723
|
-
* - an `eq` clause with a value outside the residual interval
|
|
724
|
-
* established by range clauses on the same field
|
|
725
|
-
* - merging `{op:"gt", value:10}` with `{op:"lt", value:5}` on the
|
|
726
|
-
* same field (empty interval)
|
|
727
|
-
* - merging two `in` clauses on the same field with empty intersection
|
|
728
|
-
*
|
|
729
|
-
* Conflicting equality across clauses (`eq:"open"` + `eq:"closed"` on
|
|
730
|
-
* the same field) surfaces as `InvalidConfig` rather than this code —
|
|
731
|
-
* the merger treats it as a caller-side configuration bug, not an
|
|
732
|
-
* algebraic contradiction.
|
|
733
|
-
*
|
|
734
|
-
* The HTTP layer treats this as a 400 (caller error). The distinct
|
|
735
|
-
* code lets downstream code short-circuit empty-by-construction
|
|
736
|
-
* without re-running the validator or parsing messages.
|
|
737
|
-
*/
|
|
738
|
-
| "UnsatisfiablePredicate"
|
|
739
|
-
/**
|
|
740
|
-
* A `useQuery` callback awaited a recorder terminal
|
|
741
|
-
* (`.get`/`.first`/`.all`/`.count`). The recorder runs once per
|
|
742
|
-
* render to capture the chain shape; it cannot survive an `await`
|
|
743
|
-
* because the proxy doesn't proxy across microtask boundaries. The
|
|
744
|
-
* recorder's terminal returns a thenable whose `.then` throws this
|
|
745
|
-
* error synchronously, converting what would otherwise be a silent
|
|
746
|
-
* spinner-hang into a render-time error the hook surfaces as
|
|
747
|
-
* `status: "error"`. Companion `baerly/no-await-in-use-query` lint
|
|
748
|
-
* flags the pattern at edit time. For compound reads, use
|
|
749
|
-
* `Promise.all` (parallel) or compose two `useQuery` calls with
|
|
750
|
-
* `useQuery.skip` (dependent).
|
|
751
|
-
*/
|
|
752
|
-
| "UseQueryAwaitedRecorder"
|
|
753
|
-
/**
|
|
754
|
-
* A write method (`.insert`/`.update`/`.replace`/`.delete`) was
|
|
755
|
-
* called on the recorder inside a `useQuery` callback. Writes
|
|
756
|
-
* inside reads are a programming error; the recorder rejects them
|
|
757
|
-
* synchronously from the discovery pass, before any I/O fires. Use
|
|
758
|
-
* `useMutation()` instead.
|
|
759
|
-
*/
|
|
760
|
-
| "UnexpectedWriteInQuery"
|
|
761
|
-
/**
|
|
762
|
-
* A `useMutation()` callback rejected with a non-`BaerlyError`
|
|
763
|
-
* throwable. The hook wraps the original throw under this code so
|
|
764
|
-
* the `error` slot is always a `BaerlyError`; the original value
|
|
765
|
-
* is preserved on `.cause`.
|
|
766
|
-
*/
|
|
767
|
-
| "MutationFailed";
|
|
768
|
-
/**
|
|
769
|
-
* The single error class thrown by Baerly. Discriminate by `code`, not
|
|
770
|
-
* `instanceof`: the code string survives `JSON.stringify` round-trips
|
|
771
|
-
* across Worker / iframe / postMessage realm boundaries, where each
|
|
772
|
-
* realm has its own `BaerlyError` constructor identity. IDB-restored
|
|
773
|
-
* writes can replay across realms, so `instanceof` would spuriously
|
|
774
|
-
* fail on a structurally-identical error from another realm.
|
|
775
|
-
*
|
|
776
|
-
* @example
|
|
777
|
-
* ```ts
|
|
778
|
-
* try {
|
|
779
|
-
* await db.collection("tickets").insert({ title: "hi" });
|
|
780
|
-
* } catch (err) {
|
|
781
|
-
* if (err instanceof BaerlyError && err.code === "Conflict") {
|
|
782
|
-
* // ... CAS lost; retry
|
|
783
|
-
* }
|
|
784
|
-
* throw err;
|
|
785
|
-
* }
|
|
786
|
-
* ```
|
|
787
|
-
*/
|
|
788
|
-
declare class BaerlyError extends Error {
|
|
789
|
-
readonly code: BaerlyErrorCode;
|
|
790
|
-
readonly cause?: unknown;
|
|
791
|
-
/**
|
|
792
|
-
* Structured field-path issues, set only when `code === "SchemaError"`.
|
|
793
|
-
* Each entry's `path` is a dotted-key list (e.g. `["assignee", "team"]`
|
|
794
|
-
* or `["items", 3, "qty"]`) that targets the offending field on the
|
|
795
|
-
* input document. `message` is the validator-emitted human string.
|
|
796
|
-
*
|
|
797
|
-
* The HTTP layer's `mapError` renders these into the 400 body via
|
|
798
|
-
* the existing `HttpErrorEnvelope`; older callers that don't know
|
|
799
|
-
* about `issues` see a plain message-only error and stay correct.
|
|
800
|
-
*/
|
|
801
|
-
readonly issues?: ReadonlyArray<{
|
|
802
|
-
readonly path: ReadonlyArray<string | number>;
|
|
803
|
-
readonly message: string;
|
|
804
|
-
}>;
|
|
832
|
+
//#region packages/protocol/src/storage/memory.d.ts
|
|
833
|
+
/** Options for {@link MemoryStorage}. */
|
|
834
|
+
interface MemoryStorageOptions {
|
|
805
835
|
/**
|
|
806
|
-
*
|
|
807
|
-
*
|
|
808
|
-
*
|
|
809
|
-
* outbound status from `code`). Useful for diagnostics — e.g. to
|
|
810
|
-
* distinguish 404-as-"no such row" from 404-as-"route not found".
|
|
811
|
-
* Discriminate by `code` for behavior; reach for `status` only when
|
|
812
|
-
* you genuinely need the wire value.
|
|
836
|
+
* Acknowledge the store is intentionally ephemeral — required to
|
|
837
|
+
* construct in a detected deployment ({@link isDeployedEnv}); ignored in
|
|
838
|
+
* dev/test. Env equivalent: `BAERLY_ALLOW_EPHEMERAL_STORAGE=true`.
|
|
813
839
|
*/
|
|
814
|
-
|
|
815
|
-
constructor(code: BaerlyErrorCode, message: string, cause?: unknown, issues?: ReadonlyArray<{
|
|
816
|
-
readonly path: ReadonlyArray<string | number>;
|
|
817
|
-
readonly message: string;
|
|
818
|
-
}>, status?: number);
|
|
840
|
+
ephemeral?: boolean;
|
|
819
841
|
}
|
|
820
|
-
//#endregion
|
|
821
|
-
//#region packages/protocol/src/storage/memory.d.ts
|
|
822
842
|
/**
|
|
823
843
|
* In-memory `Storage`. The randomized property test runs against
|
|
824
844
|
* this; it must be deterministic — no clocks beyond the caller's,
|
|
@@ -841,6 +861,7 @@ declare class BaerlyError extends Error {
|
|
|
841
861
|
*/
|
|
842
862
|
declare class MemoryStorage implements Storage {
|
|
843
863
|
#private;
|
|
864
|
+
constructor(opts?: MemoryStorageOptions);
|
|
844
865
|
get(key: string, opts?: StorageGetOptions): Promise<StorageGetResult | null>;
|
|
845
866
|
put(key: string, body: Uint8Array, opts?: StoragePutOptions): Promise<StoragePutResult>;
|
|
846
867
|
delete(key: string, opts?: {
|
|
@@ -956,11 +977,13 @@ type Verifier = (req: Request) => Promise<VerifierResult | null>;
|
|
|
956
977
|
/**
|
|
957
978
|
* Debezium-style JSON CDC envelope using pgoutput's message-tag (`I`/`U`/`D`) vocabulary. One per mutation.
|
|
958
979
|
*
|
|
959
|
-
*
|
|
960
|
-
*
|
|
961
|
-
*
|
|
962
|
-
*
|
|
963
|
-
*
|
|
980
|
+
* `LogEntry` is now a public, versionless/additive-only wire contract:
|
|
981
|
+
* 0.3.0 is the public early-access baseline. It is still pre-1.0 and
|
|
982
|
+
* soaking, so breaking changes remain possible, but only through an
|
|
983
|
+
* explicit compatibility decision, changelog/migration notes, and a
|
|
984
|
+
* versioned release. Assume external consumers may exist; do not
|
|
985
|
+
* silently rename, remove, or repurpose fields. Consumers must ignore
|
|
986
|
+
* unknown keys; new optional fields can be added in compatible releases.
|
|
964
987
|
*
|
|
965
988
|
* Field requirement matrix:
|
|
966
989
|
* - Always: `lsn`, `commit_ts`, `op`, `collection`, `session`,
|
|
@@ -1016,7 +1039,7 @@ interface LogEntry {
|
|
|
1016
1039
|
before?: DocumentData;
|
|
1017
1040
|
/**
|
|
1018
1041
|
* Pre-image of the primary key. U/D always carry this when
|
|
1019
|
-
* `replica_identity` is not `PATCH_ONLY`. (For
|
|
1042
|
+
* `replica_identity` is not `PATCH_ONLY`. (For baerly-storage today,
|
|
1020
1043
|
* `_id` is the only PK.)
|
|
1021
1044
|
*/
|
|
1022
1045
|
key_old?: {
|
|
@@ -1025,12 +1048,19 @@ interface LogEntry {
|
|
|
1025
1048
|
/** ORIGIN analogue — the writer session id. */
|
|
1026
1049
|
origin?: string;
|
|
1027
1050
|
/**
|
|
1028
|
-
* Causal metadata (
|
|
1051
|
+
* Causal metadata (baerly-storage-only; no pgoutput analogue). The
|
|
1029
1052
|
* session id that built the `lsn`. Surfaces here so consumers
|
|
1030
1053
|
* can dedupe / order without parsing the cursor.
|
|
1031
1054
|
*/
|
|
1032
1055
|
session: string;
|
|
1033
|
-
/**
|
|
1056
|
+
/**
|
|
1057
|
+
* The `log/<seq>` slot this entry occupies — the integer in its
|
|
1058
|
+
* `log/<seq>.json` key, minted by `Writer.commit` as the forward-probed
|
|
1059
|
+
* collection-log tail (the winning `If-None-Match: "*"` create). One
|
|
1060
|
+
* entry per `session`, so this is a per-collection slot, not a
|
|
1061
|
+
* per-session counter. Also encoded (descending base-32) as the LSN's
|
|
1062
|
+
* third segment — see `lsnParts`.
|
|
1063
|
+
*/
|
|
1034
1064
|
seq: number;
|
|
1035
1065
|
}
|
|
1036
1066
|
//#endregion
|
|
@@ -1078,5 +1108,5 @@ interface MetricsRecorder {
|
|
|
1078
1108
|
histogram(name: string, value: number, labels?: Readonly<Record<string, string>>): void;
|
|
1079
1109
|
}
|
|
1080
1110
|
//#endregion
|
|
1081
|
-
export {
|
|
1082
|
-
//# sourceMappingURL=index-
|
|
1111
|
+
export { StoragePutOptions as _, MemoryStorage as a, BaerlyErrorCode as b, Predicate as c, CurrentJson as d, CurrentJsonRead as f, StorageListEntry as g, StorageGetResult as h, VerifierResult as i, Query as l, StorageGetOptions as m, LogEntry as n, Collection as o, Storage as p, Verifier as r, OrderSpec as s, MetricsRecorder as t, PredicateArg as u, StoragePutResult as v, BaerlyError as y };
|
|
1112
|
+
//# sourceMappingURL=index-BYk9oCNf.d.ts.map
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import { a as CollectionNames, c as defineConfig, d as IndexDefinition, f as DocumentData, i as CollectionDefinition, l as SchemaIssue, n as BaerlyAppConfig, o as RowOf, r as BaerlyConfig, s as UnboundConfig, u as SchemaValidator } from "./app-config-
|
|
2
|
-
import {
|
|
3
|
-
import { t as allIndexKeysFor } from "./indexes-
|
|
4
|
-
import { a as loadSnapshotAsMap, c as collectionsToMaps, i as encodeSnapshotBody, n as walkLogRange, o as snapshotKey, r as SnapshotBody, s as resolveVerifier, t as probeTailFrom } from "./index-
|
|
5
|
-
import { n as validateOrThrow, t as Db } from "./db-
|
|
6
|
-
export { type BaerlyAppConfig, type BaerlyConfig, BaerlyError, type BaerlyErrorCode, type Collection, type CollectionDefinition, type CollectionNames, Db, type DocumentData, type IndexDefinition, MemoryStorage, type Query, type RowOf, type SchemaIssue, type SchemaValidator, type SnapshotBody, type Storage, type StorageGetResult, type StorageListEntry, type StoragePutResult, type UnboundConfig, type Verifier, type VerifierResult, allIndexKeysFor, collectionsToMaps, defineConfig, encodeSnapshotBody, loadSnapshotAsMap, probeTailFrom, resolveVerifier, snapshotKey, validateOrThrow, walkLogRange };
|
|
1
|
+
import { a as CollectionNames, c as defineConfig, d as IndexDefinition, f as DocumentData, i as CollectionDefinition, l as SchemaIssue, n as BaerlyAppConfig, o as RowOf, r as BaerlyConfig, s as UnboundConfig, u as SchemaValidator } from "./app-config-DyiFK3_k.js";
|
|
2
|
+
import { a as MemoryStorage, b as BaerlyErrorCode, c as Predicate, g as StorageListEntry, h as StorageGetResult, i as VerifierResult, l as Query, o as Collection, p as Storage, r as Verifier, u as PredicateArg, v as StoragePutResult, y as BaerlyError } from "./index-BYk9oCNf.js";
|
|
3
|
+
import { t as allIndexKeysFor } from "./indexes-Dn9hbGQG.js";
|
|
4
|
+
import { a as loadSnapshotAsMap, c as collectionsToMaps, i as encodeSnapshotBody, n as walkLogRange, o as snapshotKey, r as SnapshotBody, s as resolveVerifier, t as probeTailFrom } from "./index-BNRh23K9.js";
|
|
5
|
+
import { n as validateOrThrow, t as Db } from "./db-DsPkOVEH.js";
|
|
6
|
+
export { type BaerlyAppConfig, type BaerlyConfig, BaerlyError, type BaerlyErrorCode, type Collection, type CollectionDefinition, type CollectionNames, Db, type DocumentData, type IndexDefinition, MemoryStorage, type Predicate, type PredicateArg, type Query, type RowOf, type SchemaIssue, type SchemaValidator, type SnapshotBody, type Storage, type StorageGetResult, type StorageListEntry, type StoragePutResult, type UnboundConfig, type Verifier, type VerifierResult, allIndexKeysFor, collectionsToMaps, defineConfig, encodeSnapshotBody, loadSnapshotAsMap, probeTailFrom, resolveVerifier, snapshotKey, validateOrThrow, walkLogRange };
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { defineConfig } from "./app-config.js";
|
|
2
|
-
import { t as BaerlyError } from "./errors-
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
5
|
-
import {
|
|
2
|
+
import { t as BaerlyError } from "./errors-Dfa3p78c.js";
|
|
3
|
+
import { b as loadSnapshotAsMap, g as allIndexKeysFor, h as walkLogRange, w as probeTailFrom, x as snapshotKey, y as encodeSnapshotBody } from "./maintenance-B4Dki6Ig.js";
|
|
4
|
+
import { i as MemoryStorage, n as resolveVerifier, r as collectionsToMaps, t as Db } from "./src-CYHFDrKz.js";
|
|
5
|
+
import { o as validateOrThrow } from "./query-rAtXNQQB.js";
|
|
6
6
|
export { BaerlyError, Db, MemoryStorage, allIndexKeysFor, collectionsToMaps, defineConfig, encodeSnapshotBody, loadSnapshotAsMap, probeTailFrom, resolveVerifier, snapshotKey, validateOrThrow, walkLogRange };
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { d as IndexDefinition, f as DocumentData } from "./app-config-
|
|
1
|
+
import { d as IndexDefinition, f as DocumentData } from "./app-config-DyiFK3_k.js";
|
|
2
2
|
//#region packages/server/src/indexes.d.ts
|
|
3
3
|
/**
|
|
4
4
|
* Compute the full index-key set a single doc produces under every
|
|
@@ -19,4 +19,4 @@ import { d as IndexDefinition, f as DocumentData } from "./app-config-BIzyAKzy.j
|
|
|
19
19
|
declare const allIndexKeysFor: (logPrefix: string, defs: ReadonlyArray<IndexDefinition>, body: DocumentData | undefined, docId: string) => string[];
|
|
20
20
|
//#endregion
|
|
21
21
|
export { allIndexKeysFor as t };
|
|
22
|
-
//# sourceMappingURL=indexes-
|
|
22
|
+
//# sourceMappingURL=indexes-Dn9hbGQG.d.ts.map
|
|
@@ -1,44 +1,21 @@
|
|
|
1
|
-
import { n as loadCollectionIndexes, r as parseBucketUri } from "./config-
|
|
2
|
-
import { h as readCurrentJson, n as probeTailFrom } from "./log-tail-
|
|
1
|
+
import { n as loadCollectionIndexes, r as parseBucketUri } from "./config-1tv0-Yzm.js";
|
|
2
|
+
import { h as readCurrentJson, n as probeTailFrom } from "./log-tail-D98U1JBo.js";
|
|
3
3
|
import { i as isJsonMode, o as BaerlyError, r as emitSuccess } from "./baerly.js";
|
|
4
|
-
import { n as loadMaterialisedView } from "./plan-
|
|
5
|
-
import { n as defineBaerlySubcommand, t as
|
|
4
|
+
import { n as loadMaterialisedView } from "./plan-a7PJHBCy.js";
|
|
5
|
+
import { a as TENANT_ARG, i as JSON_ARG, n as BUCKET_ARG, o as assertCollectionArg, r as COLLECTION_ARG, s as defineBaerlySubcommand, t as APP_ARG } from "./subcommand-DoDA-K7d.js";
|
|
6
6
|
//#region src/inspect.ts
|
|
7
7
|
const INSPECT_ARGS = {
|
|
8
|
-
bucket:
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
valueHint: "bucket-uri"
|
|
13
|
-
},
|
|
14
|
-
app: {
|
|
15
|
-
type: "string",
|
|
16
|
-
required: false,
|
|
17
|
-
description: "Application name segment (defaults to baerly.config.ts).",
|
|
18
|
-
valueHint: "app"
|
|
19
|
-
},
|
|
20
|
-
tenant: {
|
|
21
|
-
type: "string",
|
|
22
|
-
required: false,
|
|
23
|
-
description: "Tenant name segment (defaults to baerly.config.ts).",
|
|
24
|
-
valueHint: "tenant"
|
|
25
|
-
},
|
|
26
|
-
collection: {
|
|
27
|
-
type: "string",
|
|
28
|
-
required: true,
|
|
29
|
-
description: "Collection name.",
|
|
30
|
-
valueHint: "name"
|
|
31
|
-
},
|
|
8
|
+
bucket: BUCKET_ARG,
|
|
9
|
+
app: APP_ARG,
|
|
10
|
+
tenant: TENANT_ARG,
|
|
11
|
+
collection: COLLECTION_ARG,
|
|
32
12
|
config: {
|
|
33
13
|
type: "string",
|
|
34
14
|
required: false,
|
|
35
15
|
description: "Path to baerly.config.{js,mjs,json}; pulls declared indexes for key-count probes.",
|
|
36
16
|
valueHint: "path"
|
|
37
17
|
},
|
|
38
|
-
json:
|
|
39
|
-
type: "boolean",
|
|
40
|
-
description: "Emit a structured JSON envelope to stdout (success) or stderr (error)"
|
|
41
|
-
}
|
|
18
|
+
json: JSON_ARG
|
|
42
19
|
};
|
|
43
20
|
const countListEntries = async (storage, prefix) => {
|
|
44
21
|
let count = 0;
|
|
@@ -153,4 +130,4 @@ bundle.run;
|
|
|
153
130
|
//#endregion
|
|
154
131
|
export { inspect };
|
|
155
132
|
|
|
156
|
-
//# sourceMappingURL=inspect-
|
|
133
|
+
//# sourceMappingURL=inspect-6WZ-pC7-.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"inspect-6WZ-pC7-.js","names":[],"sources":["../packages/cli/src/inspect.ts"],"sourcesContent":["/**\n * `baerly inspect` — read-only summary for one collection.\n *\n * Args:\n * --bucket Required. Bucket URI.\n * --app Required (or via baerly.config.ts).\n * --tenant Required (or via baerly.config.ts).\n * --collection Required. Collection name.\n * --config Optional path to baerly.config.{js,mjs,json} for index info.\n * --json JSON envelope.\n *\n * Reports, per-collection:\n * - currentJsonKey path.\n * - schema_version, tail_hint, log_seq_start (default 0).\n * - live_log_tail (= tail_hint - log_seq_start).\n * - snapshot key (or null).\n * - snapshot_bytes / snapshot_rows (the fold-ceiling inputs C / E\n * are compared against; see graduation.md).\n * - writer_fence (epoch, owner, claimed_at).\n * - materialised row count (via export/loadMaterialisedView).\n * - per-declared-index key count (when --config supplied).\n * - well-formed status: \"ok\" or \"error\" with an `errors` array.\n *\n * For projected monthly Class A / $ trajectories, use\n * `baerly cost --bucket=<uri> --collection=<name>` — the projection\n * used to live as a footer here but moved to its own verb so inspect\n * stays a glance command (no GET-storm over the trailing log sample).\n *\n * Cost shape:\n * 1 GET current.json\n * + 1 GET snapshot (if any)\n * + N GETs log tail (= tail_hint - log_seq_start)\n * + K LISTs (one per declared index, when --config supplied)\n * + 1 LIST snapshot/ prefix (orphan detection)\n *\n * Never mutates anything.\n *\n * Exit codes:\n * 0 — inspection ran (status may be \"ok\" or \"error\"; both exit 0).\n * 1 — InvalidConfig (bad bucket URI, missing args, unknown flag).\n * 2 — Storage / Network error.\n * 3 — Protocol invariant (Conflict / Internal / InvalidResponse).\n */\n\nimport { type ArgsDef } from \"citty\";\nimport { BaerlyError, readCurrentJson, type CurrentJson, type Storage } from \"@baerly/protocol\";\nimport { probeTailFrom } from \"@baerly/server\";\nimport { loadMaterialisedView } from \"./export/index.ts\";\nimport { loadCollectionIndexes } from \"./config.ts\";\nimport { parseBucketUri } from \"./bucket-uri.ts\";\nimport { emitSuccess, isJsonMode } from \"./output.ts\";\nimport {\n APP_ARG,\n assertCollectionArg,\n BUCKET_ARG,\n COLLECTION_ARG,\n defineBaerlySubcommand,\n JSON_ARG,\n TENANT_ARG,\n} from \"./subcommand.ts\";\n\nconst INSPECT_ARGS = {\n bucket: BUCKET_ARG,\n app: APP_ARG,\n tenant: TENANT_ARG,\n collection: COLLECTION_ARG,\n config: {\n type: \"string\",\n required: false,\n description:\n \"Path to baerly.config.{js,mjs,json}; pulls declared indexes for key-count probes.\",\n valueHint: \"path\",\n },\n json: JSON_ARG,\n} as const satisfies ArgsDef;\n\nconst countListEntries = async (\n storage: Storage,\n prefix: string,\n): Promise<{ count: number; keys: string[] }> => {\n let count = 0;\n const keys: string[] = [];\n for await (const entry of storage.list(prefix)) {\n count++;\n keys.push(entry.key);\n }\n return { count, keys };\n};\n\ninterface InspectResult {\n currentJsonKey: string;\n schema_version: number;\n /** The stored, compactor-advanced lower-bound hint (`current.json.tail_hint`). */\n tail_hint: number;\n /** The TRUE committed tail, discovered by forward-probe past `tail_hint`. */\n discovered_tail: number;\n log_seq_start: number;\n live_log_tail: number;\n snapshot: string | null;\n snapshot_bytes: number;\n snapshot_rows: number;\n writer_fence: CurrentJson[\"writer_fence\"];\n materialised_rows: number;\n indexes: { name: string; count: number }[];\n status: \"ok\" | \"error\";\n errors: string[];\n}\n\nconst renderText = (r: InspectResult, collection: string): string => {\n const lines: string[] = [];\n lines.push(`baerly inspect ${collection}`);\n lines.push(` current.json: ${r.currentJsonKey}`);\n lines.push(` schema_version: ${r.schema_version}`);\n lines.push(` tail_hint (stored): ${r.tail_hint}`);\n lines.push(` discovered_tail: ${r.discovered_tail}`);\n lines.push(` log_seq_start: ${r.log_seq_start}`);\n lines.push(` live_log_tail: ${r.live_log_tail}`);\n lines.push(` snapshot: ${r.snapshot ?? \"(none)\"}`);\n lines.push(` snapshot_bytes: ${r.snapshot_bytes}`);\n lines.push(` snapshot_rows: ${r.snapshot_rows}`);\n lines.push(\n ` writer_fence: epoch=${r.writer_fence.epoch} owner=${JSON.stringify(r.writer_fence.owner)} claimed_at=${JSON.stringify(r.writer_fence.claimed_at)}`,\n );\n lines.push(` materialised_rows: ${r.materialised_rows}`);\n if (r.indexes.length > 0) {\n const formatted = r.indexes.map((i) => `${i.name} (count=${i.count})`).join(\", \");\n lines.push(` indexes: ${formatted}`);\n } else {\n lines.push(` indexes: (none declared)`);\n }\n lines.push(` status: ${r.status}`);\n if (r.errors.length > 0) {\n for (const e of r.errors) {\n lines.push(` error: ${e}`);\n }\n }\n return lines.join(\"\\n\") + \"\\n\";\n};\n\nconst bundle = defineBaerlySubcommand({\n name: \"inspect\",\n meta: {\n description: \"Read-only summary of one collection's snapshot + log state.\",\n },\n args: INSPECT_ARGS,\n handler: async (args, ctx) => {\n const bucket = await parseBucketUri(args.bucket);\n const { app, tenant } = await ctx.resolveAppTenant({ app: args.app, tenant: args.tenant });\n assertCollectionArg(args.collection, \"baerly inspect\");\n const collectionPrefix = `${bucket.keyPrefix}app/${app}/tenant/${tenant}/manifests/${args.collection}`;\n const currentJsonKey = `${collectionPrefix}/current.json`;\n\n const read = await readCurrentJson(bucket.storage, currentJsonKey);\n if (read === null) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `baerly inspect: current.json not found at ${currentJsonKey}`,\n );\n }\n const cur = read.json;\n const log_seq_start = cur.log_seq_start ?? 0;\n // Discover the TRUE tail by forward-probe — under single-write commit\n // the stored `tail_hint` is only a lower bound (compactor-advanced),\n // so an accurate operator summary must probe past it.\n const tailProbe = await probeTailFrom(\n bucket.storage,\n collectionPrefix,\n Math.max(log_seq_start, cur.tail_hint),\n );\n const discoveredTail = tailProbe.tail;\n\n const errors: string[] = [];\n let materialisedRows = 0;\n try {\n const view = await loadMaterialisedView({\n storage: bucket.storage,\n currentJsonKey,\n collection: args.collection,\n });\n materialisedRows = view?.size ?? 0;\n } catch (error) {\n if (error instanceof BaerlyError) {\n errors.push(`${error.code}: ${error.message}`);\n } else {\n errors.push((error as Error).message);\n }\n }\n\n // Orphan-snapshot detection: list every file under <collectionPrefix>/snapshot/\n // and flag anything that isn't the currently-pointed-at snapshot.\n try {\n const snapshotPrefix = `${collectionPrefix}/snapshot/`;\n const { keys } = await countListEntries(bucket.storage, snapshotPrefix);\n for (const k of keys) {\n if (cur.snapshot !== k) {\n errors.push(`orphan snapshot: ${k}`);\n }\n }\n } catch (error) {\n if (error instanceof BaerlyError) {\n errors.push(`${error.code}: ${error.message}`);\n }\n }\n\n const indexes: { name: string; count: number }[] = [];\n if (typeof args.config === \"string\" && args.config.length > 0) {\n const defs = await loadCollectionIndexes(args.config, args.collection, \"baerly inspect\");\n for (const def of defs) {\n const prefix = `${collectionPrefix}/index/${def.name}/`;\n const { count } = await countListEntries(bucket.storage, prefix);\n indexes.push({ name: def.name, count });\n }\n }\n\n const result: InspectResult = {\n currentJsonKey,\n schema_version: cur.schema_version,\n tail_hint: cur.tail_hint,\n discovered_tail: discoveredTail,\n log_seq_start,\n live_log_tail: discoveredTail - log_seq_start,\n snapshot: cur.snapshot,\n snapshot_bytes: cur.snapshot_bytes,\n snapshot_rows: cur.snapshot_rows,\n writer_fence: cur.writer_fence,\n materialised_rows: materialisedRows,\n indexes,\n status: errors.length === 0 ? \"ok\" : \"error\",\n errors,\n };\n\n if (isJsonMode()) {\n emitSuccess({ command: \"inspect\", ...result });\n } else {\n process.stdout.write(renderText(result, args.collection));\n }\n return 0;\n },\n});\n\n/** citty `defineCommand` block for `baerly inspect`. */\nexport const inspect = bundle.cmd;\n\n/**\n * Programmatic entry used by tests. Bypasses citty's `run` wrapper\n * (which would call `process.exit` and kill vitest) and returns the\n * integer exit code directly.\n */\nexport const runInspect = bundle.run;\n"],"mappings":"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"}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { t as BaerlyError } from "./errors-Dfa3p78c.js";
|
|
2
|
+
//#region packages/protocol/src/storage/key.ts
|
|
3
|
+
/**
|
|
4
|
+
* Validate a raw {@link Storage} object key against the portable baerly key
|
|
5
|
+
* grammar before it is used to address an object. A key MUST be non-empty
|
|
6
|
+
* and `/`-delimited, with **no path segment equal to `.` or `..`**.
|
|
7
|
+
*
|
|
8
|
+
* The dot-segment rule is not a vendor quirk — it is a *client-side*
|
|
9
|
+
* universal: RFC 3986 §5.2.4 "remove dot segments" is mandatory for every
|
|
10
|
+
* conformant URL parser, so `<endpoint>/<bucket>/.` normalizes to
|
|
11
|
+
* `<endpoint>/<bucket>/` and `<endpoint>/<bucket>/..` escapes the bucket
|
|
12
|
+
* entirely — *before* the request is signed or sent, in TypeScript, Go,
|
|
13
|
+
* Rust, Python, or any language a `Storage` port is written in. Such a key
|
|
14
|
+
* cannot be addressed over the S3/R2 HTTP API regardless of backend; a bare
|
|
15
|
+
* `.` PUT surfaces as a confusing bucket-root 403 rather than a clear
|
|
16
|
+
* rejection. The kernel never emits such keys (caller-controlled segments
|
|
17
|
+
* are already screened by `assertPathSegment` one layer up), so this is the
|
|
18
|
+
* boundary guard that makes every adapter reject them *identically* and
|
|
19
|
+
* gives ports a single, testable contract.
|
|
20
|
+
*
|
|
21
|
+
* Thrown as `BaerlyError{code:"InvalidConfig"}` to match the sibling
|
|
22
|
+
* key/segment guards (`assertKeyWithinLimit`, `assertPathSegment`). The
|
|
23
|
+
* full-key 1024-byte ceiling is enforced separately on the write path
|
|
24
|
+
* (`assertKeyWithinLimit`), where multi-segment keys are assembled.
|
|
25
|
+
*
|
|
26
|
+
* @see docs/spec/storage-compatibility.md — "Key namespace"
|
|
27
|
+
*/
|
|
28
|
+
function assertValidStorageKey(key) {
|
|
29
|
+
if (key.length === 0) throw new BaerlyError("InvalidConfig", "storage key must be a non-empty string");
|
|
30
|
+
for (const segment of key.split("/")) if (segment === "." || segment === "..") throw new BaerlyError("InvalidConfig", `storage key may not contain a "." or ".." path segment — RFC 3986 dot-segment removal makes it unaddressable over the S3/R2 HTTP API: ${JSON.stringify(key)}`);
|
|
31
|
+
}
|
|
32
|
+
//#endregion
|
|
33
|
+
export { assertValidStorageKey as t };
|
|
34
|
+
|
|
35
|
+
//# sourceMappingURL=key-Di6yyxFu.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"key-Di6yyxFu.js","names":[],"sources":["../packages/protocol/src/storage/key.ts"],"sourcesContent":["import { BaerlyError } from \"../errors.ts\";\n\n/**\n * Validate a raw {@link Storage} object key against the portable baerly key\n * grammar before it is used to address an object. A key MUST be non-empty\n * and `/`-delimited, with **no path segment equal to `.` or `..`**.\n *\n * The dot-segment rule is not a vendor quirk — it is a *client-side*\n * universal: RFC 3986 §5.2.4 \"remove dot segments\" is mandatory for every\n * conformant URL parser, so `<endpoint>/<bucket>/.` normalizes to\n * `<endpoint>/<bucket>/` and `<endpoint>/<bucket>/..` escapes the bucket\n * entirely — *before* the request is signed or sent, in TypeScript, Go,\n * Rust, Python, or any language a `Storage` port is written in. Such a key\n * cannot be addressed over the S3/R2 HTTP API regardless of backend; a bare\n * `.` PUT surfaces as a confusing bucket-root 403 rather than a clear\n * rejection. The kernel never emits such keys (caller-controlled segments\n * are already screened by `assertPathSegment` one layer up), so this is the\n * boundary guard that makes every adapter reject them *identically* and\n * gives ports a single, testable contract.\n *\n * Thrown as `BaerlyError{code:\"InvalidConfig\"}` to match the sibling\n * key/segment guards (`assertKeyWithinLimit`, `assertPathSegment`). The\n * full-key 1024-byte ceiling is enforced separately on the write path\n * (`assertKeyWithinLimit`), where multi-segment keys are assembled.\n *\n * @see docs/spec/storage-compatibility.md — \"Key namespace\"\n */\nexport function assertValidStorageKey(key: string): void {\n if (key.length === 0) {\n throw new BaerlyError(\"InvalidConfig\", \"storage key must be a non-empty string\");\n }\n for (const segment of key.split(\"/\")) {\n if (segment === \".\" || segment === \"..\") {\n throw new BaerlyError(\n \"InvalidConfig\",\n `storage key may not contain a \".\" or \"..\" path segment — RFC 3986 dot-segment ` +\n `removal makes it unaddressable over the S3/R2 HTTP API: ${JSON.stringify(key)}`,\n );\n }\n }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,sBAAsB,KAAmB;CACvD,IAAI,IAAI,WAAW,GACjB,MAAM,IAAI,YAAY,iBAAiB,wCAAwC;CAEjF,KAAK,MAAM,WAAW,IAAI,MAAM,GAAG,GACjC,IAAI,YAAY,OAAO,YAAY,MACjC,MAAM,IAAI,YACR,iBACA,yIAC6D,KAAK,UAAU,GAAG,GACjF;AAGN"}
|