bunderstack 0.4.0 → 0.6.0

package/src/jobs/cron-auth.ts

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

@@ -0,0 +1,131 @@
+import { Hono } from 'hono'
+import { and, eq, lt } from 'drizzle-orm'
+
+import type { AnyDb } from '../dialect'
+import type { BackgroundDefs } from './define'
+
+import { verifyScheduleRequest } from './cron-auth'
+import { runCronSlot, runScheduledSlot } from './cron-runner'
+import { cronRunsTableFor } from '../internal-tables'
+
+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

@@ -0,0 +1,112 @@
+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
+}): Promise<CronRunResult> {
+  const { db, taskId, schedule, slot, now, run } = args
+  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 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 })
+
+  if (!inserted[0]) {
+    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 })
+    if (!reclaimed[0]) return { status: 'running' }
+  }
+
+  try {
+    await run(new Date(slot))
+    await db
+      .update(t)
+      .set({ status: 'succeeded', lockedUntil: null, finishedAt: Date.now() })
+      .where(and(eq(t.taskId, taskId), eq(t.scheduledAt, slot)))
+    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)))
+    throw error
+  }
+}
+
+export async function runCronSlot(args: {
+  db: AnyDb
+  defs: BackgroundDefs
+  ctx: Record<string, unknown>
+  name: string
+  slot: number
+  now: 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,
+    run: (scheduledFor) => definition.handler({ scheduledFor }, args.ctx as never),
+  })
+}

package/src/jobs/define.ts

@@ -13,7 +13,7 @@ export const DEFAULT_RETRIES = 3
 export const DEFAULT_TIMEOUT_MS = 60_000
 
 export type EnqueueOptions = {
-  /** Collapse duplicate enqueues; see spec for cron vs non-cron lifetime. */
+  /** Collapse duplicate enqueues while the queue row is non-terminal. */
   dedupeKey?: string
   /** Milliseconds from now until the job becomes claimable. */
   delay?: number
@@ -46,11 +46,12 @@ export type JobContext<
   jobs: JobsRuntimeFacade
 }
 
-export type JobDefinition<
+export type QueueJobDefinition<
   TInput,
   TSchema extends Record<string, unknown> = Record<string, unknown>,
   TEnvResult = Record<string, unknown>,
 > = {
+  kind: 'job'
   /** zod schema for the payload; parsed at enqueue AND before the handler runs. */
   input?: ZodType<TInput>
   /** Attempts after the first failure. Default 3 (so 4 total attempts). */
@@ -61,8 +62,6 @@ export type JobDefinition<
   concurrency?: number
   /** Lease duration in ms; an expired lease sends the job back to pending. */
   timeout?: number
-  /** 5-field UTC cron expression. Cron jobs cannot declare `input`. */
-  cron?: string
   handler: (
     input: TInput,
     ctx: JobContext<TSchema, TEnvResult>,
@@ -75,23 +74,51 @@ export type JobDefinition<
   ) => Promise<void> | void
 }
 
+export type CronInvocation = { scheduledFor: Date }
+
+export type CronDefinition<
+  TSchema extends Record<string, unknown> = Record<string, unknown>,
+  TEnvResult = Record<string, unknown>,
+> = {
+  kind: 'cron'
+  schedule: string
+  handler: (
+    invocation: CronInvocation,
+    ctx: JobContext<TSchema, TEnvResult>,
+  ) => Promise<void> | void
+}
+
+export type BackgroundDefinition =
+  | QueueJobDefinition<any, any, any>
+  | CronDefinition<any, any>
+export type BackgroundDefs = Record<string, BackgroundDefinition>
+
+/** @deprecated Use QueueJobDefinition. */
+export type JobDefinition<TInput, TSchema extends Record<string, unknown> = Record<string, unknown>, TEnvResult = Record<string, unknown>> = QueueJobDefinition<
+  TInput,
+  TSchema,
+  TEnvResult
+>
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type AnyJobDefinition = JobDefinition<any, any, any>
-export type JobsDefs = Record<string, AnyJobDefinition>
+export type AnyJobDefinition = QueueJobDefinition<any, any, any>
+export type JobsDefs = BackgroundDefs
+
+export type QueueJobKeys<TDefs extends BackgroundDefs> = {
+  [K in keyof TDefs & string]: TDefs[K] extends QueueJobDefinition<any, any, any>
+    ? K
+    : never
+}[keyof TDefs & string]
 
 /** Throws when a definition is unusable. Safe to call more than once. */
