bunderstack 0.5.0 → 0.6.0

package/README.md

@@ -13,7 +13,7 @@ bun add bunderstack
 import { createBunderstack } from 'bunderstack'
 import * as schema from './schema'
 
-const app = createBunderstack({
+const app = await createBunderstack({
   schema,
   auth: { emailAndPassword: { enabled: true } },
   access: {
@@ -57,9 +57,28 @@ don't throw. Then read `app.manifest`:
 process.env.BUNDERSTACK_INTROSPECT = '1'
 const { app } = await import('./src/bunderstack')
 console.log(JSON.stringify(app.manifest))
-// { dialect, tables, defaultBucket, buckets, realtime, env: { server, client } }
+// { version: 2, dialect, tables, tableMap, systemTables, background, ... }
 ```
 
+### Background runtime
+
+Declaring jobs does not start a worker. Queue jobs (`j.job()`) are processed by
+an explicit worker process:
+
+```ts
+import { app } from './bunderstack'
+
+await app.runWorker()
+```
+
+Cron tasks (`j.cron()`) are delivered by the host to
+`POST /api/_bunderstack/cron/:name`; storage maintenance uses
+`POST /api/_bunderstack/maintenance/storage-sweep`. Production requires the
+injected `BUNDERSTACK_CRON_SECRET`. Use `await app.startCronScheduler()` only
+for local standalone development. `app.manifest.background` tells Bunderhost
+whether to deploy an always-on worker (queue jobs) or only HTTP-delivered cron
+(cron-only).
+
 ## Shipping TypeScript source
 
 This package publishes raw TypeScript (`exports` point at `.ts` files). Bun

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Batteries-included backend framework for Bun: CRUD APIs, auth, file storage, realtime, tRPC, email, and validated env from a single Drizzle schema and config object.",
   "keywords": [
     "backend",
@@ -39,7 +39,8 @@
     "./typeid": "./src/typeid.ts",
     "./typeid/pg": "./src/typeid-pg.ts",
     "./env": "./src/env.ts",
-    "./trpc": "./src/trpc.ts"
+    "./trpc": "./src/trpc.ts",
+    "./cron": "./src/cron.ts"
   },
   "scripts": {
     "test": "bun test",

package/src/cron.ts

@@ -0,0 +1,2 @@
+export { cronMatches, parseCron } from './jobs/cron'
+export { signScheduleRequest, verifyScheduleRequest } from './jobs/cron-auth'

package/src/env.ts

@@ -19,6 +19,7 @@ export type BaseEnv = {
   REDIS_URL?: string
   RESEND_API_KEY?: string
   SMTP_URL?: string
+  BUNDERSTACK_CRON_SECRET?: string
 }
 
 type InferVars<T> = T extends Record<string, ZodType>
@@ -51,6 +52,8 @@ export type ValidateEnvOptions = {
   source?: Record<string, string | undefined>
   /** Dialect-aware DATABASE_URL fallback; createBunderstack passes it. */
   defaultDatabaseUrl?: string
+  /** Require the platform schedule secret for an application with cron work. */
+  cronConfigured?: boolean
 }
 
 const DEV_AUTH_SECRET = 'dev-secret-change-in-prod'
@@ -105,10 +108,14 @@ export function validateEnv<TEnv extends EnvConfigInput | undefined>(
     REDIS_URL: source.REDIS_URL,
     RESEND_API_KEY: source.RESEND_API_KEY,
     SMTP_URL: source.SMTP_URL,
+    BUNDERSTACK_CRON_SECRET: source.BUNDERSTACK_CRON_SECRET,
   }
   if (isProduction && !source.AUTH_SECRET) {
     issues.push('AUTH_SECRET: required in production')
   }
+  if (isProduction && options.cronConfigured && !source.BUNDERSTACK_CRON_SECRET) {
+    issues.push('BUNDERSTACK_CRON_SECRET: required when cron is configured in production')
+  }
   if (options.emailProvider === 'resend' && !source.RESEND_API_KEY) {
     issues.push("RESEND_API_KEY: required when email provider is 'resend'")
   }

package/src/handler.ts

@@ -8,6 +8,7 @@ interface HandlerParts {
   authHandler?: (req: Request) => Promise<Response>
   storageRouter?: Hono
   realtimeRouter?: Hono
+  cronRouter?: Hono
   trpcHandler?: (req: Request) => Promise<Response>
   rateLimit?: boolean | RateLimitConfig
 }
@@ -25,6 +26,10 @@ export function buildHandler(parts: HandlerParts): {
   app.get('/api/health', health)
   app.route('/api', parts.crudRouter)
 
+  if (parts.cronRouter) {
+    app.route('/api/_bunderstack', parts.cronRouter)
+  }
+
   if (parts.authHandler) {
     app.all('/api/auth/*', (c) => parts.authHandler!(c.req.raw))
   }

package/src/index.ts

@@ -22,10 +22,15 @@ import { buildCrudRouter } from './crud'
 import { createDb } from './db'
 import { buildHandler } from './handler'
 import { withInternalTables } from './internal-tables'
+import { Lifecycle, type LifecycleStatus } from './lifecycle'
 import {
   createJobsBuilder,
   createJobRunner,
+  buildCronRouter,
   enqueueJob,
+  runCronSlot,
+  startLocalCronScheduler,
+  startJobWorker,
   validateJobsDefs,
 } from './jobs/index'
 import type {
@@ -33,6 +38,10 @@ import type {
   EnqueueOptions,
   JobsDefs,
   JobsFacade,
+  LocalCronScheduler,
+  LocalCronSchedulerOptions,
+  StartWorkerOptions,
+  WorkerHandle,
 } from './jobs/index'
 import {
   PROVISION_INTERNALS,
@@ -48,13 +57,31 @@ import { sweepOrphans } from './storage/sweep'
 
 type AuthInstance = ReturnType<typeof createAuth>
 
+function waitForWorkerShutdown(
+  signal: AbortSignal,
+  installProcessListeners: boolean,
+): Promise<void> {
+  if (signal.aborted) return Promise.resolve()
+
+  return new Promise((resolve) => {
+    const done = () => {
+      signal.removeEventListener('abort', done)
+      if (installProcessListeners) {
+        process.removeListener('SIGINT', done)
+        process.removeListener('SIGTERM', done)
+      }
+      resolve()
+    }
+    signal.addEventListener('abort', done, { once: true })
+    if (installProcessListeners) {
+      process.once('SIGINT', done)
+      process.once('SIGTERM', done)
+    }
+  })
+}
+
 /** Default age before an unconfirmed `pending` file is treated as an orphan. */
 const DEFAULT_PENDING_TTL_MS = 30 * 60_000
-/** How often the auto-started orphan sweep runs. */
-const SWEEP_INTERVAL_MS = 10 * 60_000
-/** How often the in-process job worker polls for claimable jobs. */
-const JOBS_POLL_INTERVAL_MS = 1000
-
 /**
  * Public storage facade exposed as `app.storage`. Object-level operations live
  * on the per-bucket adapters; this surface offers the app-wide deletes that
@@ -67,12 +94,19 @@ export interface StorageFacade {
   bucket(name: string): StorageAdapter | undefined
   /**
    * Reap stale `pending` uploads older than `olderThanMs` (default 30m). Runs
-   * automatically on an interval; exposed for manual/test invocation. Returns
+   * only when explicitly invoked by the host or local scheduler. Returns
    * the count reaped.
    */
   sweep(olderThanMs?: number): Promise<number>
 }
 
+export type AppStartWorkerOptions = Omit<StartWorkerOptions, 'tick'>
+export type AppRunWorkerOptions = AppStartWorkerOptions
+export type AppStartCronSchedulerOptions = Pick<
+  LocalCronSchedulerOptions,
+  'onError'
+>
+
 /** Bucket names declared in a storage config; `string` when unknowable. */
 export type BucketNamesOf<TStorage> = TStorage extends {
   buckets: infer B extends Record<string, unknown>
@@ -102,6 +136,16 @@ export type BunderstackApp<
   email: EmailFacade
   /** Job queue facade; always present — enqueue throws when jobs aren't configured. */
   jobs: JobsFacade<TJobsDefs extends JobsDefs ? TJobsDefs : Record<never, never>>
+  startWorker(options?: AppStartWorkerOptions): Promise<WorkerHandle>
+  /** Run a queue worker until aborted, then close the application. */
+  runWorker(options?: AppRunWorkerOptions): Promise<void>
+  /** Start local delivery for declared cron tasks (for development only). */
+  startCronScheduler(
+    options?: AppStartCronSchedulerOptions,
+  ): Promise<LocalCronScheduler>
+  close(): Promise<void>
+  readonly status: LifecycleStatus
+  readonly signal: AbortSignal
   /** Deploy-time introspection: what this app needs provisioned. */
   manifest: BunderstackManifest
   /**
@@ -214,12 +258,21 @@ export async function createBunderstack<
   >
 > {
   const dialect = detectDialect(options.schema)
+  const jobsDefs: JobsDefs | undefined = options.jobs
+    ? typeof options.jobs === 'function'
+      ? options.jobs(createJobsBuilder<TSchema, ValidatedEnv<TEnv>>())
+      : (options.jobs as JobsDefs)
+    : undefined
+  if (jobsDefs) validateJobsDefs(jobsDefs)
   // Env is validated FIRST: the app refuses to boot on missing/invalid vars,
   // and everything downstream (config, email, trpc ctx) consumes the result.
   const env = validateEnv(options.env, {
     emailProvider: emailProviderTag(options.email),
     defaultDatabaseUrl:
       dialect === 'pg' ? 'file:./data.pglite' : 'file:./data.db',
+    // Storage orphan cleanup is also a signed platform schedule, so every
+    // production app has scheduled delivery even without user-defined cron.
+    cronConfigured: true,
   })
   const config = resolveConfig(options, env)
   // Introspection mode (BUNDERSTACK_INTROSPECT=1): deployment platforms import
@@ -269,7 +322,7 @@ export async function createBunderstack<
     ? redisUrl
       ? createRedisRealtimeBroker({
           access: resolvedAccess,
-          redis: (() => {
+          redis: () => {
             // Redis pub/sub requires a dedicated connection (subscribe puts the client into
             // a restricted state). We use one client for commands and a second for subscribe.
             const cmdClient = new Bun.RedisClient(redisUrl)
@@ -286,8 +339,12 @@ export async function createBunderstack<
                 cmdClient.ltrim(key, start, stop),
               lrange: (key: string, start: number, stop: number) =>
                 cmdClient.lrange(key, start, stop),
+              close: () => {
+                cmdClient.close()
+                subClient.close()
+              },
             }
-          })(),
+          },
           bufferSize: realtimeBufferSize,
         })
       : createRealtimeBroker({
@@ -311,6 +368,8 @@ export async function createBunderstack<
       })
     : undefined
   const registry = createBucketStorages(config.storage)
+  const lifecycle = new Lifecycle()
+  if (broker) lifecycle.add(() => broker.close())
   const storageRouter = buildBucketStorageRouter({
     registry,
     db,
@@ -334,18 +393,6 @@ export async function createBunderstack<
       return sweepOrphans(registry, db, olderThanMs)
     },
   }
-  // Auto-reap orphaned `pending` uploads. `unref()` keeps this from holding the
-  // process (and test runners) open.
-  const sweepTimer = setInterval(() => {
-    void sweepOrphans(registry, db, DEFAULT_PENDING_TTL_MS).catch(() => {})
-  }, SWEEP_INTERVAL_MS)
-  sweepTimer.unref?.()
-  const jobsDefs: JobsDefs | undefined = options.jobs
-    ? typeof options.jobs === 'function'
-      ? options.jobs(createJobsBuilder<TSchema, ValidatedEnv<TEnv>>())
-      : (options.jobs as JobsDefs)
-    : undefined
-  if (jobsDefs) validateJobsDefs(jobsDefs)
   const jobRunner = jobsDefs
     ? createJobRunner({
         db,
@@ -361,8 +408,6 @@ export async function createBunderstack<
         )
       }
       const result = await enqueueJob(db, jobsDefs, name, input, opts)
-      // Wake the local worker so same-process jobs start without poll latency.
-      if (jobRunner && !introspect) void jobRunner.tick().catch(() => {})
       return result
     },
     tick(now?: number) {
@@ -370,11 +415,78 @@ export async function createBunderstack<
     },
   }
   if (jobRunner) jobRunner.setJobsFacade(jobs)
-  if (jobRunner && !introspect) {
-    const jobsTimer = setInterval(() => {
-      void jobRunner.tick().catch(() => {})
-    }, JOBS_POLL_INTERVAL_MS)
-    jobsTimer.unref?.()
+  const startWorker = async (
+    options: AppStartWorkerOptions = {},
+  ): Promise<WorkerHandle> => {
+    if (!jobRunner) {
+      throw new Error('[bunderstack] no queue jobs configured')
+    }
+    if (lifecycle.status !== 'ready') {
+      throw new Error('[bunderstack] application lifecycle is closed')
+    }
+    const signal = options.signal
+      ? AbortSignal.any([lifecycle.signal, options.signal])
+      : lifecycle.signal
+    const handle = startJobWorker({
+      ...options,
+      signal,
+      tick: (now) => jobRunner.tick(now),
+    })
+    const unregister = lifecycle.add(() => handle.close())
+    void handle.closed.finally(unregister)
+    return handle
+  }
+  const startCronScheduler = async (
+    options: AppStartCronSchedulerOptions = {},
+  ): Promise<LocalCronScheduler> => {
+    const cron = Object.entries(jobsDefs ?? {}).flatMap(([name, definition]) =>
+      definition.kind === 'cron'
+        ? [{ name, schedule: definition.schedule }]
+        : [],
+    )
+    if (cron.length === 0) {
+      throw new Error('[bunderstack] no cron tasks configured')
+    }
+    if (lifecycle.status !== 'ready') {
+      throw new Error('[bunderstack] application lifecycle is closed')
+    }
+    const scheduler = startLocalCronScheduler({
+      cron,
+      onError: options.onError,
+      runSlot: async (name, slot) => {
+        await runCronSlot({
+          db,
+          defs: jobsDefs!,
+          ctx: { db: userDb, env, email, storage },
+          name,
+          slot,
+          now: Date.now(),
+        })
+      },
+    })
+    const unregister = lifecycle.add(() => scheduler.close())
+    try {
+      await scheduler.tick()
+    } catch (error) {
+      unregister()
+      await scheduler.close()
+      throw error
+    }
+    return scheduler
+  }
+  const runWorker = async (
+    options: AppRunWorkerOptions = {},
+  ): Promise<void> => {
+    const handle = await startWorker(options)
+    try {
+      const signal = options.signal
+        ? AbortSignal.any([lifecycle.signal, options.signal])
+        : lifecycle.signal
+      await waitForWorkerShutdown(signal, !options.signal)
+    } finally {
+      await handle.close()
+      await lifecycle.close()
+    }
   }
   const trpcRouter: AnyRouter | undefined =
     typeof options.trpc === 'function'
@@ -396,12 +508,23 @@ export async function createBunderstack<
           }),
         })
     : undefined
+  const cronRouter =
+    env.BUNDERSTACK_CRON_SECRET
+      ? buildCronRouter({
+          db,
+          defs: jobsDefs ?? {},
+          ctx: { db: userDb, env, email, storage },
+          secret: env.BUNDERSTACK_CRON_SECRET,
+          storage,
+        })
+      : undefined
   const { handler, router } = buildHandler({
     crudRouter,
     authHandler: (req) => auth.handler(req),
     storageRouter,
     realtimeRouter,
     trpcHandler,
+    cronRouter,
     rateLimit: options.rateLimit,
   })
 
@@ -425,6 +548,14 @@ export async function createBunderstack<
     // narrows `enqueue` per-app from the declared job defs — same relationship
     // as `userDb` above.
     jobs: jobs as never,
+    startWorker,
+    runWorker,
+    startCronScheduler,
+    close: () => lifecycle.close(),
+    get status() {
+      return lifecycle.status
+    },
+    signal: lifecycle.signal,
     trpcRouter,
     manifest: buildManifest({
       schema: options.schema,
@@ -461,7 +592,7 @@ export type {
 export { validateEnv, createClientEnv, BunderstackEnvError } from './env'
 export type { EnvConfigInput, BaseEnv, ValidatedEnv } from './env'
 export { buildManifest } from './manifest'
-export type { BunderstackManifest, ManifestEnvVar, ManifestJob } from './manifest'
+export type { BunderstackManifest, ManifestEnvVar } from './manifest'
 export { createEmail } from './email'
 export type {
   EmailMessage,
@@ -471,15 +602,30 @@ export type {
 } from './email'
 export { createTRPC } from './trpc'
 export type { BunderstackTRPC, TRPCContext } from './trpc'
-export { createJobsBuilder } from './jobs/index'
+export {
+  createJobsBuilder,
+  signScheduleRequest,
+  verifyScheduleRequest,
+} from './jobs/index'
 export type {
   BunderstackJobsBuilder,
+  BackgroundDefinition,
+  BackgroundDefs,
+  CronDefinition,
+  CronInvocation,
   EnqueueOptions,
   JobContext,
   JobDefinition,
   JobsDefs,
   JobsFacade,
   JobsRuntimeFacade,
+  QueueJobDefinition,
+  QueueJobKeys,
+  LocalCronScheduler,
+  LocalCronSchedulerOptions,
+  RunWorkerOptions,
+  StartWorkerOptions,
+  WorkerHandle,
 } from './jobs/index'
 export {
   defineAccess,

package/src/internal-tables-pg.ts

@@ -66,3 +66,21 @@ export const bunderstackJobsPg = pgTable(
     uniqueIndex('bjq_dedupe').on(t.type, t.dedupeKey),
   ],
 )
+
+export const bunderstackCronRunsPg = pgTable(
+  '_bunderstack_cron_runs',
+  {
+    taskId: text('task_id').notNull(),
+    scheduledAt: bigint('scheduled_at', { mode: 'number' }).notNull(),
+    status: text('status').notNull(),
+    attempts: integer('attempts').notNull().default(0),
+    lockedUntil: bigint('locked_until', { mode: 'number' }),
+    lastError: text('last_error'),
+    startedAt: bigint('started_at', { mode: 'number' }),
+    finishedAt: bigint('finished_at', { mode: 'number' }),
+  },
+  (t) => [
+    primaryKey({ columns: [t.taskId, t.scheduledAt] }),
+    index('bcr_claim').on(t.status, t.lockedUntil),
+  ],
+)

package/src/internal-tables.ts

@@ -12,6 +12,7 @@ import {
 import { detectDialect } from './dialect'
 import {
   bunderstackFilesPg,
+  bunderstackCronRunsPg,
   bunderstackIdempotencyPg,
   bunderstackJobsPg,
 } from './internal-tables-pg'
@@ -73,22 +74,43 @@ export const bunderstackJobs = sqliteTable(
   ],
 )
 
+export const bunderstackCronRuns = sqliteTable(
+  '_bunderstack_cron_runs',
+  {
+    taskId: text('task_id').notNull(),
+    scheduledAt: integer('scheduled_at').notNull(),
+    status: text('status').notNull(),
+    attempts: integer('attempts').notNull().default(0),
+    lockedUntil: integer('locked_until'),
+    lastError: text('last_error'),
+    startedAt: integer('started_at'),
+    finishedAt: integer('finished_at'),
+  },
+  (t) => [
+    primaryKey({ columns: [t.taskId, t.scheduledAt] }),
+    index('bcr_claim').on(t.status, t.lockedUntil),
+  ],
+)
+
 export const INTERNAL_TABLES = {
   bunderstackFiles,
   bunderstackIdempotency,
   bunderstackJobs,
+  bunderstackCronRuns,
 } as const
 
 export const INTERNAL_TABLE_NAMES: ReadonlySet<string> = new Set([
   'bunderstack_file_meta',
   '_bunderstack_idempotency',
   '_bunderstack_jobs',
+  '_bunderstack_cron_runs',
 ])
 
 export const INTERNAL_TABLES_PG = {
   bunderstackFiles: bunderstackFilesPg,
   bunderstackIdempotency: bunderstackIdempotencyPg,
   bunderstackJobs: bunderstackJobsPg,
+  bunderstackCronRuns: bunderstackCronRunsPg,
 } as const
 
 // Both dialect twins count as "ours" for the re-export identity check.
@@ -99,6 +121,7 @@ const INTERNAL_TABLE_CANDIDATES = new Map<string, readonly unknown[]>([
     [bunderstackIdempotency, bunderstackIdempotencyPg],
   ],
   [getTableName(bunderstackJobs), [bunderstackJobs, bunderstackJobsPg]],
+  [getTableName(bunderstackCronRuns), [bunderstackCronRuns, bunderstackCronRunsPg]],
 ])
 
 /** Internal file-meta table matching the db's dialect. */
@@ -116,6 +139,11 @@ export function jobsTableFor(db: unknown) {
   return is(db, PgDatabase) ? bunderstackJobsPg : bunderstackJobs
 }
 
+/** Internal cron-run table matching the db's dialect. */
+export function cronRunsTableFor(db: unknown) {
+  return is(db, PgDatabase) ? bunderstackCronRunsPg : bunderstackCronRuns
+}
+
 export function withInternalTables<TSchema extends Record<string, unknown>>(
   schema: TSchema,
 ): TSchema & typeof INTERNAL_TABLES {

package/src/jobs/cron-auth.ts

@@ -0,0 +1,28 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+function canonical(taskId: string, slot: number): string {
+  return `${taskId}\n${slot}`
+}
+
+export function signScheduleRequest(
+  secret: string,
+  taskId: string,
+  slot: number,
+): string {
+  const digest = createHmac('sha256', secret)
+    .update(canonical(taskId, slot))
+    .digest('hex')
+  return `sha256=${digest}`
+}
+
+export function verifyScheduleRequest(
+  secret: string,
+  taskId: string,
+  slot: number,
+  signature: string,
+): boolean {
+  if (!/^sha256=[0-9a-f]{64}$/.test(signature)) return false
+  const expected = Buffer.from(signScheduleRequest(secret, taskId, slot))
+  const received = Buffer.from(signature)
+  return timingSafeEqual(expected, received)
+}