@gusto/baerly-storage 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (215) hide show
  1. package/README.md +47 -124
  2. package/dist/API.md +161 -511
  3. package/dist/CHANGELOG.md +1148 -307
  4. package/dist/RECIPES.md +398 -80
  5. package/dist/THIRD-PARTY-LICENSES.txt +5 -26
  6. package/dist/{app-config-DyiFK3_k.d.ts → app-config-C6qW7m8S.d.ts} +119 -111
  7. package/dist/app-config.d.ts +31 -1
  8. package/dist/app-config.js +1 -2
  9. package/dist/app-config.js.map +1 -1
  10. package/dist/auth.d.ts +33 -28
  11. package/dist/auth.js +549 -985
  12. package/dist/auth.js.map +1 -1
  13. package/dist/baerly.js +130 -138
  14. package/dist/baerly.js.map +1 -1
  15. package/dist/baerly.spec.json +97 -22
  16. package/dist/capacity-warning-header-BlVopyiI.js +16 -0
  17. package/dist/capacity-warning-header-BlVopyiI.js.map +1 -0
  18. package/dist/{client-Fe8CwB73.d.ts → client-CHQTXpef.d.ts} +121 -36
  19. package/dist/client-react.d.ts +67 -20
  20. package/dist/client-react.js +240 -54
  21. package/dist/client-react.js.map +1 -1
  22. package/dist/client.d.ts +5 -4
  23. package/dist/client.js +51 -16
  24. package/dist/client.js.map +1 -1
  25. package/dist/{cloudflare-DzKBrUlg.js → cloudflare-CKHYXccw.js} +504 -124
  26. package/dist/cloudflare-CKHYXccw.js.map +1 -0
  27. package/dist/cloudflare.d.ts +106 -71
  28. package/dist/cloudflare.js +334 -271
  29. package/dist/cloudflare.js.map +1 -1
  30. package/dist/code-resolution-CL_7L0wS.js +22 -0
  31. package/dist/code-resolution-CL_7L0wS.js.map +1 -0
  32. package/dist/collection-api-DbyhLAY8.d.ts +1001 -0
  33. package/dist/config-DEzInG6M.js +4035 -0
  34. package/dist/config-DEzInG6M.js.map +1 -0
  35. package/dist/constants-D3GSH3tc.js +469 -0
  36. package/dist/constants-D3GSH3tc.js.map +1 -0
  37. package/dist/{context-DRZ3tZ5l.js → context-rlpSnHFA.js} +17 -17
  38. package/dist/context-rlpSnHFA.js.map +1 -0
  39. package/dist/cost-B52llVDx.js +330 -0
  40. package/dist/cost-B52llVDx.js.map +1 -0
  41. package/dist/{current-json-C6nhPOm1.js → current-json-CC6lE4Aj.js} +115 -32
  42. package/dist/current-json-CC6lE4Aj.js.map +1 -0
  43. package/dist/db-plFUNTSF.d.ts +130 -0
  44. package/dist/db-read-seams-BSs0m1z1.js +3261 -0
  45. package/dist/db-read-seams-BSs0m1z1.js.map +1 -0
  46. package/dist/{deploy-DonTr-CV.js → deploy-Obj4nE-Z.js} +12 -16
  47. package/dist/deploy-Obj4nE-Z.js.map +1 -0
  48. package/dist/{dev-banner-CWHIk8tH.d.ts → dev-banner-B5AUHmu1.d.ts} +1 -4
  49. package/dist/dev-landing-BI5UdmOb.d.ts +32 -0
  50. package/dist/dev-landing-CD-si4dW.js +50 -0
  51. package/dist/dev-landing-CD-si4dW.js.map +1 -0
  52. package/dist/dev-vite.d.ts +38 -39
  53. package/dist/dev-vite.js +67 -36
  54. package/dist/dev-vite.js.map +1 -1
  55. package/dist/dev.d.ts +3 -2
  56. package/dist/dev.js +2 -1
  57. package/dist/doctor-BA0i-YAN.js +270 -0
  58. package/dist/doctor-BA0i-YAN.js.map +1 -0
  59. package/dist/dump-D1vX8ozg.js +133 -0
  60. package/dist/dump-D1vX8ozg.js.map +1 -0
  61. package/dist/errors-7Rk1HGCE.js +160 -0
  62. package/dist/errors-7Rk1HGCE.js.map +1 -0
  63. package/dist/{validate-DtljsCh1.js → export-BVL2EvYE.js} +409 -19
  64. package/dist/export-BVL2EvYE.js.map +1 -0
  65. package/dist/fsck-BWkPgov4.js +145 -0
  66. package/dist/fsck-BWkPgov4.js.map +1 -0
  67. package/dist/gcs-admin-Dso1HWQj.d.ts +127 -0
  68. package/dist/gcs.d.ts +30 -0
  69. package/dist/gcs.js +1 -0
  70. package/dist/goog4-signer-CeLIABoE.js +331 -0
  71. package/dist/goog4-signer-CeLIABoE.js.map +1 -0
  72. package/dist/{http-DGd5tbNs.js → http-Z5rZyYMX.js} +898 -271
  73. package/dist/http-Z5rZyYMX.js.map +1 -0
  74. package/dist/http-transport-DNUM8kU-.js +1299 -0
  75. package/dist/http-transport-DNUM8kU-.js.map +1 -0
  76. package/dist/http.d.ts +366 -294
  77. package/dist/http.js +2 -2
  78. package/dist/index-JJrIu1pO.d.ts +135 -0
  79. package/dist/index-LEgHN0qJ.d.ts +50 -0
  80. package/dist/{index-CuA9Mi3K.d.ts → index-RiEYj8t0.d.ts} +291 -78
  81. package/dist/index.d.ts +27 -6
  82. package/dist/index.js +3 -5
  83. package/dist/inspect-BTsVYZKd.js +196 -0
  84. package/dist/inspect-BTsVYZKd.js.map +1 -0
  85. package/dist/{key-Di6yyxFu.js → key-C4FPZ9Io.js} +3 -4
  86. package/dist/{key-Di6yyxFu.js.map → key-C4FPZ9Io.js.map} +1 -1
  87. package/dist/ledger-Dj_bGgo0.js +192 -0
  88. package/dist/ledger-Dj_bGgo0.js.map +1 -0
  89. package/dist/legacy-names-DgZBtgOh.js +47 -0
  90. package/dist/legacy-names-DgZBtgOh.js.map +1 -0
  91. package/dist/log-C9W15Dfo.d.ts +94 -0
  92. package/dist/log-tail-DWJbneBF.js +142 -0
  93. package/dist/log-tail-DWJbneBF.js.map +1 -0
  94. package/dist/log-walk-C-vA-WGJ.js +111 -0
  95. package/dist/log-walk-C-vA-WGJ.js.map +1 -0
  96. package/dist/maintenance-Dd-Yakqj.js +1709 -0
  97. package/dist/maintenance-Dd-Yakqj.js.map +1 -0
  98. package/dist/maintenance-DevB6z4e.js +2237 -0
  99. package/dist/maintenance-DevB6z4e.js.map +1 -0
  100. package/dist/maintenance.d.ts +100 -3
  101. package/dist/maintenance.js +1 -3
  102. package/dist/node.d.ts +130 -142
  103. package/dist/node.js +4 -3
  104. package/dist/{observability-BmflLCdF.js → observability-C-ISCCLE.js} +1275 -332
  105. package/dist/observability-C-ISCCLE.js.map +1 -0
  106. package/dist/observability.d.ts +27 -3
  107. package/dist/observability.js +3 -3
  108. package/dist/path-segment-DBXG26PW.js +363 -0
  109. package/dist/path-segment-DBXG26PW.js.map +1 -0
  110. package/dist/{plan-a7PJHBCy.js → plan-BvQbaNMe.js} +19 -11
  111. package/dist/plan-BvQbaNMe.js.map +1 -0
  112. package/dist/request-CRWiTrza.js +272 -0
  113. package/dist/request-CRWiTrza.js.map +1 -0
  114. package/dist/restore-U6Im8V1V.js +1467 -0
  115. package/dist/restore-U6Im8V1V.js.map +1 -0
  116. package/dist/retry-OBtLB2GC.js +126 -0
  117. package/dist/retry-OBtLB2GC.js.map +1 -0
  118. package/dist/rolldown-runtime-D3KUYPsf.js +12 -0
  119. package/dist/{runtime-spec-Dsw2-n8S.js → runtime-spec-B5mg3pHF.js} +189 -28
  120. package/dist/runtime-spec-B5mg3pHF.js.map +1 -0
  121. package/dist/{s3-http-B-z8th6O.d.ts → s3-http-DBC_wiCL.d.ts} +18 -10
  122. package/dist/s3.d.ts +20 -7
  123. package/dist/s3.js +4 -5
  124. package/dist/s3.js.map +1 -1
  125. package/dist/sha256-4FfGQNPw.js +22 -0
  126. package/dist/sha256-4FfGQNPw.js.map +1 -0
  127. package/dist/{shared-secret-DgEicd3x.js → shared-secret-Vkur-8r0.js} +27 -15
  128. package/dist/shared-secret-Vkur-8r0.js.map +1 -0
  129. package/dist/sigv4-sign-5IUflUD_.js +507 -0
  130. package/dist/sigv4-sign-5IUflUD_.js.map +1 -0
  131. package/dist/snapshot-CknzkDM0.js +148 -0
  132. package/dist/snapshot-CknzkDM0.js.map +1 -0
  133. package/dist/{src-BL_JoPTn.js → src-Actga-bO.js} +1004 -378
  134. package/dist/src-Actga-bO.js.map +1 -0
  135. package/dist/src-D0MQfvOp.js +812 -0
  136. package/dist/src-D0MQfvOp.js.map +1 -0
  137. package/dist/src-Dr9uo3dc.js +501 -0
  138. package/dist/src-Dr9uo3dc.js.map +1 -0
  139. package/dist/{subcommand-DoDA-K7d.js → subcommand-BLoF66dG.js} +89 -16
  140. package/dist/subcommand-BLoF66dG.js.map +1 -0
  141. package/dist/{time-DUqvFMHq.js → time-DRxTP9iv.js} +15 -34
  142. package/dist/time-DRxTP9iv.js.map +1 -0
  143. package/dist/types-suVbsEWS.d.ts +116 -0
  144. package/dist/{usage-DBV1eQHC.js → usage-CPzVhrQr.js} +40 -45
  145. package/dist/usage-CPzVhrQr.js.map +1 -0
  146. package/dist/uuid-BuT_c404.js +333 -0
  147. package/dist/uuid-BuT_c404.js.map +1 -0
  148. package/dist/verifier-Bmlmndzo.d.ts +95 -0
  149. package/dist/{wire-izfGZDvr.js → wire-DndvKU-K.js} +2 -3
  150. package/dist/wire-DndvKU-K.js.map +1 -0
  151. package/package.json +96 -69
  152. package/dist/aws4fetch.esm-p7eEzLCs.js +0 -1702
  153. package/dist/aws4fetch.esm-p7eEzLCs.js.map +0 -1
  154. package/dist/bytes-BXdamO3L.js +0 -11
  155. package/dist/bytes-BXdamO3L.js.map +0 -1
  156. package/dist/cloudflare-DzKBrUlg.js.map +0 -1
  157. package/dist/config-1tv0-Yzm.js +0 -2693
  158. package/dist/config-1tv0-Yzm.js.map +0 -1
  159. package/dist/constants-CfeMWQWk.js +0 -222
  160. package/dist/constants-CfeMWQWk.js.map +0 -1
  161. package/dist/context-DRZ3tZ5l.js.map +0 -1
  162. package/dist/cost-DSMIVqzL.js +0 -203
  163. package/dist/cost-DSMIVqzL.js.map +0 -1
  164. package/dist/current-json-C6nhPOm1.js.map +0 -1
  165. package/dist/db-DsPkOVEH.d.ts +0 -254
  166. package/dist/deploy-DonTr-CV.js.map +0 -1
  167. package/dist/doctor-DSIyCDg_.js +0 -346
  168. package/dist/doctor-DSIyCDg_.js.map +0 -1
  169. package/dist/dump-Bh5k26VQ.js +0 -94
  170. package/dist/dump-Bh5k26VQ.js.map +0 -1
  171. package/dist/errors-Dfa3p78c.js +0 -78
  172. package/dist/errors-Dfa3p78c.js.map +0 -1
  173. package/dist/export-DtF5tDIM.js +0 -401
  174. package/dist/export-DtF5tDIM.js.map +0 -1
  175. package/dist/fsck-D_djMO5D.js +0 -279
  176. package/dist/fsck-D_djMO5D.js.map +0 -1
  177. package/dist/http-DGd5tbNs.js.map +0 -1
  178. package/dist/index-0rZcMBwy.d.ts +0 -115
  179. package/dist/index-BNRh23K9.d.ts +0 -162
  180. package/dist/index-BYk9oCNf.d.ts +0 -1112
  181. package/dist/indexes-Dn9hbGQG.d.ts +0 -22
  182. package/dist/inspect-6WZ-pC7-.js +0 -133
  183. package/dist/inspect-6WZ-pC7-.js.map +0 -1
  184. package/dist/log-tail-D98U1JBo.js +0 -522
  185. package/dist/log-tail-D98U1JBo.js.map +0 -1
  186. package/dist/maintenance-B4Dki6Ig.js +0 -2157
  187. package/dist/maintenance-B4Dki6Ig.js.map +0 -1
  188. package/dist/maintenance-B_e0T99L.d.ts +0 -537
  189. package/dist/maintenance-C7coQp4c.js +0 -1418
  190. package/dist/maintenance-C7coQp4c.js.map +0 -1
  191. package/dist/normalize-rjnZLwS4.js +0 -133
  192. package/dist/normalize-rjnZLwS4.js.map +0 -1
  193. package/dist/observability-BmflLCdF.js.map +0 -1
  194. package/dist/plan-a7PJHBCy.js.map +0 -1
  195. package/dist/query-rAtXNQQB.js +0 -1773
  196. package/dist/query-rAtXNQQB.js.map +0 -1
  197. package/dist/rebuild-index-BVzQSZlm.js +0 -81
  198. package/dist/rebuild-index-BVzQSZlm.js.map +0 -1
  199. package/dist/request-u0M51mhJ.js +0 -72
  200. package/dist/request-u0M51mhJ.js.map +0 -1
  201. package/dist/restore-R-4rbciV.js +0 -778
  202. package/dist/restore-R-4rbciV.js.map +0 -1
  203. package/dist/rolldown-runtime-EAsCxrDo.js +0 -14
  204. package/dist/runtime-spec-Dsw2-n8S.js.map +0 -1
  205. package/dist/shared-secret-DgEicd3x.js.map +0 -1
  206. package/dist/src-BL_JoPTn.js.map +0 -1
  207. package/dist/src-CYHFDrKz.js +0 -536
  208. package/dist/src-CYHFDrKz.js.map +0 -1
  209. package/dist/src-DYZ4H1aF.js +0 -392
  210. package/dist/src-DYZ4H1aF.js.map +0 -1
  211. package/dist/subcommand-DoDA-K7d.js.map +0 -1
  212. package/dist/time-DUqvFMHq.js.map +0 -1
  213. package/dist/usage-DBV1eQHC.js.map +0 -1
  214. package/dist/validate-DtljsCh1.js.map +0 -1
  215. package/dist/wire-izfGZDvr.js.map +0 -1
