@12-apps/jobs 1.18.0 → 1.20.0

package/ADOPTING.md

@@ -0,0 +1,139 @@
+# Adopting @12-apps/jobs
+
+This package is a **plug-and-play background-job runtime**: one library,
+reusable across repositories, exposing standardized surfaces. A host repo only
+*points* at these surfaces — when the library updates, every host updates with
+**no app changes**. The contract below is the same one `@12-apps/report-builder`
+and `@12-apps/payments-backend` established.
+
+## The standardized plugin surfaces
+
+| Surface | Export | What the host does |
+|---|---|---|
+| **Core library** | `@12-apps/jobs` | `defineJob` next to the domain each job belongs to (the import IS the registration), `enqueue` at emit sites, `SWEEP_QUEUE` + `createSweepLease` for scheduled sweeps. Never drags Redis into a bundle. |
+| **Server** | `@12-apps/jobs/server` | Call `createApiJobs(config)` once at process start: driver resolution (with the inline zero-config default and the production refusals), job registration, the `JOBS_WORKER` producer/consumer switch, graceful drain on `SIGTERM`/`SIGINT`, the bound sweep lease, and the health endpoint as framework-neutral route descriptors. |
+| **Hono** | `@12-apps/jobs/hono` | `app.route(prefix, jobsRouter(jobsApi))`. A one-call mount for hosts on Hono; `hono` is an OPTIONAL peer, so importing the root or `/server` never resolves it. |
+| **Drivers** | `@12-apps/jobs/bullmq`, `@12-apps/jobs/inline` | Nothing, usually — `createApiJobs` resolves them. Import directly only to hand a pre-built instance in (`driver: createInlineJobDriver({ await: true })` in a test). |
+| **Prisma** | `prisma/jobs.prisma` + `prisma/migrations/*` | Sync BOTH into the host's schema/migrations folders as **copies** (see below). One table: `sweep_leases`. |
+
+## Why there is no `createWebJobs`
+
+The porting contract asks for both halves — `createApiFoo` and `createWebFoo`
+— and this package deliberately ships only the first. The runtime is headless:
+it has no screens, no flows and no routes a user ever sees. Its API surface is
+the health endpoint (`GET /health` on the mounted routes), which exists for
+probes and dashboards, not for people; its user-visible effects are whatever
+the HOST's job handlers do, and those handlers are exactly the part that stays
+in the host. Inventing a web half here would mean shipping an admin UI for a
+queue this package does not own the semantics of — that is a different
+product (and BullMQ already has several). If a host wants a jobs dashboard,
+it reads the same health endpoint every other probe reads.
+
+## Host wiring rules (the ones that bite)
+
+1. **The host owns the handlers; this package owns the running of them.**
+   Job definitions, their retry policies and their schedules are host domain —
+   they stay in the host, declared with `defineJob` next to the code they
+   belong to. What moved here is everything operational: which driver runs,
+   when workers start, how they drain, who may run a sweep.
+2. **Payloads carry identifiers, never state**, and every handler is
+   idempotent — delivery is at-least-once. Both rules are documented on
+   `JobDefinition`; they are the design the whole package rests on. Pair every
+   job with a durable row a sweep can re-find: the enqueue is only the fast
+   path, and `enqueue` never throws.
+3. **Duck-typed DB, never a generated client.** The sweep lease takes the
+   host's Prisma client through a structural seam (`SweepLeaseDb`), as a lazy
+   provider: `db: () => getPrismaClient()`. A non-Prisma adapter must honour
+   one contract: `create` rejects a duplicate primary key with an error
+   carrying `code: "P2002"` — that is the one error the claim reads as "lost
+   the race" rather than "the store is broken".
+4. **The zero-config default is a real mode, keep it reachable.** A fresh
+   host with no `REDIS_URL` must boot green: `createApiJobs` resolves the
+   inline driver outside production (handlers in-process, schedules off and
+   logged). Do not "fix" that by demanding Redis in dev.
+5. **Fail closed, never fail loud.** In production every misconfiguration
+   (no `REDIS_URL`, `inline` requested, a bad URL) resolves to NO driver plus
+   a loud error log and a 503 from `/health`. Enqueues then report
+   `no-driver`; the durable rows still get written. A queue must never take
+   the host app down.
+6. **Auth for the health endpoint is the host's.** Mount `jobsRouter` under
+   whatever guard the deployment's internal probes live behind (future-pay
+   answers `/api/internal/*` only machine-to-machine). The package holds zero
+   authorization logic.
+7. **Sweeps: one queue, one flight, one lease.** Declare scheduled sweeps
+   with `queue: SWEEP_QUEUE, concurrency: 1` and take
+   `withSweepLease(name, ttlMs, work)` inside the handler. The TTL must
+   comfortably exceed the sweep's own duration — a lease expiring mid-sweep
+   is the one way two workers can still overlap. Only a lost race is silent;
+   a real store fault throws, so a stopped sweep has a failed job to notice.
+
+## Configuration
+
+`createApiJobs(config)` — every field optional except `jobs`; unset fields
+default from the environment, which is what makes the mount one line:
+
+| Config | Env default | Meaning |
+|---|---|---|
+| `jobs` | — | An import thunk (`() => import("./jobs")`) or an array of `defineJob` returns. Registration. |
+| `driver` | `JOBS_DRIVER` | `bullmq` \| `inline` \| `off`, or a `JobDriver` instance. Unset → `bullmq` when a Redis URL exists, else `off` in production, `inline` elsewhere. |
+| `redisUrl` | `REDIS_URL` | Setting it turns the queue on. |
+| `worker` | `JOBS_WORKER` (`1`/`true`) | This process consumes and runs schedules, not just enqueues. |
+| `production` | `NODE_ENV === "production"` | Refuses `inline`, makes "no queue" loud. |
+| `queuePrefix` | `JOBS_QUEUE_PREFIX` | Share one Redis across environments. |
+| `logger` | console | Structurally a winston logger or `console`. |
+| `db` | — | `() => SweepLeaseDb` — enables `withSweepLease`. Without it the lease throws on first use (loud, never a silent skip). |
+| `installShutdownHooks` | `true` | `SIGTERM`/`SIGINT` drain in-flight jobs (workers only). Off in tests. |
+
+## The endpoints
+
+Mounted under whatever prefix the host chooses (recommended: wherever its
+internal probes live, e.g. `/api/internal/jobs`):
+
+| Method | Path | Notes |
+|---|---|---|
+| GET | `/health` | 200 `{ status: "ok", checks }` when the runtime is in its intended state; 200 `{ status: "disabled", checks }` when jobs are off **by explicit choice outside production** (`JOBS_DRIVER=off` / `driver: "off"` — a review box or CI must not fail a readiness aggregate forever); 503 `{ status: "degraded", checks }` for everything wrong rather than chosen — a misconfiguration, a `start()` that threw, a worker that stopped consuming, and ANY production with no queue, spelled out or not: production never deliberately wants none, so an explicit off that reaches it through a shared env template still probes red. `checks` reports the resolved driver kind, producer/consumer role, consuming state, and the registered job/schedule counts. |
+
+## The Prisma partial — copies, never symlinks
+
+The `SweepLease` model and its migration ship in this package:
+
+```
+packages/jobs/prisma/jobs.prisma          # the model partial
+packages/jobs/prisma/migrations/          # its migration
+```
+
+A host adopts them by COPY (the entity-lifecycle / shift precedent — in this
+repo, `packages/shared-helpers/scripts/sync-jobs-schema.mjs` plus the
+structural migration sync in `sync-prisma-plugins.mjs`):
+
+- **Migrations are copied, never symlinked.** Prisma enumerates the
+  migrations folder with `lstat`, so a symlinked migration reports
+  `isDirectory() === false` and is silently skipped — a green deploy that
+  changed no schema.
+- **The partial is copied too**, and the owning package must be a **declared
+  dependency** of whichever host package owns the schema folder: `turbo prune`
+  copies only what the dependency graph reaches, and an undeclared owner is
+  dropped from the build context.
+- Never edit the synced copy by hand; re-run the sync. The `--check` variant
+  is the CI gate against drift.
+- **The migration's timestamp (`20260727190000`) may sort before migrations
+  your host has already applied.** That is deliberate: the directory is a
+  byte-identical copy of the one future-pay already has in production, so a
+  rename would make that host's sync try to create a second table. For every
+  other host the out-of-order arrival is safe — `prisma migrate dev` may
+  grumble, but the SQL is `CREATE TABLE IF NOT EXISTS`, so even a double
+  apply is inert.
+
+## Porting to another repo
+
+1. Add the package and sync the partial + migration into your schema-owning
+   package (adjust the two paths in your copy of the sync script); declare
+   `@12-apps/jobs` as that package's dependency; `prisma generate`.
+2. Declare your jobs with `defineJob` and collect the modules behind one
+   import (`lib/jobs/index.ts` importing each for its side effect).
+3. Mount: `createApiJobs({ jobs: () => import("./lib/jobs"), db: () => yourClient })`,
+   `await jobsApi.start()` at process start, `app.route(prefix, jobsRouter(jobsApi))`.
+4. Deploy shape: the worker is the SAME image with `JOBS_WORKER=1`. Redis
+   needs `maxmemory-policy noeviction` (the driver checks and complains) and
+   AOF persistence. More than one worker is safe for sweeps that take the
+   lease.

