bunderstack 0.7.0 → 0.9.0

package/src/index.ts

@@ -4,25 +4,36 @@ import type { Hono as HonoType } from 'hono'
 
 import { fetchRequestHandler } from '@trpc/server/adapters/fetch'
 
-import type { StorageAdapter } from './storage/index'
 import type { TableAccessInput } from './access'
 import type { DbFor } from './db'
+import type {
+  BunderstackJobsBuilder,
+  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 { createAuth, toAuthSessionResolver, withEmailAuthDefaults } from './auth'
+import {
+  createAuth,
+  toAuthSessionResolver,
+  withEmailAuthDefaults,
+} from './auth'
 import { resolveConfig, type BunderstackConfig } from './config'
 import { resolveRealtimeRedisUrl } from './config'
+import { buildCrudRouter } from './crud'
+import { createDb } from './db'
 import { detectDialect } from './dialect'
 import { createEmail, emailProviderTag, type EmailFacade } from './email'
 import { validateEnv, type EnvConfigInput, type ValidatedEnv } from './env'
-import { buildManifest, type BunderstackManifest } from './manifest'
-import { createTRPC, type BunderstackTRPC } from './trpc'
-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,
@@ -33,28 +44,25 @@ import {
   startJobWorker,
   validateJobsDefs,
 } from './jobs/index'
-import type {
-  BunderstackJobsBuilder,
-  EnqueueOptions,
-  JobsDefs,
-  JobsFacade,
-  LocalCronScheduler,
-  LocalCronSchedulerOptions,
-  StartWorkerOptions,
-  WorkerHandle,
-} from './jobs/index'
+import { Lifecycle, type LifecycleStatus } from './lifecycle'
+import { buildManifest, type BunderstackManifest } from './manifest'
 import {
   PROVISION_INTERNALS,
   type WithProvisionInternals,
 } from './provision-internals'
+import {
+  createRealtimeFacade,
+  type RealtimeFacade,
+  type RealtimeTransport,
+} from './realtime/facade'
 import { createRealtimeBroker, buildRealtimeRouter } from './realtime/index'
 import { createRedisRealtimeBroker } from './realtime/redis'
-import { createRealtimeFacade, type RealtimeFacade } from './realtime/facade'
 import { deleteFileWithDerivatives } from './storage/delete'
 import { deleteFileMetaRow } from './storage/file-meta'
 import { createBucketStorages } from './storage/registry'
 import { buildBucketStorageRouter } from './storage/router'
 import { sweepOrphans } from './storage/sweep'
+import { createTRPC, type BunderstackTRPC } from './trpc'
 
 type AuthInstance = ReturnType<typeof createAuth>
 
@@ -89,9 +97,9 @@ const DEFAULT_PENDING_TTL_MS = 30 * 60_000
  * must also clean the file-meta row.
  */
 export interface StorageFacade {
-  /** Delete an object, its transform derivatives, and its file-meta row. `fileId` is `<bucket>/<id>`. */
+  /** Delete a file row and purge all underlying storage derivatives. */
   delete(fileId: string): Promise<void>
-  /** Get the raw adapter for a bucket, or `undefined` if it isn't declared. */
+  /** Low-level access to the underlying storage adapter for a bucket. */
   bucket(name: string): StorageAdapter | undefined
   /**
    * Reap stale `pending` uploads older than `olderThanMs` (default 30m). Runs
@@ -102,7 +110,15 @@ export interface StorageFacade {
 }
 
 export type AppStartWorkerOptions = Omit<StartWorkerOptions, 'tick'>
-export type AppRunWorkerOptions = AppStartWorkerOptions
+export type AppRunWorkerOptions = AppStartWorkerOptions & {
+  /**
+   * Permit process-local realtime in a standalone worker.
+   *
+   * Use only when job handlers never call ctx.realtime.publish(). Publications
+   * made through the memory broker cannot reach SSE clients in another process.
+   */
+  allowProcessLocalRealtime?: boolean
+}
 export type AppStartCronSchedulerOptions = Pick<
   LocalCronSchedulerOptions,
   'onError'
@@ -115,7 +131,6 @@ export type BucketNamesOf<TStorage> = TStorage extends {
   ? keyof B & string
   : string
 
-
 export type BunderstackApp<
   TSchema extends Record<string, unknown>,
   TAccess extends Record<string, TableAccessInput> | undefined = undefined,
@@ -136,7 +151,9 @@ export type BunderstackApp<
   /** Email facade; always present — send() throws when email isn't configured. */
   email: EmailFacade
   /** Job queue facade; always present — enqueue throws when jobs aren't configured. */
-  jobs: JobsFacade<TJobsDefs extends JobsDefs ? TJobsDefs : Record<never, never>>
+  jobs: JobsFacade<
+    TJobsDefs extends JobsDefs ? TJobsDefs : Record<never, never>
+  >
   /** Typed custom row publication; enabled=false/no-op when realtime is off. */
   realtime: RealtimeFacade<TSchema>
   startWorker(options?: AppStartWorkerOptions): Promise<WorkerHandle>
@@ -186,7 +203,16 @@ export function createBunderstack<
     /** Builder callback receiving the pre-wired `j` instance. */
     jobs: (j: BunderstackJobsBuilder<TSchema, ValidatedEnv<TEnv>>) => TJobsDefs
   },
-): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter, TJobsDefs>>
+): Promise<
+  BunderstackApp<
+    TSchema,
+    TAccess,
+    BucketNamesOf<TStorage>,
+    TEnv,
+    TRouter,
+    TJobsDefs
+  >
+>
 export function createBunderstack<
   TSchema extends Record<string, unknown>,
   const TAccess extends Record<string, TableAccessInput> | undefined =
