@strav/queue 0.4.31 → 1.0.0-alpha.3

package/src/queue/worker.ts

@@ -1,273 +0,0 @@
-import Queue, { hydrateJob } from './queue.ts'
-import Emitter from '@strav/kernel/events/emitter'
-import { checkBreaker, recordFailure, recordSuccess } from './circuit_breaker.ts'
-import type { JobRecord, JobMeta } from './queue.ts'
-
-export interface WorkerOptions {
-  queue?: string
-  sleep?: number
-}
-
-/**
- * Processes jobs from the queue.
- *
- * Uses `SELECT ... FOR UPDATE SKIP LOCKED` for safe concurrent polling.
- * Supports job timeouts, exponential/linear backoff for retries,
- * and graceful shutdown on SIGINT/SIGTERM.
- *
- * @example
- * const worker = new Worker({ queue: 'emails', sleep: 500 })
- * await worker.start() // blocks until worker.stop() is called
- */
-export default class Worker {
-  private running = false
-  private processing = false
-  private queue: string
-  private sleep: number
-
-  constructor(options: WorkerOptions = {}) {
-    this.queue = options.queue ?? Queue.config.default
-    this.sleep = options.sleep ?? Queue.config.sleep
-  }
-
-  /** Start the worker loop. Blocks until stop() is called. */
-  async start(): Promise<void> {
-    this.running = true
-
-    const onSignal = () => this.stop()
-    process.on('SIGINT', onSignal)
-    process.on('SIGTERM', onSignal)
-
-    let pollCount = 0
-
-    try {
-      while (this.running) {
-        // Periodically release stale jobs (every 60 cycles)
-        if (pollCount % 60 === 0) {
-          await this.releaseStaleJobs()
-        }
-        pollCount++
-
-        const job = await this.fetchNext()
-        if (job) {
-          this.processing = true
-          await this.process(job)
-          this.processing = false
-        } else {
-          await Bun.sleep(this.sleep)
-        }
-      }
-    } finally {
-      process.off('SIGINT', onSignal)
-      process.off('SIGTERM', onSignal)
-    }
-  }
-
-  /** Signal the worker to stop after the current job completes. */
-  stop(): void {
-    this.running = false
-  }
-
-  /** Whether the worker is currently processing a job. */
-  get busy(): boolean {
-    return this.processing
-  }
-
-  // ---------------------------------------------------------------------------
-  // Internal
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Fetch the next available job using FOR UPDATE SKIP LOCKED.
-   * Atomically reserves it by setting reserved_at and incrementing attempts.
-   */
-  private async fetchNext(): Promise<JobRecord | null> {
-    const sql = Queue.db.sql
-
-    const rows = await sql.begin(async (tx: any) => {
-      const result = await tx`
-        SELECT * FROM "_strav_jobs"
-        WHERE "queue" = ${this.queue}
-          AND "available_at" <= NOW()
-          AND "reserved_at" IS NULL
-        ORDER BY "available_at" ASC
-        LIMIT 1
-        FOR UPDATE SKIP LOCKED
-      `
-      if (result.length === 0) return []
-
-      const job = result[0] as Record<string, unknown>
-      await tx`
-        UPDATE "_strav_jobs"
-        SET "reserved_at" = NOW(), "attempts" = "attempts" + 1
-        WHERE "id" = ${job.id}
-      `
-      return [{ ...job, attempts: (job.attempts as number) + 1 }]
-    })
-
-    return rows.length > 0 ? hydrateJob(rows[0] as Record<string, unknown>) : null
-  }
-
-  /** Process a single job: run handler, handle success/failure. */
-  private async process(job: JobRecord): Promise<void> {
-    const registration = Queue.handlers.get(job.job)
-
-    if (!registration) {
-      await this.fail(job, new Error(`No handler registered for job "${job.job}"`))
-      return
-    }
-
-    // Q-1: per-handler circuit breaker. If the handler has tripped its
-    // breaker (too many failures in the configured window), defer this
-    // job rather than running it. Push it back to the queue with
-    // `available_at = now + cooldown` so it retries AFTER the breaker
-    // resets — this clears the worker to drain unrelated jobs from the
-    // queue instead of compounding the failure storm.
-    const cooldownRemaining = checkBreaker(job.job)
-    if (cooldownRemaining !== null) {
-      await this.deferForCooldown(job, cooldownRemaining)
-      return
-    }
-
-    const meta: JobMeta = {
-      id: job.id,
-      queue: job.queue,
-      job: job.job,
-      attempts: job.attempts,
-      maxAttempts: job.maxAttempts,
-      progress: (value: number, message?: string) => Queue.reportProgress(job.id, value, message),
-    }
-
-    // Re-parse the payload through the registered schema (CC-5). Catches
-    // payloads that drifted from the handler's expected shape — older
-    // enqueues, manual DB edits, malicious tampering. A parse failure
-    // is fatal: the job goes straight to failed_jobs without retry,
-    // because retrying with the same bad payload won't help.
-    let payload = job.payload
-    if (registration.schema) {
-      try {
-        payload = registration.schema.parse(job.payload)
-      } catch (err) {
-        const detail = err instanceof Error ? err.message : String(err)
-        await this.fail(job, new Error(`Job "${job.job}" payload failed validation: ${detail}`))
-        return
-      }
-    }
-
-    const start = performance.now()
-
-    try {
-      await Promise.race([
-        Promise.resolve(registration.handler(payload, meta)),
-        new Promise<never>((_, reject) =>
-          setTimeout(
-            () => reject(new Error(`Job "${job.job}" timed out after ${job.timeout}ms`)),
-            job.timeout
-          )
-        ),
-      ])
-      await this.complete(job)
-      recordSuccess(job.job)
-
-      if (Emitter.listenerCount('queue:processed') > 0) {
-        const duration = performance.now() - start
-        Emitter.emit('queue:processed', {
-          job: job.job,
-          id: job.id,
-          queue: job.queue,
-          duration,
-        }).catch(() => {})
-      }
-    } catch (error) {
-      const err = error instanceof Error ? error : new Error(String(error))
-      // Update breaker state regardless of retry decision so a job that
-      // exhausts its retries still counts toward the trip threshold.
-      recordFailure(job.job)
-      if (job.attempts >= job.maxAttempts) {
-        await this.fail(job, err)
-
-        if (Emitter.listenerCount('queue:failed') > 0) {
-          const duration = performance.now() - start
-          Emitter.emit('queue:failed', {
-            job: job.job,
-            id: job.id,
-            queue: job.queue,
-            error: err.message,
-            duration,
-          }).catch(() => {})
-        }
-      } else {
-        await this.release(job)
-      }
-    }
-  }
-
-  /** Delete a completed job. */
-  private async complete(job: JobRecord): Promise<void> {
-    await Queue.db.sql`DELETE FROM "_strav_jobs" WHERE "id" = ${job.id}`
-  }
-
-  /** Move a job to the failed_jobs table and delete from jobs. */
-  private async fail(job: JobRecord, error: Error): Promise<void> {
-    const sql = Queue.db.sql
-    await sql.begin(async (tx: any) => {
-      await tx`
-        INSERT INTO "_strav_failed_jobs" ("queue", "job", "payload", "error")
-        VALUES (${job.queue}, ${job.job}, ${JSON.stringify(job.payload)}, ${error.message})
-      `
-      await tx`DELETE FROM "_strav_jobs" WHERE "id" = ${job.id}`
-    })
-  }
-
-  /** Release a job back to the queue with incremented backoff delay. */
-  private async release(job: JobRecord): Promise<void> {
-    const delay = this.backoffDelay(job.attempts)
-    const availableAt = new Date(Date.now() + delay)
-
-    await Queue.db.sql`
-      UPDATE "_strav_jobs"
-      SET "reserved_at" = NULL, "available_at" = ${availableAt}
-      WHERE "id" = ${job.id}
-    `
-  }
-
-  /**
-   * Push a tripped-circuit job back to the queue with `available_at`
-   * scheduled past the cooldown. Also rolls back the attempts counter
-   * the fetcher incremented so a circuit trip doesn't eat retry
-   * budget — the job genuinely never executed.
-   */
-  private async deferForCooldown(job: JobRecord, cooldownMs: number): Promise<void> {
-    const availableAt = new Date(Date.now() + Math.max(cooldownMs, 1_000))
-
-    await Queue.db.sql`
-      UPDATE "_strav_jobs"
-      SET "reserved_at" = NULL,
-          "available_at" = ${availableAt},
-          "attempts" = GREATEST("attempts" - 1, 0)
-      WHERE "id" = ${job.id}
-    `
-  }
-
-  /** Calculate backoff delay in ms based on attempt number. */
-  backoffDelay(attempts: number): number {
-    if (Queue.config.retryBackoff === 'linear') {
-      return attempts * 5_000
-    }
-    // Exponential: 2^attempts * 1000, with jitter
-    const base = Math.pow(2, attempts) * 1000
-    const jitter = Math.random() * 1000
-    return base + jitter
-  }
-
-  /** Release jobs that have been reserved for too long (crashed workers). */
-  private async releaseStaleJobs(): Promise<void> {
-    await Queue.db.sql`
-      UPDATE "_strav_jobs"
-      SET "reserved_at" = NULL
-      WHERE "reserved_at" IS NOT NULL
-        AND "queue" = ${this.queue}
-        AND "reserved_at" < NOW() - MAKE_INTERVAL(secs => "timeout" * 2.0 / 1000)
-    `
-  }
-}

