@maroonedsoftware/jobbroker 1.8.2 → 1.9.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 +132 -10
- 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/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 +1 -0
- package/dist/pgboss.d.ts.map +1 -1
- package/dist/pgboss.js +246 -17
- package/dist/pgboss.js.map +1 -1
- package/package.json +1 -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
|
|
@@ -23,8 +25,8 @@ pnpm add @maroonedsoftware/jobbroker injectkit pg-boss reflect-metadata
|
|
|
23
25
|
|
|
24
26
|
| Import | Contents | Pulls in |
|
|
25
27
|
| ------------------------------------ | ---------------------------------------------------------------------------------------- | ------------- |
|
|
26
|
-
| `@maroonedsoftware/jobbroker` | `Job`, `JobBroker`, `JobRunner`, `JobInfo`, `JobState`, `NotSupportedError`
|
|
27
|
-
| `@maroonedsoftware/jobbroker/pgboss` | `PgBossJobBroker`, `PgBossJobRunner`, `PgBossJobRegistryMap`, `PgBossConnectionProvider` | `pg-boss` |
|
|
28
|
+
| `@maroonedsoftware/jobbroker` | `Job`, `JobBroker`, `JobRunner`, `JobMonitor`, `JobInfo`, `JobState`, `JobQueuePolicy`, `NotSupportedError` | nothing extra |
|
|
29
|
+
| `@maroonedsoftware/jobbroker/pgboss` | `PgBossJobBroker`, `PgBossJobRunner`, `PgBossJobMonitor`, `PgBossJobRegistryMap`, `PgBossConnectionProvider` | `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,8 @@ 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 { PgBossJobBroker, PgBossJobRunner, PgBossJobRegistryMap, PgBossConnectionProvider } from '@maroonedsoftware/jobbroker/pgboss';
|
|
99
|
+
import { JobBroker, JobRunner, JobMonitor } from '@maroonedsoftware/jobbroker';
|
|
100
|
+
import { PgBossJobBroker, PgBossJobRunner, PgBossJobMonitor, PgBossJobRegistryMap, PgBossConnectionProvider } from '@maroonedsoftware/jobbroker/pgboss';
|
|
88
101
|
|
|
89
102
|
// Initialize pg-boss
|
|
90
103
|
const pgboss = new PgBoss('postgres://user:pass@localhost/mydb');
|
|
@@ -98,6 +111,7 @@ diRegistry.register(Logger).useClass(ConsoleLogger).asSingleton();
|
|
|
98
111
|
diRegistry.register(PgBossConnectionProvider).useClass(PgBossConnectionProvider).asSingleton();
|
|
99
112
|
diRegistry.register(JobBroker).useClass(PgBossJobBroker).asSingleton();
|
|
100
113
|
diRegistry.register(JobRunner).useClass(PgBossJobRunner).asSingleton();
|
|
114
|
+
diRegistry.register(JobMonitor).useClass(PgBossJobMonitor).asSingleton();
|
|
101
115
|
|
|
102
116
|
// Build the container
|
|
103
117
|
const container = diRegistry.build();
|
|
@@ -160,6 +174,80 @@ runner.cancelPollIntervalSeconds = 2; // default 5; set to 0 to disable polling
|
|
|
160
174
|
|
|
161
175
|
Lower values reduce cancellation latency at the cost of one extra lookup query per running job per interval.
|
|
162
176
|
|
|
177
|
+
## Retry & dead-letter policy
|
|
178
|
+
|
|
179
|
+
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.
|
|
180
|
+
|
|
181
|
+
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):
|
|
182
|
+
|
|
183
|
+
```typescript
|
|
184
|
+
import { Duration } from 'luxon';
|
|
185
|
+
|
|
186
|
+
registry.set('deliver-webhook', {
|
|
187
|
+
job: DeliverWebhookJob,
|
|
188
|
+
policy: {
|
|
189
|
+
retryLimit: 5, // attempts before the job is failed / dead-lettered
|
|
190
|
+
retryDelay: Duration.fromObject({ seconds: 30 }), // base delay between attempts
|
|
191
|
+
retryBackoff: true, // grow the delay exponentially (with jitter) from retryDelay
|
|
192
|
+
retryDelayMax: Duration.fromObject({ minutes: 10 }), // cap for the backoff curve
|
|
193
|
+
expiresIn: Duration.fromObject({ minutes: 2 }), // a run is considered stuck after this
|
|
194
|
+
deadLetter: 'deliver-webhook-dead', // where exhausted jobs land
|
|
195
|
+
},
|
|
196
|
+
});
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
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.
|
|
200
|
+
|
|
201
|
+
**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.
|
|
202
|
+
|
|
203
|
+
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:
|
|
204
|
+
|
|
205
|
+
```typescript
|
|
206
|
+
const runner = container.get(JobRunner) as PgBossJobRunner;
|
|
207
|
+
runner.defaultQueuePolicy = {
|
|
208
|
+
retryLimit: 3,
|
|
209
|
+
retryBackoff: true,
|
|
210
|
+
retryDelay: Duration.fromObject({ seconds: 10 }),
|
|
211
|
+
};
|
|
212
|
+
await runner.start();
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
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.
|
|
216
|
+
|
|
217
|
+
## Monitoring & draining dead-letter queues
|
|
218
|
+
|
|
219
|
+
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.
|
|
220
|
+
|
|
221
|
+
```typescript
|
|
222
|
+
const monitor = container.get(JobMonitor);
|
|
223
|
+
|
|
224
|
+
// Observe — poll depth/health (e.g. from a reconciliation cron) to alert on a growing DLQ
|
|
225
|
+
const stats = await monitor.getQueueStats('deliver-webhook-dead');
|
|
226
|
+
// stats: { name, queued, active, failed, total } | null (null when the queue does not exist)
|
|
227
|
+
|
|
228
|
+
if (stats && stats.total > 0) {
|
|
229
|
+
// Retrieve — inspect the poison messages (id, state, original payload)
|
|
230
|
+
const stuck = await monitor.listJobs<WebhookPayload>('deliver-webhook-dead');
|
|
231
|
+
logger.warn(`${stuck.length} webhooks in the dead-letter queue`, { ids: stuck.map(j => j.id) });
|
|
232
|
+
|
|
233
|
+
// Act — move them back to their original source queue to reprocess, oldest first, rate-limited
|
|
234
|
+
const moved = await monitor.redrive('deliver-webhook-dead', { limit: 100 });
|
|
235
|
+
|
|
236
|
+
// ...or discard a specific unrecoverable message
|
|
237
|
+
await monitor.deleteJob('deliver-webhook-dead', stuck[0].id);
|
|
238
|
+
}
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
| Method | Description |
|
|
242
|
+
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
243
|
+
| `getQueueStats(name)` | Point-in-time `{ name, queued, active, failed, total }`, or `null` if the queue does not exist. |
|
|
244
|
+
| `listJobs<P>(name, options?)` | List retained jobs as `JobInfo<P>[]`; filter by `id`, partial `data`, or `queuedOnly`. |
|
|
245
|
+
| `redrive(name, options?)` | Move dead-lettered jobs back to their source (or a `destination`), oldest first; returns count. |
|
|
246
|
+
| `deleteJob(name, id)` | Permanently discard one or more jobs (no registry check, so DLQ sinks are serviceable). |
|
|
247
|
+
| `retryJob(name, id)` | Re-attempt failed jobs **in place**; for a DLQ sink prefer `redrive`, which moves them to a worker. |
|
|
248
|
+
|
|
249
|
+
`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)).
|
|
250
|
+
|
|
163
251
|
### Backend portability
|
|
164
252
|
|
|
165
253
|
`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.
|
|
@@ -203,6 +291,20 @@ Abstract base class for processing jobs from the queue.
|
|
|
203
291
|
| `start(): Promise<void>` | Start processing jobs |
|
|
204
292
|
| `stop(): Promise<void>` | Gracefully stop processing |
|
|
205
293
|
|
|
294
|
+
### `JobMonitor`
|
|
295
|
+
|
|
296
|
+
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).
|
|
297
|
+
|
|
298
|
+
| Method | Description |
|
|
299
|
+
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
300
|
+
| `getQueueStats(name: string): Promise<JobQueueStats \| null>` | Queue depth/health counts, or `null` if the queue does not exist |
|
|
301
|
+
| `listJobs<P>(name: string, options?: JobQueryOptions): Promise<JobInfo<P>[]>` | List retained jobs, optionally filtered by `id`, `data`, or `queuedOnly` |
|
|
302
|
+
| `redrive(name: string, options?: JobRedriveOptions): Promise<number>` | Move dead-lettered jobs back to source (or a `destination`); returns count moved |
|
|
303
|
+
| `deleteJob(name: string, id: string \| string[]): Promise<void>` | Permanently discard jobs |
|
|
304
|
+
| `retryJob(name: string, id: string \| string[]): Promise<void>` | Re-attempt failed jobs in place |
|
|
305
|
+
|
|
306
|
+
`JobQueueStats` is `{ name, queued, active, failed, total }`. `JobQueryOptions` is `{ id?, data?, queuedOnly? }`. `JobRedriveOptions` is `{ destination?, sourceName?, limit? }`.
|
|
307
|
+
|
|
206
308
|
### `PgBossJobRegistryMap`
|
|
207
309
|
|
|
208
310
|
A `Map<string, Identifier<Job> | PgBossJobRegistration>` for registering jobs.
|
|
@@ -210,16 +312,30 @@ A `Map<string, Identifier<Job> | PgBossJobRegistration>` for registering jobs.
|
|
|
210
312
|
Entries can be either:
|
|
211
313
|
|
|
212
314
|
- A job class identifier (for on-demand jobs)
|
|
213
|
-
- A `PgBossJobRegistration` object
|
|
315
|
+
- A `PgBossJobRegistration` object (for scheduled jobs, jobs with a queue policy, or both)
|
|
214
316
|
|
|
215
317
|
### `PgBossJobRegistration`
|
|
216
318
|
|
|
217
|
-
Configuration object for a scheduled job.
|
|
319
|
+
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.
|
|
320
|
+
|
|
321
|
+
| Property | Type | Description |
|
|
322
|
+
| -------- | ----------------- | ------------------------------------------------------------------- |
|
|
323
|
+
| `job` | `Identifier<Job>` | The job class identifier to instantiate when the job runs. |
|
|
324
|
+
| `cron` | `string` | Optional cron expression defining when the job should run. |
|
|
325
|
+
| `policy` | `JobQueuePolicy` | Optional per-queue retry and dead-letter policy for the job's queue. |
|
|
218
326
|
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
327
|
+
### `JobQueuePolicy`
|
|
328
|
+
|
|
329
|
+
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.
|
|
330
|
+
|
|
331
|
+
| Property | Type | Description |
|
|
332
|
+
| --------------- | ---------- | --------------------------------------------------------------------------------------- |
|
|
333
|
+
| `retryLimit` | `number` | Attempts before a job is failed (and dead-lettered, if `deadLetter` is set). |
|
|
334
|
+
| `retryDelay` | `Duration` | Delay before retrying; the base of the curve when `retryBackoff` is on. |
|
|
335
|
+
| `retryBackoff` | `boolean` | Grow the retry delay exponentially (with jitter) from `retryDelay` instead of fixed. |
|
|
336
|
+
| `retryDelayMax` | `Duration` | Upper bound on the backoff delay. Only used when `retryBackoff` is on. |
|
|
337
|
+
| `expiresIn` | `Duration` | How long a run may take before it is considered stuck and made eligible for retry. |
|
|
338
|
+
| `deadLetter` | `string` | Name of the dead-letter queue that receives jobs which exhaust their retries. |
|
|
223
339
|
|
|
224
340
|
### `PgBossJobBroker`
|
|
225
341
|
|
|
@@ -269,6 +385,12 @@ Concrete `JobRunner` implementation backed by pg-boss. Constructor signature: `n
|
|
|
269
385
|
|
|
270
386
|
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
387
|
|
|
388
|
+
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).
|
|
389
|
+
|
|
390
|
+
### `PgBossJobMonitor`
|
|
391
|
+
|
|
392
|
+
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.
|
|
393
|
+
|
|
272
394
|
## Graceful Shutdown
|
|
273
395
|
|
|
274
396
|
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"}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import { Duration } from 'luxon';
|
|
2
|
+
/**
|
|
3
|
+
* Backend-agnostic reliability policy for a job *queue*: how many times a failed
|
|
4
|
+
* job is retried, how long to wait between attempts, how long a running job may
|
|
5
|
+
* take before it is considered stuck, and where a job goes once it has exhausted
|
|
6
|
+
* its retries.
|
|
7
|
+
*
|
|
8
|
+
* Like {@link JobSendOptions}, this type describes *intent* rather than any one
|
|
9
|
+
* backend's wire format. Retry, backoff, and dead-lettering are queue-level
|
|
10
|
+
* concepts on every mainstream queue (pg-boss `retryLimit`/`deadLetter`, SQS's
|
|
11
|
+
* redrive policy `maxReceiveCount` + DLQ ARN, Cloud Tasks' `maxAttempts` /
|
|
12
|
+
* `minBackoff`), so a policy declared here maps cleanly onto whichever backend
|
|
13
|
+
* is in use. A backend that cannot honor a requested knob throws a
|
|
14
|
+
* `NotSupportedError` rather than silently ignoring it.
|
|
15
|
+
*
|
|
16
|
+
* Because these are queue-level properties, the policy is declared where the job
|
|
17
|
+
* is registered (see the pg-boss `PgBossJobRegistration`), not per individual
|
|
18
|
+
* `send`. Deferring a single job is still a per-send concern (see
|
|
19
|
+
* {@link JobSendOptions.startAfter}); retry/dead-letter behavior is not.
|
|
20
|
+
*
|
|
21
|
+
* @example
|
|
22
|
+
* ```typescript
|
|
23
|
+
* const policy: JobQueuePolicy = {
|
|
24
|
+
* retryLimit: 5,
|
|
25
|
+
* retryDelay: Duration.fromObject({ seconds: 30 }),
|
|
26
|
+
* retryBackoff: true,
|
|
27
|
+
* deadLetter: 'charge.webhook.dead',
|
|
28
|
+
* };
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
31
|
+
export interface JobQueuePolicy {
|
|
32
|
+
/**
|
|
33
|
+
* How many times a failed job is retried before it is marked failed (and, if a
|
|
34
|
+
* {@link deadLetter} queue is set, dead-lettered). Omit to use the backend's
|
|
35
|
+
* default.
|
|
36
|
+
*/
|
|
37
|
+
retryLimit?: number;
|
|
38
|
+
/**
|
|
39
|
+
* Delay to wait before retrying a failed job. When {@link retryBackoff} is
|
|
40
|
+
* enabled this is the *base* delay that the backoff curve grows from. Backends
|
|
41
|
+
* that measure retry delay in whole seconds receive this rounded to the
|
|
42
|
+
* nearest second.
|
|
43
|
+
*/
|
|
44
|
+
retryDelay?: Duration;
|
|
45
|
+
/**
|
|
46
|
+
* Grow the delay between successive retries exponentially (with jitter)
|
|
47
|
+
* starting from {@link retryDelay}, instead of waiting a fixed
|
|
48
|
+
* {@link retryDelay} each time. Useful for backing off transient failures such
|
|
49
|
+
* as a rate-limited external API.
|
|
50
|
+
*/
|
|
51
|
+
retryBackoff?: boolean;
|
|
52
|
+
/**
|
|
53
|
+
* Upper bound on the delay between retries when {@link retryBackoff} is
|
|
54
|
+
* enabled. Ignored for fixed-delay retries. Rounded to whole seconds for
|
|
55
|
+
* backends that require it.
|
|
56
|
+
*/
|
|
57
|
+
retryDelayMax?: Duration;
|
|
58
|
+
/**
|
|
59
|
+
* How long a job may run before it is considered stuck and made eligible for
|
|
60
|
+
* retry (or failure). Maps onto pg-boss `expireInSeconds`, an SQS visibility
|
|
61
|
+
* timeout, and similar. Rounded to whole seconds for backends that require it.
|
|
62
|
+
*/
|
|
63
|
+
expiresIn?: Duration;
|
|
64
|
+
/**
|
|
65
|
+
* Name of the dead-letter queue that receives a job once it has exhausted all
|
|
66
|
+
* of its retries, so terminal failures are preserved for inspection or replay
|
|
67
|
+
* instead of being dropped. The referenced queue must exist; backends that can
|
|
68
|
+
* do so (pg-boss) create it automatically when absent.
|
|
69
|
+
*/
|
|
70
|
+
deadLetter?: string;
|
|
71
|
+
}
|
|
72
|
+
//# sourceMappingURL=job.queue.policy.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"job.queue.policy.d.ts","sourceRoot":"","sources":["../src/job.queue.policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,QAAQ,CAAC;IAEtB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC;IAEzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC;IAErB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}
|