bunderstack 0.14.0 → 0.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.14.0",
+  "version": "0.15.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",
@@ -20,6 +20,9 @@
     "url": "git+https://github.com/kirill-dev-pro/bunderstack.git",
     "directory": "packages/bunderstack"
   },
+  "bin": {
+    "bunderstack": "./src/cli.ts"
+  },
   "files": [
     "src",
     "!src/**/*.test.ts",
@@ -30,9 +33,6 @@
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "types": "./src/index.ts",
-  "bin": {
-    "bunderstack": "./src/cli.ts"
-  },
   "exports": {
     ".": "./src/index.ts",
     "./access": "./src/access.ts",

package/src/config.ts

@@ -197,12 +197,23 @@ export function resolveConfig<TSchema extends Record<string, unknown>>(
 export function resolveRealtimeRedisUrl(
   realtime: ResolvedConfig['realtime'],
   env?: BaseEnv,
+  platformSource: Record<string, string | undefined> = process.env as Record<
+    string,
+    string | undefined
+  >,
 ): string | undefined {
+  const platformRedis = platformSource['REDIS_URL']
+  if (platformRedis) return platformRedis
+
+  const envRedis = env?.REDIS_URL
+  if (envRedis) return envRedis
+
   const fromConfig =
     typeof realtime === 'object' && realtime.redis
       ? typeof realtime.redis === 'string'
         ? realtime.redis
         : realtime.redis.url
       : undefined
-  return fromConfig ?? env?.REDIS_URL ?? process.env.REDIS_URL ?? undefined
+
+  return fromConfig ?? undefined
 }

package/src/index.ts

@@ -407,6 +407,7 @@ export async function createBunderstack<
       ? redisUrl
         ? createRedisRealtimeBroker({
             access: resolvedAccess,
+            channel: process.env.BUNDERSTACK_REALTIME_CHANNEL || undefined,
             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.
@@ -487,9 +488,7 @@ export async function createBunderstack<
       },
       async getUrl(key, opts = {}) {
         const bucketName =
-          opts.bucket ??
-          key.split('/')[0] ??
-          config.storage.defaultBucket
+          opts.bucket ?? key.split('/')[0] ?? config.storage.defaultBucket
         const adapter = registry.get(bucketName)?.adapter
         if (adapter?.presignGet) {
           return adapter.presignGet(key, {
@@ -503,7 +502,10 @@ export async function createBunderstack<
         const adapter = registry.get(bucketName)?.adapter
         if (!adapter) throw new Error(`Unknown bucket: ${bucketName}`)
         const u8 = body instanceof Uint8Array ? body : new Uint8Array(body)
-        const buf: ArrayBuffer = u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength) as ArrayBuffer
+        const buf: ArrayBuffer = u8.buffer.slice(
+          u8.byteOffset,
+          u8.byteOffset + u8.byteLength,
+        ) as ArrayBuffer
         await adapter.upload(key, buf, contentType)
         await insertReadyFile(db, {
           fileId: key,

package/src/jobs/cron-runner.ts

@@ -20,14 +20,22 @@ export async function runScheduledSlot(args: {
   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 + LEASE_MS
+  const leaseUntil = now + leaseMs
   const inserted = await db
     .insert(t)
     .values({
@@ -39,9 +47,12 @@ export async function runScheduledSlot(args: {
       startedAt: now,
     })
     .onConflictDoNothing({ target: [t.taskId, t.scheduledAt] })
-    .returning({ taskId: t.taskId })
+    .returning({ taskId: t.taskId, attempts: t.attempts })
 
-  if (!inserted[0]) {
+  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)
@@ -68,24 +79,118 @@ export async function runScheduledSlot(args: {
           or(eq(t.status, 'failed'), lt(t.lockedUntil, now)),
         ),
       )
-      .returning({ taskId: t.taskId })
-    if (!reclaimed[0]) return { status: 'running' }
+      .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))
-    await db
+
+    const updated = await db
       .update(t)
       .set({ status: 'succeeded', lockedUntil: null, finishedAt: Date.now() })
-      .where(and(eq(t.taskId, taskId), eq(t.scheduledAt, slot)))
+      .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)))
+      .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()
   }
 }
 
@@ -96,6 +201,9 @@ export async function runCronSlot(args: {
   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') {
@@ -107,6 +215,10 @@ export async function runCronSlot(args: {
     schedule: definition.schedule,
     slot: args.slot,
     now: args.now,
-    run: (scheduledFor) => definition.handler({ scheduledFor }, args.ctx as never),
+    leaseMs: args.leaseMs,
+    heartbeatIntervalMs: args.heartbeatIntervalMs,
+    heartbeatCleanupTimeoutMs: args.heartbeatCleanupTimeoutMs,
+    run: (scheduledFor) =>
+      definition.handler({ scheduledFor }, args.ctx as never),
   })
 }

package/src/realtime/redis.ts

@@ -125,7 +125,8 @@ export function createRedisRealtimeBroker(opts: {
     if (typeof entry.get === 'function') return false
     if (!checkAccessSync(entry.get, ctx, entry.ownerColumn).allowed)
       return false
-    if (entry.readScope && !rowMatchesScope(record, entry.readScope(ctx))) return false
+    if (entry.readScope && !rowMatchesScope(record, entry.readScope(ctx)))
+      return false
     return true
   }
 
@@ -140,7 +141,10 @@ export function createRedisRealtimeBroker(opts: {
   let closed = false
 
   const start = () => {
-    if (closed) return Promise.reject(new Error('[bunderstack] realtime broker is closed'))
+    if (closed)
+      return Promise.reject(
+        new Error('[bunderstack] realtime broker is closed'),
+      )
     started ??= getRedis()
       .subscribe(channel, (message) => {
         const evt = parseWireEvent(message)