@12-apps/jobs 1.20.0 → 3.0.0

package/src/server/config.ts

@@ -1,18 +1,22 @@
 import type { RegisteredJob } from "../core/registry";
-import type { JobDriver, JobLogger } from "../core/types";
+import type {
+  JobDriver,
+  JobEvents,
+  JobLogger,
+  JobRetention,
+} from "../core/types";
 import type { SweepLeaseDbProvider } from "../lease/sweep-lease";
 
 /**
  * The factory's config surface, and how it resolves against the environment.
  *
  * Every environment read happens in {@link resolveConfig}, which `start()`
- * calls — NOT the factory. future-pay's `bootstrapJobs()` read the whole
- * matrix (`JOBS_DRIVER`, `REDIS_URL`, `NODE_ENV`, `JOBS_WORKER`,
- * `JOBS_QUEUE_PREFIX`) at the moment it ran, and the recommended host shape
- * is factory-at-module-scope + `await jobsApi.start()` later — so an env var
- * that arrives between the two (a config module loading after the route
- * module) must be honoured for ALL of the matrix, not silently for one
- * variable and not the others.
+ * calls — NOT the factory. The whole matrix (`JOBS_DRIVER`, `REDIS_URL`,
+ * `NODE_ENV`, `JOBS_WORKER`, `JOBS_QUEUE_PREFIX`) has to be read at ONE
+ * moment, because the recommended host shape is factory-at-module-scope +
+ * `await jobsApi.start()` later: an env var that arrives between the two (a
+ * config module loading after the module that built the api) must be honoured
+ * for all of the matrix, not silently for one variable and not the others.
  */
 
 /** What the driver choice may say (`JOBS_DRIVER`, or `config.driver`). */
@@ -21,16 +25,38 @@ export type JobsDriverChoice = "bullmq" | "inline" | "off";
 /**
  * How the host names its jobs. An import thunk (`() => import("./jobs")`) is
  * the usual form — `defineJob` registers at module scope, so importing the
- * modules IS the registration. An array of already-registered jobs is
- * accepted for hosts (and tests) that hold the references anyway; it forces
- * the modules to have been imported, which is the same guarantee.
+ * modules IS the registration. An array of already-registered jobs is accepted
+ * for hosts (and tests) that hold the references anyway; it forces the modules
+ * to have been imported, which is the same guarantee.
+ *
+ * Neither form may be EMPTY. See {@link JobsConfigError}.
  */
 export type JobsSource =
   | readonly RegisteredJob<never>[]
   | (() => unknown | Promise<unknown>);
 