package/README.md

@@ -1,9 +1,12 @@
 # @12-apps/jobs
 
 Typed background jobs — retries, exponential backoff and cron — behind a
-swappable driver. BullMQ/Redis in production, inline execution in tests.
+swappable driver. BullMQ/Redis in production, inline execution in tests and
+zero-config development.
 
-Framework-free: no Prisma, no Next, no host-app types. The logger is a port.
+Framework-free: no Prisma import, no Next, no host-app types. The logger is a
+port, the lease's database is a structural seam, and the one web framework in
+sight (`hono`) is an optional peer behind its own subpath.
 
 ```ts
 // where the domain lives — the import IS the registration
@@ -24,12 +27,30 @@ defineJob({
 // at an emit site
 await dispatchNotification.enqueue({ notificationId }, { dedupeKey: notificationId });
 
-// at process start
-import { createBullMqJobDriver } from "@12-apps/jobs/bullmq";  // not the barrel
-configureJobs({ driver: createBullMqJobDriver({ redisUrl, logger }), logger });
-await startJobWorkers();   // consumers only
+// at process start — ONE call wires driver, workers, drain, lease and health
+import { createApiJobs } from "@12-apps/jobs/server";
+import { jobsRouter } from "@12-apps/jobs/hono";
+
+const jobsApi = createApiJobs({
+  jobs: () => import("./lib/jobs"),   // the defineJob modules
+  db: () => getPrismaClient(),        // the sweep_leases table (optional)
+});
+await jobsApi.start();
+app.route("/api/internal/jobs", jobsRouter(jobsApi));
 ```
 
