@strav/queue 1.0.0-alpha.3 → 1.0.0-alpha.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/queue",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.4",
   "description": "Strav queue layer — Job + JobRegistry + dispatch contract; backends ship as drivers",
   "type": "module",
   "main": "./src/index.ts",
@@ -19,8 +19,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/database": "1.0.0-alpha.3",
-    "@strav/kernel": "1.0.0-alpha.3"
+    "@strav/cli": "1.0.0-alpha.4",
+    "@strav/database": "1.0.0-alpha.4",
+    "@strav/kernel": "1.0.0-alpha.4"
   },
   "peerDependencies": {
     "@types/bun": ">=1.3.14"

package/src/console/index.ts

@@ -0,0 +1,10 @@
+// Console subsystem — queue + scheduler commands + QueueConsoleProvider.
+
+export { QueueConsoleProvider } from './queue_console_provider.ts'
+export { QueueFailed } from './queue_failed.ts'
+export { QueueFlush } from './queue_flush.ts'
+export { QueueRetry } from './queue_retry.ts'
+export { QueueWork } from './queue_work.ts'
+export { SchedulerList } from './scheduler_list.ts'
+export { SchedulerRun } from './scheduler_run.ts'
+export { SchedulerWork } from './scheduler_work.ts'

package/src/console/queue_console_provider.ts

@@ -0,0 +1,32 @@
+/**
+ * `QueueConsoleProvider` — declares the queue + scheduler console commands.
+ *
+ * Apps add it to `bootstrap/providers.ts` alongside whatever provider binds
+ * `Worker` + `Scheduler` (apps wire those — see `docs/queue/guides/console.md`).
+ *
+ * The provider doesn't bind Worker/Scheduler itself because their
+ * construction is app-specific (queue names, registered jobs, scheduler
+ * entries) — too much variance for a sensible default.
+ */
+
+import { ConsoleProvider } from '@strav/cli'
+import { QueueFailed } from './queue_failed.ts'
+import { QueueFlush } from './queue_flush.ts'
+import { QueueRetry } from './queue_retry.ts'
+import { QueueWork } from './queue_work.ts'
+import { SchedulerList } from './scheduler_list.ts'
+import { SchedulerRun } from './scheduler_run.ts'
+import { SchedulerWork } from './scheduler_work.ts'
+
+export class QueueConsoleProvider extends ConsoleProvider {
+  override readonly name = 'console.queue'
+  override readonly commands = [
+    QueueWork,
+    QueueFailed,
+    QueueRetry,
+    QueueFlush,
+    SchedulerWork,
+    SchedulerList,
+    SchedulerRun,
+  ] as const
+}

package/src/console/queue_failed.ts

@@ -0,0 +1,57 @@
+/**
+ * `bun strav queue:failed` — list rows in the dead-letter table.
+ *
+ * Reads `strav_failed_jobs` directly via the bound `Database`. The
+ * Worker moves terminal failures here (atomic INSERT + DELETE from
+ * `strav_jobs`); this command surfaces them for triage.
+ */
+
+import { Command, ExitCode } from '@strav/cli'
+import { PostgresDatabase } from '@strav/database'
+
+interface FailedRow {
+  id: string
+  queue: string
+  job_name: string
+  attempts: number
+  failed_at: Date | string
+  exception: string
+}
+
+export class QueueFailed extends Command {
+  static signature = 'queue:failed'
+  static description = 'List jobs in the dead-letter table.'
+  static providers = ['config', 'logger', 'database']
+
+  override async execute(): Promise<number> {
+    const db = this.app.resolve(PostgresDatabase)
+    const rows = await db.query<FailedRow>(
+      `SELECT id, queue, job_name, attempts, failed_at, exception
+         FROM "strav_failed_jobs"
+         ORDER BY failed_at DESC`,
+    )
+
+    if (rows.length === 0) {
+      this.info('No failed jobs.')
+      return ExitCode.Success
+    }
+
+    this.table(
+      ['ID', 'Queue', 'Job', 'Attempts', 'Failed at', 'Error'],
+      rows.map((r) => [
+        r.id,
+        r.queue,
+        r.job_name,
+        String(r.attempts),
+        (r.failed_at instanceof Date ? r.failed_at : new Date(r.failed_at)).toISOString(),
+        firstLine(r.exception),
+      ]),
+    )
+    return ExitCode.Success
+  }
+}
+
+function firstLine(text: string): string {
+  const newline = text.indexOf('\n')
+  return newline === -1 ? text : text.slice(0, newline)
+}

package/src/console/queue_flush.ts

@@ -0,0 +1,41 @@
+/**
+ * `bun strav queue:flush [--queue=name] [--force]` — drop pending jobs.
+ *
+ * `DELETE FROM strav_jobs` (optionally filtered by queue name). Confirms
+ * before running unless `--force` is set. Doesn't touch
+ * `strav_failed_jobs` — the dead-letter table is separate and managed
+ * via `queue:retry` / a separate operator-driven cleanup.
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { PostgresDatabase } from '@strav/database'
+
+export class QueueFlush extends Command {
+  static signature = 'queue:flush {--queue=} {--force}'
+  static description = 'Delete pending jobs (optionally filtered by --queue).'
+  static providers = ['config', 'logger', 'database']
+
+  override async execute({ flags }: ExecuteArgs): Promise<number> {
+    const queue = typeof flags.queue === 'string' && flags.queue.length > 0 ? flags.queue : null
+
+    if (flags.force !== true) {
+      const ok = await this.confirm(
+        queue
+          ? `Delete every pending job on queue "${queue}"? This is irreversible.`
+          : 'Delete EVERY pending job across all queues? This is irreversible.',
+      )
+      if (!ok) {
+        this.info('Aborted.')
+        return ExitCode.Success
+      }
+    }
+
+    const db = this.app.resolve(PostgresDatabase)
+    const deleted = queue
+      ? await db.execute(`DELETE FROM "strav_jobs" WHERE queue = $1`, [queue])
+      : await db.execute(`DELETE FROM "strav_jobs"`)
+
+    this.success(`Deleted ${deleted} pending job(s)${queue ? ` from queue "${queue}"` : ''}.`)
+    return ExitCode.Success
+  }
+}

package/src/console/queue_retry.ts

@@ -0,0 +1,68 @@
+/**
+ * `bun strav queue:retry <id>` or `--all` — re-enqueue failed jobs.
+ *
+ * Copies the failed row(s) back into `strav_jobs` (attempts reset to 0,
+ * available_at = now()) and deletes them from `strav_failed_jobs` — all
+ * inside one transaction so a crash mid-move can't lose rows or
+ * double-enqueue.
+ *
+ * `<id>` re-enqueues exactly one job; `--all` re-enqueues every row in
+ * the dead-letter table. Without either, the command errors out with a
+ * usage message.
+ */
+
+import { Command, type ExecuteArgs, ExitCode, UsageError } from '@strav/cli'
+import { PostgresDatabase } from '@strav/database'
+import { ulid } from '@strav/kernel'
+
+interface FailedRow {
+  id: string
+  queue: string
+  job_name: string
+  payload: unknown
+}
+
+export class QueueRetry extends Command {
+  static signature = 'queue:retry {id?} {--all}'
+  static description = 'Re-enqueue a failed job by id, or every failed job with --all.'
+  static providers = ['config', 'logger', 'database']
+
+  override async execute({ args, flags }: ExecuteArgs): Promise<number> {
+    const all = flags.all === true
+    const id = args.id
+    if (!all && (id === undefined || id.length === 0)) {
+      throw new UsageError('queue:retry needs an <id> or the --all flag')
+    }
+    if (all && id !== undefined && id.length > 0) {
+      throw new UsageError('queue:retry: pass an <id> OR --all, not both')
+    }
+
+    const db = this.app.resolve(PostgresDatabase)
+    const moved = await db.transaction(async (tx) => {
+      const rows = all
+        ? await tx.query<FailedRow>(`SELECT id, queue, job_name, payload FROM "strav_failed_jobs"`)
+        : await tx.query<FailedRow>(
+            `SELECT id, queue, job_name, payload FROM "strav_failed_jobs" WHERE id = $1`,
+            [id],
+          )
+      for (const row of rows) {
+        await tx.execute(
+          `INSERT INTO "strav_jobs" (id, queue, job_name, payload, attempts, max_attempts, available_at, reserved_at, created_at, updated_at)
+             VALUES ($1, $2, $3, $4, 0, 3, now(), NULL, now(), now())`,
+          [ulid(), row.queue, row.job_name, row.payload],
+        )
+        await tx.execute(`DELETE FROM "strav_failed_jobs" WHERE id = $1`, [row.id])
+      }
+      return rows
+    })
+
+    if (moved.length === 0) {
+      if (all) this.info('No failed jobs to retry.')
+      else this.warn(`No failed job with id "${id}".`)
+      return ExitCode.Success
+    }
+    this.success(`Re-enqueued ${moved.length} job(s).`)
+    for (const row of moved) this.line(`  ↻ ${row.id}  ${row.job_name}`)
+    return ExitCode.Success
+  }
+}

package/src/console/queue_work.ts

@@ -0,0 +1,85 @@
+/**
+ * `bun strav queue:work [--max=N]` — drain jobs forever (or up to N).
+ *
+ * Resolves the container-bound `Worker`. Apps construct the `Worker` in
+ * their provider (it needs `db`, `registry`, `container`, plus the
+ * `queues` slice config) — the command just drives it.
+ *
+ * Signal handling: registers `SIGINT` + `SIGTERM` listeners that abort
+ * the worker's loop. The Worker's own graceful-shutdown semantics
+ * (drain in-flight jobs, release SKIP LOCKED rows) handle the rest.
+ *
+ * `--max=N` exits after N completed jobs — useful for hosted runtimes
+ * (Render workers, supervised tasks) that prefer "exit cleanly so the
+ * supervisor restarts you" over an unbounded loop. When N is set we
+ * loop on `processOne()` so we can count cleanly; otherwise we hand
+ * off to `worker.run(signal)`.
+ */
+
+import { Command, type ExecuteArgs, ExitCode, UsageError } from '@strav/cli'
+import { Worker } from '../worker.ts'
+
+export class QueueWork extends Command {
+  static signature = 'queue:work {--queue=default} {--max=}'
+  static description = 'Run a queue worker until interrupted (or --max=N jobs).'
+  // Boot the full default list — the Worker pulls Database, JobRegistry,
+  // Logger, and any app-registered services through the container at
+  // resolution time.
+
+  override async execute({ flags }: ExecuteArgs): Promise<number> {
+    const maxStr = flags.max
+    let max: number | null = null
+    if (typeof maxStr === 'string' && maxStr.length > 0) {
+      const parsed = Number.parseInt(maxStr, 10)
+      if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new UsageError(`--max must be a positive integer (got "${maxStr}")`)
+      }
+      max = parsed
+    }
+
+    const worker = this.app.resolve(Worker)
+    const controller = new AbortController()
+    const sigint = () => controller.abort()
+    const sigterm = () => controller.abort()
+    process.once('SIGINT', sigint)
+    process.once('SIGTERM', sigterm)
+
+    this.info(`Worker started — queue=${flags.queue}${max !== null ? `, max=${max}` : ''}.`)
+    try {
+      if (max === null) {
+        await worker.run(controller.signal)
+      } else {
+        // Bounded loop — `processOne()` returns null when nothing's claimable;
+        // sleep briefly so we don't spin-poll an empty queue.
+        let processed = 0
+        while (processed < max && !controller.signal.aborted) {
+          const result = await worker.processOne()
+          if (result === null) {
+            await sleep(1000, controller.signal)
+            continue
+          }
+          processed++
+        }
+        this.info(`Stopped after ${processed} job(s).`)
+      }
+      return ExitCode.Success
+    } finally {
+      process.off('SIGINT', sigint)
+      process.off('SIGTERM', sigterm)
+    }
+  }
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms)
+    signal.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer)
+        resolve()
+      },
+      { once: true },
+    )
+  })
+}

