bunderstack 0.15.2 → 0.16.0

package/README.md

@@ -87,6 +87,10 @@ import { app } from './bunderstack'
 await app.runWorker()
 ```
 
+Most applications need none of this: background work runs in-process by
+default. Set `BUNDERSTACK_ROLE` to `web` or `worker` to split it across
+processes without changing code.
+
 If a queue handler calls `ctx.realtime.publish()`, the web and worker processes
 must share a realtime transport. Configure `REDIS_URL` (or
 `realtime: { redis: "redis://..." }`). `realtime: true` without Redis uses a
@@ -114,13 +118,9 @@ REDIS_URL=redis://localhost:6379 bun src/server.ts
 REDIS_URL=redis://localhost:6379 bun src/worker.ts
 ```
 
-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).
+Cron tasks (`j.cron()`) are materialized as job rows keyed by their slot, so
+they run through the same loop, retries, and timeouts as queue jobs. There is
+no separate cron process and no signed dispatch endpoint.
 
 ### Publishing custom writes to realtime
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.15.2",
+  "version": "0.16.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",
@@ -53,6 +53,7 @@
   },
   "scripts": {
     "test": "bun test",
+    "typecheck": "tsc --noEmit",
     "dev": "bun --hot ../../examples/standalone/server.ts",
     "db:push": "drizzle-kit push",
     "db:migrate": "drizzle-kit migrate"

package/src/access.ts

@@ -103,6 +103,24 @@ export type ResolvedTableAccess = {
 
 export type ResolvedAccess = Map<string, ResolvedTableAccess>
 
+/**
+ * Look up a table's resolved access by its physical table name.
+ *
+ * `ResolvedAccess` is keyed by schema export name, not table name, so every
+ * consumer that starts from a physical name needs this scan. It lives here so
+ * CRUD, realtime, and route validation cannot drift apart on which tables they
+ * consider enabled.
+ */
+export function tableEntryForName(
+  access: ResolvedAccess,
+  tableName: string,
+): ResolvedTableAccess | undefined {
+  for (const entry of access.values()) {
+    if (entry.tableName === tableName) return entry
+  }
+  return undefined
+}
+
 const DEFAULT_READONLY = [
   'id',
   'createdAt',

package/src/config.ts

@@ -20,29 +20,10 @@ export type BetterAuthConfig = Omit<
   'database'
 >
 
-export const BunderstackOptionsSchema = z.object({
-  schema: z.record(z.string(), z.unknown()),
-  access: z.record(z.string(), z.unknown()).optional(),
-  database: z
-    .object({
-      adapter: z.unknown(),
-      url: z.string().optional(),
-      authToken: z.string().optional(),
-      migrations: z.string().optional(),
-    })
-    .optional(),
-  auth: z.record(z.string(), z.unknown()).optional(),
-  // Loose: bucket access/scope hold functions that can't survive strict zod
-  // (mirrors how `access` is loose). Resolution happens in resolveBuckets.
-  storage: z.unknown().optional(),
-  // Loose: holds zod schemas. Validation happens in validateEnv.
-  env: z.unknown().optional(),
-  // Loose: provider may be a function/adapter. Resolution happens in createEmail.
-  email: z.unknown().optional(),
-  // Loose: a tRPC router or builder callback. Resolved in createBunderstack.
-  trpc: z.unknown().optional(),
-  // Loose: holds handler functions and zod schemas. Resolved in createBunderstack.
-  jobs: z.unknown().optional(),
+// Only the union-shaped options need runtime validation: they are the ones a
+// JavaScript caller can plausibly get wrong in a way that fails confusingly
+// downstream. Everything else is either typed-only or read raw from `options`.
+const RuntimeOptionsSchema = z.object({
   rateLimit: z
     .union([
       z.boolean(),
@@ -81,19 +62,7 @@ export type BunderstackConfig<
     | StorageConfigInput
     | undefined,
   TEnv extends EnvConfigInput | undefined = EnvConfigInput | undefined,
-> = Omit<
-  z.input<typeof BunderstackOptionsSchema>,
-  | 'schema'
-  | 'access'
-  | 'auth'
-  | 'authResolver'
-  | 'storage'
-  | 'env'
-  | 'email'
-  | 'trpc'
-  | 'jobs'
-  | 'database'
-> & {
+> = {
   schema: TSchema
   access?: TAccess
   database: {
@@ -110,11 +79,20 @@ export type BunderstackConfig<
   authResolver?: AuthSessionResolver
   storage?: TStorage
   env?: TEnv
+  /**
+   * Stand-in for `process.env`. Feeds both env validation and platform
+   * overrides, so tests and embedders have one injection point instead of
+   * three.
+   */
+  processEnv?: Record<string, string | undefined>
+  background?: { autoStart?: boolean }
   email?: EmailConfigInput
-  // `trpc` is intentionally NOT declared here: createBunderstack intersects
-  // its own inference-friendly `trpc` declaration (router | builder callback)
-  // so the callback's `t` parameter gets contextual typing. `jobs` follows the
-  // same pattern (defs map | builder callback receiving `j`).
+  /**
+   * Custom Hono routes, mounted at root ahead of bunderstack's own. Declared as
+   * a callback because routes in a separate file cannot import the app that is
+   * still being constructed — the same reason `trpc` takes a builder.
+   */
+  routes?: (ctx: never) => unknown
   rateLimit?: boolean | RateLimitConfig
   idempotency?: boolean | IdempotencyConfig
   realtime?:
@@ -154,7 +132,7 @@ export function resolveConfig<TSchema extends Record<string, unknown>>(
     string | undefined
   >,
 ): ResolvedConfig {
-  const parsed = BunderstackOptionsSchema.parse(options)
+  const parsed = RuntimeOptionsSchema.parse(options)
   // Self-validate when the caller didn't pass a pre-validated env, so
   // resolveConfig stays usable standalone.
   const resolvedEnv =
@@ -173,14 +151,14 @@ export function resolveConfig<TSchema extends Record<string, unknown>>(
       adapter,
       url:
         platformSource['BUNDERSTACK_DATABASE_URL'] ??
-        parsed.database?.url ??
+        options.database?.url ??
         resolvedEnv.DATABASE_URL ??
         defaultUrl,
       authToken:
         platformSource['BUNDERSTACK_DATABASE_AUTH_TOKEN'] ??
-        parsed.database?.authToken ??
+        options.database?.authToken ??
         resolvedEnv.DATABASE_AUTH_TOKEN,
-      migrations: parsed.database?.migrations ?? './migrations',
+      migrations: options.database?.migrations ?? './migrations',
     },
     auth: (() => {
       const authInput = options.auth ?? {}

package/src/cron.ts

@@ -1,2 +1,3 @@
 export { cronMatches, parseCron } from './jobs/cron'
-export { signScheduleRequest, verifyScheduleRequest } from './jobs/cron-auth'
+export { floorSlot, slotsDue, CRON_PREFIX, SLOT_MS } from './jobs/slots'
+export type { CatchUp } from './jobs/slots'

package/src/crud.ts

@@ -14,6 +14,7 @@ import {
   type AuthSessionResolver,
   type CrudOperation,
   type ResolvedAccess,
+  tableEntryForName,
   type ResolvedTableAccess,
   type ScopeMap,
   type ScopeResolver,
@@ -38,15 +39,6 @@ export type CrudRouterOptions<
   realtime?: RealtimeFacade<TSchema>
 }
 
-function tableEntryForName(
-  access: ResolvedAccess,
-  tableName: string,
-): ResolvedTableAccess | undefined {
-  for (const entry of access.values()) {
-    if (entry.tableName === tableName) return entry
-  }
-  return undefined
-}
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value)

package/src/env.ts

@@ -10,6 +10,10 @@ export type EnvConfigInput = {
   runtimeEnv?: Record<string, unknown>
 }
 
+export type BunderstackRole = 'all' | 'web' | 'worker'
+
+const ROLES: readonly BunderstackRole[] = ['all', 'web', 'worker']
+
 /** Vars bunderstack itself consumes, always validated. */
 export type BaseEnv = {
   NODE_ENV?: string
@@ -19,7 +23,7 @@ export type BaseEnv = {
   REDIS_URL?: string
   RESEND_API_KEY?: string
   SMTP_URL?: string
-  BUNDERSTACK_CRON_SECRET?: string
+  BUNDERSTACK_ROLE: BunderstackRole
 }
 
 type InferVars<T> =
@@ -53,8 +57,6 @@ 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'
@@ -109,18 +111,17 @@ 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,
+    BUNDERSTACK_ROLE: (source.BUNDERSTACK_ROLE ?? 'all') as BunderstackRole,
   }
   if (isProduction && !source.AUTH_SECRET) {
     issues.push('AUTH_SECRET: required in production')
   }
   if (
-    isProduction &&
-    options.cronConfigured &&
-    !source.BUNDERSTACK_CRON_SECRET
+    source.BUNDERSTACK_ROLE !== undefined &&
+    !ROLES.includes(source.BUNDERSTACK_ROLE as BunderstackRole)
   ) {
     issues.push(
-      'BUNDERSTACK_CRON_SECRET: required when cron is configured in production',
+      `BUNDERSTACK_ROLE: must be one of ${ROLES.join(', ')} (got "${String(source.BUNDERSTACK_ROLE)}")`,
     )
   }
   if (options.emailProvider === 'resend' && !source.RESEND_API_KEY) {

package/src/handler.ts

@@ -4,11 +4,11 @@ import { Hono } from 'hono'
 import { createRateLimiter, type RateLimitConfig } from './rate-limit'
 
 interface HandlerParts {
+  customRouter?: Hono
   crudRouter: Hono
   authHandler?: (req: Request) => Promise<Response>
   storageRouter?: Hono
   realtimeRouter?: Hono
-  cronRouter?: Hono
   trpcHandler?: (req: Request) => Promise<Response>
   rateLimit?: boolean | RateLimitConfig
 }
@@ -20,16 +20,16 @@ export function buildHandler(parts: HandlerParts): {
   const app = new Hono()
   const checkRateLimit = createRateLimiter(parts.rateLimit)
 
+  // Registered ahead of everything so custom routes can sit in front of the
+  // core app. Collisions are rejected at construction, not silently shadowed.
+  if (parts.customRouter) app.route('/', parts.customRouter)
+
   const health = (c: { json: (data: unknown) => Response }) =>
     c.json({ status: 'ok' })
   app.get('/health', health)
   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

@@ -4,6 +4,8 @@ import type { Hono as HonoType } from 'hono'
 
 import { fetchRequestHandler } from '@trpc/server/adapters/fetch'
 
+import { getTableName, isTable } from 'drizzle-orm'
+
 import type { TableAccessInput } from './access'
 import type { DbFor } from './db'
 import type {
@@ -11,15 +13,17 @@ import type {
   EnqueueOptions,
   JobsDefs,
   JobsFacade,
-  LocalCronScheduler,
-  LocalCronSchedulerOptions,
   StartWorkerOptions,
   WorkerHandle,
 } from './jobs/index'
 import type { StorageConfigInput } from './storage/buckets'
 import type { StorageAdapter } from './storage/index'
 
-import { resolveAccessUser, validateAndResolveAccess } from './access'
+import {
+  resolveAccessUser,
+  tableEntryForName,
+  validateAndResolveAccess,
+} from './access'
 import {
   createAuth,
   toAuthSessionResolver,
@@ -37,10 +41,7 @@ import { withInternalTables } from './internal-tables'
 import {
   createJobsBuilder,
   createJobRunner,
-  buildCronRouter,
   enqueueJob,
-  runCronSlot,
-  startLocalCronScheduler,
   startJobWorker,
   validateJobsDefs,
 } from './jobs/index'
@@ -57,6 +58,7 @@ import {
 } from './realtime/facade'
 import { createRealtimeBroker, buildRealtimeRouter } from './realtime/index'
 import { createRedisRealtimeBroker } from './realtime/redis'
+import { createRouteContext, validateCustomRoutes } from './routes'
 import { deleteFileWithDerivatives } from './storage/delete'
 import { deleteFileMetaRow, insertReadyFile } from './storage/file-meta'
 import { createBucketStorages } from './storage/registry'
@@ -64,7 +66,8 @@ import { buildBucketStorageRouter } from './storage/router'
 import { sweepOrphans } from './storage/sweep'
 import { createTRPC, type BunderstackTRPC } from './trpc'
 
-type AuthInstance = ReturnType<typeof createAuth>
+export type AuthInstance = ReturnType<typeof createAuth>
+
 
 function waitForWorkerShutdown(
   signal: AbortSignal,
@@ -138,11 +141,6 @@ export type AppRunWorkerOptions = AppStartWorkerOptions & {
    */
   allowProcessLocalRealtime?: boolean
 }
-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>
@@ -178,11 +176,9 @@ export type BunderstackApp<
   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>
+  /** True when this process is running the background tick loop. */
+  readonly backgroundRunning: boolean
   readonly status: LifecycleStatus
   readonly signal: AbortSignal
   /** Deploy-time introspection: what this app needs provisioned. */
@@ -345,11 +341,9 @@ export async function createBunderstack<
     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,
+    source: options.processEnv,
   })
-  const config = resolveConfig(options, env)
+  const config = resolveConfig(options, env, options.processEnv)
   // Adapters use Drizzle mocks during deployment introspection, so the database
   // and Redis below never touch external services.
   const introspect = process.env.BUNDERSTACK_INTROSPECT === '1'
@@ -518,25 +512,41 @@ export async function createBunderstack<
         })
       },
     }
-    const jobRunner = jobsDefs
+    const storageConfigured = Boolean(options.storage)
+    // The storage sweep used to be a hardcoded maintenance route. It is an
+    // ordinary cron now, so it inherits retries, timeout and onFailed.
+    const resolvedDefs: JobsDefs | undefined = storageConfigured
+      ? {
+          ...(jobsDefs ?? {}),
+          'bunderstack:storage-sweep': {
+            kind: 'cron',
+            schedule: '0 4 * * *',
+            handler: async () => {
+              await storage.sweep()
+            },
+          },
+        }
+      : jobsDefs
+
+    const jobRunner = resolvedDefs
       ? createJobRunner({
           db,
-          defs: jobsDefs,
+          defs: resolvedDefs,
           ctx: { db: userDb, env, email, storage, realtime },
         })
       : undefined
     const jobs = {
       async enqueue(name: string, input?: unknown, opts?: EnqueueOptions) {
-        if (!jobsDefs) {
+        if (!resolvedDefs) {
           throw new Error(
             '[bunderstack] no jobs configured — add a `jobs` key to createBunderstack',
           )
         }
-        const result = await enqueueJob(db, jobsDefs, name, input, opts)
+        const result = await enqueueJob(db, resolvedDefs, name, input, opts)
         return result
       },
       tick(now?: number) {
-        return jobRunner ? jobRunner.tick(now) : Promise.resolve()
+        return jobRunner ? jobRunner.tick(now) : Promise.resolve({ claimed: 0, ran: 0, failed: 0 })
       },
     }
     if (jobRunner) jobRunner.setJobsFacade(jobs)
@@ -558,54 +568,16 @@ export async function createBunderstack<
       const handle = startJobWorker({
         ...options,
         signal,
-        tick: (now) => jobRunner.tick(now),
+        // The runtime loop only cares that a tick completed; TickResult is for
+        // callers that invoke tick() directly.
+        tick: async (now) => {
+          await jobRunner.tick(now)
+        },
       })
       const unregister = lifecycle.add(() => handle.close())
       void handle.closed.finally(unregister)
       return handle
     }
-    const startCronScheduler = async (
-      options: AppStartCronSchedulerOptions = {},
-    ): Promise<LocalCronScheduler> => {
-      if (introspect) {
-        return { tick: async () => {}, close: async () => {} }
-      }
-      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, realtime },
-            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> => {
@@ -655,25 +627,52 @@ export async function createBunderstack<
             }),
           })
       : undefined
-    const cronRouter = env.BUNDERSTACK_CRON_SECRET
-      ? buildCronRouter({
-          db,
-          defs: jobsDefs ?? {},
-          ctx: { db: userDb, env, email, storage, realtime },
-          secret: env.BUNDERSTACK_CRON_SECRET,
-          storage,
-        })
+    const customRouter = options.routes
+      ? (() => {
+          const routeCtx = createRouteContext({
+            db: userDb,
+            env,
+            storage,
+            email,
+            jobs,
+            realtime,
+            auth,
+            authResolver,
+          })
+          const built = (
+            options.routes as (ctx: unknown) => import('hono').Hono
+          )(routeCtx)
+          const enabledTables = Object.values(options.schema)
+            .filter((table) => isTable(table))
+            .map((table) => getTableName(table))
+            .filter((name) => tableEntryForName(resolvedAccess, name)?.enabled)
+          validateCustomRoutes(built.routes, enabledTables)
+          return built
+        })()
       : undefined
     const { handler, router } = buildHandler({
+      customRouter,
       crudRouter,
       authHandler: (req) => auth.handler(req),
       storageRouter,
       realtimeRouter,
       trpcHandler,
-      cronRouter,
       rateLimit: options.rateLimit,
     })
 
+    // Topology is a deployment concern: the role decides whether this process
+    // runs background work, so application code never has to.
+    const roleWantsWorker =
+      env.BUNDERSTACK_ROLE === 'all' || env.BUNDERSTACK_ROLE === 'worker'
+    const autoStart =
+      options.background?.autoStart ??
+      (roleWantsWorker && !introspect && resolvedDefs !== undefined)
+    let backgroundRunning = false
+    if (autoStart) {
+      await startWorker()
+      backgroundRunning = true
+    }
+
     const app: BunderstackApp<
       TSchema,
       TAccess,
@@ -697,8 +696,8 @@ export async function createBunderstack<
       jobs: jobs as never,
       startWorker,
       runWorker,
-      startCronScheduler,
       close: () => lifecycle.close(),
+      backgroundRunning,
       get status() {
         return lifecycle.status
       },
@@ -712,7 +711,7 @@ export async function createBunderstack<
         envConfig: options.env as EnvConfigInput | undefined,
         emailProvider: emailProviderTag(options.email),
         realtime: Boolean(config.realtime),
-        jobs: jobsDefs,
+        jobs: resolvedDefs,
       }),
     }
 
@@ -763,11 +762,7 @@ export type {
 } from './email'
 export { createTRPC } from './trpc'
 export type { BunderstackTRPC, TRPCContext } from './trpc'
-export {
-  createJobsBuilder,
-  signScheduleRequest,
-  verifyScheduleRequest,
-} from './jobs/index'
+export { createJobsBuilder } from './jobs/index'
 export type {
   BunderstackJobContext,
   BunderstackJobsBuilder,
@@ -783,8 +778,6 @@ export type {
   JobsRuntimeFacade,
   QueueJobDefinition,
   QueueJobKeys,
-  LocalCronScheduler,
-  LocalCronSchedulerOptions,
   RunWorkerOptions,
   StartWorkerOptions,
   WorkerHandle,
@@ -831,3 +824,10 @@ export type {
   RealtimeTransport,
   SchemaTable,
 } from './realtime/facade'
+
+export type {
+  BunderstackRouteContext,
+  RouteContext,
+  RoutesBuilder,
+} from './routes'
+

package/src/internal-tables-pg.ts

@@ -67,20 +67,4 @@ export const bunderstackJobsPg = pgTable(
   ],
 )
 
-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),
-  ],
-)
+