@softure-ai/jobs 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+Newest first. Each version lists what changed for an app that uses `@softure-ai/jobs`. When an app has run a version in
+production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
+"Definition of done").
+
+## 0.1.1
+
+- Recurring schedules (#491): `jobs({ schedules: { "<queue>": { every: "1h", payload } } })`. Workers enqueue each
+  period's run once, however many run (a conditional upsert of the new table `jobs.schedules`, migration
+  `0002_create_schedules.sql`, in the same transaction as the job); missed periods collapse into one run; while a run
+  is still live the next period joins it. A schedule's queue takes the default queue settings unless `queues` names
+  it, and `queues` may be left out when schedules define them. `runDueJobs` enqueues due runs first;
+  `enqueueDueSchedules` serves apps that drain from a cron. `getQueueStats` reports each queue's `schedule`
+  (`everySeconds`, `lastEnqueuedAt`, `lastSucceededAt`, `isLate`). auth, mcp-access, waitlist, security and analytics
+  ship their prune handlers and schedules in their `./jobs` entries.
+
+## 0.1.0
+
+- First version (#471): background jobs in Postgres (`jobs.jobs`). `jobs({ queues })` in `softure.config.ts`;
+  `enqueueJob` inside the caller's transaction with an optional `dedupKey`; `cancelJob`, `retryJob`, `getJob`,
+  `getQueueStats`, `pruneJobs`; handlers with a zod payload schema (`defineJobHandler`, `failJob`, `retryJobLater`);
+  `runJobWorker` and `runJobWorkerProcess` (`@softure-ai/jobs/worker`): claim with `FOR UPDATE SKIP LOCKED` under a
+  lease, a heartbeat for long jobs, fenced completion, retry with exponential backoff and jitter, a terminal `failed`
+  state, pruning, and release of unfinished jobs on SIGTERM; `runDueJobs` (`@softure-ai/jobs/testing`) runs due jobs
+  in-process for tests and cron-driven apps.
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOFTURE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,290 @@
-# Temporary Holding Version
+# @softure-ai/jobs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Background jobs in Postgres: an app enqueues work in the same transaction as its own write, and a worker process
+runs it with leases, retries and a terminal failure state. Built for the case an adopting app solved by hand (a job
+table of its own and a `scripts/worker.ts` loop): a slow or unreliable call after a request, such as an AI call per
+received message.
+
+## 1. What it provides
+
+A job queue in one table (`jobs.jobs`) with enqueue inside the caller's transaction and dedup keys, claims with
+`FOR UPDATE SKIP LOCKED` under a lease, fenced completion, retry with exponential backoff, a worker process with
+graceful shutdown, recurring schedules that run once per period however many workers run, and an in-process runner
+for tests and cron-driven apps.
+
+## 2. Installation
+
+```bash
+npm install @softure-ai/jobs @softure-ai/core @softure-ai/db drizzle-orm zod
+```
+
+The worker runs as its own process. With `@softure-ai/deploy`, `softure-deploy init` sees `@softure-ai/jobs` in
+`package.json` and adds `scripts/worker.ts`, its bundle in the image and a `worker` service next to the app (deploy
+README, "Job worker").
+
+## 3. Configuration
+
+```ts
+import { defineSoftureConfig } from "@softure-ai/core";
+import { jobs } from "@softure-ai/jobs";
+
+export default defineSoftureConfig({
+  // database, locale, timezone, appOrigin …
+  modules: [
+    jobs({
+      queues: {
+        "ai.reply": { maxAttempts: 5, backoff: { baseSeconds: 10, maxSeconds: 600 }, leaseSeconds: 120, concurrency: 4 },
+        "mail.digest": {},
+      },
+    }),
+  ],
+});
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `queues.<name>.maxAttempts` | `5` | attempts before a job is `failed`; the first run counts |
+| `queues.<name>.backoff` | `{ baseSeconds: 10, maxSeconds: 3600 }` | delay after attempt n is `min(max, base * 2^(n-1))`, shortened by up to 20 % at random |
+| `queues.<name>.leaseSeconds` | `300` | how long a claimed job is reserved; the worker extends it while the handler runs, so it bounds how long a crashed worker's job waits, not how long a handler may take |
+| `queues.<name>.concurrency` | `1` | jobs of the queue one worker process runs at once |
+| `schedules.<queue>.every` | (required) | how often the schedule runs: `<n>m`, `<n>h` or `<n>d`, from `1m` to `7d` (§3, "Schedules") |
+| `schedules.<queue>.payload` | `{}` | the payload of every scheduled run |
+| `pollIntervalMs` | `1000` | how often an idle worker looks for due jobs |
+| `shutdownGraceMs` | `20000` | how long a stopping worker waits for running handlers before releasing their jobs |
+| `retention` | `{ succeededDays: 7, failedDays: 30, cancelledDays: 7 }` | how long finished jobs are kept; the worker prunes once an hour |
+
+A queue name is lowercase letters, digits, `_`, `.` and `-`. A queue the config does not define is refused by
+`enqueueJob` and by the worker: a typo is a bug, not a new queue. A schedule defines its queue too, with the default
+settings unless `queues` names it; the config needs at least one queue or schedule.
+
+### Handlers
+
+One handler per queue, with the zod schema of its payload. The payload read back from the table is parsed with it
+before the handler runs; a payload that does not match fails the job with `jobs.invalid_payload` and is not retried.
+
+```ts
+// src/jobs/handlers.ts
+import { ok } from "@softure-ai/core";
+import { defineJobHandler, failJob, retryJobLater, type JobHandlers } from "@softure-ai/jobs";
+import { z } from "zod";
+
+export const handlers: JobHandlers = {
+  "ai.reply": defineJobHandler({
+    payload: z.object({ messageId: z.string() }),
+    run: async ({ messageId }, { db, signal, job }) => {
+      const message = await findMessage(db, messageId);
+      if (message === null) return failJob("app.message_gone"); // failed at once, no retry
+      const reply = await callModel(message, { signal });
+      if (reply.status === 429) return retryJobLater("app.rate_limited", reply.retryAfterSeconds);
+      if (!reply.ok) return reply; // an Err: retried with the queue's backoff
+      await saveReply(db, messageId, reply.value);
+      return ok();
+    },
+  }),
+};
+```
+
+- `ok()`: done, the job is `succeeded`.
+- An `Err` (any `Result` failure): retried after the backoff delay, until `maxAttempts`; then `failed`.
+- `failJob(code)`: `failed` at once.
+- `retryJobLater(code, seconds)`: retried after `seconds` instead of the backoff (a provider's `Retry-After`); still
+  counts as an attempt.
+- A throw: retried like an `Err` with the code `jobs.handler_threw`, and logged with the error.
+
+**Handlers run at least once.** A worker can die after the side effect and before recording it, a lease can end, a
+stopping worker releases unfinished jobs: the job then runs again. Make handlers idempotent (check whether the reply
+was already saved, pass an idempotency key to the provider).
+
+`context.signal` aborts when the job is taken from the handler: the worker's grace period ended on shutdown, or its
+lease could not be extended. Pass it to `fetch` and other cancellable calls; anything the handler returns afterwards
+is not recorded. `context.db` is the worker's pool, not a transaction; `context.job.attempts` is this attempt's number.
+
+### Enqueueing
+
+```ts
+import { enqueueJob } from "@softure-ai/jobs/server";
+
+await db.transaction(async (tx) => {
+  const [message] = await tx.insert(messages).values(input).returning();
+  await enqueueJob({ db: tx, clock, config }, { queue: "ai.reply", payload: { messageId: message.id }, dedupKey: message.id });
+});
+```
+
+| Field | Meaning |
+| --- | --- |
+| `queue` | a configured queue |
+| `payload` | JSON for the handler, `{}` when there is none; stored as `jsonb`, so a `Date` comes back as a string. Ids, not personal data |
+| `runAt` / `delaySeconds` | when the job is due; default now; one or the other |
+| `dedupKey` | while a pending or running job of the queue has this key, the call returns that job (`isDuplicate: true`) instead of writing a second one; a finished job frees the key |
+| `maxAttempts` | this job's own limit instead of the queue's |
+
+Inside the caller's transaction the job exists exactly when the caller's change commits; a rolled-back transaction
+leaves no job behind.
+
+### Running the worker
+
+```ts
+// scripts/worker.ts
+import { runJobWorkerProcess } from "@softure-ai/jobs/worker";
+import config from "../softure.config";
+import { handlers } from "../src/jobs/handlers";
+
+await runJobWorkerProcess({ config, handlers });
+```
+
+`runJobWorkerProcess` opens its own pool (`database.url`, or the app's `database.handle`) with one connection per job
+that can run at once plus one, runs the worker until SIGTERM or SIGINT, closes the pool and sets `process.exitCode`
+(0 after a clean stop, 1 when it could not start). Pass `logger: createLogger("jobs")` from
+`@softure-ai/observability` to send its lines to OpenTelemetry; by default they go to the console. `queues: [...]`
+runs only some queues (one worker per queue group).
+
+The worker claims due jobs of every queue it has a handler for, up to each queue's `concurrency`, oldest due first.
+A claim counts as an attempt and takes a lease, which a heartbeat extends while the handler runs. A worker that dies
+leaves its jobs `running` until their lease ends; the next claim then takes them over (or fails them with
+`jobs.lease_expired` when no attempt is left). Every write after a claim is fenced by a claim token, so the worker
+whose lease was taken over cannot record an outcome over the newer attempt. Several workers can run side by side:
+`SKIP LOCKED` hands each job to one of them.
+
+On SIGTERM the worker stops claiming, waits up to `shutdownGraceMs` for running handlers, then aborts the rest and
+releases their jobs (pending again, due now, the attempt given back). Database errors while claiming or recording are
+logged and retried on the next round; a database restart does not end the worker.
+
+`runJobWorker({ db, config, handlers, signal })` is the loop without the process part, for an app that runs it inside
+a process of its own.
+
+### Schedules
+
+A schedule runs its queue's handler once per period, instead of an app cron:
+
+```ts
+import { authJobSchedules } from "@softure-ai/auth/jobs";
+import { securityJobSchedules } from "@softure-ai/security/jobs";
+
+jobs({
+  schedules: {
+    ...authJobSchedules, // auth.prune-sessions hourly, auth.prune-password-resets daily
+    ...securityJobSchedules, // security.prune-rate-limits hourly
+    "app.digest": { every: "1d", payload: { kind: "weekly" } },
+  },
+});
+```
+
+```ts
+// src/jobs/handlers.ts: the packages' handlers next to the app's own
+import { authJobHandlers } from "@softure-ai/auth/jobs";
+import { securityJobHandlers } from "@softure-ai/security/jobs";
+
+export const handlers: JobHandlers = { ...authJobHandlers, ...securityJobHandlers, "app.digest": digestHandler };
+```
+
+- Periods start on whole multiples of `every` counted from 1970-01-01 00:00 UTC: `1h` on the full hour, `1d` at
+  midnight UTC, `15m` at :00, :15, :30, :45. A run is due at the start of its period.
+- Once per period, however many workers run: a worker takes a period with a conditional upsert of
+  `jobs.schedules` (the period must be later than the stored one) and enqueues the run in the same transaction, so a
+  missed or doubled tick cannot happen. A worker enqueues only the schedules of the queues it runs.
+- Missed periods (no worker ran) collapse into one run for the current period.
+- Every scheduled run has the dedup key `schedule`: while a run is still pending or running (retrying a failure), the
+  next period joins it instead of queueing a second run behind it.
+- Scheduled runs are ordinary jobs: retries, `maxAttempts`, `getJob`, `retryJob` and pruning apply.
+- A package's prune handlers live in its `./jobs` entry (`@softure-ai/auth/jobs`, `@softure-ai/mcp-access/jobs`,
+  `@softure-ai/waitlist/jobs`, `@softure-ai/security/jobs`, `@softure-ai/analytics/jobs`), with `@softure-ai/jobs` as an
+  optional peer.
+
+`getQueueStats` reports each scheduled queue's `schedule`: `everySeconds`, `lastEnqueuedAt` (the start of the latest
+period a run was enqueued for), `lastSucceededAt` (any succeeded job of the queue, a run enqueued by hand too) and
+`isLate`: no success within two periods, counted from when a worker first saw the schedule, or no worker has seen it
+at all. The module's health check does not fail on a late schedule (a late cleanup must not take the app out of
+rotation); an app that wants an alarm adds a check of its own:
+
+```ts
+ops({
+  checks: {
+    "app.schedules": async (context) => {
+      const late = (await getQueueStats(context as JobsContext)).filter((stats) => stats.schedule?.isLate === true);
+      return late.length === 0 ? ok() : err("app.schedules_late");
+    },
+  },
+});
+```
+
+### Without a worker
+
+`runDueJobs(ctx, { handlers })` (from `@softure-ai/jobs/server` or `/testing`) enqueues the due runs of the schedules
+among its queues, then runs every due job once, in this process, one after another, and returns
+`{ succeeded, retried, failed, stale }`. A cron can drain a queue with it; call `pruneJobs(ctx)` from the same cron.
+`enqueueDueSchedules(ctx, { queues? })` only enqueues the due scheduled runs.
+
+### Steering and overview
+
+From `@softure-ai/jobs/server`, each on `ctx = { db, clock, config }`:
+
+| Function | Result |
+| --- | --- |
+| `getJob(ctx, id)` | the `Job` or `null` |
+| `cancelJob(ctx, id)` | a pending job becomes `cancelled`; `jobs.not_cancellable` for a running or finished one, `jobs.not_found` |
+| `retryJob(ctx, id)` | a failed or cancelled job runs again from scratch (attempts 0, due now); `jobs.not_retryable`, `jobs.dedup_key_taken` while a live job has its key, `jobs.not_found` |
+| `getQueueStats(ctx)` | per queue: counts per status, the due backlog, the `run_at` of its oldest due job and its `schedule` (or `null`) |
+| `pruneJobs(ctx)` | deletes finished jobs past their retention; returns the count |
+
+`getQueueStats` suits an app health check of its own, `ops({ checks: { "app.jobs": … } })`, e.g. unavailable when the
+oldest due job of a queue waited more than ten minutes (no worker is running). An ops script (`@softure-ai/ops/scripts`)
+can wrap `retryJob` and `cancelJob` for the operator.
+
+## 4. Mounting
+
+Nothing to mount: the module has no routes or pages. The worker is a process (§3, "Running the worker").
+
+## 5. Migrations and tables
+
+Schema `jobs`, two tables, `migrations/0001_create_jobs.sql` and `migrations/0002_create_schedules.sql`:
+
+`jobs.jobs`: `id` (bigint identity; a string in the API), `queue`, `payload` (jsonb), `status` (`pending`, `running`,
+`succeeded`, `failed`, `cancelled`), `attempts`, `max_attempts`, `run_at`, `locked_until`, `locked_by` (the worker,
+`<hostname>:<pid>`), `claim_token`, `dedup_key`, `last_error` (an error code, never a message), `created_at`,
+`updated_at`, `finished_at`. Checks keep the lease columns set exactly while `running` and `finished_at` set exactly
+for finished jobs; a partial unique index allows one live job per queue and dedup key.
+
+`jobs.schedules`: `name` (the schedule's queue, primary key), `last_slot_at` (the start of the latest period a run
+was enqueued for), `last_succeeded_at`, `created_at`, `updated_at`. One row per schedule a worker has seen; a row of
+a schedule removed from the config stays and is ignored.
+
+The app role needs `SELECT, INSERT, UPDATE, DELETE` on the tables, which the `@softure-ai/ops` roles recipe grants on
+every schema the migrator creates.
+
+## 6. Environment variables
+
+None of its own. The worker reads the app's config, so it gets the app's `DATABASE_URL` and whatever its handlers need.
+
+## 7. Switches
+
+None.
+
+## 8. Appearance
+
+No UI.
+
+## 9. Copy
+
+`errors.*` in `src/messages/en.ts`, one key per error code (`invalid_payload`, `handler_threw`, `lease_expired`,
+`not_found`, `not_cancellable`, `not_retryable`, `dedup_key_taken`), for an admin screen that shows a job's state.
+
+## 10. Hooks
+
+The handlers (§3) are the app's code. `logger` (`info`, `warn`, `error`; `@softure-ai/observability`'s `Logger` fits)
+receives the worker's lines: started, stopped, a scheduled run enqueued, a thrown handler with its error, a lost lease,
+a release, pruning.
+
+## 11. GDPR
+
+No export or deletion contributor: jobs are transient and pruned (§3, `retention`). Keep personal data out of
+payloads (ids only); then a deleted account leaves nothing personal in `jobs.jobs`. `last_error` holds codes, and the
+logger gets payload paths, never values, for a payload that does not match its schema.
+
+## 12. Limitations
+
+- Polling, no `LISTEN/NOTIFY`: a job waits up to `pollIntervalMs` when the worker is idle.
+- Schedules take a fixed period (`every`), aligned to UTC; no cron expressions, no time zones, no "at 03:00".
+- No priorities within a queue and no rate limits per queue beyond `concurrency`; split work into queues instead.
+- At-least-once delivery (§3, "Handlers run at least once").
+- PGlite has one connection, so tests run claims one after another; concurrent claiming is Postgres behaviour
+  (`SKIP LOCKED`) and is not exercised in unit tests.

package/dist/contract.d.ts

@@ -0,0 +1,48 @@
+import type { Err, ErrorCode } from "@softure-ai/core";
+export type JobsErrorCode = "jobs.invalid_payload" | "jobs.handler_threw" | "jobs.lease_expired" | "jobs.not_found" | "jobs.not_cancellable" | "jobs.not_retryable" | "jobs.dedup_key_taken";
+export declare const JOB_STATUSES: readonly ["pending", "running", "succeeded", "failed", "cancelled"];
+export type JobStatus = (typeof JOB_STATUSES)[number];
+/** One job as the module's functions return it. */
+export interface Job {
+    readonly id: string;
+    readonly queue: string;
+    readonly payload: unknown;
+    readonly status: JobStatus;
+    /** Claims so far; the running attempt's number while `running`. */
+    readonly attempts: number;
+    readonly maxAttempts: number;
+    /** When a pending job is due. */
+    readonly runAt: Date;
+    readonly lockedUntil: Date | null;
+    readonly lockedBy: string | null;
+    readonly dedupKey: string | null;
+    /** The error code of the last failed attempt. */
+    readonly lastError: string | null;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+    readonly finishedAt: Date | null;
+}
+/**
+ * A handler's failure. Retried with the queue's backoff unless `retry` is false or the attempts are used up;
+ * `retryAfterSeconds` replaces the backoff delay for this attempt (a provider's `Retry-After`).
+ */
+export type JobFailure = Err<ErrorCode> & {
+    readonly retry?: boolean;
+    readonly retryAfterSeconds?: number;
+};
+/** What happened to a job after one attempt. */
+export type JobOutcome = {
+    readonly kind: "succeeded";
+} | {
+    readonly kind: "retried";
+    readonly error: string;
+    readonly runAt: Date;
+} | {
+    readonly kind: "failed";
+    readonly error: string;
+}
+/** The job was taken over (lease ended) or released before the attempt finished; nothing was recorded. */
+ | {
+    readonly kind: "stale";
+};
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,MAAM,aAAa,GACrB,sBAAsB,GACtB,oBAAoB,GACpB,oBAAoB,GACpB,gBAAgB,GAChB,sBAAsB,GACtB,oBAAoB,GACpB,sBAAsB,CAAC;AAE3B,eAAO,MAAM,YAAY,qEAAsE,CAAC;AAEhG,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD,mDAAmD;AACnD,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,gDAAgD;AAChD,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACrD,0GAA0G;GACxG;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC"}

package/dist/contract.js

@@ -0,0 +1,2 @@
+export const JOB_STATUSES = ["pending", "running", "succeeded", "failed", "cancelled"];
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAaA,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAU,CAAC"}

package/dist/handlers.d.ts

@@ -0,0 +1,60 @@
+import type { Clock, ErrorCode, Ok, SoftureConfig } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import type { z } from "zod";
+import type { Job, JobFailure } from "./contract.js";
+/** What a handler receives besides its payload. */
+export interface JobHandlerContext {
+    /** The worker's database: not a transaction; open one with `db.transaction` when the work needs it. */
+    readonly db: Queryable;
+    readonly clock: Clock;
+    readonly config: SoftureConfig;
+    /** The job as claimed: `attempts` is this attempt's number, starting at 1. */
+    readonly job: Job;
+    /**
+     * Aborted when the job is taken away from this handler: the worker stops and its grace period ended, or the lease
+     * could not be extended. Pass it to `fetch` and other cancellable calls; whatever the handler returns afterwards is
+     * not recorded.
+     */
+    readonly signal: AbortSignal;
+}
+/**
+ * What a handler returns: `ok()` when the work is done; an `Err` to try again with the queue's backoff (until the
+ * attempts are used up); `failJob(code)` to fail for good; `retryJobLater(code, seconds)` to try again after a delay
+ * the handler chooses. A throw is retried like an `Err` with the code `jobs.handler_threw` and logged.
+ */
+export type JobRunResult = Ok<unknown> | JobFailure;
+export interface JobHandler<TPayload = unknown> {
+    /** The schema of the payload; a payload that does not match fails the job with `jobs.invalid_payload`, untried. */
+    readonly payload: z.ZodType<TPayload>;
+    readonly run: (payload: TPayload, context: JobHandlerContext) => Promise<JobRunResult>;
+}
+/**
+ * A handler of any payload type, as a handler map holds it. `run` takes `never` so every `JobHandler<T>` fits; the
+ * runner passes it the payload its own schema parsed.
+ */
+export interface AnyJobHandler {
+    readonly payload: z.ZodType;
+    readonly run: (payload: never, context: JobHandlerContext) => Promise<JobRunResult>;
+}
+/** Handlers by queue name. Every queue a worker runs needs one; a handler for an unknown queue is refused. */
+export type JobHandlers = Readonly<Record<string, AnyJobHandler>>;
+/**
+ * Defines a handler with its payload type inferred from the schema:
+ *
+ *   export const replyHandler = defineJobHandler({
+ *     payload: z.object({ messageId: z.string() }),
+ *     run: async ({ messageId }, { db }) => { ...; return ok(); },
+ *   });
+ */
+export declare function defineJobHandler<TSchema extends z.ZodType>(handler: {
+    readonly payload: TSchema;
+    readonly run: (payload: z.output<TSchema>, context: JobHandlerContext) => Promise<JobRunResult>;
+}): JobHandler<z.output<TSchema>>;
+/** A failure that is not retried: the job is `failed` at once with this code. */
+export declare function failJob<E extends ErrorCode>(error: E): JobFailure;
+/**
+ * A failure retried after `seconds` instead of the queue's backoff (a provider's `Retry-After`). Still counts as an
+ * attempt: after the last one the job is `failed`.
+ */
+export declare function retryJobLater<E extends ErrorCode>(error: E, seconds: number): JobFailure;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAErD,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC,uGAAuG;IACvG,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC;AAEpD,MAAM,WAAW,UAAU,CAAC,QAAQ,GAAG,OAAO;IAC5C,mHAAmH;IACnH,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtC,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACxF;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACrF;AAED,8GAA8G;AAC9G,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;AAElE;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE;IACnE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACjG,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAKhC;AAED,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,GAAG,UAAU,CAEjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAKxF"}

package/dist/handlers.js

@@ -0,0 +1,29 @@
+/**
+ * Defines a handler with its payload type inferred from the schema:
+ *
+ *   export const replyHandler = defineJobHandler({
+ *     payload: z.object({ messageId: z.string() }),
+ *     run: async ({ messageId }, { db }) => { ...; return ok(); },
+ *   });
+ */
+export function defineJobHandler(handler) {
+    if (typeof handler.run !== "function") {
+        throw new Error("defineJobHandler: run must be a function");
+    }
+    return handler;
+}
+/** A failure that is not retried: the job is `failed` at once with this code. */
+export function failJob(error) {
+    return { ok: false, error, retry: false };
+}
+/**
+ * A failure retried after `seconds` instead of the queue's backoff (a provider's `Retry-After`). Still counts as an
+ * attempt: after the last one the job is `failed`.
+ */
+export function retryJobLater(error, seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0) {
+        throw new RangeError(`retryJobLater: seconds must be a finite number >= 0, got ${String(seconds)}`);
+    }
+    return { ok: false, error, retryAfterSeconds: seconds };
+}
+//# sourceMappingURL=handlers.js.map

package/dist/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"AAgDA;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAA4B,OAG3D;IACC,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,OAAwC,CAAC;AAClD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,OAAO,CAAsB,KAAQ;IACnD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAsB,KAAQ,EAAE,OAAe;IAC1E,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,UAAU,CAAC,4DAA4D,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACtG,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAC;AAC1D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+export declare const MODULE_ID = "jobs";
+/**
+ * Enables background jobs in `softure.config.ts`: `jobs({ queues: { "ai.reply": { maxAttempts: 5 } } })`. Jobs run
+ * in a worker process (`runJobWorkerProcess` from `@softure-ai/jobs/worker`).
+ */
+export declare const jobs: import("@softure-ai/core").ModuleFactory<{}, {
+    errors: {
+        invalid_payload: string;
+        handler_threw: string;
+        lease_expired: string;
+        not_found: string;
+        not_cancellable: string;
+        not_retryable: string;
+        dedup_key_taken: string;
+    };
+}, import("zod").ZodPipe<import("zod").ZodObject<{
+    queues: import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodObject<{
+        maxAttempts: import("zod").ZodDefault<import("zod").ZodNumber>;
+        backoff: import("zod").ZodDefault<import("zod").ZodObject<{
+            baseSeconds: import("zod").ZodDefault<import("zod").ZodNumber>;
+            maxSeconds: import("zod").ZodDefault<import("zod").ZodNumber>;
+        }, import("zod/v4/core").$strict>>;
+        leaseSeconds: import("zod").ZodDefault<import("zod").ZodNumber>;
+        concurrency: import("zod").ZodDefault<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strict>>>;
+    schedules: import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodObject<{
+        every: import("zod").ZodString;
+        payload: import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
+    }, import("zod/v4/core").$strict>>>;
+    pollIntervalMs: import("zod").ZodDefault<import("zod").ZodNumber>;
+    shutdownGraceMs: import("zod").ZodDefault<import("zod").ZodNumber>;
+    retention: import("zod").ZodDefault<import("zod").ZodObject<{
+        succeededDays: import("zod").ZodDefault<import("zod").ZodNumber>;
+        failedDays: import("zod").ZodDefault<import("zod").ZodNumber>;
+        cancelledDays: import("zod").ZodDefault<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strict>>;
+}, import("zod/v4/core").$strict>, import("zod").ZodTransform<{
+    queues: {
+        [x: string]: {
+            maxAttempts: number;
+            backoff: {
+                baseSeconds: number;
+                maxSeconds: number;
+            };
+            leaseSeconds: number;
+            concurrency: number;
+        };
+    };
+    schedules: Record<string, {
+        every: string;
+        payload: Record<string, unknown>;
+    }>;
+    pollIntervalMs: number;
+    shutdownGraceMs: number;
+    retention: {
+        succeededDays: number;
+        failedDays: number;
+        cancelledDays: number;
+    };
+}, {
+    queues: Record<string, {
+        maxAttempts: number;
+        backoff: {
+            baseSeconds: number;
+            maxSeconds: number;
+        };
+        leaseSeconds: number;
+        concurrency: number;
+    }>;
+    schedules: Record<string, {
+        every: string;
+        payload: Record<string, unknown>;
+    }>;
+    pollIntervalMs: number;
+    shutdownGraceMs: number;
+    retention: {
+        succeededDays: number;
+        failedDays: number;
+        cancelledDays: number;
+    };
+}>>>;
+export { JOB_STATUSES, type Job, type JobFailure, type JobOutcome, type JobsErrorCode, type JobStatus, } from "./contract.js";
+export { jobsMessages, type JobsMessages } from "./messages/index.js";
+export { jobsOptionsSchema, type JobQueueOptions, type JobScheduleOptions, type JobSchedulesInput, type JobsOptions, type JobsOptionsInput, } from "./options.js";
+export { defineJobHandler, failJob, retryJobLater, type JobHandler, type JobHandlerContext, type JobHandlers } from "./handlers.js";
+export { jobs as jobsTable, schedules as jobSchedulesTable } from "./schema.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,SAAS,SAAS,CAAC;AAEhC;;;GAGG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAiBf,CAAC;AAEH,OAAO,EACL,YAAY,EACZ,KAAK,GAAG,EACR,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,SAAS,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,EACL,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACpI,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,SAAS,IAAI,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,36 @@
+// Public API of @softure-ai/jobs: the module factory for softure.config.ts, the handler helpers and the types.
+// Database work is in `@softure-ai/jobs/server`, the worker in `@softure-ai/jobs/worker`, the in-process runner for
+// tests in `@softure-ai/jobs/testing`.
+import { defineModule, resolveMigrationsDir } from "@softure-ai/core";
+import { jobsMessages } from "./messages/index.js";
+import { jobsOptionsSchema } from "./options.js";
+import { checkJobsTable } from "./server/health.js";
+export const MODULE_ID = "jobs";
+/**
+ * Enables background jobs in `softure.config.ts`: `jobs({ queues: { "ai.reply": { maxAttempts: 5 } } })`. Jobs run
+ * in a worker process (`runJobWorkerProcess` from `@softure-ai/jobs/worker`).
+ */
+export const jobs = defineModule({
+    manifest: {
+        id: MODULE_ID,
+        version: "0.1.1",
+        dependsOn: {},
+        dbSchema: "jobs",
+        tables: ["jobs", "schedules"],
+        env: [],
+        switches: [],
+        routes: {},
+        mount: [],
+        privacy: { exports: false, deletes: false },
+    },
+    messages: jobsMessages,
+    options: jobsOptionsSchema,
+    migrations: { dir: resolveMigrationsDir(import.meta.url, "../migrations/") },
+    health: checkJobsTable,
+});
+export { JOB_STATUSES, } from "./contract.js";
+export { jobsMessages } from "./messages/index.js";
+export { jobsOptionsSchema, } from "./options.js";
+export { defineJobHandler, failJob, retryJobLater } from "./handlers.js";
+export { jobs as jobsTable, schedules as jobSchedulesTable } from "./schema.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+GAA+G;AAC/G,oHAAoH;AACpH,uCAAuC;AACvC,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC;AAEhC;;;GAGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,YAAY,CAAC;IAC/B,QAAQ,EAAE;QACR,EAAE,EAAE,SAAS;QACb,OAAO,EAAE,OAAO;QAChB,SAAS,EAAE,EAAE;QACb,QAAQ,EAAE,MAAM;QAChB,MAAM,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC;QAC7B,GAAG,EAAE,EAAE;QACP,QAAQ,EAAE,EAAE;QACZ,MAAM,EAAE,EAAE;QACV,KAAK,EAAE,EAAE;QACT,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE;KAC5C;IACD,QAAQ,EAAE,YAAY;IACtB,OAAO,EAAE,iBAAiB;IAC1B,UAAU,EAAE,EAAE,GAAG,EAAE,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,EAAE;IAC5E,MAAM,EAAE,cAAc;CACvB,CAAC,CAAC;AAEH,OAAO,EACL,YAAY,GAMb,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAqB,MAAM,qBAAqB,CAAC;AACtE,OAAO,EACL,iBAAiB,GAMlB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,EAA6D,MAAM,eAAe,CAAC;AACpI,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,SAAS,IAAI,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/messages/en.d.ts

@@ -0,0 +1,12 @@
+export declare const en: {
+    errors: {
+        invalid_payload: string;
+        handler_threw: string;
+        lease_expired: string;
+        not_found: string;
+        not_cancellable: string;
+        not_retryable: string;
+        dedup_key_taken: string;
+    };
+};
+//# sourceMappingURL=en.d.ts.map