@12-apps/jobs 1.19.0 → 1.20.0

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

@@ -0,0 +1,363 @@
+import { listJobs } from "../core/registry";
+import {
+  configureJobs,
+  getJobDriver,
+  startJobWorkers,
+  stopJobs,
+} from "../core/runtime";
+import type { JobLogger } from "../core/types";
+import {
+  createSweepLease,
+  type SweepLeaseDbProvider,
+  type WithSweepLease,
+} from "../lease/sweep-lease";
+
+import {
+  isWorkerProcess,
+  resolveConfig,
+  type JobsServerConfig,
+  type JobsSource,
+  type ResolvedConfig,
+} from "./config";
+import { resolveDriver } from "./resolve-driver";
+
+/**
+ * `createApiJobs` — the jobs runtime as ONE mountable surface.
+ *
+ * The bootstrap used to live in the host: a runtime module that read the
+ * environment, picked a driver, refused the unsafe one in production,
+ * registered every job, started the workers and hooked the drain signals.
+ * None of that is host domain — the only decisions a host genuinely owns are
+ * WHICH jobs exist and WHERE the lease table lives, and both arrive here as
+ * config.
+ *
+ * ## Two roles, one image
+ *
+ * A PRODUCER (the web server) configures the driver and enqueues. A CONSUMER
+ * (the worker) does that and also starts consuming, which is the only
+ * difference between the two — so the worker is the SAME container image with
+ * `JOBS_WORKER=1` set, not a second build. Splitting the roles keeps a slow
+ * job off the request path; running them in one process (set `JOBS_WORKER=1`
+ * on the web service and skip the worker service) also works and is a
+ * reasonable choice on a single small box.
+ *
+ * ## Fail closed, never fail loud
+ *
+ * A misconfigured queue must never take the host app down. Every problem here
+ * (no `REDIS_URL` in production, `inline` requested in production, an
+ * unparseable URL, `bullmq` failing to load) resolves to NO driver plus a
+ * loud error: enqueues then report `no-driver` instead of throwing, the
+ * durable rows still get written, and the sweeps catch up once a worker
+ * exists. The health endpoint reports the same fact as a 503, so a probe can
+ * see what the log line said.
+ *
+ * ## Zero config is a real mode
+ *
+ * `createApiJobs({ jobs })` with nothing else and no `REDIS_URL` in the
+ * environment resolves to the INLINE driver outside production: handlers run
+ * in-process, schedules do not fire (and say so), and the app starts green
+ * with no Redis container. That is the default a fresh host is supposed to
+ * boot in.
+ *
+ * ## 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.
+ */
+
+/** What a route handler answers; the host maps it onto its response type. */
+export interface JobsResponse {
+  status: number;
+  body: unknown;
+}
+
+/** A framework-neutral route descriptor, the same shape report-builder mounts. */
+export interface JobsRoute {
+  method: "GET";
+  /** Path relative to the host's jobs mount, e.g. `/health`. */
+  path: string;
+  handle(): Promise<JobsResponse>;
+}
+
+/**
+ * The health payload `GET /health` answers with.
+ *
+ * Three states, two status codes: `ok` (200) is a working runtime; `disabled`
+ * (200) is an EXPLICIT `off` — `JOBS_DRIVER=off` or
+ * `createApiJobs({ driver: "off" })` — OUTSIDE production: a review box or CI
+ * that genuinely wants no queue, which must not fail a readiness aggregate
+ * forever; `degraded` (503) is everything that is wrong rather than chosen —
+ * a misconfiguration, a failed start, a drained worker, and any production
+ * with no queue, spelled out or not (production never deliberately wants
+ * none).
+ */
+export interface JobsHealth {
+  status: "ok" | "degraded" | "disabled";
+  checks: {
+    /**
+     * `start()` has completed WITHOUT THROWING in this process. A start that
+     * rejected (a duplicate job name, a failing registration import) leaves
+     * this false and the status degraded — a failed boot must never probe
+     * green.
+     */
+    configured: boolean;
+    /**
+     * The resolved driver's kind, or null when jobs are disabled. Reads the
+     * process-wide runtime: with two `createApiJobs` instances in one process
+     * (never a real host's shape) each reports whichever driver was
+     * configured last.
+     */
+    driver: string | null;
+    /**
+     * Whether this process is meant to consume, not just enqueue.
+     * Provisional until `start()` has run: before then it is a best-effort
+     * read of `config.worker` / `JOBS_WORKER` at probe time (pre-start health
+     * is degraded regardless, so nothing is decided from it).
+     */
+    worker: boolean;
+    /** Whether consuming actually began (always false in a producer). */
+    consuming: boolean;
+    /** Registered job definitions. */
+    jobs: number;
+    /** How many of them run on a cron schedule. */
+    schedules: number;
+  };
+}
+
+export interface JobsApi {
+  /** The health endpoint. Mount with `@12-apps/jobs/hono` or your own adapter. */
+  routes: JobsRoute[];
+  /**
+   * Configure the driver, register every job, and — in a worker — start
+   * consuming and install the cron schedules. Call it once at process start,
+   * before the first request; safe to call again (no-op). Never throws for a
+   * MISCONFIGURED queue (see "fail closed" above) — only for a programming
+   * error such as a duplicate job name.
+   */
+  start(): Promise<void>;
+  /** Stop consuming and release the driver's connections, draining in-flight jobs. */
+  stop(): Promise<void>;
+  /**
+   * Single-writer lease for cron sweeps, bound to `config.db`. See
+   * {@link createSweepLease} for the contract.
+   */
+  withSweepLease: WithSweepLease;
+}
+
+/** Trigger the host's registrations. An array means "already registered". */
+async function registerJobs(jobs: JobsSource): Promise<void> {
+  if (typeof jobs === "function") await jobs();
+}
+
+/** The lease bound to the configured db — or, without one, a loud refusal. */
+function bindSweepLease(db: SweepLeaseDbProvider | undefined): WithSweepLease {
+  const lease = db ? createSweepLease({ db }) : null;
+  // Async so the refusal is a REJECTION, which is what the type promises: a
+  // synchronous throw from a Promise-returning function escapes `.catch()`
+  // and `Promise.all`, and a caller that collected the promise before
+  // awaiting it would never see the error at all.
+  return async (name, ttlMs, work) => {
+    if (!lease) {
+      // Loud, not silent: a sweep whose lease quietly no-ops is exactly the
+      // unprotected concurrent pass the lease exists to prevent. Same rule as
+      // the claim itself — only a lost race may be silent.
+      throw new Error(
+        "withSweepLease needs a `db` provider in createApiJobs({ db }).",
+      );
+    }
+    return lease.withSweepLease(name, ttlMs, work);
+  };
+}
+
+/** 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.
+   */
+  starting: boolean;
+  /**
+   * `start()` has COMPLETED without throwing — the success flag health keys
+   * on. Kept separate from `starting` because a start that rejected must
+   * leave the probe red, not report the half-configured runtime as ok.
+   */
+  started: boolean;
+  consuming: boolean;
+  /** Resolution chose "no driver" because it was TOLD to — see {@link JobsHealth}. */
+  deliberatelyOff: boolean;
+  /**
+   * The drain hooks have been installed — once per instance, ever. A
+   * stop()/start() cycle must not stack a second `process.once` pair, or one
+   * real signal would drain the driver twice.
+   */
+  hooksInstalled: boolean;
+  /**
+   * The env-resolved config, cached by `start()`. Null until then: the
+   * factory deliberately reads no environment (see the module header), so a
+   * pre-start health probe falls back to reading the worker switch at handle
+   * time.
+   */
+  resolved: ResolvedConfig | null;
+}
+
+/** "disabled" is a choice, "ok" is a working runtime, "degraded" is a fault. */
+function statusOf(
+  state: RuntimeState,
+  driverKind: string | null,
+  worker: boolean,
+): JobsHealth["status"] {
+  if (state.started && state.deliberatelyOff) return "disabled";
+  const ready = state.started && driverKind !== null && (!worker || state.consuming);
+  return ready ? "ok" : "degraded";
+}
+
+function healthOf(config: JobsServerConfig, state: RuntimeState): JobsHealth {
+  const definitions = listJobs();
+  const driver = getJobDriver()?.kind ?? null;
+  const worker = state.resolved
+    ? state.resolved.worker
+    : (config.worker ?? isWorkerProcess());
+  return {
+    status: statusOf(state, driver, worker),
+    checks: {
+      configured: state.started,
+      driver,
+      worker,
+      consuming: state.consuming,
+      jobs: definitions.length,
+      schedules: definitions.filter((job) => job.schedule).length,
+    },
+  };
+}
+
+/**
+ * Let in-flight jobs finish on a deploy. Deliberately does NOT call
+ * process.exit — the host owns the shutdown, and cutting it short here would
+ * kill the very requests we are draining for.
+ *
+ * The hook clears the instance state BEFORE the async drain: a drained worker
+ * is no longer consuming, and the readiness probe must stop saying it is the
+ * moment the drain begins — that flip is what tells a rolling deploy to stop
+ * routing to this process.
+ */
+function installDrainHooks(logger: JobLogger, state: RuntimeState): void {
+  for (const signal of ["SIGTERM", "SIGINT"] as const) {
+    process.once(signal, () => {
+      state.consuming = false;
+      state.started = false;
+      void stopJobs().catch((error) => logger.error("shutdown failed:", error));
+    });
+  }
+}
+
+/**
+ * The `start()` body: configure, register, and — in a worker — consume.
+ *
+ * `state.started` is set LAST on every successful path, so a throw anywhere
+ * in here (a duplicate job name, a registration import that fails) leaves the
+ * health endpoint degraded rather than reporting the half-configured runtime
+ * as ok.
+ */
+async function startRuntime(
+  config: JobsServerConfig,
+  resolved: ResolvedConfig,
+  state: RuntimeState,
+): Promise<void> {
+  const { logger, worker } = resolved;
+  // A stop() that lands while start() is awaiting wins: `stop()` clears
+  // `starting`, and each publish point below re-checks it — otherwise the
+  // start's continuation would set consuming/started AFTER the stop and a
+  // stopped runtime would advertise itself as a healthy consumer (the same
+  // untruth the drain-hook fix closed, one window narrower).
+  const stopped = (): boolean => !state.starting;
+
+  const { driver, deliberatelyOff } = await resolveDriver(config, resolved);
+  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.
+    state.started = true;
+    return;
+  }
+
+  configureJobs({ driver, logger });
+
+  // Registers every job. Must happen BEFORE `startJobWorkers`, which consumes
+  // whatever is registered — a worker cannot consume a job it has never heard
+  // of, and a producer cannot enqueue one.
+  await registerJobs(config.jobs);
+  if (stopped()) return;
+
+  if (!worker) {
+    logger.info("producer mode: jobs will be enqueued, not consumed by this process.");
+    state.started = true;
+    return;
+  }
+
+  await startJobWorkers();
+  if (stopped()) return;
+  state.consuming = true;
+
+  if ((config.installShutdownHooks ?? true) && !state.hooksInstalled) {
+    installDrainHooks(logger, state);
+    state.hooksInstalled = true;
+  }
+  state.started = true;
+}
+
+export function createApiJobs(config: JobsServerConfig): JobsApi {
+  const state: RuntimeState = {
+    starting: false,
+    started: false,
+    consuming: false,
+    deliberatelyOff: false,
+    hooksInstalled: false,
+    resolved: null,
+  };
+
+  return {
+    routes: [
+      {
+        method: "GET",
+        path: "/health",
+        handle: async () => {
+          const body = healthOf(config, state);
+          // Only "degraded" is a failure; "disabled" is a choice and must not
+          // fail a readiness aggregate forever.
+          return { status: body.status === "degraded" ? 503 : 200, body };
+        },
+      },
+    ],
+
+    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.
+      if (state.starting) return;
+      state.starting = true;
+      // The whole env matrix is read HERE, at the same moment the driver
+      // choice reads JOBS_DRIVER — never at factory time.
+      state.resolved = resolveConfig(config);
+      await startRuntime(config, state.resolved, state);
+    },
+
+    async stop(): Promise<void> {
+      await stopJobs();
+      state.consuming = false;
+      state.started = false;
+      state.starting = false;
+    },
+
+    withSweepLease: bindSweepLease(config.db),
+  };
+}

