@maroonedsoftware/jobbroker 1.8.2 → 1.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +179 -35
- package/dist/{chunk-GKXLBFUJ.js → chunk-VCGAI6CK.js} +23 -4
- package/dist/chunk-VCGAI6CK.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -1
- package/dist/index.js.map +1 -1
- package/dist/job.monitor.d.ts +157 -0
- package/dist/job.monitor.d.ts.map +1 -0
- package/dist/job.queue.policy.d.ts +72 -0
- package/dist/job.queue.policy.d.ts.map +1 -0
- package/dist/pgboss/kysely.transaction.connection.provider.d.ts +56 -0
- package/dist/pgboss/kysely.transaction.connection.provider.d.ts.map +1 -0
- package/dist/pgboss/pgboss.job.monitor.d.ts +82 -0
- package/dist/pgboss/pgboss.job.monitor.d.ts.map +1 -0
- package/dist/pgboss/pgboss.job.registration.d.ts +39 -8
- package/dist/pgboss/pgboss.job.registration.d.ts.map +1 -1
- package/dist/pgboss/pgboss.job.runner.d.ts +58 -3
- package/dist/pgboss/pgboss.job.runner.d.ts.map +1 -1
- package/dist/pgboss.d.ts +2 -0
- package/dist/pgboss.d.ts.map +1 -1
- package/dist/pgboss.js +272 -17
- package/dist/pgboss.js.map +1 -1
- package/package.json +2 -1
- package/dist/chunk-GKXLBFUJ.js.map +0 -1
package/README.md
CHANGED
|
@@ -9,6 +9,8 @@ A flexible background job processing library with support for scheduled and on-d
|
|
|
9
9
|
- **Scheduled jobs** using cron expressions
|
|
10
10
|
- **On-demand jobs** for immediate execution
|
|
11
11
|
- **Cancellation** of queued _and_ running jobs, plus state lookup, delete, and resume
|
|
12
|
+
- **Per-queue retry & dead-letter policy** for retry limits, backoff, and poison-message capture
|
|
13
|
+
- **Dead-letter monitoring** to inspect, redrive, retry, or discard failed jobs
|
|
12
14
|
- **PostgreSQL backing** for reliability and transactional guarantees
|
|
13
15
|
|
|
14
16
|
## Installation
|
|
@@ -21,10 +23,10 @@ pnpm add @maroonedsoftware/jobbroker injectkit pg-boss reflect-metadata
|
|
|
21
23
|
|
|
22
24
|
`pg-boss` is an optional peer dependency. The pg-boss backend lives behind a subpath export so importing the core (`@maroonedsoftware/jobbroker`) never loads it:
|
|
23
25
|
|
|
24
|
-
| Import | Contents
|
|
25
|
-
| ------------------------------------ |
|
|
26
|
-
| `@maroonedsoftware/jobbroker` | `Job`, `JobBroker`, `JobRunner`, `JobInfo`, `JobState`, `NotSupportedError`
|
|
27
|
-
| `@maroonedsoftware/jobbroker/pgboss` | `PgBossJobBroker`, `PgBossJobRunner`, `PgBossJobRegistryMap`, `PgBossConnectionProvider` | `pg-boss` |
|
|
26
|
+
| Import | Contents | Pulls in |
|
|
27
|
+
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
|
|
28
|
+
| `@maroonedsoftware/jobbroker` | `Job`, `JobBroker`, `JobRunner`, `JobMonitor`, `JobInfo`, `JobState`, `JobQueuePolicy`, `NotSupportedError` | nothing extra |
|
|
29
|
+
| `@maroonedsoftware/jobbroker/pgboss` | `PgBossJobBroker`, `PgBossJobRunner`, `PgBossJobMonitor`, `PgBossJobRegistryMap`, `PgBossConnectionProvider`, `KyselyTransactionConnectionProvider` | `pg-boss` |
|
|
28
30
|
|
|
29
31
|
## Quick Start
|
|
30
32
|
|
|
@@ -74,6 +76,17 @@ registry.set('daily-report', {
|
|
|
74
76
|
job: DailyReportJob,
|
|
75
77
|
cron: '0 9 * * *', // Every day at 9 AM
|
|
76
78
|
});
|
|
79
|
+
|
|
80
|
+
// On-demand job with a retry / dead-letter policy (see "Retry & dead-letter policy")
|
|
81
|
+
registry.set('deliver-webhook', {
|
|
82
|
+
job: DeliverWebhookJob,
|
|
83
|
+
policy: {
|
|
84
|
+
retryLimit: 5,
|
|
85
|
+
retryDelay: Duration.fromObject({ seconds: 30 }),
|
|
86
|
+
retryBackoff: true,
|
|
87
|
+
deadLetter: 'deliver-webhook-dead',
|
|
88
|
+
},
|
|
89
|
+
});
|
|
77
90
|
```
|
|
78
91
|
|
|
79
92
|
### 3. Set Up the Broker and Runner
|
|
@@ -83,8 +96,14 @@ import 'reflect-metadata';
|
|
|
83
96
|
import { PgBoss } from 'pg-boss';
|
|
84
97
|
import { InjectKitRegistry } from 'injectkit';
|
|
85
98
|
import { ConsoleLogger, Logger } from '@maroonedsoftware/logger';
|
|
86
|
-
import { JobBroker, JobRunner } from '@maroonedsoftware/jobbroker';
|
|
87
|
-
import {
|
|
99
|
+
import { JobBroker, JobRunner, JobMonitor } from '@maroonedsoftware/jobbroker';
|
|
100
|
+
import {
|
|
101
|
+
PgBossJobBroker,
|
|
102
|
+
PgBossJobRunner,
|
|
103
|
+
PgBossJobMonitor,
|
|
104
|
+
PgBossJobRegistryMap,
|
|
105
|
+
PgBossConnectionProvider,
|
|
106
|
+
} from '@maroonedsoftware/jobbroker/pgboss';
|
|
88
107
|
|
|
89
108
|
// Initialize pg-boss
|
|
90
109
|
const pgboss = new PgBoss('postgres://user:pass@localhost/mydb');
|
|
@@ -98,6 +117,7 @@ diRegistry.register(Logger).useClass(ConsoleLogger).asSingleton();
|
|
|
98
117
|
diRegistry.register(PgBossConnectionProvider).useClass(PgBossConnectionProvider).asSingleton();
|
|
99
118
|
diRegistry.register(JobBroker).useClass(PgBossJobBroker).asSingleton();
|
|
100
119
|
diRegistry.register(JobRunner).useClass(PgBossJobRunner).asSingleton();
|
|
120
|
+
diRegistry.register(JobMonitor).useClass(PgBossJobMonitor).asSingleton();
|
|
101
121
|
|
|
102
122
|
// Build the container
|
|
103
123
|
const container = diRegistry.build();
|
|
@@ -160,11 +180,85 @@ runner.cancelPollIntervalSeconds = 2; // default 5; set to 0 to disable polling
|
|
|
160
180
|
|
|
161
181
|
Lower values reduce cancellation latency at the cost of one extra lookup query per running job per interval.
|
|
162
182
|
|
|
183
|
+
## Retry & dead-letter policy
|
|
184
|
+
|
|
185
|
+
By default a job that keeps failing is retried a couple of times and then marked `failed` — where it stays, with nothing draining it. For money-critical or webhook work you usually want an explicit retry budget, backoff between attempts, and a **dead-letter queue (DLQ)** so a job that exhausts its retries is preserved for inspection or replay instead of being dropped.
|
|
186
|
+
|
|
187
|
+
Declare a `JobQueuePolicy` on the registration, right where the job is mapped. Every field is optional, and durations are Luxon `Duration`s (mapped to whole seconds for pg-boss):
|
|
188
|
+
|
|
189
|
+
```typescript
|
|
190
|
+
import { Duration } from 'luxon';
|
|
191
|
+
|
|
192
|
+
registry.set('deliver-webhook', {
|
|
193
|
+
job: DeliverWebhookJob,
|
|
194
|
+
policy: {
|
|
195
|
+
retryLimit: 5, // attempts before the job is failed / dead-lettered
|
|
196
|
+
retryDelay: Duration.fromObject({ seconds: 30 }), // base delay between attempts
|
|
197
|
+
retryBackoff: true, // grow the delay exponentially (with jitter) from retryDelay
|
|
198
|
+
retryDelayMax: Duration.fromObject({ minutes: 10 }), // cap for the backoff curve
|
|
199
|
+
expiresIn: Duration.fromObject({ minutes: 2 }), // a run is considered stuck after this
|
|
200
|
+
deadLetter: 'deliver-webhook-dead', // where exhausted jobs land
|
|
201
|
+
},
|
|
202
|
+
});
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
The policy is applied to the queue when `runner.start()` runs: an absent queue is **created** with these options, and an existing queue is **updated** to match, so changing a policy and restarting reconciles it. When a registration declares no policy, its queue is created exactly as before — this feature is fully backward-compatible.
|
|
206
|
+
|
|
207
|
+
**Dead-letter queues are auto-created.** If `deadLetter` names a queue that does not yet exist, the runner creates it (as a plain queue) before the source queue that references it, so you don't have to register a placeholder. A DLQ you actually want to _drain_ is just another registered job whose name matches — give it its own handler (and, if you like, its own policy). A DLQ you only want to inspect can be left unregistered; jobs simply accumulate there for manual review or redrive.
|
|
208
|
+
|
|
209
|
+
To apply the same defaults to **every** queue without repeating them, set `defaultQueuePolicy` on the runner. Each queue's own policy is layered on top, so a field a queue sets wins over the default:
|
|
210
|
+
|
|
211
|
+
```typescript
|
|
212
|
+
const runner = container.get(JobRunner) as PgBossJobRunner;
|
|
213
|
+
runner.defaultQueuePolicy = {
|
|
214
|
+
retryLimit: 3,
|
|
215
|
+
retryBackoff: true,
|
|
216
|
+
retryDelay: Duration.fromObject({ seconds: 10 }),
|
|
217
|
+
};
|
|
218
|
+
await runner.start();
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Retry and dead-letter behavior is a **queue-level** concern here, not a per-`send` one: it is declared once where the job is registered rather than on each `broker.send(...)`. This matches how the mainstream backends model it (pg-boss `retryLimit`/`deadLetter`, SQS's redrive policy, Cloud Tasks' `maxAttempts`), none of which support per-message retry overrides — so `JobQueuePolicy` stays portable across backends.
|
|
222
|
+
|
|
223
|
+
## Monitoring & draining dead-letter queues
|
|
224
|
+
|
|
225
|
+
Capturing a poison message is only half the job: a consumer needs to see what landed in a dead-letter queue and act on it. `JobMonitor` is the operator-side companion to `JobBroker` (produce) and `JobRunner` (consume) — it reads queue depth, lists the stuck jobs, and remediates them. Unlike the broker, it operates on **any queue name and does not require the queue to be registered**, because a dead-letter queue is often an unregistered sink with no worker of its own.
|
|
226
|
+
|
|
227
|
+
```typescript
|
|
228
|
+
const monitor = container.get(JobMonitor);
|
|
229
|
+
|
|
230
|
+
// Observe — poll depth/health (e.g. from a reconciliation cron) to alert on a growing DLQ
|
|
231
|
+
const stats = await monitor.getQueueStats('deliver-webhook-dead');
|
|
232
|
+
// stats: { name, queued, active, failed, total } | null (null when the queue does not exist)
|
|
233
|
+
|
|
234
|
+
if (stats && stats.total > 0) {
|
|
235
|
+
// Retrieve — inspect the poison messages (id, state, original payload)
|
|
236
|
+
const stuck = await monitor.listJobs<WebhookPayload>('deliver-webhook-dead');
|
|
237
|
+
logger.warn(`${stuck.length} webhooks in the dead-letter queue`, { ids: stuck.map(j => j.id) });
|
|
238
|
+
|
|
239
|
+
// Act — move them back to their original source queue to reprocess, oldest first, rate-limited
|
|
240
|
+
const moved = await monitor.redrive('deliver-webhook-dead', { limit: 100 });
|
|
241
|
+
|
|
242
|
+
// ...or discard a specific unrecoverable message
|
|
243
|
+
await monitor.deleteJob('deliver-webhook-dead', stuck[0].id);
|
|
244
|
+
}
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
| Method | Description |
|
|
248
|
+
| ----------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
249
|
+
| `getQueueStats(name)` | Point-in-time `{ name, queued, active, failed, total }`, or `null` if the queue does not exist. |
|
|
250
|
+
| `listJobs<P>(name, options?)` | List retained jobs as `JobInfo<P>[]`; filter by `id`, partial `data`, or `queuedOnly`. |
|
|
251
|
+
| `redrive(name, options?)` | Move dead-lettered jobs back to their source (or a `destination`), oldest first; returns count. |
|
|
252
|
+
| `deleteJob(name, id)` | Permanently discard one or more jobs (no registry check, so DLQ sinks are serviceable). |
|
|
253
|
+
| `retryJob(name, id)` | Re-attempt failed jobs **in place**; for a DLQ sink prefer `redrive`, which moves them to a worker. |
|
|
254
|
+
|
|
255
|
+
`redrive` returns each job to the queue it was dead-lettered from by default, so a worker can process it again. Pass `destination` to funnel everything into one queue, `sourceName` to drain just one source's jobs from a shared DLQ, and `limit` to move in controlled batches. All operations source their pg-boss `db` executor from `PgBossConnectionProvider`, so a remediation can run inside a transaction when you override the provider (see [Transactional enqueue](#transactional-enqueue)).
|
|
256
|
+
|
|
163
257
|
### Backend portability
|
|
164
258
|
|
|
165
259
|
`cancel`, `resume`, `deleteJob`, and `getJob` are best-effort by contract: a backend that cannot honor an operation throws `NotSupportedError` rather than silently doing nothing. `JobState` (`created | retry | active | completed | cancelled | failed`) is the normalized, lowest-common-denominator lifecycle; alternative backends map their native states to the nearest value. The bundled pg-boss backend supports every operation.
|
|
166
260
|
|
|
167
|
-
`send`'s `startAfter` is deliberately expressed as
|
|
261
|
+
`send`'s `startAfter` is deliberately expressed as _intent_ (a relative `Duration` or an absolute `DateTime`), not a wire format, so it maps cleanly onto each backend's native deferral mechanism — pg-boss `startAfter` (unbounded), SQS `DelaySeconds` (max 15 minutes), Cloud Tasks `scheduleTime` (up to 30 days). A backend that cannot honor a requested delay (e.g. an SQS backend asked for a 1-hour delay) throws `NotSupportedError` rather than clamping silently.
|
|
168
262
|
|
|
169
263
|
## API Reference
|
|
170
264
|
|
|
@@ -180,15 +274,15 @@ Abstract base class for job handlers.
|
|
|
180
274
|
|
|
181
275
|
Abstract base class for sending, cancelling, and inspecting jobs. Operations a backend cannot honor throw `NotSupportedError`.
|
|
182
276
|
|
|
183
|
-
| Method
|
|
184
|
-
|
|
|
277
|
+
| Method | Description |
|
|
278
|
+
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
|
|
185
279
|
| `send<P>(name: string, payload: P, options?: JobSendOptions): Promise<string>` | Queue a job; resolves with the new job id. Pass `options.startAfter` (a Luxon `Duration` or `DateTime`) to defer it |
|
|
186
|
-
| `schedule<P>(name: string, cron: string, payload?: P): Promise<void>`
|
|
187
|
-
| `unschedule(name: string): Promise<void>`
|
|
188
|
-
| `cancel(name: string, id: string \| string[]): Promise<void>`
|
|
189
|
-
| `resume(name: string, id: string \| string[]): Promise<void>`
|
|
190
|
-
| `deleteJob(name: string, id: string \| string[]): Promise<void>`
|
|
191
|
-
| `getJob<P>(name: string, id: string): Promise<JobInfo<P> \| null>`
|
|
280
|
+
| `schedule<P>(name: string, cron: string, payload?: P): Promise<void>` | Create a recurring job schedule |
|
|
281
|
+
| `unschedule(name: string): Promise<void>` | Remove a recurring job schedule |
|
|
282
|
+
| `cancel(name: string, id: string \| string[]): Promise<void>` | Request cancellation of queued or running jobs (cooperative) |
|
|
283
|
+
| `resume(name: string, id: string \| string[]): Promise<void>` | Re-queue previously cancelled jobs |
|
|
284
|
+
| `deleteJob(name: string, id: string \| string[]): Promise<void>` | Permanently delete jobs |
|
|
285
|
+
| `getJob<P>(name: string, id: string): Promise<JobInfo<P> \| null>` | Look up a job's current state, or `null` if it does not exist |
|
|
192
286
|
|
|
193
287
|
### `JobInfo<Payload>` / `JobState`
|
|
194
288
|
|
|
@@ -203,6 +297,20 @@ Abstract base class for processing jobs from the queue.
|
|
|
203
297
|
| `start(): Promise<void>` | Start processing jobs |
|
|
204
298
|
| `stop(): Promise<void>` | Gracefully stop processing |
|
|
205
299
|
|
|
300
|
+
### `JobMonitor`
|
|
301
|
+
|
|
302
|
+
Abstract base class for observing queues and remediating dead-letter queues. Operates on raw queue names (no registry check). Operations a backend cannot honor throw `NotSupportedError`. See [Monitoring & draining dead-letter queues](#monitoring--draining-dead-letter-queues).
|
|
303
|
+
|
|
304
|
+
| Method | Description |
|
|
305
|
+
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
306
|
+
| `getQueueStats(name: string): Promise<JobQueueStats \| null>` | Queue depth/health counts, or `null` if the queue does not exist |
|
|
307
|
+
| `listJobs<P>(name: string, options?: JobQueryOptions): Promise<JobInfo<P>[]>` | List retained jobs, optionally filtered by `id`, `data`, or `queuedOnly` |
|
|
308
|
+
| `redrive(name: string, options?: JobRedriveOptions): Promise<number>` | Move dead-lettered jobs back to source (or a `destination`); returns count moved |
|
|
309
|
+
| `deleteJob(name: string, id: string \| string[]): Promise<void>` | Permanently discard jobs |
|
|
310
|
+
| `retryJob(name: string, id: string \| string[]): Promise<void>` | Re-attempt failed jobs in place |
|
|
311
|
+
|
|
312
|
+
`JobQueueStats` is `{ name, queued, active, failed, total }`. `JobQueryOptions` is `{ id?, data?, queuedOnly? }`. `JobRedriveOptions` is `{ destination?, sourceName?, limit? }`.
|
|
313
|
+
|
|
206
314
|
### `PgBossJobRegistryMap`
|
|
207
315
|
|
|
208
316
|
A `Map<string, Identifier<Job> | PgBossJobRegistration>` for registering jobs.
|
|
@@ -210,16 +318,30 @@ A `Map<string, Identifier<Job> | PgBossJobRegistration>` for registering jobs.
|
|
|
210
318
|
Entries can be either:
|
|
211
319
|
|
|
212
320
|
- A job class identifier (for on-demand jobs)
|
|
213
|
-
- A `PgBossJobRegistration` object
|
|
321
|
+
- A `PgBossJobRegistration` object (for scheduled jobs, jobs with a queue policy, or both)
|
|
214
322
|
|
|
215
323
|
### `PgBossJobRegistration`
|
|
216
324
|
|
|
217
|
-
Configuration object for a scheduled job.
|
|
325
|
+
Configuration object for a job. Only `job` is required, so it covers on-demand jobs (`{ job }`), scheduled jobs (`{ job, cron }`), and either with a retry/dead-letter policy attached.
|
|
326
|
+
|
|
327
|
+
| Property | Type | Description |
|
|
328
|
+
| -------- | ----------------- | -------------------------------------------------------------------- |
|
|
329
|
+
| `job` | `Identifier<Job>` | The job class identifier to instantiate when the job runs. |
|
|
330
|
+
| `cron` | `string` | Optional cron expression defining when the job should run. |
|
|
331
|
+
| `policy` | `JobQueuePolicy` | Optional per-queue retry and dead-letter policy for the job's queue. |
|
|
332
|
+
|
|
333
|
+
### `JobQueuePolicy`
|
|
334
|
+
|
|
335
|
+
Backend-agnostic per-queue retry and dead-letter policy (see [Retry & dead-letter policy](#retry--dead-letter-policy)). Every field is optional; durations are Luxon `Duration`s.
|
|
218
336
|
|
|
219
|
-
| Property
|
|
220
|
-
|
|
|
221
|
-
| `
|
|
222
|
-
| `
|
|
337
|
+
| Property | Type | Description |
|
|
338
|
+
| --------------- | ---------- | ------------------------------------------------------------------------------------ |
|
|
339
|
+
| `retryLimit` | `number` | Attempts before a job is failed (and dead-lettered, if `deadLetter` is set). |
|
|
340
|
+
| `retryDelay` | `Duration` | Delay before retrying; the base of the curve when `retryBackoff` is on. |
|
|
341
|
+
| `retryBackoff` | `boolean` | Grow the retry delay exponentially (with jitter) from `retryDelay` instead of fixed. |
|
|
342
|
+
| `retryDelayMax` | `Duration` | Upper bound on the backoff delay. Only used when `retryBackoff` is on. |
|
|
343
|
+
| `expiresIn` | `Duration` | How long a run may take before it is considered stuck and made eligible for retry. |
|
|
344
|
+
| `deadLetter` | `string` | Name of the dead-letter queue that receives jobs which exhaust their retries. |
|
|
223
345
|
|
|
224
346
|
### `PgBossJobBroker`
|
|
225
347
|
|
|
@@ -235,27 +357,26 @@ Supplies the pg-boss `db` executor used when enqueuing or scheduling jobs.
|
|
|
235
357
|
|
|
236
358
|
The default implementation returns `undefined`, so pg-boss uses its own connection pool (standard, non-transactional behavior). Override it on a request-scoped DI container to return a transaction-bound executor and enqueue jobs atomically with the surrounding database transaction — see [Transactional enqueue](#transactional-enqueue).
|
|
237
359
|
|
|
238
|
-
|
|
360
|
+
### `KyselyTransactionConnectionProvider`
|
|
239
361
|
|
|
240
|
-
|
|
362
|
+
`PgBossConnectionProvider` bound to an active Kysely transaction. Constructor signature: `new KyselyTransactionConnectionProvider(trx: KyselyLike)`. Register it as a request-scoped override of `PgBossConnectionProvider` and every enqueue performed during the request inserts on the transaction's connection, so the job row and the surrounding writes commit or roll back together.
|
|
241
363
|
|
|
242
|
-
|
|
243
|
-
import { fromKysely } from 'pg-boss';
|
|
244
|
-
import { PgBossConnectionProvider } from '@maroonedsoftware/jobbroker/pgboss';
|
|
364
|
+
The constructor takes `KyselyLike`, a structural type satisfied by both `Kysely<DB>` and `Transaction<DB>` with no type argument or cast. Declaring it structurally means the package has no dependency on `kysely`, not even an optional peer.
|
|
245
365
|
|
|
246
|
-
|
|
247
|
-
constructor(private readonly trx: Transaction<DB>) {
|
|
248
|
-
super();
|
|
249
|
-
}
|
|
366
|
+
Plugins are stripped (`withoutPlugins()`) before the transaction is adapted: pg-boss runs raw SQL straight through `executeQuery`, so a column-rewriting plugin on the caller's instance would corrupt pg-boss's own result columns. The stripped instance shares the same connection-bound executor, so atomicity is preserved.
|
|
250
367
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
368
|
+
## Transactional enqueue
|
|
369
|
+
|
|
370
|
+
By default a job row is inserted on pg-boss's own connection, so it commits independently of any database work happening in the same request. To make an enqueue commit (or roll back) together with your business writes, override `PgBossConnectionProvider` in the request scope so its `executor()` returns the active transaction's connection.
|
|
371
|
+
|
|
372
|
+
For Kysely, `KyselyTransactionConnectionProvider` does this for you:
|
|
373
|
+
|
|
374
|
+
```typescript
|
|
375
|
+
import { PgBossConnectionProvider, KyselyTransactionConnectionProvider } from '@maroonedsoftware/jobbroker/pgboss';
|
|
255
376
|
|
|
256
377
|
// Inside a transaction, bind the provider on the scoped container before resolving the broker:
|
|
257
378
|
await repository.withTransaction(async trx => {
|
|
258
|
-
scopedContainer.override(PgBossConnectionProvider, new
|
|
379
|
+
scopedContainer.override(PgBossConnectionProvider, new KyselyTransactionConnectionProvider(trx));
|
|
259
380
|
|
|
260
381
|
await doBusinessWrites(trx);
|
|
261
382
|
await scopedContainer.get(JobBroker).send('send-email', { to: 'user@example.com' });
|
|
@@ -263,12 +384,35 @@ await repository.withTransaction(async trx => {
|
|
|
263
384
|
});
|
|
264
385
|
```
|
|
265
386
|
|
|
387
|
+
For the other query builders, pg-boss ships adapters (`fromKnex`, `fromDrizzle`, `fromPrisma`) that wrap a transaction into the executor shape pg-boss expects. Subclass the provider yourself:
|
|
388
|
+
|
|
389
|
+
```typescript
|
|
390
|
+
import { fromKnex } from 'pg-boss';
|
|
391
|
+
import { PgBossConnectionProvider } from '@maroonedsoftware/jobbroker/pgboss';
|
|
392
|
+
|
|
393
|
+
class KnexTransactionConnectionProvider extends PgBossConnectionProvider {
|
|
394
|
+
constructor(private readonly trx: Knex.Transaction) {
|
|
395
|
+
super();
|
|
396
|
+
}
|
|
397
|
+
|
|
398
|
+
override executor() {
|
|
399
|
+
return fromKnex(this.trx);
|
|
400
|
+
}
|
|
401
|
+
}
|
|
402
|
+
```
|
|
403
|
+
|
|
266
404
|
### `PgBossJobRunner`
|
|
267
405
|
|
|
268
406
|
Concrete `JobRunner` implementation backed by pg-boss. Constructor signature: `new PgBossJobRunner(container: Container, registrations: PgBossJobRegistryMap, pgboss: PgBoss, logger: Logger)`. Calls `pgboss.start()` during `start()` and `pgboss.stop()` during `stop()`. Job instances are resolved from the DI container on each invocation. Typically resolved through the DI container rather than instantiated directly.
|
|
269
407
|
|
|
270
408
|
Exposes a `cancelPollIntervalSeconds` property (default `5`) that controls how often a running job is polled for cancellation; set it to `0` to disable polling. See [Cancelling jobs](#cancelling-jobs).
|
|
271
409
|
|
|
410
|
+
Also exposes an optional `defaultQueuePolicy` (a `JobQueuePolicy`) applied beneath every queue's own policy, so all queues can share retry/dead-letter defaults without repeating them. See [Retry & dead-letter policy](#retry--dead-letter-policy).
|
|
411
|
+
|
|
412
|
+
### `PgBossJobMonitor`
|
|
413
|
+
|
|
414
|
+
Concrete `JobMonitor` implementation backed by pg-boss. Constructor signature: `new PgBossJobMonitor(pgboss: PgBoss, connectionProvider: PgBossConnectionProvider)`. Reads and remediates queues via pg-boss's `getQueue`, `findJobs`, `redrive`, `deleteJob`, and `retry`, sourcing the `db` executor from the injected `PgBossConnectionProvider` (so remediation can be transactional). Does not consult the job registry, so it works on unregistered dead-letter sinks. Typically resolved through the DI container rather than instantiated directly.
|
|
415
|
+
|
|
272
416
|
## Graceful Shutdown
|
|
273
417
|
|
|
274
418
|
Ensure you stop the runner during application shutdown:
|
|
@@ -19,7 +19,7 @@ JobBroker = _ts_decorate([
|
|
|
19
19
|
Injectable()
|
|
20
20
|
], JobBroker);
|
|
21
21
|
|
|
22
|
-
// src/job.
|
|
22
|
+
// src/job.monitor.ts
|
|
23
23
|
import { Injectable as Injectable2 } from "injectkit";
|
|
24
24
|
function _ts_decorate2(decorators, target, key, desc) {
|
|
25
25
|
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
@@ -28,18 +28,37 @@ function _ts_decorate2(decorators, target, key, desc) {
|
|
|
28
28
|
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
29
29
|
}
|
|
30
30
|
__name(_ts_decorate2, "_ts_decorate");
|
|
31
|
+
var JobMonitor = class {
|
|
32
|
+
static {
|
|
33
|
+
__name(this, "JobMonitor");
|
|
34
|
+
}
|
|
35
|
+
};
|
|
36
|
+
JobMonitor = _ts_decorate2([
|
|
37
|
+
Injectable2()
|
|
38
|
+
], JobMonitor);
|
|
39
|
+
|
|
40
|
+
// src/job.runner.ts
|
|
41
|
+
import { Injectable as Injectable3 } from "injectkit";
|
|
42
|
+
function _ts_decorate3(decorators, target, key, desc) {
|
|
43
|
+
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
44
|
+
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
45
|
+
else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
|
|
46
|
+
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
47
|
+
}
|
|
48
|
+
__name(_ts_decorate3, "_ts_decorate");
|
|
31
49
|
var JobRunner = class {
|
|
32
50
|
static {
|
|
33
51
|
__name(this, "JobRunner");
|
|
34
52
|
}
|
|
35
53
|
};
|
|
36
|
-
JobRunner =
|
|
37
|
-
|
|
54
|
+
JobRunner = _ts_decorate3([
|
|
55
|
+
Injectable3()
|
|
38
56
|
], JobRunner);
|
|
39
57
|
|
|
40
58
|
export {
|
|
41
59
|
__name,
|
|
42
60
|
JobBroker,
|
|
61
|
+
JobMonitor,
|
|
43
62
|
JobRunner
|
|
44
63
|
};
|
|
45
|
-
//# sourceMappingURL=chunk-
|
|
64
|
+
//# sourceMappingURL=chunk-VCGAI6CK.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/job.broker.ts","../src/job.monitor.ts","../src/job.runner.ts"],"sourcesContent":["import { Injectable } from 'injectkit';\nimport { JobInfo } from './job.info.js';\nimport { JobSendOptions } from './job.send.options.js';\n\n/**\n * Abstract base class for job broker implementations.\n *\n * A job broker is responsible for sending jobs to a queue, cancelling and\n * inspecting jobs, and managing scheduled jobs. It provides the producer-side\n * interface for the job processing system.\n *\n * Backends differ in what they can do. Operations a backend cannot honor throw\n * a `NotSupportedError` rather than silently doing nothing. The bundled pg-boss\n * backend supports every operation.\n *\n * @example\n * ```typescript\n * // Sending a job immediately (returns the job id)\n * const id = await jobBroker.send('send-email', {\n * to: 'user@example.com',\n * subject: 'Welcome!',\n * body: 'Thanks for signing up.'\n * });\n *\n * // Deferring a job: run it no earlier than five minutes from now\n * await jobBroker.send('send-email', payload, {\n * startAfter: Duration.fromObject({ minutes: 5 })\n * });\n *\n * // Deferring to an absolute time\n * await jobBroker.send('send-email', payload, {\n * startAfter: DateTime.now().plus({ hours: 2 })\n * });\n *\n * // Cancelling it later, whether it is still queued or already running\n * await jobBroker.cancel('send-email', id);\n *\n * // Scheduling a recurring job with cron\n * await jobBroker.schedule('daily-report', '0 9 * * *', {\n * reportType: 'sales'\n * });\n *\n * // Removing a scheduled job\n * await jobBroker.unschedule('daily-report');\n * ```\n */\n@Injectable()\nexport abstract class JobBroker {\n /**\n * Sends a job to the queue.\n *\n * By default the job is eligible for immediate processing and will be picked\n * up by a worker as soon as one is available. Pass {@link JobSendOptions.startAfter}\n * to defer it: the job becomes eligible only once the given delay has elapsed\n * (a {@link Duration}) or the given moment has passed (a {@link DateTime}).\n * Deferral is a lower bound, not a guarantee of exact-time execution — the job\n * runs at the first opportunity after it becomes eligible.\n *\n * @typeParam Payload - The type of the job payload. Must be an object.\n * @param name - The unique name identifying the job type.\n * Must match a registered job handler.\n * @param payload - The data to pass to the job handler.\n * @param options - Optional enqueue options, e.g. `startAfter` to defer the job.\n * @returns A promise that resolves with the id of the queued job. The id can\n * be passed to {@link cancel}, {@link resume}, {@link deleteJob}, or\n * {@link getJob}.\n * @throws If the job name is not registered.\n * @throws `NotSupportedError` if `options.startAfter` requests a deferral the\n * backend cannot honor (e.g. a delay beyond the backend's maximum).\n */\n abstract send<Payload extends object>(name: string, payload: Payload, options?: JobSendOptions): Promise<string>;\n\n /**\n * Schedules a recurring job using a cron expression.\n *\n * The job will be automatically enqueued according to the cron schedule.\n * If a schedule already exists for this job name, it will be updated.\n *\n * @typeParam Payload - The type of the job payload. Must be an object.\n * @param name - The unique name identifying the job type.\n * Must match a registered job handler.\n * @param cron - A cron expression defining the schedule (e.g., '0 9 * * *' for daily at 9am).\n * @param payload - Optional data to pass to the job handler on each execution.\n * @returns A promise that resolves when the schedule has been created.\n * @throws If the job name is not registered.\n */\n abstract schedule<Payload extends object>(name: string, cron: string, payload?: Payload): Promise<void>;\n\n /**\n * Removes a scheduled job.\n *\n * Stops the recurring execution of the specified job.\n * Does not affect jobs that are already queued.\n *\n * @param name - The unique name of the scheduled job to remove.\n * @returns A promise that resolves when the schedule has been removed.\n * @throws If the job name is not registered.\n */\n abstract unschedule(name: string): Promise<void>;\n\n /**\n * Requests cancellation of one or more jobs.\n *\n * Cancellation is best-effort and applies regardless of the job's state: a\n * job that is still queued is prevented from running, and a job that is\n * already running is asked to stop. For a running job, cancellation is\n * cooperative — the job's handler receives an aborted `AbortSignal` (see\n * {@link Job.run}) and must honor it. A handler that ignores the signal runs\n * to completion. Some backends may forcefully terminate the running compute\n * instead; this contract only guarantees the request is delivered.\n *\n * @param name - The name of the registered job type.\n * @param id - A single job id, or an array of ids, to cancel.\n * @returns A promise that resolves once the cancellation has been requested.\n * @throws If the job name is not registered.\n * @throws `NotSupportedError` if the backend cannot cancel jobs.\n */\n abstract cancel(name: string, id: string | string[]): Promise<void>;\n\n /**\n * Resumes one or more previously cancelled jobs, re-queuing them for processing.\n *\n * Only jobs in the `cancelled` state can be resumed; other states are\n * unaffected.\n *\n * @param name - The name of the registered job type.\n * @param id - A single job id, or an array of ids, to resume.\n * @returns A promise that resolves once the jobs have been re-queued.\n * @throws If the job name is not registered.\n * @throws `NotSupportedError` if the backend cannot resume jobs.\n */\n abstract resume(name: string, id: string | string[]): Promise<void>;\n\n /**\n * Permanently deletes one or more jobs.\n *\n * Removes the job records entirely. Unlike {@link cancel}, a deleted job\n * leaves no `cancelled` record behind and cannot be resumed.\n *\n * @param name - The name of the registered job type.\n * @param id - A single job id, or an array of ids, to delete.\n * @returns A promise that resolves once the jobs have been deleted.\n * @throws If the job name is not registered.\n * @throws `NotSupportedError` if the backend cannot delete jobs.\n */\n abstract deleteJob(name: string, id: string | string[]): Promise<void>;\n\n /**\n * Looks up the current state of a single job.\n *\n * @typeParam Payload - The type of the job payload.\n * @param name - The name of the registered job type.\n * @param id - The id of the job to look up.\n * @returns A promise that resolves with the {@link JobInfo} for the job, or\n * `null` if no job with that id exists.\n * @throws If the job name is not registered.\n * @throws `NotSupportedError` if the backend cannot report per-job state.\n */\n abstract getJob<Payload extends object>(name: string, id: string): Promise<JobInfo<Payload> | null>;\n}\n","import { Injectable } from 'injectkit';\nimport { JobInfo } from './job.info.js';\n\n/**\n * A backend-agnostic snapshot of a single queue's depth and health, as returned\n * by {@link JobMonitor.getQueueStats}. Every count is a point-in-time reading;\n * poll it on a schedule (for example from a reconciliation job) to drive\n * alerting on a backlog or a growing dead-letter queue.\n *\n * The counts are the lowest common denominator every supported backend can\n * report. `failed` in particular is a *retained* count: it reflects failures\n * still held in the queue subject to the queue's retention policy, not an\n * all-time total.\n */\nexport interface JobQueueStats {\n /** The queue name these stats describe. */\n name: string;\n /** Jobs waiting to be processed (enqueued but not yet active). */\n queued: number;\n /** Jobs currently being executed by a worker. */\n active: number;\n /** Failed jobs still retained in the queue (bounded by the retention policy). */\n failed: number;\n /** All jobs still retained for the queue across every state. */\n total: number;\n}\n\n/**\n * Filters for {@link JobMonitor.listJobs}. All fields are optional; omitting them\n * lists every job currently retained in the queue (the common case when\n * inspecting a small dead-letter queue).\n */\nexport interface JobQueryOptions {\n /** Match a single job by its id. */\n id?: string;\n /** Match jobs whose payload contains these fields (a partial-match filter). */\n data?: Record<string, unknown>;\n /** Restrict the result to jobs still waiting to be processed. */\n queuedOnly?: boolean;\n}\n\n/**\n * Options for {@link JobMonitor.redrive}, which moves dead-lettered jobs out of a\n * queue and back into circulation.\n */\nexport interface JobRedriveOptions {\n /**\n * The queue to move jobs into. When omitted, each job returns to the queue it\n * originally came from before it was dead-lettered — the usual \"reprocess\"\n * behavior. Supply this to funnel everything into a specific queue instead.\n */\n destination?: string;\n /**\n * Only redrive jobs that originated from this source queue. Useful when a\n * single dead-letter queue collects failures from several source queues and\n * you want to drain just one source's worth.\n */\n sourceName?: string;\n /**\n * Maximum number of jobs to move in this call, oldest first. Call repeatedly\n * (or on a schedule) to drain a large dead-letter queue at a controlled rate.\n */\n limit?: number;\n}\n\n/**\n * Read-and-remediate interface for job queues, and in particular for\n * *dead-letter queues*: the queues that collect jobs which have exhausted their\n * retries (see the queue policy on the pg-boss backend's registration).\n *\n * Where {@link JobBroker} is the producer side (enqueue, cancel, inspect a job\n * you hold the id for) and {@link JobRunner} is the consumer side, `JobMonitor`\n * is the operator side: it lets a consumer answer \"how deep is this queue?\",\n * \"what is stuck in this dead-letter queue?\", and \"reprocess / discard those\n * jobs\". Unlike the broker, it operates on raw queue names and does **not**\n * require the queue to be registered, because a dead-letter queue is often an\n * unregistered sink with no worker of its own.\n *\n * Backends that cannot honor an operation throw a `NotSupportedError` rather than\n * silently doing nothing, matching the rest of the package. The bundled pg-boss\n * backend supports every operation.\n *\n * @example\n * ```typescript\n * // A reconciliation sweep over a money-critical dead-letter queue.\n * const stats = await monitor.getQueueStats('charge.webhook.dead');\n * if (stats && stats.total > 0) {\n * const stuck = await monitor.listJobs('charge.webhook.dead'); // inspect / log / alert\n * const moved = await monitor.redrive('charge.webhook.dead', { limit: 100 }); // drain back\n * }\n * ```\n */\n@Injectable()\nexport abstract class JobMonitor {\n /**\n * Reports the current depth and health of a queue.\n *\n * @param name - The queue name to inspect (may be an unregistered dead-letter queue).\n * @returns A promise resolving to the {@link JobQueueStats}, or `null` if no\n * queue with that name exists.\n * @throws `NotSupportedError` if the backend cannot report queue statistics.\n */\n abstract getQueueStats(name: string): Promise<JobQueueStats | null>;\n\n /**\n * Lists the jobs currently retained in a queue, optionally filtered.\n *\n * The primary use is inspecting a dead-letter queue: the returned\n * {@link JobInfo} objects expose each poison message's id, state, and original\n * payload so a consumer can decide whether to reprocess ({@link redrive}),\n * discard ({@link deleteJob}), or escalate it.\n *\n * @typeParam Payload - The type of the job payloads.\n * @param name - The queue name to list (may be an unregistered dead-letter queue).\n * @param options - Optional {@link JobQueryOptions} filters.\n * @returns A promise resolving to the matching jobs (empty if none / no such queue).\n * @throws `NotSupportedError` if the backend cannot enumerate jobs.\n */\n abstract listJobs<Payload extends object>(name: string, options?: JobQueryOptions): Promise<JobInfo<Payload>[]>;\n\n /**\n * Moves dead-lettered jobs out of a queue and back into circulation, returning\n * the number of jobs moved.\n *\n * By default each job goes back to the source queue it was dead-lettered from,\n * so a worker can process it again; pass {@link JobRedriveOptions.destination}\n * to route them elsewhere, {@link JobRedriveOptions.sourceName} to drain only\n * one source's jobs from a shared dead-letter queue, and\n * {@link JobRedriveOptions.limit} to move at a controlled rate.\n *\n * @param name - The (dead-letter) queue to drain.\n * @param options - Optional {@link JobRedriveOptions}.\n * @returns A promise resolving to the count of jobs moved.\n * @throws `NotSupportedError` if the backend cannot redrive jobs.\n */\n abstract redrive(name: string, options?: JobRedriveOptions): Promise<number>;\n\n /**\n * Permanently deletes one or more jobs from a queue.\n *\n * This is the \"discard\" action for a dead-letter queue: a poison message that\n * should not be reprocessed is removed outright. Unlike {@link JobBroker.deleteJob},\n * it does not require the queue to be registered.\n *\n * @param name - The queue name the jobs live in.\n * @param id - A single job id, or an array of ids, to delete.\n * @returns A promise that resolves once the jobs have been deleted.\n * @throws `NotSupportedError` if the backend cannot delete jobs.\n */\n abstract deleteJob(name: string, id: string | string[]): Promise<void>;\n\n /**\n * Re-attempts one or more failed jobs *in place*, re-queuing them within their\n * current queue.\n *\n * Use this to re-run a job that failed in a queue that has its own worker. To\n * reprocess a job sitting in a dead-letter *sink* (a queue with no worker),\n * prefer {@link redrive}, which moves it back to a queue that can run it.\n *\n * @param name - The queue name the jobs live in.\n * @param id - A single job id, or an array of ids, to retry.\n * @returns A promise that resolves once the jobs have been re-queued.\n * @throws `NotSupportedError` if the backend cannot retry jobs.\n */\n abstract retryJob(name: string, id: string | string[]): Promise<void>;\n}\n","import { Injectable } from 'injectkit';\n\n/**\n * Abstract base class for job runner implementations.\n *\n * A job runner is responsible for consuming jobs from the queue and\n * executing the appropriate job handlers. It manages the worker lifecycle\n * and provides the consumer-side interface for the job processing system.\n *\n * @example\n * ```typescript\n * // Start processing jobs\n * await jobRunner.start();\n *\n * // Gracefully stop processing (e.g., on shutdown)\n * process.on('SIGTERM', async () => {\n * await jobRunner.stop();\n * process.exit(0);\n * });\n * ```\n */\n@Injectable()\nexport abstract class JobRunner {\n /**\n * Starts the job runner and begins processing jobs.\n *\n * This method initializes all registered job handlers and starts\n * listening for jobs on their respective queues. It should be called\n * during application startup.\n *\n * @returns A promise that resolves when the runner has started successfully.\n */\n abstract start(): Promise<void>;\n\n /**\n * Stops the job runner gracefully.\n *\n * This method stops accepting new jobs and waits for currently\n * executing jobs to complete. It should be called during application\n * shutdown to ensure clean termination.\n *\n * @returns A promise that resolves when the runner has stopped completely.\n */\n abstract stop(): Promise<void>;\n}\n"],"mappings":";;;;AAAA,SAASA,kBAAkB;;;;;;;;AA+CpB,IAAeC,YAAf,MAAeA;SAAAA;;;AAgHtB;;;;;;AC/JA,SAASC,cAAAA,mBAAkB;;;;;;;;AA6FpB,IAAeC,aAAf,MAAeA;SAAAA;;;AAwEtB;;;;;;ACrKA,SAASC,cAAAA,mBAAkB;;;;;;;;AAsBpB,IAAeC,YAAf,MAAeA;SAAAA;;;AAsBtB;;;;","names":["Injectable","JobBroker","Injectable","JobMonitor","Injectable","JobRunner"]}
|
package/dist/index.d.ts
CHANGED
|
@@ -2,6 +2,8 @@ export * from './job.broker.js';
|
|
|
2
2
|
export * from './job.js';
|
|
3
3
|
export * from './job.info.js';
|
|
4
4
|
export * from './job.send.options.js';
|
|
5
|
+
export * from './job.queue.policy.js';
|
|
6
|
+
export * from './job.monitor.js';
|
|
5
7
|
export * from './job.runner.js';
|
|
6
8
|
export * from './not.supported.error.js';
|
|
7
9
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
import {
|
|
2
2
|
JobBroker,
|
|
3
|
+
JobMonitor,
|
|
3
4
|
JobRunner,
|
|
4
5
|
__name
|
|
5
|
-
} from "./chunk-
|
|
6
|
+
} from "./chunk-VCGAI6CK.js";
|
|
6
7
|
|
|
7
8
|
// src/job.ts
|
|
8
9
|
import { Injectable } from "injectkit";
|
|
@@ -48,6 +49,7 @@ var NotSupportedError = class extends ServerkitError {
|
|
|
48
49
|
export {
|
|
49
50
|
Job,
|
|
50
51
|
JobBroker,
|
|
52
|
+
JobMonitor,
|
|
51
53
|
JobRunner,
|
|
52
54
|
NotSupportedError
|
|
53
55
|
};
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/job.ts","../src/not.supported.error.ts"],"sourcesContent":["import { Injectable } from 'injectkit';\n\n/**\n * Abstract base class for defining background jobs.\n *\n * Extend this class to create custom job handlers that can be executed\n * asynchronously by a {@link JobRunner}. Each job implementation defines\n * how to process a specific type of payload.\n *\n * @typeParam Payload - The type of data the job expects to receive.\n * Must be an object type. Defaults to `object`.\n *\n * @example\n * ```typescript\n * interface EmailPayload {\n * to: string;\n * subject: string;\n * body: string;\n * }\n *\n * @Injectable()\n * class SendEmailJob extends Job<EmailPayload> {\n * async run(payload: EmailPayload, signal?: AbortSignal): Promise<void> {\n * // Long-running work should honor the signal so the job can be cancelled.\n * await emailService.send(payload.to, payload.subject, payload.body, { signal });\n * if (signal?.aborted) return;\n * }\n * }\n * ```\n */\n@Injectable()\nexport abstract class Job<Payload extends object = object> {\n /**\n * Executes the job with the provided payload.\n *\n * This method is called by the job runner when a job is dequeued\n * and ready for processing. Implementations should contain the\n * business logic for handling the job.\n *\n * The optional `signal` is aborted when the job is cancelled (see\n * {@link JobBroker.cancel}) or when the runner shuts down. Cancellation is\n * cooperative: long-running handlers should forward `signal` to the async\n * operations they perform (fetch, database queries, etc.) or periodically\n * check `signal.aborted` and return early. A handler that ignores the signal\n * cannot be interrupted and will run to completion.\n *\n * @param payload - The data required to execute the job.\n * @param signal - An {@link AbortSignal} that fires when the job is cancelled\n * or the runner stops. Optional; handlers may ignore it.\n * @returns A promise that resolves when the job completes successfully.\n * @throws If the job fails, the error will be caught and logged by the runner.\n */\n abstract run(payload: Payload, signal?: AbortSignal): Promise<void>;\n}\n","import { ServerkitError } from '@maroonedsoftware/errors';\n\n/**\n * Thrown by a {@link JobBroker} when a requested operation is not supported by\n * the underlying backend.\n *\n * Backends vary in what they can do: some queue implementations can cancel a\n * queued job but not look up its state, others cannot cancel individual jobs at\n * all. Rather than silently doing nothing (which hides bugs), a backend throws\n * this error from any capability it cannot honor.\n *\n * Extends {@link ServerkitError}, so `errorMiddleware` renders it (as a 500) and\n * the `withDetails` / `withCause` / `withInternalDetails` setters apply.\n *\n * The bundled pg-boss backend supports every operation and never throws this;\n * it exists as the shared vocabulary for future backends (e.g. SQS, Pub/Sub).\n *\n * @example\n * ```typescript\n * async cancel(): Promise<void> {\n * throw new NotSupportedError('cancel', 'sqs');\n * }\n * ```\n */\nexport class NotSupportedError extends ServerkitError {\n /** The name of the operation that is not supported (e.g. `'cancel'`). */\n readonly operation: string;\n /** The backend that does not support the operation, when known (e.g. `'sqs'`). */\n readonly backend?: string;\n\n /**\n * Creates a new NotSupportedError.\n *\n * @param operation - The name of the unsupported operation.\n * @param backend - The backend that does not support it, if known.\n */\n constructor(operation: string, backend?: string) {\n super(\n backend\n ? `Operation \"${operation}\" is not supported by the ${backend} job broker`\n : `Operation \"${operation}\" is not supported by this job broker`,\n );\n this.name = 'NotSupportedError';\n this.operation = operation;\n this.backend = backend;\n }\n}\n"],"mappings":"
|
|
1
|
+
{"version":3,"sources":["../src/job.ts","../src/not.supported.error.ts"],"sourcesContent":["import { Injectable } from 'injectkit';\n\n/**\n * Abstract base class for defining background jobs.\n *\n * Extend this class to create custom job handlers that can be executed\n * asynchronously by a {@link JobRunner}. Each job implementation defines\n * how to process a specific type of payload.\n *\n * @typeParam Payload - The type of data the job expects to receive.\n * Must be an object type. Defaults to `object`.\n *\n * @example\n * ```typescript\n * interface EmailPayload {\n * to: string;\n * subject: string;\n * body: string;\n * }\n *\n * @Injectable()\n * class SendEmailJob extends Job<EmailPayload> {\n * async run(payload: EmailPayload, signal?: AbortSignal): Promise<void> {\n * // Long-running work should honor the signal so the job can be cancelled.\n * await emailService.send(payload.to, payload.subject, payload.body, { signal });\n * if (signal?.aborted) return;\n * }\n * }\n * ```\n */\n@Injectable()\nexport abstract class Job<Payload extends object = object> {\n /**\n * Executes the job with the provided payload.\n *\n * This method is called by the job runner when a job is dequeued\n * and ready for processing. Implementations should contain the\n * business logic for handling the job.\n *\n * The optional `signal` is aborted when the job is cancelled (see\n * {@link JobBroker.cancel}) or when the runner shuts down. Cancellation is\n * cooperative: long-running handlers should forward `signal` to the async\n * operations they perform (fetch, database queries, etc.) or periodically\n * check `signal.aborted` and return early. A handler that ignores the signal\n * cannot be interrupted and will run to completion.\n *\n * @param payload - The data required to execute the job.\n * @param signal - An {@link AbortSignal} that fires when the job is cancelled\n * or the runner stops. Optional; handlers may ignore it.\n * @returns A promise that resolves when the job completes successfully.\n * @throws If the job fails, the error will be caught and logged by the runner.\n */\n abstract run(payload: Payload, signal?: AbortSignal): Promise<void>;\n}\n","import { ServerkitError } from '@maroonedsoftware/errors';\n\n/**\n * Thrown by a {@link JobBroker} when a requested operation is not supported by\n * the underlying backend.\n *\n * Backends vary in what they can do: some queue implementations can cancel a\n * queued job but not look up its state, others cannot cancel individual jobs at\n * all. Rather than silently doing nothing (which hides bugs), a backend throws\n * this error from any capability it cannot honor.\n *\n * Extends {@link ServerkitError}, so `errorMiddleware` renders it (as a 500) and\n * the `withDetails` / `withCause` / `withInternalDetails` setters apply.\n *\n * The bundled pg-boss backend supports every operation and never throws this;\n * it exists as the shared vocabulary for future backends (e.g. SQS, Pub/Sub).\n *\n * @example\n * ```typescript\n * async cancel(): Promise<void> {\n * throw new NotSupportedError('cancel', 'sqs');\n * }\n * ```\n */\nexport class NotSupportedError extends ServerkitError {\n /** The name of the operation that is not supported (e.g. `'cancel'`). */\n readonly operation: string;\n /** The backend that does not support the operation, when known (e.g. `'sqs'`). */\n readonly backend?: string;\n\n /**\n * Creates a new NotSupportedError.\n *\n * @param operation - The name of the unsupported operation.\n * @param backend - The backend that does not support it, if known.\n */\n constructor(operation: string, backend?: string) {\n super(\n backend\n ? `Operation \"${operation}\" is not supported by the ${backend} job broker`\n : `Operation \"${operation}\" is not supported by this job broker`,\n );\n this.name = 'NotSupportedError';\n this.operation = operation;\n this.backend = backend;\n }\n}\n"],"mappings":";;;;;;;;AAAA,SAASA,kBAAkB;;;;;;;;AA+BpB,IAAeC,MAAf,MAAeA;SAAAA;;;AAsBtB;;;;;;ACrDA,SAASC,sBAAsB;AAwBxB,IAAMC,oBAAN,cAAgCC,eAAAA;EAxBvC,OAwBuCA;;;;EAE5BC;;EAEAC;;;;;;;EAQT,YAAYD,WAAmBC,SAAkB;AAC/C,UACEA,UACI,cAAcD,SAAAA,6BAAsCC,OAAAA,gBACpD,cAAcD,SAAAA,uCAAgD;AAEpE,SAAKE,OAAO;AACZ,SAAKF,YAAYA;AACjB,SAAKC,UAAUA;EACjB;AACF;","names":["Injectable","Job","ServerkitError","NotSupportedError","ServerkitError","operation","backend","name"]}
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
import { JobInfo } from './job.info.js';
|
|
2
|
+
/**
|
|
3
|
+
* A backend-agnostic snapshot of a single queue's depth and health, as returned
|
|
4
|
+
* by {@link JobMonitor.getQueueStats}. Every count is a point-in-time reading;
|
|
5
|
+
* poll it on a schedule (for example from a reconciliation job) to drive
|
|
6
|
+
* alerting on a backlog or a growing dead-letter queue.
|
|
7
|
+
*
|
|
8
|
+
* The counts are the lowest common denominator every supported backend can
|
|
9
|
+
* report. `failed` in particular is a *retained* count: it reflects failures
|
|
10
|
+
* still held in the queue subject to the queue's retention policy, not an
|
|
11
|
+
* all-time total.
|
|
12
|
+
*/
|
|
13
|
+
export interface JobQueueStats {
|
|
14
|
+
/** The queue name these stats describe. */
|
|
15
|
+
name: string;
|
|
16
|
+
/** Jobs waiting to be processed (enqueued but not yet active). */
|
|
17
|
+
queued: number;
|
|
18
|
+
/** Jobs currently being executed by a worker. */
|
|
19
|
+
active: number;
|
|
20
|
+
/** Failed jobs still retained in the queue (bounded by the retention policy). */
|
|
21
|
+
failed: number;
|
|
22
|
+
/** All jobs still retained for the queue across every state. */
|
|
23
|
+
total: number;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Filters for {@link JobMonitor.listJobs}. All fields are optional; omitting them
|
|
27
|
+
* lists every job currently retained in the queue (the common case when
|
|
28
|
+
* inspecting a small dead-letter queue).
|
|
29
|
+
*/
|
|
30
|
+
export interface JobQueryOptions {
|
|
31
|
+
/** Match a single job by its id. */
|
|
32
|
+
id?: string;
|
|
33
|
+
/** Match jobs whose payload contains these fields (a partial-match filter). */
|
|
34
|
+
data?: Record<string, unknown>;
|
|
35
|
+
/** Restrict the result to jobs still waiting to be processed. */
|
|
36
|
+
queuedOnly?: boolean;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Options for {@link JobMonitor.redrive}, which moves dead-lettered jobs out of a
|
|
40
|
+
* queue and back into circulation.
|
|
41
|
+
*/
|
|
42
|
+
export interface JobRedriveOptions {
|
|
43
|
+
/**
|
|
44
|
+
* The queue to move jobs into. When omitted, each job returns to the queue it
|
|
45
|
+
* originally came from before it was dead-lettered — the usual "reprocess"
|
|
46
|
+
* behavior. Supply this to funnel everything into a specific queue instead.
|
|
47
|
+
*/
|
|
48
|
+
destination?: string;
|
|
49
|
+
/**
|
|
50
|
+
* Only redrive jobs that originated from this source queue. Useful when a
|
|
51
|
+
* single dead-letter queue collects failures from several source queues and
|
|
52
|
+
* you want to drain just one source's worth.
|
|
53
|
+
*/
|
|
54
|
+
sourceName?: string;
|
|
55
|
+
/**
|
|
56
|
+
* Maximum number of jobs to move in this call, oldest first. Call repeatedly
|
|
57
|
+
* (or on a schedule) to drain a large dead-letter queue at a controlled rate.
|
|
58
|
+
*/
|
|
59
|
+
limit?: number;
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Read-and-remediate interface for job queues, and in particular for
|
|
63
|
+
* *dead-letter queues*: the queues that collect jobs which have exhausted their
|
|
64
|
+
* retries (see the queue policy on the pg-boss backend's registration).
|
|
65
|
+
*
|
|
66
|
+
* Where {@link JobBroker} is the producer side (enqueue, cancel, inspect a job
|
|
67
|
+
* you hold the id for) and {@link JobRunner} is the consumer side, `JobMonitor`
|
|
68
|
+
* is the operator side: it lets a consumer answer "how deep is this queue?",
|
|
69
|
+
* "what is stuck in this dead-letter queue?", and "reprocess / discard those
|
|
70
|
+
* jobs". Unlike the broker, it operates on raw queue names and does **not**
|
|
71
|
+
* require the queue to be registered, because a dead-letter queue is often an
|
|
72
|
+
* unregistered sink with no worker of its own.
|
|
73
|
+
*
|
|
74
|
+
* Backends that cannot honor an operation throw a `NotSupportedError` rather than
|
|
75
|
+
* silently doing nothing, matching the rest of the package. The bundled pg-boss
|
|
76
|
+
* backend supports every operation.
|
|
77
|
+
*
|
|
78
|
+
* @example
|
|
79
|
+
* ```typescript
|
|
80
|
+
* // A reconciliation sweep over a money-critical dead-letter queue.
|
|
81
|
+
* const stats = await monitor.getQueueStats('charge.webhook.dead');
|
|
82
|
+
* if (stats && stats.total > 0) {
|
|
83
|
+
* const stuck = await monitor.listJobs('charge.webhook.dead'); // inspect / log / alert
|
|
84
|
+
* const moved = await monitor.redrive('charge.webhook.dead', { limit: 100 }); // drain back
|
|
85
|
+
* }
|
|
86
|
+
* ```
|
|
87
|
+
*/
|
|
88
|
+
export declare abstract class JobMonitor {
|
|
89
|
+
/**
|
|
90
|
+
* Reports the current depth and health of a queue.
|
|
91
|
+
*
|
|
92
|
+
* @param name - The queue name to inspect (may be an unregistered dead-letter queue).
|
|
93
|
+
* @returns A promise resolving to the {@link JobQueueStats}, or `null` if no
|
|
94
|
+
* queue with that name exists.
|
|
95
|
+
* @throws `NotSupportedError` if the backend cannot report queue statistics.
|
|
96
|
+
*/
|
|
97
|
+
abstract getQueueStats(name: string): Promise<JobQueueStats | null>;
|
|
98
|
+
/**
|
|
99
|
+
* Lists the jobs currently retained in a queue, optionally filtered.
|
|
100
|
+
*
|
|
101
|
+
* The primary use is inspecting a dead-letter queue: the returned
|
|
102
|
+
* {@link JobInfo} objects expose each poison message's id, state, and original
|
|
103
|
+
* payload so a consumer can decide whether to reprocess ({@link redrive}),
|
|
104
|
+
* discard ({@link deleteJob}), or escalate it.
|
|
105
|
+
*
|
|
106
|
+
* @typeParam Payload - The type of the job payloads.
|
|
107
|
+
* @param name - The queue name to list (may be an unregistered dead-letter queue).
|
|
108
|
+
* @param options - Optional {@link JobQueryOptions} filters.
|
|
109
|
+
* @returns A promise resolving to the matching jobs (empty if none / no such queue).
|
|
110
|
+
* @throws `NotSupportedError` if the backend cannot enumerate jobs.
|
|
111
|
+
*/
|
|
112
|
+
abstract listJobs<Payload extends object>(name: string, options?: JobQueryOptions): Promise<JobInfo<Payload>[]>;
|
|
113
|
+
/**
|
|
114
|
+
* Moves dead-lettered jobs out of a queue and back into circulation, returning
|
|
115
|
+
* the number of jobs moved.
|
|
116
|
+
*
|
|
117
|
+
* By default each job goes back to the source queue it was dead-lettered from,
|
|
118
|
+
* so a worker can process it again; pass {@link JobRedriveOptions.destination}
|
|
119
|
+
* to route them elsewhere, {@link JobRedriveOptions.sourceName} to drain only
|
|
120
|
+
* one source's jobs from a shared dead-letter queue, and
|
|
121
|
+
* {@link JobRedriveOptions.limit} to move at a controlled rate.
|
|
122
|
+
*
|
|
123
|
+
* @param name - The (dead-letter) queue to drain.
|
|
124
|
+
* @param options - Optional {@link JobRedriveOptions}.
|
|
125
|
+
* @returns A promise resolving to the count of jobs moved.
|
|
126
|
+
* @throws `NotSupportedError` if the backend cannot redrive jobs.
|
|
127
|
+
*/
|
|
128
|
+
abstract redrive(name: string, options?: JobRedriveOptions): Promise<number>;
|
|
129
|
+
/**
|
|
130
|
+
* Permanently deletes one or more jobs from a queue.
|
|
131
|
+
*
|
|
132
|
+
* This is the "discard" action for a dead-letter queue: a poison message that
|
|
133
|
+
* should not be reprocessed is removed outright. Unlike {@link JobBroker.deleteJob},
|
|
134
|
+
* it does not require the queue to be registered.
|
|
135
|
+
*
|
|
136
|
+
* @param name - The queue name the jobs live in.
|
|
137
|
+
* @param id - A single job id, or an array of ids, to delete.
|
|
138
|
+
* @returns A promise that resolves once the jobs have been deleted.
|
|
139
|
+
* @throws `NotSupportedError` if the backend cannot delete jobs.
|
|
140
|
+
*/
|
|
141
|
+
abstract deleteJob(name: string, id: string | string[]): Promise<void>;
|
|
142
|
+
/**
|
|
143
|
+
* Re-attempts one or more failed jobs *in place*, re-queuing them within their
|
|
144
|
+
* current queue.
|
|
145
|
+
*
|
|
146
|
+
* Use this to re-run a job that failed in a queue that has its own worker. To
|
|
147
|
+
* reprocess a job sitting in a dead-letter *sink* (a queue with no worker),
|
|
148
|
+
* prefer {@link redrive}, which moves it back to a queue that can run it.
|
|
149
|
+
*
|
|
150
|
+
* @param name - The queue name the jobs live in.
|
|
151
|
+
* @param id - A single job id, or an array of ids, to retry.
|
|
152
|
+
* @returns A promise that resolves once the jobs have been re-queued.
|
|
153
|
+
* @throws `NotSupportedError` if the backend cannot retry jobs.
|
|
154
|
+
*/
|
|
155
|
+
abstract retryJob(name: string, id: string | string[]): Promise<void>;
|
|
156
|
+
}
|
|
157
|
+
//# sourceMappingURL=job.monitor.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"job.monitor.d.ts","sourceRoot":"","sources":["../src/job.monitor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,iEAAiE;IACjE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,8BACsB,UAAU;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAEnE;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,QAAQ,CAAC,OAAO,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;IAE/G;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAE5E;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAEtE;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CACtE"}
|