+With no `REDIS_URL` and no config, `start()` resolves 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. Production with no
+Redis resolves to NO driver plus a loud error and a 503 from `/health` —
+never a crash, never a silent fake. `JOBS_WORKER=1` is what turns a process
+from producer (enqueue only) into consumer (workers + schedules); the worker
+is the same image, not a second build.
+
+The full adoption contract — config seam, env variables, the sweep lease, the
+Prisma partial and why there is no `createWebJobs` — is in
+[ADOPTING.md](./ADOPTING.md).
+
 ## The two rules
 
 **Payloads carry identifiers, never state.** `{ notificationId }`, not the
@@ -55,6 +76,36 @@ constraints, not on the queue.
 
 The BullMQ driver is exported from `@12-apps/jobs/bullmq`, never the barrel, so
 importing `defineJob` at an emit site does not drag Redis into the bundle.
+`createApiJobs` keeps the same property: it imports the BullMQ driver lazily,
+only in a process whose resolution actually picked it.
 
 Redis must run with `maxmemory-policy noeviction` — the driver checks and
-complains. See [docs/JOBS.md](../../docs/JOBS.md) for the deployment side.
+complains.
+
+## The sweep lease
+
+Scheduled sweeps declare `queue: SWEEP_QUEUE, concurrency: 1`, which makes
+them single-flight within one worker. Across replicas that guarantee needs a
+named, time-bounded claim in the DATABASE — `createSweepLease` (or the bound
+`withSweepLease` on the `createApiJobs` return):
+
+```ts
+defineJob({
+  name: "billing.tick",
+  queue: SWEEP_QUEUE,
+  concurrency: 1,
+  schedule: { pattern: "0 * * * *" },
+  handle: async () => {
+    const { ran } = await jobsApi.withSweepLease("billing.tick", 10 * 60_000, () =>
+      runBillingTick(),
+    );
+    if (!ran) return; // another worker holds this tick
+  },
+});
+```
+
+The claim is a conditional UPDATE — the database picks the winner — and only
+a lost race is silent; a missing table or a dead store THROWS, so a stopped
+sweep has a failed job to point at it. The `SweepLease` table ships with this
+package (`prisma/jobs.prisma` + `prisma/migrations/`) and is synced into the
+host's schema; partials and migrations are COPIED, never symlinked.

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@12-apps/jobs",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "type": "module",
-  "description": "Generic background-job library: a typed job registry with retries, exponential backoff and cron schedules, behind a swappable driver port (BullMQ/Redis in production, inline execution in tests). Framework-free; knows nothing about the host app's domain, ORM or transport.",
+  "description": "Generic background-job library: a typed job registry with retries, exponential backoff and cron schedules, behind a swappable driver port (BullMQ/Redis in production, inline execution in tests and zero-config dev). The runtime half (./server) is one factory — createApiJobs: driver resolution, worker bootstrap, graceful drain, the single-writer sweep lease and a health endpoint — with a Hono adapter (./hono) and the package-owned SweepLease Prisma partial + migrations. Knows nothing about the host app's domain, ORM or transport.",
   "exports": {
     ".": "./src/index.ts",
+    "./server": "./src/server/index.ts",
+    "./hono": "./src/hono/index.ts",
     "./bullmq": "./src/drivers/bullmq.ts",
-    "./inline": "./src/drivers/inline.ts"
+    "./inline": "./src/drivers/inline.ts",
+    "./package.json": "./package.json"
   },
   "scripts": {
     "clean": "rm -rf node_modules coverage",
@@ -20,10 +23,11 @@
     "bullmq": "^5.81.2"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.19.0",
-    "@12-apps/typescript-config": "^1.19.0",
+    "@12-apps/eslint-config": "^1.20.0",
+    "@12-apps/typescript-config": "^1.20.0",
     "eslint": "^9.39.1",
     "eslint-plugin-test-flakiness": "^1.4.0",
+    "hono": "^4.6.0",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"
   },
