bunderstack 0.8.0 → 0.9.1

package/README.md

@@ -82,6 +82,32 @@ import { app } from './bunderstack'
 await app.runWorker()
 ```
 
+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
+process-local memory broker and is suitable only when the worker is embedded
+with `app.startWorker()`.
+
+Since 0.9.0, `app.runWorker()` rejects that unsafe combination by default. If
+queue handlers never publish realtime events, acknowledge the process-local
+behavior with `app.runWorker({ allowProcessLocalRealtime: true })`.
+
+Inspect the active runtime with `app.realtime.transport` (`'disabled'`,
+`'memory'`, or `'redis'`). Deploy tooling can read the configured transport
+from `app.manifest.realtimeTransport`.
+
+```ts
+const app = await createBunderstack({
+  // ...
+  realtime: { redis: process.env.REDIS_URL! },
+})
+```
+
+```bash
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "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",

package/src/index.ts

@@ -50,7 +50,11 @@ import {
   PROVISION_INTERNALS,
   type WithProvisionInternals,
 } from './provision-internals'
-import { createRealtimeFacade, type RealtimeFacade } from './realtime/facade'
+import {
+  createRealtimeFacade,
+  type RealtimeFacade,
+  type RealtimeTransport,
+} from './realtime/facade'
 import { createRealtimeBroker, buildRealtimeRouter } from './realtime/index'
 import { createRedisRealtimeBroker } from './realtime/redis'
 import { deleteFileWithDerivatives } from './storage/delete'
@@ -93,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
@@ -106,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'
@@ -362,10 +374,15 @@ export async function createBunderstack<
       typeof config.realtime === 'object'
         ? config.realtime.bufferSize
         : undefined
-    const redisUrl =
-      config.realtime && !introspect
-        ? resolveRealtimeRedisUrl(config.realtime, env)
-        : undefined
+    const configuredRedisUrl = config.realtime
+      ? resolveRealtimeRedisUrl(config.realtime, env)
+      : undefined
+    const configuredRealtimeTransport: RealtimeTransport = !config.realtime
+      ? 'disabled'
+      : configuredRedisUrl
+        ? 'redis'
+        : 'memory'
+    const redisUrl = introspect ? undefined : configuredRedisUrl
     const broker = config.realtime
       ? redisUrl
         ? createRedisRealtimeBroker({
@@ -400,7 +417,15 @@ export async function createBunderstack<
             bufferSize: realtimeBufferSize,
           })
       : undefined
-    const realtime = createRealtimeFacade<TSchema>(broker)
+    const runtimeRealtimeTransport: RealtimeTransport = !broker
+      ? 'disabled'
+      : redisUrl
+        ? 'redis'
+        : 'memory'
+    const realtime = createRealtimeFacade<TSchema>(
+      broker,
+      runtimeRealtimeTransport,
+    )
     const crudRouter = buildCrudRouter(options.schema, userDb, {
       auth: authResolver,
       access: resolvedAccess,
@@ -526,12 +551,24 @@ export async function createBunderstack<
     const runWorker = async (
       options: AppRunWorkerOptions = {},
     ): Promise<void> => {
-      const handle = await startWorker(options)
+      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 = options.signal
-          ? AbortSignal.any([lifecycle.signal, options.signal])
+        const signal = workerOptions.signal
+          ? AbortSignal.any([lifecycle.signal, workerOptions.signal])
           : lifecycle.signal
-        await waitForWorkerShutdown(signal, !options.signal)
+        await waitForWorkerShutdown(signal, !workerOptions.signal)
       } finally {
         await handle.close()
         await lifecycle.close()
@@ -613,6 +650,7 @@ export async function createBunderstack<
         storage: config.storage,
         envConfig: options.env as EnvConfigInput | undefined,
         realtime: Boolean(config.realtime),
+        realtimeTransport: configuredRealtimeTransport,
         jobs: jobsDefs,
       }),
     }
@@ -724,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'

package/src/manifest.ts

@@ -8,6 +8,7 @@ import { getTableName, isTable } from 'drizzle-orm'
 import type { Dialect } from './dialect'
 import type { EnvConfigInput } from './env'
 import type { JobsDefs } from './jobs/define'
+import type { RealtimeTransport } from './realtime/facade'
 import type { ResolvedBucket, ResolvedStorageBuckets } from './storage/buckets'
 import {
   bunderstackCronRuns,
@@ -29,6 +30,7 @@ export type BunderstackManifest = {
   defaultBucket: string
   buckets: { name: string; visibility: ResolvedBucket['visibility'] }[]
   realtime: boolean
+  realtimeTransport: RealtimeTransport
   env: { server: ManifestEnvVar[]; client: ManifestEnvVar[] }
   background: {
     jobs: { name: string }[]
@@ -60,6 +62,7 @@ export function buildManifest(args: {
   storage: ResolvedStorageBuckets
   envConfig: EnvConfigInput | undefined
   realtime: boolean
+  realtimeTransport: RealtimeTransport
   jobs: JobsDefs | undefined
 }): BunderstackManifest {
   return {
@@ -78,6 +81,7 @@ export function buildManifest(args: {
       visibility: bucket.visibility,
     })),
     realtime: args.realtime,
+    realtimeTransport: args.realtimeTransport,
     env: {
       server: describeSection(args.envConfig?.server),
       client: describeSection(args.envConfig?.client),

package/src/realtime/facade.ts

@@ -2,6 +2,8 @@ import { getTableName, type InferSelectModel, type Table } from 'drizzle-orm'
 
 import type { RealtimeAction, RealtimeBroker } from './index'
 
+export type RealtimeTransport = 'disabled' | 'memory' | 'redis'
+
 export type SchemaTable<TSchema extends Record<string, unknown>> = Extract<
   TSchema[keyof TSchema],
   Table
@@ -11,6 +13,7 @@ export interface RealtimeFacade<
   TSchema extends Record<string, unknown> = Record<string, unknown>,
 > {
   readonly enabled: boolean
+  readonly transport: RealtimeTransport
 
   publish<TTable extends SchemaTable<TSchema>>(
     table: TTable,
@@ -21,9 +24,22 @@ export interface RealtimeFacade<
 
 export function createRealtimeFacade<TSchema extends Record<string, unknown>>(
   broker?: RealtimeBroker,
+  transport: RealtimeTransport = broker ? 'memory' : 'disabled',
 ): RealtimeFacade<TSchema> {
+  if (!broker && transport !== 'disabled') {
+    throw new Error(
+      '[bunderstack] an enabled realtime transport requires a broker',
+    )
+  }
+  if (broker && transport === 'disabled') {
+    throw new Error(
+      '[bunderstack] a realtime broker cannot use the disabled transport',
+    )
+  }
+
   return {
     enabled: broker !== undefined,
+    transport,
     async publish(table, action, record) {
       if (!broker) return
       await broker.publish(