-export function validateJobsDefs(defs: JobsDefs): void {
+export function validateBackgroundDefs(defs: BackgroundDefs): void {
   for (const [name, def] of Object.entries(defs)) {
     if (typeof def.handler !== 'function') {
-      throw new Error(`[bunderstack] job "${name}" has no handler`)
+      throw new Error(`[bunderstack] background task "${name}" has no handler`)
     }
-    if (def.cron !== undefined) {
-      parseCron(def.cron) // throws with a clear message on invalid expressions
-      if (def.input !== undefined) {
-        throw new Error(
-          `[bunderstack] job "${name}": cron jobs cannot declare input (nothing enqueues a payload for a schedule)`,
-        )
-      }
+    if (def.kind === 'cron') {
+      parseCron(def.schedule)
+      continue
     }
     if (def.retries !== undefined && (def.retries < 0 || !Number.isInteger(def.retries))) {
       throw new Error(`[bunderstack] job "${name}": retries must be a non-negative integer`)
@@ -105,6 +132,9 @@ export function validateJobsDefs(defs: JobsDefs): void {
   }
 }
 
+/** @deprecated Use validateBackgroundDefs. */
+export const validateJobsDefs = validateBackgroundDefs
+
 /** Delay in ms before retry `attempt` (1-based = the attempt that just failed). */
 export function backoffMs(def: AnyJobDefinition, attempt: number): number {
   const b = def.backoff
@@ -125,13 +155,19 @@ export function createJobsBuilder<
   return {
     /** Identity with inference: pins TInput from the zod schema. */
     job<TInput = undefined>(
-      def: JobDefinition<TInput, TSchema, TEnvResult>,
-    ): JobDefinition<TInput, TSchema, TEnvResult> {
-      return def
+      def: Omit<QueueJobDefinition<TInput, TSchema, TEnvResult>, 'kind'>,
+    ): QueueJobDefinition<TInput, TSchema, TEnvResult> {
+      return { kind: 'job', ...def }
+    },
+    cron(
+      def: Omit<CronDefinition<TSchema, TEnvResult>, 'kind'>,
+    ): CronDefinition<TSchema, TEnvResult> {
+      parseCron(def.schedule)
+      return { kind: 'cron', ...def }
     },
     /** Identity with validation: returns the defs map, typed. */
-    define<TDefs extends JobsDefs>(defs: TDefs): TDefs {
-      validateJobsDefs(defs)
+    define<TDefs extends BackgroundDefs>(defs: TDefs): TDefs {
+      validateBackgroundDefs(defs)
       return defs
     },
   }
@@ -148,7 +184,7 @@ export type BunderstackJobsBuilder<
 // `TDef extends { input: ZodType<infer I> }` fails structurally because
 // `input?: ZodType<TInput>` desugars to `ZodType<TInput> | undefined`, which
 // can never satisfy a required-property pattern.
-type JobInputOf<TDef> = TDef extends JobDefinition<infer TInput, any, any>
+type JobInputOf<TDef> = TDef extends QueueJobDefinition<infer TInput, any, any>
   ? TInput
   : undefined
 
@@ -162,7 +198,7 @@ export type JobsFacade<TDefs extends JobsDefs> = Omit<
   JobsRuntimeFacade,
   'enqueue'
 > & {
-  enqueue<K extends keyof TDefs & string>(
+  enqueue<K extends QueueJobKeys<TDefs>>(
     name: K,
     ...rest: JobInputOf<TDefs[K]> extends undefined
       ? [input?: undefined, opts?: EnqueueOptions]

package/src/jobs/index.ts

@@ -1,20 +1,38 @@
 // src/jobs/index.ts — module surface consumed by createBunderstack.
 export {
   createJobsBuilder,
+  validateBackgroundDefs,
   validateJobsDefs,
   DEFAULT_RETRIES,
   DEFAULT_TIMEOUT_MS,
 } from './define'
 export type {
   AnyJobDefinition,
+  BackgroundDefinition,
+  BackgroundDefs,
   BunderstackJobsBuilder,
   EnqueueOptions,
   JobContext,
   JobDefinition,
+  QueueJobDefinition,
+  CronDefinition,
+  CronInvocation,
+  QueueJobKeys,
   JobsDefs,
   JobsFacade,
   JobsRuntimeFacade,
 } from './define'
 export { enqueueJob } from './queue'
 export { createJobRunner } from './worker'
+export { runCronSlot, runScheduledSlot } from './cron-runner'
+export type { CronRunResult } from './cron-runner'
+export { buildCronRouter } from './cron-router'
+export { signScheduleRequest, verifyScheduleRequest } from './cron-auth'
+export { startJobWorker } from './runtime'
+export type { StartWorkerOptions, RunWorkerOptions, WorkerHandle } from './runtime'
+export { startLocalCronScheduler } from './local-cron'
+export type {
+  LocalCronScheduler,
+  LocalCronSchedulerOptions,
+} from './local-cron'
 export { parseCron, cronMatches } from './cron'

package/src/jobs/local-cron.ts

@@ -0,0 +1,76 @@
+import { cronMatches, parseCron } from './cron'
+
+type Timer = ReturnType<typeof setTimeout>
+
+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
+      }
+    },
+  }
+}

package/src/jobs/queue.ts

@@ -15,7 +15,9 @@ export async function enqueueJob(
   opts: EnqueueOptions = {},
 ): Promise<{ id: string }> {
   const def = defs[name]
-  if (!def) throw new Error(`[bunderstack] unknown job type "${name}"`)
+  if (!def || def.kind !== 'job') {
+    throw new Error(`[bunderstack] unknown queue job "${name}"`)
+  }
   // Fail fast: a bad payload should throw at the call site, not in the worker.
   const parsed = def.input ? def.input.parse(input) : null
   const t = jobsTableFor(db)

package/src/jobs/runtime.ts

@@ -0,0 +1,58 @@
+export type WorkerHandle = {
+  readonly closed: Promise<void>
+  close(): Promise<void>
+}
+
+export type StartWorkerOptions = {
+  signal?: AbortSignal
+  pollIntervalMs?: number
+  tick: (now: number) => Promise<void>
+  onError?: (error: Error) => void
+}
+
+export type RunWorkerOptions = StartWorkerOptions
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+function wait(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal.aborted) return resolve()
+    const timer = setTimeout(done, ms)
+    function done() {
+      clearTimeout(timer)
+      signal.removeEventListener('abort', done)
+      resolve()
+    }
+    signal.addEventListener('abort', done, { once: true })
+  })
+}
+
+export function startJobWorker(options: StartWorkerOptions): WorkerHandle {
+  const controller = new AbortController()
+  const pollIntervalMs = options.pollIntervalMs ?? 1_000
+  const abort = () => controller.abort()
+  options.signal?.addEventListener('abort', abort, { once: true })
+  if (options.signal?.aborted) abort()
+
+  const closed = (async () => {
+    try {
+      while (!controller.signal.aborted) {
+        try {
+          await options.tick(Date.now())
+        } catch (error) {
+          options.onError?.(toError(error))
+        }
+        await wait(pollIntervalMs, controller.signal)
+      }
+    } finally {
+      options.signal?.removeEventListener('abort', abort)
+    }
+  })()
+  const close = () => {
+    controller.abort()
+    return closed
+  }
+  return { closed, close }
+}