@@ -31,6 +35,14 @@
     "node": ">=22.0.0"
   },
   "license": "MIT",
+  "peerDependencies": {
+    "hono": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "hono": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"

package/prisma/jobs.prisma

@@ -0,0 +1,48 @@
+// ---------------------------------------------------------------------------
+// @12-apps/jobs — CANONICAL Prisma model partial (plug-and-play).
+//
+// This file is the single source of truth for the sweep-lease table. A host
+// project does NOT copy this model into its main schema by hand: it uses
+// Prisma's multi-file schema folder and SYNCS this file into it (see
+// packages/shared-helpers/scripts/sync-jobs-schema.mjs in this repo for the
+// reference sync step — run before `prisma generate`). The migration ships
+// alongside, in prisma/migrations/, and is COPIED into the host's migrations
+// folder — never symlinked, because Prisma enumerates that folder with lstat
+// and silently skips a linked directory.
+//
+// Host-agnostic by design: the lease names a JOB, not a tenant or a user, so
+// there is no relation to any host table at all.
+// ---------------------------------------------------------------------------
+
+/// Named, time-bounded claims on the scheduled sweeps.
+///
+/// Within one worker the sweeps are single-flight (their own queue at
+/// concurrency 1). Across two workers that guarantee evaporates: both read
+/// the same work list and do the same work twice. Correctness is expected to
+/// survive that (sweeps are idempotent by durable markers in the host's own
+/// tables), but the effort and the user-visible notices double.
+///
+/// A lease row rather than `pg_advisory_lock`, deliberately. A session-level
+/// advisory lock has to be released on the SAME connection that took it, and
+/// Prisma pools connections with no such guarantee — a release that lands on
+/// another connection silently fails and strands the lock, after which that
+/// sweep never runs again until the connection recycles. The transaction-
+/// scoped variant releases correctly but only holds for the transaction, and
+/// sweeps make external HTTP calls that have no business inside one.
+///
+/// `expiresAt` is what makes a dead holder recoverable without anyone
+/// intervening: a worker that is OOM-killed mid-sweep leaves the row behind,
+/// and the next tick past the expiry simply takes it. The claim itself is a
+/// conditional UPDATE, so the database decides the winner — two workers
+/// racing cannot both see it as free.
+model SweepLease {
+  /// The job name, e.g. "billing.tick". One lease per sweep.
+  name       String   @id
+  /// Which worker run holds it — release only ever matches its own holder.
+  holder     String
+  acquiredAt DateTime @default(now()) @map("acquired_at")
+  /// Past this instant the lease is free, whether or not it was released.
+  expiresAt  DateTime @map("expires_at")
+
+  @@map("sweep_leases")
+}

package/prisma/migrations/20260727190000_sweep_leases/migration.sql

@@ -0,0 +1,13 @@
+-- Named, time-bounded claims on the scheduled sweeps (FUT-343).
+--
+-- One row per sweep. The claim is a conditional UPDATE on `expires_at`, so the
+-- database picks the winner between racing workers; `expires_at` also makes a
+-- crashed holder recoverable with no operator action.
+CREATE TABLE IF NOT EXISTS "sweep_leases" (
+    "name"        TEXT NOT NULL,
+    "holder"      TEXT NOT NULL,
+    "acquired_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "expires_at"  TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "sweep_leases_pkey" PRIMARY KEY ("name")
+);

package/src/core/queues.ts

@@ -0,0 +1,26 @@
+/**
+ * Well-known queue names.
+ *
+ * The scheduled sweeps run SINGLE-FLIGHT: their own queue at concurrency 1,
+ * so a tick that outlives its interval makes the next one WAIT rather than run
+ * alongside it.
+ *
+ * That is a correctness property, not tuning. Every sweep walks a work list
+ * and decides "has this already been handled?" by reading a row it is about
+ * to write; two ticks interleaved on the same row both read the old answer.
+ * Durable markers in the host's tables make that safe rather than corrupting
+ * — the worst case is duplicate work, and the ledger is protected by the
+ * database — but single-flight is what keeps it from happening at all, and it
+ * costs nothing: sweeps run hourly and daily, and none of them is
+ * latency-sensitive.
+ *
+ * Keeping them off the DEFAULT queue matters too, in the other direction: a
+ * sweep grinding through a few hundred tenants must not occupy the workers
+ * that handle a user-facing job.
+ *
+ * Declare a sweep with `queue: SWEEP_QUEUE, concurrency: 1` and take a
+ * {@link ../lease/sweep-lease!createSweepLease | sweep lease} inside the
+ * handler when more than one worker can run — the queue serializes ticks
+ * within one worker, the lease serializes them across the deployment.
+ */
+export const SWEEP_QUEUE = "sweeps";

package/src/hono/index.ts

@@ -0,0 +1,44 @@
+import { Hono } from "hono";
+
+import type { JobsRoute } from "../server/create-api-jobs";
+
+/**
+ * `@12-apps/jobs/hono` — the jobs endpoints as a mountable router.
+ *
+ * The framework-neutral descriptors in `/server` are the contract; this is
+ * the adapter for the framework we happen to use. It lives behind its own
+ * subpath with `hono` as an OPTIONAL peer, so a host on Express — or one that
+ * mounts the descriptors itself — never resolves Hono at all. Importing the
+ * package root or `/server` does not reach this file.
+ *
+ * A host writes:
+ *
+ *     const jobsApi = createApiJobs({ jobs: () => import("./jobs") });
+ *     await jobsApi.start();
+ *     app.route("/api/internal/jobs", jobsRouter(jobsApi));
+ *
+ * It takes the API INSTANCE rather than the config, deliberately: the host
+ * must call `start()` on the same instance whose routes report health, and a
+ * router that built its own would answer for a runtime nobody started.
+ *
+ * Auth stays the host's: mount this under whatever guard the deployment's
+ * internal probes live behind (future-pay's `/api/internal/*` is answered
+ * only machine-to-machine; the reverse proxy 404s it from the internet).
+ */
+export function jobsRouter(api: { routes: JobsRoute[] }): Hono {
+  const app = new Hono();
+  for (const route of api.routes) {
+    // Every route today is a GET; a future method would extend this dispatch,
+    // and forgetting to would fail the mount loudly rather than 404 quietly.
+    if (route.method !== "GET") {
+      throw new Error(`jobsRouter cannot mount a ${String(route.method)} route.`);
+    }
+    app.get(route.path, async (c) => {
+      const response = await route.handle();
+      // The status travels with the body the handler chose; this adapter
+      // never reinterprets either.
+      return c.json(response.body as Record<string, unknown>, response.status as 200);
+    });
+  }
+  return app;
+}

package/src/index.ts

@@ -24,6 +24,17 @@
  * The BullMQ driver is deliberately NOT re-exported here — it is imported
  * from `@12-apps/jobs/bullmq`, so that pulling in `defineJob` at an emit site
  * never drags Redis into a bundle that only ever enqueues.
+ *
+ * The OPERATIONAL half — driver resolution with the inline zero-config
+ * default, the worker switch, graceful drain and the health endpoint — is
+ * `createApiJobs` in `@12-apps/jobs/server` (mount it with
+ * `@12-apps/jobs/hono` or your own adapter). What this root adds to it:
+ *
+ *   - `SWEEP_QUEUE` — the single-flight queue the scheduled sweeps share.
+ *   - `createSweepLease` — the named, time-bounded claim that keeps a sweep
+ *     to ONE pass per tick across a multi-worker deployment. Its `SweepLease`
+ *     table ships in `prisma/jobs.prisma` with its migration; the host syncs
+ *     both (see ADOPTING.md).
  */
 
 export { defineJob, findJob, listJobs, clearJobs, DuplicateJobError } from "./core/registry";
@@ -58,3 +69,16 @@ export type { InlineJobDriver, InlineJobRun } from "./drivers/inline";
 
 export { parseRedisUrl, InvalidRedisUrlError } from "./drivers/redis-url";
 export type { RedisConnectionOptions } from "./drivers/redis-url";
+
+export { SWEEP_QUEUE } from "./core/queues";
+
+export { createSweepLease } from "./lease/sweep-lease";
+export type {
+  SweepLease,
+  SweepLeaseConfig,
+  SweepLeaseDb,
+  SweepLeaseDbProvider,
+  SweepLeaseDelegate,
+  SweepLeaseOutcome,
+  WithSweepLease,
+} from "./lease/sweep-lease";