@lunora/runtime 1.0.0-alpha.77 → 1.0.0-alpha.78

package/README.md

@@ -103,6 +103,44 @@ export const refreshProducts = action.action(async ({ ctx }) => {
 
 The `ctx.cache` binding is only available in **action** handlers (not query/mutation), because actions run in the Worker while queries/mutations run inside the Durable Object. Cache header declarations on `httpRoute` (`.cacheControl()`, `.cacheTag()`, `.vary()`) are attached by `@lunora/server` before the response leaves the handler.
 
+### Scheduled backups
+
+The worker can take its own NDJSON snapshots on a Cron Trigger, writing them to an R2 bucket in your account — the same format and key layout `lunora backup list|restore` reads, so cron-written and hand-taken snapshots share one history.
+
+```ts
+interface BackupEnv extends Env {
+    BACKUPS: R2Bucket;
+    LUNORA_ADMIN_TOKEN: string;
+}
+
+let worker: LunoraWorker | null = null;
+
+const build = (env: BackupEnv): LunoraWorker =>
+    (worker ??= createWorker({
+        adminToken: env.LUNORA_ADMIN_TOKEN,
+        backupCron: "0 3 * * *", // must match an entry in wrangler `triggers.crons`, verbatim
+        backupRetain: 14,
+        backupStore: env.BACKUPS, // a bound R2 bucket satisfies `BackupStore`
+        queryCoordinator, // the export walks every shard through it
+        shardDO: env.SHARD,
+    }));
+
+export default {
+    fetch: (request: Request, env: BackupEnv, ctx: ExecutionContext) => build(env).fetch(request, env, ctx),
+    scheduled: (controller: ScheduledController, env: BackupEnv, ctx: ExecutionContext) => build(env).scheduled(controller, env, ctx),
+};
+```
+
+Five things are easy to get wrong, and four of them fail silently:
+
+- **`scheduled` must be wired.** `createWorker` returns it, but a worker that only exports `fetch` never runs a backup, and nothing reports that.
+- **`backupCron` is compared verbatim** against the firing expression. `"0 3 * * *"` and `"0  3 * * *"` are different strings, and the mismatch is silent — the trigger fires, no backup runs.
+- **`backupStore`, `adminToken` and `queryCoordinator` are all required.** The snapshot is assembled by walking every shard's admin export route, so it needs the coordinator to reach them and a token to authorize itself. Missing any one throws `BACKUP_NOT_CONFIGURED` from inside the scheduled handler — the one failure here that is loud.
+- **`backupRetain` does not delete anything.** It is a reporting window: each run logs how many snapshots sit past the newest N and tells you to run `lunora backup prune`, which is the only thing that removes a backup. A bucket therefore grows until you prune it.
+- **The snapshot is built in memory.** It is capped at 24 MiB and refuses past it, writing nothing — narrow it with `backupTables`, or take that snapshot off-platform with `lunora backup create --bucket`.
+
+`backupPrefix` (default `"backups/"`) sets the key prefix, and `backupTables` narrows the snapshot to an allowlist. The 24 MiB cap is smaller than the 32 MiB one on `lunora backup create --bucket`, which travels through the checksum-verified upload route instead of being held in an isolate.
+
 ## Related
 
 - [`@lunora/do`](https://www.npmjs.com/package/@lunora/do) — the `ShardDO` / `SessionDO` Durable Objects this runtime routes to.

package/dist/index.d.mts

@@ -3609,9 +3609,16 @@ interface WorkerOptions {
    */
   backupPrefix?: string;
   /**
-   * Retention bound for scheduled backups: keep only the newest N snapshots
-   * under {@link WorkerOptions.backupPrefix}, pruning older NDJSON objects and
-   * their manifests after each run. Omit (or `0`) to keep every backup.
+   * Retention window for scheduled backups: the newest N snapshots under
+   * {@link WorkerOptions.backupPrefix} are the ones considered current. Omit
+   * (or `0`) to treat every backup as current.
+   *
+   * **Reporting only — this never deletes.** Each run logs how many snapshots
+   * sit past the window and points at `lunora backup prune`, which is the only
+   * thing that removes one (and which confirms first). A bucket therefore
+   * grows until someone prunes it. Said explicitly because the name reads like
+   * the opposite, and because a backup deleted by a cron nobody was watching
+   * is not a failure mode this should ever have.
    */
   backupRetain?: number;
   /**

package/dist/index.d.ts

@@ -3609,9 +3609,16 @@ interface WorkerOptions {
    */
   backupPrefix?: string;
   /**
-   * Retention bound for scheduled backups: keep only the newest N snapshots
-   * under {@link WorkerOptions.backupPrefix}, pruning older NDJSON objects and
-   * their manifests after each run. Omit (or `0`) to keep every backup.
+   * Retention window for scheduled backups: the newest N snapshots under
+   * {@link WorkerOptions.backupPrefix} are the ones considered current. Omit
+   * (or `0`) to treat every backup as current.
+   *
+   * **Reporting only — this never deletes.** Each run logs how many snapshots
+   * sit past the window and points at `lunora backup prune`, which is the only
+   * thing that removes one (and which confirms first). A bucket therefore
+   * grows until someone prunes it. Said explicitly because the name reads like
+   * the opposite, and because a backup deleted by a cron nobody was watching
+   * is not a failure mode this should ever have.
    */
   backupRetain?: number;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/runtime",
-  "version": "1.0.0-alpha.77",
+  "version": "1.0.0-alpha.78",
   "description": "Lunora Worker runtime: the RPC router, shard resolver, and query coordinator",
   "keywords": [
     "cloudflare",
@@ -46,9 +46,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/bindings": "1.0.0-alpha.39",
+    "@lunora/bindings": "1.0.0-alpha.40",
     "@lunora/errors": "1.0.0-alpha.24",
-    "@lunora/platform": "1.0.0-alpha.18"
+    "@lunora/platform": "1.0.0-alpha.19"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"