@strav/queue 0.4.31 → 1.0.0-alpha.3

package/src/failed_jobs_schema.ts

@@ -0,0 +1,37 @@
+/**
+ * `strav_failed_jobs` schema — terminal failure dead-letter table.
+ *
+ * When `Worker.processOne()` exhausts a job's `max_attempts`, the row
+ * moves from `strav_jobs` to `strav_failed_jobs` in a single
+ * transaction — INSERT here, DELETE there. Apps inspect this table
+ * to triage what blew up; the `queue:retry` / `queue:flush` console
+ * commands (lands with `@strav/cli` in M4) operate on these rows.
+ *
+ * Columns:
+ *   - `id` (char(26), ULID PK) — fresh per failure, not the original
+ *     job id (the original is gone with the row).
+ *   - `queue` (varchar(64)) — copied from `strav_jobs.queue`.
+ *   - `job_name` (varchar(128)) — copied from `strav_jobs.job_name`.
+ *   - `payload` (jsonb) — copied verbatim so retries can replay it.
+ *   - `exception` (text) — the thrown error, serialized via
+ *     `error.stack ?? String(error)`. Long; not indexed.
+ *   - `attempts` (integer) — how many total attempts the job got
+ *     before terminal failure.
+ *   - `failed_at` (timestamptz) — wall-clock time of the move.
+ *   - `created_at` / `updated_at` — provided by `t.timestamps()`.
+ *
+ * Not `tenanted: true` — same system-level scope as `strav_jobs`.
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const failedJobsSchema = defineSchema('strav_failed_jobs', Archetype.Entity, (t) => {
+  t.id()
+  t.string('queue').max(64)
+  t.string('job_name').max(128)
+  t.json<unknown>('payload')
+  t.text('exception')
+  t.integer('attempts')
+  t.timestamp('failed_at')
+  t.timestamps()
+})

package/src/index.ts

@@ -1,3 +1,52 @@
-export * from './queue/index.ts'
-export * from './scheduler/index.ts'
-export * from './providers/index.ts'
+// Public API of @strav/queue.
+//
+// V1 ships:
+//   - Job + JobContext + JobClass + PayloadOf — the unit of work + types.
+//   - JobRegistry + Bun.Glob auto-discovery + isJobClass type-guard.
+//   - Queue interface with dispatch / dispatchLater / dispatchSync.
+//   - SyncQueue — in-process synchronous driver for tests + single-process dev.
+//   - DatabaseQueue — Postgres-backed driver with queue-until-commit semantics
+//     via @strav/database's transactional ALS.
+//   - jobSchema — the `strav_jobs` Schema apps register + migrate.
+//   - Worker — consumer side: SELECT FOR UPDATE SKIP LOCKED poll loop,
+//     attempt counter, exponential backoff with jitter, per-attempt
+//     timeout, graceful shutdown via AbortSignal.
+//   - CronExpression + helpers (everyMinute / everyMinutes / hourly /
+//     daily / dailyAt / cron) — 5-field cron with UTC-based matching.
+//   - Scheduler + schedulerRunsSchema — recurring dispatch with optional
+//     onOneServer advisory lock (built on TenantManager.withLock).
+//
+//   - failedJobsSchema — the `strav_failed_jobs` dead-letter table.
+//     Worker moves terminal failures here atomically (INSERT + DELETE
+//     in one tx).
+//
+// Still deferred (waiting on @strav/cli — M4):
+//   - queue:retry / queue:flush console commands (re-enqueue / drop
+//     failed rows in bulk).
+
+export {
+  CronExpression,
+  cron,
+  daily,
+  dailyAt,
+  everyMinute,
+  everyMinutes,
+  hourly,
+} from './cron.ts'
+export { DatabaseQueue, type DatabaseQueueOptions } from './database_queue.ts'
+export { failedJobsSchema } from './failed_jobs_schema.ts'
+export {
+  Job,
+  type JobClass,
+  type JobConfig,
+  type JobContext,
+  type JobFailedContext,
+  type PayloadOf,
+} from './job.ts'
+export { isJobClass, JobRegistry } from './job_registry.ts'
+export { jobSchema } from './job_schema.ts'
+export type { DispatchLaterOptions, DispatchOptions, Queue } from './queue.ts'
+export { type ScheduleOptions, Scheduler, type SchedulerOptions } from './scheduler.ts'
+export { schedulerRunsSchema } from './scheduler_runs_schema.ts'
+export { SyncQueue, type SyncQueueOptions } from './sync_queue.ts'
+export { type JobResult, Worker, type WorkerOptions } from './worker.ts'

package/src/job.ts

@@ -0,0 +1,153 @@
+/**
+ * `Job` — the unit of background work.
+ *
+ * Subclasses declare a stable `static jobName` (the wire identifier the
+ * `JobRegistry` uses to route a serialized payload back to a class) and
+ * implement `handle(ctx)`. The Worker constructs jobs through the
+ * container so `@inject()`-marked subclasses get their dependencies
+ * resolved the usual way; the payload arrives as JSON on the
+ * `JobContext`.
+ *
+ * Configuration overrides (max attempts, backoff, timeout, queue name)
+ * are static on the subclass. The Worker reads them per-attempt — see
+ * the `JobConfig` interface below.
+ *
+ * ```ts
+ * @inject()
+ * class SendWelcomeEmail extends Job<{ userId: string }> {
+ *   static override readonly jobName = 'mail.welcome'
+ *
+ *   constructor(
+ *     private readonly users: UserRepository,
+ *     private readonly mail: MailManager,
+ *   ) {
+ *     super()
+ *   }
+ *
+ *   async handle(ctx: JobContext<{ userId: string }>): Promise<void> {
+ *     const user = await this.users.findOrFail(ctx.payload.userId)
+ *     await this.mail.send(new WelcomeEmail(user))
+ *   }
+ * }
+ * ```
+ */
+
+import type { Logger } from '@strav/kernel'
+
+/**
+ * Per-invocation context passed to `Job.handle(ctx)`. Workers populate
+ * every field — testing harnesses can build one by hand.
+ */
+export interface JobContext<TPayload = unknown> {
+  /** Stable id assigned at dispatch (typically a ULID). */
+  jobId: string
+  /** 1-based attempt counter. `attempt === 1` is the first run. */
+  attempt: number
+  /** The deserialized payload. */
+  payload: TPayload
+  /**
+   * Cancellation signal. Aborted when the Worker's shutdown grace
+   * period elapses or the job exceeds its `timeout`. Handlers that
+   * loop / stream should check `ctx.signal.aborted` and bail.
+   */
+  signal: AbortSignal
+  /**
+   * Job-scoped logger — prebound with `jobId` + `jobName` + `attempt`.
+   * Standard Logger surface (`debug`/`info`/`warn`/`error`).
+   */
+  log: Logger
+}
+
+/**
+ * Optional retry hook context — same shape as `JobContext` plus the
+ * error that caused the failure.
+ */
+export interface JobFailedContext<TPayload = unknown> extends JobContext<TPayload> {
+  /** The thrown value from the failed attempt. Already wrapped by the kernel error stack. */
+  error: unknown
+}
+
+/**
+ * The `static` config shape a Job subclass may set. Every field is
+ * optional — the Worker falls back to driver defaults when omitted.
+ */
+export interface JobConfig {
+  /** Total attempts (including the first). Default: driver-configured, typically 3. */
+  maxAttempts?: number
+  /**
+   * Backoff in seconds for `attempt` (1-based). The Worker calls this
+   * AFTER a failed attempt to schedule the next try. Default: exponential
+   * with jitter (driver-configured).
+   */
+  backoff?(attempt: number): number
+  /** Per-attempt time limit (seconds). Default: driver-configured. */
+  timeout?: number
+  /** Named queue to dispatch onto. Default: `'default'`. */
+  queue?: string
+}
+
+/**
+ * The abstract Job base class. Subclasses implement `handle` and set
+ * `static jobName`. Other static fields are optional configuration —
+ * see {@link JobConfig}.
+ *
+ * Generic parameter `TPayload` is the shape the dispatcher serializes
+ * and the handler deserializes. Workers JSON.stringify/parse it
+ * verbatim — keep it serializable (no Dates without a custom revival
+ * step, no class instances).
+ */
+export abstract class Job<TPayload = unknown> {
+  /**
+   * Stable wire identifier mapping this class in the JobRegistry.
+   * Subclasses MUST override. Convention: `<package>.<verb>` or
+   * `<resource>.<verb>` (`mail.welcome`, `user.cleanup`).
+   *
+   * The base class declares an empty string so type-checking holds;
+   * `JobRegistry.register()` rejects classes that didn't override.
+   */
+  static readonly jobName: string = ''
+
+  // Optional static configuration. Declared on the base so subclasses
+  // can shadow with `static override readonly <field> = <value>` under
+  // `noImplicitOverride`. The Worker reads these per-attempt; omitted
+  // fields fall back to driver defaults. Mirrors the {@link JobConfig}
+  // interface — the interface drives `JobClass`'s typing, the static
+  // fields here drive the override-friendly inheritance shape.
+  static readonly maxAttempts?: number
+  static readonly backoff?: (attempt: number) => number
+  static readonly timeout?: number
+  static readonly queue?: string
+
+  /** The handler. Workers call this once they've constructed the job + built the context. */
+  abstract handle(context: JobContext<TPayload>): Promise<void>
+
+  /**
+   * Optional failure hook. Fires when an attempt throws AND there are
+   * still retries left; also fires once on the FINAL failure (so apps
+   * can route to a dead-letter, post a Slack message, etc.). The Worker
+   * runs this in a try/catch — a throw from `failed()` is logged but
+   * doesn't change the retry decision.
+   */
+  failed?(context: JobFailedContext<TPayload>): Promise<void>
+}
+
+/**
+ * Constructor reference for a Job subclass. The Worker / Queue store
+ * these in the registry, look them up by `jobName`, and instantiate
+ * via the container.
+ */
+export interface JobClass<TPayload = unknown> extends JobConfig {
+  // biome-ignore lint/suspicious/noExplicitAny: ctor params are decided per-subclass; the @inject() flow resolves them.
+  new (...args: any[]): Job<TPayload>
+  readonly jobName: string
+}
+
+/**
+ * Helper type: extract the payload type from a `JobClass`.
+ *
+ * ```ts
+ * type WelcomePayload = PayloadOf<typeof SendWelcomeEmail>
+ * // → { userId: string }
+ * ```
+ */
+export type PayloadOf<T> = T extends JobClass<infer P> ? P : never

