@gusto/baerly-storage 0.2.0 → 0.4.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/LICENSE +202 -0
- package/NOTICE +29 -0
- package/README.md +176 -70
- package/dist/API.md +213 -139
- package/dist/CHANGELOG.md +434 -0
- package/dist/RECIPES.md +125 -0
- package/dist/THIRD-PARTY-LICENSES.txt +238 -0
- package/dist/{app-config-C0Bbw_Z6.d.ts → app-config-DyiFK3_k.d.ts} +55 -11
- package/dist/app-config.d.ts +1 -1
- package/dist/auth.d.ts +1 -1
- package/dist/auth.js +301 -301
- 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/bytes-BXdamO3L.js.map +1 -1
- package/dist/{client-DYZfoZb9.d.ts → client-Fe8CwB73.d.ts} +10 -10
- 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/client.js.map +1 -1
- package/dist/{cloudflare-CINJPKCW.js → cloudflare-DzKBrUlg.js} +178 -2
- package/dist/cloudflare-DzKBrUlg.js.map +1 -0
- package/dist/cloudflare.d.ts +49 -6
- package/dist/cloudflare.js +59 -26
- 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/context-DRZ3tZ5l.js.map +1 -1
- package/dist/{cost-CQt1YRkA.js → cost-DSMIVqzL.js} +43 -42
- package/dist/cost-DSMIVqzL.js.map +1 -0
- package/dist/current-json-C6nhPOm1.js +190 -0
- package/dist/current-json-C6nhPOm1.js.map +1 -0
- package/dist/{db-BM3y2JQw.d.ts → db-DsPkOVEH.d.ts} +26 -108
- package/dist/{deploy-CrAbfgCq.js → deploy-DonTr-CV.js} +12 -5
- package/dist/deploy-DonTr-CV.js.map +1 -0
- package/dist/dev-vite.d.ts +11 -7
- package/dist/dev-vite.js +7 -6
- package/dist/dev-vite.js.map +1 -1
- package/dist/dev.d.ts +1 -1
- package/dist/dev.js +1 -1
- package/dist/{doctor-Db-hzPmE.js → doctor-DSIyCDg_.js} +14 -136
- package/dist/doctor-DSIyCDg_.js.map +1 -0
- package/dist/{dump-BYA55NLP.js → dump-Bh5k26VQ.js} +10 -31
- 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-Bhbz90-z.js → export-DtF5tDIM.js} +11 -32
- package/dist/{export-Bhbz90-z.js.map → export-DtF5tDIM.js.map} +1 -1
- package/dist/{fsck-CPPZWt9p.js → fsck-D_djMO5D.js} +28 -39
- package/dist/fsck-D_djMO5D.js.map +1 -0
- package/dist/{http-Cw8p6y5b.js → http-DxM9MflO.js} +151 -79
- package/dist/http-DxM9MflO.js.map +1 -0
- package/dist/http.d.ts +42 -26
- package/dist/http.js +3 -2
- package/dist/{index-DwDTWPSU.d.ts → index-0rZcMBwy.d.ts} +10 -7
- package/dist/{index-C3JAH1Yo.d.ts → index-B6oexfOB.d.ts} +9 -9
- package/dist/{index-cUY-36AN.d.ts → index-BNRh23K9.d.ts} +21 -5
- package/dist/{index-DSvwEUeF.d.ts → index-BYk9oCNf.d.ts} +240 -202
- package/dist/index.d.ts +6 -6
- package/dist/index.js +5 -5
- package/dist/{indexes-DAu2AkTW.d.ts → indexes-Dn9hbGQG.d.ts} +2 -2
- package/dist/{inspect-Bdbzvi-_.js → inspect-6WZ-pC7-.js} +21 -36
- 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/{snapshot-SS8USDUF.js → log-tail-D98U1JBo.js} +179 -84
- package/dist/log-tail-D98U1JBo.js.map +1 -0
- package/dist/{maintenance-ClzBC1Vv.js → maintenance-B4Dki6Ig.js} +438 -176
- package/dist/maintenance-B4Dki6Ig.js.map +1 -0
- package/dist/{maintenance-BRrThz8V.d.ts → maintenance-B_e0T99L.d.ts} +114 -26
- package/dist/{maintenance-BvOv6BMM.js → maintenance-C7coQp4c.js} +217 -94
- package/dist/maintenance-C7coQp4c.js.map +1 -0
- package/dist/maintenance.d.ts +3 -2
- package/dist/maintenance.js +3 -2
- package/dist/node.d.ts +176 -68
- 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-CpOiEN0k.js → observability-wzs3-BL_.js} +279 -109
- package/dist/observability-wzs3-BL_.js.map +1 -0
- package/dist/observability.d.ts +3 -3
- package/dist/observability.js +1 -1
- package/dist/{plan-DOTl21vq.js → plan-a7PJHBCy.js} +7 -4
- package/dist/plan-a7PJHBCy.js.map +1 -0
- package/dist/{query-BmiQy328.js → query-rAtXNQQB.js} +1063 -1202
- package/dist/query-rAtXNQQB.js.map +1 -0
- package/dist/{rebuild-index-DC_nR6wP.js → rebuild-index-BVzQSZlm.js} +10 -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-R-4rbciV.js +778 -0
- package/dist/restore-R-4rbciV.js.map +1 -0
- package/dist/runtime-spec-qL3_lTTU.js +391 -0
- package/dist/runtime-spec-qL3_lTTU.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-BG20LZs7.js +2271 -0
- package/dist/src-BG20LZs7.js.map +1 -0
- package/dist/{src-zhEAmmF7.js → src-CYHFDrKz.js} +82 -99
- package/dist/src-CYHFDrKz.js.map +1 -0
- package/dist/{src-QQ7jDeL2.js → src-DYZ4H1aF.js} +44 -23
- package/dist/src-DYZ4H1aF.js.map +1 -0
- package/dist/subcommand-DoDA-K7d.js +197 -0
- 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-CLjirdD-.js → usage-DBV1eQHC.js} +7 -22
- package/dist/usage-DBV1eQHC.js.map +1 -0
- package/dist/{validate-DCq_0DIn.js → validate-DtljsCh1.js} +51 -51
- package/dist/{validate-DCq_0DIn.js.map → validate-DtljsCh1.js.map} +1 -1
- package/dist/wire-izfGZDvr.js.map +1 -1
- package/package.json +77 -42
- package/dist/cloudflare-CINJPKCW.js.map +0 -1
- package/dist/config-DVfDGyw1.js +0 -278
- package/dist/config-DVfDGyw1.js.map +0 -1
- package/dist/cost-CQt1YRkA.js.map +0 -1
- package/dist/current-json-C-EyJqs0.js +0 -354
- package/dist/current-json-C-EyJqs0.js.map +0 -1
- package/dist/deploy-CrAbfgCq.js.map +0 -1
- package/dist/doctor-Db-hzPmE.js.map +0 -1
- package/dist/dump-BYA55NLP.js.map +0 -1
- package/dist/errors-DOdL95kK.js.map +0 -1
- package/dist/fsck-CPPZWt9p.js.map +0 -1
- package/dist/http-Cw8p6y5b.js.map +0 -1
- package/dist/inspect-Bdbzvi-_.js.map +0 -1
- package/dist/maintenance-BvOv6BMM.js.map +0 -1
- package/dist/maintenance-ClzBC1Vv.js.map +0 -1
- package/dist/normalize-XWY25_sG.js.map +0 -1
- package/dist/observability-CpOiEN0k.js.map +0 -1
- package/dist/plan-DOTl21vq.js.map +0 -1
- package/dist/query-BmiQy328.js.map +0 -1
- package/dist/rebuild-index-DC_nR6wP.js.map +0 -1
- package/dist/restore-C6IcmLeA.js +0 -771
- package/dist/restore-C6IcmLeA.js.map +0 -1
- package/dist/shared-secret-BJdSwpgw.js.map +0 -1
- package/dist/snapshot-SS8USDUF.js.map +0 -1
- package/dist/src-DU1sCMlr.js +0 -6236
- package/dist/src-DU1sCMlr.js.map +0 -1
- package/dist/src-QQ7jDeL2.js.map +0 -1
- package/dist/src-zhEAmmF7.js.map +0 -1
- package/dist/subcommand-DZcHcsYp.js +0 -5122
- package/dist/subcommand-DZcHcsYp.js.map +0 -1
- package/dist/usage-CLjirdD-.js.map +0 -1
- /package/dist/{chunk-EAsCxrDo.js → rolldown-runtime-EAsCxrDo.js} +0 -0
|
@@ -0,0 +1,434 @@
|
|
|
1
|
+
# @gusto/baerly-storage
|
|
2
|
+
|
|
3
|
+
## 0.4.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 878bd78: Fail closed on ephemeral storage in production
|
|
8
|
+
|
|
9
|
+
`MemoryStorage` now refuses to construct in a detected deployment
|
|
10
|
+
(`NODE_ENV=production` or a known PaaS marker) unless you explicitly acknowledge
|
|
11
|
+
that it's ephemeral. This closes a silent-data-loss failure mode: an app that
|
|
12
|
+
falls back to in-memory storage in production, where writes "succeed" into
|
|
13
|
+
process RAM and vanish on every restart with no loud signal.
|
|
14
|
+
|
|
15
|
+
**What changed**
|
|
16
|
+
|
|
17
|
+
- `new MemoryStorage()` throws `BaerlyError("InvalidConfig")` in a detected
|
|
18
|
+
deployment. Tests and local dev are unaffected — neither sets those signals.
|
|
19
|
+
- New `resolveStorageFromEnv(env?)` export on `@gusto/baerly-storage/node`: the
|
|
20
|
+
safe, tested storage selector the Node example scaffolds now use, so apps
|
|
21
|
+
don't hand-roll one with a silent fallback.
|
|
22
|
+
- New `assertStorageReachable(storage)` export on `@gusto/baerly-storage/node`:
|
|
23
|
+
an opt-in boot/readiness check that fails closed on an unreachable or
|
|
24
|
+
CAS-broken bucket — the wrong-bucket-name gap a missing-bucket guard can't
|
|
25
|
+
catch.
|
|
26
|
+
- New pure `isDeployedEnv(env)` predicate on `@gusto/baerly-storage`.
|
|
27
|
+
|
|
28
|
+
**Migration**
|
|
29
|
+
|
|
30
|
+
- To run in-memory storage in a deployment on purpose (e.g. a throwaway demo),
|
|
31
|
+
opt in explicitly — either in code:
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
new MemoryStorage({ ephemeral: true });
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
or via the environment:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
BAERLY_ALLOW_EPHEMERAL_STORAGE=true
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
- No action needed for tests, local dev, or apps already using a real S3/R2
|
|
44
|
+
bucket.
|
|
45
|
+
|
|
46
|
+
**Platform note**
|
|
47
|
+
|
|
48
|
+
- The guard is effectively Node-only. A Cloudflare Worker requires an R2
|
|
49
|
+
binding and has no silent in-memory fallback, and the deploy-detection
|
|
50
|
+
predicate reads `process.env`, which is empty on Workerd — so the guard never
|
|
51
|
+
fires (and never needs to) on Cloudflare.
|
|
52
|
+
- CI is never treated as deployed. When `CI` is set to a non-empty, non-`false`
|
|
53
|
+
value, PaaS-marker detection is suppressed, so `MemoryStorage` still
|
|
54
|
+
constructs in CI — including Kubernetes-hosted CI agents that set
|
|
55
|
+
`KUBERNETES_SERVICE_HOST`. An explicit `NODE_ENV=production` still trips the
|
|
56
|
+
guard.
|
|
57
|
+
|
|
58
|
+
- ab1d80e: Node apps can now run with zero storage credentials, using the new
|
|
59
|
+
`localFsStorage()` factory from `@gusto/baerly-storage/node`. The Node examples
|
|
60
|
+
default to local filesystem storage in development and promote to S3 or R2 once
|
|
61
|
+
bucket environment variables are set.
|
|
62
|
+
|
|
63
|
+
`localFsStorage()` is a local-dev convenience only — single-process, with no
|
|
64
|
+
cross-process CAS and no crash durability. So the Node example servers fail loud
|
|
65
|
+
in a detected deployment (`NODE_ENV=production` or a known PaaS) and require a
|
|
66
|
+
real bucket: a missing or typo'd bucket aborts startup instead of running
|
|
67
|
+
production on non-durable storage. There is deliberately no opt-in to run
|
|
68
|
+
local-fs in a deployment. When self-hosting without a cloud bucket, run MinIO on
|
|
69
|
+
the box or use SQLite + Litestream.
|
|
70
|
+
|
|
71
|
+
- 7ded765: Cloudflare Workers can now talk to S3-compatible storage over HTTP instead of a
|
|
72
|
+
native R2 binding. This is opt-in; the R2 binding remains the default.
|
|
73
|
+
|
|
74
|
+
New exports and options:
|
|
75
|
+
|
|
76
|
+
- New Worker-safe subpath `@gusto/baerly-storage/s3` exports `S3HttpStorage` and
|
|
77
|
+
`sigV4Signer`. Their closure pulls in no `node:` builtins, so it loads in a
|
|
78
|
+
Worker.
|
|
79
|
+
- `baerlyWorker` accepts an optional `storage` in its factory options. It
|
|
80
|
+
defaults to the `env.BUCKET` R2 binding.
|
|
81
|
+
- `BaerlyEnv.BUCKET` is now optional, so an S3-only Worker need not declare an R2
|
|
82
|
+
binding.
|
|
83
|
+
|
|
84
|
+
`sigV4Signer` fails fast with `InvalidConfig` when `accessKeyId`,
|
|
85
|
+
`secretAccessKey`, or `region` is empty or whitespace-only (for example, a blank
|
|
86
|
+
or accidentally-spaced wrangler `var`). This replaces signing with blank
|
|
87
|
+
credentials — or building a malformed empty-region SigV4 scope — and drawing an
|
|
88
|
+
opaque 403.
|
|
89
|
+
|
|
90
|
+
This path ships at the same support tier as AWS-via-`S3HttpStorage`:
|
|
91
|
+
credential-gated, with production validation owned by the operator. CI guards the
|
|
92
|
+
closure under workerd on two levels:
|
|
93
|
+
|
|
94
|
+
- a bundle probe that it stays `node:`-free (so it loads in a Worker), and
|
|
95
|
+
- an in-isolate wire test that `S3HttpStorage` + `sigV4Signer` actually run
|
|
96
|
+
there — signing, XML parse, request/response plumbing — against an in-memory
|
|
97
|
+
S3 stub.
|
|
98
|
+
|
|
99
|
+
CI does not drive a real S3 endpoint from workerd. Verify yours with `baerly
|
|
100
|
+
doctor --bucket` before relying on it. Note that `baerly deploy` and `doctor
|
|
101
|
+
--target=cloudflare` still expect an R2 binding in `wrangler.jsonc`.
|
|
102
|
+
|
|
103
|
+
- df232a4: Add IRSA (web-identity) credential support for S3 on EKS. Previously
|
|
104
|
+
`fromEksPodIdentity()` handled only the EKS Pod Identity agent
|
|
105
|
+
(`AWS_CONTAINER_CREDENTIALS_FULL_URI`). Clusters that inject credentials via
|
|
106
|
+
IRSA (`AWS_ROLE_ARN` + `AWS_WEB_IDENTITY_TOKEN_FILE`) threw `InvalidConfig` on
|
|
107
|
+
first sign, so every S3 call failed.
|
|
108
|
+
|
|
109
|
+
Two new credential providers in `@gusto/baerly-storage/node`:
|
|
110
|
+
|
|
111
|
+
- `fromWebIdentity()` — exchanges the projected service-account token for
|
|
112
|
+
short-lived credentials via STS `AssumeRoleWithWebIdentity`. The call is
|
|
113
|
+
unsigned; the token is the auth. It returns `expiration`, so the signing layer
|
|
114
|
+
rotates the ~1h credentials automatically. No AWS SDK dependency — it uses
|
|
115
|
+
`fetch` plus the existing hardened XML parser.
|
|
116
|
+
- `fromEks()` — auto-detects the mechanism on each resolve: Pod Identity when
|
|
117
|
+
`AWS_CONTAINER_CREDENTIALS_FULL_URI` is present, otherwise IRSA. It throws a
|
|
118
|
+
clear `InvalidConfig` when neither is configured. Prefer this over the
|
|
119
|
+
mechanism-specific providers unless you have a reason to pin one.
|
|
120
|
+
|
|
121
|
+
Both EKS providers now fail with actionable errors instead of a bare status. A
|
|
122
|
+
missing, unreadable, or empty projected token throws `InvalidConfig`. A failed
|
|
123
|
+
STS `AssumeRoleWithWebIdentity` call folds the STS error `Code`/`Message` (for
|
|
124
|
+
example, `InvalidIdentityToken`) into the thrown message, so credential
|
|
125
|
+
misconfigs are diagnosable at a glance.
|
|
126
|
+
|
|
127
|
+
`fromEksPodIdentity()` keeps its behavior; it only gains the same
|
|
128
|
+
`InvalidConfig` token-file guards.
|
|
129
|
+
|
|
130
|
+
- 73110de: Add public exports `PredicateArg` / `Predicate` / `Collection`; fix `Path<T>`
|
|
131
|
+
for optional array fields
|
|
132
|
+
|
|
133
|
+
**New public exports**
|
|
134
|
+
|
|
135
|
+
- `PredicateArg`, `Predicate`, and `Collection` are now exported from
|
|
136
|
+
`@gusto/baerly-storage`.
|
|
137
|
+
- `PredicateArg` is now exported from `@gusto/baerly-storage/client` (which
|
|
138
|
+
already exported `ClientCollection` and `Predicate`).
|
|
139
|
+
|
|
140
|
+
These let you name the `.where(...)` argument and predicate types directly
|
|
141
|
+
instead of hand-rolling a structural interface to accept a `Db` or a
|
|
142
|
+
`BaerlyClient`. The client handle type stays `ClientCollection`; the in-process
|
|
143
|
+
`Collection` type is root-only, because the client's HTTP handle is structurally
|
|
144
|
+
distinct (read-only `.where(...)`, `TerminalOptions`).
|
|
145
|
+
|
|
146
|
+
**Bug fix — optional array fields**
|
|
147
|
+
|
|
148
|
+
`Path<T>` (the dotted-path key type behind `Predicate<T>` and `.where(...)`) now
|
|
149
|
+
runs its leaf test on `NonNullable<T[K]>`, so `Path<{ tags?: string[] }>` is
|
|
150
|
+
`"tags"` — an optional array ends path recursion exactly like a required one.
|
|
151
|
+
Previously the `undefined` arm of `string[] | undefined` defeated the
|
|
152
|
+
array-is-a-leaf check and synthesized bogus `Array.prototype` keys (`tags.map…`),
|
|
153
|
+
which broke assignability of a bound `Db<Config>` / `BaerlyClient<Config>` to a
|
|
154
|
+
hand-rolled structural `collection(name: string)` interface — even for
|
|
155
|
+
collections that never used the array field.
|
|
156
|
+
|
|
157
|
+
**Migration**
|
|
158
|
+
|
|
159
|
+
No action required — both changes are additive. If you hand-rolled a structural
|
|
160
|
+
`collection(name: string)` shim to read collections by a runtime-computed name,
|
|
161
|
+
you can now import the real types or narrow at the boundary:
|
|
162
|
+
|
|
163
|
+
```ts
|
|
164
|
+
(db as Db<UnboundConfig>).collection(name);
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Patch Changes
|
|
168
|
+
|
|
169
|
+
- 29bb00c: Refresh dependencies ahead of release. No public API changes.
|
|
170
|
+
|
|
171
|
+
Runtime deps that ship to consumers:
|
|
172
|
+
|
|
173
|
+
- `@logtape/logtape` 2.1.3 → 2.2.2
|
|
174
|
+
- `hono` 4.12.25 → 4.12.27
|
|
175
|
+
- `@hono/node-server` 2.0.4 → 2.0.6
|
|
176
|
+
- `jose` caret floor `^6.2.0` → `^6.2.3`
|
|
177
|
+
|
|
178
|
+
The `@gusto/create-baerly-storage` scaffolder picks up `@clack/prompts` 1.6.0.
|
|
179
|
+
|
|
180
|
+
The `@logtape/logtape` growth was rebaselined with a dated note in the
|
|
181
|
+
bundle-size budgets. (The XML parser was separately swapped from
|
|
182
|
+
`fast-xml-parser` to `@rgrove/parse-xml` — see the parser-swap changeset — which
|
|
183
|
+
removes `fast-xml-parser` and its transitive closure from the tree entirely.)
|
|
184
|
+
|
|
185
|
+
- 4813d9e: Swap `fast-xml-parser` for `@rgrove/parse-xml` in the S3 XML decode path
|
|
186
|
+
(`@baerly/adapter-node`). No public API changes — all exported functions and
|
|
187
|
+
types are unchanged.
|
|
188
|
+
|
|
189
|
+
**Smaller bundle:** −87 KiB raw / −24 KiB gz / −14 KiB min-gz on the `s3.js`
|
|
190
|
+
closure. `@rgrove/parse-xml` also has zero transitive dependencies, where
|
|
191
|
+
`fast-xml-parser` pulled in `strnum` and `@nodable/entities` — so the
|
|
192
|
+
supply-chain and audit surface both shrink.
|
|
193
|
+
|
|
194
|
+
**CVE-class defense-in-depth (not an active-hole fix):** `fast-xml-parser`
|
|
195
|
+
shipped ~6 CVEs across 5.x (CVE-2026-25896, CVE-2026-26278, CVE-2026-33036,
|
|
196
|
+
and others), all in the DOCTYPE/entity surface. Our `<!DOCTYPE` regex guard
|
|
197
|
+
already made those vectors unreachable — the pinned `fast-xml-parser@5.8.0`
|
|
198
|
+
was never itself vulnerable — but each new CVE still forced a version-pin
|
|
199
|
+
review. `@rgrove/parse-xml` parses and discards DTDs without resolving custom
|
|
200
|
+
entities, so the entity-expansion CVE _class_ cannot recur even if that regex
|
|
201
|
+
guard ever regressed. Removing the dependency also ends its dependabot cadence.
|
|
202
|
+
|
|
203
|
+
**Intended entity-set difference (not a bug):** `@rgrove/parse-xml` decodes
|
|
204
|
+
only the 5 predefined XML entities (`& < > " '`) plus
|
|
205
|
+
decimal and hex numeric character references. It does NOT decode HTML named
|
|
206
|
+
entities (` `, `—`, etc.); the old code enabled `htmlEntities: true`
|
|
207
|
+
solely to get numeric refs. S3/R2/MinIO wire data is XML, not HTML — no backend
|
|
208
|
+
emits HTML-only named entities in `ListObjectsV2` or error responses — so the
|
|
209
|
+
narrower set is more spec-correct.
|
|
210
|
+
|
|
211
|
+
The swap was validated during development with a one-time differential-oracle
|
|
212
|
+
test asserting field-for-field parity between the two parsers on generated
|
|
213
|
+
S3-shaped XML (predefined entities, decimal/hex numeric refs, CDATA, singular
|
|
214
|
+
and plural `<Contents>`). That check is not retained; going forward, parser
|
|
215
|
+
behavior is pinned by the example-based contract tests in
|
|
216
|
+
`packages/adapter-node/src/xml.test.ts`.
|
|
217
|
+
|
|
218
|
+
- e18e9c4: Reject `.` / `..` / empty object keys at the Storage boundary
|
|
219
|
+
|
|
220
|
+
Every `Storage` adapter (`MemoryStorage`, `S3HttpStorage`, `r2BindingStorage`,
|
|
221
|
+
`LocalFsStorage`) now validates the key on `get` / `put` / `delete` and throws
|
|
222
|
+
`BaerlyError("InvalidConfig")` when the key is empty or has a `.` or `..`
|
|
223
|
+
segment in its `/`-delimited path. Such keys can't be addressed over the S3/R2
|
|
224
|
+
HTTP API: RFC 3986 dot-segment removal rewrites `<bucket>/.` to the bucket root
|
|
225
|
+
before the request is signed, so a naive PUT fails as a confusing bucket-root
|
|
226
|
+
`403` instead of a clear error. The check runs client-side, before any network
|
|
227
|
+
call, so every backend rejects identically and the behavior ports cleanly to
|
|
228
|
+
other languages.
|
|
229
|
+
|
|
230
|
+
**What changed**
|
|
231
|
+
|
|
232
|
+
- `get` / `put` / `delete` on all adapters reject `""`, `.`, `..`, and any key
|
|
233
|
+
with a `.` or `..` path segment, with `InvalidConfig`. `list(prefix)` is
|
|
234
|
+
unaffected — a prefix rides the `?prefix=` query component, where `.` / `..`
|
|
235
|
+
are harmless.
|
|
236
|
+
- The 1024-byte full-key ceiling is still enforced on the write path
|
|
237
|
+
(`assertKeyWithinLimit`), where multi-segment keys are assembled.
|
|
238
|
+
|
|
239
|
+
**Migration**
|
|
240
|
+
|
|
241
|
+
- No action for normal use. The kernel never emits these keys, and
|
|
242
|
+
caller-controlled segments (`_id`, `collection`, `app`, `tenant`) are already
|
|
243
|
+
screened one layer up. If you call a `Storage` adapter directly with a bare
|
|
244
|
+
`.` / `..` / empty key, catch `BaerlyError` and check `code === "InvalidConfig"`.
|
|
245
|
+
- Shipped as a patch, not a minor: these keys were never addressable — a
|
|
246
|
+
`.` / `..` / empty key already failed with an opaque bucket-root `403` — so no
|
|
247
|
+
working call site changes behavior.
|
|
248
|
+
|
|
249
|
+
- b8b87e5: Write down the durable-contract promises: LogEntry is versionless, version axes
|
|
250
|
+
are named and drift-gated, and backend capabilities are split into required vs.
|
|
251
|
+
optional
|
|
252
|
+
|
|
253
|
+
Documentation and internal tooling only. Nothing changes in the emitted bytes,
|
|
254
|
+
the public API, or runtime behavior — this just records compatibility promises
|
|
255
|
+
the project already relied on, so anyone building on the durable contract (the
|
|
256
|
+
CDC-style `LogEntry` export, the bucket layout) can depend on them in writing.
|
|
257
|
+
|
|
258
|
+
**LogEntry is versionless and additive-only (ADR-005, `docs/adr/005-logentry-versionless.md`)**
|
|
259
|
+
|
|
260
|
+
- `LogEntry` carries no `schema_version`; the live wire contract is owned by
|
|
261
|
+
`docs/spec/log-entry-shape.md`. Consumers **must ignore unknown keys** — a
|
|
262
|
+
compatible release can add new optional fields at any time. Renaming a field,
|
|
263
|
+
repurposing a value, removing a field, or widening `op` requires an explicit
|
|
264
|
+
compatibility decision, a migration note, and a versioned release.
|
|
265
|
+
|
|
266
|
+
**Version matrix + drift gate**
|
|
267
|
+
|
|
268
|
+
- `docs/contributing/version-matrix.json` names every version axis in one place:
|
|
269
|
+
package semver, `specVersion`, the per-artifact durable `schema_version`s, the
|
|
270
|
+
`layout_version` cordon, and a reserved conformance `corpusVersion`.
|
|
271
|
+
- `docs/contributing/conventions/versioning.md` states the pre-1.0 rules: no
|
|
272
|
+
breaking wire/schema/layout change ships as a patch; while `0.x` it takes a
|
|
273
|
+
minor plus a migration note.
|
|
274
|
+
- `scripts/check-version-matrix.ts` fails `verify` on drift — it derives
|
|
275
|
+
`specVersion` from the wire IR so the matrix can't diverge, and enforces
|
|
276
|
+
package lockstep plus the LogEntry/layout/corpus sentinels. `gen:version-matrix`
|
|
277
|
+
regenerates the artifact from the reference implementation.
|
|
278
|
+
|
|
279
|
+
**Required vs. optional storage capabilities**
|
|
280
|
+
|
|
281
|
+
- `docs/spec/capabilities.md` records what a backend MUST support to certify as
|
|
282
|
+
a full `Storage` (CAS — exactly-one-winner conditional create — is required,
|
|
283
|
+
not optional), what is optional, and a planned read-only `ReaderStorage` tier.
|
|
284
|
+
|
|
285
|
+
**Migration**
|
|
286
|
+
|
|
287
|
+
- No action required. Nothing in the emitted bytes, the public API, or runtime
|
|
288
|
+
behavior changes. `SNAPSHOT_SCHEMA_VERSION` replaces a `1` literal with a named
|
|
289
|
+
constant of the same value.
|
|
290
|
+
|
|
291
|
+
## 0.3.0
|
|
292
|
+
|
|
293
|
+
### Minor Changes
|
|
294
|
+
|
|
295
|
+
- 79cc324: First public release. `baerly-storage` is a vendorless document database that
|
|
296
|
+
runs over any S3-compatible bucket — the data lives in your bucket and there is
|
|
297
|
+
no runtime to operate. Commit is one conditional log append (`If-None-Match`)
|
|
298
|
+
per collection, so each collection is linearizable; compaction and GC run
|
|
299
|
+
in-band on writes (reads never tick); no operator cron or sidecar. First-class
|
|
300
|
+
on Cloudflare Workers (R2) and self-hosted Node (S3), with day-one templates for
|
|
301
|
+
both.
|
|
302
|
+
|
|
303
|
+
Versions `0.1.x`–`0.2.0` were internal/experimental builds. They remain
|
|
304
|
+
published, but this is the first release intended for outside use. **Still
|
|
305
|
+
pre-1.0:** the on-disk format and public API may change between minor versions
|
|
306
|
+
until 1.0 — pin your version.
|
|
307
|
+
|
|
308
|
+
**New here? You're done — everything above is what you get.** The rest is for
|
|
309
|
+
the few of you who ran an internal `0.1`–`0.2` build and need to know what
|
|
310
|
+
changed since `0.2.0`. Reach out and I'll help you migrate.
|
|
311
|
+
|
|
312
|
+
**Migrating from an internal build**
|
|
313
|
+
|
|
314
|
+
- **Cheaper commits, and a breaking on-disk format (schema v3).** A write now
|
|
315
|
+
costs 2 Class-A PUTs instead of 3 — appending the numbered `log/<seq>` entry
|
|
316
|
+
_is_ the commit, so there is no separate `current.json` write. `current.json`
|
|
317
|
+
becomes compactor-owned compaction state (`next_seq` → `tail_hint`,
|
|
318
|
+
`+mean_entry_bytes`, `−tail_bytes`), and readers discover the true tail by
|
|
319
|
+
forward-probe. **Buckets written under schema v2 are rejected with no
|
|
320
|
+
migration path** — re-create the bucket (or `admin dump` on a v2 build →
|
|
321
|
+
`admin restore` on this one). See ADR-004.
|
|
322
|
+
- **`Db.transaction` removed — the document is the atomic unit.** Single-document
|
|
323
|
+
writes are each atomic; there is no batch. Replace
|
|
324
|
+
`db.transaction(name, tx => { tx.update(a); tx.update(b) })` with individual
|
|
325
|
+
`db.collection(name).update(...)` calls. The both-or-neither guarantee is
|
|
326
|
+
gone; model a single document as your consistency boundary. Re-adding
|
|
327
|
+
transactions later is additive (under the API surface lock).
|
|
328
|
+
- **Tighter key-segment validation.** One shared rule validates every
|
|
329
|
+
caller-controlled segment (`_id`, `collection`, `app`, `tenant`), rejecting
|
|
330
|
+
empty / `/` / `.` / `..` / control chars / reserved leading `_` / over-length
|
|
331
|
+
as `InvalidConfig`. The per-segment byte cap drops 1024 → 256 (an existing
|
|
332
|
+
`_id` of 257–1024 bytes can no longer be read-modified), and over-long
|
|
333
|
+
assembled keys now fail early as `InvalidConfig` instead of an opaque provider
|
|
334
|
+
`KeyTooLong`. HTTP (`/v1/since`) and the `baerly admin` CLI route through the
|
|
335
|
+
same rule.
|
|
336
|
+
|
|
337
|
+
**Fixed**
|
|
338
|
+
|
|
339
|
+
- **The change feed no longer dies after 1024 writes to a collection.** The
|
|
340
|
+
`/v1/since` cursor's sequence segment was 10-bit (`0..1023`); the 1025th write
|
|
341
|
+
produced an invalid cursor the server then rejected with a `400`, permanently
|
|
342
|
+
killing the feed. It is now 53-bit from a single source of truth.
|
|
343
|
+
- **Concurrent create-if-absent has exactly one winner.** `LocalFsStorage` now
|
|
344
|
+
uses an atomic `link(2)` exclusive create (was a TOCTOU read-then-write that
|
|
345
|
+
could admit two winners and split-brain the commit path), and
|
|
346
|
+
`baerly doctor --bucket` gains an `ifNoneMatch-concurrent` linearizability
|
|
347
|
+
check. The property is asserted for every shipped adapter by the conformance
|
|
348
|
+
suite.
|
|
349
|
+
- **Adapter error contract + CVE floor.** Terminal socket failures from
|
|
350
|
+
`S3HttpStorage` now surface as `BaerlyError{code:"NetworkError"}` instead of
|
|
351
|
+
raw `fetch` throws; the `fast-xml-parser` floor is raised past the disclosed
|
|
352
|
+
entity/numeric-reference advisories (bundle byte-neutral); and
|
|
353
|
+
schema-mismatch errors now name the required version and prescribe recovery.
|
|
354
|
+
- **GC stays bounded under backlog and concurrency.** The live-content-hash
|
|
355
|
+
scan now walks the log in bounded chunks (was an unbounded `Promise.all` that
|
|
356
|
+
could exceed Cloudflare's subrequest cap on a backlogged tail), and
|
|
357
|
+
`gc/pending.json` is merged under CAS with bounded retry so a concurrent GC
|
|
358
|
+
pass can no longer silently lose candidate marks.
|
|
359
|
+
- **Scaffolded Node + Docker apps boot.** The `--with=docker --target=node`
|
|
360
|
+
template now copies `baerly.config.ts` into the runtime image (the server
|
|
361
|
+
entrypoint imports it), so the container no longer crashes on an
|
|
362
|
+
unresolved-import error at startup.
|
|
363
|
+
|
|
364
|
+
## 0.2.0
|
|
365
|
+
|
|
366
|
+
### Minor Changes
|
|
367
|
+
|
|
368
|
+
- React hooks are now bound to your config via the `createBaerlyReact` factory.
|
|
369
|
+
|
|
370
|
+
**Migration — agents: if you wrote the LEFT, use the RIGHT:**
|
|
371
|
+
|
|
372
|
+
```ts
|
|
373
|
+
// before — loose hook exports (removed)
|
|
374
|
+
import {
|
|
375
|
+
BaerlyProvider,
|
|
376
|
+
useQuery,
|
|
377
|
+
useMutation,
|
|
378
|
+
useBaerlyClient,
|
|
379
|
+
} from "@gusto/baerly-storage/client/react";
|
|
380
|
+
|
|
381
|
+
// after — factory bound to your defineConfig collections
|
|
382
|
+
import { createBaerlyReact } from "@gusto/baerly-storage/client/react";
|
|
383
|
+
const { Provider, useQuery, useMutation, useClient } =
|
|
384
|
+
createBaerlyReact<typeof config>();
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
The loose exports no longer exist; obtain the hooks from the factory so
|
|
388
|
+
they are typed against your config (additive-only surface lock).
|
|
389
|
+
|
|
390
|
+
## 0.1.2
|
|
391
|
+
|
|
392
|
+
### Patch Changes
|
|
393
|
+
|
|
394
|
+
- In-band maintenance landed: compaction + GC run opportunistically on the
|
|
395
|
+
write path (reads never tick), gated so idle buckets pay zero. No operator
|
|
396
|
+
cron or sidecar required.
|
|
397
|
+
- **`LogEntry` wire shape tightened** (affects `baerly export` / log
|
|
398
|
+
consumers): `new` → `after`, `old` → `before`; `op` narrowed to
|
|
399
|
+
`"I" | "U" | "D"`; `patch` and `schema_version` removed; `doc_id` is now
|
|
400
|
+
required.
|
|
401
|
+
- Leading-underscore names are reserved for collections and indexes (one
|
|
402
|
+
`InvalidConfig` contract). A config using a `_`-prefixed collection name is
|
|
403
|
+
rejected.
|
|
404
|
+
- `adapter-node` parses S3 `<Error>` response bodies and guards against
|
|
405
|
+
`Invalid Date`.
|
|
406
|
+
- `baerly doctor --bucket <uri>` performs a live CAS probe.
|
|
407
|
+
|
|
408
|
+
## 0.1.1
|
|
409
|
+
|
|
410
|
+
### Patch Changes
|
|
411
|
+
|
|
412
|
+
- Internal tooling only: `pnpm dev:storage` ports are parameterised so two
|
|
413
|
+
worktrees can run stacks side by side; added a package-layer DAG lint. No
|
|
414
|
+
public API changes.
|
|
415
|
+
|
|
416
|
+
## 0.1.0
|
|
417
|
+
|
|
418
|
+
### Minor Changes
|
|
419
|
+
|
|
420
|
+
- Initial release of `@gusto/baerly-storage` — a vendorless document
|
|
421
|
+
database over any S3-compatible bucket. Public surface: `Db.create()`,
|
|
422
|
+
`db.collection(...)` with the eight-verb / three-modifier / six-operator
|
|
423
|
+
query API, `defineConfig`, `createBaerlyClient`, the Cloudflare Workers and
|
|
424
|
+
self-hosted Node adapters, and the `baerly` CLI. See `dist/API.md` for the
|
|
425
|
+
full surface.
|
|
426
|
+
|
|
427
|
+
---
|
|
428
|
+
|
|
429
|
+
_Maintained by [Changesets](https://github.com/changesets/changesets); entries
|
|
430
|
+
at and below `0.2.0` were backfilled by hand from the git history. This file
|
|
431
|
+
ships in the published package at `dist/CHANGELOG.md` so an agent that expected
|
|
432
|
+
an older API can recover the current call. The `.d.ts` types are the canonical
|
|
433
|
+
authority — if this file and the types disagree, the types win. (The footer sits
|
|
434
|
+
below all versions because Changesets prepends new releases under the H1.)_
|
package/dist/RECIPES.md
ADDED
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# baerly-storage — common mistakes & recipes
|
|
2
|
+
|
|
3
|
+
> Companion to `dist/API.md`. API.md is the surface; this file is the
|
|
4
|
+
> "why did my call fail" lookup, keyed by the exact error string you
|
|
5
|
+
> see. If a fix here disagrees with the `.d.ts` types, the types win.
|
|
6
|
+
|
|
7
|
+
## Common mistakes (keyed by the error you see)
|
|
8
|
+
|
|
9
|
+
### `Request body must be { doc: object }` (HTTP 400, `code="SchemaError"`)
|
|
10
|
+
|
|
11
|
+
**Cause:** POSTed a flat document body to `/v1/c/<collection>`.
|
|
12
|
+
**Fix:** Wrap it: `{ "doc": { ...yourFields } }`. The insert verb reads
|
|
13
|
+
`body.doc`, not the body itself. Same pattern for PATCH (`patch:`) and
|
|
14
|
+
PUT (`doc:`).
|
|
15
|
+
The wire `resolution` says: `Send a JSON body shaped { "doc": { ... } } for POST/PUT, or { "patch": { ... } } for PATCH.`
|
|
16
|
+
|
|
17
|
+
### `BaerlyError code="SchemaError"` on insert/update/replace
|
|
18
|
+
|
|
19
|
+
**Cause:** the document failed schema validation, OR the body is not
|
|
20
|
+
valid JSON / contains an array where `DocumentValue` is required, OR a
|
|
21
|
+
`null` field value (use `.optional()`; `null` in an *update patch* is the
|
|
22
|
+
RFC 7386 deletion sentinel, not a storable value).
|
|
23
|
+
**Fix:** read `error.issues` (each `{ path, message }`) for the offending
|
|
24
|
+
field path. Declare `_id: z.string()` (required) in your schema — the
|
|
25
|
+
validator runs on the post-image, so optional `_id` is wrong.
|
|
26
|
+
|
|
27
|
+
### `BaerlyError code="Conflict"` (HTTP 409)
|
|
28
|
+
|
|
29
|
+
**Cause:** the write conflicted with existing state. CAS conflicts are
|
|
30
|
+
retryable (`retriable: true`); duplicate caller-supplied `_id` inserts are
|
|
31
|
+
terminal (`retriable: false`).
|
|
32
|
+
**Fix:** follow the wire `resolution`. For retryable CAS conflicts, re-read,
|
|
33
|
+
re-apply, and retry with bounded backoff. For duplicate `_id` conflicts,
|
|
34
|
+
choose a different `_id`, or omit `_id` so baerly-storage can mint one.
|
|
35
|
+
The in-process writer already retries a bounded number of CAS attempts; a
|
|
36
|
+
remote client that sees `retriable: true` should apply its own bounded backoff.
|
|
37
|
+
|
|
38
|
+
### `db.collection(name).insertOne(...)` / `.find(...)` is not a function
|
|
39
|
+
|
|
40
|
+
**Cause:** Mongo muscle memory. No such method.
|
|
41
|
+
**Fix:** `db.collection(name).insert(row)` and
|
|
42
|
+
`.where({ field: value }).all()` / `.where(q => q.gte("count", 1)).all()`.
|
|
43
|
+
|
|
44
|
+
### `.useIndex(...)` / `.hint(...)` is not a function
|
|
45
|
+
|
|
46
|
+
**Cause:** SQL/ORM muscle memory. No such method.
|
|
47
|
+
**Fix:** the planner picks the index automatically from the
|
|
48
|
+
`IndexDefinition`s registered in `baerly.config.ts`.
|
|
49
|
+
|
|
50
|
+
### `BaerlyError code="InvalidConfig"` — `baerly: no auth configured`
|
|
51
|
+
|
|
52
|
+
**Full message:** `baerly: no auth configured. Set \`auth\` in baerly.config.ts ("none", "shared-secret") or pass \`verifier\` on the adapter factory.`
|
|
53
|
+
|
|
54
|
+
**Cause:** the adapter resolved no `Verifier`.
|
|
55
|
+
**Fix:** set `auth` in `baerly.config.ts` (`"none"` or `"shared-secret"`)
|
|
56
|
+
or pass `verifier:` on the adapter factory.
|
|
57
|
+
|
|
58
|
+
### `BaerlyError code="InvalidConfig"` — `SHARED_SECRET env is empty/unset`
|
|
59
|
+
|
|
60
|
+
**Full message:** `baerly: auth="shared-secret" but SHARED_SECRET env is empty/unset. Cloudflare: \`wrangler secret put SHARED_SECRET\`, or add to .dev.vars for local dev. Node: set in process env.`
|
|
61
|
+
|
|
62
|
+
**Cause:** `auth: "shared-secret"` was set but the `SHARED_SECRET`
|
|
63
|
+
environment variable is missing or empty at startup.
|
|
64
|
+
**Fix:** set the `SHARED_SECRET` env (`wrangler secret put SHARED_SECRET`
|
|
65
|
+
on Cloudflare, `.dev.vars` for local dev, process env on Node).
|
|
66
|
+
|
|
67
|
+
### `BaerlyError code="InvalidConfig"` — `Refusing to start: no durable storage configured` / `Refusing to use in-memory storage`
|
|
68
|
+
|
|
69
|
+
**Cause:** a deployed process (`NODE_ENV=production` or a known PaaS marker)
|
|
70
|
+
reached storage selection with no real bucket configured — or constructed
|
|
71
|
+
`MemoryStorage` there. In-memory "succeeds" into RAM and vanishes on every
|
|
72
|
+
restart; local-fs is single-process with no cross-process CAS. Both are
|
|
73
|
+
refused in a deployment so the failure is loud at boot, not silent data loss
|
|
74
|
+
in production.
|
|
75
|
+
**Fix:** don't hand-roll storage selection — call `resolveStorageFromEnv()`
|
|
76
|
+
from `@gusto/baerly-storage/node` (`R2_ACCOUNT_ID` → R2, `BUCKET` → S3, else
|
|
77
|
+
local-fs in dev) and configure a bucket: `BUCKET` + `AWS_ACCESS_KEY_ID` +
|
|
78
|
+
`AWS_SECRET_ACCESS_KEY` (add `R2_ACCOUNT_ID` for R2). To catch an
|
|
79
|
+
unreachable or CAS-broken bucket at boot rather than on the first write,
|
|
80
|
+
`await assertStorageReachable(storage)`. Intentionally ephemeral (a throwaway
|
|
81
|
+
demo)? Opt in explicitly: `new MemoryStorage({ ephemeral: true })` or
|
|
82
|
+
`BAERLY_ALLOW_EPHEMERAL_STORAGE=true`.
|
|
83
|
+
|
|
84
|
+
### `BaerlyError code="UseQueryAwaitedRecorder"`
|
|
85
|
+
|
|
86
|
+
**Cause:** awaited a terminal (`.get`/`.first`/`.all`/`.count`) inside a
|
|
87
|
+
`useQuery` callback. The recorder is synchronous; awaiting it yields a
|
|
88
|
+
sentinel and the next property access throws.
|
|
89
|
+
**Fix:** don't `await` in `useQuery` — for compound reads use
|
|
90
|
+
`Promise.all` (parallel) or compose two `useQuery` calls with
|
|
91
|
+
`useQuery.skip` (dependent). For writes use `useMutation()`.
|
|
92
|
+
|
|
93
|
+
### `BaerlyError code="UnexpectedWriteInQuery"`
|
|
94
|
+
|
|
95
|
+
**Cause:** called a write verb (`insert`/`update`/`replace`/`delete`)
|
|
96
|
+
inside a `useQuery` callback.
|
|
97
|
+
**Fix:** reads go in `useQuery`, writes go in `useMutation()`.
|
|
98
|
+
|
|
99
|
+
## Anti-patterns (compile-clean but wrong)
|
|
100
|
+
|
|
101
|
+
- Don't reach into `node_modules/@gusto/baerly-storage/dist/` at runtime —
|
|
102
|
+
consume the published exports.
|
|
103
|
+
- Don't widen branded types (`UUID`, `ContentVersionId`) with `as string`.
|
|
104
|
+
- Don't put `SHARED_SECRET` in the SPA bundle — it is server-to-server
|
|
105
|
+
only.
|
|
106
|
+
- Don't mutate `VerifierResult.tenantPrefix` between the verifier and
|
|
107
|
+
`Db.create` — the dispatcher pins the tenant from the verifier's return.
|
|
108
|
+
- `z.string().nullable()` in a schema — `DocumentValue` excludes `null`.
|
|
109
|
+
- Raw SQL / `WHERE` clauses / hand-built query AST — the only query
|
|
110
|
+
surface is the `.where(...)` method chain.
|
|
111
|
+
- `.all()` on a hot path — page or cursor-iterate; `.all()` is for
|
|
112
|
+
bounded result sets.
|
|
113
|
+
- Relying on baerly to cap or scope a read. `GET /v1/c/:collection` (and
|
|
114
|
+
`.all()`) returns the **whole collection** — there is no default row
|
|
115
|
+
cap, and auth pins a tenant, not a row owner. Scope non-owner reads in
|
|
116
|
+
your own route: inject a `where owner_id = <verified id>` predicate
|
|
117
|
+
(ideally index-backed) and clamp `limit = min(requested ?? MAX, MAX)`.
|
|
118
|
+
Rejecting `?limit` backfires — it forces the uncapped path. See
|
|
119
|
+
`docs/guide/auth.md` § Authorization Boundary.
|
|
120
|
+
|
|
121
|
+
## Where to look next
|
|
122
|
+
|
|
123
|
+
- Public API surface: `dist/API.md` (`cat node_modules/@gusto/baerly-storage/dist/API.md`).
|
|
124
|
+
- Per-symbol types: the `dist/*.d.ts` chunks.
|
|
125
|
+
- A remembered call no longer type-checks: `dist/CHANGELOG.md`.
|