@gusto/create-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/dist/index.js +54 -28
- package/dist/index.js.map +1 -1
- package/dist/templates/addons/docker/Dockerfile +8 -2
- package/dist/templates/minimal-cloudflare/AGENTS.md +140 -101
- package/dist/templates/minimal-cloudflare/README.md +43 -33
- package/dist/templates/minimal-cloudflare/package.json +7 -7
- package/dist/templates/minimal-cloudflare/wrangler.jsonc +1 -1
- package/dist/templates/minimal-node/.baerly/scaffold.json +1 -1
- package/dist/templates/minimal-node/.env.example +12 -5
- package/dist/templates/minimal-node/AGENTS.md +135 -107
- package/dist/templates/minimal-node/README.md +77 -44
- package/dist/templates/minimal-node/package.json +5 -5
- package/dist/templates/minimal-node/src/server/index.ts +22 -30
- package/dist/templates/minimal-node/src/server/resolve-storage.ts +18 -0
- package/dist/templates/minimal-node/vite.config.ts +0 -2
- package/dist/templates/react-cloudflare/AGENTS.md +77 -52
- package/dist/templates/react-cloudflare/README.md +25 -16
- package/dist/templates/react-cloudflare/index.html +1 -1
- package/dist/templates/react-cloudflare/package.json +12 -12
- package/dist/templates/react-cloudflare/wrangler.jsonc +1 -1
- package/dist/templates/react-node/.env.example +12 -5
- package/dist/templates/react-node/AGENTS.md +117 -81
- package/dist/templates/react-node/README.md +67 -37
- package/dist/templates/react-node/package.json +10 -10
- package/dist/templates/react-node/src/server/index.ts +18 -29
- package/dist/templates/react-node/src/server/resolve-storage.ts +18 -0
- package/dist/templates/react-node/vite.config.ts +0 -2
- package/package.json +16 -11
|
@@ -15,14 +15,14 @@
|
|
|
15
15
|
"@gusto/baerly-storage": "workspace:*"
|
|
16
16
|
},
|
|
17
17
|
"devDependencies": {
|
|
18
|
-
"@cloudflare/vite-plugin": "^1.
|
|
19
|
-
"@cloudflare/workers-types": "^4",
|
|
20
|
-
"@types/node": "^
|
|
21
|
-
"happy-dom": "^20.
|
|
18
|
+
"@cloudflare/vite-plugin": "^1.42.4",
|
|
19
|
+
"@cloudflare/workers-types": "^4.20260630.1",
|
|
20
|
+
"@types/node": "^26.0.1",
|
|
21
|
+
"happy-dom": "^20.10.6",
|
|
22
22
|
"typescript": "^6.0.3",
|
|
23
|
-
"vite": "^8.
|
|
24
|
-
"vitest": "^4.1.
|
|
25
|
-
"wrangler": "^4.
|
|
23
|
+
"vite": "^8.1.2",
|
|
24
|
+
"vitest": "^4.1.9",
|
|
25
|
+
"wrangler": "^4.106.0"
|
|
26
26
|
},
|
|
27
27
|
"packageManager": "pnpm@11.1.2"
|
|
28
28
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
// Cloudflare Worker manifest. See `AGENTS.md` for what each field
|
|
3
|
-
// drives (R2 binding, assets, vars
|
|
3
|
+
// drives (R2 binding, assets, vars) and how
|
|
4
4
|
// the verifier consumes the vars.
|
|
5
5
|
"$schema": "node_modules/wrangler/config-schema.json",
|
|
6
6
|
"name": "minimal-cloudflare",
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
{ "from": "minimal-demo", "fromKey": "tenant" }
|
|
5
5
|
],
|
|
6
6
|
"excludePaths": [".baerly/scaffold.json"],
|
|
7
|
-
"excludeNames": ["node_modules", "dist", ".DS_Store", "*.tsbuildinfo"],
|
|
7
|
+
"excludeNames": ["node_modules", "dist", ".baerly-data", ".DS_Store", "*.tsbuildinfo"],
|
|
8
8
|
"dropDevDeps": [],
|
|
9
9
|
"copies": [
|
|
10
10
|
{ "from": "AGENTS.md", "to": "CLAUDE.md" },
|
|
@@ -1,13 +1,20 @@
|
|
|
1
|
-
# Storage
|
|
2
|
-
#
|
|
3
|
-
#
|
|
1
|
+
# Storage selection. Defaults to local filesystem storage
|
|
2
|
+
# (./.baerly-data, zero credentials) for local dev. A deployment
|
|
3
|
+
# (NODE_ENV=production or a known PaaS) requires a bucket below — the
|
|
4
|
+
# server fails loud rather than running on local-fs, which is local-dev
|
|
5
|
+
# only. Self-hosting without a cloud bucket? Run MinIO on the box, or use
|
|
6
|
+
# SQLite + Litestream.
|
|
7
|
+
# MinIO is for local conformance. Other S3-compatible endpoints require
|
|
8
|
+
# `baerly doctor --bucket` plus owner validation; GCS S3-interop is not
|
|
9
|
+
# supported for database use today.
|
|
10
|
+
# AWS S3: set BUCKET + AWS creds (AWS_REGION optional).
|
|
4
11
|
AWS_ACCESS_KEY_ID=
|
|
5
12
|
AWS_SECRET_ACCESS_KEY=
|
|
6
13
|
AWS_REGION=us-east-1
|
|
7
14
|
BUCKET=
|
|
8
15
|
# Set to your Cloudflare R2 account ID (left half of the
|
|
9
|
-
# https://<account>.r2.cloudflarestorage.com endpoint) to
|
|
10
|
-
#
|
|
16
|
+
# https://<account>.r2.cloudflarestorage.com endpoint) to use R2
|
|
17
|
+
# instead of AWS S3 (still set BUCKET + AWS_* creds). Leave unset for S3.
|
|
11
18
|
# R2_ACCOUNT_ID=
|
|
12
19
|
|
|
13
20
|
# Server
|
|
@@ -1,16 +1,17 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: AGENTS.md — agent guidance for minimal-node
|
|
3
3
|
audience: agent
|
|
4
|
-
summary: How to develop and deploy minimal-node, a baerly app.
|
|
5
|
-
tags: [agent-entry, baerly]
|
|
4
|
+
summary: How to develop and deploy minimal-node, a baerly-storage app.
|
|
5
|
+
tags: [agent-entry, baerly-storage]
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# AGENTS.md
|
|
9
9
|
|
|
10
|
+
<!-- stop:start -->
|
|
10
11
|
## STOP — read this before writing any storage code
|
|
11
12
|
|
|
12
13
|
Your training data is dense with Postgres + Prisma/Drizzle, Mongo,
|
|
13
|
-
and Firebase patterns. **None of them apply here.** This is a baerly
|
|
14
|
+
and Firebase patterns. **None of them apply here.** This is a baerly-storage
|
|
14
15
|
app — a small, LLM-legible document database with a narrow API on top
|
|
15
16
|
of S3-compatible storage. Before writing or modifying storage code,
|
|
16
17
|
read:
|
|
@@ -18,7 +19,7 @@ read:
|
|
|
18
19
|
- **`node_modules/@gusto/baerly-storage/dist/API.md`** — hand-authored
|
|
19
20
|
public-API quickref. Read first. Lists every method, every error
|
|
20
21
|
code, every example. If a pattern you want to use isn't here, it
|
|
21
|
-
doesn't exist in baerly.
|
|
22
|
+
doesn't exist in baerly-storage.
|
|
22
23
|
- **`node_modules/@gusto/baerly-storage/dist/*.d.ts`** — authoritative type
|
|
23
24
|
signatures. `Db`, `Collection<T>`, `Query<T>`, and `Predicate<T>` are
|
|
24
25
|
the whole API surface.
|
|
@@ -37,41 +38,42 @@ Common anti-patterns that compile but are wrong:
|
|
|
37
38
|
picks the index automatically from `IndexDefinition`s in
|
|
38
39
|
`baerly.config.ts`. See **Indexes** below.
|
|
39
40
|
|
|
41
|
+
<!-- stop:end -->
|
|
40
42
|
## What this is
|
|
41
43
|
|
|
42
|
-
`minimal-node` is a baerly app scaffolded with
|
|
43
|
-
Node target
|
|
44
|
-
Fly without Docker, Heroku, a VM, a
|
|
45
|
-
package: the Node-side server lives in
|
|
46
|
-
optional client lives in `src/web/`.
|
|
47
|
-
`baerly.config.ts`.
|
|
44
|
+
`minimal-node` is a baerly-storage app scaffolded with
|
|
45
|
+
`create-baerly-storage` for the Node target: any host that runs
|
|
46
|
+
`node server.js` (Railway, Render, Fly without Docker, Heroku, a VM, a
|
|
47
|
+
container scheduler). One flat package: the Node-side server lives in
|
|
48
|
+
`src/server/index.ts`; the optional client lives in `src/web/`.
|
|
49
|
+
Configuration lives in `baerly.config.ts`.
|
|
48
50
|
|
|
49
51
|
Single package, single `vite` process: `baerlyDev()` from
|
|
50
52
|
`@gusto/baerly-storage/dev/vite` mounts the Node HTTP listener as Vite
|
|
51
53
|
middleware on `:5173` alongside the SPA dev server, so `pnpm dev`
|
|
52
54
|
brings up SPA + HMR + `/v1/*` in one command — same origin in dev,
|
|
53
|
-
same `dist/client/`-served origin in production via `pnpm start
|
|
54
|
-
|
|
55
|
-
option
|
|
55
|
+
same `dist/client/`-served origin in production via `pnpm start`. The
|
|
56
|
+
production entrypoint serves the Vite-built SPA from `dist/client/`
|
|
57
|
+
via the `baerlyNode({ webRoot: "dist/client" })` option, with `/v1/*`
|
|
58
|
+
handled by the kernel on the same origin.
|
|
56
59
|
|
|
57
60
|
If this scaffold was created with `--with=docker`, you'll also have a
|
|
58
61
|
multi-stage distroless `Dockerfile`, a `.dockerignore`, and a
|
|
59
62
|
`healthcheck.js` at the project root — wired to the same
|
|
60
63
|
`pnpm install && pnpm build && pnpm start` flow.
|
|
61
64
|
|
|
62
|
-
Public API docs:
|
|
63
|
-
|
|
64
|
-
|
|
65
|
+
Public API docs: the JSDoc on `baerly-storage`'s `Db` and `Collection`
|
|
66
|
+
is the canonical reference; read it via your editor's TS LS, the
|
|
67
|
+
published types, or `node_modules/@gusto/baerly-storage/dist/API.md`.
|
|
65
68
|
|
|
66
69
|
## Toolchain
|
|
67
70
|
|
|
68
71
|
- **Package manager:** pnpm. The emitted repo pins
|
|
69
72
|
`packageManager: pnpm@11.1.2`.
|
|
70
73
|
- **Test runner:** vitest.
|
|
71
|
-
- **Type checker:** TypeScript
|
|
72
|
-
itself uses TypeScript 7 via
|
|
73
|
-
|
|
74
|
-
apps work with the wider ecosystem.)
|
|
74
|
+
- **Type checker:** TypeScript 6.x, as pinned in `package.json`.
|
|
75
|
+
(The baerly-storage monorepo itself uses TypeScript 7 via
|
|
76
|
+
`@typescript/native-preview`.)
|
|
75
77
|
- **`erasableSyntaxOnly`** is enabled in every `tsconfig*.json` so the
|
|
76
78
|
code stays compatible with type-stripping runtimes (Node's
|
|
77
79
|
`--experimental-strip-types`, esbuild's strip path). The flag bans
|
|
@@ -85,15 +87,15 @@ read it via your editor's TS LS or via the published types).
|
|
|
85
87
|
|
|
86
88
|
## Verification
|
|
87
89
|
|
|
88
|
-
| Command
|
|
89
|
-
|
|
|
90
|
-
| `pnpm install`
|
|
91
|
-
| `pnpm verify`
|
|
92
|
-
| `pnpm typecheck`
|
|
93
|
-
| `pnpm test`
|
|
94
|
-
| `pnpm dev`
|
|
95
|
-
| `pnpm build`
|
|
96
|
-
| `pnpm start`
|
|
90
|
+
| Command | What it does | Runtime |
|
|
91
|
+
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
|
|
92
|
+
| `pnpm install` | One-time bootstrap — the scaffold ships without `node_modules/`, so `pnpm verify` / `pnpm dev` fail with `Cannot find package '…'` until this runs once | seconds to a minute |
|
|
93
|
+
| `pnpm verify` | `pnpm run typecheck && pnpm run test` — the green-light gate; what an agent should run as the smoke check before claiming the change works | seconds |
|
|
94
|
+
| `pnpm typecheck` | TS typecheck across the `app` + `server` project references | seconds |
|
|
95
|
+
| `pnpm test` | `vitest run` — standalone `vitest.config.ts` (Node env). The template ships `src/notes.test.ts` by default. | seconds |
|
|
96
|
+
| `pnpm dev` | Run `vite` — `baerlyDev()` mounts the Node HTTP listener as Connect middleware next to the SPA dev server; same origin on :5173 | seconds to start |
|
|
97
|
+
| `pnpm build` | `tsc -b && vite build` — emits the SPA into `dist/client/` | seconds |
|
|
98
|
+
| `pnpm start` | `node --experimental-strip-types src/server/index.ts` — production entry; serves the built SPA from `dist/client/` plus `/v1/*` on the same origin via `webRoot` | seconds to start |
|
|
97
99
|
|
|
98
100
|
**`pnpm verify` exercises typecheck + tests only.** The dev-auth
|
|
99
101
|
middleware, the SPA bundle, and any custom `/api/*` route are NOT
|
|
@@ -105,31 +107,32 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
105
107
|
|
|
106
108
|
## Where the code is
|
|
107
109
|
|
|
108
|
-
| Path
|
|
109
|
-
|
|
|
110
|
-
| `src/server/index.ts`
|
|
111
|
-
| `src/web/`, `index.html`
|
|
112
|
-
| `vite.config.ts`
|
|
113
|
-
| `tsconfig.{app,server}.json` | TS project references for the client and server projects
|
|
114
|
-
| `baerly.config.ts`
|
|
115
|
-
| `types.ts`
|
|
110
|
+
| Path | What it is |
|
|
111
|
+
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
112
|
+
| `src/server/index.ts` | Server entry — defaults to zero-config `localFsStorage()` (persists to `./.baerly-data`); promotes to `s3Storage` (AWS) when `BUCKET` is set or `r2Storage` (Cloudflare R2) when `R2_ACCOUNT_ID` is set; composes a verifier and calls `baerlyNode({ ... }).listen(PORT)` |
|
|
113
|
+
| `src/web/`, `index.html` | Optional SPA shell built by Vite into `dist/client/`. `src/web/main.ts` is a ~17-line hello-world: reads `client.collection("notes").all()` to render a `${n} note(s)` count and an `[Add note]` button that inserts a timestamped row and re-fetches. Demonstrates both read and write paths on first load — extend, replace, or remove the whole tree if not needed. The `config`-bound `client.collection("notes")` is the typed surface (the generic on `.collection()` is the collection **name**, not the row type). |
|
|
114
|
+
| `vite.config.ts` | Vite client build — `outDir: dist/client`; `baerlyDev()` mounts the Node listener as middleware so SPA + `/v1/*` share `:5173` in dev |
|
|
115
|
+
| `tsconfig.{app,server}.json` | TS project references for the client and server projects |
|
|
116
|
+
| `baerly.config.ts` | App config — `app`, `tenant`, `target`, `domain`, `collections` (schemas live here). |
|
|
117
|
+
| `types.ts` | Shared types between the Node server (`src/server/`) and the SPA (`src/web/`). Both `tsconfig.app.json` and `tsconfig.server.json` include this file; put any row type or interface that crosses the boundary here. |
|
|
116
118
|
|
|
117
119
|
> **`baerly.config.ts` and `types.ts` are dual-included** by both
|
|
118
120
|
> `tsconfig.app.json` and `tsconfig.server.json`. Both can only
|
|
119
121
|
> import from `baerly-storage`, `zod`, and other dual-included root
|
|
120
122
|
> files. Paths under `src/server/` are server-only; importing them
|
|
121
|
-
> here triggers `TS6307
|
|
122
|
-
>
|
|
123
|
-
> in `types.ts`; re-export from a server-only file if
|
|
124
|
-
> wants a local name.
|
|
123
|
+
> here triggers a `TS6307` "not listed within the file list of
|
|
124
|
+
> project … tsconfig.app.json" error. Cross-boundary interfaces
|
|
125
|
+
> belong in `types.ts`; re-export from a server-only file if
|
|
126
|
+
> downstream code wants a local name.
|
|
125
127
|
|
|
126
128
|
## When editing X, read Y
|
|
127
129
|
|
|
128
130
|
- **Writing tests** — the kernel exports `MemoryStorage`, an
|
|
129
131
|
in-memory `Storage` impl that's the canonical backend for unit
|
|
130
|
-
tests. Don't roll your own
|
|
131
|
-
config })`
|
|
132
|
-
`new MemoryStorage()` swaps S3 for an
|
|
132
|
+
tests. Don't roll your own: the same
|
|
133
|
+
`Db.create({ storage, app, tenant, config })` boilerplate prod uses
|
|
134
|
+
also accepts a `new MemoryStorage()` that swaps S3 for an
|
|
135
|
+
in-process map.
|
|
133
136
|
|
|
134
137
|
```ts
|
|
135
138
|
// src/notes.test.ts
|
|
@@ -156,9 +159,10 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
156
159
|
instance into multiple `Db.create` calls so they share the
|
|
157
160
|
underlying bucket.
|
|
158
161
|
|
|
159
|
-
- **Predicates** — `db.collection
|
|
160
|
-
|
|
161
|
-
|
|
162
|
+
- **Predicates** — `db.collection(name).where({...}).all()` (the row
|
|
163
|
+
type is inferred from the schema declared for `name` in
|
|
164
|
+
`baerly.config.ts`; the generic on `.collection()` is the collection
|
|
165
|
+
**name**, not the row type). Two shapes:
|
|
162
166
|
- **Object literal** — equality only (top-level, dotted-path, or
|
|
163
167
|
nested literal sub-predicate). Multi-field is implicit AND.
|
|
164
168
|
- **Callback DSL** — `q => q.eq(...).gt(...).gte(...).lt(...).lte(...).in(...)`
|
|
@@ -172,24 +176,25 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
172
176
|
await db.collection("tickets").where({ status: "open" }).all();
|
|
173
177
|
|
|
174
178
|
// Dotted-path on a nested field
|
|
175
|
-
await db.collection("tickets")
|
|
176
|
-
.where({ "assignee.team": "platform" })
|
|
177
|
-
.all();
|
|
179
|
+
await db.collection("tickets").where({ "assignee.team": "platform" }).all();
|
|
178
180
|
|
|
179
181
|
// Operator on a single field — set membership (callback form)
|
|
180
|
-
await db
|
|
181
|
-
.
|
|
182
|
+
await db
|
|
183
|
+
.collection("tickets")
|
|
184
|
+
.where((q) => q.in("status", ["open", "pending"]))
|
|
182
185
|
.all();
|
|
183
186
|
|
|
184
187
|
// Range — also callback form
|
|
185
|
-
await db
|
|
186
|
-
.
|
|
188
|
+
await db
|
|
189
|
+
.collection("tickets")
|
|
190
|
+
.where((q) => q.gte("priority", 5).lt("priority", 10))
|
|
187
191
|
.all();
|
|
188
192
|
|
|
189
193
|
// AND-merge across two .where() calls (mix shapes freely)
|
|
190
|
-
await db
|
|
194
|
+
await db
|
|
195
|
+
.collection("tickets")
|
|
191
196
|
.where({ status: "open" })
|
|
192
|
-
.where(q => q.gte("priority", 5))
|
|
197
|
+
.where((q) => q.gte("priority", 5))
|
|
193
198
|
.all();
|
|
194
199
|
```
|
|
195
200
|
|
|
@@ -216,8 +221,9 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
216
221
|
});
|
|
217
222
|
```
|
|
218
223
|
|
|
219
|
-
With that declared,
|
|
220
|
-
}).all()` walks
|
|
224
|
+
With that declared, a query like
|
|
225
|
+
`db.collection("tickets").where({ status: "open" }).all()` walks
|
|
226
|
+
`by_status` automatically. Composite indexes
|
|
221
227
|
(`on: ["status", "priority"]`) match any leftmost prefix.
|
|
222
228
|
Mismatches (predicate doesn't cover any index) fall back to a full
|
|
223
229
|
table scan with a metric bump; correctness is preserved because the
|
|
@@ -248,7 +254,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
248
254
|
|
|
249
255
|
On a validation failure the server throws
|
|
250
256
|
`BaerlyError{ code: "SchemaError", issues: [{ path, message }] }`;
|
|
251
|
-
HTTP clients see a
|
|
257
|
+
HTTP clients see a 400 with the same envelope. Validation runs
|
|
252
258
|
on the post-image so `update` and `replace` see the full doc, not
|
|
253
259
|
just the patch.
|
|
254
260
|
|
|
@@ -256,12 +262,12 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
256
262
|
(`db.collection(name).insert(...)`) is the canonical path; reach for `curl`
|
|
257
263
|
only when debugging the wire. Mutation bodies are wrapped:
|
|
258
264
|
|
|
259
|
-
| Route
|
|
260
|
-
|
|
|
261
|
-
| `POST /v1/c/:collection`
|
|
262
|
-
| `PATCH /v1/c/:collection/:id`
|
|
263
|
-
| `PUT /v1/c/:collection/:id`
|
|
264
|
-
| `DELETE /v1/c/:collection/:id`
|
|
265
|
+
| Route | Body | Response |
|
|
266
|
+
| ------------------------------ | ----------------- | ---------------- |
|
|
267
|
+
| `POST /v1/c/:collection` | `{"doc":{...}}` | `201 {_id}` |
|
|
268
|
+
| `PATCH /v1/c/:collection/:id` | `{"patch":{...}}` | `200 {modified}` |
|
|
269
|
+
| `PUT /v1/c/:collection/:id` | `{"doc":{...}}` | `200 {modified}` |
|
|
270
|
+
| `DELETE /v1/c/:collection/:id` | — | `204` |
|
|
265
271
|
|
|
266
272
|
Reads (`GET /v1/c/:collection[/:id]`, `GET /v1/count?collection=…`,
|
|
267
273
|
`GET /v1/since?collection=…&cursor=…`) take no body and return
|
|
@@ -269,15 +275,17 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
269
275
|
(without the `doc` wrapper) returns
|
|
270
276
|
`400 SchemaError "Request body must be { doc: object }"` — the
|
|
271
277
|
wording is locked by `assertJsonBodyField` in the kernel. Canonical
|
|
272
|
-
reference: the
|
|
278
|
+
reference: the JSDoc on `createRouter` in
|
|
273
279
|
`baerly-storage`.
|
|
274
280
|
|
|
275
281
|
- **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`:
|
|
276
282
|
every request resolves to `tenant: "minimal-demo"` and `Authorization`
|
|
277
283
|
is ignored. The adapter reads `config.auth` to pick its verifier;
|
|
278
|
-
a `verifier:` on `baerlyNode({ ... })` overrides it.
|
|
279
|
-
doctor --target=node`
|
|
280
|
-
|
|
284
|
+
a `verifier:` on `baerlyNode({ ... })` overrides it. There is no
|
|
285
|
+
`baerly doctor --target=node` backend today; verify bucket CAS with
|
|
286
|
+
`baerly doctor --bucket=<s3-uri>` and probe `/v1/healthz` after
|
|
287
|
+
deploy. See "Going to production" below for the two production-fit
|
|
288
|
+
recipes.
|
|
281
289
|
|
|
282
290
|
### Going to production
|
|
283
291
|
|
|
@@ -286,6 +294,7 @@ zero env vars. Two patterns flip to a production-fit posture; pick
|
|
|
286
294
|
the one matching your gate.
|
|
287
295
|
|
|
288
296
|
<!-- pattern-b:start -->
|
|
297
|
+
|
|
289
298
|
**Pattern B — `auth: "shared-secret"`** (single-tenant
|
|
290
299
|
server-to-server). No factory code changes; `baerly.config.ts` flips:
|
|
291
300
|
|
|
@@ -296,12 +305,13 @@ auth: "shared-secret", // ← flip from "none"
|
|
|
296
305
|
|
|
297
306
|
Dev: put `SHARED_SECRET=dev-shared-secret` in `.env`. Prod: set
|
|
298
307
|
`SHARED_SECRET` in the process environment (your PaaS / secret
|
|
299
|
-
manager).
|
|
300
|
-
|
|
301
|
-
`
|
|
308
|
+
manager). The Node process fails closed if `auth: "shared-secret"`
|
|
309
|
+
is set without `SHARED_SECRET` reachable from `process.env`; verify
|
|
310
|
+
the live bucket separately with `baerly doctor --bucket=<s3-uri>`.
|
|
302
311
|
|
|
303
312
|
<!-- pattern-b:end -->
|
|
304
313
|
<!-- pattern-c:start -->
|
|
314
|
+
|
|
305
315
|
**Pattern C — JWKS-backed JWT** (multi-tenant; OIDC IdP). The factory
|
|
306
316
|
`verifier:` overrides `config.auth`, so dev keeps `"none"` and prod
|
|
307
317
|
gets `bearerJwt`:
|
|
@@ -332,6 +342,7 @@ await baerlyNode({
|
|
|
332
342
|
jwks: process.env["JWKS_URL"],
|
|
333
343
|
issuer: process.env["JWT_ISSUER"]!,
|
|
334
344
|
audience: process.env["JWT_AUDIENCE"]!,
|
|
345
|
+
tenantPrefix: config.tenant, // or tenantClaim: "tenant"
|
|
335
346
|
}),
|
|
336
347
|
}),
|
|
337
348
|
}).listen(Number(process.env["PORT"] ?? 8080));
|
|
@@ -339,28 +350,37 @@ await baerlyNode({
|
|
|
339
350
|
|
|
340
351
|
Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
|
|
341
352
|
`config.auth: "none"` runs. Prod sets `JWKS_URL` + `JWT_ISSUER` +
|
|
342
|
-
`JWT_AUDIENCE` and `bearerJwt` engages.
|
|
353
|
+
`JWT_AUDIENCE` and `bearerJwt` engages. Use `tenantClaim` when your
|
|
354
|
+
IdP issues one tenant per token; use `tenantPrefix` for single-tenant
|
|
355
|
+
apps or tenancy enforced outside baerly-storage.
|
|
343
356
|
|
|
344
357
|
<!-- pattern-c:end -->
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
`R2_ACCOUNT_ID`
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
358
|
+
|
|
359
|
+
- **Storage backend** — `src/server/index.ts` resolves storage by env:
|
|
360
|
+
`R2_ACCOUNT_ID` → Cloudflare R2, else `BUCKET` → AWS S3, else
|
|
361
|
+
zero-config `localFsStorage()` (persists to `./.baerly-data`, no
|
|
362
|
+
credentials, local dev only). **In a detected deployment
|
|
363
|
+
(`NODE_ENV=production` or a known PaaS) the server fails loud and
|
|
364
|
+
requires a bucket** — local-fs is single-process with no cross-process
|
|
365
|
+
CAS or crash durability, so it is never a production store (there is no
|
|
366
|
+
opt-in). AWS S3 and Cloudflare R2 are the production-supported stores;
|
|
367
|
+
self-hosting without a cloud bucket, run **MinIO** on the box (also the
|
|
368
|
+
local/dev conformance target) or graduate to SQLite + Litestream. Other S3-compatible endpoints need a
|
|
369
|
+
green `baerly doctor --bucket` plus owner validation; GCS S3-interop
|
|
370
|
+
is not supported for database use today. JSDoc `@example` blocks for
|
|
371
|
+
the factories are visible in your editor's TS hover.
|
|
372
|
+
|
|
373
|
+
- **Switching from static creds to EKS** — in
|
|
356
374
|
`src/server/index.ts`, swap `credentials: { accessKeyId,
|
|
357
|
-
secretAccessKey }` for `credentials:
|
|
358
|
-
|
|
359
|
-
`import { s3Storage,
|
|
360
|
-
|
|
361
|
-
`
|
|
362
|
-
|
|
363
|
-
`
|
|
375
|
+
secretAccessKey }` for `credentials: fromEks()` and add `fromEks`
|
|
376
|
+
to your import:
|
|
377
|
+
`import { s3Storage, fromEks } from "@gusto/baerly-storage/node"`.
|
|
378
|
+
`fromEks()` auto-detects the cluster's mechanism — EKS Pod Identity
|
|
379
|
+
(`AWS_CONTAINER_CREDENTIALS_FULL_URI` +
|
|
380
|
+
`AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE`) or IRSA (`AWS_ROLE_ARN` +
|
|
381
|
+
`AWS_WEB_IDENTITY_TOKEN_FILE`), both EKS-injected; to pin one, use
|
|
382
|
+
`fromEksPodIdentity()` or `fromWebIdentity()`. For ECS / EC2 / other
|
|
383
|
+
AWS contexts, see `packages/adapter-node/AGENTS.md` — pass any
|
|
364
384
|
`() => Promise<Credentials>` or an `@aws-sdk/credential-providers`
|
|
365
385
|
factory through the seam.
|
|
366
386
|
|
|
@@ -396,12 +416,14 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
|
|
|
396
416
|
into the predicate so the index planner can prune
|
|
397
417
|
(`db.collection("notes").where({ ... }).all()`), or maintain a
|
|
398
418
|
side-projection (Postgres/SQLite/search index) populated
|
|
399
|
-
incrementally from the `/v1/since
|
|
419
|
+
incrementally from the `/v1/since?collection=<name>&cursor=<opaque>`
|
|
420
|
+
log feed or from a write hook —
|
|
400
421
|
never re-scan per request.
|
|
401
422
|
|
|
402
423
|
## Maintenance
|
|
403
424
|
|
|
404
425
|
<!-- pattern-d:start -->
|
|
426
|
+
|
|
405
427
|
Maintenance is automatic and write-triggered. No cron, no sidecar, no scheduler, no
|
|
406
428
|
timer, no lock, no app-config knob — identical on every host. Every write runs a
|
|
407
429
|
bounded GC slice inline plus a go/no-go compaction fold bounded by a fold-size ceiling
|
|
@@ -415,36 +437,42 @@ maintenance, so the published idle-reader cost bound holds.
|
|
|
415
437
|
A bucket maintains itself as long as it takes writes. A bucket served read-only does
|
|
416
438
|
not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
|
|
417
439
|
graduate once a collection is large. See docs/about/graduation.md for the per-tier
|
|
418
|
-
envelope and the BAERLY_MAINTENANCE_
|
|
440
|
+
envelope and the `BAERLY_MAINTENANCE_*` operator env vars (you almost never need them).
|
|
419
441
|
|
|
420
442
|
Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
|
|
421
443
|
your own schedule. Not required for steady-state operation.
|
|
444
|
+
|
|
422
445
|
<!-- pattern-d:end -->
|
|
423
446
|
|
|
424
447
|
## When to graduate
|
|
425
448
|
|
|
426
|
-
baerly is designed for the small-to-medium operating point.
|
|
427
|
-
model puts the soft ceiling at:
|
|
449
|
+
baerly-storage is designed for the small-to-medium operating point.
|
|
450
|
+
The cost model puts the soft ceiling at:
|
|
428
451
|
|
|
429
|
-
- **~30 writes / minute / collection**
|
|
430
|
-
-
|
|
431
|
-
- **~100 collections / tenant**
|
|
452
|
+
- **~30 writes / minute / collection** (throughput ceiling — model/estimate)
|
|
453
|
+
- **>10 GB / tenant stored** (R2 free-tier storage line — a cost signal, not a protocol ceiling)
|
|
454
|
+
- **~100 collections / tenant** (soft fan-out guideline — bench-grounded linear cost)
|
|
432
455
|
|
|
433
|
-
|
|
434
|
-
op pricing start to dominate;
|
|
456
|
+
At M-size (~30 writes/min) the projected cost is ~$26/mo on S3 (~$18/mo on R2). Past
|
|
457
|
+
those, per-class op pricing and fan-out scan cost start to dominate;
|
|
458
|
+
you've outgrown the workload envelope — move to a database service (D1 / Postgres) suited to higher scale.
|
|
435
459
|
Pick your graduation target:
|
|
460
|
+
|
|
436
461
|
- **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
|
|
437
462
|
- **Off-Workers or portability matters:** managed Postgres.
|
|
438
463
|
- **Single-instance Node:** SQLite via Litestream.
|
|
439
464
|
|
|
440
465
|
Either way, the export below is mechanical because log entries are
|
|
441
|
-
|
|
442
|
-
not a churn event.
|
|
443
|
-
|
|
444
|
-
**Estimate your current rate:**
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
466
|
+
Debezium-style CDC change events — graduation is a baerly-storage
|
|
467
|
+
win, not a churn event.
|
|
468
|
+
|
|
469
|
+
**Estimate your current rate:** for Node/self-hosted buckets,
|
|
470
|
+
`baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
|
|
471
|
+
--tenant=<tenant>` lists recent log entries per collection and computes
|
|
472
|
+
writes/min. On Cloudflare, use canonical logs for trend history and
|
|
473
|
+
`baerly cost --bucket=<bucket-uri> --collection=<collection>` for the
|
|
474
|
+
current operation-cost projection until the usage scanner is wired to
|
|
475
|
+
R2 bindings.
|
|
448
476
|
|
|
449
477
|
**Export when ready:** `baerly export --target=sqlite|postgres|d1
|
|
450
478
|
--bucket=<...> --app=<...> --tenant=<...> --collection=<...>` writes a
|