package/src/job_registry.ts

@@ -0,0 +1,135 @@
+/**
+ * `JobRegistry` — runtime catalog of every registered `Job` class.
+ *
+ * Apps register jobs explicitly (`register(JobClass)` / `registerAll
+ * ([...])`) or via `discover(pattern)`, which uses `Bun.Glob` to scan
+ * files + dynamically `import()` each, registering every exported
+ * class that satisfies {@link isJobClass}. Same shape as
+ * `SchemaRegistry.discover` in `@strav/database`.
+ *
+ * The registry rejects two different classes claiming the same
+ * `jobName` (a wire-protocol collision — the Worker can't disambiguate
+ * which class to instantiate). Re-imports of the same class via a
+ * barrel are deduped by identity.
+ */
+
+import { ConfigError } from '@strav/kernel'
+import { Job, type JobClass } from './job.ts'
+
+export class JobRegistry {
+  private readonly byName = new Map<string, JobClass>()
+
+  /** Register one Job class. Throws when `jobName` is empty or already taken. */
+  register(jobClass: JobClass): this {
+    if (!jobClass.jobName) {
+      throw new ConfigError(
+        `JobRegistry: ${jobClass.name || 'anonymous job'} must declare a non-empty \`static jobName\` — that's the wire identifier the Worker dispatches against.`,
+      )
+    }
+    const existing = this.byName.get(jobClass.jobName)
+    if (existing === jobClass) return this
+    if (existing) {
+      throw new ConfigError(
+        `JobRegistry: jobName "${jobClass.jobName}" is already registered to a different class (${existing.name} vs ${jobClass.name}). Pick a different jobName — the Worker uses it to route serialized payloads back to a class.`,
+      )
+    }
+    this.byName.set(jobClass.jobName, jobClass)
+    return this
+  }
+
+  /** Register several. Order matters only insofar as register() throws on conflict. */
+  registerAll(jobClasses: readonly JobClass[]): this {
+    for (const cls of jobClasses) this.register(cls)
+    return this
+  }
+
+  /**
+   * Auto-discover Job classes by glob pattern. For each matched file:
+   *   1. dynamically `import()` it,
+   *   2. iterate every exported value,
+   *   3. register every one that satisfies {@link isJobClass}.
+   *
+   * `pattern` is a `Bun.Glob`-compatible string (or array). `cwd`
+   * defaults to `process.cwd()` (typically the repo root). Returns
+   * `this` for chaining.
+   *
+   * Re-exports of the same class via multiple files dedupe by object
+   * identity — typical barrel patterns work. Two DIFFERENT classes
+   * sharing a `jobName` still throw `ConfigError`.
+   *
+   * Files exporting no Job classes (helpers, type-only re-exports) are
+   * silently skipped.
+   */
+  async discover(pattern: string | string[], options: { cwd?: string } = {}): Promise<this> {
+    const patterns = Array.isArray(pattern) ? pattern : [pattern]
+    const cwd = options.cwd ?? process.cwd()
+    const files = new Set<string>()
+    for (const p of patterns) {
+      const glob = new Bun.Glob(p)
+      for await (const file of glob.scan({ cwd, absolute: true })) {
+        files.add(file)
+      }
+    }
+    for (const file of files) {
+      const mod = (await import(file)) as Record<string, unknown>
+      for (const value of Object.values(mod)) {
+        if (!isJobClass(value)) continue
+        this.register(value)
+      }
+    }
+    return this
+  }
+
+  /** Resolve by `jobName`. Returns `undefined` for unknown names. */
+  get(jobName: string): JobClass | undefined {
+    return this.byName.get(jobName)
+  }
+
+  /** Throwing variant — use when "this job must exist" is a hard precondition. */
+  getOrFail(jobName: string): JobClass {
+    const cls = this.byName.get(jobName)
+    if (!cls) {
+      throw new ConfigError(
+        `JobRegistry: no Job is registered under "${jobName}". ` +
+          'Either the dispatcher serialized an unknown class, or the Worker is running against a different registry than the dispatcher used.',
+      )
+    }
+    return cls
+  }
+
+  /** True when a Job with this `jobName` is registered. */
+  has(jobName: string): boolean {
+    return this.byName.has(jobName)
+  }
+
+  /** Every registered class, in insertion order. */
+  all(): readonly JobClass[] {
+    return [...this.byName.values()]
+  }
+
+  /** Test helper: wipe the registry. */
+  clear(): void {
+    this.byName.clear()
+  }
+}
+
+/**
+ * Type-guard: a value looks like a Job class — a function whose
+ * prototype extends `Job` and which declares a non-empty `jobName`.
+ * Used by `discover()` to filter exported values; exported so apps can
+ * hand-roll their own discovery loops.
+ *
+ * The prototype check is conservative — a class that doesn't extend
+ * `Job` (even one that happens to look duck-typed) is rejected. That's
+ * intentional: the `failed?` hook + future Worker extensions key off
+ * `instanceof Job`, so the registry's identity guarantee has to match.
+ */
+export function isJobClass(value: unknown): value is JobClass {
+  if (typeof value !== 'function') return false
+  // The Job constructor itself isn't registerable (it's abstract); only
+  // subclasses are.
+  if (value === Job) return false
+  if (!(value.prototype instanceof Job)) return false
+  const jobName = (value as { jobName?: unknown }).jobName
+  return typeof jobName === 'string' && jobName.length > 0
+}