@@ -1,3 +1,100 @@
1
- import { _ as MAINTENANCE_PROFILE_NODE, g as MAINTENANCE_PROFILE_CF_PAID, h as MAINTENANCE_PROFILE_CF_FREE } from "./app-config-DyiFK3_k.js";
2
- import { C as CompactOptions, S as runGc, T as compact, _ as RebuildIndexOptions, a as MaintenanceArgs, b as RunGcOptions, c as MaintenanceProfile, d as dispatchInlineAwaited, f as estimateTailBytes, g as shouldFireMaintenance, h as runScheduledMaintenance, i as InternalMaintenanceOptions, l as MaintenanceResult, m as runBoundedMaintenance, n as CLOUDFLARE_FREE_TIER, o as MaintenanceDispatch, p as parseMaintenanceEnv, r as CLOUDFLARE_PAID_TIER, s as MaintenanceOptions, t as BoundedMaintenanceOptions, u as crossesGcBoundary, v as RebuildIndexResult, w as CompactResult, x as RunGcResult, y as rebuildIndex } from "./maintenance-B_e0T99L.js";
3
- export { BoundedMaintenanceOptions, CLOUDFLARE_FREE_TIER, CLOUDFLARE_PAID_TIER, type CompactOptions, type CompactResult, InternalMaintenanceOptions, MAINTENANCE_PROFILE_CF_FREE, MAINTENANCE_PROFILE_CF_PAID, MAINTENANCE_PROFILE_NODE, MaintenanceArgs, MaintenanceDispatch, MaintenanceOptions, MaintenanceProfile, MaintenanceResult, type RebuildIndexOptions, type RebuildIndexResult, type RunGcOptions, type RunGcResult, compact, crossesGcBoundary, dispatchInlineAwaited, estimateTailBytes, parseMaintenanceEnv, rebuildIndex, runBoundedMaintenance, runGc, runScheduledMaintenance, shouldFireMaintenance };
1
+ /**
2
+ * Published `@gusto/baerly-storage/maintenance` entry: the opt-in
3
+ * scheduled-maintenance SDK, one function addressed by collection.
4
+ *
5
+ * The phases it composes (`compact`, `runGc`), the host tiers behind its
6
+ * `tier` option, the write-tick runner and env parsing live in
7
+ * `./maintenance.ts` and reach the CLI, adapters, and bench through the
8
+ * unpublished `@baerly/server/_internal/maintenance` subpath.
9
+ */
10
+ import { t as Storage } from "./types-suVbsEWS.js";
11
+ /**
12
+ * Run one opt-in scheduled maintenance pass over one collection: fold its
13
+ * recent writes, delete data nothing references any more, and retire old
14
+ * log entries. Optional: every write already runs bounded maintenance in
15
+ * band, so a collection that takes writes maintains itself. A schedule is
16
+ * for collections served mostly read-only, or to keep folding ahead of
17
+ * the write tick.
18
+ *
19
+ * One call does a bounded amount of work and returns; it never loops or
20
+ * retries, and it is safe to run concurrently with writes and with other
21
+ * passes. The caller schedules the next pass. Run one collection per
22
+ * Cloudflare invocation: shard the cron schedule or persist a collection
23
+ * cursor instead of looping tenants or collections in one invocation.
24
+ *
25
+ * `tier` sizes the pass for its host, in the `BAERLY_MAINTENANCE_PROFILE`
26
+ * vocabulary: `"cf-free"` fits one Workers Free invocation through the R2
27
+ * binding, `"cf-paid"` one Workers Paid invocation, and `"node"` (the
28
+ * default) is unbounded. S3 storage on Workers needs Paid, with
29
+ * `"cf-paid"`.
30
+ *
31
+ * Errors propagate; log them from the cron handler. On Cloudflare an
32
+ * uncaught error reaches the Workers dashboard.
33
+ *
34
+ * @throws BaerlyError code="InvalidConfig" when `app`, `tenant` or
35
+ * `collection` is not a name `Db.create` / `db.collection` accepts, or
36
+ * `tier` is not one of the listed values, or when an option this
37
+ * release no longer accepts is passed.
38
+ *
39
+ * @example
40
+ * ```ts
41
+ * import { runScheduledMaintenance } from "@gusto/baerly-storage/maintenance";
42
+ *
43
+ * const target = { storage, app: "helpdesk", tenant: "acme", collection: "tickets" };
44
+ *
45
+ * // Node: one unbounded pass.
46
+ * const res = await runScheduledMaintenance(target);
47
+ * console.log("folded", res.folded, "deleted", res.gcDeleted);
48
+ *
49
+ * // Cloudflare: one bounded pass per invocation.
50
+ * await runScheduledMaintenance(target, { tier: "cf-paid" });
51
+ * ```
52
+ */
53
+ export declare const runScheduledMaintenance: (target: MaintenanceTarget, options?: MaintenanceOptions) => Promise<MaintenanceResult>;
54
+ /** The collection one {@link runScheduledMaintenance} call maintains. */
55
+ interface MaintenanceTarget {
56
+ readonly storage: Storage;
57
+ /** The same `app` the `Db` that writes this collection was created with. */
58
+ readonly app: string;
59
+ /** The same `tenant` the `Db` that writes this collection was created with. */
60
+ readonly tenant: string;
61
+ /** The collection name, as passed to `db.collection(name)`. */
62
+ readonly collection: string;
63
+ }
64
+ /** Options for {@link runScheduledMaintenance}. All optional. */
65
+ interface MaintenanceOptions {
66
+ /**
67
+ * The host this pass runs on, in the `BAERLY_MAINTENANCE_PROFILE`
68
+ * vocabulary. `"cf-free"` and `"cf-paid"` cap one pass's work so it fits
69
+ * one Workers invocation on that plan; `"node"` (the default) is
70
+ * unbounded.
71
+ */
72
+ readonly tier?: "cf-free" | "cf-paid" | "node";
73
+ /** Forwarded to every storage call. */
74
+ readonly signal?: AbortSignal;
75
+ }
76
+ /** What one {@link runScheduledMaintenance} call did. */
77
+ interface MaintenanceResult {
78
+ /** Writes folded into the collection's compacted state. `0` when the pass did not compact. */
79
+ readonly folded: number;
80
+ /**
81
+ * Present when contention or a probe budget prevented folding. Omitted
82
+ * for `"cf-free"` tails below its 20-entry fold floor, which stay unfolded
83
+ * until more writes arrive. Nothing is lost; the next pass retries after
84
+ * contention or a probe-budget deferral. `"contention"`: a concurrent
85
+ * write or pass won the race. `"budget"`: the pass ran out of its
86
+ * per-invocation budget while locating the latest writes; it saved its
87
+ * progress, so later passes get further.
88
+ */
89
+ readonly deferred?: {
90
+ readonly reason: "contention" | "budget";
91
+ };
92
+ /** Objects this pass deleted from storage. */
93
+ readonly gcDeleted: number;
94
+ /**
95
+ * Objects marked for deletion that a later pass deletes once their grace
96
+ * period ends.
97
+ */
98
+ readonly pending: number;
99
+ }
100
+ export type { MaintenanceOptions, MaintenanceResult, MaintenanceTarget };
@@ -1,3 +1 @@
1
- import { d as MAINTENANCE_PROFILE_NODE, l as MAINTENANCE_PROFILE_CF_FREE, u as MAINTENANCE_PROFILE_CF_PAID } from "./constants-CfeMWQWk.js";
2
- import { a as estimateTailBytes, c as runScheduledMaintenance, d as runGc, f as compact, i as dispatchInlineAwaited, l as shouldFireMaintenance, n as CLOUDFLARE_PAID_TIER, o as parseMaintenanceEnv, r as crossesGcBoundary, s as runBoundedMaintenance, t as CLOUDFLARE_FREE_TIER, u as rebuildIndex } from "./maintenance-B4Dki6Ig.js";
3
- export { CLOUDFLARE_FREE_TIER, CLOUDFLARE_PAID_TIER, MAINTENANCE_PROFILE_CF_FREE, MAINTENANCE_PROFILE_CF_PAID, MAINTENANCE_PROFILE_NODE, compact, crossesGcBoundary, dispatchInlineAwaited, estimateTailBytes, parseMaintenanceEnv, rebuildIndex, runBoundedMaintenance, runGc, runScheduledMaintenance, shouldFireMaintenance };
1
+ export { a as runScheduledMaintenance } from "./maintenance-DevB6z4e.js";
package/dist/node.d.ts CHANGED
@@ -1,50 +1,58 @@
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-CuA9Mi3K.js";
5
- import { n as S3HttpStorageOptions, t as S3HttpStorage } from "./s3-http-B-z8th6O.js";
6
-
7
- //#region packages/adapter-node/src/credentials/types.d.ts
8
1
  /**
9
- * Temporary or static AWS-shaped credentials. Field shape matches
10
- * `@smithy/types`' `AwsCredentialIdentity` so callers can pass
11
- * `@aws-sdk/credential-providers` output directly (e.g.
12
- * `fromTokenFile()`) without an adapter.
13
- *
14
- * `expiration` is the absolute time at which `accessKeyId` /
15
- * `secretAccessKey` / `sessionToken` stop being valid. When present,
16
- * the signing layer re-resolves credentials some buffer before that
17
- * time. When absent, credentials are treated as static.
18
- */
19
- type Credentials = {
20
- readonly accessKeyId: string;
21
- readonly secretAccessKey: string;
22
- readonly sessionToken?: string;
23
- readonly expiration?: Date;
24
- };
25
- /**
26
- * Async credential resolver. Called by the signing layer on demand —
27
- * once on first sign, then again when cached `expiration` is within
28
- * the refresh buffer. Closure is the natural place to keep retry /
29
- * fallback / fan-out logic; the signing layer only cares about the
30
- * resolved shape.
31
- *
32
- * **Refresh is driven by `Credentials.expiration`.** If your provider
33
- * returns no `expiration`, the signer will call this function
34
- * **exactly once** for the lifetime of the storage handle and reuse
35
- * those credentials forever. That's the right default for genuinely
36
- * static creds (e.g. `process.env`), but it's a footgun if you're
37
- * resolving rotating credentials and forgot to set `expiration` —
38
- * the first 1 h works, then every request 403s with no retry. Set
39
- * `expiration` on every refresh-eligible resolve.
40
- *
41
- * Implementations should be safe to call concurrently — the signing
42
- * layer single-flights refresh, but tests and chained providers may
43
- * call this in parallel.
2
+ * `@baerly/adapter-node` — Node host adapter for `@baerly/server`.
3
+ *
4
+ * Re-exports the runtime-appropriate `Storage` impls and the one-call
5
+ * host helper. Pairs with `@baerly/adapter-cloudflare`, which provides
6
+ * the same surface for Workers + R2 bindings.
7
+ *
8
+ * `baerlyNode` is the public seam. It composes the kernel router with
9
+ * `@hono/node-server`'s `serve()` and SIGTERM/SIGINT handlers into a
10
+ * single handle. The returned `BaerlyNodeHandle` exposes `.fetch` for
11
+ * in-process embedding (Vite middleware, custom servers, tests) and
12
+ * `.listen(port)` for the standard standalone-server case. The
13
+ * `serve()` call is lazy — calling `baerlyNode(opts)` builds the Hono
14
+ * app + resolves the verifier but does not create an `http.Server`
15
+ * until `.listen()` runs.
16
+ *
17
+ * Maintenance (compaction + GC) is in-band: it runs INLINE on the
18
+ * write path the kernel decides needs it — no `setInterval`, no cron,
19
+ * no operator scheduler. Tune via `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` /
20
+ * `BAERLY_MAINTENANCE_DISABLE` (see {@link baerlyNode} for the accepted
21
+ * values); invalid values fail API/database dispatch with
22
+ * `BaerlyError{code:"InvalidConfig"}`. Call `runScheduledMaintenance`
23
+ * from `@gusto/baerly-storage/maintenance` for an explicit out-of-band sweep.
24
+ *
25
+ * @example
26
+ * ```ts
27
+ * import { baerlyNode, s3Storage } from "@gusto/baerly-storage/node";
28
+ * import config from "./baerly.config.ts";
29
+ *
30
+ * const handle = baerlyNode({
31
+ * config,
32
+ * storage: s3Storage({
33
+ * region: "us-east-1",
34
+ * bucket: process.env["BUCKET"]!,
35
+ * credentials: {
36
+ * accessKeyId: process.env["AWS_ACCESS_KEY_ID"]!,
37
+ * secretAccessKey: process.env["AWS_SECRET_ACCESS_KEY"]!,
38
+ * },
39
+ * }),
40
+ * });
41
+ * await handle.listen(Number(process.env["PORT"] ?? 8080));
42
+ * ```
43
+ *
44
+ * Advanced users who need to override the `fetch` / retry knobs can
45
+ * construct `S3HttpStorage` directly — see the `S3HttpStorageOptions`
46
+ * JSDoc. The four factories (`s3Storage`, `r2Storage`, `minioStorage`,
47
+ * `gcsStorage`) wrap the common case for AWS S3, R2, Minio, and GCS.
44
48
  */
