@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.
Files changed (155) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +29 -0
  3. package/README.md +176 -70
  4. package/dist/API.md +213 -139
  5. package/dist/CHANGELOG.md +434 -0
  6. package/dist/RECIPES.md +125 -0
  7. package/dist/THIRD-PARTY-LICENSES.txt +238 -0
  8. package/dist/{app-config-C0Bbw_Z6.d.ts → app-config-DyiFK3_k.d.ts} +55 -11
  9. package/dist/app-config.d.ts +1 -1
  10. package/dist/auth.d.ts +1 -1
  11. package/dist/auth.js +301 -301
  12. package/dist/auth.js.map +1 -1
  13. package/dist/aws4fetch.esm-p7eEzLCs.js +1702 -0
  14. package/dist/aws4fetch.esm-p7eEzLCs.js.map +1 -0
  15. package/dist/baerly.js +35 -15
  16. package/dist/baerly.js.map +1 -1
  17. package/dist/baerly.spec.json +342 -0
  18. package/dist/bytes-BXdamO3L.js.map +1 -1
  19. package/dist/{client-DYZfoZb9.d.ts → client-Fe8CwB73.d.ts} +10 -10
  20. package/dist/client-react.d.ts +3 -3
  21. package/dist/client-react.js +4 -4
  22. package/dist/client-react.js.map +1 -1
  23. package/dist/client.d.ts +4 -4
  24. package/dist/client.js +3 -3
  25. package/dist/client.js.map +1 -1
  26. package/dist/{cloudflare-CINJPKCW.js → cloudflare-DzKBrUlg.js} +178 -2
  27. package/dist/cloudflare-DzKBrUlg.js.map +1 -0
  28. package/dist/cloudflare.d.ts +49 -6
  29. package/dist/cloudflare.js +59 -26
  30. package/dist/cloudflare.js.map +1 -1
  31. package/dist/config-1tv0-Yzm.js +2693 -0
  32. package/dist/config-1tv0-Yzm.js.map +1 -0
  33. package/dist/constants-CfeMWQWk.js +222 -0
  34. package/dist/constants-CfeMWQWk.js.map +1 -0
  35. package/dist/context-DRZ3tZ5l.js.map +1 -1
  36. package/dist/{cost-CQt1YRkA.js → cost-DSMIVqzL.js} +43 -42
  37. package/dist/cost-DSMIVqzL.js.map +1 -0
  38. package/dist/current-json-C6nhPOm1.js +190 -0
  39. package/dist/current-json-C6nhPOm1.js.map +1 -0
  40. package/dist/{db-BM3y2JQw.d.ts → db-DsPkOVEH.d.ts} +26 -108
  41. package/dist/{deploy-CrAbfgCq.js → deploy-DonTr-CV.js} +12 -5
  42. package/dist/deploy-DonTr-CV.js.map +1 -0
  43. package/dist/dev-vite.d.ts +11 -7
  44. package/dist/dev-vite.js +7 -6
  45. package/dist/dev-vite.js.map +1 -1
  46. package/dist/dev.d.ts +1 -1
  47. package/dist/dev.js +1 -1
  48. package/dist/{doctor-Db-hzPmE.js → doctor-DSIyCDg_.js} +14 -136
  49. package/dist/doctor-DSIyCDg_.js.map +1 -0
  50. package/dist/{dump-BYA55NLP.js → dump-Bh5k26VQ.js} +10 -31
  51. package/dist/dump-Bh5k26VQ.js.map +1 -0
  52. package/dist/{errors-DOdL95kK.js → errors-Dfa3p78c.js} +25 -5
  53. package/dist/errors-Dfa3p78c.js.map +1 -0
  54. package/dist/{export-Bhbz90-z.js → export-DtF5tDIM.js} +11 -32
  55. package/dist/{export-Bhbz90-z.js.map → export-DtF5tDIM.js.map} +1 -1
  56. package/dist/{fsck-CPPZWt9p.js → fsck-D_djMO5D.js} +28 -39
  57. package/dist/fsck-D_djMO5D.js.map +1 -0
  58. package/dist/{http-Cw8p6y5b.js → http-DxM9MflO.js} +151 -79
  59. package/dist/http-DxM9MflO.js.map +1 -0
  60. package/dist/http.d.ts +42 -26
  61. package/dist/http.js +3 -2
  62. package/dist/{index-DwDTWPSU.d.ts → index-0rZcMBwy.d.ts} +10 -7
  63. package/dist/{index-C3JAH1Yo.d.ts → index-B6oexfOB.d.ts} +9 -9
  64. package/dist/{index-cUY-36AN.d.ts → index-BNRh23K9.d.ts} +21 -5
  65. package/dist/{index-DSvwEUeF.d.ts → index-BYk9oCNf.d.ts} +240 -202
  66. package/dist/index.d.ts +6 -6
  67. package/dist/index.js +5 -5
  68. package/dist/{indexes-DAu2AkTW.d.ts → indexes-Dn9hbGQG.d.ts} +2 -2
  69. package/dist/{inspect-Bdbzvi-_.js → inspect-6WZ-pC7-.js} +21 -36
  70. package/dist/inspect-6WZ-pC7-.js.map +1 -0
  71. package/dist/key-Di6yyxFu.js +35 -0
  72. package/dist/key-Di6yyxFu.js.map +1 -0
  73. package/dist/{snapshot-SS8USDUF.js → log-tail-D98U1JBo.js} +179 -84
  74. package/dist/log-tail-D98U1JBo.js.map +1 -0
  75. package/dist/{maintenance-ClzBC1Vv.js → maintenance-B4Dki6Ig.js} +438 -176
  76. package/dist/maintenance-B4Dki6Ig.js.map +1 -0
  77. package/dist/{maintenance-BRrThz8V.d.ts → maintenance-B_e0T99L.d.ts} +114 -26
  78. package/dist/{maintenance-BvOv6BMM.js → maintenance-C7coQp4c.js} +217 -94
  79. package/dist/maintenance-C7coQp4c.js.map +1 -0
  80. package/dist/maintenance.d.ts +3 -2
  81. package/dist/maintenance.js +3 -2
  82. package/dist/node.d.ts +176 -68
  83. package/dist/node.js +3 -2
  84. package/dist/{normalize-XWY25_sG.js → normalize-rjnZLwS4.js} +2 -2
  85. package/dist/normalize-rjnZLwS4.js.map +1 -0
  86. package/dist/{observability-CpOiEN0k.js → observability-wzs3-BL_.js} +279 -109
  87. package/dist/observability-wzs3-BL_.js.map +1 -0
  88. package/dist/observability.d.ts +3 -3
  89. package/dist/observability.js +1 -1
  90. package/dist/{plan-DOTl21vq.js → plan-a7PJHBCy.js} +7 -4
  91. package/dist/plan-a7PJHBCy.js.map +1 -0
  92. package/dist/{query-BmiQy328.js → query-rAtXNQQB.js} +1063 -1202
  93. package/dist/query-rAtXNQQB.js.map +1 -0
  94. package/dist/{rebuild-index-DC_nR6wP.js → rebuild-index-BVzQSZlm.js} +10 -32
  95. package/dist/rebuild-index-BVzQSZlm.js.map +1 -0
  96. package/dist/{request-BEF_OvMh.js → request-u0M51mhJ.js} +3 -3
  97. package/dist/{request-BEF_OvMh.js.map → request-u0M51mhJ.js.map} +1 -1
  98. package/dist/restore-R-4rbciV.js +778 -0
  99. package/dist/restore-R-4rbciV.js.map +1 -0
  100. package/dist/runtime-spec-qL3_lTTU.js +391 -0
  101. package/dist/runtime-spec-qL3_lTTU.js.map +1 -0
  102. package/dist/s3-http-B-z8th6O.d.ts +60 -0
  103. package/dist/s3.d.ts +47 -0
  104. package/dist/s3.js +45 -0
  105. package/dist/s3.js.map +1 -0
  106. package/dist/{shared-secret-BJdSwpgw.js → shared-secret-DgEicd3x.js} +13 -5
  107. package/dist/shared-secret-DgEicd3x.js.map +1 -0
  108. package/dist/src-BG20LZs7.js +2271 -0
  109. package/dist/src-BG20LZs7.js.map +1 -0
  110. package/dist/{src-zhEAmmF7.js → src-CYHFDrKz.js} +82 -99
  111. package/dist/src-CYHFDrKz.js.map +1 -0
  112. package/dist/{src-QQ7jDeL2.js → src-DYZ4H1aF.js} +44 -23
  113. package/dist/src-DYZ4H1aF.js.map +1 -0
  114. package/dist/subcommand-DoDA-K7d.js +197 -0
  115. package/dist/subcommand-DoDA-K7d.js.map +1 -0
  116. package/dist/time-DUqvFMHq.js +119 -0
  117. package/dist/time-DUqvFMHq.js.map +1 -0
  118. package/dist/{usage-CLjirdD-.js → usage-DBV1eQHC.js} +7 -22
  119. package/dist/usage-DBV1eQHC.js.map +1 -0
  120. package/dist/{validate-DCq_0DIn.js → validate-DtljsCh1.js} +51 -51
  121. package/dist/{validate-DCq_0DIn.js.map → validate-DtljsCh1.js.map} +1 -1
  122. package/dist/wire-izfGZDvr.js.map +1 -1
  123. package/package.json +77 -42
  124. package/dist/cloudflare-CINJPKCW.js.map +0 -1
  125. package/dist/config-DVfDGyw1.js +0 -278
  126. package/dist/config-DVfDGyw1.js.map +0 -1
  127. package/dist/cost-CQt1YRkA.js.map +0 -1
  128. package/dist/current-json-C-EyJqs0.js +0 -354
  129. package/dist/current-json-C-EyJqs0.js.map +0 -1
  130. package/dist/deploy-CrAbfgCq.js.map +0 -1
  131. package/dist/doctor-Db-hzPmE.js.map +0 -1
  132. package/dist/dump-BYA55NLP.js.map +0 -1
  133. package/dist/errors-DOdL95kK.js.map +0 -1
  134. package/dist/fsck-CPPZWt9p.js.map +0 -1
  135. package/dist/http-Cw8p6y5b.js.map +0 -1
  136. package/dist/inspect-Bdbzvi-_.js.map +0 -1
  137. package/dist/maintenance-BvOv6BMM.js.map +0 -1
  138. package/dist/maintenance-ClzBC1Vv.js.map +0 -1
  139. package/dist/normalize-XWY25_sG.js.map +0 -1
  140. package/dist/observability-CpOiEN0k.js.map +0 -1
  141. package/dist/plan-DOTl21vq.js.map +0 -1
  142. package/dist/query-BmiQy328.js.map +0 -1
  143. package/dist/rebuild-index-DC_nR6wP.js.map +0 -1
  144. package/dist/restore-C6IcmLeA.js +0 -771
  145. package/dist/restore-C6IcmLeA.js.map +0 -1
  146. package/dist/shared-secret-BJdSwpgw.js.map +0 -1
  147. package/dist/snapshot-SS8USDUF.js.map +0 -1
  148. package/dist/src-DU1sCMlr.js +0 -6236
  149. package/dist/src-DU1sCMlr.js.map +0 -1
  150. package/dist/src-QQ7jDeL2.js.map +0 -1
  151. package/dist/src-zhEAmmF7.js.map +0 -1
  152. package/dist/subcommand-DZcHcsYp.js +0 -5122
  153. package/dist/subcommand-DZcHcsYp.js.map +0 -1
  154. package/dist/usage-CLjirdD-.js.map +0 -1
  155. /package/dist/{chunk-EAsCxrDo.js → rolldown-runtime-EAsCxrDo.js} +0 -0