package/src/job_schema.ts

@@ -0,0 +1,49 @@
+/**
+ * `strav_jobs` schema — the backing table for `DatabaseQueue`.
+ *
+ * Naming convention: framework-managed tables that apps register +
+ * migrate use the `strav_*` prefix (no leading underscore — those are
+ * reserved for raw-DDL tables created by the runner / DDL emitter:
+ * `_strav_migrations`, `_strav_tenant_sequences`). Apps register
+ * `jobSchema` with their SchemaRegistry and `generateMigration` picks
+ * it up like any other schema.
+ *
+ * Columns:
+ *   - `id` (char(26), ULID PK) — globally unique across queues.
+ *   - `queue` (varchar(64)) — named queue. Default `'default'`. Workers
+ *     poll one queue at a time, so this is the routing key.
+ *   - `job_name` (varchar(128)) — `JobRegistry` lookup key. The Worker
+ *     deserializes the row by mapping this back to a `JobClass`.
+ *   - `payload` (jsonb) — the `JSON.stringify`'d job payload.
+ *   - `attempts` (integer, default 0) — count of attempts so far. The
+ *     Worker increments before running `handle()`.
+ *   - `max_attempts` (integer, default 3) — total retries allowed.
+ *     `attempts >= max_attempts` after a failed attempt → terminal
+ *     failure, moves to `failed_jobs` (V1 just leaves it; failed-jobs
+ *     handling is its own slice).
+ *   - `available_at` (timestamptz) — the earliest time a Worker may
+ *     pick this row up. `now()` for immediate dispatch; `dispatchLater`
+ *     pushes this into the future.
+ *   - `reserved_at` (timestamptz, nullable) — when a Worker locked
+ *     the row via `SELECT FOR UPDATE SKIP LOCKED`. NULL means
+ *     unreserved.
+ *   - `created_at` / `updated_at` — provided by `t.timestamps()`.
+ *
+ * Not `tenanted: true` — the queue is system-level. Multi-tenant apps
+ * that want per-tenant queues can clone this schema with a tenant_id
+ * FK + RLS, but that's a follow-up.
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const jobSchema = defineSchema('strav_jobs', Archetype.Entity, (t) => {
+  t.id()
+  t.string('queue').max(64).default('default')
+  t.string('job_name').max(128)
+  t.json<unknown>('payload')
+  t.integer('attempts').default(0)
+  t.integer('max_attempts').default(3)
+  t.timestamp('available_at')
+  t.timestamp('reserved_at').nullable()
+  t.timestamps()
+})

package/src/queue.ts

@@ -0,0 +1,69 @@
+/**
+ * `Queue` — the contract every backend implements.
+ *
+ * V1 ships two: `SyncQueue` (in-process, no persistence — for tests +
+ * single-process dev) and `DatabaseQueue` (Postgres-backed, the
+ * production driver). Both implement this interface; apps depend on
+ * the abstract `Queue` symbol via DI.
+ *
+ * Method semantics:
+ *   - `dispatch(JobClass, payload, opts?)` — enqueue for a Worker to
+ *     pick up. Returns the assigned `jobId` (ULID).
+ *   - `dispatchLater(at, JobClass, payload, opts?)` — same as dispatch
+ *     but the row isn't picked up until `at`. `at` is either a `Date`
+ *     (absolute) or a number of seconds from now (relative).
+ *   - `dispatchSync(JobClass, payload)` — instantiate + run `handle()`
+ *     synchronously in the caller's process. No persistence, no
+ *     retries, no Worker required. Useful for tests, for dev mode,
+ *     and for callers that genuinely want the work done inline (rare
+ *     in production — most jobs exist precisely to defer work).
+ */
+
+import type { JobClass, PayloadOf } from './job.ts'
+
+export interface DispatchOptions {
+  /** Named queue to dispatch onto. Default: the JobClass's `static queue` or `'default'`. */
+  queue?: string
+  /**
+   * Override total attempts (including the first). Default: the
+   * JobClass's `static maxAttempts`, or the driver default (typically 3).
+   */
+  attempts?: number
+}
+
+export interface DispatchLaterOptions extends DispatchOptions {
+  // No additional options today; the slot exists so future drivers can
+  // grow it (e.g. `priority` or `deduplicationKey`) without breaking
+  // the call sites.
+}
+
+export interface Queue {
+  /** Enqueue immediately. Returns the assigned job id (ULID). */
+  dispatch<TJob extends JobClass>(
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+    opts?: DispatchOptions,
+  ): Promise<string>
+
+  /**
+   * Enqueue with a delay. `at` is either a `Date` (absolute wall-clock
+   * time) or a positive number of seconds from now. Returns the
+   * assigned job id (ULID).
+   *
+   * `Date` values in the past are clamped to "now" — i.e. the job
+   * becomes immediately eligible. Negative numbers throw.
+   */
+  dispatchLater<TJob extends JobClass>(
+    at: Date | number,
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+    opts?: DispatchLaterOptions,
+  ): Promise<string>
+
+  /**
+   * Run the job synchronously in the caller's process. No persistence,
+   * no retries — if `handle()` throws, the throw propagates. Returns
+   * when `handle()` resolves.
+   */
+  dispatchSync<TJob extends JobClass>(jobClass: TJob, payload: PayloadOf<TJob>): Promise<void>
+}