package/src/server/index.ts

@@ -0,0 +1,27 @@
+/**
+ * `@12-apps/jobs/server` — the backend factory.
+ *
+ * One call wires the whole operational half: driver resolution (with the
+ * inline zero-config default), job registration, the worker switch, graceful
+ * drain, the sweep lease and a health endpoint the host mounts wherever its
+ * internal probes live.
+ *
+ *     const jobsApi = createApiJobs({
+ *       jobs: () => import("./lib/jobs"),      // defineJob modules
+ *       db: () => getPrismaClient(),           // the sweep_leases table
+ *     });
+ *     await jobsApi.start();                   // at process start
+ *     app.route("/api/internal/jobs", jobsRouter(jobsApi));   // ./hono
+ *
+ * There is deliberately NO `createWebJobs` half: this runtime has no screens
+ * — its API surface is the health endpoint, and its user-visible effects are
+ * whatever the host's job handlers do. See ADOPTING.md.
+ */
+export { createApiJobs } from "./create-api-jobs";
+export type {
+  JobsApi,
+  JobsHealth,
+  JobsResponse,
+  JobsRoute,
+} from "./create-api-jobs";
+export type { JobsDriverChoice, JobsServerConfig, JobsSource } from "./config";

package/src/server/resolve-driver.ts