package/dist/node.d.ts CHANGED
@@ -1,64 +1,9 @@
1
- import { n as BaerlyAppConfig } from "./app-config-C0Bbw_Z6.js";
2
- import { _ as StorageGetResult, b as StoragePutResult, g as StorageGetOptions, h as Storage, r as Verifier, v as StorageListEntry, y as StoragePutOptions } from "./index-DSvwEUeF.js";
3
- import { i as DevLandingOptions } from "./index-DwDTWPSU.js";
4
- import { d as ObservabilityConfig } from "./index-C3JAH1Yo.js";
1
+ import { n as BaerlyAppConfig } from "./app-config-DyiFK3_k.js";
2
+ import { p as Storage, r as Verifier } from "./index-BYk9oCNf.js";
3
+ import { i as DevLandingOptions } from "./index-0rZcMBwy.js";
4
+ import { d as ObservabilityConfig } from "./index-B6oexfOB.js";
5
+ import { n as S3HttpStorageOptions, t as S3HttpStorage } from "./s3-http-B-z8th6O.js";
5
6
 
6
- //#region packages/adapter-node/src/s3-http.d.ts
7
- /**
8
- * Construction-time options for {@link S3HttpStorage}. Everything is
9
- * optional except `endpoint` and `bucket`; the consumer chooses how
10
- * to satisfy `fetch` (browser/Node global vs. injected) and `sign`
11
- * (anonymous Minio vs. SigV4-signed via aws4fetch).
12
- */
13
- interface S3HttpStorageOptions {
14
- /**
15
- * S3 endpoint URL, e.g. `https://s3.us-east-1.amazonaws.com` or
16
- * `http://127.0.0.1:9102` (Minio). Trailing slashes are trimmed.
17
- */
18
- endpoint: string;
19
- /** S3 bucket name. */
20
- bucket: string;
21
- /**
22
- * `fetch` implementation. Defaults to `globalThis.fetch.bind(globalThis)`.
23
- * Tests pass a `vi.fn()` stub.
24
- */
25
- fetch?: typeof fetch;
26
- /**
27
- * Signs requests before send. Pass `undefined` for anonymous
28
- * (Minio without creds). The seam is `(req) => Promise<req>` so
29
- * SigV4 implementations like `aws4fetch.AwsClient.sign` plug in
30
- * directly.
31
- */
32
- sign?: (req: Request) => Promise<Request>;
33
- /** Max retries for transient (non-permanent) failures. */
34
- retries?: number;
35
- /** Initial backoff in ms. */
36
- backoffMs?: number;
37
- }
38
- /**
39
- * `Storage` impl that speaks the S3 REST API directly. Works against
40
- * any S3-compatible endpoint — AWS S3, R2 (S3-compat), GCS (S3-compat),
41
- * Minio. Does not depend on any AWS SDK.
42
- *
43
- * Authentication is plugged in via the `sign` callback; this class
44
- * itself does no SigV4. For Cloudflare Workers, the R2 binding fast
45
- * path lives in `@baerly/adapter-cloudflare`.
46
- */
47
- declare class S3HttpStorage implements Storage {
48
- #private;
49
- constructor(options: S3HttpStorageOptions);
50
- get(key: string, opts?: StorageGetOptions): Promise<StorageGetResult | null>;
51
- put(key: string, body: Uint8Array, opts?: StoragePutOptions): Promise<StoragePutResult>;
52
- delete(key: string, opts?: {
53
- signal?: AbortSignal;
54
- }): Promise<void>;
55
- list(prefix: string, opts?: {
56
- startAfter?: string;
57
- maxKeys?: number;
58
- signal?: AbortSignal;
59
- }): AsyncIterable<StorageListEntry>;
60
- }
61
- //#endregion
62
7
  //#region packages/adapter-node/src/credentials/types.d.ts