package/src/scheduler/cron.ts

@@ -1,146 +0,0 @@
-/**
- * Minimal 5-field cron expression parser.
- *
- * Supports: `*`, exact (`5`), range (`1-5`), list (`1,3,5`),
- * step (`*​/10`), and range+step (`1-30/5`).
- *
- * Fields: minute (0–59), hour (0–23), day-of-month (1–31),
- * month (1–12), day-of-week (0–6, 0 = Sunday).
- */
-
-export interface CronExpression {
-  minute: number[]
-  hour: number[]
-  dayOfMonth: number[]
-  month: number[]
-  dayOfWeek: number[]
-}
-
-const FIELD_RANGES: [number, number][] = [
-  [0, 59], // minute
-  [0, 23], // hour
-  [1, 31], // day of month
-  [1, 12], // month
-  [0, 6], // day of week
-]
-
-// Parse a 5-field cron string into expanded numeric arrays.
-export function parseCron(expression: string): CronExpression {
-  const parts = expression.trim().split(/\s+/)
-  if (parts.length !== 5) {
-    throw new Error(
-      `Invalid cron expression "${expression}": expected 5 fields, got ${parts.length}`
-    )
-  }
-
-  const [minute, hour, dayOfMonth, month, dayOfWeek] = parts.map((part, i) =>
-    parseField(part, FIELD_RANGES[i]![0], FIELD_RANGES[i]![1])
-  )
-
-  return {
-    minute: minute!,
-    hour: hour!,
-    dayOfMonth: dayOfMonth!,
-    month: month!,
-    dayOfWeek: dayOfWeek!,
-  }
-}
-
-/**
- * Check if a Date matches a parsed cron expression.
- *
- * Standard cron rule: if both day-of-month and day-of-week are restricted
- * (not wildcards), either match satisfies the condition.
- */
-export function cronMatches(cron: CronExpression, date: Date): boolean {
-  const minute = date.getUTCMinutes()
-  const hour = date.getUTCHours()
-  const dayOfMonth = date.getUTCDate()
-  const month = date.getUTCMonth() + 1
-  const dayOfWeek = date.getUTCDay()
-
-  if (!cron.minute.includes(minute)) return false
-  if (!cron.hour.includes(hour)) return false
-  if (!cron.month.includes(month)) return false
-
-  // Standard cron: day-of-month and day-of-week are OR'd when both are restricted
-  const domRestricted = cron.dayOfMonth.length < 31
-  const dowRestricted = cron.dayOfWeek.length < 7
-
-  if (domRestricted && dowRestricted) {
-    return cron.dayOfMonth.includes(dayOfMonth) || cron.dayOfWeek.includes(dayOfWeek)
-  }
-
-  if (!cron.dayOfMonth.includes(dayOfMonth)) return false
-  if (!cron.dayOfWeek.includes(dayOfWeek)) return false
-
-  return true
-}
-
-/**
- * Compute the next Date (UTC) after `after` that matches the expression.
- * Searches up to 2 years ahead to prevent infinite loops.
- */
-export function nextCronDate(cron: CronExpression, after: Date): Date {
-  const date = new Date(after.getTime())
-  // Advance to the next whole minute
-  date.setUTCSeconds(0, 0)
-  date.setUTCMinutes(date.getUTCMinutes() + 1)
-
-  const limit = after.getTime() + 2 * 365 * 24 * 60 * 60 * 1000
-
-  while (date.getTime() <= limit) {
-    if (cronMatches(cron, date)) return date
-    date.setUTCMinutes(date.getUTCMinutes() + 1)
-  }
-
-  throw new Error('Could not find next matching date within 2 years')
-}
-
-// ---------------------------------------------------------------------------
-// Field parsing
-// ---------------------------------------------------------------------------
-
-function parseField(field: string, min: number, max: number): number[] {
-  const values = new Set<number>()
-
-  for (const part of field.split(',')) {
-    const stepMatch = part.match(/^(.+)\/(\d+)$/)
-
-    if (stepMatch) {
-      const [, rangePart, stepStr] = stepMatch
-      const step = parseInt(stepStr!, 10)
-      if (step <= 0) throw new Error(`Invalid step value: ${stepStr}`)
-
-      const [start, end] = rangePart === '*' ? [min, max] : parseRange(rangePart!, min, max)
-      for (let i = start; i <= end; i += step) {
-        values.add(i)
-      }
-    } else if (part === '*') {
-      for (let i = min; i <= max; i++) values.add(i)
-    } else if (part.includes('-')) {
-      const [start, end] = parseRange(part, min, max)
-      for (let i = start; i <= end; i++) values.add(i)
-    } else {
-      const n = parseInt(part, 10)
-      if (isNaN(n) || n < min || n > max) {
-        throw new Error(`Invalid cron value "${part}": must be ${min}–${max}`)
-      }
-      values.add(n)
-    }
-  }
-
-  return [...values].sort((a, b) => a - b)
-}
-
-function parseRange(part: string, min: number, max: number): [number, number] {
-  const [startStr, endStr] = part.split('-')
-  const start = parseInt(startStr!, 10)
-  const end = parseInt(endStr!, 10)
-
-  if (isNaN(start) || isNaN(end) || start < min || end > max || start > end) {
-    throw new Error(`Invalid cron range "${part}": must be within ${min}–${max}`)
-  }
-
-  return [start, end]
-}