@@ -0,0 +1,202 @@
+import type { JobDriver } from "../core/types";
+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.
+ */
+
+/** A resolved choice, and which knob said so. */
+interface DriverChoice {
+  choice: JobsDriverChoice;
+  /**
+   * `env` is `JOBS_DRIVER`; `config` is `createApiJobs({ driver })`;
+   * `default` is the matrix (Redis presence / production). An INVALID value
+   * resolves to `off` with source `default`: a misconfiguration is not a
+   * deliberate opt-out.
+   */
+  source: "config" | "env" | "default";
+}
+
+/** The allow-list. Anything else is a misconfiguration, never a guess. */
+function asChoice(value: string): JobsDriverChoice | null {
+  return value === "bullmq" || value === "inline" || value === "off" ? value : null;
+}
+
+function resolveChoice(
+  config: JobsServerConfig,
+  resolved: ResolvedConfig,
+): DriverChoice {
+  if (typeof config.driver === "string") {
+    const named = asChoice(config.driver.trim().toLowerCase());
+    if (named) return { choice: named, source: "config" };
+    // The type forbids this, but a JS consumer can pass anything — and the
+    // env path validates, so the config path must too: same value, same
+    // loud-and-off outcome, never a silent fallthrough to bullmq.
+    resolved.logger.error(
+      `createApiJobs({ driver: "${config.driver}" }) is not a driver; jobs are disabled.`,
+    );
+    return { choice: "off", source: "default" };
+  }
+  if (config.driver !== undefined) {
+    // Not a string, and the caller already peeled off object instances — so
+    // this is 42, true, null: junk only a JS consumer can pass. It must not
+    // fall through to the env matrix as if nothing had been said.
+    resolved.logger.error(
+      `createApiJobs({ driver: ${JSON.stringify(config.driver)} }) is not a driver; jobs are disabled.`,
+    );
+    return { choice: "off", source: "default" };
+  }
+  const configured = process.env.JOBS_DRIVER?.trim().toLowerCase();
+  if (configured) {
+    const named = asChoice(configured);
+    if (named) return { choice: named, source: "env" };
+    resolved.logger.error(
+      `JOBS_DRIVER="${configured}" is not a driver; jobs are disabled.`,
+    );
+    return { choice: "off", source: "default" };
+  }
+  // Unset: Redis being configured is the signal that a queue exists.
+  if (resolved.redisUrl) return { choice: "bullmq", source: "default" };
+  return { choice: resolved.production ? "off" : "inline", source: "default" };
+}
+
+/**
+ * Names the knob a choice came from, so an operator debugging the log line is
+ * sent to the setting that actually said it — a `JOBS_DRIVER` message for a
+ * choice made in code would have them hunting for an env var that is not set.
+ */
+function knob(choice: JobsDriverChoice, source: DriverChoice["source"]): string {
+  return source === "config"
+    ? `createApiJobs({ driver: "${choice}" })`
+    : `JOBS_DRIVER=${choice}`;
+}
+
+/**
+ * What resolution decided, and whether "no driver" was a deliberate choice.
+ * Not exported: `createApiJobs` destructures it, and an exported type nothing
+ * imports is exactly what the knip gate is there to stop.
+ */
+interface DriverResolution {
+  driver: JobDriver | null;
+  /**
+   * True only for an EXPLICIT `off` — `JOBS_DRIVER=off` or
+   * `createApiJobs({ driver: "off" })` — OUTSIDE production: a review box or
+   * a CI environment that genuinely wants no queue. False for every
+   * misconfiguration that merely RESOLVES to off, and false in production
+   * even when spelled out (production never deliberately wants no queue), so
+   * health can tell "disabled by choice" apart from "broken".
+   */
+  deliberatelyOff: boolean;
+}
+
+const off = (deliberatelyOff: boolean): DriverResolution => ({
+  driver: null,
+  deliberatelyOff,
+});
+
+/**
+ * An instance passed in is the host's own decision — for anything except the
+ * inline driver in production, which is refused for exactly the reason the
+ * NAMED choice is: no retries, no schedules, and work that dies with the
+ * request that enqueued it. An instance must not be the quiet way around
+ * that guard.
+ */
+function resolveInstance(driver: JobDriver, resolved: ResolvedConfig): DriverResolution {
+  if (resolved.production && driver.kind === "inline") {
+    resolved.logger.error(
+      "an inline driver instance is refused in production; jobs are disabled.",
+    );
+    return off(false);
+  }
+  return { driver, deliberatelyOff: false };
+}
+
+/** The bullmq branch: a Redis URL is required, and the import stays lazy. */
+async function resolveBullMq(
+  choice: DriverChoice,
+  resolved: ResolvedConfig,
+): Promise<DriverResolution> {
+  const { logger, redisUrl } = resolved;
+  if (!redisUrl) {
+    logger.error(`${knob(choice.choice, choice.source)} needs REDIS_URL; jobs are disabled.`);
+    return off(false);
+  }
+  try {
+    // Imported lazily so `bullmq` (and ioredis) are pulled in only by a
+    // process that actually talks to Redis — never into a bundle that only
+    // enqueues. The specifier is a literal, which is what keeps it loadable
+    // once the host bundles this package's published TS source.
+    const { createBullMqJobDriver } = await import("../drivers/bullmq");
+    return {
+      driver: createBullMqJobDriver({ redisUrl, logger, prefix: resolved.queuePrefix }),
+      deliberatelyOff: false,
+    };
+  } catch (error) {
+    logger.error("could not create the BullMQ driver; jobs are disabled:", error);
+    return off(false);
+  }
+}
+
+/**
+ * Pick the driver, or NULL for "jobs are disabled in this process" — which is
+ * always accompanied by a loud log line, never silent, unless it was a
+ * deliberate `off`.
+ */
+export async function resolveDriver(
+  config: JobsServerConfig,
+  resolved: ResolvedConfig,
+): Promise<DriverResolution> {
+  const { logger, production } = resolved;
+
+  if (config.driver && typeof config.driver === "object") {
+    return resolveInstance(config.driver, resolved);
+  }
+
+  const named = resolveChoice(config, resolved);
+  const { choice, source } = named;
+
+  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.
+      logger.error(
+        "No job driver: scheduled work will NOT run in this deployment. Set REDIS_URL.",
+      );
+    }
+    // Deliberate only OUTSIDE production. A review box or CI genuinely wants
+    // no queue; production never does — a JOBS_DRIVER=off that reaches it
+    // through a shared env template or a promoted staging config is a
+    // mistake, and the probe must answer 503 exactly like the unconfigured
+    // case rather than green-light the same fact the error line above just
+    // reported.
+    return off(source !== "default" && !production);
+  }
+
+  if (choice === "inline") {
+    if (production) {
+      // Inline runs the handler inside whatever request enqueued it and has
+      // no retries and no schedules. That is a development convenience, and
+      // in production it would silently drop work a crash interrupts.
+      logger.error(`${knob(choice, source)} is refused in production; jobs are disabled.`);
+      return off(false);
+    }
+    logger.info("using the inline job driver (no Redis): schedules will not fire.");
+    // 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 resolveBullMq(named, resolved);
+}