45
- type CredentialsProvider = () => Promise<Credentials>;
46
- //#endregion
47
- //#region packages/adapter-node/src/storage-factories.d.ts
49
+ import { n as S3HttpStorageOptions, t as S3HttpStorage } from "./s3-http-DBC_wiCL.js";
50
+ import { a as DEFAULT_GCS_ENDPOINT, i as CredentialsProvider, n as gcsVersioningStatus, o as GcsHttpStorage, r as Credentials, s as GcsHttpStorageOptions, t as GcsVersioningStatus } from "./gcs-admin-Dso1HWQj.js";
51
+ import { t as Storage } from "./types-suVbsEWS.js";
52
+ import { t as DevLandingOptions } from "./dev-landing-BI5UdmOb.js";
53
+ import { n as BaerlyAppConfig } from "./app-config-C6qW7m8S.js";
54
+ import { t as Verifier } from "./verifier-Bmlmndzo.js";
55
+ import { f as ObservabilityConfig } from "./index-RiEYj8t0.js";
48
56
  /**
49
57
  * AWS S3 `Storage` factory. Wraps `S3HttpStorage` with the standard
50
58
  * `aws4fetch` SigV4 signer. The endpoint is derived from the region as
@@ -75,7 +83,7 @@ type CredentialsProvider = () => Promise<Credentials>;
75
83
  * });
76
84
  * ```
77
85
  */
