@sigil-dev/plugin-jobs 0.9.21 → 0.9.22

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 (8) hide show
  1. package/README.md +159 -154
  2. package/index.ts +480 -452
  3. package/package.json +3 -3
  4. package/queue.ts +396 -396
  5. package/store-bun.ts +137 -137
  6. package/store-drizzle.ts +86 -86
  7. package/store.ts +117 -117
  8. package/worker.ts +128 -128
package/queue.ts CHANGED
@@ -1,396 +1,396 @@
1
- import type {
2
- Capabilities,
3
- EnqueueOptions,
4
- JobRow,
5
- JobStats,
6
- JobStore,
7
- } from "./store.ts";
8
-
9
- /**
10
- * Schema statements, kept portable.
11
- *
12
- * Deliberately plain: no dialect, no generated columns, no `jsonb`. The
13
- * payload is TEXT holding JSON rather than a JSON column type, because the
14
- * json type is spelled differently everywhere and nothing here needs to
15
- * query inside the payload.
16
- */
17
- export const SCHEMA = `
18
- CREATE TABLE IF NOT EXISTS sigil_jobs (
19
- -- VARCHAR(64), not TEXT: MySQL refuses to index a TEXT primary key
20
- -- without a prefix length ("BLOB/TEXT column 'id' used in key
21
- -- specification without a key length"), so a portable id column has to
22
- -- be a bounded character type. 36 is a UUID with room to spare, and it
23
- -- is what the generated ids actually look like.
24
- id VARCHAR(64) PRIMARY KEY,
25
- name TEXT NOT NULL,
26
- payload TEXT NOT NULL,
27
- -- name is indexed nowhere, so TEXT is fine and keeps long handler
28
- -- names from being truncated by a column width.
29
- run_at TIMESTAMP NOT NULL,
30
- attempts INTEGER NOT NULL DEFAULT 0,
31
- max_attempts INTEGER NOT NULL DEFAULT 5,
32
- last_error TEXT,
33
- claimed_at TIMESTAMP,
34
- -- Which claim took this row. NOT a timestamp: MySQL truncates TIMESTAMP to
35
- -- whole seconds, so two workers claiming in the same second are
36
- -- indistinguishable, and the stale-claim comparison then re-claims a live
37
- -- row. Measured: a second worker re-claimed rows claimed milliseconds
38
- -- earlier. A random token per claim is exact on all three dialects.
39
- claim_token VARCHAR(64),
40
- created_at TIMESTAMP NOT NULL
41
- );
42
- CREATE INDEX IF NOT EXISTS sigil_jobs_ready ON sigil_jobs (run_at);
43
- `;
44
-
45
- /**
46
- * A durable queue over any client that can run a query and return rows.
47
- *
48
- * Delivery is at-least-once, and that is not a caveat to be apologetic
49
- * about — it is the guarantee being bought. A worker can die between doing
50
- * the side effect and deleting the row, so a handler must be idempotent.
51
- * The alternative is exactly-once, which in practice means transactions
52
- * held open across the entire handler, including every HTTP call inside it.
53
- */
54
- export class JobQueue {
55
- /** Recurring jobs: row id → interval. Set by `ensureSchedules`. */
56
- private readonly schedules = new Map<string, number>();
57
-
58
- constructor(
59
- private readonly store: JobStore,
60
- private readonly table: string = "sigil_jobs",
61
- ) {}
62
-
63
- /**
64
- * Every capability defaults to false. A store that declares nothing gets
65
- * the weakest path, which is correct on every dialect rather than correct
66
- * on the one it was written for.
67
- *
68
- * Read on use rather than at construction: a store over a database that
69
- * opens later only knows its dialect once it is open.
70
- */
71
- private get caps(): Required<Capabilities> {
72
- return {
73
- skipLocked: this.store.capabilities?.skipLocked ?? false,
74
- spaceSeparatedTimestamp:
75
- this.store.capabilities?.spaceSeparatedTimestamp ?? false,
76
- };
77
- }
78
-
79
- /** The row id a schedule lives under. */
80
- static scheduleId(name: string): string {
81
- return `schedule:${name}`;
82
- }
83
-
84
- /** Whether a job is a recurring one, rescheduled rather than deleted. */
85
- isScheduled(id: string): boolean {
86
- return this.schedules.has(id);
87
- }
88
-
89
- /**
90
- * Make the recurring jobs exist, one row each, and remove the rows of
91
- * schedules that are no longer configured.
92
- *
93
- * One row per schedule, rescheduled on completion, is what makes this
94
- * safe with several workers: every worker runs this at boot, but a
95
- * primary key admits one row, and a row is claimed by one worker at a
96
- * time. A scheduler per worker firing on its own clock would run the
97
- * job once per worker.
98
- *
99
- * An existing row keeps its `run_at`, so a restart does not reset the
100
- * clock — and does not run everything the moment a deploy lands.
101
- */
102
- async ensureSchedules(
103
- schedules: Record<string, { everyMs: number; payload?: unknown }>,
104
- ): Promise<void> {
105
- this.schedules.clear();
106
- for (const [name, { everyMs, payload }] of Object.entries(schedules)) {
107
- const id = JobQueue.scheduleId(name);
108
- this.schedules.set(id, everyMs);
109
- const exists = await this.store.query(
110
- `SELECT id FROM ${this.table} WHERE id = ?`,
111
- [id],
112
- );
113
- if (exists.length > 0) continue;
114
- const now = new Date();
115
- try {
116
- await this.store.query(
117
- `INSERT INTO ${this.table}
118
- (id, name, payload, run_at, attempts, max_attempts, created_at)
119
- VALUES (?, ?, ?, ?, 0, ?, ?)`,
120
- // First run one interval from now, not at boot: a deploy
121
- // should not fire every schedule at once.
122
- [id, name, JSON.stringify(payload ?? {}), this.ts(new Date(now.getTime() + everyMs)), 5, this.ts(now)],
123
- );
124
- } catch (e) {
125
- // Another worker inserted it between our SELECT and INSERT.
126
- const raced = await this.store.query(
127
- `SELECT id FROM ${this.table} WHERE id = ?`,
128
- [id],
129
- );
130
- if (raced.length === 0) throw e;
131
- }
132
- }
133
- const ids = [...this.schedules.keys()];
134
- await this.store.query(
135
- ids.length
136
- ? `DELETE FROM ${this.table} WHERE id LIKE 'schedule:%' AND id NOT IN (${ids.map(() => "?").join(", ")})`
137
- : `DELETE FROM ${this.table} WHERE id LIKE 'schedule:%'`,
138
- ids,
139
- );
140
- }
141
-
142
- /**
143
- * Move a recurring job to its next run, clearing its attempts. Used on
144
- * success, and on a failure that has used up its retries: a schedule
145
- * that failed five times still runs next time.
146
- */
147
- async reschedule(id: string, lastError: string | null = null): Promise<void> {
148
- const every = this.schedules.get(id);
149
- if (every === undefined) {
150
- await this.store.query(`DELETE FROM ${this.table} WHERE id = ?`, [id]);
151
- return;
152
- }
153
- await this.store.query(
154
- `UPDATE ${this.table}
155
- SET run_at = ?, attempts = 0, last_error = ?, claimed_at = NULL, claim_token = NULL
156
- WHERE id = ?`,
157
- [this.ts(new Date(Date.now() + every)), lastError?.slice(0, 2000) ?? null, id],
158
- );
159
- }
160
-
161
- /**
162
- * A timestamp in the spelling this dialect accepts.
163
- *
164
- * The obvious thing — pass `Date.toISOString()` and let the driver
165
- * serialise it — is what MariaDB rejects: "Incorrect datetime value:
166
- * '2026-09-27T21:17:22.073Z'". The T and the Z are the problem, not the
167
- * precision.
168
- */
169
- private ts(date: Date): string {
170
- const iso = date.toISOString();
171
- return this.caps.spaceSeparatedTimestamp
172
- ? iso.replace("T", " ").replace("Z", "")
173
- : iso;
174
- }
175
-
176
- async migrate(): Promise<void> {
177
- // SCHEMA names the default table, so a custom `table` option has to be
178
- // substituted here too. It used to be ignored, which produced the
179
- // worst kind of failure: migrate() succeeded, then every query failed
180
- // with "relation does not exist" against a name that looked correct.
181
- const schema = SCHEMA.replaceAll("sigil_jobs", this.table);
182
- for (const stmt of schema.split(";").map((s) => s.trim()).filter(Boolean)) {
183
- try {
184
- await this.store.query(stmt);
185
- } catch {
186
- // Two workers booting together both run CREATE TABLE IF NOT
187
- // EXISTS, and postgres can fail the loser with a duplicate key
188
- // on its own catalog — "IF NOT EXISTS" is checked before the
189
- // insert, not atomically with it. By the time we retry the
190
- // table exists, so the second attempt is a no-op; a real error
191
- // fails again and surfaces.
192
- await new Promise((r) => setTimeout(r, 50 + Math.random() * 100));
193
- await this.store.query(stmt);
194
- }
195
- }
196
- }
197
-
198
- /**
199
- * Add a job.
200
- *
201
- * The id is generated here rather than by the database so a retry of
202
- * the enqueue is recognisable, and so a caller who retries cannot
203
- * accidentally create a second job for the same logical work.
204
- */
205
- async enqueue(
206
- name: string,
207
- payload: unknown = {},
208
- options: EnqueueOptions = {},
209
- ): Promise<string> {
210
- const id = crypto.randomUUID();
211
- const now = new Date();
212
- const runAt = options.runAt ?? now;
213
- await this.store.query(
214
- `INSERT INTO ${this.table}
215
- (id, name, payload, run_at, attempts, max_attempts, created_at)
216
- VALUES (?, ?, ?, ?, 0, ?, ?)`,
217
- [
218
- id,
219
- name,
220
- JSON.stringify(payload ?? {}),
221
- this.ts(runAt),
222
- options.maxAttempts ?? 5,
223
- this.ts(now),
224
- ],
225
- );
226
- return id;
227
- }
228
-
229
- /**
230
- * Atomically take up to `limit` due jobs.
231
- *
232
- * The safety comes from the claim guard, not from row locking: a row is
233
- * only claimable when `claimed_at` is NULL or an old claim, and that
234
- * check happens as part of the write. Two workers issuing this
235
- * simultaneously both read the same candidate ids, but the second one's
236
- * UPDATE matches nothing because the first has already set `claimed_at`.
237
- * So the loser gets an empty set rather than a duplicate job — which is
238
- * the whole requirement.
239
- *
240
- * Which shape that takes depends on the dialect:
241
- *
242
- * - With RETURNING, the ids are chosen and claimed in one statement, so
243
- * there is no window between reading candidates and writing the
244
- * claim.
245
- * - Without it — MariaDB — the candidates are read first and then
246
- * claimed. The window is real but harmless: correctness still comes
247
- * from the `claimed_at` condition inside the UPDATE, so the loser
248
- * updates zero rows and gets an empty batch rather than a duplicate.
249
- * The cost is one extra round trip per claim.
250
- *
251
- * `SKIP LOCKED` is appended only when the store declares it. It changes
252
- * contention behaviour, not correctness.
253
- *
254
- * The returned rows are NOT in run_at order, and cannot be made to be:
255
- * SQL does not define the order of an UPDATE's RETURNING clause. The
256
- * inner ORDER BY decides which `limit` rows are taken, not the order
257
- * they come back. Sort in the caller if order matters.
258
- */
259
- async claim(limit: number, staleMs = 60_000): Promise<JobRow[]> {
260
- const now = this.ts(new Date());
261
- const cutoff = this.ts(new Date(Date.now() - staleMs));
262
- const skip = this.caps.skipLocked ? " FOR UPDATE SKIP LOCKED" : "";
263
- // One token per claim pass, not per row: a single pass is a single
264
- // atomic event from the point of view of "did I get these rows", and
265
- // one token makes the re-read a single equality test.
266
- const token = `c_${crypto.randomUUID()}`;
267
-
268
- // The candidate batch is selected in a derived table rather than a
269
- // plain `WHERE id IN (SELECT ... LIMIT n)` because MariaDB refuses
270
- // the latter outright: "This version of MariaDB doesn't yet support
271
- // 'LIMIT & IN/ALL/ANY/SOME subquery'". A derived table joined on id
272
- // means the same thing and is accepted by all three dialects.
273
- const candidates = `
274
- SELECT id FROM (
275
- SELECT id FROM ${this.table}
276
- WHERE run_at <= ?
277
- AND attempts < max_attempts
278
- AND (claim_token IS NULL OR claimed_at < ?)
279
- ORDER BY run_at
280
- LIMIT ?
281
- ${skip}
282
- ) AS ready`;
283
-
284
- const columns =
285
- "id, name, payload, run_at, attempts, max_attempts, last_error, claimed_at, claim_token, created_at";
286
-
287
- // Claim in one statement. The `claim_token IS NULL OR claimed_at < ?`
288
- // guard is what makes this exclusive: two workers selecting the same
289
- // candidates both issue this UPDATE, and the second one matches
290
- // nothing, because the first has already set claim_token. The loser
291
- // gets an empty batch rather than a duplicate job.
292
- //
293
- // `claim_token` is set to a fresh random value rather than
294
- // claimed_at's own instant, because MySQL truncates TIMESTAMP to whole
295
- // seconds. Two workers claiming in the same second would be
296
- // indistinguishable, the second would match the first's rows, and
297
- // both would run the same job. Measured, not theorised.
298
- await this.store.query(
299
- `UPDATE ${this.table}
300
- SET claimed_at = ?, claim_token = ?, attempts = attempts + 1
301
- WHERE id IN (${candidates})
302
- AND attempts < max_attempts
303
- AND (claim_token IS NULL OR claimed_at < ?)`,
304
- [now, token, now, cutoff, limit, cutoff],
305
- );
306
-
307
- // Read back only the rows this pass won, by token. A dialect without
308
- // RETURNING cannot tell us which ids the UPDATE matched — MariaDB
309
- // returns [] even when it updated two rows — so the token is what
310
- // makes the answer knowable, and it works identically on all three.
311
- return this.store.query<JobRow>(
312
- `SELECT ${columns} FROM ${this.table} WHERE claim_token = ?`,
313
- [token],
314
- );
315
- }
316
-
317
- async complete(id: string): Promise<void> {
318
- if (this.isScheduled(id)) return this.reschedule(id);
319
- await this.store.query(`DELETE FROM ${this.table} WHERE id = ?`, [id]);
320
- }
321
-
322
- /**
323
- * Record a failure.
324
- *
325
- * The row stays, because retry is the point. `claimed_at` is cleared so
326
- * the next pass can take it, and `run_at` is pushed into the future for
327
- * a failed job so a persistently broken handler does not spin — a
328
- * crash-looping job would otherwise burn a worker in a tight loop.
329
- */
330
- async fail(id: string, error: unknown, backoffMs = 30_000): Promise<void> {
331
- const message = error instanceof Error ? error.message : String(error);
332
- const nextRun = this.ts(new Date(Date.now() + backoffMs));
333
- await this.store.query(
334
- `UPDATE ${this.table}
335
- SET last_error = ?, claimed_at = NULL, claim_token = NULL, run_at = ?
336
- WHERE id = ?`,
337
- [message.slice(0, 2000), nextRun, id],
338
- );
339
- }
340
-
341
- /**
342
- * Put a job back on the queue immediately, for manual recovery.
343
- *
344
- * Reports whether the row existed. That used to come from
345
- * `UPDATE ... RETURNING id`, which no dialect other than postgres and
346
- * sqlite has, so a store without RETURNING has to check first. One extra
347
- * query in exchange for an honest return value on every dialect —
348
- * returning `true` unconditionally would tell a caller it had recovered a
349
- * job that does not exist.
350
- */
351
- async retry(id: string): Promise<boolean> {
352
- const found = await this.store.query<{ id: string }>(
353
- `SELECT id FROM ${this.table} WHERE id = ?`,
354
- [id],
355
- );
356
- if (found.length === 0) return false;
357
- await this.store.query(
358
- `UPDATE ${this.table}
359
- SET attempts = 0, last_error = NULL, claimed_at = NULL, claim_token = NULL, run_at = ?
360
- WHERE id = ?`,
361
- [this.ts(new Date()), id],
362
- );
363
- return true;
364
- }
365
-
366
- async list(limit = 20): Promise<JobRow[]> {
367
- return this.store.query<JobRow>(
368
- `SELECT ${"id, name, payload, run_at, attempts, max_attempts, last_error, claimed_at, claim_token, created_at"}
369
- FROM ${this.table}
370
- ORDER BY created_at DESC
371
- LIMIT ?`,
372
- [limit],
373
- );
374
- }
375
-
376
- async stats(): Promise<JobStats> {
377
- const rows = await this.store.query<{ bucket: string; count: number }>(
378
- `SELECT
379
- CASE
380
- WHEN attempts >= max_attempts THEN 'failed'
381
- WHEN claimed_at IS NOT NULL THEN 'claimed'
382
- ELSE 'pending'
383
- END AS bucket,
384
- COUNT(*) AS count
385
- FROM ${this.table}
386
- GROUP BY bucket`,
387
- );
388
- const stats: JobStats = { pending: 0, claimed: 0, failed: 0 };
389
- for (const row of rows) {
390
- if (row.bucket === "failed") stats.failed = Number(row.count);
391
- else if (row.bucket === "claimed") stats.claimed = Number(row.count);
392
- else stats.pending = Number(row.count);
393
- }
394
- return stats;
395
- }
396
- }
1
+ import type {
2
+ Capabilities,
3
+ EnqueueOptions,
4
+ JobRow,
5
+ JobStats,
6
+ JobStore,
7
+ } from "./store.ts";
8
+
9
+ /**
10
+ * Schema statements, kept portable.
11
+ *
12
+ * Deliberately plain: no dialect, no generated columns, no `jsonb`. The
13
+ * payload is TEXT holding JSON rather than a JSON column type, because the
14
+ * json type is spelled differently everywhere and nothing here needs to
15
+ * query inside the payload.
16
+ */
17
+ export const SCHEMA = `
18
+ CREATE TABLE IF NOT EXISTS sigil_jobs (
19
+ -- VARCHAR(64), not TEXT: MySQL refuses to index a TEXT primary key
20
+ -- without a prefix length ("BLOB/TEXT column 'id' used in key
21
+ -- specification without a key length"), so a portable id column has to
22
+ -- be a bounded character type. 36 is a UUID with room to spare, and it
23
+ -- is what the generated ids actually look like.
24
+ id VARCHAR(64) PRIMARY KEY,
25
+ name TEXT NOT NULL,
26
+ payload TEXT NOT NULL,
27
+ -- name is indexed nowhere, so TEXT is fine and keeps long handler
28
+ -- names from being truncated by a column width.
29
+ run_at TIMESTAMP NOT NULL,
30
+ attempts INTEGER NOT NULL DEFAULT 0,
31
+ max_attempts INTEGER NOT NULL DEFAULT 5,
32
+ last_error TEXT,
33
+ claimed_at TIMESTAMP,
34
+ -- Which claim took this row. NOT a timestamp: MySQL truncates TIMESTAMP to
35
+ -- whole seconds, so two workers claiming in the same second are
36
+ -- indistinguishable, and the stale-claim comparison then re-claims a live
37
+ -- row. Measured: a second worker re-claimed rows claimed milliseconds
38
+ -- earlier. A random token per claim is exact on all three dialects.
39
+ claim_token VARCHAR(64),
40
+ created_at TIMESTAMP NOT NULL
41
+ );
42
+ CREATE INDEX IF NOT EXISTS sigil_jobs_ready ON sigil_jobs (run_at);
43
+ `;
44
+
45
+ /**
46
+ * A durable queue over any client that can run a query and return rows.
47
+ *
48
+ * Delivery is at-least-once, and that is not a caveat to be apologetic
49
+ * about — it is the guarantee being bought. A worker can die between doing
50
+ * the side effect and deleting the row, so a handler must be idempotent.
51
+ * The alternative is exactly-once, which in practice means transactions
52
+ * held open across the entire handler, including every HTTP call inside it.
53
+ */
54
+ export class JobQueue {
55
+ /** Recurring jobs: row id → interval. Set by `ensureSchedules`. */
56
+ private readonly schedules = new Map<string, number>();
57
+
58
+ constructor(
59
+ private readonly store: JobStore,
60
+ private readonly table: string = "sigil_jobs",
61
+ ) {}
62
+
63
+ /**
64
+ * Every capability defaults to false. A store that declares nothing gets
65
+ * the weakest path, which is correct on every dialect rather than correct
66
+ * on the one it was written for.
67
+ *
68
+ * Read on use rather than at construction: a store over a database that
69
+ * opens later only knows its dialect once it is open.
70
+ */
71
+ private get caps(): Required<Capabilities> {
72
+ return {
73
+ skipLocked: this.store.capabilities?.skipLocked ?? false,
74
+ spaceSeparatedTimestamp:
75
+ this.store.capabilities?.spaceSeparatedTimestamp ?? false,
76
+ };
77
+ }
78
+
79
+ /** The row id a schedule lives under. */
80
+ static scheduleId(name: string): string {
81
+ return `schedule:${name}`;
82
+ }
83
+
84
+ /** Whether a job is a recurring one, rescheduled rather than deleted. */
85
+ isScheduled(id: string): boolean {
86
+ return this.schedules.has(id);
87
+ }
88
+
89
+ /**
90
+ * Make the recurring jobs exist, one row each, and remove the rows of
91
+ * schedules that are no longer configured.
92
+ *
93
+ * One row per schedule, rescheduled on completion, is what makes this
94
+ * safe with several workers: every worker runs this at boot, but a
95
+ * primary key admits one row, and a row is claimed by one worker at a
96
+ * time. A scheduler per worker firing on its own clock would run the
97
+ * job once per worker.
98
+ *
99
+ * An existing row keeps its `run_at`, so a restart does not reset the
100
+ * clock — and does not run everything the moment a deploy lands.
101
+ */
102
+ async ensureSchedules(
103
+ schedules: Record<string, { everyMs: number; payload?: unknown }>,
104
+ ): Promise<void> {
105
+ this.schedules.clear();
106
+ for (const [name, { everyMs, payload }] of Object.entries(schedules)) {
107
+ const id = JobQueue.scheduleId(name);
108
+ this.schedules.set(id, everyMs);
109
+ const exists = await this.store.query(
110
+ `SELECT id FROM ${this.table} WHERE id = ?`,
111
+ [id],
112
+ );
113
+ if (exists.length > 0) continue;
114
+ const now = new Date();
115
+ try {
116
+ await this.store.query(
117
+ `INSERT INTO ${this.table}
118
+ (id, name, payload, run_at, attempts, max_attempts, created_at)
119
+ VALUES (?, ?, ?, ?, 0, ?, ?)`,
120
+ // First run one interval from now, not at boot: a deploy
121
+ // should not fire every schedule at once.
122
+ [id, name, JSON.stringify(payload ?? {}), this.ts(new Date(now.getTime() + everyMs)), 5, this.ts(now)],
123
+ );
124
+ } catch (e) {
125
+ // Another worker inserted it between our SELECT and INSERT.
126
+ const raced = await this.store.query(
127
+ `SELECT id FROM ${this.table} WHERE id = ?`,
128
+ [id],
129
+ );
130
+ if (raced.length === 0) throw e;
131
+ }
132
+ }
133
+ const ids = [...this.schedules.keys()];
134
+ await this.store.query(
135
+ ids.length
136
+ ? `DELETE FROM ${this.table} WHERE id LIKE 'schedule:%' AND id NOT IN (${ids.map(() => "?").join(", ")})`
137
+ : `DELETE FROM ${this.table} WHERE id LIKE 'schedule:%'`,
138
+ ids,
139
+ );
140
+ }
141
+
142
+ /**
143
+ * Move a recurring job to its next run, clearing its attempts. Used on
144
+ * success, and on a failure that has used up its retries: a schedule
145
+ * that failed five times still runs next time.
146
+ */
147
+ async reschedule(id: string, lastError: string | null = null): Promise<void> {
148
+ const every = this.schedules.get(id);
149
+ if (every === undefined) {
150
+ await this.store.query(`DELETE FROM ${this.table} WHERE id = ?`, [id]);
151
+ return;
152
+ }
153
+ await this.store.query(
154
+ `UPDATE ${this.table}
155
+ SET run_at = ?, attempts = 0, last_error = ?, claimed_at = NULL, claim_token = NULL
156
+ WHERE id = ?`,
157
+ [this.ts(new Date(Date.now() + every)), lastError?.slice(0, 2000) ?? null, id],
158
+ );
159
+ }
160
+
161
+ /**
162
+ * A timestamp in the spelling this dialect accepts.
163
+ *
164
+ * The obvious thing — pass `Date.toISOString()` and let the driver
165
+ * serialise it — is what MariaDB rejects: "Incorrect datetime value:
166
+ * '2026-09-27T21:17:22.073Z'". The T and the Z are the problem, not the
167
+ * precision.
168
+ */
169
+ private ts(date: Date): string {
170
+ const iso = date.toISOString();
171
+ return this.caps.spaceSeparatedTimestamp
172
+ ? iso.replace("T", " ").replace("Z", "")
173
+ : iso;
174
+ }
175
+
176
+ async migrate(): Promise<void> {
177
+ // SCHEMA names the default table, so a custom `table` option has to be
178
+ // substituted here too. It used to be ignored, which produced the
179
+ // worst kind of failure: migrate() succeeded, then every query failed
180
+ // with "relation does not exist" against a name that looked correct.
181
+ const schema = SCHEMA.replaceAll("sigil_jobs", this.table);
182
+ for (const stmt of schema.split(";").map((s) => s.trim()).filter(Boolean)) {
183
+ try {
184
+ await this.store.query(stmt);
185
+ } catch {
186
+ // Two workers booting together both run CREATE TABLE IF NOT
187
+ // EXISTS, and postgres can fail the loser with a duplicate key
188
+ // on its own catalog — "IF NOT EXISTS" is checked before the
189
+ // insert, not atomically with it. By the time we retry the
190
+ // table exists, so the second attempt is a no-op; a real error
191
+ // fails again and surfaces.
192
+ await new Promise((r) => setTimeout(r, 50 + Math.random() * 100));
193
+ await this.store.query(stmt);
194
+ }
195
+ }
196
+ }
197
+
198
+ /**
199
+ * Add a job.
200
+ *
201
+ * The id is generated here rather than by the database so a retry of
202
+ * the enqueue is recognisable, and so a caller who retries cannot
203
+ * accidentally create a second job for the same logical work.
204
+ */
205
+ async enqueue(
206
+ name: string,
207
+ payload: unknown = {},
208
+ options: EnqueueOptions = {},
209
+ ): Promise<string> {
210
+ const id = crypto.randomUUID();
211
+ const now = new Date();
212
+ const runAt = options.runAt ?? now;
213
+ await this.store.query(
214
+ `INSERT INTO ${this.table}
215
+ (id, name, payload, run_at, attempts, max_attempts, created_at)
216
+ VALUES (?, ?, ?, ?, 0, ?, ?)`,
217
+ [
218
+ id,
219
+ name,
220
+ JSON.stringify(payload ?? {}),
221
+ this.ts(runAt),
222
+ options.maxAttempts ?? 5,
223
+ this.ts(now),
224
+ ],
225
+ );
226
+ return id;
227
+ }
228
+
229
+ /**
230
+ * Atomically take up to `limit` due jobs.
231
+ *
232
+ * The safety comes from the claim guard, not from row locking: a row is
233
+ * only claimable when `claimed_at` is NULL or an old claim, and that
234
+ * check happens as part of the write. Two workers issuing this
235
+ * simultaneously both read the same candidate ids, but the second one's
236
+ * UPDATE matches nothing because the first has already set `claimed_at`.
237
+ * So the loser gets an empty set rather than a duplicate job — which is
238
+ * the whole requirement.
239
+ *
240
+ * Which shape that takes depends on the dialect:
241
+ *
242
+ * - With RETURNING, the ids are chosen and claimed in one statement, so
243
+ * there is no window between reading candidates and writing the
244
+ * claim.
245
+ * - Without it — MariaDB — the candidates are read first and then
246
+ * claimed. The window is real but harmless: correctness still comes
247
+ * from the `claimed_at` condition inside the UPDATE, so the loser
248
+ * updates zero rows and gets an empty batch rather than a duplicate.
249
+ * The cost is one extra round trip per claim.
250
+ *
251
+ * `SKIP LOCKED` is appended only when the store declares it. It changes
252
+ * contention behaviour, not correctness.
253
+ *
254
+ * The returned rows are NOT in run_at order, and cannot be made to be:
255
+ * SQL does not define the order of an UPDATE's RETURNING clause. The
256
+ * inner ORDER BY decides which `limit` rows are taken, not the order
257
+ * they come back. Sort in the caller if order matters.
258
+ */
259
+ async claim(limit: number, staleMs = 60_000): Promise<JobRow[]> {
260
+ const now = this.ts(new Date());
261
+ const cutoff = this.ts(new Date(Date.now() - staleMs));
262
+ const skip = this.caps.skipLocked ? " FOR UPDATE SKIP LOCKED" : "";
263
+ // One token per claim pass, not per row: a single pass is a single
264
+ // atomic event from the point of view of "did I get these rows", and
265
+ // one token makes the re-read a single equality test.
266
+ const token = `c_${crypto.randomUUID()}`;
267
+
268
+ // The candidate batch is selected in a derived table rather than a
269
+ // plain `WHERE id IN (SELECT ... LIMIT n)` because MariaDB refuses
270
+ // the latter outright: "This version of MariaDB doesn't yet support
271
+ // 'LIMIT & IN/ALL/ANY/SOME subquery'". A derived table joined on id
272
+ // means the same thing and is accepted by all three dialects.
273
+ const candidates = `
274
+ SELECT id FROM (
275
+ SELECT id FROM ${this.table}
276
+ WHERE run_at <= ?
277
+ AND attempts < max_attempts
278
+ AND (claim_token IS NULL OR claimed_at < ?)
279
+ ORDER BY run_at
280
+ LIMIT ?
281
+ ${skip}
282
+ ) AS ready`;
283
+
284
+ const columns =
285
+ "id, name, payload, run_at, attempts, max_attempts, last_error, claimed_at, claim_token, created_at";
286
+
287
+ // Claim in one statement. The `claim_token IS NULL OR claimed_at < ?`
288
+ // guard is what makes this exclusive: two workers selecting the same
289
+ // candidates both issue this UPDATE, and the second one matches
290
+ // nothing, because the first has already set claim_token. The loser
291
+ // gets an empty batch rather than a duplicate job.
292
+ //
293
+ // `claim_token` is set to a fresh random value rather than
294
+ // claimed_at's own instant, because MySQL truncates TIMESTAMP to whole
295
+ // seconds. Two workers claiming in the same second would be
296
+ // indistinguishable, the second would match the first's rows, and
297
+ // both would run the same job. Measured, not theorised.
298
+ await this.store.query(
299
+ `UPDATE ${this.table}
300
+ SET claimed_at = ?, claim_token = ?, attempts = attempts + 1
301
+ WHERE id IN (${candidates})
302
+ AND attempts < max_attempts
303
+ AND (claim_token IS NULL OR claimed_at < ?)`,
304
+ [now, token, now, cutoff, limit, cutoff],
305
+ );
306
+
307
+ // Read back only the rows this pass won, by token. A dialect without
308
+ // RETURNING cannot tell us which ids the UPDATE matched — MariaDB
309
+ // returns [] even when it updated two rows — so the token is what
310
+ // makes the answer knowable, and it works identically on all three.
311
+ return this.store.query<JobRow>(
312
+ `SELECT ${columns} FROM ${this.table} WHERE claim_token = ?`,
313
+ [token],
314
+ );
315
+ }
316
+
317
+ async complete(id: string): Promise<void> {
318
+ if (this.isScheduled(id)) return this.reschedule(id);
319
+ await this.store.query(`DELETE FROM ${this.table} WHERE id = ?`, [id]);
320
+ }
321
+
322
+ /**
323
+ * Record a failure.
324
+ *
325
+ * The row stays, because retry is the point. `claimed_at` is cleared so
326
+ * the next pass can take it, and `run_at` is pushed into the future for
327
+ * a failed job so a persistently broken handler does not spin — a
328
+ * crash-looping job would otherwise burn a worker in a tight loop.
329
+ */
330
+ async fail(id: string, error: unknown, backoffMs = 30_000): Promise<void> {
331
+ const message = error instanceof Error ? error.message : String(error);
332
+ const nextRun = this.ts(new Date(Date.now() + backoffMs));
333
+ await this.store.query(
334
+ `UPDATE ${this.table}
335
+ SET last_error = ?, claimed_at = NULL, claim_token = NULL, run_at = ?
336
+ WHERE id = ?`,
337
+ [message.slice(0, 2000), nextRun, id],
338
+ );
339
+ }
340
+
341
+ /**
342
+ * Put a job back on the queue immediately, for manual recovery.
343
+ *
344
+ * Reports whether the row existed. That used to come from
345
+ * `UPDATE ... RETURNING id`, which no dialect other than postgres and
346
+ * sqlite has, so a store without RETURNING has to check first. One extra
347
+ * query in exchange for an honest return value on every dialect —
348
+ * returning `true` unconditionally would tell a caller it had recovered a
349
+ * job that does not exist.
350
+ */
351
+ async retry(id: string): Promise<boolean> {
352
+ const found = await this.store.query<{ id: string }>(
353
+ `SELECT id FROM ${this.table} WHERE id = ?`,
354
+ [id],
355
+ );
356
+ if (found.length === 0) return false;
357
+ await this.store.query(
358
+ `UPDATE ${this.table}
359
+ SET attempts = 0, last_error = NULL, claimed_at = NULL, claim_token = NULL, run_at = ?
360
+ WHERE id = ?`,
361
+ [this.ts(new Date()), id],
362
+ );
363
+ return true;
364
+ }
365
+
366
+ async list(limit = 20): Promise<JobRow[]> {
367
+ return this.store.query<JobRow>(
368
+ `SELECT ${"id, name, payload, run_at, attempts, max_attempts, last_error, claimed_at, claim_token, created_at"}
369
+ FROM ${this.table}
370
+ ORDER BY created_at DESC
371
+ LIMIT ?`,
372
+ [limit],
373
+ );
374
+ }
375
+
376
+ async stats(): Promise<JobStats> {
377
+ const rows = await this.store.query<{ bucket: string; count: number }>(
378
+ `SELECT
379
+ CASE
380
+ WHEN attempts >= max_attempts THEN 'failed'
381
+ WHEN claimed_at IS NOT NULL THEN 'claimed'
382
+ ELSE 'pending'
383
+ END AS bucket,
384
+ COUNT(*) AS count
385
+ FROM ${this.table}
386
+ GROUP BY bucket`,
387
+ );
388
+ const stats: JobStats = { pending: 0, claimed: 0, failed: 0 };
389
+ for (const row of rows) {
390
+ if (row.bucket === "failed") stats.failed = Number(row.count);
391
+ else if (row.bucket === "claimed") stats.claimed = Number(row.count);
392
+ else stats.pending = Number(row.count);
393
+ }
394
+ return stats;
395
+ }
396
+ }