@strav/queue 0.4.31 → 1.0.0-alpha.3

package/src/scheduler.ts

@@ -0,0 +1,242 @@
+/**
+ * `Scheduler` — recurring job dispatch on a cron cadence.
+ *
+ * Two surfaces:
+ *   - `.schedule(opts)` registers an entry (`{ job, cron, name?,
+ *     payload?, oneServer? }`). Returns `this` for chaining.
+ *   - `.tick(now)` processes every registered entry whose cron matches
+ *     `now`. Dispatches via the wired `Queue`. Exposed for tests +
+ *     one-shot CLI use.
+ *   - `.run(signal)` is the long-running loop — calls `tick()` at each
+ *     minute boundary, sleeps abort-aware between ticks.
+ *
+ * `oneServer: true` entries use `TenantManager.withLock` to acquire a
+ * fleet-wide advisory lock named after the entry. Inside the lock the
+ * dispatcher checks `strav_scheduler_runs.last_run_at` — if the
+ * current tick boundary already has a run recorded, this server skips
+ * (another server won). Otherwise dispatch + UPSERT atomically.
+ *
+ * `withLock` is built on `UnitOfWork.run`, which means
+ * `DatabaseQueue.dispatch` inside it auto-routes through the same
+ * transaction — the queue row INSERT + the run-tracking UPSERT commit
+ * together. A throw before COMMIT drops both. Exactly the
+ * queue-until-commit semantic from M2.
+ *
+ * Cron matching is UTC-based (see {@link CronExpression}). Apps that
+ * want local-time scheduling shift their schedule expressions; the
+ * Scheduler doesn't take a timezone option.
+ */
+
+import type { TenantManager } from '@strav/database'
+import { type Logger, ulid } from '@strav/kernel'
+import type { CronExpression } from './cron.ts'
+import type { JobClass } from './job.ts'
+import type { Queue } from './queue.ts'
+
+export interface ScheduleOptions {
+  /** Job to dispatch when the cron matches. */
+  job: JobClass
+  /** Payload handed to the Job. Default `undefined` → empty payload. */
+  payload?: unknown
+  /** Cron expression that gates the dispatch. */
+  cron: CronExpression
+  /**
+   * Identifier used for the advisory lock key + the
+   * `strav_scheduler_runs` row. Defaults to `job.jobName`.
+   * Specify when one job class is scheduled multiple times with
+   * different cadences / payloads, so each has its own lock + row.
+   */
+  name?: string
+  /**
+   * When `true`, only one server in the fleet dispatches per tick
+   * (advisory lock + run-tracking row). When `false` (default), every
+   * server dispatches independently — fine for jobs whose work is
+   * itself idempotent or which want fan-out semantics.
+   */
+  oneServer?: boolean
+}
+
+export interface SchedulerOptions {
+  /** Queue used to dispatch each entry's job. */
+  queue: Queue
+  /**
+   * TenantManager — used for its `withLock` + UoW combo on
+   * `oneServer` entries. `Scheduler` doesn't itself do tenancy; this
+   * is the most ergonomic primitive for "advisory lock + transaction
+   * + ambient ALS so dispatch joins the same tx."
+   */
+  tenants: TenantManager
+  /**
+   * Optional fallback executor used when an `oneServer: false` entry's
+   * dispatch raises. Only used to log the failure; the Queue itself
+   * already routes the SQL. Default: no-op logger.
+   */
+  logger?: Logger
+}
+
+interface ScheduledEntry {
+  name: string
+  cron: CronExpression
+  job: JobClass
+  payload: unknown
+  oneServer: boolean
+}
+
+export class Scheduler {
+  private readonly queue: Queue
+  private readonly tenants: TenantManager
+  private readonly logger: Logger
+  private readonly entries: ScheduledEntry[] = []
+
+  constructor(opts: SchedulerOptions) {
+    this.queue = opts.queue
+    this.tenants = opts.tenants
+    this.logger = opts.logger ?? createNoopLogger()
+  }
+
+  /** Register a recurring dispatch. Returns `this` for chaining. */
+  schedule(options: ScheduleOptions): this {
+    this.entries.push({
+      name: options.name ?? options.job.jobName,
+      cron: options.cron,
+      job: options.job,
+      payload: options.payload,
+      oneServer: options.oneServer ?? false,
+    })
+    return this
+  }
+
+  /** Every registered entry — exposed for inspection / tests. */
+  all(): readonly ScheduledEntry[] {
+    return [...this.entries]
+  }
+
+  /**
+   * Process every entry against `now`. The tick boundary is `now`
+   * floored to the start of its minute (seconds + millis cleared) —
+   * cron matches against that, and `oneServer` run-tracking writes
+   * that value into `strav_scheduler_runs.last_run_at`.
+   */
+  async tick(now: Date = new Date()): Promise<void> {
+    const boundary = floorToMinute(now)
+    for (const entry of this.entries) {
+      if (!entry.cron.matches(boundary)) continue
+      try {
+        if (entry.oneServer) {
+          await this.dispatchOneServer(entry, boundary)
+        } else {
+          await this.queue.dispatch(entry.job, entry.payload as never)
+        }
+      } catch (error) {
+        this.logger.error('Scheduler: dispatch failed', {
+          name: entry.name,
+          jobName: entry.job.jobName,
+          error,
+        })
+      }
+    }
+  }
+
+  /**
+   * Run the minute-tick loop until `signal` aborts. Each iteration
+   * sleeps until the next minute boundary, then calls `tick()`. The
+   * sleep is abort-aware — `signal.abort()` returns within one tick
+   * rather than waiting out the minute.
+   *
+   * On the FIRST iteration, sleeps to the next minute boundary
+   * BEFORE the first tick — so callers see one full minute pass
+   * between `run()` start and the first dispatch. (Calling `tick()`
+   * explicitly before `run()` is the way to dispatch immediately.)
+   */
+  async run(signal: AbortSignal): Promise<void> {
+    while (!signal.aborted) {
+      const now = new Date()
+      const nextBoundary = nextMinuteBoundary(now)
+      const sleepMs = Math.max(0, nextBoundary.getTime() - now.getTime())
+      await sleep(sleepMs, signal)
+      if (signal.aborted) return
+      try {
+        await this.tick(nextBoundary)
+      } catch (loopError) {
+        this.logger.error('Scheduler: tick iteration failed', { error: loopError })
+      }
+    }
+  }
+
+  private async dispatchOneServer(entry: ScheduledEntry, tickBoundary: Date): Promise<void> {
+    await this.tenants.withLock(`scheduler:${entry.name}`, async (tx) => {
+      const last = await tx.queryOne<{ last_run_at: Date }>(
+        `SELECT last_run_at FROM "strav_scheduler_runs" WHERE name = $1`,
+        [entry.name],
+      )
+      // The lock serializes the read+write window — if another server
+      // already recorded this tick boundary, skip cleanly.
+      if (last !== null && last.last_run_at.getTime() >= tickBoundary.getTime()) {
+        return
+      }
+      // Inside withLock's UoW, the dispatch routes through the ambient
+      // tx — the queue row INSERT + the run-tracking UPSERT commit
+      // atomically. If anything throws, both roll back.
+      await this.queue.dispatch(entry.job, entry.payload as never)
+      await tx.execute(
+        `INSERT INTO "strav_scheduler_runs" (id, name, last_run_at, created_at, updated_at)
+         VALUES ($1, $2, $3, now(), now())
+         ON CONFLICT (name) DO UPDATE
+           SET last_run_at = EXCLUDED.last_run_at, updated_at = now()`,
+        [ulid(), entry.name, tickBoundary],
+      )
+    })
+  }
+}
+
+/** Floor a Date to the start of its minute (seconds + millis cleared). */
+function floorToMinute(date: Date): Date {
+  return new Date(
+    Date.UTC(
+      date.getUTCFullYear(),
+      date.getUTCMonth(),
+      date.getUTCDate(),
+      date.getUTCHours(),
+      date.getUTCMinutes(),
+      0,
+      0,
+    ),
+  )
+}
+
+/** Next-minute boundary strictly after `date`. */
+function nextMinuteBoundary(date: Date): Date {
+  const floor = floorToMinute(date)
+  return new Date(floor.getTime() + 60_000)
+}
+
+/** Abort-aware sleep. */
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (signal.aborted) {
+      resolve()
+      return
+    }
+    const timer = setTimeout(resolve, ms)
+    const onAbort = () => {
+      clearTimeout(timer)
+      signal.removeEventListener('abort', onAbort)
+      resolve()
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/** No-op Logger — same shape as the ones in DatabaseQueue / Worker. */
+function createNoopLogger(): Logger {
+  const noop = () => undefined
+  return {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    fatal: noop,
+    trace: noop,
+    child: () => createNoopLogger(),
+  } as unknown as Logger
+}

package/src/scheduler_runs_schema.ts

@@ -0,0 +1,33 @@
+/**
+ * `strav_scheduler_runs` schema — tracks the last tick boundary at
+ * which a `Scheduler.onOneServer` entry dispatched.
+ *
+ * Why the table exists: `pg_advisory_xact_lock` releases on COMMIT —
+ * the lock is held only for the duration of the dispatch transaction
+ * (~10ms). Without a run-tracking row, two servers entering the lock
+ * block back-to-back at the start of the same minute would each see
+ * "cron matches now" and dispatch — double work.
+ *
+ * The check inside the lock block:
+ *   1. SELECT last_run_at WHERE name = $name.
+ *   2. If last_run_at >= tick_boundary, another server already won
+ *      this minute. Skip.
+ *   3. Otherwise dispatch + UPSERT last_run_at = tick_boundary.
+ *
+ * The advisory lock serializes the read+write so the check is honest.
+ *
+ * Schema constraints: framework PK kinds are `id`/`uuid`/`bigSerial`/
+ * `tenantedBigSerial`. None are text, so we can't make `name` itself
+ * the PK; instead ULID PK + `name` UNIQUE. The ULID is dead weight on
+ * the application side but keeps the row shape consistent with the
+ * rest of the framework.
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const schedulerRunsSchema = defineSchema('strav_scheduler_runs', Archetype.Entity, (t) => {
+  t.id()
+  t.string('name').max(128).unique()
+  t.timestamp('last_run_at')
+  t.timestamps()
+})

package/src/sync_queue.ts

@@ -0,0 +1,126 @@
+/**
+ * `SyncQueue` — in-process synchronous Queue driver.
+ *
+ * Instantiates the Job via the container (so `@inject()` resolves
+ * dependencies the same way the real Worker would), builds a
+ * `JobContext`, runs `handle(ctx)`. No persistence, no retries — if
+ * the handler throws, the throw propagates to the dispatcher.
+ *
+ * Use cases:
+ *   - **Tests** — drive a job end-to-end without standing up a
+ *     `DatabaseQueue` + Worker.
+ *   - **Single-process dev** — flatten the Queue → Worker hop so
+ *     `bun dev` shows job output inline.
+ *   - **Inline-by-design** — rare in production, but callers that
+ *     genuinely want sync execution (e.g. an importer that's already
+ *     in a transaction) call `dispatchSync` directly.
+ *
+ * The non-sync methods (`dispatch` / `dispatchLater`) on this driver
+ * also run the work synchronously — they exist so the same code path
+ * works in both sync-only test setups and async-Worker production
+ * setups. `dispatchLater`'s delay is ignored under SyncQueue; the work
+ * runs immediately.
+ */
+
+import { type Container, type Logger, ulid } from '@strav/kernel'
+import type { JobClass, JobContext, PayloadOf } from './job.ts'
+import type { DispatchLaterOptions, DispatchOptions, Queue } from './queue.ts'
+
+export interface SyncQueueOptions {
+  /**
+   * Container used to construct Job instances. `make(JobClass)` builds
+   * via `@inject()` metadata, so subclasses with constructor deps get
+   * the same wiring the production Worker provides.
+   */
+  container: Container
+  /**
+   * Optional Logger to attach to every `JobContext.log`. When omitted,
+   * a no-op logger is used — useful in tests where log noise is
+   * unwelcome.
+   */
+  logger?: Logger
+}
+
+export class SyncQueue implements Queue {
+  private readonly container: Container
+  private readonly logger: Logger
+
+  constructor(opts: SyncQueueOptions) {
+    this.container = opts.container
+    this.logger = opts.logger ?? createNoopLogger()
+  }
+
+  async dispatch<TJob extends JobClass>(
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+    _opts?: DispatchOptions,
+  ): Promise<string> {
+    const jobId = ulid()
+    await this.run(jobId, jobClass, payload)
+    return jobId
+  }
+
+  async dispatchLater<TJob extends JobClass>(
+    at: Date | number,
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+    _opts?: DispatchLaterOptions,
+  ): Promise<string> {
+    // Validate the delay even though we don't honor it — same contract
+    // surface as the production driver, so callers can't accidentally
+    // pass a negative delay that "works" under SyncQueue and fails on
+    // DatabaseQueue.
+    if (typeof at === 'number' && at < 0) {
+      throw new Error(`SyncQueue.dispatchLater: delay must be non-negative, got ${at}.`)
+    }
+    return this.dispatch(jobClass, payload)
+  }
+
+  async dispatchSync<TJob extends JobClass>(
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+  ): Promise<void> {
+    await this.run(ulid(), jobClass, payload)
+  }
+
+  private async run<TJob extends JobClass>(
+    jobId: string,
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+  ): Promise<void> {
+    const job = this.container.make(jobClass)
+    const ctx: JobContext = {
+      jobId,
+      attempt: 1,
+      payload,
+      // SyncQueue runs to completion in one tick — abort isn't a thing
+      // here. We hand out a never-aborted signal so handlers written
+      // against the production contract don't need a separate code
+      // path.
+      signal: new AbortController().signal,
+      log: this.logger,
+    }
+    await job.handle(ctx)
+  }
+}
+
+/**
+ * Bare Logger that drops every call. Avoids pulling in the full
+ * LoggerProvider when callers just want SyncQueue in tests.
+ */
+function createNoopLogger(): Logger {
+  const noop = () => undefined
+  // The Logger contract is wider; the few methods downstream code may
+  // call are stubbed. Cast keeps the type signature honest at the
+  // boundary — Logger's full surface includes `child()` etc., which a
+  // future caller could exercise.
+  return {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    fatal: noop,
+    trace: noop,
+    child: () => createNoopLogger(),
+  } as unknown as Logger
+}