@gusto/create-baerly-storage 0.1.0 → 0.1.2
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/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/templates/addons/docker/Dockerfile +7 -1
- package/dist/templates/minimal-cloudflare/AGENTS.md +24 -33
- package/dist/templates/minimal-node/AGENTS.md +24 -48
- package/dist/templates/minimal-node/README.md +9 -6
- package/dist/templates/react-cloudflare/AGENTS.md +24 -33
- package/dist/templates/react-node/AGENTS.md +25 -48
- package/dist/templates/react-node/README.md +9 -6
- package/dist/templates/react-node/src/server/index.ts +4 -1
- package/package.json +5 -2
|
@@ -5,7 +5,13 @@
|
|
|
5
5
|
# Runtime path: node --experimental-strip-types src/server/index.ts.
|
|
6
6
|
# No `tsc` emit at runtime — the server runs straight off TS source.
|
|
7
7
|
# The SPA bundle (vite build) lives under dist/client/ and is served
|
|
8
|
-
# by
|
|
8
|
+
# by baerlyNode({ webRoot }).
|
|
9
|
+
#
|
|
10
|
+
# If you diverge and compile the server with `tsc -b` instead of
|
|
11
|
+
# strip-types, exclude `*.tsbuildinfo` from the build context (or run
|
|
12
|
+
# `tsc -b --force`): a stale tsbuildinfo copied in lets incremental
|
|
13
|
+
# `tsc -b` skip emit, and the container then crashes on a missing
|
|
14
|
+
# dist/server/*.js.
|
|
9
15
|
|
|
10
16
|
# Base images are tag-pinned (not digest-pinned) so this template
|
|
11
17
|
# stays fresh as new patch images ship. Once you vendor this file,
|
|
@@ -29,7 +29,7 @@ Common anti-patterns that compile but are wrong:
|
|
|
29
29
|
`db.collection(name).insert(row)` and `.where({ ... }).all()`.
|
|
30
30
|
- `z.string().nullable()` in a schema — `DocumentValue` excludes
|
|
31
31
|
`null`. Use `.optional()`; `null` in an update patch is the RFC
|
|
32
|
-
|
|
32
|
+
7386 deletion sentinel, not a storable value.
|
|
33
33
|
- Raw SQL strings, `WHERE` clauses, hand-built query AST — the only
|
|
34
34
|
query surface is `db.collection(...).where({ field: value }).all()` or
|
|
35
35
|
`.where(q => q.gte("count", 1))`. See **Predicates** below.
|
|
@@ -247,7 +247,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
247
247
|
import { defineConfig } from "@gusto/baerly-storage/config";
|
|
248
248
|
|
|
249
249
|
const Ticket = z.object({
|
|
250
|
-
_id: z.string()
|
|
250
|
+
_id: z.string(),
|
|
251
251
|
status: z.enum(["open", "closed"]),
|
|
252
252
|
title: z.string().min(1),
|
|
253
253
|
});
|
|
@@ -456,37 +456,6 @@ from the runtime env.
|
|
|
456
456
|
only, so setting them via `wrangler secret put` would silently
|
|
457
457
|
defeat the doctor check.
|
|
458
458
|
|
|
459
|
-
- **Maintenance loop (Cloudflare)** — opt-in. Add
|
|
460
|
-
`"triggers": { "crons": ["* * * * *"] }` to `wrangler.jsonc` and
|
|
461
|
-
wire `scheduled` on the options the factory returns from `baerlyWorker((env) => ({ ... }))`. The
|
|
462
|
-
handler is your code, so you choose what to call
|
|
463
|
-
(`runScheduledMaintenance`, `compact`, `runGc`) and which
|
|
464
|
-
`current.json` keys to target. Multi-tenant deployments iterate
|
|
465
|
-
their own keys; single-tenant deployments call once with a fixed
|
|
466
|
-
key. See the JSDoc on `WorkerScheduledHandler` in
|
|
467
|
-
`@gusto/baerly-storage/cloudflare` and `runScheduledMaintenance` in
|
|
468
|
-
`@gusto/baerly-storage/maintenance` for the wiring + free-vs-paid-tier
|
|
469
|
-
subrequest-budget guidance.
|
|
470
|
-
|
|
471
|
-
Maintenance emits one canonical info line per run on stdout
|
|
472
|
-
(Workers Logs ingestion). Filter your log stream on
|
|
473
|
-
`"unit_of_work": "maintenance"` and read these fields:
|
|
474
|
-
|
|
475
|
-
- `compact_written` — log entries folded into the new snapshot
|
|
476
|
-
this tick (`0` when the live tail was below
|
|
477
|
-
`minEntriesToCompact`). Only set when the tick called
|
|
478
|
-
`runScheduledMaintenance` or `compact` directly; isolated
|
|
479
|
-
`runGc` ticks emit their own `unit_of_work: "gc"` line.
|
|
480
|
-
- `gc_swept` — keys deleted this tick (`0` when no candidates
|
|
481
|
-
aged out). Only set when the tick called
|
|
482
|
-
`runScheduledMaintenance` or `runGc` directly.
|
|
483
|
-
- The kernel also emits the recorder-bag fields alongside:
|
|
484
|
-
`db.compact.entries_folded_p50` / `_p99` / `_count` / `_sum`,
|
|
485
|
-
`db.manifest.lag_window_depth`, `db.orphan.candidate_count`,
|
|
486
|
-
`db.gc.entries_swept_per_second`, `db.gc.swept_total`.
|
|
487
|
-
Useful for dashboards; the four explicit fields above are
|
|
488
|
-
the at-a-glance summary.
|
|
489
|
-
|
|
490
459
|
- **Deploy** — `baerly deploy --target=cloudflare` runs
|
|
491
460
|
`wrangler deploy --x-provision --x-auto-create` (Wrangler 4.10+)
|
|
492
461
|
to auto-create the declared R2 buckets and ship the Worker. When
|
|
@@ -513,6 +482,28 @@ from the runtime env.
|
|
|
513
482
|
the `/v1/since` log feed or from a write hook — never re-scan per
|
|
514
483
|
request.
|
|
515
484
|
|
|
485
|
+
## Maintenance
|
|
486
|
+
|
|
487
|
+
<!-- pattern-d:start -->
|
|
488
|
+
Maintenance is automatic and write-triggered. No cron, no sidecar, no scheduler, no
|
|
489
|
+
timer, no lock, no app-config knob — identical on every host. Every write runs a
|
|
490
|
+
bounded GC slice inline plus a go/no-go compaction fold bounded by a fold-size ceiling
|
|
491
|
+
whose default is safe on every tier. A size-ratio threshold means idle buckets pay
|
|
492
|
+
nothing. Concurrent folds are safe without coordination: the commit is a
|
|
493
|
+
compare-and-swap, so a fold that loses to a concurrent write is simply discarded and
|
|
494
|
+
its leftover swept by GC. On Cloudflare the fold is deferred past the response via
|
|
495
|
+
ctx.waitUntil; everywhere else it runs inline. **Reads are pure** — they never run
|
|
496
|
+
maintenance, so the published idle-reader cost bound holds.
|
|
497
|
+
|
|
498
|
+
A bucket maintains itself as long as it takes writes. A bucket served read-only does
|
|
499
|
+
not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
|
|
500
|
+
graduate once a collection is large. See docs/about/graduation.md for the per-tier
|
|
501
|
+
envelope and the BAERLY_MAINTENANCE_* operator env vars (you almost never need them).
|
|
502
|
+
|
|
503
|
+
Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
|
|
504
|
+
your own schedule. Not required for steady-state operation.
|
|
505
|
+
<!-- pattern-d:end -->
|
|
506
|
+
|
|
516
507
|
## When to graduate
|
|
517
508
|
|
|
518
509
|
baerly is designed for the small-to-medium operating point. The cost
|
|
@@ -29,7 +29,7 @@ Common anti-patterns that compile but are wrong:
|
|
|
29
29
|
`db.collection(name).insert(row)` and `.where({ ... }).all()`.
|
|
30
30
|
- `z.string().nullable()` in a schema — `DocumentValue` excludes
|
|
31
31
|
`null`. Use `.optional()`; `null` in an update patch is the RFC
|
|
32
|
-
|
|
32
|
+
7386 deletion sentinel, not a storable value.
|
|
33
33
|
- Raw SQL strings, `WHERE` clauses, hand-built query AST — the only
|
|
34
34
|
query surface is `db.collection(...).where({ field: value }).all()` or
|
|
35
35
|
`.where(q => q.gte("count", 1))`. See **Predicates** below.
|
|
@@ -234,7 +234,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
234
234
|
import { defineConfig } from "@gusto/baerly-storage/config";
|
|
235
235
|
|
|
236
236
|
const Ticket = z.object({
|
|
237
|
-
_id: z.string()
|
|
237
|
+
_id: z.string(),
|
|
238
238
|
status: z.enum(["open", "closed"]),
|
|
239
239
|
title: z.string().min(1),
|
|
240
240
|
});
|
|
@@ -364,52 +364,6 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
|
|
|
364
364
|
`() => Promise<Credentials>` or an `@aws-sdk/credential-providers`
|
|
365
365
|
factory through the seam.
|
|
366
366
|
|
|
367
|
-
- **Maintenance loop (Node)** — `src/server/index.ts` passes a
|
|
368
|
-
`maintenance: { collections, tenants }` option to `baerlyNode`.
|
|
369
|
-
Each tick (hourly by default; override via
|
|
370
|
-
`maintenance.intervalMs`) runs one compact+GC pass per
|
|
371
|
-
`(tenant, collection)` pair against the engine's default
|
|
372
|
-
unbounded maintenance profile (folds the entire live tail; sweeps
|
|
373
|
-
every aged-out candidate the GC marks).
|
|
374
|
-
|
|
375
|
-
Opt-in via the `MAINTENANCE_COLLECTIONS` env var — a comma-
|
|
376
|
-
separated list of collection slugs:
|
|
377
|
-
|
|
378
|
-
```sh
|
|
379
|
-
MAINTENANCE_COLLECTIONS=tickets,comments
|
|
380
|
-
```
|
|
381
|
-
|
|
382
|
-
When unset, the entry passes `maintenance: undefined` to
|
|
383
|
-
`baerlyNode` and no in-process loop runs. Operators who prefer
|
|
384
|
-
external scheduling can wire a separate cron trigger (PaaS cron,
|
|
385
|
-
k8s CronJob, systemd timer) per collection that invokes
|
|
386
|
-
`runMaintenanceTick` directly — that function stays exported
|
|
387
|
-
from `@gusto/baerly-storage/node`.
|
|
388
|
-
|
|
389
|
-
The template is single-tenant by default (`tenants: [TENANT]`).
|
|
390
|
-
Multi-tenant deployments override the `tenants` array in
|
|
391
|
-
`src/server/index.ts`; the cross-product `tenants × collections`
|
|
392
|
-
defines the work per tick. A separate `runMaintenanceTick` call
|
|
393
|
-
fires per pair, and a failure on one pair logs to stderr without
|
|
394
|
-
crashing the process or blocking the others.
|
|
395
|
-
|
|
396
|
-
Maintenance emits one canonical info line per `(tenant,
|
|
397
|
-
collection)` run on stdout.
|
|
398
|
-
Filter your log stream on `"unit_of_work": "maintenance"` and
|
|
399
|
-
read these fields:
|
|
400
|
-
|
|
401
|
-
- `compact_written` — log entries folded into the new snapshot
|
|
402
|
-
this tick (`0` when the live tail was below
|
|
403
|
-
`minEntriesToCompact`).
|
|
404
|
-
- `gc_swept` — keys deleted this tick (`0` when no candidates
|
|
405
|
-
aged out).
|
|
406
|
-
- The kernel also emits the recorder-bag fields alongside:
|
|
407
|
-
`db.compact.entries_folded_p50` / `_p99` / `_count` / `_sum`,
|
|
408
|
-
`db.manifest.lag_window_depth`, `db.orphan.candidate_count`,
|
|
409
|
-
`db.gc.entries_swept_per_second`, `db.gc.swept_total`.
|
|
410
|
-
Useful for dashboards; the four explicit fields above are
|
|
411
|
-
the at-a-glance summary.
|
|
412
|
-
|
|
413
367
|
- **Deploy** — runs anywhere `node server.js` runs. The
|
|
414
368
|
`package.json`'s `start` script is
|
|
415
369
|
`node --experimental-strip-types src/server/index.ts`. Arrange the
|
|
@@ -445,6 +399,28 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
|
|
|
445
399
|
incrementally from the `/v1/since` log feed or from a write hook —
|
|
446
400
|
never re-scan per request.
|
|
447
401
|
|
|
402
|
+
## Maintenance
|
|
403
|
+
|
|
404
|
+
<!-- pattern-d:start -->
|
|
405
|
+
Maintenance is automatic and write-triggered. No cron, no sidecar, no scheduler, no
|
|
406
|
+
timer, no lock, no app-config knob — identical on every host. Every write runs a
|
|
407
|
+
bounded GC slice inline plus a go/no-go compaction fold bounded by a fold-size ceiling
|
|
408
|
+
whose default is safe on every tier. A size-ratio threshold means idle buckets pay
|
|
409
|
+
nothing. Concurrent folds are safe without coordination: the commit is a
|
|
410
|
+
compare-and-swap, so a fold that loses to a concurrent write is simply discarded and
|
|
411
|
+
its leftover swept by GC. On Cloudflare the fold is deferred past the response via
|
|
412
|
+
ctx.waitUntil; everywhere else it runs inline. **Reads are pure** — they never run
|
|
413
|
+
maintenance, so the published idle-reader cost bound holds.
|
|
414
|
+
|
|
415
|
+
A bucket maintains itself as long as it takes writes. A bucket served read-only does
|
|
416
|
+
not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
|
|
417
|
+
graduate once a collection is large. See docs/about/graduation.md for the per-tier
|
|
418
|
+
envelope and the BAERLY_MAINTENANCE_* operator env vars (you almost never need them).
|
|
419
|
+
|
|
420
|
+
Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
|
|
421
|
+
your own schedule. Not required for steady-state operation.
|
|
422
|
+
<!-- pattern-d:end -->
|
|
423
|
+
|
|
448
424
|
## When to graduate
|
|
449
425
|
|
|
450
426
|
baerly is designed for the small-to-medium operating point. The cost
|
|
@@ -65,12 +65,15 @@ posture needs no auth env vars; if you adopt Pattern B / C from
|
|
|
65
65
|
"Going to production" below, also set `SHARED_SECRET` (Pattern B)
|
|
66
66
|
or `JWKS_URL` + `JWT_ISSUER` + `JWT_AUDIENCE` (Pattern C). Optional:
|
|
67
67
|
`R2_ACCOUNT_ID` (switches the storage factory from `s3Storage` to
|
|
68
|
-
`r2Storage`), `AWS_REGION`, `PORT`, `TENANT`, `WEB_ROOT
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
68
|
+
`r2Storage`), `AWS_REGION`, `PORT`, `TENANT`, `WEB_ROOT`.
|
|
69
|
+
|
|
70
|
+
Maintenance (compaction + GC) is automatic and in-band: it runs
|
|
71
|
+
inline on the rare write that crosses a maintenance trigger — no env
|
|
72
|
+
var, no tick, no `setInterval`, no operator scheduler. Two ops-plane
|
|
73
|
+
env vars tune it: `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` raises the
|
|
74
|
+
snapshot ceiling and `BAERLY_MAINTENANCE_DISABLE=1` is a kill switch.
|
|
75
|
+
For an explicit out-of-band sweep, call `runScheduledMaintenance`
|
|
76
|
+
from `@gusto/baerly-storage`.
|
|
74
77
|
|
|
75
78
|
After `pnpm build`, `http://localhost:8080/` serves the built SPA
|
|
76
79
|
out of `dist/client/` and `http://localhost:8080/v1/*` is the
|
|
@@ -29,7 +29,7 @@ Common anti-patterns that compile but are wrong:
|
|
|
29
29
|
`db.collection(name).insert(row)` and `.where({ ... }).all()`.
|
|
30
30
|
- `z.string().nullable()` in a schema — `DocumentValue` excludes
|
|
31
31
|
`null`. Use `.optional()`; `null` in an update patch is the RFC
|
|
32
|
-
|
|
32
|
+
7386 deletion sentinel, not a storable value.
|
|
33
33
|
- Raw SQL strings, `WHERE` clauses, hand-built query AST — the only
|
|
34
34
|
query surface is `db.collection(...).where({ field: value }).all()` or
|
|
35
35
|
`.where(q => q.gte("count", 1))`. See **Predicates** below.
|
|
@@ -475,37 +475,6 @@ from the runtime env.
|
|
|
475
475
|
only, so setting them via `wrangler secret put` would silently
|
|
476
476
|
defeat the doctor check.
|
|
477
477
|
|
|
478
|
-
- **Maintenance loop (Cloudflare)** — opt-in. Add
|
|
479
|
-
`"triggers": { "crons": ["* * * * *"] }` to `wrangler.jsonc` and
|
|
480
|
-
wire `scheduled` on the options the factory returns from `baerlyWorker((env) => ({ ... }))`. The
|
|
481
|
-
handler is your code, so you choose what to call
|
|
482
|
-
(`runScheduledMaintenance`, `compact`, `runGc`) and which
|
|
483
|
-
`current.json` keys to target. Multi-tenant deployments iterate
|
|
484
|
-
their own keys; single-tenant deployments call once with a fixed
|
|
485
|
-
key. See the JSDoc on `WorkerScheduledHandler` in
|
|
486
|
-
`@gusto/baerly-storage/cloudflare` and `runScheduledMaintenance` in
|
|
487
|
-
`@gusto/baerly-storage/maintenance` for the wiring + free-vs-paid-tier
|
|
488
|
-
subrequest-budget guidance.
|
|
489
|
-
|
|
490
|
-
Maintenance emits one canonical info line per run on stdout
|
|
491
|
-
(Workers Logs ingestion). Filter your log stream on
|
|
492
|
-
`"unit_of_work": "maintenance"` and read these fields:
|
|
493
|
-
|
|
494
|
-
- `compact_written` — log entries folded into the new snapshot
|
|
495
|
-
this tick (`0` when the live tail was below
|
|
496
|
-
`minEntriesToCompact`). Only set when the tick called
|
|
497
|
-
`runScheduledMaintenance` or `compact` directly; isolated
|
|
498
|
-
`runGc` ticks emit their own `unit_of_work: "gc"` line.
|
|
499
|
-
- `gc_swept` — keys deleted this tick (`0` when no candidates
|
|
500
|
-
aged out). Only set when the tick called
|
|
501
|
-
`runScheduledMaintenance` or `runGc` directly.
|
|
502
|
-
- The kernel also emits the recorder-bag fields alongside:
|
|
503
|
-
`db.compact.entries_folded_p50` / `_p99` / `_count` / `_sum`,
|
|
504
|
-
`db.manifest.lag_window_depth`, `db.orphan.candidate_count`,
|
|
505
|
-
`db.gc.entries_swept_per_second`, `db.gc.swept_total`.
|
|
506
|
-
Useful for dashboards; the four explicit fields above are
|
|
507
|
-
the at-a-glance summary.
|
|
508
|
-
|
|
509
478
|
- **Deploy** — `baerly deploy --target=cloudflare` runs
|
|
510
479
|
`wrangler deploy --x-provision --x-auto-create` (Wrangler 4.10+)
|
|
511
480
|
to auto-create the declared R2 buckets and ship the Worker. When
|
|
@@ -532,6 +501,28 @@ from the runtime env.
|
|
|
532
501
|
the `/v1/since` log feed or from a write hook — never re-scan per
|
|
533
502
|
request.
|
|
534
503
|
|
|
504
|
+
## Maintenance
|
|
505
|
+
|
|
506
|
+
<!-- pattern-d:start -->
|
|
507
|
+
Maintenance is automatic and write-triggered. No cron, no sidecar, no scheduler, no
|
|
508
|
+
timer, no lock, no app-config knob — identical on every host. Every write runs a
|
|
509
|
+
bounded GC slice inline plus a go/no-go compaction fold bounded by a fold-size ceiling
|
|
510
|
+
whose default is safe on every tier. A size-ratio threshold means idle buckets pay
|
|
511
|
+
nothing. Concurrent folds are safe without coordination: the commit is a
|
|
512
|
+
compare-and-swap, so a fold that loses to a concurrent write is simply discarded and
|
|
513
|
+
its leftover swept by GC. On Cloudflare the fold is deferred past the response via
|
|
514
|
+
ctx.waitUntil; everywhere else it runs inline. **Reads are pure** — they never run
|
|
515
|
+
maintenance, so the published idle-reader cost bound holds.
|
|
516
|
+
|
|
517
|
+
A bucket maintains itself as long as it takes writes. A bucket served read-only does
|
|
518
|
+
not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
|
|
519
|
+
graduate once a collection is large. See docs/about/graduation.md for the per-tier
|
|
520
|
+
envelope and the BAERLY_MAINTENANCE_* operator env vars (you almost never need them).
|
|
521
|
+
|
|
522
|
+
Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
|
|
523
|
+
your own schedule. Not required for steady-state operation.
|
|
524
|
+
<!-- pattern-d:end -->
|
|
525
|
+
|
|
535
526
|
## When to graduate
|
|
536
527
|
|
|
537
528
|
baerly is designed for the small-to-medium operating point. The cost
|
|
@@ -698,7 +689,7 @@ export const NoteSchema = z.object({
|
|
|
698
689
|
|
|
699
690
|
The Zod-inferred `Note` type reflects the shape (`tags?: string[]`)
|
|
700
691
|
and call sites pick it up through `import type { Note }`.
|
|
701
|
-
JSON-merge-patch (RFC
|
|
692
|
+
JSON-merge-patch (RFC 7386) semantics apply on `update()`:
|
|
702
693
|
omitting `tags` from an update preserves the existing value;
|
|
703
694
|
passing `tags: null` deletes the field; passing `tags: []` sets
|
|
704
695
|
it to an empty array. Note that `null` is the deletion sentinel,
|
|
@@ -29,7 +29,7 @@ Common anti-patterns that compile but are wrong:
|
|
|
29
29
|
`db.collection(name).insert(row)` and `.where({ ... }).all()`.
|
|
30
30
|
- `z.string().nullable()` in a schema — `DocumentValue` excludes
|
|
31
31
|
`null`. Use `.optional()`; `null` in an update patch is the RFC
|
|
32
|
-
|
|
32
|
+
7386 deletion sentinel, not a storable value.
|
|
33
33
|
- Raw SQL strings, `WHERE` clauses, hand-built query AST — the only
|
|
34
34
|
query surface is `db.collection(...).where({ field: value }).all()` or
|
|
35
35
|
`.where(q => q.gte("count", 1))`. See **Predicates** below.
|
|
@@ -121,7 +121,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
|
|
|
121
121
|
| `tsconfig.app.json` | Client TS project (`src/web/`, DOM lib, `jsx: react-jsx`) |
|
|
122
122
|
| `tsconfig.server.json` | Node server TS project (`src/server/`, Node lib) |
|
|
123
123
|
| `baerly.config.ts` | App config — `app`, `tenant`, `target`, `collections` (schemas live here). Also exports the inferred `Note` row type used by the web client. |
|
|
124
|
-
| `.env.example` | Source of truth for env vars the Node entry reads (`BUCKET`, `AWS_*`, `
|
|
124
|
+
| `.env.example` | Source of truth for env vars the Node entry reads (`BUCKET`, `AWS_*`, the optional `BAERLY_MAINTENANCE_*` ops-plane tuners, etc.; `SHARED_SECRET` / `JWKS_URL` only needed if you adopt the "Going to production" auth recipes) |
|
|
125
125
|
|
|
126
126
|
> **`baerly.config.ts` is dual-included.** Both `tsconfig.app.json`
|
|
127
127
|
> and `tsconfig.server.json` `include` this file, so it must only
|
|
@@ -395,51 +395,6 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
|
|
|
395
395
|
`() => Promise<Credentials>` or an `@aws-sdk/credential-providers`
|
|
396
396
|
factory through the seam.
|
|
397
397
|
|
|
398
|
-
- **Maintenance loop (Node)** — `src/server/index.ts` passes a
|
|
399
|
-
`maintenance: { collections, tenants }` option to `baerlyNode`.
|
|
400
|
-
Each tick (hourly by default; override via
|
|
401
|
-
`maintenance.intervalMs`) runs one compact+GC pass per
|
|
402
|
-
`(tenant, collection)` pair against the engine's default
|
|
403
|
-
unbounded maintenance profile (folds the entire live tail; sweeps
|
|
404
|
-
every aged-out candidate the GC marks).
|
|
405
|
-
|
|
406
|
-
Opt-in via the `MAINTENANCE_COLLECTIONS` env var — a comma-
|
|
407
|
-
separated list of collection slugs:
|
|
408
|
-
|
|
409
|
-
```sh
|
|
410
|
-
MAINTENANCE_COLLECTIONS=notes
|
|
411
|
-
```
|
|
412
|
-
|
|
413
|
-
When unset, the entry passes `maintenance: undefined` to
|
|
414
|
-
`baerlyNode` and no in-process loop runs. Operators who prefer
|
|
415
|
-
external scheduling can wire a separate cron trigger (PaaS cron,
|
|
416
|
-
k8s CronJob, systemd timer) per collection that invokes
|
|
417
|
-
`runMaintenanceTick` directly — that function stays exported
|
|
418
|
-
from `@gusto/baerly-storage/node`.
|
|
419
|
-
|
|
420
|
-
The template is single-tenant by default (`tenants: [TENANT]`).
|
|
421
|
-
Multi-tenant deployments override the `tenants` array in
|
|
422
|
-
`src/server/index.ts`; the cross-product `tenants × collections`
|
|
423
|
-
defines the work per tick. A separate `runMaintenanceTick` call
|
|
424
|
-
fires per pair, and a failure on one pair logs to stderr without
|
|
425
|
-
crashing the process or blocking the others.
|
|
426
|
-
|
|
427
|
-
Maintenance emits one canonical info line per `(tenant,
|
|
428
|
-
collection)` run on stdout. Filter your log stream on
|
|
429
|
-
`"unit_of_work": "maintenance"` and read these fields:
|
|
430
|
-
|
|
431
|
-
- `compact_written` — log entries folded into the new snapshot
|
|
432
|
-
this tick (`0` when the live tail was below
|
|
433
|
-
`minEntriesToCompact`).
|
|
434
|
-
- `gc_swept` — keys deleted this tick (`0` when no candidates
|
|
435
|
-
aged out).
|
|
436
|
-
- The kernel also emits the recorder-bag fields alongside:
|
|
437
|
-
`db.compact.entries_folded_p50` / `_p99` / `_count` / `_sum`,
|
|
438
|
-
`db.manifest.lag_window_depth`, `db.orphan.candidate_count`,
|
|
439
|
-
`db.gc.entries_swept_per_second`, `db.gc.swept_total`.
|
|
440
|
-
Useful for dashboards; the four explicit fields above are
|
|
441
|
-
the at-a-glance summary.
|
|
442
|
-
|
|
443
398
|
- **Deploy** — runs anywhere `node server.js` runs. The
|
|
444
399
|
`package.json`'s `start` script is
|
|
445
400
|
`node --experimental-strip-types src/server/index.ts`. Arrange the
|
|
@@ -479,6 +434,28 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
|
|
|
479
434
|
incrementally from the `/v1/since` log feed or from a write hook —
|
|
480
435
|
never re-scan per request.
|
|
481
436
|
|
|
437
|
+
## Maintenance
|
|
438
|
+
|
|
439
|
+
<!-- pattern-d:start -->
|
|
440
|
+
Maintenance is automatic and write-triggered. No cron, no sidecar, no scheduler, no
|
|
441
|
+
timer, no lock, no app-config knob — identical on every host. Every write runs a
|
|
442
|
+
bounded GC slice inline plus a go/no-go compaction fold bounded by a fold-size ceiling
|
|
443
|
+
whose default is safe on every tier. A size-ratio threshold means idle buckets pay
|
|
444
|
+
nothing. Concurrent folds are safe without coordination: the commit is a
|
|
445
|
+
compare-and-swap, so a fold that loses to a concurrent write is simply discarded and
|
|
446
|
+
its leftover swept by GC. On Cloudflare the fold is deferred past the response via
|
|
447
|
+
ctx.waitUntil; everywhere else it runs inline. **Reads are pure** — they never run
|
|
448
|
+
maintenance, so the published idle-reader cost bound holds.
|
|
449
|
+
|
|
450
|
+
A bucket maintains itself as long as it takes writes. A bucket served read-only does
|
|
451
|
+
not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
|
|
452
|
+
graduate once a collection is large. See docs/about/graduation.md for the per-tier
|
|
453
|
+
envelope and the BAERLY_MAINTENANCE_* operator env vars (you almost never need them).
|
|
454
|
+
|
|
455
|
+
Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
|
|
456
|
+
your own schedule. Not required for steady-state operation.
|
|
457
|
+
<!-- pattern-d:end -->
|
|
458
|
+
|
|
482
459
|
## When to graduate
|
|
483
460
|
|
|
484
461
|
baerly is designed for the small-to-medium operating point. The cost
|
|
@@ -645,7 +622,7 @@ export const NoteSchema = z.object({
|
|
|
645
622
|
|
|
646
623
|
The Zod-inferred `Note` type reflects the shape (`tags?: string[]`)
|
|
647
624
|
and call sites pick it up through `import type { Note }`.
|
|
648
|
-
JSON-merge-patch (RFC
|
|
625
|
+
JSON-merge-patch (RFC 7386) semantics apply on `update()`:
|
|
649
626
|
omitting `tags` from an update preserves the existing value;
|
|
650
627
|
passing `tags: null` deletes the field; passing `tags: []` sets
|
|
651
628
|
it to an empty array. Note that `null` is the deletion sentinel,
|
|
@@ -74,12 +74,15 @@ posture needs no auth env vars; if you adopt Pattern B / C from
|
|
|
74
74
|
"Production auth" below, also set `SHARED_SECRET` (Pattern B) or
|
|
75
75
|
`JWKS_URL` + `JWT_ISSUER` + `JWT_AUDIENCE` (Pattern C). Optional:
|
|
76
76
|
`R2_ACCOUNT_ID` (switches the storage factory from `s3Storage` to
|
|
77
|
-
`r2Storage`), `AWS_REGION`, `PORT`, `TENANT`, `WEB_ROOT
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
77
|
+
`r2Storage`), `AWS_REGION`, `PORT`, `TENANT`, `WEB_ROOT`.
|
|
78
|
+
|
|
79
|
+
Maintenance (compaction + GC) is automatic and in-band: it runs
|
|
80
|
+
inline on the rare write that crosses a maintenance trigger — no env
|
|
81
|
+
var, no tick, no `setInterval`, no operator scheduler. Two ops-plane
|
|
82
|
+
env vars tune it: `BAERLY_MAINTENANCE_MAX_FOLD_BYTES` raises the
|
|
83
|
+
snapshot ceiling and `BAERLY_MAINTENANCE_DISABLE=1` is a kill switch.
|
|
84
|
+
For an explicit out-of-band sweep, call `runScheduledMaintenance`
|
|
85
|
+
from `@gusto/baerly-storage`.
|
|
83
86
|
|
|
84
87
|
After `pnpm build`, `http://localhost:8080/` serves the built SPA
|
|
85
88
|
out of `dist/client/` and `http://localhost:8080/v1/*` is the
|
|
@@ -43,6 +43,9 @@ const storage: Storage =
|
|
|
43
43
|
|
|
44
44
|
const PORT = Number(process.env["PORT"] ?? 8080);
|
|
45
45
|
|
|
46
|
-
|
|
46
|
+
// `webRoot` serves the Vite-built SPA from `dist/client/` (the
|
|
47
|
+
// `vite.config.ts` `build.outDir`) in production; `/v1/*` is handled
|
|
48
|
+
// by the kernel, everything else falls back to the SPA shell.
|
|
49
|
+
await baerlyNode({ config, storage, webRoot: "dist/client" }).listen(PORT);
|
|
47
50
|
|
|
48
51
|
console.log(`react-node listening on :${PORT}`);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gusto/create-baerly-storage",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "Scaffold a new baerly-storage app. Run via `pnpm create @gusto/baerly-storage@latest -- my-app --target=cloudflare`.",
|
|
5
5
|
"homepage": "https://github.com/Gusto/baerly-storage#readme",
|
|
6
6
|
"bugs": {
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
"directory": "packages/create-baerly-storage"
|
|
15
15
|
},
|
|
16
16
|
"bin": {
|
|
17
|
-
"create-baerly-storage": "
|
|
17
|
+
"create-baerly-storage": "dist/index.js"
|
|
18
18
|
},
|
|
19
19
|
"files": [
|
|
20
20
|
"dist"
|
|
@@ -26,6 +26,9 @@
|
|
|
26
26
|
"import": "./src/index.ts"
|
|
27
27
|
}
|
|
28
28
|
},
|
|
29
|
+
"publishConfig": {
|
|
30
|
+
"access": "restricted"
|
|
31
|
+
},
|
|
29
32
|
"dependencies": {
|
|
30
33
|
"@clack/prompts": "^1.4.0",
|
|
31
34
|
"citty": "^0.2.2",
|