+/**
+ * Raised at ASSEMBLY for a config that cannot work — today, a `jobs` that
+ * names nothing.
+ *
+ * A required option that is never checked is still fail-open. `jobs: []` type-
+ * checks, starts, resolves a driver, installs no schedule, consumes no queue
+ * and answers `/health` with `status: "ok"` — every scheduled job in the
+ * deployment silently stops and the probe stays green. Refusing at the factory
+ * puts the failure at the line that wrote it.
+ */
+export class JobsConfigError extends Error {
+  constructor(detail: string) {
+    super(`createApiJobs: ${detail}`);
+    this.name = "JobsConfigError";
+  }
+}
+
 export interface JobsServerConfig {
-  /** Every job this process can enqueue or consume. See {@link JobsSource}. */
+  /**
+   * Every job this process can enqueue or consume. See {@link JobsSource}.
+   * Required, and refused when it names nothing.
+   */
   jobs: JobsSource;
   /**
    * A driver INSTANCE (tests, exotic hosts), a choice by name, or unset to
@@ -58,6 +84,22 @@ export interface JobsServerConfig {
   queuePrefix?: string;
   /** The host's logger. Defaults to the console. */
   logger?: JobLogger;
+  /**
+   * Where completions, dead-letters and removed schedules are reported. This
+   * package never notifies, audits or publishes anything itself — it exports
+   * the moment and the host wires the consequence.
+   */
+  events?: JobEvents;
+  /**
+   * How long finished jobs are kept. Defaults to the package's bounded
+   * default (a day of successes, a week of failures).
+   */
+  retention?: JobRetention;
+  /**
+   * Per-queue worker concurrency when no job on the queue states one. A job
+   * that states `concurrency: 1` still gets 1 — a stated value always wins.
+   */
+  defaultConcurrency?: number;
   /**
    * Where the `sweep_leases` table lives — enables `withSweepLease` on the
    * factory's return. Omit it and the lease helper rejects on first use,
@@ -80,6 +122,29 @@ const consoleLogger: JobLogger = {
   error: (message, ...meta) => console.error(`[jobs] ${message}`, ...meta),
 };
 
+/**
+ * Refuse a `jobs` that names nothing, at assembly.
+ *
+ * The array form is decidable here and is refused here. The thunk form is not
+ * — running it is the only way to know what it registers — so it is checked
+ * again after registration, inside `start()`. Both paths end at the same
+ * refusal, which is why neither is optional.
+ */
+export function assertJobsDeclared(jobs: JobsSource | undefined): void {
+  if (typeof jobs === "function") return;
+  if (!Array.isArray(jobs)) {
+    throw new JobsConfigError(
+      "`jobs` is required — an import thunk (() => import('./jobs')) or a non-empty array of defineJob() results.",
+    );
+  }
+  if (jobs.length === 0) {
+    throw new JobsConfigError(
+      "`jobs: []` declares no work. A process with no jobs consumes no queue, installs no " +
+        "schedule and still reports itself healthy — pass the jobs, or do not mount this package.",
+    );
+  }
+}
+
 /** `JOBS_WORKER=1|true` is how a deployment marks the consuming process. */
 export function isWorkerProcess(): boolean {
   const flag = process.env.JOBS_WORKER?.trim().toLowerCase();
@@ -93,6 +158,9 @@ export interface ResolvedConfig {
   worker: boolean;
   queuePrefix: string | undefined;
   logger: JobLogger;
+  events: JobEvents | undefined;
+  retention: JobRetention | undefined;
+  defaultConcurrency: number | undefined;
 }
 
 /**
@@ -108,5 +176,8 @@ export function resolveConfig(config: JobsServerConfig): ResolvedConfig {
     worker: config.worker ?? isWorkerProcess(),
     queuePrefix: config.queuePrefix ?? process.env.JOBS_QUEUE_PREFIX,
     logger: config.logger ?? consoleLogger,
+    events: config.events,
+    retention: config.retention,
+    defaultConcurrency: config.defaultConcurrency,
   };
 }

package/src/server/create-api-jobs.ts

@@ -1,4 +1,5 @@
-import { listJobs } from "../core/registry";
+import { assertJobsRegistered, listJobs } from "../core/registry";
+import { assertValidRetention } from "../core/retention";
 import {
   configureJobs,
   getJobDriver,
@@ -13,6 +14,7 @@ import {
 } from "../lease/sweep-lease";
 
 import {
+  assertJobsDeclared,
   isWorkerProcess,
   resolveConfig,
   type JobsServerConfig,
@@ -59,16 +61,23 @@ import { resolveDriver } from "./resolve-driver";
  * with no Redis container. That is the default a fresh host is supposed to
  * boot in.
  *
+ * ## `jobs` is refused when it names nothing
+ *
+ * "Fail closed, never fail loud" is about the QUEUE. It does not extend to the
+ * wiring: `jobs: []`, or a thunk that registers nothing because its import was
+ * dropped, produces a process that resolves a driver, consumes no queue,
+ * installs no schedule and answers `/health` with `ok`. Every scheduled job in
+ * the deployment stops and nothing reports it. So an empty `jobs` throws — at
+ * the factory for the array form, and after registration for the thunk form.
+ *
  * ## The environment is read at `start()`, not at the factory
  *
- * future-pay's `bootstrapJobs()` read the whole matrix — `JOBS_DRIVER`,
- * `REDIS_URL`, `NODE_ENV`, `JOBS_WORKER`, `JOBS_QUEUE_PREFIX` — at the moment
- * it ran, and the recommended host shape is factory-at-module-scope +
- * `await jobsApi.start()` at process start. Reading part of the matrix at
- * factory time would honour a late-arriving `JOBS_DRIVER` and silently
- * ignore a late-arriving `REDIS_URL` (a host whose config module loads after
- * the module that built the api), so the factory reads nothing and `start()`
- * resolves everything at one single moment.
+ * The recommended host shape is factory-at-module-scope + `await
+ * jobsApi.start()` at process start. Reading part of the matrix at factory
+ * time would honour a late-arriving `JOBS_DRIVER` and silently ignore a
+ * late-arriving `REDIS_URL` (a host whose config module loads after the module
+ * that built the api), so the factory reads nothing and `start()` resolves
+ * everything at one single moment.
  */
 
 /** What a route handler answers; the host maps it onto its response type. */
@@ -77,7 +86,7 @@ export interface JobsResponse {
   body: unknown;
 }
 
-/** A framework-neutral route descriptor, the same shape report-builder mounts. */
+/** A framework-neutral route descriptor. */
 export interface JobsRoute {
   method: "GET";
   /** Path relative to the host's jobs mount, e.g. `/health`. */
@@ -178,9 +187,8 @@ function bindSweepLease(db: SweepLeaseDbProvider | undefined): WithSweepLease {
 /** What one `start()`/`stop()` cycle has actually done in this process. */
 interface RuntimeState {
   /**
-   * `start()` has been ENTERED — the idempotency latch, exactly future-pay's
-   * `bootstrapped` flag: a second call is a no-op, and a start that threw is
-   * not retried by calling it again.
+   * `start()` has been ENTERED — the idempotency latch: a second call is a
+   * no-op, and a start that threw is not retried by calling it again.
    */
   starting: boolean;
   /**
@@ -282,9 +290,11 @@ async function startRuntime(
   if (stopped()) return;
   state.deliberatelyOff = deliberatelyOff;
   if (!driver) {
-    // Fail closed, by design: "no driver" is a completed start (future-pay's
-    // bootstrapJobs returned normally here too). Health still reports it —
-    // the driver check is null — so the probe sees what the log line said.
+    // Fail closed, by design: "no driver" is a completed start. Health still
+    // reports it — the driver check is null — so the probe sees what the log
+    // line said. Registration is deliberately skipped: a process with jobs
+    // disabled must not install seams whose enqueues would all report
+    // `no-driver`.
     state.started = true;
     return;
   }
@@ -295,6 +305,11 @@ async function startRuntime(
   // whatever is registered — a worker cannot consume a job it has never heard
   // of, and a producer cannot enqueue one.
   await registerJobs(config.jobs);
+  // The thunk form's half of the empty-`jobs` refusal (the array form was
+  // refused at the factory). It runs for BOTH roles: a producer that
+  // registered nothing enqueues nothing, which is the same silent stop as a
+  // worker that consumes nothing.
+  assertJobsRegistered("createApiJobs().start()");
   if (stopped()) return;
 
   if (!worker) {
@@ -315,6 +330,16 @@ async function startRuntime(
 }
 
 export function createApiJobs(config: JobsServerConfig): JobsApi {
+  // At ASSEMBLY, before anything else: a `jobs` that names nothing is a wiring
+  // error, and the factory is where the stack trace still points at the host
+  // module that wrote it.
+  assertJobsDeclared(config?.jobs);
+  // The same class of failure, one knob over: a retention window that is NaN
+  // or negative does not shrink retention, it stops bounding the backend at
+  // all — silently, weeks before anyone notices. The driver re-checks it, for
+  // a host that builds one directly off `@12-apps/jobs/bullmq`.
+  assertValidRetention(config?.retention);
+
   const state: RuntimeState = {
     starting: false,
     started: false,
@@ -340,9 +365,8 @@ export function createApiJobs(config: JobsServerConfig): JobsApi {
 
     async start(): Promise<void> {
       // The latch, not the success flag: a second call is a no-op, and a
-      // start that threw is not silently retried — future-pay's bootstrapJobs
-      // latched `bootstrapped` the same way. Success is `startRuntime`'s to
-      // declare, as its last statement.
+      // start that threw is not silently retried. Success is `startRuntime`'s
+      // to declare, as its last statement.
       if (state.starting) return;
       state.starting = true;
       // The whole env matrix is read HERE, at the same moment the driver

package/src/server/index.ts

@@ -7,8 +7,10 @@
  * internal probes live.
  *
  *     const jobsApi = createApiJobs({
- *       jobs: () => import("./lib/jobs"),      // defineJob modules
+ *       jobs: () => import("./lib/jobs"),      // defineJob modules — required,
+ *                                             // and refused if it names nothing
  *       db: () => getPrismaClient(),           // the sweep_leases table
+ *       events: { onJobFailed: … },            // dead-letters, for YOUR notifier
  *     });
  *     await jobsApi.start();                   // at process start
  *     app.route("/api/internal/jobs", jobsRouter(jobsApi));   // ./hono
@@ -24,4 +26,10 @@ export type {
   JobsResponse,
   JobsRoute,
 } from "./create-api-jobs";
+export { JobsConfigError } from "./config";
 export type { JobsDriverChoice, JobsServerConfig, JobsSource } from "./config";
+// Re-exported so a host that only imports `/server` can catch what the factory
+// and `start()` throw without also reaching for the root entry point.
+export { NoJobsRegisteredError } from "../core/registry";
+export { InvalidJobRetentionError } from "../core/retention";
+export type { JobEvents, JobRetention } from "../core/types";

package/src/server/resolve-driver.ts

@@ -4,13 +4,14 @@ import { createInlineJobDriver } from "../drivers/inline";
 import type { JobsDriverChoice, JobsServerConfig, ResolvedConfig } from "./config";
 
 /**
- * Driver resolution — future-pay `runtime.ts`'s `readDriverChoice` +
- * `resolveDriver`. The choice can also arrive through `config.driver` (a name
- * or an instance), which future-pay had no seam for — so the resolution
- * tracks WHERE the choice came from, validates the config path exactly as
- * strictly as the env path, and names the right knob in every error message.
- * The `JOBS_DRIVER=…` messages stay byte-identical to future-pay's, because
- * a host greps for them.
+ * Driver resolution.
+ *
+ * The choice can arrive from the environment (`JOBS_DRIVER`) or through
+ * `config.driver` — a name or a ready-made instance. The resolution tracks
+ * WHERE the choice came from, validates the config path exactly as strictly as
+ * the env path, and names the right knob in every error message: an operator
+ * reading a `JOBS_DRIVER` message for a choice made in code would hunt for an
+ * env var that is not set.
  */
 
 /** A resolved choice, and which knob said so. */
@@ -136,7 +137,14 @@ async function resolveBullMq(
     // once the host bundles this package's published TS source.
     const { createBullMqJobDriver } = await import("../drivers/bullmq");
     return {
-      driver: createBullMqJobDriver({ redisUrl, logger, prefix: resolved.queuePrefix }),
+      driver: createBullMqJobDriver({
+        redisUrl,
+        logger,
+        prefix: resolved.queuePrefix,
+        events: resolved.events,
+        retention: resolved.retention,
+        defaultConcurrency: resolved.defaultConcurrency,
+      }),
       deliberatelyOff: false,
     };
   } catch (error) {
@@ -165,11 +173,8 @@ export async function resolveDriver(
 
   if (choice === "off") {
     if (production) {
-      // Logged in production even for an explicit off — the BEHAVIOUR is
-      // future-pay's runtime.ts, though not the bytes: its message named the
-      // domain sweeps, and the examples were dropped when this moved into
-      // the package. Production with no queue is worth a line in the log
-      // however it came about.
+      // Logged in production even for an explicit off: production with no
+      // queue is worth a line in the log however it came about.
       logger.error(
         "No job driver: scheduled work will NOT run in this deployment. Set REDIS_URL.",
       );
@@ -195,7 +200,10 @@ export async function resolveDriver(
     // Detached on purpose: in a dev server the handler must not run inside
     // the request that enqueued it. A test that wants to await the handler
     // passes its own `createInlineJobDriver({ await: true })` instance.
-    return { driver: createInlineJobDriver({ logger, await: false }), deliberatelyOff: false };
+    return {
+      driver: createInlineJobDriver({ logger, await: false, events: resolved.events }),
+      deliberatelyOff: false,
+    };
   }
 
   return resolveBullMq(named, resolved);