package/src/scheduler/index.ts

@@ -1,8 +0,0 @@
-export { default as Scheduler } from './scheduler.ts'
-export { Schedule } from './schedule.ts'
-export { default as SchedulerRunner } from './runner.ts'
-export { parseCron, cronMatches, nextCronDate } from './cron.ts'
-export type { CronExpression } from './cron.ts'
-export { TimeUnit } from './schedule.ts'
-export type { TaskHandler } from './schedule.ts'
-export type { RunnerOptions } from './runner.ts'

package/src/scheduler/runner.ts

@@ -1,116 +0,0 @@
-import Scheduler from './scheduler.ts'
-import type { Schedule } from './schedule.ts'
-
-export interface RunnerOptions {
-  /** Timezone for schedule evaluation. @default 'UTC' */
-  timezone?: string
-}
-
-/**
- * Long-running scheduler loop.
- *
- * Aligns to minute boundaries (standard cron behaviour), checks which
- * tasks are due, and executes them concurrently. Supports graceful
- * shutdown via SIGINT/SIGTERM and per-task overlap prevention.
- *
- * @example
- * const runner = new SchedulerRunner()
- * await runner.start() // blocks until runner.stop()
- */
-export default class SchedulerRunner {
-  private running = false
-  private active = new Set<string>()
-
-  /** Start the scheduler loop. Blocks until stop() is called. */
-  async start(): Promise<void> {
-    this.running = true
-
-    const onSignal = () => this.stop()
-    process.on('SIGINT', onSignal)
-    process.on('SIGTERM', onSignal)
-
-    try {
-      while (this.running) {
-        await this.sleepUntilNextMinute()
-        if (!this.running) break
-
-        const now = new Date()
-        const due = Scheduler.due(now)
-
-        if (due.length > 0) {
-          await this.runAll(due)
-        }
-      }
-
-      // Wait for active tasks to finish before exiting
-      if (this.active.size > 0) {
-        await this.waitForActive()
-      }
-    } finally {
-      process.off('SIGINT', onSignal)
-      process.off('SIGTERM', onSignal)
-    }
-  }
-
-  /** Signal the runner to stop after the current tick completes. */
-  stop(): void {
-    this.running = false
-  }
-
-  /** Number of tasks currently executing. */
-  get activeCount(): number {
-    return this.active.size
-  }
-
-  // ---------------------------------------------------------------------------
-  // Internal
-  // ---------------------------------------------------------------------------
-
-  /** Sleep until the start of the next minute (XX:XX:00.000). */
-  private async sleepUntilNextMinute(): Promise<void> {
-    const now = Date.now()
-    const nextMinute = Math.ceil(now / 60_000) * 60_000
-    const delay = nextMinute - now
-
-    // Minimum 1s, maximum 60s — avoid sleeping 0ms on exact boundaries
-    const ms = Math.max(1_000, Math.min(delay, 60_000))
-    await Bun.sleep(ms)
-  }
-
-  /** Execute all due tasks concurrently. */
-  private async runAll(tasks: Schedule[]): Promise<void> {
-    const promises: Promise<void>[] = []
-
-    for (const task of tasks) {
-      if (task.preventsOverlap && this.active.has(task.name)) {
-        continue
-      }
-
-      promises.push(this.runTask(task))
-    }
-
-    await Promise.allSettled(promises)
-  }
-
-  /** Execute a single task with overlap tracking and error handling. */
-  private async runTask(task: Schedule): Promise<void> {
-    this.active.add(task.name)
-    try {
-      await task.handler()
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error)
-      console.error(`[scheduler] Task "${task.name}" failed: ${message}`)
-    } finally {
-      this.active.delete(task.name)
-    }
-  }
-
-  /** Wait for all active tasks to complete (for graceful shutdown). */
-  private async waitForActive(): Promise<void> {
-    const maxWait = 30_000
-    const start = Date.now()
-    while (this.active.size > 0 && Date.now() - start < maxWait) {
-      await Bun.sleep(100)
-    }
-  }
-}