@@ -202,7 +228,16 @@ export function createBunderstack<
     /** Prebuilt job definitions (escape hatch for multi-file setups). */
     jobs?: TJobsDefs
   },
-): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter, TJobsDefs>>
+): Promise<
+  BunderstackApp<
+    TSchema,
+    TAccess,
+    BucketNamesOf<TStorage>,
+    TEnv,
+    TRouter,
+    TJobsDefs
+  >
+>
 export function createBunderstack<
   TSchema extends Record<string, unknown>,
   const TAccess extends Record<string, TableAccessInput> | undefined =
@@ -218,7 +253,16 @@ export function createBunderstack<
     /** Builder callback receiving the pre-wired `j` instance. */
     jobs: (j: BunderstackJobsBuilder<TSchema, ValidatedEnv<TEnv>>) => TJobsDefs
   },
-): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter, TJobsDefs>>
+): Promise<
+  BunderstackApp<
+    TSchema,
+    TAccess,
+    BucketNamesOf<TStorage>,
+    TEnv,
+    TRouter,
+    TJobsDefs
+  >
+>
 export function createBunderstack<
   TSchema extends Record<string, unknown>,
   const TAccess extends Record<string, TableAccessInput> | undefined =
@@ -234,7 +278,16 @@ export function createBunderstack<
     /** Prebuilt job definitions (escape hatch for multi-file setups). */
     jobs?: TJobsDefs
   },
-): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter, TJobsDefs>>
+): Promise<
+  BunderstackApp<
+    TSchema,
+    TAccess,
+    BucketNamesOf<TStorage>,
+    TEnv,
+    TRouter,
+    TJobsDefs
+  >
+>
 export async function createBunderstack<
   TSchema extends Record<string, unknown>,
   const TAccess extends Record<string, TableAccessInput> | undefined =
@@ -278,243 +331,271 @@ export async function createBunderstack<
     cronConfigured: true,
   })
   const config = resolveConfig(options, env)
-  // Introspection mode (BUNDERSTACK_INTROSPECT=1): deployment platforms import
-  // the app declaration only to read `app.manifest`. The boot must never touch
-  // the outside world — force an in-memory db (':memory:' is valid for both
-  // dialects) and skip Redis below. Env validation is already lenient (env.ts).
+  // Adapters use Drizzle mocks during deployment introspection, so the database
+  // and Redis below never touch external services.
   const introspect = process.env.BUNDERSTACK_INTROSPECT === '1'
