bunderstack 0.15.2 → 0.16.0

package/src/realtime/index.ts

@@ -5,6 +5,7 @@ import {
   checkAccessSync,
   resolveSession,
   rowMatchesScope,
+  tableEntryForName,
   type AccessUser,
   type AuthSessionResolver,
   type ResolvedAccess,
@@ -55,15 +56,6 @@ export type RealtimeBroker = {
   ): void | Promise<void>
 }
 
-function tableEntry(
-  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)
@@ -166,7 +158,7 @@ export function createRealtimeBroker(opts: {
     record: Record<string, unknown>,
     id: unknown,
   ): boolean {
-    const entry = tableEntry(opts.access, table)
+    const entry = tableEntryForName(opts.access, table)
     if (!entry) return false
     const topicMatch =
       s.subscriptions.has(table) ||
@@ -232,7 +224,7 @@ export function createRealtimeBroker(opts: {
       subscribers.delete(id)
     },
     publish(table, action, record) {
-      const entry = tableEntry(opts.access, table)
+      const entry = tableEntryForName(opts.access, table)
       if (!entry) return
       const eventId = nextId++
       buffer.push({ eventId, table, action, record })

package/src/realtime/redis.ts

@@ -12,9 +12,9 @@ import type { RealtimeAction, RealtimeBroker } from './index'
 import {
   checkAccessSync,
   rowMatchesScope,
+  tableEntryForName,
   type AccessUser,
   type ResolvedAccess,
-  type ResolvedTableAccess,
 } from '../access'
 
 export type RedisLike = {
@@ -45,15 +45,6 @@ type WireEvent = {
   record: Record<string, unknown>
 }
 
-function tableEntry(
-  access: ResolvedAccess,
-  name: string,
-): ResolvedTableAccess | undefined {
-  for (const entry of access.values())
-    if (entry.tableName === name) return entry
-  return undefined
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
@@ -109,7 +100,7 @@ export function createRedisRealtimeBroker(opts: {
     table: string,
     record: Record<string, unknown>,
   ): boolean {
-    const entry = tableEntry(opts.access, table)
+    const entry = tableEntryForName(opts.access, table)
     if (!entry) return false
     const id = record['id']
     const topicMatch =
@@ -208,7 +199,7 @@ export function createRedisRealtimeBroker(opts: {
       subscribers.delete(id)
     },
     async publish(table, action, record) {
-      if (!tableEntry(opts.access, table)) return
+      if (!tableEntryForName(opts.access, table)) return
       try {
         const client = getRedis()
         const eventId = await client.incr(counterKey)

package/src/routes.ts

@@ -0,0 +1,137 @@
+// src/routes.ts — mounting user-supplied Hono routes inside the app.
+
+/** A route as Hono reports it on `app.routes`. */
+export type DeclaredRoute = { method: string; path: string }
+
+const RESERVED_EXACT = ['/health', '/api/health', '/api/realtime'] as const
+
+const RESERVED_PREFIXES = [
+  '/api/auth/',
+  '/api/trpc/',
+  '/api/files/',
+  '/files/',
+] as const
+
+/** The first path segment under `/api/`, or undefined when not under it. */
+function apiSegment(path: string): string | undefined {
+  if (!path.startsWith('/api/')) return undefined
+  return path.slice('/api/'.length).split('/')[0]
+}
+
+function collisionFor(
+  route: DeclaredRoute,
+  tableNames: readonly string[],
+): string | undefined {
+  const { path } = route
+  if (RESERVED_EXACT.includes(path as (typeof RESERVED_EXACT)[number])) {
+    return `it is reserved by bunderstack`
+  }
+  for (const prefix of RESERVED_PREFIXES) {
+    if (path.startsWith(prefix)) {
+      return `"${prefix}*" is reserved by bunderstack`
+    }
+  }
+  const segment = apiSegment(path)
+  if (segment === undefined) return undefined
+  if (segment === '*' || segment.startsWith(':')) {
+    return `a parameter or wildcard here would shadow every generated CRUD route`
+  }
+  if (tableNames.includes(segment)) {
+    return `it collides with the generated CRUD route for table "${segment}"`
+  }
+  return undefined
+}
+
+/**
+ * Throws when any declared route would collide with a bunderstack route.
+ *
+ * Custom routes are registered before the built-ins, so a collision silently
+ * shadows core behaviour — including authentication. Failing at construction is
+ * the cheapest place to find out.
+ */
+export function validateCustomRoutes(
+  routes: readonly DeclaredRoute[],
+  tableNames: readonly string[],
+): void {
+  const problems: string[] = []
+  for (const route of routes) {
+    const reason = collisionFor(route, tableNames)
+    if (reason) {
+      problems.push(`  ${route.method} ${route.path} — ${reason}`)
+    }
+  }
+  if (problems.length === 0) return
+  throw new Error(
+    `[bunderstack] routes: ${problems.length} route(s) collide with bunderstack's own:\n${problems.join('\n')}\nChoose different paths.`,
+  )
+}
+
+import type { Hono } from 'hono'
+
+import type { AccessUser, AuthSessionResolver } from './access'
+import type { DbFor } from './db'
+import type { EmailFacade } from './email'
+import type { JobsRuntimeFacade } from './jobs/define'
+import type { RealtimeFacade } from './realtime/facade'
+import type { AuthInstance, StorageFacade } from './index'
+
+import { resolveAccessUser, resolveSession } from './access'
+
+export type RouteContext<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnvResult = Record<string, unknown>,
+> = {
+  db: DbFor<TSchema>
+  env: TEnvResult
+  storage: StorageFacade
+  email: EmailFacade
+  jobs: JobsRuntimeFacade
+  realtime: RealtimeFacade<TSchema>
+  auth: AuthInstance
+  /** Resolve the caller's session. Costs an auth round-trip; call only when needed. */
+  getSession(
+    request: Request,
+  ): Promise<{ user: AccessUser | null; activeOrganizationId: string | null }>
+  /** Convenience wrapper over getSession when the organization is irrelevant. */
+  getUser(request: Request): Promise<AccessUser | null>
+}
+
+/** Alias mirroring the JobContext / BunderstackJobContext pair. */
+export type BunderstackRouteContext<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnvResult = Record<string, unknown>,
+> = RouteContext<TSchema, TEnvResult>
+
+export type RoutesBuilder<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnvResult = Record<string, unknown>,
+> = (ctx: RouteContext<TSchema, TEnvResult>) => Hono
+
+export function createRouteContext<
+  TSchema extends Record<string, unknown>,
+  TEnvResult,
+>(deps: {
+  db: DbFor<TSchema>
+  env: TEnvResult
+  storage: StorageFacade
+  email: EmailFacade
+  jobs: JobsRuntimeFacade
+  realtime: RealtimeFacade<TSchema>
+  auth: AuthInstance
+  authResolver: AuthSessionResolver | undefined
+}): RouteContext<TSchema, TEnvResult> {
+  return {
+    db: deps.db,
+    env: deps.env,
+    storage: deps.storage,
+    email: deps.email,
+    jobs: deps.jobs,
+    realtime: deps.realtime,
+    auth: deps.auth,
+    // Lazy on purpose: a webhook has no session, and resolving one eagerly
+    // would spend an auth round-trip per request on a value nobody reads.
+    getSession: (request) => resolveSession(deps.authResolver, request.headers),
+    getUser: (request) => resolveAccessUser(deps.authResolver, request.headers),
+  }
+}
+

package/src/jobs/cron-auth.ts

@@ -1,28 +0,0 @@
-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)
-}

package/src/jobs/cron-router.ts

@@ -1,135 +0,0 @@
-import { and, eq, lt } from 'drizzle-orm'
-import { Hono } from 'hono'
-
-import type { AnyDb } from '../dialect'
-import type { BackgroundDefs } from './define'
-
-import { cronRunsTableFor } from '../internal-tables'
-import { verifyScheduleRequest } from './cron-auth'
-import { runCronSlot, runScheduledSlot } from './cron-runner'
-
-const MAX_SLOT_AGE_MS = 60 * 60_000
-const MAX_FUTURE_SLOT_MS = 60_000
-const STORAGE_SWEEP_SCHEDULE = '0 4 * * *'
-const SCHEDULED_RUN_RETENTION_MS = 30 * 24 * 60 * 60_000
-
-export function buildCronRouter(args: {
-  db: AnyDb
-  defs: BackgroundDefs
-  ctx: Record<string, unknown>
-  secret: string
-  storage: { sweep: () => Promise<unknown> }
-  now?: () => number
-}): Hono {
-  const app = new Hono()
-  const now = args.now ?? Date.now
-
-  app.post('/cron/:name', async (c) => {
-    const name = c.req.param('name')
-    const slotText = c.req.header('X-Bunderstack-Cron-Slot')
-    const signature = c.req.header('X-Bunderstack-Cron-Signature')
-    const slot = Number(slotText)
-    if (!slotText || !Number.isSafeInteger(slot) || !signature) {
-      return c.json({ error: 'invalid schedule signature' }, 401)
-    }
-    if (!verifyScheduleRequest(args.secret, `cron:${name}`, slot, signature)) {
-      return c.json({ error: 'invalid schedule signature' }, 401)
-    }
-    const definition = args.defs[name]
-    if (!definition || definition.kind !== 'cron') {
-      return c.json({ error: 'unknown cron' }, 404)
-    }
-    const current = now()
-    if (
-      slot % 60_000 !== 0 ||
-      slot < current - MAX_SLOT_AGE_MS ||
-      slot > current + MAX_FUTURE_SLOT_MS
-    ) {
-      return c.json({ error: 'invalid cron slot' }, 400)
-    }
-    try {
-      const result = await runCronSlot({
-        db: args.db,
-        defs: args.defs,
-        ctx: args.ctx,
-        name,
-        slot,
-        now: current,
-      })
-      return c.json(result, result.status === 'running' ? 202 : 200)
-    } catch (error) {
-      if (
-        error instanceof Error &&
-        error.message === '[bunderstack] cron slot does not match its schedule'
-      ) {
-        return c.json({ error: 'invalid cron slot' }, 400)
-      }
-      return c.json({ error: 'cron handler failed' }, 500)
-    }
-  })
-
-  app.post('/maintenance/:name', async (c) => {
-    const name = c.req.param('name')
-    const slotText = c.req.header('X-Bunderstack-Cron-Slot')
-    const signature = c.req.header('X-Bunderstack-Cron-Signature')
-    const slot = Number(slotText)
-    if (!slotText || !Number.isSafeInteger(slot) || !signature) {
-      return c.json({ error: 'invalid schedule signature' }, 401)
-    }
-    if (
-      !verifyScheduleRequest(
-        args.secret,
-        `maintenance:${name}`,
-        slot,
-        signature,
-      )
-    ) {
-      return c.json({ error: 'invalid schedule signature' }, 401)
-    }
-    if (name !== 'storage-sweep') {
-      return c.json({ error: 'unknown maintenance task' }, 404)
-    }
-    const current = now()
-    if (
-      slot % 60_000 !== 0 ||
-      slot < current - MAX_SLOT_AGE_MS ||
-      slot > current + MAX_FUTURE_SLOT_MS
-    ) {
-      return c.json({ error: 'invalid cron slot' }, 400)
-    }
-    try {
-      const result = await runScheduledSlot({
-        db: args.db,
-        taskId: 'maintenance:storage-sweep',
-        schedule: STORAGE_SWEEP_SCHEDULE,
-        slot,
-        now: current,
-        run: async () => {
-          await args.storage.sweep()
-        },
-      })
-      if (result.status === 'succeeded') {
-        const t = cronRunsTableFor(args.db)
-        await args.db
-          .delete(t)
-          .where(
-            and(
-              eq(t.status, 'succeeded'),
-              lt(t.finishedAt, current - SCHEDULED_RUN_RETENTION_MS),
-            ),
-          )
-      }
-      return c.json(result, result.status === 'running' ? 202 : 200)
-    } catch (error) {
-      if (
-        error instanceof Error &&
-        error.message === '[bunderstack] cron slot does not match its schedule'
-      ) {
-        return c.json({ error: 'invalid cron slot' }, 400)
-      }
-      return c.json({ error: 'maintenance handler failed' }, 500)
-    }
-  })
-
-  return app
-}

package/src/jobs/cron-runner.ts

@@ -1,224 +0,0 @@
-import { and, eq, lt, or, sql } from 'drizzle-orm'
-
-import type { AnyDb } from '../dialect'
-import type { BackgroundDefs } from './define'
-
-import { cronRunsTableFor } from '../internal-tables'
-import { cronMatches, parseCron } from './cron'
-
-const LEASE_MS = 60_000
-
-export type CronRunResult =
-  | { status: 'succeeded' }
-  | { status: 'duplicate' }
-  | { status: 'running' }
-
-export async function runScheduledSlot(args: {
-  db: AnyDb
-  taskId: string
-  schedule: string
-  slot: number
-  now: number
-  run: (scheduledFor: Date) => Promise<void> | void
-  leaseMs?: number
-  heartbeatIntervalMs?: number
-  heartbeatCleanupTimeoutMs?: number
-}): Promise<CronRunResult> {
-  const { db, taskId, schedule, slot, now, run } = args
-  const leaseMs = args.leaseMs ?? LEASE_MS
-  const heartbeatIntervalMs =
-    args.heartbeatIntervalMs ?? Math.max(1, Math.floor(leaseMs / 4))
-  const heartbeatCleanupTimeoutMs = args.heartbeatCleanupTimeoutMs ?? 1_000
-
-  if (slot % 60_000 !== 0 || !cronMatches(parseCron(schedule), slot)) {
-    throw new Error('[bunderstack] cron slot does not match its schedule')
-  }
-
-  const t = cronRunsTableFor(db)
-  const leaseUntil = now + leaseMs
-  const inserted = await db
-    .insert(t)
-    .values({
-      taskId,
-      scheduledAt: slot,
-      status: 'running',
-      attempts: 1,
-      lockedUntil: leaseUntil,
-      startedAt: now,
-    })
-    .onConflictDoNothing({ target: [t.taskId, t.scheduledAt] })
-    .returning({ taskId: t.taskId, attempts: t.attempts })
-
-  let ownershipAttempt: number
-  if (inserted[0]) {
-    ownershipAttempt = Number(inserted[0].attempts)
-  } else {
-    const existing = await db
-      .select({ status: t.status, lockedUntil: t.lockedUntil })
-      .from(t)
-      .where(and(eq(t.taskId, taskId), eq(t.scheduledAt, slot)))
-      .limit(1)
-    const row = existing[0]
-    if (!row || row.status === 'succeeded') return { status: 'duplicate' }
-    if (row.status === 'running' && Number(row.lockedUntil) >= now) {
-      return { status: 'running' }
-    }
-    const reclaimed = await db
-      .update(t)
-      .set({
-        status: 'running',
-        lockedUntil: leaseUntil,
-        startedAt: now,
-        attempts: sql`${t.attempts} + 1`,
-        lastError: null,
-      })
-      .where(
-        and(
-          eq(t.taskId, taskId),
-          eq(t.scheduledAt, slot),
-          or(eq(t.status, 'failed'), lt(t.lockedUntil, now)),
-        ),
-      )
-      .returning({ taskId: t.taskId, attempts: t.attempts })
-    const reclaimedRow = reclaimed[0]
-    if (!reclaimedRow) return { status: 'running' }
-    ownershipAttempt = Number(reclaimedRow.attempts)
-  }
-
-  let heartbeatTimer: Timer | undefined
-  let heartbeatInFlight: Promise<void> | undefined
-  let heartbeatStopped = false
-
-  const scheduleHeartbeat = () => {
-    heartbeatTimer = setTimeout(() => {
-      heartbeatTimer = undefined
-      if (heartbeatStopped) return
-
-      heartbeatInFlight = (async () => {
-        try {
-          const renewUntil = Date.now() + leaseMs
-          await db
-            .update(t)
-            .set({ lockedUntil: renewUntil })
-            .where(
-              and(
-                eq(t.taskId, taskId),
-                eq(t.scheduledAt, slot),
-                eq(t.status, 'running'),
-                eq(t.startedAt, now),
-                eq(t.attempts, ownershipAttempt),
-              ),
-            )
-        } catch {
-          // Best effort renewal
-        }
-      })()
-
-      void heartbeatInFlight.finally(() => {
-        heartbeatInFlight = undefined
-        if (!heartbeatStopped) scheduleHeartbeat()
-      })
-    }, heartbeatIntervalMs)
-  }
-
-  const stopHeartbeat = async () => {
-    heartbeatStopped = true
-    if (heartbeatTimer) {
-      clearTimeout(heartbeatTimer)
-      heartbeatTimer = undefined
-    }
-    const inFlight = heartbeatInFlight
-    if (!inFlight) return
-
-    let cleanupTimer: Timer | undefined
-    try {
-      await Promise.race([
-        inFlight,
-        new Promise<void>((resolve) => {
-          cleanupTimer = setTimeout(resolve, heartbeatCleanupTimeoutMs)
-        }),
-      ])
-    } finally {
-      if (cleanupTimer) clearTimeout(cleanupTimer)
-    }
-  }
-
-  scheduleHeartbeat()
-
-  try {
-    await run(new Date(slot))
-
-    const updated = await db
-      .update(t)
-      .set({ status: 'succeeded', lockedUntil: null, finishedAt: Date.now() })
-      .where(
-        and(
-          eq(t.taskId, taskId),
-          eq(t.scheduledAt, slot),
-          eq(t.status, 'running'),
-          eq(t.startedAt, now),
-          eq(t.attempts, ownershipAttempt),
-        ),
-      )
-      .returning({ taskId: t.taskId })
-
-    if (!updated[0]) {
-      throw new Error(
-        '[bunderstack] cron lease ownership was lost during execution',
-      )
-    }
-
-    return { status: 'succeeded' }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
-    await db
-      .update(t)
-      .set({
-        status: 'failed',
-        lockedUntil: null,
-        lastError: message,
-        finishedAt: Date.now(),
-      })
-      .where(
-        and(
-          eq(t.taskId, taskId),
-          eq(t.scheduledAt, slot),
-          eq(t.status, 'running'),
-          eq(t.startedAt, now),
-          eq(t.attempts, ownershipAttempt),
-        ),
-      )
-    throw error
-  } finally {
-    await stopHeartbeat()
-  }
-}
-
-export async function runCronSlot(args: {
-  db: AnyDb
-  defs: BackgroundDefs
-  ctx: Record<string, unknown>
-  name: string
-  slot: number
-  now: number
-  leaseMs?: number
-  heartbeatIntervalMs?: number
-  heartbeatCleanupTimeoutMs?: number
-}): Promise<CronRunResult> {
-  const definition = args.defs[args.name]
-  if (!definition || definition.kind !== 'cron') {
-    throw new Error(`[bunderstack] unknown cron "${args.name}"`)
-  }
-  return runScheduledSlot({
-    db: args.db,
-    taskId: `cron:${args.name}`,
-    schedule: definition.schedule,
-    slot: args.slot,
-    now: args.now,
-    leaseMs: args.leaseMs,
-    heartbeatIntervalMs: args.heartbeatIntervalMs,
-    heartbeatCleanupTimeoutMs: args.heartbeatCleanupTimeoutMs,
-    run: (scheduledFor) =>
-      definition.handler({ scheduledFor }, args.ctx as never),
-  })
-}

package/src/jobs/local-cron.ts

@@ -1,78 +0,0 @@
-import { cronMatches, parseCron } from './cron'
-
-type Timer = ReturnType<typeof setTimeout> | number
-
-export type LocalCronDefinition = {
-  name: string
-  schedule: string
-}
-
-export type LocalCronSchedulerOptions = {
-  cron: readonly LocalCronDefinition[]
-  runSlot: (name: string, scheduledFor: number) => Promise<void>
-  now?: () => number
-  setTimer?: (callback: () => void, delayMs: number) => Timer
-  clearTimer?: (timer: Timer) => void
-  onError?: (error: Error) => void
-}
-
-export type LocalCronScheduler = {
-  tick: () => Promise<void>
-  close: () => Promise<void>
-}
-
-/**
- * Runs declared cron handlers locally. Production schedules should be delivered
- * by the hosting platform through the signed cron endpoint instead.
- */
-export function startLocalCronScheduler(
-  options: LocalCronSchedulerOptions,
-): LocalCronScheduler {
-  const cron = options.cron.map((definition) => ({
-    ...definition,
-    expression: parseCron(definition.schedule),
-  }))
-  const now = options.now ?? Date.now
-  const setTimer = options.setTimer ?? setTimeout
-  const clearTimer = options.clearTimer ?? clearTimeout
-  let timer: Timer | undefined
-  let closed = false
-
-  const scheduleNextTick = () => {
-    if (closed || timer) return
-
-    const delay = 60_000 - (now() % 60_000)
-    timer = setTimer(() => {
-      timer = undefined
-      void tick().catch((error: unknown) => {
-        options.onError?.(
-          error instanceof Error ? error : new Error(String(error)),
-        )
-      })
-    }, delay)
-  }
-
-  const tick = async () => {
-    if (closed) return
-
-    const scheduledFor = Math.floor(now() / 60_000) * 60_000
-    for (const definition of cron) {
-      if (cronMatches(definition.expression, scheduledFor)) {
-        await options.runSlot(definition.name, scheduledFor)
-      }
-    }
-
-    scheduleNextTick()
-  }
-
-  return {
-    tick,
-    async close() {
-      closed = true
-      if (timer) {
-        clearTimer(timer)
-        timer = undefined
-      }
-    },
-  }
-}