package/src/console/scheduler_list.ts

@@ -0,0 +1,27 @@
+/**
+ * `bun strav scheduler:list` — table of every registered scheduled entry.
+ *
+ * Read-only / pure introspection — never dispatches.
+ */
+
+import { Command, ExitCode } from '@strav/cli'
+import { Scheduler } from '../scheduler.ts'
+
+export class SchedulerList extends Command {
+  static signature = 'scheduler:list'
+  static description = 'List registered scheduler entries.'
+
+  override execute(): number {
+    const scheduler = this.app.resolve(Scheduler)
+    const entries = scheduler.all()
+    if (entries.length === 0) {
+      this.info('No schedules registered.')
+      return ExitCode.Success
+    }
+    this.table(
+      ['Name', 'Cron', 'Job', 'OneServer'],
+      entries.map((e) => [e.name, e.cron.expression, e.job.jobName, e.oneServer ? 'yes' : 'no']),
+    )
+    return ExitCode.Success
+  }
+}

package/src/console/scheduler_run.ts

@@ -0,0 +1,31 @@
+/**
+ * `bun strav scheduler:run <name>` — force-dispatch one named entry on demand.
+ *
+ * Bypasses the cron expression. When the entry was registered with
+ * `oneServer: true`, the advisory lock + run-tracking row still apply,
+ * so two `scheduler:run` invocations from different machines can't
+ * double-dispatch.
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { Scheduler } from '../scheduler.ts'
+
+export class SchedulerRun extends Command {
+  static signature = 'scheduler:run {name}'
+  static description = 'Force-run one named schedule entry.'
+
+  override async execute({ args }: ExecuteArgs): Promise<number> {
+    const name = args.name
+    if (!name) return ExitCode.UsageError // unreachable: bindArgv already enforced
+
+    const scheduler = this.app.resolve(Scheduler)
+    try {
+      await scheduler.runEntry(name)
+    } catch (err) {
+      this.error((err as Error).message)
+      return ExitCode.UsageError
+    }
+    this.success(`Dispatched "${name}".`)
+    return ExitCode.Success
+  }
+}

package/src/console/scheduler_work.ts

@@ -0,0 +1,32 @@
+/**
+ * `bun strav scheduler:work` — run the minute-tick scheduler loop.
+ *
+ * Long-running; SIGINT / SIGTERM aborts the loop, which (per Scheduler's
+ * semantics) returns within one tick.
+ */
+
+import { Command, ExitCode } from '@strav/cli'
+import { Scheduler } from '../scheduler.ts'
+
+export class SchedulerWork extends Command {
+  static signature = 'scheduler:work'
+  static description = 'Run the scheduler tick loop until interrupted.'
+
+  override async execute(): Promise<number> {
+    const scheduler = this.app.resolve(Scheduler)
+    const controller = new AbortController()
+    const sigint = () => controller.abort()
+    const sigterm = () => controller.abort()
+    process.once('SIGINT', sigint)
+    process.once('SIGTERM', sigterm)
+
+    this.info(`Scheduler started (${scheduler.all().length} entries).`)
+    try {
+      await scheduler.run(controller.signal)
+      return ExitCode.Success
+    } finally {
+      process.off('SIGINT', sigint)
+      process.off('SIGTERM', sigterm)
+    }
+  }
+}