-  if (introspect) {
-    config.database.url = ':memory:'
-    config.database.authToken = undefined
-  }
   const email = createEmail(options.email, { env })
   // Merge bunderstack's internal tables (file-meta, idempotency) into the
   // schema used for the db client + provisioning. CRUD/access stay on the USER
   // schema so internal tables never get a CRUD route.
   const mergedSchema = withInternalTables(options.schema)
-  const { db, driver } = await createDb(mergedSchema, {
+  const lifecycle = new Lifecycle()
+  const {
+    db,
+    driver,
+    close: closeDatabase,
+  } = await createDb(mergedSchema, {
     ...config.database,
     dialect,
+    introspect,
   })
-  // `db` is typed with the merged schema (user tables + internal tables) so the
-  // storage/idempotency code can query the internal tables. The public surface
-  // and CRUD only expose the USER schema. TS can widen the merged-schema db type
-  // on its own (storage/auth pass `db` directly), but it can't *narrow* a
-  // generic schema view, so this single intentional cast produces the
-  // user-facing, per-dialect db type. See `app.db` / crud below.
-  const userDb = db as unknown as DbFor<TSchema>
-  const auth = createAuth(
-    db,
-    withEmailAuthDefaults(config.auth, email, Boolean(options.email)),
-    dialect,
-  )
-  // Internal routers consume the narrow AuthSessionResolver contract, not the
-  // raw better-auth instance. app.auth still exposes `auth` unchanged.
-  const authResolver = toAuthSessionResolver(auth)
-  const resolvedAccess = validateAndResolveAccess(
-    options.schema,
-    options.access,
-  )
-  const realtimeBufferSize =
-    typeof config.realtime === 'object' ? config.realtime.bufferSize : undefined
-  const redisUrl =
-    config.realtime && !introspect
+  if (closeDatabase) lifecycle.add(closeDatabase)
+  try {
+    // `db` is typed with the merged schema (user tables + internal tables) so the
+    // storage/idempotency code can query the internal tables. The public surface
+    // and CRUD only expose the USER schema. TS can widen the merged-schema db type
+    // on its own (storage/auth pass `db` directly), but it can't *narrow* a
+    // generic schema view, so this single intentional cast produces the
+    // user-facing, per-dialect db type. See `app.db` / crud below.
+    const userDb = db as unknown as DbFor<TSchema>
+    const auth = createAuth(
+      db,
+      withEmailAuthDefaults(config.auth, email, Boolean(options.email)),
+      dialect,
+    )
+    // Internal routers consume the narrow AuthSessionResolver contract, not the
+    // raw better-auth instance. app.auth still exposes `auth` unchanged.
+    const authResolver = toAuthSessionResolver(auth)
+    const resolvedAccess = validateAndResolveAccess(
+      options.schema,
+      options.access,
+    )
+    const realtimeBufferSize =
+      typeof config.realtime === 'object'
+        ? config.realtime.bufferSize
+        : undefined
+    const configuredRedisUrl = config.realtime
       ? resolveRealtimeRedisUrl(config.realtime, env)
       : undefined
-  const broker = config.realtime
-    ? redisUrl
-      ? createRedisRealtimeBroker({
-          access: resolvedAccess,
-          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)
-            const subClient = new Bun.RedisClient(redisUrl)
-            return {
-              incr: (key: string) => cmdClient.incr(key),
-              publish: (channel: string, message: string) =>
-                cmdClient.publish(channel, message),
-              subscribe: (channel: string, listener: (msg: string) => void) =>
-                subClient.subscribe(channel, listener),
-              lpush: (key: string, value: string) =>
-                cmdClient.lpush(key, value),
-              ltrim: (key: string, start: number, stop: number) =>
-                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({
-          access: resolvedAccess,
-          bufferSize: realtimeBufferSize,
+    const configuredRealtimeTransport: RealtimeTransport = !config.realtime
+      ? 'disabled'
+      : configuredRedisUrl
+        ? 'redis'
+        : 'memory'
+    const redisUrl = introspect ? undefined : configuredRedisUrl
+    const broker = config.realtime
+      ? redisUrl
+        ? createRedisRealtimeBroker({
+            access: resolvedAccess,
+            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)
+              const subClient = new Bun.RedisClient(redisUrl)
+              return {
+                incr: (key: string) => cmdClient.incr(key),
+                publish: (channel: string, message: string) =>
+                  cmdClient.publish(channel, message),
+                subscribe: (channel: string, listener: (msg: string) => void) =>
+                  subClient.subscribe(channel, listener),
+                lpush: (key: string, value: string) =>
+                  cmdClient.lpush(key, value),
+                ltrim: (key: string, start: number, stop: number) =>
+                  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({
+            access: resolvedAccess,
+            bufferSize: realtimeBufferSize,
+          })
+      : undefined
+    const runtimeRealtimeTransport: RealtimeTransport = !broker
+      ? 'disabled'
+      : redisUrl
+        ? 'redis'
+        : 'memory'
+    const realtime = createRealtimeFacade<TSchema>(
+      broker,
+      runtimeRealtimeTransport,
+    )
+    const crudRouter = buildCrudRouter(options.schema, userDb, {
+      auth: authResolver,
+      access: resolvedAccess,
+      idempotency: options.idempotency,
+      realtime,
+    })
+    const realtimeRouter = broker
+      ? buildRealtimeRouter(broker, {
+          auth: authResolver,
+          keepaliveMs:
+            typeof config.realtime === 'object'
+              ? config.realtime.keepaliveMs
+              : undefined,
         })
-    : undefined
-  const realtime = createRealtimeFacade<TSchema>(broker)
-  const crudRouter = buildCrudRouter(options.schema, userDb, {
-    auth: authResolver,
-    access: resolvedAccess,
-    idempotency: options.idempotency,
-    realtime,
-  })
-  const realtimeRouter = broker
-    ? buildRealtimeRouter(broker, {
-        auth: authResolver,
-        keepaliveMs:
-          typeof config.realtime === 'object'
-            ? config.realtime.keepaliveMs
-            : undefined,
-      })
-    : undefined
-  const registry = createBucketStorages(config.storage)
-  const lifecycle = new Lifecycle()
-  if (broker) lifecycle.add(() => broker.close())
-  const storageRouter = buildBucketStorageRouter({
-    registry,
-    db,
-    auth: authResolver,
-  })
-  const storage: StorageFacade = {
-    async delete(fileId) {
-      const bucketName = fileId.split('/')[0] ?? ''
-      const entry = registry.get(bucketName)
-      if (entry) {
-        await deleteFileWithDerivatives(entry.adapter, db, fileId)
-      } else {
-        // Unknown bucket: no adapter to clean, but still drop the meta row.
-        await deleteFileMetaRow(db, fileId)
-      }
-    },
-    bucket(name) {
-      return registry.get(name)?.adapter
-    },
-    sweep(olderThanMs = DEFAULT_PENDING_TTL_MS) {
-      return sweepOrphans(registry, db, olderThanMs)
-    },
-  }
-  const jobRunner = jobsDefs
-    ? createJobRunner({
-        db,
-        defs: jobsDefs,
-        ctx: { db: userDb, env, email, storage, realtime },
-      })
-    : undefined
-  const jobs = {
-    async enqueue(name: string, input?: unknown, opts?: EnqueueOptions) {
-      if (!jobsDefs) {
-        throw new Error(
-          '[bunderstack] no jobs configured — add a `jobs` key to createBunderstack',
-        )
-      }
-      const result = await enqueueJob(db, jobsDefs, name, input, opts)
-      return result
-    },
-    tick(now?: number) {
-      return jobRunner ? jobRunner.tick(now) : Promise.resolve()
-    },
-  }
-  if (jobRunner) jobRunner.setJobsFacade(jobs)
-  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),
+      : undefined
+    const registry = createBucketStorages(config.storage)
+    if (broker) lifecycle.add(() => broker.close())
+    const storageRouter = buildBucketStorageRouter({
+      registry,
+      db,
+      auth: authResolver,
     })
-    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 storage: StorageFacade = {
+      async delete(fileId) {
+        const bucketName = fileId.split('/')[0] ?? ''
+        const entry = registry.get(bucketName)
+        if (entry) {
+          await deleteFileWithDerivatives(entry.adapter, db, fileId)
+        } else {
+          // Unknown bucket: no adapter to clean, but still drop the meta row.
+          await deleteFileMetaRow(db, fileId)
+        }
+      },
+      bucket(name) {
+        return registry.get(name)?.adapter
+      },
+      sweep(olderThanMs = DEFAULT_PENDING_TTL_MS) {
+        return sweepOrphans(registry, db, olderThanMs)
+      },
     }
-    const scheduler = startLocalCronScheduler({
-      cron,
-      onError: options.onError,
-      runSlot: async (name, slot) => {
-        await runCronSlot({
+    const jobRunner = jobsDefs
+      ? createJobRunner({
           db,
-          defs: jobsDefs!,
+          defs: jobsDefs,
           ctx: { db: userDb, env, email, storage, realtime },
-          name,
-          slot,
-          now: Date.now(),
         })
+      : undefined
+    const jobs = {
+      async enqueue(name: string, input?: unknown, opts?: EnqueueOptions) {
+        if (!jobsDefs) {
+          throw new Error(
+            '[bunderstack] no jobs configured — add a `jobs` key to createBunderstack',
+          )
+        }
+        const result = await enqueueJob(db, jobsDefs, name, input, opts)
+        return result
+      },
+      tick(now?: number) {
+        return jobRunner ? jobRunner.tick(now) : Promise.resolve()
       },
-    })
-    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 {
+    if (jobRunner) jobRunner.setJobsFacade(jobs)
+    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
-      await waitForWorkerShutdown(signal, !options.signal)
-    } finally {
-      await handle.close()
-      await lifecycle.close()
+      const handle = startJobWorker({
+        ...options,
+        signal,
+        tick: (now) => jobRunner.tick(now),
+      })
+      const unregister = lifecycle.add(() => handle.close())
+      void handle.closed.finally(unregister)
+      return handle
     }
-  }
-  const trpcRouter: AnyRouter | undefined =
-    typeof options.trpc === 'function'
-      ? options.trpc(createTRPC<TSchema, ValidatedEnv<TEnv>>())
-      : options.trpc
-  const trpcHandler = trpcRouter
-    ? (req: Request) =>
-        fetchRequestHandler({
-          endpoint: '/api/trpc',
-          req,
-          router: trpcRouter,
-          createContext: async () => ({
-            db: userDb,
-            user: await resolveAccessUser(authResolver, req.headers),
-            env,
-            email,
-            jobs,
-            realtime,
+    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, 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> => {
+      if (
+        realtime.transport === 'memory' &&
+        !options.allowProcessLocalRealtime
+      ) {
+        throw new Error(
+          '[bunderstack] runWorker() cannot deliver realtime events through the in-memory broker. Configure REDIS_URL or realtime.redis, embed the worker with startWorker(), or pass allowProcessLocalRealtime: true only when jobs never publish realtime.',
+        )
+      }
+      const {
+        allowProcessLocalRealtime: _allowProcessLocalRealtime,
+        ...workerOptions
+      } = options
+      const handle = await startWorker(workerOptions)
+      try {
+        const signal = workerOptions.signal
+          ? AbortSignal.any([lifecycle.signal, workerOptions.signal])
+          : lifecycle.signal
+        await waitForWorkerShutdown(signal, !workerOptions.signal)
+      } finally {
+        await handle.close()
+        await lifecycle.close()
+      }
+    }
+    const trpcRouter: AnyRouter | undefined =
+      typeof options.trpc === 'function'
+        ? options.trpc(createTRPC<TSchema, ValidatedEnv<TEnv>>())
+        : options.trpc
+    const trpcHandler = trpcRouter
+      ? (req: Request) =>
+          fetchRequestHandler({
+            endpoint: '/api/trpc',
             req,
-          }),
-        })
-    : undefined
-  const cronRouter =
-    env.BUNDERSTACK_CRON_SECRET
+            router: trpcRouter,
+            createContext: async () => ({
+              db: userDb,
+              user: await resolveAccessUser(authResolver, req.headers),
+              env,
+              email,
+              jobs,
+              realtime,
+              req,
+            }),
+          })
+      : undefined
+    const cronRouter = env.BUNDERSTACK_CRON_SECRET
       ? buildCronRouter({
           db,
           defs: jobsDefs ?? {},
@@ -523,69 +604,82 @@ export async function createBunderstack<
           storage,
         })
       : undefined
-  const { handler, router } = buildHandler({
-    crudRouter,
-    authHandler: (req) => auth.handler(req),
-    storageRouter,
-    realtimeRouter,
-    trpcHandler,
-    cronRouter,
-    rateLimit: options.rateLimit,
-  })
+    const { handler, router } = buildHandler({
+      crudRouter,
+      authHandler: (req) => auth.handler(req),
+      storageRouter,
+      realtimeRouter,
+      trpcHandler,
+      cronRouter,
+      rateLimit: options.rateLimit,
+    })
 
-  const app: BunderstackApp<
-    TSchema,
-    TAccess,
-    BucketNamesOf<TStorage>,
-    TEnv,
-    AnyRouter | undefined,
-    JobsDefs | undefined
-  > = {
-    handler,
-    // Internal tables live on the runtime db but stay out of the public type.
-    db: userDb,
-    auth,
-    storage,
-    router,
-    env,
-    email,
-    realtime,
-    // Runtime facade is untyped (JobsRuntimeFacade); the generic-typed field
-    // 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,
+    const app: BunderstackApp<
+      TSchema,
+      TAccess,
+      BucketNamesOf<TStorage>,
+      TEnv,
+      AnyRouter | undefined,
+      JobsDefs | undefined
+    > = {
+      handler,
+      // Internal tables live on the runtime db but stay out of the public type.
+      db: userDb,
+      auth,
+      storage,
+      router,
+      env,
+      email,
+      realtime,
+      // Runtime facade is untyped (JobsRuntimeFacade); the generic-typed field
+      // 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,
+        dialect,
+        storage: config.storage,
+        envConfig: options.env as EnvConfigInput | undefined,
+        realtime: Boolean(config.realtime),
+        realtimeTransport: configuredRealtimeTransport,
+        jobs: jobsDefs,
+      }),
+    }
+
+    // Hidden handle for the optional `bunderstack/provision` entry. Kept off the
+    // public type so provisioning stays opt-in (and drizzle-kit out of this
+    // module graph).
+    ;(app as WithProvisionInternals)[PROVISION_INTERNALS] = {
+      db,
+      schema: mergedSchema,
+      databaseUrl: config.database.url,
+      migrationsFolder: config.database.migrations,
       dialect,
-      storage: config.storage,
-      envConfig: options.env as EnvConfigInput | undefined,
-      realtime: Boolean(config.realtime),
-      jobs: jobsDefs,
-    }),
-  }
+      driver,
+      adapter: config.database.adapter,
+    }
 
-  // Hidden handle for the optional `bunderstack/provision` entry. Kept off the
-  // public type so provisioning stays opt-in (and drizzle-kit out of this
-  // module graph).
-  ;(app as WithProvisionInternals)[PROVISION_INTERNALS] = {
-    db,
-    schema: mergedSchema,
-    databaseUrl: config.database.url,
-    migrationsFolder: config.database.migrations,
-    dialect,
-    driver,
+    return app
+  } catch (cause) {
+    try {
+      await lifecycle.close()
+    } catch (cleanupCause) {
+      throw new AggregateError(
+        [cause, cleanupCause],
+        '[bunderstack] application initialization failed and cleanup failed',
+      )
+    }
+    throw cause
   }
-
-  return app
 }
 
 export { MAX_LIST_LIMIT } from './list-query'
@@ -652,6 +746,12 @@ export {
   asTypeId,
 } from './typeid'
 export type { TypeId } from './typeid'
+export type {
+  DatabaseAdapter,
+  DatabaseConnectOptions,
+  DatabaseConnection,
+  DatabaseConnectionResult,
+} from './database/adapter'
 export type { StorageAdapter } from './storage/index'
 export type {
   StorageConfigInput,
@@ -662,4 +762,9 @@ export type {
 export type { TransformSpec } from './storage/thumbnails'
 
 export type { RealtimeAction } from './realtime/index'
-export type { RealtimeFacade, SchemaTable } from './realtime/facade'
+export { createRealtimeFacade } from './realtime/facade'
+export type {
+  RealtimeFacade,
+  RealtimeTransport,
+  SchemaTable,
+} from './realtime/facade'