@sigil-dev/plugin-jobs 0.9.32 → 0.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.
Files changed (4) hide show
  1. package/index.ts +427 -414
  2. package/package.json +4 -4
  3. package/queue.ts +305 -293
  4. package/worker.ts +163 -134
package/package.json CHANGED
@@ -11,7 +11,7 @@
11
11
  "module": "index.ts",
12
12
  "type": "module",
13
13
  "private": false,
14
- "version": "0.9.32",
14
+ "version": "0.10.0",
15
15
  "keywords": [
16
16
  "grimoire",
17
17
  "sigil",
@@ -28,8 +28,8 @@
28
28
  },
29
29
  "peerDependencies": {
30
30
  "typescript": "^5",
31
- "@sigil-dev/grimoire": "0.9.32",
32
- "@sigil-dev/plugin-sql": "0.9.32",
33
- "@sigil-dev/tome": "0.9.32"
31
+ "@sigil-dev/grimoire": "^0.10.0",
32
+ "@sigil-dev/plugin-sql": "^0.10.0",
33
+ "@sigil-dev/tome": "^0.10.0"
34
34
  }
35
35
  }
package/queue.ts CHANGED
@@ -1,293 +1,305 @@
1
- import type { Tome } from "@sigil-dev/tome";
2
- import type { JobsTable } from "./schema.ts";
3
- import type { JobRow, JobStats } from "./store.ts";
4
-
5
- /** When and how often a row runs; `job.enqueue` fills it from the job. */
6
- export interface QueueOptions {
7
- runAt?: Date;
8
- maxAttempts?: number;
9
- }
10
-
11
- // biome-ignore lint/suspicious/noExplicitAny: the queue works on any schema that holds its table
12
- type AnyTome = Tome<any, any>;
13
-
14
- /**
15
- * A durable queue in a tome table.
16
- *
17
- * Delivery is at-least-once, and that is not a caveat to be apologetic
18
- * about — it is the guarantee being bought. A worker can die between doing
19
- * the side effect and deleting the row, so a handler must be idempotent.
20
- * The alternative is exactly-once, which in practice means transactions
21
- * held open across the entire handler, including every HTTP call inside it.
22
- *
23
- * Every query goes through tome, so it runs inside the request's
24
- * transaction when there is one: a job enqueued by a request that fails is
25
- * rolled back with it.
26
- */
27
- export class JobQueue {
28
- /** Recurring jobs: row id → interval. Set by `ensureSchedules`. */
29
- private readonly schedules = new Map<string, number>();
30
- private readonly db: () => AnyTome;
31
-
32
- constructor(
33
- db: AnyTome | (() => AnyTome),
34
- readonly table: JobsTable,
35
- ) {
36
- this.db = typeof db === "function" ? db : () => db;
37
- }
38
-
39
- private get rows() {
40
- return this.db().table(this.table);
41
- }
42
-
43
- /** The row id a schedule lives under. */
44
- static scheduleId(name: string): string {
45
- return `schedule:${name}`;
46
- }
47
-
48
- /** Whether a job is a recurring one, rescheduled rather than deleted. */
49
- isScheduled(id: string): boolean {
50
- return this.schedules.has(id);
51
- }
52
-
53
- /**
54
- * Make the recurring jobs exist, one row each, and remove the rows of
55
- * schedules that are no longer configured.
56
- *
57
- * One row per schedule, rescheduled on completion, is what makes this
58
- * safe with several workers: every worker runs this at boot, but a
59
- * primary key admits one row, and a row is claimed by one worker at a
60
- * time. A scheduler per worker firing on its own clock would run the
61
- * job once per worker.
62
- *
63
- * An existing row keeps its `run_at`, so a restart does not reset the
64
- * clock — and does not run everything the moment a deploy lands.
65
- */
66
- async ensureSchedules(
67
- schedules: Record<
68
- string,
69
- { everyMs: number; payload?: unknown; maxAttempts?: number }
70
- >,
71
- ): Promise<void> {
72
- const j = this.table;
73
- this.schedules.clear();
74
- for (const [name, { everyMs, payload, maxAttempts }] of Object.entries(
75
- schedules,
76
- )) {
77
- const id = JobQueue.scheduleId(name);
78
- this.schedules.set(id, everyMs);
79
- if (await this.rows.exists(j.id.eq(id))) continue;
80
- try {
81
- await this.rows.insert({
82
- id,
83
- name,
84
- payload: JSON.stringify(payload ?? {}),
85
- // First run one interval from now, not at boot: a deploy
86
- // should not fire every schedule at once.
87
- runAt: new Date(Date.now() + everyMs),
88
- ...(maxAttempts ? { maxAttempts } : {}),
89
- });
90
- } catch (e) {
91
- // Another worker inserted it between our check and insert.
92
- if (!(await this.rows.exists(j.id.eq(id)))) throw e;
93
- }
94
- }
95
- const ids = [...this.schedules.keys()];
96
- const stale = this.db().delete(j).where(j.id.like("schedule:%"));
97
- await (ids.length ? stale.where(j.id.notIn(ids)) : stale);
98
- }
99
-
100
- /**
101
- * Move a recurring job to its next run, clearing its attempts. Used on
102
- * success, and on a failure that has used up its retries: a schedule
103
- * that failed five times still runs next time.
104
- */
105
- async reschedule(id: string, lastError: string | null = null): Promise<void> {
106
- const j = this.table;
107
- const every = this.schedules.get(id);
108
- if (every === undefined) {
109
- await this.db().delete(j).where(j.id.eq(id));
110
- return;
111
- }
112
- await this.db()
113
- .update(j)
114
- .set({
115
- runAt: new Date(Date.now() + every),
116
- attempts: 0,
117
- lastError: lastError?.slice(0, 2000) ?? null,
118
- claimedAt: null,
119
- claimToken: null,
120
- })
121
- .where(j.id.eq(id));
122
- }
123
-
124
- /**
125
- * Add a job.
126
- *
127
- * The id is generated here rather than by the database so a retry of
128
- * the enqueue is recognisable, and so a caller who retries cannot
129
- * accidentally create a second job for the same logical work.
130
- */
131
- async enqueue(
132
- name: string,
133
- payload: unknown = {},
134
- options: QueueOptions = {},
135
- ): Promise<string> {
136
- const id = crypto.randomUUID();
137
- await this.rows.insert({
138
- id,
139
- name,
140
- payload: JSON.stringify(payload ?? {}),
141
- runAt: options.runAt ?? new Date(),
142
- maxAttempts: options.maxAttempts ?? 5,
143
- });
144
- return id;
145
- }
146
-
147
- /**
148
- * Atomically take up to `limit` due jobs.
149
- *
150
- * One UPDATE picks the candidates in a subquery and claims them, so
151
- * there is no window between reading and writing. The guard
152
- * (`claim_token IS NULL OR claimed_at < cutoff`) is repeated in the
153
- * outer WHERE: two workers whose subqueries pick the same rows both
154
- * reach the UPDATE, and the second matches nothing because the first
155
- * already set the token. The loser gets an empty batch, never a
156
- * duplicate job — which is the whole requirement.
157
- *
158
- * On postgres the candidates are locked `FOR UPDATE SKIP LOCKED`, so a
159
- * second worker takes the next rows instead of waiting for, and then
160
- * losing, the same ones. SQLite has one writer, so the statement is
161
- * already exclusive.
162
- *
163
- * The rows come back in run_at order. The token is what tells this
164
- * pass which rows it won.
165
- */
166
- async claim(limit: number, staleMs = 60_000): Promise<JobRow[]> {
167
- const db = this.db();
168
- const j = this.table;
169
- const now = new Date().toISOString();
170
- const cutoff = new Date(Date.now() - staleMs).toISOString();
171
- const token = `c_${crypto.randomUUID()}`;
172
- if (db.dialect === "postgres") {
173
- await db.sql`
174
- update ${j}
175
- set claimed_at = ${now}, claim_token = ${token}, attempts = attempts + 1
176
- where id in (
177
- select id from ${j}
178
- where run_at <= ${now}
179
- and attempts < max_attempts
180
- and (claim_token is null or claimed_at < ${cutoff})
181
- order by run_at
182
- limit ${limit}
183
- for update skip locked
184
- )
185
- and attempts < max_attempts
186
- and (claim_token is null or claimed_at < ${cutoff})`;
187
- } else {
188
- await db.sql`
189
- update ${j}
190
- set claimed_at = ${now}, claim_token = ${token}, attempts = attempts + 1
191
- where id in (
192
- select id from ${j}
193
- where run_at <= ${now}
194
- and attempts < max_attempts
195
- and (claim_token is null or claimed_at < ${cutoff})
196
- order by run_at
197
- limit ${limit}
198
- )
199
- and attempts < max_attempts
200
- and (claim_token is null or claimed_at < ${cutoff})`;
201
- }
202
- return (await db
203
- .from(j)
204
- .where(j.claimToken.eq(token))
205
- .orderBy(j.runAt)) as JobRow[];
206
- }
207
-
208
- async complete(id: string): Promise<void> {
209
- if (this.isScheduled(id)) return this.reschedule(id);
210
- const j = this.table;
211
- await this.db().delete(j).where(j.id.eq(id));
212
- }
213
-
214
- /**
215
- * Record a failure.
216
- *
217
- * The row stays, because retry is the point. The claim is cleared so the
218
- * next pass can take it, and `run_at` is pushed into the future so a
219
- * persistently broken handler does not spin — a crash-looping job would
220
- * otherwise burn a worker in a tight loop.
221
- */
222
- async fail(id: string, error: unknown, backoffMs = 30_000): Promise<void> {
223
- const j = this.table;
224
- const message = error instanceof Error ? error.message : String(error);
225
- await this.db()
226
- .update(j)
227
- .set({
228
- lastError: message.slice(0, 2000),
229
- claimedAt: null,
230
- claimToken: null,
231
- runAt: new Date(Date.now() + backoffMs),
232
- })
233
- .where(j.id.eq(id));
234
- }
235
-
236
- /**
237
- * Stop retrying a job: it stays in the table as failed, with the reason,
238
- * for `sigil jobs retry` once whatever was wrong is fixed. For a failure
239
- * another try cannot fix, like a payload the job no longer accepts.
240
- */
241
- async bury(id: string, reason: string): Promise<void> {
242
- const j = this.table;
243
- await this.db()
244
- .update(j)
245
- .set({
246
- lastError: reason.slice(0, 2000),
247
- claimedAt: null,
248
- claimToken: null,
249
- attempts: this.db().sql`max_attempts`,
250
- })
251
- .where(j.id.eq(id));
252
- }
253
-
254
- /** Put a job back on the queue now, for manual recovery. False when there is no such job. */
255
- async retry(id: string): Promise<boolean> {
256
- const j = this.table;
257
- const updated = await this.db()
258
- .update(j)
259
- .set({
260
- attempts: 0,
261
- lastError: null,
262
- claimedAt: null,
263
- claimToken: null,
264
- runAt: new Date(),
265
- })
266
- .where(j.id.eq(id));
267
- return updated.length > 0;
268
- }
269
-
270
- async list(limit = 20): Promise<JobRow[]> {
271
- const j = this.table;
272
- return (await this.db()
273
- .from(j)
274
- .orderBy(j.createdAt.desc())
275
- .limit(limit)) as JobRow[];
276
- }
277
-
278
- async stats(): Promise<JobStats> {
279
- const db = this.db();
280
- const j = this.table;
281
- const [row] = (await db.sql`
282
- select
283
- sum(case when attempts >= max_attempts then 1 else 0 end) as failed,
284
- sum(case when attempts < max_attempts and claimed_at is not null then 1 else 0 end) as claimed,
285
- sum(case when attempts < max_attempts and claimed_at is null then 1 else 0 end) as pending
286
- from ${j}`) as { failed: unknown; claimed: unknown; pending: unknown }[];
287
- return {
288
- pending: Number(row?.pending ?? 0),
289
- claimed: Number(row?.claimed ?? 0),
290
- failed: Number(row?.failed ?? 0),
291
- };
292
- }
293
- }
1
+ import type { Tome } from "@sigil-dev/tome";
2
+ import type { JobsTable } from "./schema.ts";
3
+ import type { JobRow, JobStats } from "./store.ts";
4
+
5
+ /** When and how often a row runs; `job.enqueue` fills it from the job. */
6
+ export interface QueueOptions {
7
+ runAt?: Date;
8
+ maxAttempts?: number;
9
+ }
10
+
11
+ // biome-ignore lint/suspicious/noExplicitAny: the queue works on any schema that holds its table
12
+ type AnyTome = Tome<any, any>;
13
+
14
+ /**
15
+ * A durable queue in a tome table.
16
+ *
17
+ * Delivery is at-least-once, and that is not a caveat to be apologetic
18
+ * about — it is the guarantee being bought. A worker can die between doing
19
+ * the side effect and deleting the row, so a handler must be idempotent.
20
+ * The alternative is exactly-once, which in practice means transactions
21
+ * held open across the entire handler, including every HTTP call inside it.
22
+ *
23
+ * Every query goes through tome, so it runs inside the request's
24
+ * transaction when there is one: a job enqueued by a request that fails is
25
+ * rolled back with it.
26
+ */
27
+ /**
28
+ * The queue's table isn't there: the app started before `sigil db migrate`.
29
+ * sqlite says "no such table", postgres 42P01 / "does not exist".
30
+ */
31
+ export function isMissingTable(error: unknown): boolean {
32
+ const e = error as { code?: unknown; errno?: unknown; message?: unknown } | null;
33
+ if (!e || typeof e !== "object") return false;
34
+ if (e.code === "42P01") return true;
35
+ const message = String(e.message ?? "");
36
+ return /no such table|relation "[^"]*" does not exist|doesn't exist/i.test(message);
37
+ }
38
+
39
+ export class JobQueue {
40
+ /** Recurring jobs: row id → interval. Set by `ensureSchedules`. */
41
+ private readonly schedules = new Map<string, number>();
42
+ private readonly db: () => AnyTome;
43
+
44
+ constructor(
45
+ db: AnyTome | (() => AnyTome),
46
+ readonly table: JobsTable,
47
+ ) {
48
+ this.db = typeof db === "function" ? db : () => db;
49
+ }
50
+
51
+ private get rows() {
52
+ return this.db().table(this.table);
53
+ }
54
+
55
+ /** The row id a schedule lives under. */
56
+ static scheduleId(name: string): string {
57
+ return `schedule:${name}`;
58
+ }
59
+
60
+ /** Whether a job is a recurring one, rescheduled rather than deleted. */
61
+ isScheduled(id: string): boolean {
62
+ return this.schedules.has(id);
63
+ }
64
+
65
+ /**
66
+ * Make the recurring jobs exist, one row each, and remove the rows of
67
+ * schedules that are no longer configured.
68
+ *
69
+ * One row per schedule, rescheduled on completion, is what makes this
70
+ * safe with several workers: every worker runs this at boot, but a
71
+ * primary key admits one row, and a row is claimed by one worker at a
72
+ * time. A scheduler per worker firing on its own clock would run the
73
+ * job once per worker.
74
+ *
75
+ * An existing row keeps its `run_at`, so a restart does not reset the
76
+ * clock — and does not run everything the moment a deploy lands.
77
+ */
78
+ async ensureSchedules(
79
+ schedules: Record<
80
+ string,
81
+ { everyMs: number; payload?: unknown; maxAttempts?: number }
82
+ >,
83
+ ): Promise<void> {
84
+ const j = this.table;
85
+ this.schedules.clear();
86
+ for (const [name, { everyMs, payload, maxAttempts }] of Object.entries(
87
+ schedules,
88
+ )) {
89
+ const id = JobQueue.scheduleId(name);
90
+ this.schedules.set(id, everyMs);
91
+ if (await this.rows.exists(j.id.eq(id))) continue;
92
+ try {
93
+ await this.rows.insert({
94
+ id,
95
+ name,
96
+ payload: JSON.stringify(payload ?? {}),
97
+ // First run one interval from now, not at boot: a deploy
98
+ // should not fire every schedule at once.
99
+ runAt: new Date(Date.now() + everyMs),
100
+ ...(maxAttempts ? { maxAttempts } : {}),
101
+ });
102
+ } catch (e) {
103
+ // Another worker inserted it between our check and insert.
104
+ if (!(await this.rows.exists(j.id.eq(id)))) throw e;
105
+ }
106
+ }
107
+ const ids = [...this.schedules.keys()];
108
+ const stale = this.db().delete(j).where(j.id.like("schedule:%"));
109
+ await (ids.length ? stale.where(j.id.notIn(ids)) : stale);
110
+ }
111
+
112
+ /**
113
+ * Move a recurring job to its next run, clearing its attempts. Used on
114
+ * success, and on a failure that has used up its retries: a schedule
115
+ * that failed five times still runs next time.
116
+ */
117
+ async reschedule(id: string, lastError: string | null = null): Promise<void> {
118
+ const j = this.table;
119
+ const every = this.schedules.get(id);
120
+ if (every === undefined) {
121
+ await this.db().delete(j).where(j.id.eq(id));
122
+ return;
123
+ }
124
+ await this.db()
125
+ .update(j)
126
+ .set({
127
+ runAt: new Date(Date.now() + every),
128
+ attempts: 0,
129
+ lastError: lastError?.slice(0, 2000) ?? null,
130
+ claimedAt: null,
131
+ claimToken: null,
132
+ })
133
+ .where(j.id.eq(id));
134
+ }
135
+
136
+ /**
137
+ * Add a job.
138
+ *
139
+ * The id is generated here rather than by the database so a retry of
140
+ * the enqueue is recognisable, and so a caller who retries cannot
141
+ * accidentally create a second job for the same logical work.
142
+ */
143
+ async enqueue(
144
+ name: string,
145
+ payload: unknown = {},
146
+ options: QueueOptions = {},
147
+ ): Promise<string> {
148
+ const id = crypto.randomUUID();
149
+ await this.rows.insert({
150
+ id,
151
+ name,
152
+ payload: JSON.stringify(payload ?? {}),
153
+ runAt: options.runAt ?? new Date(),
154
+ maxAttempts: options.maxAttempts ?? 5,
155
+ });
156
+ return id;
157
+ }
158
+
159
+ /**
160
+ * Atomically take up to `limit` due jobs.
161
+ *
162
+ * One UPDATE picks the candidates in a subquery and claims them, so
163
+ * there is no window between reading and writing. The guard
164
+ * (`claim_token IS NULL OR claimed_at < cutoff`) is repeated in the
165
+ * outer WHERE: two workers whose subqueries pick the same rows both
166
+ * reach the UPDATE, and the second matches nothing because the first
167
+ * already set the token. The loser gets an empty batch, never a
168
+ * duplicate job — which is the whole requirement.
169
+ *
170
+ * On postgres the candidates are locked `FOR UPDATE SKIP LOCKED`, so a
171
+ * second worker takes the next rows instead of waiting for, and then
172
+ * losing, the same ones. SQLite has one writer, so the statement is
173
+ * already exclusive.
174
+ *
175
+ * The rows come back in run_at order. The token is what tells this
176
+ * pass which rows it won.
177
+ */
178
+ async claim(limit: number, staleMs = 60_000): Promise<JobRow[]> {
179
+ const db = this.db();
180
+ const j = this.table;
181
+ const now = new Date().toISOString();
182
+ const cutoff = new Date(Date.now() - staleMs).toISOString();
183
+ const token = `c_${crypto.randomUUID()}`;
184
+ if (db.dialect === "postgres") {
185
+ await db.sql`
186
+ update ${j}
187
+ set claimed_at = ${now}, claim_token = ${token}, attempts = attempts + 1
188
+ where id in (
189
+ select id from ${j}
190
+ where run_at <= ${now}
191
+ and attempts < max_attempts
192
+ and (claim_token is null or claimed_at < ${cutoff})
193
+ order by run_at
194
+ limit ${limit}
195
+ for update skip locked
196
+ )
197
+ and attempts < max_attempts
198
+ and (claim_token is null or claimed_at < ${cutoff})`;
199
+ } else {
200
+ await db.sql`
201
+ update ${j}
202
+ set claimed_at = ${now}, claim_token = ${token}, attempts = attempts + 1
203
+ where id in (
204
+ select id from ${j}
205
+ where run_at <= ${now}
206
+ and attempts < max_attempts
207
+ and (claim_token is null or claimed_at < ${cutoff})
208
+ order by run_at
209
+ limit ${limit}
210
+ )
211
+ and attempts < max_attempts
212
+ and (claim_token is null or claimed_at < ${cutoff})`;
213
+ }
214
+ return (await db
215
+ .from(j)
216
+ .where(j.claimToken.eq(token))
217
+ .orderBy(j.runAt)) as JobRow[];
218
+ }
219
+
220
+ async complete(id: string): Promise<void> {
221
+ if (this.isScheduled(id)) return this.reschedule(id);
222
+ const j = this.table;
223
+ await this.db().delete(j).where(j.id.eq(id));
224
+ }
225
+
226
+ /**
227
+ * Record a failure.
228
+ *
229
+ * The row stays, because retry is the point. The claim is cleared so the
230
+ * next pass can take it, and `run_at` is pushed into the future so a
231
+ * persistently broken handler does not spin — a crash-looping job would
232
+ * otherwise burn a worker in a tight loop.
233
+ */
234
+ async fail(id: string, error: unknown, backoffMs = 30_000): Promise<void> {
235
+ const j = this.table;
236
+ const message = error instanceof Error ? error.message : String(error);
237
+ await this.db()
238
+ .update(j)
239
+ .set({
240
+ lastError: message.slice(0, 2000),
241
+ claimedAt: null,
242
+ claimToken: null,
243
+ runAt: new Date(Date.now() + backoffMs),
244
+ })
245
+ .where(j.id.eq(id));
246
+ }
247
+
248
+ /**
249
+ * Stop retrying a job: it stays in the table as failed, with the reason,
250
+ * for `sigil jobs retry` once whatever was wrong is fixed. For a failure
251
+ * another try cannot fix, like a payload the job no longer accepts.
252
+ */
253
+ async bury(id: string, reason: string): Promise<void> {
254
+ const j = this.table;
255
+ await this.db()
256
+ .update(j)
257
+ .set({
258
+ lastError: reason.slice(0, 2000),
259
+ claimedAt: null,
260
+ claimToken: null,
261
+ attempts: this.db().sql`max_attempts`,
262
+ })
263
+ .where(j.id.eq(id));
264
+ }
265
+
266
+ /** Put a job back on the queue now, for manual recovery. False when there is no such job. */
267
+ async retry(id: string): Promise<boolean> {
268
+ const j = this.table;
269
+ const updated = await this.db()
270
+ .update(j)
271
+ .set({
272
+ attempts: 0,
273
+ lastError: null,
274
+ claimedAt: null,
275
+ claimToken: null,
276
+ runAt: new Date(),
277
+ })
278
+ .where(j.id.eq(id));
279
+ return updated.length > 0;
280
+ }
281
+
282
+ async list(limit = 20): Promise<JobRow[]> {
283
+ const j = this.table;
284
+ return (await this.db()
285
+ .from(j)
286
+ .orderBy(j.createdAt.desc())
287
+ .limit(limit)) as JobRow[];
288
+ }
289
+
290
+ async stats(): Promise<JobStats> {
291
+ const db = this.db();
292
+ const j = this.table;
293
+ const [row] = (await db.sql`
294
+ select
295
+ sum(case when attempts >= max_attempts then 1 else 0 end) as failed,
296
+ sum(case when attempts < max_attempts and claimed_at is not null then 1 else 0 end) as claimed,
297
+ sum(case when attempts < max_attempts and claimed_at is null then 1 else 0 end) as pending
298
+ from ${j}`) as { failed: unknown; claimed: unknown; pending: unknown }[];
299
+ return {
300
+ pending: Number(row?.pending ?? 0),
301
+ claimed: Number(row?.claimed ?? 0),
302
+ failed: Number(row?.failed ?? 0),
303
+ };
304
+ }
305
+ }