@gusto/create-baerly-storage 0.1.2 → 0.3.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.map +1 -1
- package/dist/templates/addons/docker/Dockerfile +8 -2
- package/dist/templates/minimal-cloudflare/AGENTS.md +115 -79
- package/dist/templates/minimal-cloudflare/README.md +22 -15
- package/dist/templates/minimal-cloudflare/package.json +6 -6
- package/dist/templates/minimal-cloudflare/wrangler.jsonc +1 -1
- package/dist/templates/minimal-node/AGENTS.md +80 -61
- package/dist/templates/minimal-node/README.md +11 -9
- package/dist/templates/minimal-node/package.json +4 -4
- package/dist/templates/react-cloudflare/AGENTS.md +57 -32
- package/dist/templates/react-cloudflare/README.md +8 -5
- package/dist/templates/react-cloudflare/package.json +7 -7
- package/dist/templates/react-cloudflare/src/web/App.tsx +1 -2
- package/dist/templates/react-cloudflare/src/web/NoteList.tsx +2 -2
- package/dist/templates/react-cloudflare/src/web/client.ts +8 -0
- package/dist/templates/react-cloudflare/wrangler.jsonc +1 -1
- package/dist/templates/react-node/AGENTS.md +56 -30
- package/dist/templates/react-node/README.md +8 -7
- package/dist/templates/react-node/package.json +5 -5
- package/dist/templates/react-node/src/web/App.tsx +1 -2
- package/dist/templates/react-node/src/web/NoteList.tsx +2 -2
- package/dist/templates/react-node/src/web/client.ts +8 -0
- package/package.json +4 -10
|
@@ -45,9 +45,15 @@ WORKDIR /app
|
|
|
45
45
|
# Distroless's `nonroot` user is UID 65532. We run as that.
|
|
46
46
|
USER nonroot:nonroot
|
|
47
47
|
|
|
48
|
-
# Copy the TS source, the
|
|
49
|
-
# and the prune'd node_modules.
|
|
48
|
+
# Copy the TS source, the project-root config, the SPA build, the
|
|
49
|
+
# healthcheck, the manifest, and the prune'd node_modules.
|
|
50
|
+
#
|
|
51
|
+
# baerly.config.ts is load-bearing: the server entrypoint does
|
|
52
|
+
# `import config from "../../baerly.config.ts"`, which resolves to the
|
|
53
|
+
# project root. Omit it and the container crashes on boot with an
|
|
54
|
+
# unresolved import.
|
|
50
55
|
COPY --from=build --chown=nonroot:nonroot /app/src src
|
|
56
|
+
COPY --from=build --chown=nonroot:nonroot /app/baerly.config.ts baerly.config.ts
|
|
51
57
|
COPY --from=build --chown=nonroot:nonroot /app/dist/client dist/client
|
|
52
58
|
COPY --from=build --chown=nonroot:nonroot /app/healthcheck.js healthcheck.js
|
|
53
59
|
COPY --from=build --chown=nonroot:nonroot /app/package.json package.json
|
|
@@ -74,15 +74,15 @@ read it via your editor's TS LS or via the published types).
|
|
|
74
74
|
|
|
75
75
|
## Verification
|
|
76
76
|
|
|
77
|
-
| Command | What it does
|
|
78
|
-
| ---------------- |
|
|
79
|
-
| `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
|
|
80
|
-
| `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
|
|
81
|
-
| `pnpm typecheck` | TS typecheck across the worker + web project references (`tsc -b --noEmit`)
|
|
82
|
-
| `pnpm test` | `vitest run --passWithNoTests` — standalone `vitest.config.ts` (Node env, ignores `vite.config.ts` so the Cloudflare plugin doesn't load). The minimal template ships no SPA tests by default; `--passWithNoTests` keeps the gate green until you add one. | seconds
|
|
83
|
-
| `pnpm dev` | Run `vite` — the Cloudflare plugin runs the Worker inside `workerd` next to the SPA dev server; same origin on :5173
|
|
84
|
-
| `pnpm build` | `tsc -b && vite build` — emits `dist/client/` for the Workers Assets binding
|
|
85
|
-
| `pnpm deploy` | `wrangler deploy` — ships Worker + assets in one shipment (auto-creates R2 on first run via `--x-provision`)
|
|
77
|
+
| Command | What it does | Runtime |
|
|
78
|
+
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
|
|
79
|
+
| `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 |
|
|
80
|
+
| `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 |
|
|
81
|
+
| `pnpm typecheck` | TS typecheck across the worker + web project references (`tsc -b --noEmit`) | seconds |
|
|
82
|
+
| `pnpm test` | `vitest run --passWithNoTests` — standalone `vitest.config.ts` (Node env, ignores `vite.config.ts` so the Cloudflare plugin doesn't load). The minimal template ships no SPA tests by default; `--passWithNoTests` keeps the gate green until you add one. | seconds |
|
|
83
|
+
| `pnpm dev` | Run `vite` — the Cloudflare plugin runs the Worker inside `workerd` next to the SPA dev server; same origin on :5173 | seconds to start |
|
|
84
|
+
| `pnpm build` | `tsc -b && vite build` — emits `dist/client/` for the Workers Assets binding | seconds |
|
|
85
|
+
| `pnpm deploy` | `wrangler deploy` — ships Worker + assets in one shipment (auto-creates R2 on first run via `--x-provision`) | seconds |
|
|
86
86
|
|
|
87
87
|
**`pnpm verify` exercises typecheck + tests only.** The dev-auth
|
|
88
88
|
middleware, the SPA bundle, and any custom `/api/*` route are NOT
|
|
@@ -94,44 +94,64 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
94
94
|
|
|
95
95
|
## Where the code is
|
|
96
96
|
|
|
97
|
-
| Path
|
|
98
|
-
|
|
|
99
|
-
| `src/server/index.ts`
|
|
100
|
-
| `wrangler.jsonc`
|
|
101
|
-
| `index.html`
|
|
102
|
-
| `src/web/main.ts`
|
|
103
|
-
| `vite.config.ts`
|
|
104
|
-
| `tsconfig.json`
|
|
105
|
-
| `tsconfig.app.json`
|
|
106
|
-
| `tsconfig.worker.json`
|
|
107
|
-
| `baerly.config.ts`
|
|
108
|
-
| `types.ts`
|
|
97
|
+
| Path | What it is |
|
|
98
|
+
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
99
|
+
| `src/server/index.ts` | Worker entry — `baerlyWorker((env) => ({ verifier }))` |
|
|
100
|
+
| `wrangler.jsonc` | Cloudflare Worker manifest — name, R2 binding, assets, vars |
|
|
101
|
+
| `index.html` | SPA shell — Vite's entry point at the project root; references `/src/web/main.ts`. |
|
|
102
|
+
| `src/web/main.ts` | SPA client entry — 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 or replace; the `config`-bound `client.collection("notes")` is the typed surface (the generic on `.collection()` is the collection **name**, not the row type). Workers Assets serves the built bundle from `dist/client/`. |
|
|
103
|
+
| `vite.config.ts` | Vite + `@cloudflare/vite-plugin` — runs the Worker inside `workerd` in dev |
|
|
104
|
+
| `tsconfig.json` | Root project-references stub |
|
|
105
|
+
| `tsconfig.app.json` | Client TS project (`src/web/`, DOM lib) |
|
|
106
|
+
| `tsconfig.worker.json` | Worker TS project (`src/server/`, workerd lib) |
|
|
107
|
+
| `baerly.config.ts` | App config — `app`, `tenant`, `target`, `domain`, `collections` (schemas live here). |
|
|
108
|
+
| `types.ts` | Shared types between the Worker (`src/server/`) and the SPA (`src/web/`). Both project tsconfigs include this file; put any row type or interface that crosses the boundary here. |
|
|
109
109
|
|
|
110
110
|
> **`baerly.config.ts` and `types.ts` are dual-included** by both
|
|
111
111
|
> `tsconfig.app.json` and `tsconfig.worker.json`. Both can only
|
|
112
112
|
> import from `baerly-storage`, `zod`, and other dual-included root
|
|
113
113
|
> files. Paths under `src/server/` are worker-only; importing them
|
|
114
|
-
> here triggers `TS6307
|
|
115
|
-
>
|
|
116
|
-
> in `types.ts`; re-export from a server-only file if
|
|
117
|
-
> wants a local name.
|
|
114
|
+
> here triggers a `TS6307` "not listed within the file list of
|
|
115
|
+
> project … tsconfig.app.json" error. Cross-boundary interfaces
|
|
116
|
+
> belong in `types.ts`; re-export from a server-only file if
|
|
117
|
+
> downstream code wants a local name.
|
|
118
118
|
|
|
119
119
|
## When editing X, read Y
|
|
120
120
|
|
|
121
|
-
- **Typed collections** —
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
`
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
121
|
+
- **Typed collections** — two ways to get a typed row, in DX order.
|
|
122
|
+
The generic on `client.collection<N>(name)` is the collection
|
|
123
|
+
**name** (constrained to `CollectionNames<typeof config>`), not the
|
|
124
|
+
row type — so don't pass a row type to it.
|
|
125
|
+
1. **Bind the config.** This template's `src/web/main.ts` already
|
|
126
|
+
passes `config` to `createBaerlyClient({ baseUrl, config })` (and
|
|
127
|
+
`src/notes.test.ts` passes `config` to `Db.create`), so
|
|
128
|
+
`client.collection("notes")` returns `ClientCollection<Row>` with
|
|
129
|
+
`Row` derived from the schema declared in `baerly.config.ts`. No
|
|
130
|
+
generic needed. When you need to name that row type elsewhere, use
|
|
131
|
+
`RowOf<typeof config, "notes">` (re-exported from
|
|
132
|
+
`@gusto/baerly-storage`) — not a generic on `.collection()`.
|
|
133
|
+
2. **Cast the handle (undeclared collection).** This template's
|
|
134
|
+
`client` is bound to `config`, so its names narrow to the
|
|
135
|
+
declared collections. To reach a collection that isn't in
|
|
136
|
+
`config`, build an unbound client
|
|
137
|
+
(`createBaerlyClient({ baseUrl })` with no `config`) — its names
|
|
138
|
+
widen to `string` and its row defaults to `DocumentData`. Cast at
|
|
139
|
+
the construction site for a narrower shape that still satisfies
|
|
140
|
+
the kernel's `DocumentData` constraint
|
|
141
|
+
(`{ [k: string]: DocumentValue }`):
|
|
131
142
|
```ts
|
|
132
|
-
import
|
|
133
|
-
|
|
134
|
-
|
|
143
|
+
import {
|
|
144
|
+
createBaerlyClient,
|
|
145
|
+
type ClientCollection,
|
|
146
|
+
type DocumentData,
|
|
147
|
+
} from "@gusto/baerly-storage/client";
|
|
148
|
+
interface Bookmark extends DocumentData {
|
|
149
|
+
_id: string;
|
|
150
|
+
url: string;
|
|
151
|
+
}
|
|
152
|
+
const raw = createBaerlyClient({ baseUrl: "" });
|
|
153
|
+
const bookmarks = raw.collection("bookmarks") as ClientCollection<Bookmark>;
|
|
154
|
+
await bookmarks.all();
|
|
135
155
|
```
|
|
136
156
|
A plain `interface Bookmark { _id: string; url: string }`
|
|
137
157
|
(no index signature) will fail with TS2344 — the constraint
|
|
@@ -139,9 +159,10 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
139
159
|
|
|
140
160
|
- **Writing tests** — the kernel exports `MemoryStorage`, an
|
|
141
161
|
in-memory `Storage` impl that's the canonical backend for unit
|
|
142
|
-
tests. Don't roll your own
|
|
143
|
-
config })`
|
|
144
|
-
`new MemoryStorage()` swaps R2 for an
|
|
162
|
+
tests. Don't roll your own: the same
|
|
163
|
+
`Db.create({ storage, app, tenant, config })` boilerplate prod uses
|
|
164
|
+
also accepts a `new MemoryStorage()` that swaps R2 for an
|
|
165
|
+
in-process map.
|
|
145
166
|
|
|
146
167
|
```ts
|
|
147
168
|
// src/notes.test.ts
|
|
@@ -170,7 +191,6 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
170
191
|
|
|
171
192
|
- **Predicates** — `db.collection("tickets").where({...}).all()`. Two
|
|
172
193
|
shapes:
|
|
173
|
-
|
|
174
194
|
- **Object literal** — equality only (top-level, dotted-path, or
|
|
175
195
|
nested literal sub-predicate). Multi-field is implicit AND.
|
|
176
196
|
- **Callback DSL** — `q => q.eq(...).gt(...).gte(...).lt(...).lte(...).in(...)`
|
|
@@ -185,24 +205,25 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
185
205
|
await db.collection("tickets").where({ status: "open" }).all();
|
|
186
206
|
|
|
187
207
|
// Dotted-path on a nested field
|
|
188
|
-
await db.collection("tickets")
|
|
189
|
-
.where({ "assignee.team": "platform" })
|
|
190
|
-
.all();
|
|
208
|
+
await db.collection("tickets").where({ "assignee.team": "platform" }).all();
|
|
191
209
|
|
|
192
210
|
// Operator on a single field — set membership (callback form)
|
|
193
|
-
await db
|
|
194
|
-
.
|
|
211
|
+
await db
|
|
212
|
+
.collection("tickets")
|
|
213
|
+
.where((q) => q.in("status", ["open", "pending"]))
|
|
195
214
|
.all();
|
|
196
215
|
|
|
197
216
|
// Range — also callback form
|
|
198
|
-
await db
|
|
199
|
-
.
|
|
217
|
+
await db
|
|
218
|
+
.collection("tickets")
|
|
219
|
+
.where((q) => q.gte("priority", 5).lt("priority", 10))
|
|
200
220
|
.all();
|
|
201
221
|
|
|
202
222
|
// AND-merge across two .where() calls (mix shapes freely)
|
|
203
|
-
await db
|
|
223
|
+
await db
|
|
224
|
+
.collection("tickets")
|
|
204
225
|
.where({ status: "open" })
|
|
205
|
-
.where(q => q.gte("priority", 5))
|
|
226
|
+
.where((q) => q.gte("priority", 5))
|
|
206
227
|
.all();
|
|
207
228
|
```
|
|
208
229
|
|
|
@@ -229,8 +250,9 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
229
250
|
});
|
|
230
251
|
```
|
|
231
252
|
|
|
232
|
-
With that declared,
|
|
233
|
-
}).all()` walks
|
|
253
|
+
With that declared, a query like
|
|
254
|
+
`db.collection("tickets").where({ status: "open" }).all()` walks
|
|
255
|
+
`by_status` automatically. Composite indexes
|
|
234
256
|
(`on: ["status", "priority"]`) match any leftmost prefix.
|
|
235
257
|
Mismatches (predicate doesn't cover any index) fall back to a full
|
|
236
258
|
table scan with a metric bump; correctness is preserved because the
|
|
@@ -261,7 +283,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
261
283
|
|
|
262
284
|
On a validation failure the server throws
|
|
263
285
|
`BaerlyError{ code: "SchemaError", issues: [{ path, message }] }`;
|
|
264
|
-
HTTP clients see a
|
|
286
|
+
HTTP clients see a 400 with the same envelope. Validation runs
|
|
265
287
|
on the post-image so `update` and `replace` see the full doc, not
|
|
266
288
|
just the patch.
|
|
267
289
|
|
|
@@ -269,12 +291,12 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
269
291
|
(`db.collection(name).insert(...)`) is the canonical path; reach for `curl`
|
|
270
292
|
only when debugging the wire. Mutation bodies are wrapped:
|
|
271
293
|
|
|
272
|
-
| Route
|
|
273
|
-
|
|
|
274
|
-
| `POST /v1/c/:collection`
|
|
275
|
-
| `PATCH /v1/c/:collection/:id`
|
|
276
|
-
| `PUT /v1/c/:collection/:id`
|
|
277
|
-
| `DELETE /v1/c/:collection/:id`
|
|
294
|
+
| Route | Body | Response |
|
|
295
|
+
| ------------------------------ | ----------------- | ---------------- |
|
|
296
|
+
| `POST /v1/c/:collection` | `{"doc":{...}}` | `201 {_id}` |
|
|
297
|
+
| `PATCH /v1/c/:collection/:id` | `{"patch":{...}}` | `200 {modified}` |
|
|
298
|
+
| `PUT /v1/c/:collection/:id` | `{"doc":{...}}` | `200 {modified}` |
|
|
299
|
+
| `DELETE /v1/c/:collection/:id` | — | `204` |
|
|
278
300
|
|
|
279
301
|
Reads (`GET /v1/c/:collection[/:id]`, `GET /v1/count?collection=…`,
|
|
280
302
|
`GET /v1/since?collection=…&cursor=…`) take no body and return
|
|
@@ -289,7 +311,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
289
311
|
every request resolves to `tenant: "minimal-demo"` and `Authorization`
|
|
290
312
|
is ignored. The adapter reads `config.auth` to pick its verifier;
|
|
291
313
|
a `verifier:` on the factory overrides it. `baerly doctor
|
|
292
|
-
|
|
314
|
+
--target=cloudflare` warns on `"none"` for deploy targets. See
|
|
293
315
|
"Going to production" below for the two production-fit recipes.
|
|
294
316
|
|
|
295
317
|
### Going to production
|
|
@@ -299,6 +321,7 @@ zero env vars. Two patterns flip to a production-fit posture; pick the
|
|
|
299
321
|
one matching your gate.
|
|
300
322
|
|
|
301
323
|
<!-- pattern-a:start -->
|
|
324
|
+
|
|
302
325
|
**Pattern A — env-aware verifier (recommended for CF Access).** Same
|
|
303
326
|
artifact ships to dev and prod; the factory `verifier:` override
|
|
304
327
|
engages only when prod env vars are present. `baerlyWorker` resolves
|
|
@@ -313,7 +336,7 @@ export default defineConfig({
|
|
|
313
336
|
app: "minimal-cloudflare",
|
|
314
337
|
tenant: "minimal-demo",
|
|
315
338
|
target: "cloudflare",
|
|
316
|
-
auth: "none",
|
|
339
|
+
auth: "none", // dev default
|
|
317
340
|
collections: { notes: {} },
|
|
318
341
|
});
|
|
319
342
|
```
|
|
@@ -336,6 +359,7 @@ export default baerlyWorker<AppEnv>((env) => ({
|
|
|
336
359
|
verifier: cloudflareAccess({
|
|
337
360
|
teamDomain: env.CF_ACCESS_TEAM_DOMAIN,
|
|
338
361
|
audienceTag: env.CF_ACCESS_AUDIENCE_TAG,
|
|
362
|
+
tenantPrefix: config.tenant,
|
|
339
363
|
}),
|
|
340
364
|
}),
|
|
341
365
|
}));
|
|
@@ -345,12 +369,15 @@ Set both `CF_ACCESS_TEAM_DOMAIN` and `CF_ACCESS_AUDIENCE_TAG` in
|
|
|
345
369
|
`wrangler.jsonc:vars` for prod (they're public identifiers, not
|
|
346
370
|
secrets). Dev `wrangler dev` sees them as `undefined`, the spread
|
|
347
371
|
short-circuits, and `config.auth: "none"` runs. Prod sees them set
|
|
348
|
-
and `cloudflareAccess` engages.
|
|
372
|
+
and `cloudflareAccess` engages. Every verified token is pinned to
|
|
373
|
+
`config.tenant`; pass `tenantClaim` instead only when your Access JWT
|
|
374
|
+
actually carries a tenant claim.
|
|
349
375
|
|
|
350
376
|
<!-- pattern-a:end -->
|
|
351
377
|
<!-- pattern-b:start -->
|
|
378
|
+
|
|
352
379
|
**Pattern B — `auth: "shared-secret"`.** Single-tenant
|
|
353
|
-
server-to-server callers (CI
|
|
380
|
+
server-to-server callers (CI and internal services). No factory
|
|
354
381
|
code changes; only `baerly.config.ts` flips:
|
|
355
382
|
|
|
356
383
|
```ts
|
|
@@ -391,11 +418,13 @@ if `auth: "shared-secret"` is set without `SHARED_SECRET` reachable
|
|
|
391
418
|
from the runtime env.
|
|
392
419
|
|
|
393
420
|
<!-- pattern-b:end -->
|
|
421
|
+
|
|
394
422
|
- **Extending the Worker with a custom route** — `baerlyWorker(...)`
|
|
395
|
-
owns `/v1
|
|
423
|
+
owns `/v1/*`, including `/v1/healthz`. For server-side endpoints the SPA
|
|
396
424
|
client can't run on its own (the canonical case: an endpoint that
|
|
397
|
-
|
|
398
|
-
reads + by-id mutations only), wrap the
|
|
425
|
+
fans a write across several documents server-side, since
|
|
426
|
+
`createBaerlyClient` is reads + by-id mutations only), wrap the
|
|
427
|
+
worker `fetch`:
|
|
399
428
|
|
|
400
429
|
```ts
|
|
401
430
|
// src/server/index.ts
|
|
@@ -428,10 +457,10 @@ from the runtime env.
|
|
|
428
457
|
tenant: config.tenant,
|
|
429
458
|
config,
|
|
430
459
|
});
|
|
431
|
-
// …db.
|
|
460
|
+
// …db.collection(...).insert(doc), db.collection(...).get(id), etc.
|
|
432
461
|
return new Response(null, { status: 204 });
|
|
433
462
|
}
|
|
434
|
-
// Fall through to the baerly cascade for /v1
|
|
463
|
+
// Fall through to the baerly cascade for /v1/*, including /v1/healthz.
|
|
435
464
|
return baerly.fetch!(req, env, ctx);
|
|
436
465
|
},
|
|
437
466
|
} satisfies ExportedHandler<BaerlyEnv>;
|
|
@@ -452,7 +481,7 @@ from the runtime env.
|
|
|
452
481
|
`SHARED_SECRET` (only required if you flip `auth` to
|
|
453
482
|
`"shared-secret"`) live in `.dev.vars` for local `wrangler dev`
|
|
454
483
|
and behind `wrangler secret put` in production. `baerly doctor
|
|
455
|
-
|
|
484
|
+
--target=cloudflare` reads `CF_ACCESS_*` from `wrangler.jsonc:vars`
|
|
456
485
|
only, so setting them via `wrangler secret put` would silently
|
|
457
486
|
defeat the doctor check.
|
|
458
487
|
|
|
@@ -479,12 +508,14 @@ from the runtime env.
|
|
|
479
508
|
into the predicate so the index planner can prune
|
|
480
509
|
(`db.collection("notes").where({ ... }).all()`), or maintain a
|
|
481
510
|
side-projection (D1/KV/search index) populated incrementally from
|
|
482
|
-
the `/v1/since
|
|
511
|
+
the `/v1/since?collection=<name>&cursor=<opaque>` log feed or from
|
|
512
|
+
a write hook — never re-scan per
|
|
483
513
|
request.
|
|
484
514
|
|
|
485
515
|
## Maintenance
|
|
486
516
|
|
|
487
517
|
<!-- pattern-d:start -->
|
|
518
|
+
|
|
488
519
|
Maintenance is automatic and write-triggered. No cron, no sidecar, no scheduler, no
|
|
489
520
|
timer, no lock, no app-config knob — identical on every host. Every write runs a
|
|
490
521
|
bounded GC slice inline plus a go/no-go compaction fold bounded by a fold-size ceiling
|
|
@@ -498,10 +529,11 @@ maintenance, so the published idle-reader cost bound holds.
|
|
|
498
529
|
A bucket maintains itself as long as it takes writes. A bucket served read-only does
|
|
499
530
|
not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
|
|
500
531
|
graduate once a collection is large. See docs/about/graduation.md for the per-tier
|
|
501
|
-
envelope and the BAERLY_MAINTENANCE_
|
|
532
|
+
envelope and the `BAERLY_MAINTENANCE_*` operator env vars (you almost never need them).
|
|
502
533
|
|
|
503
534
|
Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
|
|
504
535
|
your own schedule. Not required for steady-state operation.
|
|
536
|
+
|
|
505
537
|
<!-- pattern-d:end -->
|
|
506
538
|
|
|
507
539
|
## When to graduate
|
|
@@ -513,21 +545,25 @@ model puts the soft ceiling at:
|
|
|
513
545
|
- **~10 GB / tenant**
|
|
514
546
|
- **~100 collections / tenant**
|
|
515
547
|
|
|
516
|
-
Past those, S3 list-prefix latency,
|
|
548
|
+
Past those, S3 list-prefix latency, snapshot fold cost, and per-class
|
|
517
549
|
op pricing start to dominate; you're better off on a real database.
|
|
518
550
|
Pick your graduation target:
|
|
551
|
+
|
|
519
552
|
- **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
|
|
520
553
|
- **Off-Workers or portability matters:** managed Postgres.
|
|
521
554
|
- **Single-instance Node:** SQLite via Litestream.
|
|
522
555
|
|
|
523
556
|
Either way, the export below is mechanical because log entries are
|
|
524
|
-
|
|
557
|
+
Debezium-style CDC change events — graduation is a Baerly win,
|
|
525
558
|
not a churn event.
|
|
526
559
|
|
|
527
|
-
**Estimate your current rate:**
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
560
|
+
**Estimate your current rate:** for Node/self-hosted buckets,
|
|
561
|
+
`baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
|
|
562
|
+
--tenant=<tenant>` lists recent log entries per collection and computes
|
|
563
|
+
writes/min. On Cloudflare, use canonical logs for trend history and
|
|
564
|
+
`baerly cost --bucket=<bucket-uri> --collection=<collection>` for the
|
|
565
|
+
current operation-cost projection until the usage scanner is wired to
|
|
566
|
+
R2 bindings.
|
|
531
567
|
|
|
532
568
|
**Export when ready:** `baerly export --target=sqlite|postgres|d1
|
|
533
569
|
--bucket=<...> --app=<...> --tenant=<...> --collection=<...>` writes a
|
|
@@ -542,6 +578,6 @@ The export is point-in-time and honours the active schema. Flags:
|
|
|
542
578
|
|
|
543
579
|
- `baerly.config.ts` — app config.
|
|
544
580
|
- `src/server/index.ts` — Worker entry.
|
|
545
|
-
- `wrangler.jsonc` — Cloudflare Worker manifest (R2 binding, `assets:`, vars
|
|
581
|
+
- `wrangler.jsonc` — Cloudflare Worker manifest (R2 binding, `assets:`, vars).
|
|
546
582
|
- `vite.config.ts` — Vite + `@cloudflare/vite-plugin`.
|
|
547
583
|
- `package.json` — root scripts + dependencies.
|
|
@@ -7,6 +7,8 @@ day-1 happy path works with zero env vars; flip to Cloudflare
|
|
|
7
7
|
Access or a shared secret before deploy — see "Going to
|
|
8
8
|
production" below.
|
|
9
9
|
|
|
10
|
+
**The only persistent component is your R2 bucket** — there is no Worker to keep warm, no database daemon to operate, no idle bill, and maintenance is automatic and write-triggered (no cron, no sidecar, no scheduler).
|
|
11
|
+
|
|
10
12
|
## What you got
|
|
11
13
|
|
|
12
14
|
```
|
|
@@ -16,7 +18,7 @@ minimal-cloudflare/
|
|
|
16
18
|
├── tsconfig.app.json # client TS project (src/web)
|
|
17
19
|
├── tsconfig.worker.json # Worker TS project (src/server)
|
|
18
20
|
├── vite.config.ts # Vite + @cloudflare/vite-plugin
|
|
19
|
-
├── wrangler.jsonc # Worker manifest — R2 binding, assets, vars
|
|
21
|
+
├── wrangler.jsonc # Worker manifest — R2 binding, assets, vars
|
|
20
22
|
├── index.html # SPA shell — Vite's entry point
|
|
21
23
|
├── baerly.config.ts # app, tenant, target, domain
|
|
22
24
|
├── AGENTS.md # deeper guide: predicates, schemas,
|
|
@@ -61,7 +63,7 @@ references.
|
|
|
61
63
|
# `wrangler r2 bucket create` + `wrangler deploy`.
|
|
62
64
|
baerly deploy
|
|
63
65
|
|
|
64
|
-
# Verify the deployed config — bindings, secrets,
|
|
66
|
+
# Verify the deployed config — bindings, secrets, optional triggers.
|
|
65
67
|
baerly doctor --target=cloudflare
|
|
66
68
|
```
|
|
67
69
|
|
|
@@ -91,23 +93,28 @@ needs no secrets. If you adopt a "Going to production" recipe:
|
|
|
91
93
|
## Next steps
|
|
92
94
|
|
|
93
95
|
1. **Read `AGENTS.md`** for the agent-facing guide — predicates,
|
|
94
|
-
indexes, schemas, auth recipes,
|
|
96
|
+
indexes, schemas, auth recipes, write-triggered maintenance, and the
|
|
95
97
|
graduation criteria. Codex CLI reads `AGENTS.md`; Claude Code
|
|
96
98
|
reads `CLAUDE.md`; both files are byte-identical so either
|
|
97
99
|
surface lands you the same context.
|
|
98
100
|
2. **Declare your first collection schema** in `baerly.config.ts`
|
|
99
101
|
via `defineConfig({ collections: { ... } })` and pass it to
|
|
100
102
|
`Db.create({ ..., collections })`. Schema validation is live;
|
|
101
|
-
bad inserts return
|
|
103
|
+
bad inserts return 400.
|
|
102
104
|
3. **Set up production auth** — follow `AGENTS.md` → "Going to
|
|
103
105
|
production". Pattern A wires CF Access via an env-aware factory
|
|
104
106
|
`verifier:` override; Pattern B flips `auth: "shared-secret"`.
|
|
105
107
|
`baerly doctor --target=cloudflare` reports any gaps.
|
|
106
|
-
4. **Check usage trends** — run
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
108
|
+
4. **Check usage trends** — run the current operation-cost
|
|
109
|
+
projection:
|
|
110
|
+
|
|
111
|
+
```sh
|
|
112
|
+
baerly cost --bucket=<bucket-uri> --collection=<collection-name>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Then pipe canonical logs to your observability system for 7-day /
|
|
116
|
+
30-day write-rate trends. The graduation ceiling is described in
|
|
117
|
+
the "When to graduate" section below.
|
|
111
118
|
|
|
112
119
|
## When to graduate
|
|
113
120
|
|
|
@@ -120,8 +127,7 @@ start to dominate, and you're better off on a real database:
|
|
|
120
127
|
- **~100 collections / tenant**
|
|
121
128
|
|
|
122
129
|
When you cross the soft ceiling, graduation is mechanical:
|
|
123
|
-
`baerly export --target=postgres` walks your log entries (already
|
|
124
|
-
Postgres-logical-replication-shaped) into a real DB. If your
|
|
130
|
+
`baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a real DB. If your
|
|
125
131
|
deploy target is Cloudflare Workers and you'll accept Cloudflare
|
|
126
132
|
lock-in, [D1](https://developers.cloudflare.com/d1/) is cheaper
|
|
127
133
|
per-write at M-size and is a natural next step. If you're on
|
|
@@ -134,7 +140,7 @@ not a churn event.
|
|
|
134
140
|
|
|
135
141
|
```sh
|
|
136
142
|
baerly export --target=postgres \
|
|
137
|
-
--bucket=minimal-cloudflare --app=minimal-cloudflare --tenant=<your-tenant> \
|
|
143
|
+
--bucket=s3://minimal-cloudflare --app=minimal-cloudflare --tenant=<your-tenant> \
|
|
138
144
|
--collection=<collection-name> --output=./out.sql
|
|
139
145
|
```
|
|
140
146
|
|
|
@@ -155,7 +161,8 @@ Before deploy, follow `AGENTS.md` → "Going to production":
|
|
|
155
161
|
`wrangler.jsonc:vars`. The `cloudflareAccess()` preset
|
|
156
162
|
(re-exported from `@gusto/baerly-storage/auth`) reads the JWT off
|
|
157
163
|
`Cf-Access-Jwt-Assertion`, validates it against your team's JWKS,
|
|
158
|
-
and
|
|
164
|
+
and pins `tenantPrefix` to `config.tenant` unless you pass an
|
|
165
|
+
explicit tenant claim.
|
|
159
166
|
- **Pattern B — `auth: "shared-secret"`.** Single-tenant
|
|
160
167
|
server-to-server callers. Flip `auth` in `baerly.config.ts` and
|
|
161
168
|
set `SHARED_SECRET` via `wrangler secret put`.
|
|
@@ -163,7 +170,7 @@ Before deploy, follow `AGENTS.md` → "Going to production":
|
|
|
163
170
|
## Pointers
|
|
164
171
|
|
|
165
172
|
- `baerly.config.ts` — app config (`app`, `tenant`, `target`, `domain`).
|
|
166
|
-
- `src/server/index.ts` — Worker fetch
|
|
167
|
-
- `wrangler.jsonc` — Cloudflare Worker manifest (R2 binding, `assets:`, vars
|
|
173
|
+
- `src/server/index.ts` — Worker fetch entry.
|
|
174
|
+
- `wrangler.jsonc` — Cloudflare Worker manifest (R2 binding, `assets:`, vars).
|
|
168
175
|
- `vite.config.ts` — Vite + `@cloudflare/vite-plugin`.
|
|
169
176
|
- `AGENTS.md` / `CLAUDE.md` — agent-facing guide (byte-identical).
|
|
@@ -15,14 +15,14 @@
|
|
|
15
15
|
"@gusto/baerly-storage": "workspace:*"
|
|
16
16
|
},
|
|
17
17
|
"devDependencies": {
|
|
18
|
-
"@cloudflare/vite-plugin": "^1.
|
|
18
|
+
"@cloudflare/vite-plugin": "^1.40.1",
|
|
19
19
|
"@cloudflare/workers-types": "^4",
|
|
20
|
-
"@types/node": "^
|
|
21
|
-
"happy-dom": "^20.
|
|
20
|
+
"@types/node": "^25.9.2",
|
|
21
|
+
"happy-dom": "^20.10.2",
|
|
22
22
|
"typescript": "^6.0.3",
|
|
23
|
-
"vite": "^8.0.
|
|
24
|
-
"vitest": "^4.1.
|
|
25
|
-
"wrangler": "^4.
|
|
23
|
+
"vite": "^8.0.16",
|
|
24
|
+
"vitest": "^4.1.8",
|
|
25
|
+
"wrangler": "^4.99.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",
|