63
8
  /**
64
9
  * Temporary or static AWS-shaped credentials. Field shape matches
@@ -119,14 +64,14 @@ type CredentialsProvider = () => Promise<Credentials>;
119
64
  * });
120
65
  * ```
121
66
  *
122
- * @example EKS Pod Identity (refreshing)
67
+ * @example EKS (refreshing) — auto-detects Pod Identity or IRSA
123
68
  * ```ts
124
- * import { s3Storage, fromEksPodIdentity } from "@gusto/baerly-storage/node";
69
+ * import { s3Storage, fromEks } from "@gusto/baerly-storage/node";
125
70
  *
126
71
  * const storage = s3Storage({
127
72
  * region: process.env["AWS_REGION"] ?? "us-east-1",
128
73
  * bucket: process.env["BUCKET"]!,
129
- * credentials: fromEksPodIdentity(),
74
+ * credentials: fromEks(),
130
75
  * });
131
76
  * ```
132
77
  */
@@ -198,9 +143,14 @@ declare function minioStorage(opts: {
198
143
  * goes into `credentials.accessKeyId` and the HMAC secret goes into
199
144
  * `credentials.secretAccessKey`. Region is pinned to `"auto"`.
200
145
  *
201
- * GCS's S3-compat surface supports the four `Storage` methods
202
- * (`get`/`put`/`delete`/`list`) but not all of S3's optional
203
- * features — stick to the kernel surface and you're fine.
146
+ * GCS's S3-compat surface covers the four `Storage` methods
147
+ * (`get`/`put`/`delete`/`list`), but Google documents the
148
+ * `If-Match`/`If-None-Match` headers this kernel coordinates on as
149
+ * read-only (native conditional writes use `x-goog-if-generation-match`).
150
+ * Whether GCS's interop layer enforces S3-style conditional *writes* is
151
+ * unverified — run `baerly doctor --bucket=<your-gcs-bucket>` before
152
+ * relying on it; a backend that fails the CAS probe is not a safe baerly
153
+ * store. See ADR-002.
204
154
  *
205
155
  * @example
206
156
  * ```ts
@@ -220,6 +170,140 @@ declare function gcsStorage(opts: {
220
170
  credentials: Credentials | CredentialsProvider;
221
171
  }): Storage;
222
172
  //#endregion
173
+ //#region packages/adapter-node/src/local-fs-storage.d.ts
174
+ interface LocalFsStorageFactoryOptions {
175
+ /**
176
+ * Root data directory. Resolution order: this option →
177
+ * `$BAERLY_DATA_DIR` → `<cwd>/.baerly-data`.
178
+ */
179
+ readonly dataDir?: string;
180
+ }
181
+ /**
182
+ * Zero-config local `Storage` for single-node dev / self-hosted runs.
183
+ * Persists to the filesystem (content-addressed, atomic writes), so data
184
+ * survives process restarts — unlike `MemoryStorage`, which is per-process
185
+ * and lost on exit.
186
+ *
187
+ * NOT for multi-instance production: `LocalFsStorage`'s `ifMatch` CAS is
188
+ * in-process TOCTOU only (cross-process `current.json` CAS-advance is not
189
+ * atomic — see its class JSDoc). For horizontally-scaled deploys use
190
+ * `s3Storage` / `r2Storage`, whose cross-process guarantee the no-lease
191
+ * maintenance fold relies on.
192
+ *
193
+ * @example
194
+ * ```ts
195
+ * import { baerlyNode, localFsStorage } from "@gusto/baerly-storage/node";
196
+ * import config from "./baerly.config.ts";
197
+ *
198
+ * // Runs with zero credentials; persists to ./.baerly-data.
199
+ * await baerlyNode({ config, storage: localFsStorage() }).listen(8080);
200
+ * ```
201
+ */
202
+ declare const localFsStorage: (opts?: LocalFsStorageFactoryOptions) => Storage;
203
+ //#endregion
204
+ //#region packages/adapter-node/src/resolve-storage.d.ts
205
+ /** Result of {@link resolveStorageFromEnv}. */
206
+ interface ResolvedStorage {
207
+ readonly storage: Storage;
208
+ /** Human-readable backend label for a startup log line. */
209
+ readonly label: string;
210
+ }
211
+ /**
212
+ * Choose a Node `Storage` backend from environment variables, in priority
213
+ * order:
214
+ * 1. `R2_ACCOUNT_ID` set → Cloudflare R2 (S3-compat endpoint)
215
+ * 2. `BUCKET` set → AWS S3
216
+ * 3. neither, local dev → `localFsStorage` (zero credentials)
217
+ * 4. neither, deployed → throw
218
+ *
219
+ * This is the safe default the example scaffolds use, exported so apps
220
+ * don't hand-roll their own selector and reintroduce the silent
221
+ * in-memory / local-fs fallback this library exists to prevent. There is
222
+ * deliberately **no** fallback to a non-durable store in a deployment:
223
+ * local-fs is single-process with no cross-process CAS and no crash
224
+ * durability, and in-memory storage loses all data on restart, so a
225
+ * deployed environment with no bucket fails loud instead.
226
+ *
227
+ * `env` is injectable for testing; it defaults to `process.env`.
228
+ *
229
+ * @throws BaerlyError `InvalidConfig` when {@link isDeployedEnv} is true
230
+ * and no bucket is configured, or when a configured bucket is missing its
231
+ * credentials.
232
+ *
233
+ * @example
234
+ * ```ts
235
+ * import { baerlyNode, resolveStorageFromEnv } from "@gusto/baerly-storage/node";
236
+ * import config from "./baerly.config.ts";
237
+ *
238
+ * const { storage, label } = resolveStorageFromEnv();
239
+ * console.log(`[baerly] storage=${label}`);
240
+ * await baerlyNode({ config, storage }).listen(Number(process.env["PORT"] ?? 8080));
241
+ * ```
242
+ */
243
+ declare const resolveStorageFromEnv: (env?: Record<string, string | undefined>) => ResolvedStorage;
244
+ //#endregion
245
+ //#region packages/adapter-node/src/assert-storage-reachable.d.ts
246
+ /** Options for {@link assertStorageReachable}. */
247
+ interface AssertStorageReachableOptions {
248
+ /** Key prefix for the throwaway probe sentinels. Default `""`. */
249
+ keyPrefix?: string;
250
+ signal?: AbortSignal;
251
+ }
252
+ /**
253
+ * Boot-time readiness check: confirm a live `Storage` backend is both
254
+ * reachable and honours the conditional writes the protocol depends on.
255
+ * `await` it at startup (or from a `/readyz` handler wired to your
256
+ * platform's readiness probe) to fail closed on a misconfigured backend —
257
+ * an unreachable or non-existent bucket, denied/missing credentials (wrong
258
+ * endpoint/region), or an S3-compatible store that silently ignores
259
+ * `If-Match`/`If-None-Match` (the CAS the protocol depends on) — instead
260
+ * of discovering it on the first user write. It cannot detect a
261
+ * wrong-but-writable bucket: a typo to another reachable bucket you own
262
+ * boots clean, because the probe can only tell that *a* bucket is reachable
263
+ * and CAS-correct, not that it is the *intended* one. This complements
264
+ * `resolveStorageFromEnv`, which catches a *missing* configuration:
265
+ * `assertStorageReachable` additionally catches an
266
+ * unreachable/access-denied/CAS-broken backend at boot instead of on the
267
+ * first write.
268
+ *
269
+ * Opt-in by design: it performs a handful of live round-trips (writes and
270
+ * deletes throwaway sentinels under `keyPrefix`), so it is never run
271
+ * automatically on every boot. Reuses the same `probeCas` machinery as
272
+ * `baerly doctor --bucket`.
273
+ *
274
+ * @throws BaerlyError `NetworkError` if the backend is unreachable, or
275
+ * `InvalidConfig` if it is reachable but fails a required CAS check.
276
+ *
277
+ * @example
278
+ * ```ts
279
+ * const { storage, label } = resolveStorageFromEnv();
280
+ * await assertStorageReachable(storage); // throws before we serve traffic
281
+ * console.log(`[baerly] storage=${label} (reachable)`);
282
+ * ```
283
+ */
284
+ declare const assertStorageReachable: (storage: Storage, opts?: AssertStorageReachableOptions) => Promise<void>;
285
+ //#endregion
286
+ //#region packages/adapter-node/src/credentials/from-eks.d.ts
287
+ /**
288
+ * Resolve AWS credentials on EKS regardless of which identity mechanism the
289
+ * cluster uses, so callers don't have to know. EKS injects credentials one of
290
+ * two ways:
291
+ *
292
+ * - **Pod Identity** (2023+): `AWS_CONTAINER_CREDENTIALS_FULL_URI` +
293
+ * `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE` → {@link fromEksPodIdentity}.
294
+ * - **IRSA** (web-identity token): `AWS_ROLE_ARN` +
295
+ * `AWS_WEB_IDENTITY_TOKEN_FILE` → {@link fromWebIdentity}.
296
+ *
297
+ * Detection runs on every resolve (Pod Identity preferred when both are
298
+ * present), so the right mechanism is picked even if the env is populated late
299
+ * and re-checked on each refresh. Use this instead of the mechanism-specific
300
+ * providers unless you have a reason to pin one.
301
+ */
302
+ declare function fromEks(opts?: {
303
+ fetch?: typeof fetch;
304
+ readFile?: (path: string, encoding: "utf8") => Promise<string>;
305
+ }): CredentialsProvider;
306
+ //#endregion
223
307
  //#region packages/adapter-node/src/credentials/from-eks-pod-identity.d.ts
224
308
  /**
225
309
  * Resolve AWS credentials from the EKS Pod Identity agent (the 2023
@@ -241,6 +325,30 @@ declare function fromEksPodIdentity(opts?: {
241
325
  readFile?: (path: string, encoding: "utf8") => Promise<string>;
242
326
  }): CredentialsProvider;
243
327
  //#endregion
328
+ //#region packages/adapter-node/src/credentials/from-web-identity.d.ts
329
+ /**
330
+ * Resolve AWS credentials via IRSA (IAM Roles for Service Accounts) — the
331
+ * web-identity-token flow, distinct from the EKS Pod Identity agent that
332
+ * {@link fromEksPodIdentity} handles. EKS projects a signed service-account
333
+ * token into the pod and the app exchanges it for short-lived credentials by
334
+ * calling STS `AssumeRoleWithWebIdentity` directly (the token *is* the auth, so
335
+ * the call is unsigned — no chicken-and-egg credential bootstrap).
336
+ *
337
+ * Env vars (set by EKS when the pod's service account is annotated with a role):
338
+ * - `AWS_ROLE_ARN` — the role to assume.
339
+ * - `AWS_WEB_IDENTITY_TOKEN_FILE` — path to the projected SA token.
340
+ * - `AWS_ROLE_SESSION_NAME` — optional session name (defaults to `baerly-storage`).
341
+ * - `AWS_REGION` / `AWS_DEFAULT_REGION` — optional; selects the regional STS
342
+ * endpoint (falls back to the global endpoint).
343
+ *
344
+ * STS credentials expire (~1 h); the returned provider reports `expiration`, so
345
+ * the signing layer re-resolves before they lapse.
346
+ */
347
+ declare function fromWebIdentity(opts?: {
348
+ fetch?: typeof fetch;
349
+ readFile?: (path: string, encoding: "utf8") => Promise<string>;
350
+ }): CredentialsProvider;
351
+ //#endregion
244
352
  //#region packages/adapter-node/src/baerly-node.d.ts
245
353
  /**
246
354
  * Options for {@link baerlyNode}. Composes the {@link createApp}
@@ -331,7 +439,7 @@ interface BaerlyNodeHandle {
331
439
  * INLINE on the (rare) write that crosses a maintenance trigger —
332
440
  * `createFetchHandler` threads a Node-tier `MaintenanceDispatch`
333
441
  * onto the per-request observability context, which the writer reads at
334
- * its post-CAS dispatch point. Reads never tick. Tune via the
442
+ * its post-commit dispatch point. Reads never tick. Tune via the
335
443
  * `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` / `BAERLY_MAINTENANCE_DISABLE`
336
444
  * env vars; for an explicit out-of-band sweep, call
337
445
  * `runScheduledMaintenance` from `@gusto/baerly-storage` directly.
@@ -359,5 +467,5 @@ interface BaerlyNodeHandle {
359
467
  */
360
468
  declare function baerlyNode(opts: BaerlyNodeOptions): BaerlyNodeHandle;
361
469
  //#endregion
362
- export { type BaerlyNodeHandle, type BaerlyNodeOptions, type Credentials, type CredentialsProvider, S3HttpStorage, type S3HttpStorageOptions, baerlyNode, fromEksPodIdentity, gcsStorage, minioStorage, r2Storage, s3Storage };
470
+ export { type AssertStorageReachableOptions, type BaerlyNodeHandle, type BaerlyNodeOptions, type Credentials, type CredentialsProvider, type LocalFsStorageFactoryOptions, type ResolvedStorage, S3HttpStorage, type S3HttpStorageOptions, assertStorageReachable, baerlyNode, fromEks, fromEksPodIdentity, fromWebIdentity, gcsStorage, localFsStorage, minioStorage, r2Storage, resolveStorageFromEnv, s3Storage };
363
471
  //# sourceMappingURL=node.d.ts.map
package/dist/node.js CHANGED
@@ -1,2 +1,3 @@
1
- import { a as minioStorage, c as S3HttpStorage, i as gcsStorage, o as r2Storage, r as fromEksPodIdentity, s as s3Storage, t as baerlyNode } from "./src-DU1sCMlr.js";
2
- export { S3HttpStorage, baerlyNode, fromEksPodIdentity, gcsStorage, minioStorage, r2Storage, s3Storage };
1
+ import { a as fromEksPodIdentity, c as localFsStorage, d as r2Storage, f as s3Storage, i as fromWebIdentity, l as gcsStorage, o as assertStorageReachable, r as fromEks, s as resolveStorageFromEnv, t as baerlyNode, u as minioStorage } from "./src-BG20LZs7.js";
2
+ import { n as S3HttpStorage } from "./aws4fetch.esm-p7eEzLCs.js";
3
+ export { S3HttpStorage, assertStorageReachable, baerlyNode, fromEks, fromEksPodIdentity, fromWebIdentity, gcsStorage, localFsStorage, minioStorage, r2Storage, resolveStorageFromEnv, s3Storage };
@@ -1,4 +1,4 @@
1
- import { t as BaerlyError } from "./errors-DOdL95kK.js";
1
+ import { t as BaerlyError } from "./errors-Dfa3p78c.js";
2
2
  //#region packages/protocol/src/query/builder.ts
3
3
  /**
4
4
  * Build a fresh `PredicateBuilder<T>` along with the clause-list
@@ -130,4 +130,4 @@ const normalizePredicateArg = (arg) => {
130
130
  //#endregion
131
131
  export { normalizePredicateArg as t };
132
132
 
133
- //# sourceMappingURL=normalize-XWY25_sG.js.map
133
+ //# sourceMappingURL=normalize-rjnZLwS4.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"normalize-rjnZLwS4.js","names":[],"sources":["../packages/protocol/src/query/builder.ts","../packages/protocol/src/query/normalize.ts"],"sourcesContent":["/**\n * Callback-form predicate DSL. `q.eq(\"status\", \"open\").gt(\"priority\",\n * 5)` builds a {@link PredicateWire} via methods on the\n * {@link PredicateBuilder} handle. Each method appends one\n * {@link PredicateClause} to a private list and returns the same\n * handle for chaining.\n *\n * Why a builder, not imported helpers? The methods that exist on\n * the type ARE the supported vocabulary — there is no\n * \"what we don't support\" page to maintain. The agent cannot call\n * `q.regex(...)` because there is no `regex` method; the compiler\n * surfaces the error before the request is sent.\n *\n * Companion modules: `./normalize.ts` (object → wire),\n * `./wire.ts` (wire types).\n */\n\nimport type { DocumentData, DocumentValue } from \"../json.ts\";\nimport type { Path, PathValue, Predicate } from \"../collection-api.ts\";\n\nimport type { PredicateClause, PredicateWire } from \"./wire.ts\";\n\n/**\n * Callback-form predicate builder. Methods append clauses and\n * return the same builder for chaining; chained calls AND-merge.\n *\n * The methods on this interface ARE the supported operator surface.\n * Vocabulary additions (`or`, `not`, `regex`, `ne`, `exists`, ...)\n * are intentionally absent — calling them is a TS2339 compile\n * error, not a runtime rejection. The algebra is conjunction-only in\n * perpetuity — see the API surface lock in\n * docs/contributing/conventions/change-discipline.md.\n *\n * @template T - the document shape the predicate is keyed against.\n */\nexport interface PredicateBuilder<T extends DocumentData = DocumentData> {\n /**\n * Strict equality on `field`. Use this for the in-callback\n * equality clauses that the object-form would also support;\n * mixing `q.eq(...)` with range / `in` clauses in one call is\n * the canonical \"mixed equality + range\" pattern.\n */\n eq<K extends Path<T>>(field: K, value: PathValue<T, K>): PredicateBuilder<T>;\n\n /**\n * Strict greater. `value` must be `string` or `number`; the\n * intersection at the type level rejects `boolean` / `null`\n * fields at the call site (`q.gt(\"done\", true)` is a TS error\n * on a `done: boolean` field).\n */\n gt<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;\n\n /** Inclusive greater. See {@link gt} for the value-type constraint. */\n gte<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;\n\n /** Strict less. See {@link gt} for the value-type constraint. */\n lt<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;\n\n /** Inclusive less. See {@link gt} for the value-type constraint. */\n lte<K extends Path<T>>(field: K, value: PathValue<T, K> & (string | number)): PredicateBuilder<T>;\n\n /**\n * Set membership. Empty array is `UnsatisfiablePredicate` at\n * normalise time — the validator emits the error eagerly so the\n * caller sees it at the `.where(...)` call site, not later.\n */\n in<K extends Path<T>>(field: K, values: ReadonlyArray<PathValue<T, K>>): PredicateBuilder<T>;\n}\n\n/**\n * Argument shape accepted by `.where(...)`. Either the object-literal\n * equality form ({@link Predicate}) or a callback that drives a\n * {@link PredicateBuilder} and returns it (the chain terminator).\n */\nexport type PredicateArg<T extends DocumentData> =\n | Predicate<T>\n | ((q: PredicateBuilder<T>) => PredicateBuilder<T>);\n\n/**\n * Build a fresh `PredicateBuilder<T>` along with the clause-list\n * cell it appends to. Internal — `./normalize.ts` drives this.\n *\n * @internal\n */\nexport const makeBuilder = <T extends DocumentData>(): {\n builder: PredicateBuilder<T>;\n clauses: PredicateClause[];\n} => {\n const clauses: PredicateClause[] = [];\n const push = (clause: PredicateClause): PredicateBuilder<T> => {\n clauses.push(clause);\n return builder;\n };\n const builder: PredicateBuilder<T> = {\n eq: (field, value) => push({ op: \"eq\", field: String(field), value: value as DocumentValue }),\n gt: (field, value) => push({ op: \"gt\", field: String(field), value: value as DocumentValue }),\n gte: (field, value) => push({ op: \"gte\", field: String(field), value: value as DocumentValue }),\n lt: (field, value) => push({ op: \"lt\", field: String(field), value: value as DocumentValue }),\n lte: (field, value) => push({ op: \"lte\", field: String(field), value: value as DocumentValue }),\n in: (field, values) =>\n push({\n op: \"in\",\n field: String(field),\n value: [...(values as ReadonlyArray<DocumentValue>)],\n }),\n };\n return { builder, clauses };\n};\n\n/**\n * Tighter wire-form type after running through the builder helper —\n * not part of the public surface; `./normalize.ts` returns a plain\n * {@link PredicateWire}.\n *\n * @internal\n */\nexport const wireFromBuilder = <T extends DocumentData>(\n cb: (q: PredicateBuilder<T>) => PredicateBuilder<T>,\n): PredicateWire => {\n const { builder, clauses } = makeBuilder<T>();\n cb(builder);\n return { clauses };\n};\n","/**\n * Object-form → wire normaliser. Walks a `Predicate<T>` object\n * literal, flattens nested sub-predicates to dotted-path `eq`\n * clauses, and returns a {@link PredicateWire}. Rejects any\n * `$`-prefixed key as `InvalidConfig` — the operator vocabulary\n * lives on the callback DSL only.\n *\n * Semantic invariant: a sub-predicate object (every value is itself\n * an object) flattens to one `eq` clause per leaf — the same\n * open-world matching today's matcher delivers at\n * `./matches.ts:matchesValue` for sub-predicates.\n *\n * Companion modules: `./builder.ts` (callback → wire),\n * `./wire.ts` (types).\n */\n\nimport { BaerlyError } from \"../errors.ts\";\nimport type { DocumentData } from \"../json.ts\";\n\nimport { type PredicateArg, type PredicateBuilder, wireFromBuilder } from \"./builder.ts\";\nimport type { PredicateClause, PredicateWire } from \"./wire.ts\";\n\n// Inlined so the normaliser's chunk does not pull in `_internals.ts`\n// (which carries the merger/validator's heavier comparator helpers\n// the client never executes). Keeping a tiny local copy of formatPath\n// keeps the SPA bundle's predicate footprint to normalize+wire only.\nconst formatPath = (path: ReadonlyArray<string>): string =>\n path.length === 0 ? \"<root>\" : path.map((p) => JSON.stringify(p)).join(\".\");\n\n/**\n * Walk an object-literal predicate, emit one `PredicateClause[]`.\n * Pure primitive values become `eq` clauses at the current path;\n * nested objects recurse, flattening to dotted-path clauses.\n *\n * @internal Tested via the public `normalizePredicateArg` and the\n * normalize.test.ts suite.\n */\nexport const normalizeObject = (\n obj: DocumentData,\n basePath: ReadonlyArray<string>,\n): PredicateClause[] => {\n const out: PredicateClause[] = [];\n for (const key of Object.keys(obj)) {\n const path = [...basePath, key];\n if (key.startsWith(\"$\")) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `Unsupported predicate operator ${JSON.stringify(key)} at ${formatPath(basePath)} — operator vocabulary moved to the callback form (.where(q => q.gt(field, value))). $-keys are not accepted in object-form predicates.`,\n );\n }\n if (key === \"__proto__\" || key === \"constructor\" || key === \"prototype\") {\n throw new BaerlyError(\n \"InvalidConfig\",\n `Reserved key ${JSON.stringify(key)} not allowed in a predicate at ${formatPath(basePath)}.`,\n );\n }\n const value: unknown = (obj as Record<string, unknown>)[key];\n if (value === null || value === undefined) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `Predicate value at ${formatPath(path)} is ${value === null ? \"null\" : \"undefined\"} — terminal values must be string / number / boolean / nested object.`,\n );\n }\n if (Array.isArray(value)) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `Predicate value at ${formatPath(path)} is an array — match nested objects with a sub-predicate or use callback form (q.in(field, values)) for set membership.`,\n );\n }\n const t = typeof value;\n if (t === \"object\") {\n // Sub-predicate — recurse, accumulating dotted path. Object-form\n // predicates have NO operator vocabulary, so a nested object is\n // unambiguously a literal sub-predicate. Empty object `{}` at a\n // nested position is a match-all sub-clause: it emits zero\n // clauses for that subtree, which matches the matcher's\n // pre-redesign behaviour for `{ assignee: {} }` (an empty\n // sub-predicate accepts any non-null object actual).\n const inner = normalizeObject(value as DocumentData, path);\n for (const c of inner) {\n out.push(c);\n }\n continue;\n }\n if (t !== \"string\" && t !== \"number\" && t !== \"boolean\") {\n throw new BaerlyError(\n \"InvalidConfig\",\n `Predicate value at ${formatPath(path)} has unsupported type ${JSON.stringify(t)} — must be string / number / boolean / nested object.`,\n );\n }\n if (t === \"number\" && !Number.isFinite(value as number)) {\n throw new BaerlyError(\n \"InvalidConfig\",\n `Predicate value at ${formatPath(path)} is ${String(value)} — finite numbers only (NaN / Infinity do not round-trip through JSON).`,\n );\n }\n out.push({ op: \"eq\", field: path.join(\".\"), value: value as string | number | boolean });\n }\n return out;\n};\n\n/**\n * Dispatch the two-shape `.where(...)` argument to a\n * {@link PredicateWire}. The object-form is walked by\n * {@link normalizeObject}; the callback form is invoked with a\n * fresh {@link PredicateBuilder}.\n *\n * @internal — every consumer (`Db.collection().where`,\n * `ClientCollection.where`, `parseWhereParam`'s wire-arrival\n * path) routes through this single seam so the wire\n * format has exactly one parser path.\n */\nexport const normalizePredicateArg = <T extends DocumentData>(\n arg: PredicateArg<T>,\n): PredicateWire => {\n if (typeof arg === \"function\") {\n return wireFromBuilder<T>(arg as (q: PredicateBuilder<T>) => PredicateBuilder<T>);\n }\n return { clauses: normalizeObject(arg as DocumentData, []) };\n};\n"],"mappings":";;;;;;;;AAoFA,MAAa,oBAGR;CACH,MAAM,UAA6B,CAAC;CACpC,MAAM,QAAQ,WAAiD;EAC7D,QAAQ,KAAK,MAAM;EACnB,OAAO;CACT;CACA,MAAM,UAA+B;EACnC,KAAK,OAAO,UAAU,KAAK;GAAE,IAAI;GAAM,OAAO,OAAO,KAAK;GAAU;EAAuB,CAAC;EAC5F,KAAK,OAAO,UAAU,KAAK;GAAE,IAAI;GAAM,OAAO,OAAO,KAAK;GAAU;EAAuB,CAAC;EAC5F,MAAM,OAAO,UAAU,KAAK;GAAE,IAAI;GAAO,OAAO,OAAO,KAAK;GAAU;EAAuB,CAAC;EAC9F,KAAK,OAAO,UAAU,KAAK;GAAE,IAAI;GAAM,OAAO,OAAO,KAAK;GAAU;EAAuB,CAAC;EAC5F,MAAM,OAAO,UAAU,KAAK;GAAE,IAAI;GAAO,OAAO,OAAO,KAAK;GAAU;EAAuB,CAAC;EAC9F,KAAK,OAAO,WACV,KAAK;GACH,IAAI;GACJ,OAAO,OAAO,KAAK;GACnB,OAAO,CAAC,GAAI,MAAuC;EACrD,CAAC;CACL;CACA,OAAO;EAAE;EAAS;CAAQ;AAC5B;;;;;;;;AASA,MAAa,mBACX,OACkB;CAClB,MAAM,EAAE,SAAS,YAAY,YAAe;CAC5C,GAAG,OAAO;CACV,OAAO,EAAE,QAAQ;AACnB;;;;;;;;;;;;;;;;;;AChGA,MAAM,cAAc,SAClB,KAAK,WAAW,IAAI,WAAW,KAAK,KAAK,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG;;;;;;;;;AAU5E,MAAa,mBACX,KACA,aACsB;CACtB,MAAM,MAAyB,CAAC;CAChC,KAAK,MAAM,OAAO,OAAO,KAAK,GAAG,GAAG;EAClC,MAAM,OAAO,CAAC,GAAG,UAAU,GAAG;EAC9B,IAAI,IAAI,WAAW,GAAG,GACpB,MAAM,IAAI,YACR,iBACA,kCAAkC,KAAK,UAAU,GAAG,EAAE,MAAM,WAAW,QAAQ,EAAE,wIACnF;EAEF,IAAI,QAAQ,eAAe,QAAQ,iBAAiB,QAAQ,aAC1D,MAAM,IAAI,YACR,iBACA,gBAAgB,KAAK,UAAU,GAAG,EAAE,iCAAiC,WAAW,QAAQ,EAAE,EAC5F;EAEF,MAAM,QAAkB,IAAgC;EACxD,IAAI,UAAU,QAAQ,UAAU,KAAA,GAC9B,MAAM,IAAI,YACR,iBACA,sBAAsB,WAAW,IAAI,EAAE,MAAM,UAAU,OAAO,SAAS,YAAY,sEACrF;EAEF,IAAI,MAAM,QAAQ,KAAK,GACrB,MAAM,IAAI,YACR,iBACA,sBAAsB,WAAW,IAAI,EAAE,wHACzC;EAEF,MAAM,IAAI,OAAO;EACjB,IAAI,MAAM,UAAU;GAQlB,MAAM,QAAQ,gBAAgB,OAAuB,IAAI;GACzD,KAAK,MAAM,KAAK,OACd,IAAI,KAAK,CAAC;GAEZ;EACF;EACA,IAAI,MAAM,YAAY,MAAM,YAAY,MAAM,WAC5C,MAAM,IAAI,YACR,iBACA,sBAAsB,WAAW,IAAI,EAAE,wBAAwB,KAAK,UAAU,CAAC,EAAE,sDACnF;EAEF,IAAI,MAAM,YAAY,CAAC,OAAO,SAAS,KAAe,GACpD,MAAM,IAAI,YACR,iBACA,sBAAsB,WAAW,IAAI,EAAE,MAAM,OAAO,KAAK,EAAE,wEAC7D;EAEF,IAAI,KAAK;GAAE,IAAI;GAAM,OAAO,KAAK,KAAK,GAAG;GAAU;EAAmC,CAAC;CACzF;CACA,OAAO;AACT;;;;;;;;;;;;AAaA,MAAa,yBACX,QACkB;CAClB,IAAI,OAAO,QAAQ,YACjB,OAAO,gBAAmB,GAAsD;CAElF,OAAO,EAAE,SAAS,gBAAgB,KAAqB,CAAC,CAAC,EAAE;AAC7D"}