bunderstack 0.4.0 → 0.6.0

package/src/jobs/worker.ts

@@ -1,8 +1,5 @@
-// src/jobs/worker.ts — the in-process worker. One `tick()` is a full cycle:
-// recover expired leases → schedule cron slots → reap old succeeded rows →
-// claim and run claimable jobs (awaiting handlers, so tests drive `tick()`
-// deterministically with an injected `now`). Multiple replicas run the same
-// loop safely: claims are atomic and cron slots dedupe on a unique index.
+// src/jobs/worker.ts — the queue worker. One `tick()` is a full cycle:
+// recover expired leases → reap old succeeded rows → claim and run queue jobs.
 import { and, eq, inArray, is, isNotNull, lt, lte, sql } from 'drizzle-orm'
 import { PgDatabase } from 'drizzle-orm/pg-core'
 
@@ -12,12 +9,9 @@ import type {
   JobsDefs,
   JobsRuntimeFacade,
 } from './define'
-import type { ParsedCron } from './cron'
 
 import { jobsTableFor } from '../internal-tables'
-import { cronMatches, parseCron } from './cron'
 import { backoffMs, DEFAULT_RETRIES, DEFAULT_TIMEOUT_MS } from './define'
-import { enqueueJob } from './queue'
 
 const CLAIM_BATCH = 10
 const SUCCEEDED_RETENTION_MS = 24 * 60 * 60 * 1000
@@ -37,9 +31,9 @@ function maxAttempts(def: AnyJobDefinition): number {
   return 1 + (def.retries ?? DEFAULT_RETRIES)
 }
 