package/src/index.ts

@@ -24,6 +24,16 @@
 //   - queue:retry / queue:flush console commands (re-enqueue / drop
 //     failed rows in bulk).
 
+export {
+  QueueConsoleProvider,
+  QueueFailed,
+  QueueFlush,
+  QueueRetry,
+  QueueWork,
+  SchedulerList,
+  SchedulerRun,
+  SchedulerWork,
+} from './console/index.ts'
 export {
   CronExpression,
   cron,

package/src/scheduler.ts

@@ -111,6 +111,35 @@ export class Scheduler {
     return [...this.entries]
   }
 
+  /**
+   * Force-dispatch one named entry once, regardless of its cron expression.
+   * Useful for `bun strav scheduler:run <name>` — run an entry on demand
+   * without waiting for the next tick boundary.
+   *
+   * Honors `oneServer`: when set, the lock + run-tracking row still apply,
+   * so two `scheduler:run` invocations against the same name from
+   * different machines don't double-dispatch. The "tick boundary" used
+   * for run-tracking is `now` floored to the minute, the same convention
+   * `tick()` uses.
+   *
+   * Throws when `name` doesn't match any registered entry — silent failure
+   * here would be a footgun in a deploy script.
+   */
+  async runEntry(name: string, now: Date = new Date()): Promise<void> {
+    const entry = this.entries.find((e) => e.name === name)
+    if (!entry) {
+      throw new Error(
+        `Scheduler.runEntry("${name}"): no schedule with that name registered. ` +
+          `Known names: ${this.entries.map((e) => e.name).join(', ') || '(none)'}`,
+      )
+    }
+    if (entry.oneServer) {
+      await this.dispatchOneServer(entry, floorToMinute(now))
+    } else {
+      await this.queue.dispatch(entry.job, entry.payload as never)
+    }
+  }
+
   /**
    * Process every entry against `now`. The tick boundary is `now`
    * floored to the start of its minute (seconds + millis cleared) —