78
- declare function s3Storage(opts: {
86
+ export declare function s3Storage(opts: {
79
87
  region: string;
80
88
  bucket: string;
81
89
  credentials: Credentials | CredentialsProvider;
@@ -105,7 +113,7 @@ declare function s3Storage(opts: {
105
113
  * });
106
114
  * ```
107
115
  */
108
- declare function r2Storage(opts: {
116
+ export declare function r2Storage(opts: {
109
117
  accountId: string;
110
118
  bucket: string;
111
119
  credentials: Credentials | CredentialsProvider;
@@ -131,26 +139,25 @@ declare function r2Storage(opts: {
131
139
  * });
132
140
  * ```
133
141
  */
134
- declare function minioStorage(opts: {
142
+ export declare function minioStorage(opts: {
135
143
  endpoint: string;
136
144
  bucket: string;
137
145
  credentials: Credentials | CredentialsProvider;
138
146
  }): Storage;
139
147
  /**
140
- * Google Cloud Storage `Storage` factory via the S3-compat endpoint
141
- * at `https://storage.googleapis.com`. Authentication uses GCS HMAC
142
- * keys (Console → Settings → Interoperability) — the HMAC access key
143
- * goes into `credentials.accessKeyId` and the HMAC secret goes into
144
- * `credentials.secretAccessKey`. Region is pinned to `"auto"`.
145
- *
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.
148
+ * Google Cloud Storage `Storage` factory over the native GCS XML API
149
+ * at `https://storage.googleapis.com`. Wraps {@link GcsHttpStorage} with
150
+ * a GOOG4-HMAC-SHA256 signer, driving GCS's own generation-precondition
151
+ * conditional writes (`x-goog-if-generation-match: 0` for create-if-absent,
152
+ * `x-goog-if-generation-match: <generation>` for compare-and-swap), which
153
+ * return `412` on a lost write. The object `generation` is carried verbatim
154
+ * as the opaque `Storage` etag. This is the sanctioned GCS path — the
155
+ * S3-interop endpoint treats `If-Match`/`If-None-Match` as read-scoped only
156
+ * and cannot linearize the log, so it is not supported.
157
+ *
158
+ * Authentication uses GCS HMAC keys (Console → Settings → Interoperability)
159
+ * — mint an interop key, put the HMAC access key in `credentials.accessKeyId`
160
+ * and the HMAC secret in `credentials.secretAccessKey`.
154
161
  *
155
162
  * @example
156
163
  * ```ts
@@ -165,12 +172,12 @@ declare function minioStorage(opts: {
165
172
  * });
166
173
  * ```
167
174
  */
168
- declare function gcsStorage(opts: {
175
+ export declare function gcsStorage(opts: {
169
176
  bucket: string;
170
177
  credentials: Credentials | CredentialsProvider;
178
+ /** GCS endpoint. Defaults to `https://storage.googleapis.com`. */
179
+ endpoint?: string;
171
180
  }): Storage;
172
- //#endregion
173
- //#region packages/adapter-node/src/local-fs-storage.d.ts
174
181
  interface LocalFsStorageFactoryOptions {
175
182
  /**
176
183
  * Root data directory. Resolution order: this option →
@@ -185,10 +192,12 @@ interface LocalFsStorageFactoryOptions {
185
192
  * and lost on exit.
186
193
  *
187
194
  * 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.
195
+ * serialized within one process only, so a `current.json` CAS-advance is
196
+ * not atomic against a second process on the same directory (see its class
197
+ * JSDoc). Every call here returns a fresh instance, which is fine — the
198
+ * lock is keyed by resolved root, so instances sharing a directory share
199
+ * it. For horizontally-scaled deploys use `s3Storage` / `r2Storage`, whose
200
+ * cross-process guarantee the no-lease maintenance fold relies on.
192
201
  *
193
202
  * @example
194
203
  * ```ts
@@ -199,9 +208,7 @@ interface LocalFsStorageFactoryOptions {
199
208
  * await baerlyNode({ config, storage: localFsStorage() }).listen(8080);
200
209
  * ```
201
210
  */
202
- declare const localFsStorage: (opts?: LocalFsStorageFactoryOptions) => Storage;
203
- //#endregion
204
- //#region packages/adapter-node/src/resolve-storage.d.ts
211
+ export declare const localFsStorage: (opts?: LocalFsStorageFactoryOptions) => Storage;
205
212
  /** Result of {@link resolveStorageFromEnv}. */
206
213
  interface ResolvedStorage {
207
214
  readonly storage: Storage;
@@ -240,9 +247,7 @@ interface ResolvedStorage {
240
247
  * await baerlyNode({ config, storage }).listen(Number(process.env["PORT"] ?? 8080));
241
248
  * ```
242
249
  */
243
- declare const resolveStorageFromEnv: (env?: Record<string, string | undefined>) => ResolvedStorage;
244
- //#endregion
245
- //#region packages/adapter-node/src/assert-storage-reachable.d.ts
250
+ export declare const resolveStorageFromEnv: (env?: Record<string, string | undefined>) => ResolvedStorage;
246
251
  /** Options for {@link assertStorageReachable}. */
247
252
  interface AssertStorageReachableOptions {
248
253
  /** Key prefix for the throwaway probe sentinels. Default `""`. */
@@ -281,9 +286,7 @@ interface AssertStorageReachableOptions {
281
286
  * console.log(`[baerly] storage=${label} (reachable)`);
282
287
  * ```
283
288
  */
284
- declare const assertStorageReachable: (storage: Storage, opts?: AssertStorageReachableOptions) => Promise<void>;
285
- //#endregion
286
- //#region packages/adapter-node/src/credentials/from-eks.d.ts
289
+ export declare const assertStorageReachable: (storage: Storage, opts?: AssertStorageReachableOptions) => Promise<void>;
287
290
  /**
288
291
  * Resolve AWS credentials on EKS regardless of which identity mechanism the
289
292
  * cluster uses, so callers don't have to know. EKS injects credentials one of
@@ -299,12 +302,10 @@ declare const assertStorageReachable: (storage: Storage, opts?: AssertStorageRea
299
302
  * and re-checked on each refresh. Use this instead of the mechanism-specific
300
303
  * providers unless you have a reason to pin one.
301
304
  */
302
- declare function fromEks(opts?: {
305
+ export declare function fromEks(opts?: {
303
306
  fetch?: typeof fetch;
304
307
  readFile?: (path: string, encoding: "utf8") => Promise<string>;
305
308
  }): CredentialsProvider;
306
- //#endregion
307
- //#region packages/adapter-node/src/credentials/from-eks-pod-identity.d.ts
308
309
  /**
309
310
  * Resolve AWS credentials from the EKS Pod Identity agent (the 2023
310
311
  * successor to IRSA). The agent runs on each EKS node and exchanges
@@ -319,13 +320,16 @@ declare function fromEks(opts?: {
319
320
  *
320
321
  * Both are required. Agent should respond instantly on the node-local
321
322
  * link — 2 s timeout protects against hangs.
323
+ *
324
+ * The URI must name the agent: loopback, or the ECS / EKS link-local
325
+ * addresses (the AWS SDK's container-credentials allow-list). Anything
326
+ * else throws `InvalidConfig` before the token file is read, so a
327
+ * misconfigured or injected env var never sends the token off-node.
322
328
  */
323
- declare function fromEksPodIdentity(opts?: {
329
+ export declare function fromEksPodIdentity(opts?: {
324
330
  fetch?: typeof fetch;
325
331
  readFile?: (path: string, encoding: "utf8") => Promise<string>;
326
332
  }): CredentialsProvider;
327
- //#endregion
328
- //#region packages/adapter-node/src/credentials/from-web-identity.d.ts
329
333
  /**
330
334
  * Resolve AWS credentials via IRSA (IAM Roles for Service Accounts) — the
331
335
  * web-identity-token flow, distinct from the EKS Pod Identity agent that
@@ -344,12 +348,10 @@ declare function fromEksPodIdentity(opts?: {
344
348
  * STS credentials expire (~1 h); the returned provider reports `expiration`, so
345
349
  * the signing layer re-resolves before they lapse.
346
350
  */
347
- declare function fromWebIdentity(opts?: {
351
+ export declare function fromWebIdentity(opts?: {
348
352
  fetch?: typeof fetch;
349
353
  readFile?: (path: string, encoding: "utf8") => Promise<string>;
350
354
  }): CredentialsProvider;
351
- //#endregion
352
- //#region packages/adapter-node/src/baerly-node.d.ts
353
355
  /**
354
356
  * Options for {@link baerlyNode}. Composes the {@link createApp}
355
357
  * surface (same `app` / `storage` / `verifier` / `webRoot` / etc.)
@@ -396,6 +398,14 @@ interface BaerlyNodeOptions {
396
398
  readonly sinceTimeoutMs?: number;
397
399
  readonly sincePollIntervalMs?: number;
398
400
  }
401
+ /** Options for {@link BaerlyNodeHandle.listen}. */
402
+ interface BaerlyNodeListenOptions {
403
+ /**
404
+ * Address to bind, passed to Node's `server.listen(port, host)`.
405
+ * Omit to bind every interface.
406
+ */
407
+ readonly hostname?: string;
408
+ }
399
409
  /**
400
410
  * Handle returned by {@link baerlyNode}. Composes a running
401
411
  * `node:http` server lifecycle.
@@ -404,68 +414,46 @@ interface BaerlyNodeOptions {
404
414
  * directly for in-process embedding (Vite middleware via
405
415
  * `@hono/node-server.getRequestListener`, custom servers, tests).
406
416
  * Calling `fetch` does not start the `node:http` server; the
407
- * server lifecycle is owned by `listen(port)` / `close()`.
417
+ * server lifecycle is owned by `listen()` / `close()`.
408
418
  * Hono's optional `env`/`executionCtx` parameters are intentionally
409
419
  * omitted from the signature — this is a Node-host handle, and
410
420
  * those parameters are Workers-only.
411
- * - `listen(port)` binds the server, installs SIGTERM/SIGINT
412
- * handlers that call `close()` and exit `0`, and resolves once
413
- * the server is actually listening (after Node's `'listening'`
414
- * event fires). Throws on `'error'` from the server.
421
+ * - `listen(port, { hostname })` binds the server, installs
422
+ * SIGTERM/SIGINT handlers that call `close()` and exit `0`, and
423
+ * resolves once the server is actually listening (after Node's
424
+ * `'listening'` event fires). Throws on `'error'` from the server.
425
+ * Without `hostname` it binds every interface (Node's default:
426
+ * `::` dual-stack, or `0.0.0.0` without IPv6), which is what a
427
+ * container wants; pass `"127.0.0.1"` to accept loopback only.
415
428
  * - `close()` closes the server and removes the signal handlers.
416
429
  * Resolves once `Server.close` callback fires. Safe to call
417
- * multiple times.
430
+ * multiple times; every call returns the same promise. A closed
431
+ * handle is final: `listen()` after `close()` rejects with
432
+ * `BaerlyError("InvalidConfig")`; create a new handle instead.
418
433
  */
419
434
  interface BaerlyNodeHandle {
420
435
  readonly fetch: (request: Request) => Response | Promise<Response>;
421
- listen(port: number): Promise<void>;
436
+ /**
437
+ * Bind the server on `port`, every interface unless `hostname` is set.
438
+ * Rejects with `BaerlyError("InvalidConfig")` once `close()` has been
439
+ * called.
440
+ *
441
+ * @example
442
+ * ```ts
443
+ * // Loopback only, e.g. behind a reverse proxy on the same host.
444
+ * await handle.listen(8080, { hostname: "127.0.0.1" });
445
+ * ```
446
+ */
447
+ listen(port: number, options?: BaerlyNodeListenOptions): Promise<void>;
448
+ /**
449
+ * Close the server and remove the signal handlers.
450
+ *
451
+ * If a `listen()` bind is still pending, `close()` waits for it to
452
+ * settle and then closes the resulting listener. That pending
453
+ * `listen()` resolves without installing signal handlers, or rejects
454
+ * with the bind error.
455
+ */
422
456
  close(): Promise<void>;
423
457
  }
424
- /**
425
- * Mount baerly on `node:http` with one call. Mirrors `baerlyWorker`
426
- * from `@baerly/adapter-cloudflare`.
427
- *
428
- * Composes:
429
- * - {@link createApp} → exposed as `handle.fetch` for in-process
430
- * embedding; wrapped in `@hono/node-server.serve({ fetch, createServer })`
431
- * lazily when `listen()` is called.
432
- * - SIGTERM + SIGINT handlers installed on `listen()` that call
433
- * `close()` and `process.exit(0)`. On any error during close,
434
- * `process.exit(1)`.
435
- *
436
- * **Maintenance is in-band, not scheduled.** There is no `setInterval`,
437
- * no cron, and no `maintenance:` option: the kernel maintains itself on
438
- * a bare bucket with zero operator infrastructure. Compaction + GC run
439
- * INLINE on the (rare) write that crosses a maintenance trigger —
440
- * `createFetchHandler` threads a Node-tier `MaintenanceDispatch`
441
- * onto the per-request observability context, which the writer reads at
442
- * its post-commit dispatch point. Reads never tick. Tune via the
443
- * `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` / `BAERLY_MAINTENANCE_DISABLE`
444
- * env vars; for an explicit out-of-band sweep, call
445
- * `runScheduledMaintenance` from `@gusto/baerly-storage` directly.
446
- *
447
- * @example
448
- * ```ts
449
- * import { baerlyNode, s3Storage } from "@gusto/baerly-storage/node";
450
- * import config from "./baerly.config.ts";
451
- *
452
- * const handle = baerlyNode({
453
- * config,
454
- * storage: s3Storage({
455
- * region: "us-east-1",
456
- * bucket: process.env["BUCKET"]!,
457
- * credentials: {
458
- * accessKeyId: process.env["AWS_ACCESS_KEY_ID"]!,
459
- * secretAccessKey: process.env["AWS_SECRET_ACCESS_KEY"]!,
460
- * },
461
- * }),
462
- * // No verifier needed when config.auth is "none" or "shared-secret".
463
- * webRoot: "./dist/client",
464
- * });
465
- * await handle.listen(Number(process.env["PORT"] ?? 8080));
466
- * ```
467
- */
468
- declare function baerlyNode(opts: BaerlyNodeOptions): BaerlyNodeHandle;
469
- //#endregion
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 };
471
- //# sourceMappingURL=node.d.ts.map
458
+ export declare function baerlyNode(opts: BaerlyNodeOptions): BaerlyNodeHandle;
459
+ export { type AssertStorageReachableOptions, type BaerlyNodeHandle, type BaerlyNodeListenOptions, type BaerlyNodeOptions, type Credentials, type CredentialsProvider, DEFAULT_GCS_ENDPOINT, GcsHttpStorage, type GcsHttpStorageOptions, type GcsVersioningStatus, type LocalFsStorageFactoryOptions, type ResolvedStorage, S3HttpStorage, type S3HttpStorageOptions, gcsVersioningStatus };
package/dist/node.js CHANGED
@@ -1,3 +1,4 @@
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-BL_JoPTn.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
+ import { a as fromEksPodIdentity, c as localFsStorage, d as r2Storage, f as s3Storage, i as fromWebIdentity, l as gcsStorage, o as assertStorageReachable, p as gcsVersioningStatus, r as fromEks, s as resolveStorageFromEnv, t as baerlyNode, u as minioStorage } from "./src-Actga-bO.js";
2
+ import { r as S3HttpStorage } from "./sigv4-sign-5IUflUD_.js";
3
+ import { i as GcsHttpStorage, r as DEFAULT_GCS_ENDPOINT } from "./goog4-signer-CeLIABoE.js";
4
+ export { DEFAULT_GCS_ENDPOINT, GcsHttpStorage, S3HttpStorage, assertStorageReachable, baerlyNode, fromEks, fromEksPodIdentity, fromWebIdentity, gcsStorage, gcsVersioningStatus, localFsStorage, minioStorage, r2Storage, resolveStorageFromEnv, s3Storage };