bunderstack 0.15.1 → 0.16.0

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)
@@ -163,7 +155,11 @@ export function buildCrudRouter<TSchema extends Record<string, unknown>>(
         )
       }
 
-      const scope = scopeFor(tableAccess.readScope, { user, session, request: c.req.raw })
+      const scope = scopeFor(tableAccess.readScope, {
+        user,
+        session,
+        request: c.req.raw,
+      })
       if (
         scope &&
         !rowMatchesScope(rows[0] as Record<string, unknown>, scope)
@@ -240,7 +236,12 @@ export function buildCrudRouter<TSchema extends Record<string, unknown>>(
         user?.id ?? null,
       )
 
-      const scope = scopeFor(tableAccess.writeScope, { user, session, request: c.req.raw, body: body as Record<string, unknown> })
+      const scope = scopeFor(tableAccess.writeScope, {
+        user,
+        session,
+        request: c.req.raw,
+        body: body as Record<string, unknown>,
+      })
       const stamped = scope ? stampScope(values, scope) : values
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const rows = await (db as any).insert(table).values(stamped).returning()
@@ -279,7 +280,11 @@ export function buildCrudRouter<TSchema extends Record<string, unknown>>(
         return apiError(c, ErrorCode.NOT_FOUND, 'Not found', 404)
       }
 
-      const readScope = scopeFor(tableAccess.readScope, { user, session, request: c.req.raw })
+      const readScope = scopeFor(tableAccess.readScope, {
+        user,
+        session,
+        request: c.req.raw,
+      })
       if (
         readScope &&
         !rowMatchesScope(existing[0] as Record<string, unknown>, readScope)
@@ -319,7 +324,12 @@ export function buildCrudRouter<TSchema extends Record<string, unknown>>(
         user?.id ?? null,
       )
 
-      const writeScope = scopeFor(tableAccess.writeScope, { user, session, request: c.req.raw, body: body as Record<string, unknown> })
+      const writeScope = scopeFor(tableAccess.writeScope, {
+        user,
+        session,
+        request: c.req.raw,
+        body: body as Record<string, unknown>,
+      })
       const stamped = writeScope ? stampScope(values, writeScope) : values
 
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -352,7 +362,11 @@ export function buildCrudRouter<TSchema extends Record<string, unknown>>(
         return apiError(c, ErrorCode.NOT_FOUND, 'Not found', 404)
       }
 
-      const scope = scopeFor(tableAccess.readScope, { user, session, request: c.req.raw })
+      const scope = scopeFor(tableAccess.readScope, {
+        user,
+        session,
+        request: c.req.raw,
+      })
       if (
         scope &&
         !rowMatchesScope(existing[0] as Record<string, unknown>, scope)

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,12 +23,13 @@ export type BaseEnv = {
   REDIS_URL?: string
   RESEND_API_KEY?: string
   SMTP_URL?: string
-  BUNDERSTACK_CRON_SECRET?: string
+  BUNDERSTACK_ROLE: BunderstackRole
 }
 
-type InferVars<T> = T extends Record<string, ZodType>
-  ? { [K in keyof T]: z.output<T[K]> }
-  : unknown
+type InferVars<T> =
+  T extends Record<string, ZodType>
+    ? { [K in keyof T]: z.output<T[K]> }
+    : unknown
 
 // Non-distributive so `ValidatedEnv<undefined>` is BaseEnv, not `never`.
 export type ValidatedEnv<TEnv extends EnvConfigInput | undefined> = [
@@ -52,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'
@@ -108,13 +111,18 @@ 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) {
-    issues.push('BUNDERSTACK_CRON_SECRET: required when cron is configured in production')
+  if (
+    source.BUNDERSTACK_ROLE !== undefined &&
+    !ROLES.includes(source.BUNDERSTACK_ROLE as BunderstackRole)
+  ) {
+    issues.push(
+      `BUNDERSTACK_ROLE: must be one of ${ROLES.join(', ')} (got "${String(source.BUNDERSTACK_ROLE)}")`,
+    )
   }
   if (options.emailProvider === 'resend' && !source.RESEND_API_KEY) {
     issues.push("RESEND_API_KEY: required when email provider is 'resend'")

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),
-  ],
-)
+

package/src/internal-tables.ts

@@ -12,7 +12,6 @@ import {
 import { detectDialect } from './dialect'
 import {
   bunderstackFilesPg,
-  bunderstackCronRunsPg,
   bunderstackIdempotencyPg,
   bunderstackJobsPg,
 } from './internal-tables-pg'
@@ -74,43 +73,22 @@ 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.
@@ -121,7 +99,6 @@ 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. */
@@ -139,11 +116,6 @@ 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 {