-/** Terminal-status column patch: non-cron jobs release their dedupe key. */
-function terminalPatch(def: AnyJobDefinition | undefined) {
-  return def?.cron ? {} : { dedupeKey: null }
+/** Terminal queue rows release their dedupe key. */
+function terminalPatch() {
+  return { dedupeKey: null }
 }
 
 export function createJobRunner(deps: {
@@ -51,11 +45,6 @@ export function createJobRunner(deps: {
   const { db, defs } = deps
   const t = jobsTableFor(db)
   const ctx = { ...deps.ctx } as Record<string, unknown>
-  const crons = new Map<string, ParsedCron>()
-  for (const [name, def] of Object.entries(defs)) {
-    if (def.cron) crons.set(name, parseCron(def.cron))
-  }
-
   async function fireOnFailed(
     def: AnyJobDefinition,
     payloadJson: string,
@@ -93,7 +82,7 @@ export function createJobRunner(deps: {
     for (const row of expired) {
       const def = defs[row.type]
       const error = new Error('lease expired (worker crashed or timed out)')
-      if (!def) {
+      if (!def || def.kind !== 'job') {
         await db
           .update(t)
           .set({
@@ -114,7 +103,7 @@ export function createJobRunner(deps: {
             finishedAt: now,
             lockedUntil: null,
             lastError: error.message,
-            ...terminalPatch(def),
+            ...terminalPatch(),
           })
           .where(eq(t.id, row.id))
         await fireOnFailed(def, row.payloadJson, error)
@@ -132,20 +121,6 @@ export function createJobRunner(deps: {
     }
   }
 
-  /** Enqueue the current minute's slot for every cron definition. */
-  async function scheduleCronSlots(now: number) {
-    const minute = Math.floor(now / 60_000) * 60_000
-    for (const [name, cron] of crons) {
-      if (!cronMatches(cron, minute)) continue
-      // The unique (type, dedupe_key) index collapses concurrent replicas'
-      // enqueues of the same slot into one row.
-      await enqueueJob(db, defs, name, undefined, {
-        dedupeKey: `cron:${name}:${minute}`,
-        runAt: minute,
-      })
-    }
-  }
-
   async function reapSucceeded(now: number) {
     await db
       .delete(t)
@@ -211,7 +186,7 @@ export function createJobRunner(deps: {
           finishedAt: Date.now(),
           lockedUntil: null,
           lastError: e.message,
-          ...terminalPatch(def),
+          ...terminalPatch(),
         })
         .where(eq(t.id, row.id))
       await fireOnFailed(def, row.payloadJson, e)
@@ -225,7 +200,7 @@ export function createJobRunner(deps: {
           status: 'succeeded',
           finishedAt: Date.now(),
           lockedUntil: null,
-          ...terminalPatch(def),
+          ...terminalPatch(),
         })
         .where(eq(t.id, row.id))
     } catch (err) {
@@ -248,7 +223,7 @@ export function createJobRunner(deps: {
             finishedAt: Date.now(),
             lockedUntil: null,
             lastError: e.message,
-            ...terminalPatch(def),
+            ...terminalPatch(),
           })
           .where(eq(t.id, row.id))
         await fireOnFailed(def, row.payloadJson, e)
@@ -258,7 +233,9 @@ export function createJobRunner(deps: {
 
   async function runClaimable(now: number) {
     const work: Promise<void>[] = []
-    for (const [type, def] of Object.entries(defs)) {
+    for (const [type, candidate] of Object.entries(defs)) {
+      if (candidate.kind !== 'job') continue
+      const def = candidate
       let limit = CLAIM_BATCH
       if (def.concurrency !== undefined) {
         const runningRows = await db
@@ -279,7 +256,6 @@ export function createJobRunner(deps: {
   return {
     async tick(now: number = Date.now()) {
       await recoverExpiredLeases(now)
-      await scheduleCronSlots(now)
       await reapSucceeded(now)
       await runClaimable(now)
     },

package/src/lifecycle.ts

@@ -0,0 +1,44 @@
+export type Cleanup = () => void | Promise<void>
+export type LifecycleStatus = 'ready' | 'closing' | 'closed'
+
+export class Lifecycle {
+  #controller = new AbortController()
+  #status: LifecycleStatus = 'ready'
+  #cleanups = new Set<Cleanup>()
+  #closePromise: Promise<void> | undefined
+
+  get signal(): AbortSignal {
+    return this.#controller.signal
+  }
+
+  get status(): LifecycleStatus {
+    return this.#status
+  }
+
+  add(cleanup: Cleanup): () => void {
+    if (this.#status !== 'ready') {
+      throw new Error('[bunderstack] application lifecycle is closed')
+    }
+    this.#cleanups.add(cleanup)
+    return () => this.#cleanups.delete(cleanup)
+  }
+
+  close(): Promise<void> {
+    if (this.#closePromise) return this.#closePromise
+    this.#status = 'closing'
+    this.#controller.abort()
+    this.#closePromise = (async () => {
+      const cleanups = [...this.#cleanups].reverse()
+      this.#cleanups.clear()
+      const results = await Promise.allSettled(cleanups.map((cleanup) => cleanup()))
+      this.#status = 'closed'
+      const errors = results.flatMap((result) =>
+        result.status === 'rejected' ? [result.reason] : [],
+      )
+      if (errors.length > 0) {
+        throw new AggregateError(errors, '[bunderstack] lifecycle cleanup failed')
+      }
+    })()
+    return this.#closePromise
+  }
+}

package/src/manifest.ts

@@ -3,23 +3,46 @@
 // Deployment platforms (Bunderhost) import the app declaration with
 // BUNDERSTACK_INTROSPECT=1 and read `app.manifest` to learn what to provision.
 import type { ZodType } from 'zod'
+import { getTableName, isTable } from 'drizzle-orm'
 
 import type { Dialect } from './dialect'
 import type { EnvConfigInput } from './env'
 import type { JobsDefs } from './jobs/define'
 import type { ResolvedBucket, ResolvedStorageBuckets } from './storage/buckets'
+import {
+  bunderstackCronRuns,
+  bunderstackFiles,
+  bunderstackJobs,
+} from './internal-tables'
 
 export type ManifestEnvVar = { key: string; required: boolean }
-export type ManifestJob = { name: string; cron?: string }
-
 export type BunderstackManifest = {
+  version: 2
   dialect: Dialect
   tables: string[]
+  tableMap: Record<string, string>
+  systemTables: {
+    jobs: string
+    files: string
+    scheduledRuns: string
+  }
   defaultBucket: string
   buckets: { name: string; visibility: ResolvedBucket['visibility'] }[]
   realtime: boolean
   env: { server: ManifestEnvVar[]; client: ManifestEnvVar[] }
-  jobs: ManifestJob[]
+  background: {
+    jobs: { name: string }[]
+    cron: { name: string; schedule: string; timezone: 'UTC' }[]
+    maintenance: { name: 'storage-sweep'; schedule: string }[]
+  }
+}
+
+function describeTables(schema: Record<string, unknown>): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(schema).flatMap(([key, value]) =>
+      isTable(value) ? [[key, getTableName(value)]] : [],
+    ),
+  )
 }
 
 function describeSection(
@@ -40,8 +63,15 @@ export function buildManifest(args: {
   jobs: JobsDefs | undefined
 }): BunderstackManifest {
   return {
+    version: 2,
     dialect: args.dialect,
     tables: Object.keys(args.schema),
+    tableMap: describeTables(args.schema),
+    systemTables: {
+      jobs: getTableName(bunderstackJobs),
+      files: getTableName(bunderstackFiles),
+      scheduledRuns: getTableName(bunderstackCronRuns),
+    },
     defaultBucket: args.storage.defaultBucket,
     buckets: [...args.storage.buckets.values()].map((bucket) => ({
       name: bucket.name,
@@ -52,8 +82,18 @@ export function buildManifest(args: {
       server: describeSection(args.envConfig?.server),
       client: describeSection(args.envConfig?.client),
     },
-    jobs: Object.entries(args.jobs ?? {}).map(([name, def]) =>
-      def.cron !== undefined ? { name, cron: def.cron } : { name },
-    ),
+    background: {
+      jobs: Object.entries(args.jobs ?? {})
+        .filter(([, def]) => def.kind === 'job')
+        .map(([name]) => ({ name })),
+      cron: Object.entries(args.jobs ?? {})
+        .filter(([, def]) => def.kind === 'cron')
+        .map(([name, def]) => ({
+          name,
+          schedule: def.kind === 'cron' ? def.schedule : '',
+          timezone: 'UTC' as const,
+        })),
+      maintenance: [{ name: 'storage-sweep', schedule: '0 4 * * *' }],
+    },
   }
 }

package/src/realtime/index.ts

@@ -35,6 +35,8 @@ type RealtimeContextBody = {
 }
 
 export type RealtimeBroker = {
+  start(): Promise<void>
+  close(): Promise<void>
   register(send: (data: string) => void): { id: string }
   setContext(
     id: string,
@@ -84,8 +86,8 @@ function scopeOk(
   ctx: Parameters<typeof checkAccessSync>[1],
   record: Record<string, unknown>,
 ): boolean {
-  if (!entry.scope) return true
-  return rowMatchesScope(record, entry.scope(ctx))
+  if (!entry.readScope) return true
+  return rowMatchesScope(record, entry.readScope(ctx))
 }
 
 export function buildRealtimeRouter(
@@ -101,7 +103,8 @@ export function buildRealtimeRouter(
     let keepalive: ReturnType<typeof setInterval>
 
     const stream = new ReadableStream({
-      start(controller) {
+      async start(controller) {
+        await broker.start()
         const send = (data: string) =>
           controller.enqueue(encoder.encode(`data: ${data}\n\n`))
         handle = broker.register(send)
@@ -183,6 +186,8 @@ export function createRealtimeBroker(opts: {
   }
 
   return {
+    async start() {},
+    async close() {},
     register(send) {
       const id = crypto.randomUUID()
       subscribers.set(id, {

package/src/realtime/redis.ts

@@ -27,6 +27,7 @@ export type RedisLike = {
   lpush(key: string, value: string): Promise<unknown>
   ltrim(key: string, start: number, stop: number): Promise<unknown>
   lrange(key: string, start: number, stop: number): Promise<string[]>
+  close?(): void | Promise<void>
 }
 
 type Subscriber = {
@@ -86,15 +87,22 @@ function parseWireEvent(raw: string): WireEvent | null {
 
 export function createRedisRealtimeBroker(opts: {
   access: ResolvedAccess
-  redis: RedisLike
+  /** A factory keeps Redis completely cold until SSE or a publish needs it. */
+  redis: RedisLike | (() => RedisLike)
   bufferSize?: number
   channel?: string
-}): RealtimeBroker & { ready: Promise<void> } {
+}): RealtimeBroker {
   const subscribers = new Map<string, Subscriber>()
   const bufferSize = opts.bufferSize ?? 1000
   const channel = opts.channel ?? 'bunderstack:realtime'
   const logKey = `${channel}:log`
   const counterKey = `${channel}:seq`
+  let redis: RedisLike | undefined
+
+  const getRedis = () => {
+    redis ??= typeof opts.redis === 'function' ? opts.redis() : opts.redis
+    return redis
+  }
 
   function deliverable(
     s: Subscriber,
@@ -117,7 +125,7 @@ export function createRedisRealtimeBroker(opts: {
     if (typeof entry.get === 'function') return false
     if (!checkAccessSync(entry.get, ctx, entry.ownerColumn).allowed)
       return false
-    if (entry.scope && !rowMatchesScope(record, entry.scope(ctx))) return false
+    if (entry.readScope && !rowMatchesScope(record, entry.readScope(ctx))) return false
     return true
   }
 
@@ -128,16 +136,27 @@ export function createRedisRealtimeBroker(opts: {
     }
   }
 
-  // Subscribe once; all local delivery happens here.
-  const ready = opts.redis
-    .subscribe(channel, (message) => {
-      const evt = parseWireEvent(message)
-      if (evt) fanOut(evt)
-    })
-    .then(() => undefined)
+  let started: Promise<void> | undefined
+  let closed = false
+
+  const start = () => {
+    if (closed) return Promise.reject(new Error('[bunderstack] realtime broker is closed'))
+    started ??= getRedis()
+      .subscribe(channel, (message) => {
+        const evt = parseWireEvent(message)
+        if (evt) fanOut(evt)
+      })
+      .then(() => undefined)
+    return started
+  }
 
   return {
-    ready,
+    start,
+    async close() {
+      closed = true
+      subscribers.clear()
+      await redis?.close?.()
+    },
     register(send) {
       const id = crypto.randomUUID()
       subscribers.set(id, {
@@ -164,7 +183,7 @@ export function createRedisRealtimeBroker(opts: {
       // to a full refetch rather than 500-ing the POST handler.
       let raw: string[]
       try {
-        raw = await opts.redis.lrange(logKey, 0, bufferSize - 1)
+        raw = await getRedis().lrange(logKey, 0, bufferSize - 1)
       } catch {
         return { gap: true }
       }
@@ -187,12 +206,13 @@ export function createRedisRealtimeBroker(opts: {
     async publish(table, action, record) {
       if (!tableEntry(opts.access, table)) return
       try {
-        const eventId = await opts.redis.incr(counterKey)
+        const client = getRedis()
+        const eventId = await client.incr(counterKey)
         const evt: WireEvent = { eventId, table, action, record }
         const msg = JSON.stringify(evt)
-        await opts.redis.lpush(logKey, msg)
-        await opts.redis.ltrim(logKey, 0, bufferSize - 1)
-        await opts.redis.publish(channel, msg)
+        await client.lpush(logKey, msg)
+        await client.ltrim(logKey, 0, bufferSize - 1)
+        await client.publish(channel, msg)
       } catch {
         // Broadcast is best-effort: a redis blip must not reject the floating
         // promise (callers use `void broker?.publish(...)` with no .catch).

package/src/storage/buckets.ts

@@ -25,7 +25,10 @@ export type BucketConfigInput = {
   }
   upload?: { maxSize?: string | number; accept?: string[] }
   transforms?: boolean
-  scope?: ScopeResolver
+  scope?: {
+    read?: ScopeResolver
+    write?: ScopeResolver
+  }
   quota?: { perUser?: string | number; perScope?: string | number }
 } & Partial<BucketBackendInput>
 
@@ -59,7 +62,8 @@ export type ResolvedBucket = {
   access: { create: OperationRule; get: OperationRule; delete: OperationRule }
   upload?: { maxSizeBytes?: number; accept?: string[] }
   transforms: boolean
-  scope?: ScopeResolver
+  readScope?: ScopeResolver
+  writeScope?: ScopeResolver
   quota?: { perUserBytes?: number; perScopeBytes?: number }
 }
 
@@ -248,7 +252,8 @@ function resolveSingleBucket(
     access,
     upload,
     transforms: input.transforms ?? false,
-    scope: input.scope,
+    readScope: input.scope?.read,
+    writeScope: input.scope?.write,
     quota,
   }
 }

package/src/storage/router.ts

@@ -165,7 +165,7 @@ export function buildBucketStorageRouter(
     const contentType =
       typeof body.contentType === 'string' ? body.contentType : undefined
 
-    const requesterScope = bucket.scope?.(ctx)
+    const requesterScope = bucket.writeScope?.(ctx)
     const scopeJson = scopeToJson(requesterScope)
 
     // Quota pre-check: reserve the configured max upload size.
@@ -252,7 +252,7 @@ export function buildBucketStorageRouter(
       return apiError(c, ErrorCode.VALIDATION_ERROR, 'File too large', 422)
     }
 
-    const requesterScope = bucket.scope?.(ctx)
+    const requesterScope = bucket.readScope?.(ctx)
     const scopeJson = scopeToJson(requesterScope)
 
     if (bucket.quota) {
@@ -395,7 +395,7 @@ export function buildBucketStorageRouter(
     const denied = await gate(bucket.access.get, ctx, c)
     if (denied) return denied
 
-    const requesterScope = bucket.scope?.(ctx)
+    const requesterScope = bucket.readScope?.(ctx)
     if (!fileMatchesScope(row, requesterScope)) {
       return apiError(c, ErrorCode.NOT_FOUND, 'Not found', 404)
     }
@@ -491,7 +491,7 @@ export function buildBucketStorageRouter(
     const denied = await gate(bucket.access.delete, ctx, c)
     if (denied) return denied
 
-    const requesterScope = bucket.scope?.(ctx)
+    const requesterScope = bucket.readScope?.(ctx)
     if (!fileMatchesScope(row, requesterScope)) {
       return apiError(c, ErrorCode.NOT_FOUND, 'Not found', 404)
     }