@portqueue/core 1.0.3 → 1.1.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 (64) hide show
  1. package/dist/conformance/index.cjs +70 -1
  2. package/dist/conformance/index.cjs.map +1 -1
  3. package/dist/conformance/index.d.ts +4 -2
  4. package/dist/conformance/index.mjs +70 -1
  5. package/dist/conformance/index.mjs.map +1 -1
  6. package/dist/constants/job.constants.d.ts +3 -1
  7. package/dist/constants/storage.constants.d.ts +8 -0
  8. package/dist/constants/time.constants.d.ts +13 -0
  9. package/dist/constants/worker.constants.d.ts +5 -0
  10. package/dist/drivers/driver.interface.d.ts +47 -0
  11. package/dist/drivers/mysql/index.cjs +169 -76
  12. package/dist/drivers/mysql/index.cjs.map +1 -1
  13. package/dist/drivers/mysql/index.mjs +169 -76
  14. package/dist/drivers/mysql/index.mjs.map +1 -1
  15. package/dist/drivers/mysql/mysql-driver.d.ts +42 -19
  16. package/dist/drivers/oracle/index.cjs +144 -65
  17. package/dist/drivers/oracle/index.cjs.map +1 -1
  18. package/dist/drivers/oracle/index.mjs +144 -65
  19. package/dist/drivers/oracle/index.mjs.map +1 -1
  20. package/dist/drivers/oracle/oracle-driver.d.ts +34 -15
  21. package/dist/drivers/pglite/index.cjs +3 -3
  22. package/dist/drivers/pglite/index.mjs +3 -3
  23. package/dist/drivers/postgresql/index.cjs +1 -1
  24. package/dist/drivers/postgresql/index.mjs +1 -1
  25. package/dist/drivers/postgresql/postgresql-driver.d.ts +33 -7
  26. package/dist/drivers/shared/base-driver.d.ts +2 -0
  27. package/dist/drivers/shared/migration-runner.service.d.ts +19 -4
  28. package/dist/drivers/shared/migration.d.ts +5 -3
  29. package/dist/drivers/sqlite/index.cjs +113 -42
  30. package/dist/drivers/sqlite/index.cjs.map +1 -1
  31. package/dist/drivers/sqlite/index.mjs +113 -42
  32. package/dist/drivers/sqlite/index.mjs.map +1 -1
  33. package/dist/drivers/sqlite/sqlite-driver.d.ts +26 -0
  34. package/dist/drivers/table-names.d.ts +3 -2
  35. package/dist/index.cjs +519 -316
  36. package/dist/index.cjs.map +1 -1
  37. package/dist/index.d.ts +2 -2
  38. package/dist/index.mjs +521 -318
  39. package/dist/index.mjs.map +1 -1
  40. package/dist/{migration-D73ANkYV.js → migration-D0IRP2oq.js} +6 -2
  41. package/dist/migration-D0IRP2oq.js.map +1 -0
  42. package/dist/{migration-CoTjpgBl.cjs → migration-Dx8eUthW.cjs} +6 -2
  43. package/dist/migration-Dx8eUthW.cjs.map +1 -0
  44. package/dist/monitoring/system-monitor.service.d.ts +6 -5
  45. package/dist/options/enums.d.ts +22 -0
  46. package/dist/options/job-options.d.ts +2 -1
  47. package/dist/port-queue.d.ts +76 -4
  48. package/dist/{postgresql-driver-BUHuyRYj.js → postgresql-driver-CPHv5SUT.js} +128 -55
  49. package/dist/postgresql-driver-CPHv5SUT.js.map +1 -0
  50. package/dist/{postgresql-driver-CIk94XCq.cjs → postgresql-driver-DRT68TKb.cjs} +128 -55
  51. package/dist/postgresql-driver-DRT68TKb.cjs.map +1 -0
  52. package/dist/producer/producer.service.d.ts +12 -0
  53. package/dist/producer/results.d.ts +35 -1
  54. package/dist/{storage.constants-B5oQjxp5.cjs → storage.constants-BKeXcSQe.cjs} +13 -1
  55. package/dist/storage.constants-BKeXcSQe.cjs.map +1 -0
  56. package/dist/{storage.constants-DwSzjjMZ.js → storage.constants-DYEQUmc8.js} +14 -2
  57. package/dist/storage.constants-DYEQUmc8.js.map +1 -0
  58. package/package.json +1 -1
  59. package/dist/migration-CoTjpgBl.cjs.map +0 -1
  60. package/dist/migration-D73ANkYV.js.map +0 -1
  61. package/dist/postgresql-driver-BUHuyRYj.js.map +0 -1
  62. package/dist/postgresql-driver-CIk94XCq.cjs.map +0 -1
  63. package/dist/storage.constants-B5oQjxp5.cjs.map +0 -1
  64. package/dist/storage.constants-DwSzjjMZ.js.map +0 -1
package/dist/index.cjs CHANGED
@@ -1,12 +1,13 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
3
- const storage_constants = require("./storage.constants-B5oQjxp5.cjs");
4
- const migration = require("./migration-CoTjpgBl.cjs");
3
+ const storage_constants = require("./storage.constants-BKeXcSQe.cjs");
4
+ const migration = require("./migration-Dx8eUthW.cjs");
5
5
  const cronParser = require("cron-parser");
6
6
  const node_os = require("node:os");
7
7
  const node_perf_hooks = require("node:perf_hooks");
8
8
  const node_process = require("node:process");
9
9
  const node_v8 = require("node:v8");
10
+ const DEFAULT_CRON_TIMEZONE = "UTC";
10
11
  const DEFAULT_TICK_INTERVAL_SECONDS = 5;
11
12
  const MIN_SUBSCRIBER_POLL_SECONDS = 5;
12
13
  const DEFAULT_HEARTBEAT_INTERVAL_SECONDS = 15;
@@ -16,6 +17,8 @@ const DEFAULT_SHUTDOWN_TIMEOUT_SECONDS = 30;
16
17
  const DEFAULT_SAMPLE_INTERVAL_SECONDS = 2;
17
18
  const MIGRATION_WAIT_TIMEOUT_SECONDS = 30;
18
19
  const MICROS_PER_MS = 1e3;
20
+ const NANOS_PER_MS = 1e6;
21
+ const EVENT_LOOP_HISTOGRAM_RESOLUTION_SECONDS = 0.02;
19
22
  const MIGRATION_WAIT_POLL_SECONDS = 0.2;
20
23
  const DEFAULT_CONCURRENCY = 1;
21
24
  const DEFAULT_POLL_INTERVAL_SECONDS = 5;
@@ -25,6 +28,8 @@ const MIN_LOCK_HEARTBEAT_SECONDS = 1;
25
28
  const DRAIN_POLL_SECONDS = 0.025;
26
29
  const ABORT_GRACE_SECONDS = 0.25;
27
30
  const LOCK_RELEASE_SECONDS = -1;
31
+ const DEFAULT_SHUTDOWN_GRACEFUL = true;
32
+ const DEFAULT_PAUSE_MODE = storage_constants.PauseMode.PROCESSING;
28
33
  const DEFAULT_PAGE_LIMIT = 50;
29
34
  const MAX_PAGE_LIMIT = 500;
30
35
  const DASHBOARD_MAX_PAGE_LIMIT = 200;
@@ -37,6 +42,7 @@ const MAINTENANCE_MAX_BATCHES = 20;
37
42
  const DEFAULT_PRIORITY = 0;
38
43
  const DEFAULT_RETRY_MAX_ATTEMPTS = 1;
39
44
  const DEFAULT_RETRY_DELAY_SECONDS = 0;
45
+ const DEFAULT_BACKOFF_STRATEGY = storage_constants.BackoffStrategy.FIXED;
40
46
  const DEFAULT_BACKOFF_FACTOR = 2;
41
47
  const DEFAULT_FAILURE_DETAIL = storage_constants.FailureDetail.STACK;
42
48
  const FAILURE_MESSAGE_MAX_CHARS = 4e3;
@@ -297,7 +303,7 @@ class OptionResolver {
297
303
  expireAt,
298
304
  retryMaxAttempts: merged.retry?.maxAttempts ?? DEFAULT_RETRY_MAX_ATTEMPTS,
299
305
  retryDelaySeconds: merged.retry?.delaySeconds != null ? migration.wholeSeconds(merged.retry.delaySeconds, "retry.delaySeconds") : DEFAULT_RETRY_DELAY_SECONDS,
300
- retryBackoff: backoff?.strategy ?? storage_constants.BackoffStrategy.FIXED,
306
+ retryBackoff: backoff?.strategy ?? DEFAULT_BACKOFF_STRATEGY,
301
307
  retryBackoffFactor: backoff?.factor ?? null,
302
308
  retryMaxDelaySeconds: backoff?.maxDelaySeconds != null ? migration.wholeSeconds(backoff.maxDelaySeconds, "retry.backoff.maxDelaySeconds") : null,
303
309
  retryJitter: backoff?.jitter ?? false,
@@ -467,8 +473,11 @@ class QueueRegistry {
467
473
  );
468
474
  if (!stale.size) return;
469
475
  try {
470
- const rows = await this.driver.listQueues();
471
- for (const row of rows) if (stale.has(row.name)) this.update(row);
476
+ const names = [...stale];
477
+ for (let i = 0; i < names.length; i += storage_constants.MAX_BATCH_IDS) {
478
+ const rows = await this.driver.listQueues({ names: names.slice(i, i + storage_constants.MAX_BATCH_IDS) });
479
+ for (const row of rows) this.update(row);
480
+ }
472
481
  } catch {
473
482
  }
474
483
  }
@@ -503,8 +512,176 @@ class NotifierService {
503
512
  }
504
513
  }
505
514
  }
515
+ const d = (ms) => ms == null ? null : new Date(ms);
516
+ function toSnapshot(record, queueName, now) {
517
+ const stalled = record.status === storage_constants.JobStatus.ACTIVE && record.lockedUntil != null && record.lockedUntil < now;
518
+ return {
519
+ id: record.id,
520
+ queue: queueName,
521
+ status: record.status,
522
+ data: record.data,
523
+ returnValue: record.returnValue,
524
+ priority: record.priority,
525
+ retryAttempt: record.retryAttempt,
526
+ retryMaxAttempts: record.retryMaxAttempts,
527
+ createdAt: new Date(record.createdAt),
528
+ updatedAt: new Date(record.updatedAt),
529
+ startAfter: new Date(record.startAfter),
530
+ startedAt: d(record.startedAt),
531
+ completedAt: d(record.completedAt),
532
+ failedAt: d(record.failedAt),
533
+ cancelledAt: d(record.cancelledAt),
534
+ expiredAt: d(record.expiredAt),
535
+ retriedAt: d(record.retriedAt),
536
+ stalledAt: d(record.stalledAt),
537
+ lockedUntil: d(record.lockedUntil),
538
+ preferredInstanceKeyPattern: record.preferredInstanceKeyPattern,
539
+ processedOnInstanceKey: record.processedOnInstanceKey,
540
+ failureMessage: record.failureMessage,
541
+ idempotencyKey: record.idempotencyKey,
542
+ scheduleId: record.scheduleId,
543
+ stalled
544
+ };
545
+ }
546
+ function instanceStaleAfterMs(options) {
547
+ const beatSeconds = options.instance?.heartbeatIntervalSeconds ?? DEFAULT_HEARTBEAT_INTERVAL_SECONDS;
548
+ return migration.secondsToMs(beatSeconds * HEARTBEAT_STALE_BEATS, "instance.heartbeatIntervalSeconds");
549
+ }
550
+ function toInstanceInfo(row, counts, seenSince) {
551
+ return {
552
+ instanceKey: row.instanceKey,
553
+ processingPaused: row.processingPaused,
554
+ alive: row.lastSeenAt >= seenSince,
555
+ createdAt: new Date(row.createdAt),
556
+ updatedAt: new Date(row.updatedAt),
557
+ lastSeenAt: new Date(row.lastSeenAt),
558
+ cpuPercent: row.cpuPercent,
559
+ memoryPercent: row.memoryPercent,
560
+ counts: counts ?? storage_constants.emptyStatusCounts()
561
+ };
562
+ }
563
+ function toQueueInfo(row, counts, inUse) {
564
+ return {
565
+ name: row.name,
566
+ processingPaused: row.processingPaused,
567
+ acceptingPaused: row.acceptingPaused,
568
+ counts: counts ?? storage_constants.emptyStatusCounts(),
569
+ inUse
570
+ };
571
+ }
572
+ function pageWindow(query, maxLimit = MAX_PAGE_LIMIT) {
573
+ return {
574
+ limit: Math.min(Math.max(Math.trunc(query.limit ?? DEFAULT_PAGE_LIMIT), 1), maxLimit),
575
+ offset: Math.max(Math.trunc(query.offset ?? 0), 0)
576
+ };
577
+ }
578
+ class ReadService {
579
+ constructor(runtime) {
580
+ this.runtime = runtime;
581
+ }
582
+ async getJob(jobId) {
583
+ const record = await this.runtime.driver.getJob({ jobId });
584
+ if (!record) return null;
585
+ return toSnapshot(record, record.queueName, this.runtime.clock.now());
586
+ }
587
+ /**
588
+ * A page of jobs, newest first.
589
+ *
590
+ * `instanceKey` and `search` are not part of the public `GetJobsQuery` — they are here for the
591
+ * dashboard facade, whose instance detail view reads jobs by the instance that claimed them and
592
+ * whose table offers a free-text filter. Both are pushed into SQL, so a search pages in the
593
+ * database rather than streaming the table into this process.
594
+ */
595
+ async getJobs(query) {
596
+ const { limit, offset } = pageWindow(query);
597
+ const filter = {
598
+ ...query.queue ? { queueName: query.queue } : {},
599
+ ...query.statuses ? { statuses: query.statuses } : {},
600
+ ...query.scheduleId ? { scheduleId: query.scheduleId } : {},
601
+ ...query.instanceKey ? { processedOnInstanceKey: query.instanceKey } : {},
602
+ ...query.search ? { search: query.search } : {}
603
+ };
604
+ const [records, total] = await Promise.all([
605
+ this.runtime.driver.getJobs({ ...filter, limit, offset }),
606
+ this.runtime.driver.countJobs(filter)
607
+ ]);
608
+ const now = this.runtime.clock.now();
609
+ return { items: records.map((r) => toSnapshot(r, r.queueName, now)), total };
610
+ }
611
+ async getQueueStats(queue) {
612
+ const counts = await this.runtime.driver.countJobsByStatus(queue ? { queueName: queue } : {});
613
+ return { ...queue ? { queue } : {}, counts };
614
+ }
615
+ /**
616
+ * A page of queues with their per-status counts, plus the total across every page. Same
617
+ * `limit`/`offset` window as the job, schedule and instance reads.
618
+ */
619
+ async getQueues(query = {}) {
620
+ const { limit, offset } = pageWindow(query);
621
+ const filter = {
622
+ ...query.search ? { search: query.search } : {},
623
+ ...query.processingPaused !== void 0 ? { processingPaused: query.processingPaused } : {}
624
+ };
625
+ const [rows, total] = await Promise.all([
626
+ this.runtime.driver.listQueues({ ...filter, limit, offset }),
627
+ this.runtime.driver.countQueues(filter)
628
+ ]);
629
+ if (!rows.length) return { items: [], total };
630
+ const counts = await this.runtime.driver.countJobsByStatusPerQueue({
631
+ queueNames: rows.map((r) => r.name)
632
+ });
633
+ return {
634
+ items: rows.map(
635
+ (row) => toQueueInfo(row, counts[row.name], this.runtime.registry.isRegistered(row.name))
636
+ ),
637
+ total
638
+ };
639
+ }
640
+ /** One queue by name, with the same counts and `inUse` flag the list carries. Null if unknown. */
641
+ async getQueue(name) {
642
+ const row = await this.runtime.driver.getQueueByName({ name });
643
+ if (!row) return null;
644
+ const counts = await this.runtime.driver.countJobsByStatusPerQueue({ queueNames: [row.name] });
645
+ return toQueueInfo(row, counts[row.name], this.runtime.registry.isRegistered(row.name));
646
+ }
647
+ /**
648
+ * A page of instances with liveness and per-instance job attribution, plus the total across
649
+ * every page. Same `limit`/`offset` window as the job and schedule reads.
650
+ */
651
+ async getInstances(query = {}) {
652
+ const { limit, offset } = pageWindow(query);
653
+ const seenSince = this.runtime.clock.now() - instanceStaleAfterMs(this.runtime.options);
654
+ const filter = {
655
+ ...query.search ? { search: query.search } : {},
656
+ ...query.processingPaused !== void 0 ? { processingPaused: query.processingPaused } : {},
657
+ ...query.alive !== void 0 ? { alive: query.alive, seenSince } : {}
658
+ };
659
+ const [rows, total] = await Promise.all([
660
+ this.runtime.driver.listInstances({ ...filter, limit, offset }),
661
+ this.runtime.driver.countInstances(filter)
662
+ ]);
663
+ if (!rows.length) return { items: [], total };
664
+ const counts = await this.runtime.driver.countJobsByStatusPerInstance({
665
+ instanceKeys: rows.map((r) => r.instanceKey)
666
+ });
667
+ return {
668
+ items: rows.map((row) => toInstanceInfo(row, counts[row.instanceKey], seenSince)),
669
+ total
670
+ };
671
+ }
672
+ /** One instance by key, with the same liveness, health and attribution the list carries. */
673
+ async getInstance(instanceKey) {
674
+ const row = await this.runtime.driver.getInstance({ instanceKey });
675
+ if (!row) return null;
676
+ const seenSince = this.runtime.clock.now() - instanceStaleAfterMs(this.runtime.options);
677
+ const counts = await this.runtime.driver.countJobsByStatusPerInstance({
678
+ instanceKeys: [row.instanceKey]
679
+ });
680
+ return toInstanceInfo(row, counts[row.instanceKey], seenSince);
681
+ }
682
+ }
506
683
  class CronExpression {
507
- constructor(expression, timezone = "UTC") {
684
+ constructor(expression, timezone = DEFAULT_CRON_TIMEZONE) {
508
685
  this.expression = expression;
509
686
  this.timezone = timezone;
510
687
  try {
@@ -891,11 +1068,7 @@ class ProducerService {
891
1068
  * listing the schedules of a name that was never used does not create it.
892
1069
  */
893
1070
  async getSchedules(query = {}) {
894
- const limit = Math.min(
895
- Math.max(Math.trunc(query.limit ?? DEFAULT_PAGE_LIMIT), 1),
896
- MAX_PAGE_LIMIT
897
- );
898
- const offset = Math.max(Math.trunc(query.offset ?? 0), 0);
1071
+ const { limit, offset } = pageWindow(query);
899
1072
  const filter = {
900
1073
  ...query.queue ? { queueName: query.queue } : {},
901
1074
  ...query.enabled !== void 0 ? { enabled: query.enabled } : {}
@@ -904,7 +1077,7 @@ class ProducerService {
904
1077
  this.runtime.driver.listSchedules({ ...filter, limit, offset }),
905
1078
  this.runtime.driver.countSchedules(filter)
906
1079
  ]);
907
- return { items: rows.map((s) => toScheduleInfo(s)), total };
1080
+ return { items: rows.map(toScheduleInfo), total };
908
1081
  }
909
1082
  /** One schedule by id, or null when no schedule has that id. */
910
1083
  async getSchedule(scheduleId) {
@@ -926,179 +1099,8 @@ function toScheduleInfo(s) {
926
1099
  };
927
1100
  }
928
1101
  function normalizeCron(cron) {
929
- if (typeof cron === "string") return { pattern: cron, tz: "UTC" };
930
- return { pattern: cron.pattern, tz: cron.tz ?? "UTC" };
931
- }
932
- const d = (ms) => ms == null ? null : new Date(ms);
933
- function toSnapshot(record, queueName, now) {
934
- const stalled = record.status === storage_constants.JobStatus.ACTIVE && record.lockedUntil != null && record.lockedUntil < now;
935
- return {
936
- id: record.id,
937
- queue: queueName,
938
- status: record.status,
939
- data: record.data,
940
- returnValue: record.returnValue,
941
- priority: record.priority,
942
- retryAttempt: record.retryAttempt,
943
- retryMaxAttempts: record.retryMaxAttempts,
944
- createdAt: new Date(record.createdAt),
945
- updatedAt: new Date(record.updatedAt),
946
- startAfter: new Date(record.startAfter),
947
- startedAt: d(record.startedAt),
948
- completedAt: d(record.completedAt),
949
- failedAt: d(record.failedAt),
950
- cancelledAt: d(record.cancelledAt),
951
- expiredAt: d(record.expiredAt),
952
- retriedAt: d(record.retriedAt),
953
- stalledAt: d(record.stalledAt),
954
- lockedUntil: d(record.lockedUntil),
955
- preferredInstanceKeyPattern: record.preferredInstanceKeyPattern,
956
- processedOnInstanceKey: record.processedOnInstanceKey,
957
- failureMessage: record.failureMessage,
958
- idempotencyKey: record.idempotencyKey,
959
- scheduleId: record.scheduleId,
960
- stalled
961
- };
962
- }
963
- function instanceStaleAfterMs(options) {
964
- const beatSeconds = options.instance?.heartbeatIntervalSeconds ?? DEFAULT_HEARTBEAT_INTERVAL_SECONDS;
965
- return migration.secondsToMs(beatSeconds * HEARTBEAT_STALE_BEATS, "instance.heartbeatIntervalSeconds");
966
- }
967
- function toInstanceInfo(row, counts, seenSince) {
968
- return {
969
- instanceKey: row.instanceKey,
970
- processingPaused: row.processingPaused,
971
- alive: row.lastSeenAt >= seenSince,
972
- createdAt: new Date(row.createdAt),
973
- updatedAt: new Date(row.updatedAt),
974
- lastSeenAt: new Date(row.lastSeenAt),
975
- cpuPercent: row.cpuPercent,
976
- memoryPercent: row.memoryPercent,
977
- counts: counts ?? storage_constants.emptyStatusCounts()
978
- };
979
- }
980
- function toQueueInfo(row, counts, inUse) {
981
- return {
982
- name: row.name,
983
- processingPaused: row.processingPaused,
984
- acceptingPaused: row.acceptingPaused,
985
- counts: counts ?? storage_constants.emptyStatusCounts(),
986
- inUse
987
- };
988
- }
989
- function pageWindow(query, maxLimit = MAX_PAGE_LIMIT) {
990
- return {
991
- limit: Math.min(Math.max(Math.trunc(query.limit ?? DEFAULT_PAGE_LIMIT), 1), maxLimit),
992
- offset: Math.max(Math.trunc(query.offset ?? 0), 0)
993
- };
994
- }
995
- class ReadService {
996
- constructor(runtime) {
997
- this.runtime = runtime;
998
- }
999
- async getJob(jobId) {
1000
- const record = await this.runtime.driver.getJob({ jobId });
1001
- if (!record) return null;
1002
- return toSnapshot(record, record.queueName, this.runtime.clock.now());
1003
- }
1004
- /**
1005
- * A page of jobs, newest first.
1006
- *
1007
- * `instanceKey` and `search` are not part of the public `GetJobsQuery` — they are here for the
1008
- * dashboard facade, whose instance detail view reads jobs by the instance that claimed them and
1009
- * whose table offers a free-text filter. Both are pushed into SQL, so a search pages in the
1010
- * database rather than streaming the table into this process.
1011
- */
1012
- async getJobs(query) {
1013
- const { limit, offset } = pageWindow(query);
1014
- const filter = {
1015
- ...query.queue ? { queueName: query.queue } : {},
1016
- ...query.statuses ? { statuses: query.statuses } : {},
1017
- ...query.scheduleId ? { scheduleId: query.scheduleId } : {},
1018
- ...query.instanceKey ? { processedOnInstanceKey: query.instanceKey } : {},
1019
- ...query.search ? { search: query.search } : {}
1020
- };
1021
- const [records, total] = await Promise.all([
1022
- this.runtime.driver.getJobs({ ...filter, limit, offset }),
1023
- this.runtime.driver.countJobs(filter)
1024
- ]);
1025
- const now = this.runtime.clock.now();
1026
- return { items: records.map((r) => toSnapshot(r, r.queueName, now)), total };
1027
- }
1028
- async getQueueStats(queue) {
1029
- const counts = await this.runtime.driver.countJobsByStatus(queue ? { queueName: queue } : {});
1030
- return { ...queue ? { queue } : {}, counts };
1031
- }
1032
- /**
1033
- * A page of queues with their per-status counts, plus the total across every page. Same
1034
- * `limit`/`offset` window as the job, schedule and instance reads.
1035
- */
1036
- async getQueues(query = {}) {
1037
- const { limit, offset } = pageWindow(query);
1038
- const filter = {
1039
- ...query.search ? { search: query.search } : {},
1040
- ...query.processingPaused !== void 0 ? { processingPaused: query.processingPaused } : {}
1041
- };
1042
- const [rows, total] = await Promise.all([
1043
- this.runtime.driver.listQueues({ ...filter, limit, offset }),
1044
- this.runtime.driver.countQueues(filter)
1045
- ]);
1046
- if (!rows.length) return { items: [], total };
1047
- const counts = await this.runtime.driver.countJobsByStatusPerQueue({
1048
- queueNames: rows.map((r) => r.name)
1049
- });
1050
- return {
1051
- items: rows.map(
1052
- (row) => toQueueInfo(row, counts[row.name], this.runtime.registry.isRegistered(row.name))
1053
- ),
1054
- total
1055
- };
1056
- }
1057
- /** One queue by name, with the same counts and `inUse` flag the list carries. Null if unknown. */
1058
- async getQueue(name) {
1059
- const row = await this.runtime.driver.getQueueByName({ name });
1060
- if (!row) return null;
1061
- const counts = await this.runtime.driver.countJobsByStatusPerQueue({ queueNames: [row.name] });
1062
- return toQueueInfo(row, counts[row.name], this.runtime.registry.isRegistered(row.name));
1063
- }
1064
- /**
1065
- * A page of instances with liveness and per-instance job attribution, plus the total across
1066
- * every page. Same `limit`/`offset` window as the job and schedule reads.
1067
- */
1068
- async getInstances(query = {}) {
1069
- const { limit, offset } = pageWindow(query);
1070
- const filter = {
1071
- ...query.search ? { search: query.search } : {},
1072
- ...query.processingPaused !== void 0 ? { processingPaused: query.processingPaused } : {},
1073
- ...query.alive !== void 0 ? {
1074
- alive: query.alive,
1075
- seenSince: this.runtime.clock.now() - instanceStaleAfterMs(this.runtime.options)
1076
- } : {}
1077
- };
1078
- const [rows, total] = await Promise.all([
1079
- this.runtime.driver.listInstances({ ...filter, limit, offset }),
1080
- this.runtime.driver.countInstances(filter)
1081
- ]);
1082
- if (!rows.length) return { items: [], total };
1083
- const seenSince = this.runtime.clock.now() - instanceStaleAfterMs(this.runtime.options);
1084
- const counts = await this.runtime.driver.countJobsByStatusPerInstance({
1085
- instanceKeys: rows.map((r) => r.instanceKey)
1086
- });
1087
- return {
1088
- items: rows.map((row) => toInstanceInfo(row, counts[row.instanceKey], seenSince)),
1089
- total
1090
- };
1091
- }
1092
- /** One instance by key, with the same liveness, health and attribution the list carries. */
1093
- async getInstance(instanceKey) {
1094
- const row = await this.runtime.driver.getInstance({ instanceKey });
1095
- if (!row) return null;
1096
- const seenSince = this.runtime.clock.now() - instanceStaleAfterMs(this.runtime.options);
1097
- const counts = await this.runtime.driver.countJobsByStatusPerInstance({
1098
- instanceKeys: [row.instanceKey]
1099
- });
1100
- return toInstanceInfo(row, counts[row.instanceKey], seenSince);
1101
- }
1102
+ if (typeof cron === "string") return { pattern: cron, tz: DEFAULT_CRON_TIMEZONE };
1103
+ return { pattern: cron.pattern, tz: cron.tz ?? DEFAULT_CRON_TIMEZONE };
1102
1104
  }
1103
1105
  function computeBackoffSeconds(input) {
1104
1106
  const { strategy, attempt, baseDelaySeconds } = input;
@@ -1374,14 +1376,14 @@ class SchedulerService {
1374
1376
  const job = {
1375
1377
  queueName: schedule.queueName,
1376
1378
  status: storage_constants.JobStatus.PENDING,
1377
- priority: schedule.priority ?? 0,
1379
+ priority: schedule.priority ?? DEFAULT_PRIORITY,
1378
1380
  data: schedule.data,
1379
1381
  startAfter: now,
1380
- expireAt: t?.expireInSeconds != null ? now + migration.secondsToMs(t.expireInSeconds, "expireInSeconds") : null,
1382
+ expireAt: t?.expireInSeconds != null ? now + migration.wholeSecondsToMs(t.expireInSeconds, "expireInSeconds") : null,
1381
1383
  retryAttempt: 0,
1382
- retryMaxAttempts: schedule.retryMaxAttempts ?? 1,
1383
- retryDelaySeconds: schedule.retryDelaySeconds ?? 0,
1384
- retryBackoff: t?.retryBackoff ?? storage_constants.BackoffStrategy.FIXED,
1384
+ retryMaxAttempts: schedule.retryMaxAttempts ?? DEFAULT_RETRY_MAX_ATTEMPTS,
1385
+ retryDelaySeconds: schedule.retryDelaySeconds ?? DEFAULT_RETRY_DELAY_SECONDS,
1386
+ retryBackoff: t?.retryBackoff ?? DEFAULT_BACKOFF_STRATEGY,
1385
1387
  retryBackoffFactor: t?.retryBackoffFactor ?? null,
1386
1388
  retryMaxDelaySeconds: t?.retryMaxDelaySeconds ?? null,
1387
1389
  retryJitter: t?.retryJitter ?? false,
@@ -1403,10 +1405,10 @@ class SchedulerService {
1403
1405
  }
1404
1406
  computeNext(schedule, now) {
1405
1407
  if (schedule.cron) {
1406
- return new CronExpression(schedule.cron, schedule.timezone ?? "UTC").next(now);
1408
+ return new CronExpression(schedule.cron, schedule.timezone ?? DEFAULT_CRON_TIMEZONE).next(now);
1407
1409
  }
1408
1410
  if (schedule.everySeconds != null) {
1409
- return now + migration.secondsToMs(schedule.everySeconds, "schedule.startEverySeconds");
1411
+ return now + migration.wholeSecondsToMs(schedule.everySeconds, "schedule.startEverySeconds");
1410
1412
  }
1411
1413
  return null;
1412
1414
  }
@@ -1508,7 +1510,12 @@ class SystemMonitorService {
1508
1510
  }
1509
1511
  start() {
1510
1512
  if (this.limiter?.maxEventLoopDelaySeconds != null) {
1511
- this.histogram = node_perf_hooks.monitorEventLoopDelay({ resolution: 20 });
1513
+ this.histogram = node_perf_hooks.monitorEventLoopDelay({
1514
+ resolution: migration.secondsToMs(
1515
+ EVENT_LOOP_HISTOGRAM_RESOLUTION_SECONDS,
1516
+ "event-loop histogram resolution"
1517
+ )
1518
+ });
1512
1519
  this.histogram.enable();
1513
1520
  }
1514
1521
  this.timer = setInterval(
@@ -1563,7 +1570,7 @@ class SystemMonitorService {
1563
1570
  const heap = node_v8.getHeapStatistics();
1564
1571
  let eventLoopDelaySeconds = null;
1565
1572
  if (this.histogram) {
1566
- eventLoopDelaySeconds = this.histogram.mean / 1e9;
1573
+ eventLoopDelaySeconds = migration.msToSeconds(this.histogram.mean / NANOS_PER_MS);
1567
1574
  this.histogram.reset();
1568
1575
  }
1569
1576
  return {
@@ -1691,19 +1698,21 @@ class MigrationRunner {
1691
1698
  async migrate() {
1692
1699
  await this.migrateAuto(await this.driver.getSchemaVersion());
1693
1700
  }
1694
- async migrateAuto(current) {
1695
- const ordered = [...this.driver.migrations].sort((a, b) => a.version - b.version);
1696
- const pending = ordered.filter((m) => m.version > (current ?? 0));
1697
- if (pending.length === 0) return;
1701
+ async migrateAuto(initial) {
1702
+ let current = initial;
1703
+ if (this.pendingFrom(current).length === 0) return;
1698
1704
  const useLock = this.driver.capabilities[storage_constants.DriverCapability.ADVISORY_LOCK] && this.driver.tryAdvisoryLock;
1699
- const lockKey = `${this.context.tableNames.prefix}migrate`;
1705
+ const lockKey = this.lockKey();
1700
1706
  let locked = false;
1701
1707
  if (useLock) {
1702
- locked = await this.driver.tryAdvisoryLock({ key: lockKey });
1708
+ const tryLock = () => this.driver.tryAdvisoryLock({ key: lockKey });
1709
+ locked = await tryLock();
1703
1710
  if (!locked) {
1704
1711
  this.logger.debug("Another instance is migrating; waiting.");
1705
- await this.waitForVersion(this.targetVersion);
1706
- return;
1712
+ const outcome = await this.waitForVersion(this.targetVersion, tryLock);
1713
+ if (outcome === "landed") return;
1714
+ locked = true;
1715
+ current = await this.driver.getSchemaVersion();
1707
1716
  }
1708
1717
  } else {
1709
1718
  this.logger.debug(
@@ -1712,6 +1721,8 @@ class MigrationRunner {
1712
1721
  }
1713
1722
  try {
1714
1723
  const from = current;
1724
+ const pending = this.pendingFrom(current);
1725
+ if (pending.length === 0) return;
1715
1726
  for (const migration$1 of pending) {
1716
1727
  try {
1717
1728
  await this.driver.applyMigration({ migration: migration$1 });
@@ -1733,18 +1744,43 @@ class MigrationRunner {
1733
1744
  }
1734
1745
  }
1735
1746
  }
1747
+ /** The steps above `current`, in ascending version order. */
1748
+ pendingFrom(current) {
1749
+ return [...this.driver.migrations].sort((a, b) => a.version - b.version).filter((m) => m.version > (current ?? 0));
1750
+ }
1736
1751
  /**
1737
- * Poll until another instance's migration lands. Timed against the injected clock, like every
1738
- * other deadline in the codebase, so a test with a fake clock controls this wait rather than
1739
- * spending real seconds inside it.
1752
+ * The named lock this deployment's migration serializes on: `[<schema>.]<tablePrefix>migrate`.
1753
+ *
1754
+ * Scoped by schema as well as prefix because the lock is wider than the tables it guards — a
1755
+ * PostgreSQL advisory lock is database-wide and a MySQL `GET_LOCK` server-wide — so two deployments
1756
+ * in different schemas with the default prefix used to share one key, and the second waited on a
1757
+ * migration that was never going to land in its own schema. (MySQL additionally scopes an
1758
+ * unqualified key by the connection's database; see `MysqlDriver.tryAdvisoryLock`.)
1740
1759
  */
1741
- async waitForVersion(target, timeoutSeconds = MIGRATION_WAIT_TIMEOUT_SECONDS) {
1760
+ lockKey() {
1761
+ const { schema, prefix } = this.context.tableNames;
1762
+ return `${schema ? `${schema}.` : ""}${prefix}migrate`;
1763
+ }
1764
+ /**
1765
+ * Poll until another instance's migration lands, or until the lock it held frees up while this
1766
+ * schema is still behind — in which case `tryTakeOver` has taken it and this instance migrates.
1767
+ * Timed against the injected clock, like every other deadline in the codebase, so a test with a
1768
+ * fake clock controls this wait rather than spending real seconds inside it.
1769
+ */
1770
+ async waitForVersion(target, tryTakeOver, timeoutSeconds = MIGRATION_WAIT_TIMEOUT_SECONDS) {
1742
1771
  const timeoutMs = migration.secondsToMs(timeoutSeconds, "migration wait timeout");
1743
1772
  const pollMs = migration.secondsToMs(MIGRATION_WAIT_POLL_SECONDS, "migration wait poll");
1744
1773
  const deadline = this.clock.now() + timeoutMs;
1745
1774
  for (; ; ) {
1746
1775
  const v = await this.driver.getSchemaVersion();
1747
- if ((v ?? 0) >= target) return;
1776
+ if ((v ?? 0) >= target) return "landed";
1777
+ if (await tryTakeOver()) {
1778
+ if ((await this.driver.getSchemaVersion() ?? 0) >= target) {
1779
+ await this.driver.releaseAdvisoryLock?.({ key: this.lockKey() }).catch(() => void 0);
1780
+ return "landed";
1781
+ }
1782
+ return "acquired";
1783
+ }
1748
1784
  if (this.clock.now() >= deadline) break;
1749
1785
  await new Promise((resolve) => {
1750
1786
  const timer = setTimeout(resolve, pollMs);
@@ -1781,7 +1817,7 @@ class ClientLifecycleService {
1781
1817
  this.initialized = true;
1782
1818
  const { driver, context, options, events, logger, clock } = this.runtime;
1783
1819
  await driver.connect();
1784
- const defaultMode = this.runtime.headless ? storage_constants.MigrationMode.MANUAL : storage_constants.MigrationMode.AUTO;
1820
+ const defaultMode = this.runtime.headless ? storage_constants.DEFAULT_HEADLESS_MIGRATION_MODE : storage_constants.DEFAULT_MIGRATION_MODE;
1785
1821
  const migrationRunner = new MigrationRunner(driver, context, logger, events, clock);
1786
1822
  await migrationRunner.run(options.migration ?? defaultMode);
1787
1823
  if (this.runtime.headless) {
@@ -1880,9 +1916,11 @@ class ClientLifecycleService {
1880
1916
  await this.runtime.instances?.stop();
1881
1917
  await this.subscriber?.stop();
1882
1918
  this.state.running = false;
1883
- for (const worker of this.registry.allWorkers()) {
1884
- await worker.stop({ graceful: options.graceful, timeoutSeconds: options.timeoutSeconds });
1885
- }
1919
+ await Promise.all(
1920
+ [...this.registry.allWorkers()].map(
1921
+ (worker) => worker.stop({ graceful: options.graceful, timeoutSeconds: options.timeoutSeconds })
1922
+ )
1923
+ );
1886
1924
  this.monitor?.stop();
1887
1925
  const drained = await this.runtime.background.drain(options.timeoutSeconds);
1888
1926
  if (!drained) {
@@ -2013,20 +2051,7 @@ class DashboardService {
2013
2051
  this.runtime.driver.listSchedules({ ...filter, limit, offset }),
2014
2052
  this.runtime.driver.countSchedules(filter)
2015
2053
  ]);
2016
- return {
2017
- items: rows.map((s) => ({
2018
- scheduleId: s.id,
2019
- queue: s.queueName,
2020
- cron: s.cron,
2021
- everySeconds: s.everySeconds,
2022
- timezone: s.timezone,
2023
- nextRunAt: s.nextRunAt != null ? new Date(s.nextRunAt) : null,
2024
- lastRunAt: s.lastRunAt != null ? new Date(s.lastRunAt) : null,
2025
- enabled: s.enabled,
2026
- idempotencyKey: s.idempotencyKey
2027
- })),
2028
- total
2029
- };
2054
+ return { items: rows.map(toScheduleInfo), total };
2030
2055
  }
2031
2056
  /** One schedule by id, with its queue — backs the schedule detail page. */
2032
2057
  getSchedule(options) {
@@ -2055,10 +2080,7 @@ class DashboardService {
2055
2080
  return this.reads.getJobs({
2056
2081
  ...base,
2057
2082
  ...term ? { search: term } : {},
2058
- limit: Math.min(
2059
- Math.max(Math.trunc(base.limit ?? DEFAULT_PAGE_LIMIT), 1),
2060
- DASHBOARD_MAX_PAGE_LIMIT
2061
- )
2083
+ ...pageWindow(base, DASHBOARD_MAX_PAGE_LIMIT)
2062
2084
  });
2063
2085
  }
2064
2086
  // --- Batch actions -----------------------------------------------------------------------
@@ -2631,7 +2653,7 @@ class PortQueue {
2631
2653
  }
2632
2654
  async shutdown(options = {}) {
2633
2655
  await this.lifecycle.shutdown({
2634
- graceful: options.graceful ?? true,
2656
+ graceful: options.graceful ?? DEFAULT_SHUTDOWN_GRACEFUL,
2635
2657
  timeoutSeconds: options.timeoutSeconds ?? DEFAULT_SHUTDOWN_TIMEOUT_SECONDS
2636
2658
  });
2637
2659
  }
@@ -2801,26 +2823,58 @@ class PortQueue {
2801
2823
  */
2802
2824
  async retryJob(options) {
2803
2825
  this.requireStarted("retryJob");
2804
- const requeued = await this.runtime.driver.requeueJob({
2805
- jobId: options.jobId,
2806
- now: this.runtime.clock.now(),
2826
+ const [item] = await this.retryJobs({
2827
+ jobIds: [options.jobId],
2807
2828
  ...options.tx ? { tx: options.tx } : {}
2808
2829
  });
2809
- if (!requeued) return null;
2810
- this.runtime.wakeup.signal(requeued.queueName);
2811
- this.events.emit(PortQueueEvent.JOB_ADDED, {
2812
- jobId: requeued.jobId,
2813
- queue: requeued.queueName,
2814
- deduplicated: false
2815
- });
2830
+ if (item?.outcome !== storage_constants.BatchItemOutcome.APPLIED) return null;
2816
2831
  return {
2817
- jobId: requeued.jobId,
2818
- queue: requeued.queueName,
2819
- status: requeued.status,
2820
- startAfter: new Date(requeued.startAfter),
2832
+ jobId: item.jobId,
2833
+ queue: item.queue,
2834
+ status: item.status,
2835
+ startAfter: item.startAfter,
2821
2836
  deduplicated: false
2822
2837
  };
2823
2838
  }
2839
+ /**
2840
+ * Requeue many settled jobs — from any queue — in **one** statement, with the same `ACTIVE`
2841
+ * refusal as {@link retryJob}. Returns one item per id, in the order given: `APPLIED` (with the
2842
+ * re-armed `status` and `startAfter`), `REFUSED` for a running job, `NOT_FOUND` for an unknown id.
2843
+ */
2844
+ async retryJobs(options) {
2845
+ this.requireStarted("retryJobs");
2846
+ assertBatchIds(options.jobIds, "retryJobs({ jobIds })");
2847
+ if (!options.jobIds.length) return [];
2848
+ const tx = options.tx ? { tx: options.tx } : {};
2849
+ const requeued = await this.runtime.driver.requeueJobs({
2850
+ jobIds: options.jobIds,
2851
+ now: this.runtime.clock.now(),
2852
+ ...tx
2853
+ });
2854
+ for (const queue of new Set(requeued.map((r) => r.queueName))) this.runtime.wakeup.signal(queue);
2855
+ for (const ref of requeued) {
2856
+ this.events.emit(PortQueueEvent.JOB_ADDED, {
2857
+ jobId: ref.jobId,
2858
+ queue: ref.queueName,
2859
+ deduplicated: false
2860
+ });
2861
+ }
2862
+ const applied = new Map(requeued.map((r) => [r.jobId, r]));
2863
+ const existing = await this.existingJobQueues(options.jobIds, applied, options.tx);
2864
+ return options.jobIds.map((jobId) => {
2865
+ const ref = applied.get(jobId);
2866
+ if (ref) {
2867
+ return {
2868
+ jobId,
2869
+ queue: ref.queueName,
2870
+ outcome: storage_constants.BatchItemOutcome.APPLIED,
2871
+ status: ref.status,
2872
+ startAfter: new Date(ref.startAfter)
2873
+ };
2874
+ }
2875
+ return this.unappliedJob(jobId, existing);
2876
+ });
2877
+ }
2824
2878
  /**
2825
2879
  * Cancel a job, and report **what actually happened** — see {@link CancelOutcome}.
2826
2880
  *
@@ -2834,25 +2888,68 @@ class PortQueue {
2834
2888
  */
2835
2889
  async cancelJob(options) {
2836
2890
  this.requireStarted("cancelJob");
2837
- if (this.runtime.cancelRunning?.(options.jobId)) return storage_constants.CancelOutcome.SIGNALLED;
2838
- const cancelled = await this.runtime.driver.cancelJob({
2839
- jobId: options.jobId,
2840
- now: this.runtime.clock.now(),
2891
+ const [item] = await this.cancelJobs({
2892
+ jobIds: [options.jobId],
2841
2893
  ...options.tx ? { tx: options.tx } : {}
2842
2894
  });
2843
- if (cancelled) {
2844
- this.events.emit(PortQueueEvent.JOB_CANCELLED, {
2845
- jobId: cancelled.jobId,
2846
- queue: cancelled.queueName
2847
- });
2848
- return storage_constants.CancelOutcome.CANCELLED;
2895
+ switch (item?.outcome) {
2896
+ case storage_constants.BatchItemOutcome.APPLIED:
2897
+ return storage_constants.CancelOutcome.CANCELLED;
2898
+ case storage_constants.BatchItemOutcome.SIGNALLED:
2899
+ return storage_constants.CancelOutcome.SIGNALLED;
2900
+ case storage_constants.BatchItemOutcome.REFUSED:
2901
+ return storage_constants.CancelOutcome.NOT_CANCELLABLE;
2902
+ default:
2903
+ throw new migration.JobNotFoundError(options.jobId);
2849
2904
  }
2850
- const row = await this.runtime.driver.getJob({
2851
- jobId: options.jobId,
2905
+ }
2906
+ /**
2907
+ * Cancel many jobs — from any queue — in **one** statement, with the same rules as
2908
+ * {@link cancelJob}. Returns one item per id, in the order given: `APPLIED` (now `CANCELLED`),
2909
+ * `SIGNALLED` (running here; its handler was asked to stop), `REFUSED` (already settled, or
2910
+ * running in another process) or `NOT_FOUND`. A batch never throws for an unknown id.
2911
+ */
2912
+ async cancelJobs(options) {
2913
+ this.requireStarted("cancelJobs");
2914
+ assertBatchIds(options.jobIds, "cancelJobs({ jobIds })");
2915
+ if (!options.jobIds.length) return [];
2916
+ const running = new Set(options.jobIds.filter((id) => this.runtime.isJobRunningHere?.(id)));
2917
+ const remaining = options.jobIds.filter((id) => !running.has(id));
2918
+ const cancelled = remaining.length ? await this.runtime.driver.cancelJobs({
2919
+ jobIds: remaining,
2920
+ now: this.runtime.clock.now(),
2852
2921
  ...options.tx ? { tx: options.tx } : {}
2922
+ }) : [];
2923
+ for (const jobId of running) this.runtime.cancelRunning?.(jobId);
2924
+ for (const ref of cancelled) {
2925
+ this.events.emit(PortQueueEvent.JOB_CANCELLED, { jobId: ref.jobId, queue: ref.queueName });
2926
+ }
2927
+ const applied = new Map(cancelled.map((r) => [r.jobId, r]));
2928
+ const existing = await this.existingJobQueues(remaining, applied, options.tx);
2929
+ return options.jobIds.map((jobId) => {
2930
+ if (running.has(jobId)) return { jobId, outcome: storage_constants.BatchItemOutcome.SIGNALLED };
2931
+ const ref = applied.get(jobId);
2932
+ if (ref) return { jobId, queue: ref.queueName, outcome: storage_constants.BatchItemOutcome.APPLIED };
2933
+ return this.unappliedJob(jobId, existing);
2853
2934
  });
2854
- if (!row) throw new migration.JobNotFoundError(options.jobId);
2855
- return storage_constants.CancelOutcome.NOT_CANCELLABLE;
2935
+ }
2936
+ /**
2937
+ * The queue of every id a batch did **not** act on that still names a row — read only on that
2938
+ * refusal path, and in one statement, so a batch that did everything it was asked pays nothing.
2939
+ */
2940
+ async existingJobQueues(jobIds, applied, tx) {
2941
+ const leftover = [...new Set(jobIds.filter((id) => !applied.has(id)))];
2942
+ if (!leftover.length) return /* @__PURE__ */ new Map();
2943
+ const refs = await this.runtime.driver.findJobRefs({
2944
+ jobIds: leftover,
2945
+ ...tx ? { tx } : {}
2946
+ });
2947
+ return new Map(refs.map((r) => [r.jobId, r.queueName]));
2948
+ }
2949
+ /** A job the batch did not act on: refused when its row exists, otherwise not found. */
2950
+ unappliedJob(jobId, existing) {
2951
+ const queue = existing.get(jobId);
2952
+ return queue !== void 0 ? { jobId, queue, outcome: storage_constants.BatchItemOutcome.REFUSED } : { jobId, outcome: storage_constants.BatchItemOutcome.NOT_FOUND };
2856
2953
  }
2857
2954
  /**
2858
2955
  * Remove a single job's row. Never removes a **running** job: an `ACTIVE` row is skipped and this
@@ -2861,16 +2958,11 @@ class PortQueue {
2861
2958
  */
2862
2959
  async removeJob(options) {
2863
2960
  this.requireStarted("removeJob");
2864
- const removed = await this.runtime.driver.removeJob({
2865
- jobId: options.jobId,
2961
+ const removed = await this.removeJobs({
2962
+ jobIds: [options.jobId],
2866
2963
  ...options.tx ? { tx: options.tx } : {}
2867
2964
  });
2868
- if (!removed) return false;
2869
- this.events.emit(PortQueueEvent.JOB_REMOVED, {
2870
- jobId: removed.jobId,
2871
- queue: removed.queueName
2872
- });
2873
- return true;
2965
+ return removed > 0;
2874
2966
  }
2875
2967
  /**
2876
2968
  * Remove many jobs — either a set of ids (from any queue) or every job on one queue in the given
@@ -2910,16 +3002,35 @@ class PortQueue {
2910
3002
  /** Remove a recurring schedule by id. Returns true when a schedule went away. */
2911
3003
  async removeSchedule(options) {
2912
3004
  this.requireStarted("removeSchedule");
2913
- const removed = await this.runtime.driver.deleteSchedule({
2914
- scheduleId: options.scheduleId,
3005
+ const [item] = await this.removeSchedules({
3006
+ scheduleIds: [options.scheduleId],
2915
3007
  ...options.tx ? { tx: options.tx } : {}
2916
3008
  });
2917
- if (!removed) return false;
2918
- this.events.emit(PortQueueEvent.SCHEDULE_REMOVED, {
2919
- scheduleId: removed.scheduleId,
2920
- queue: removed.queueName
3009
+ return item?.outcome === storage_constants.BatchItemOutcome.APPLIED;
3010
+ }
3011
+ /**
3012
+ * Remove many recurring schedules in **one** statement. Returns one item per id, in the order
3013
+ * given: `APPLIED` (with the schedule's `queue`) or `NOT_FOUND`.
3014
+ */
3015
+ async removeSchedules(options) {
3016
+ this.requireStarted("removeSchedules");
3017
+ assertBatchIds(options.scheduleIds, "removeSchedules({ scheduleIds })");
3018
+ if (!options.scheduleIds.length) return [];
3019
+ const removed = await this.runtime.driver.deleteSchedules({
3020
+ scheduleIds: options.scheduleIds,
3021
+ ...options.tx ? { tx: options.tx } : {}
3022
+ });
3023
+ for (const ref of removed) {
3024
+ this.events.emit(PortQueueEvent.SCHEDULE_REMOVED, {
3025
+ scheduleId: ref.scheduleId,
3026
+ queue: ref.queueName
3027
+ });
3028
+ }
3029
+ const applied = new Map(removed.map((r) => [r.scheduleId, r.queueName]));
3030
+ return options.scheduleIds.map((scheduleId) => {
3031
+ const queue = applied.get(scheduleId);
3032
+ return queue !== void 0 ? { scheduleId, queue, outcome: storage_constants.BatchItemOutcome.APPLIED } : { scheduleId, outcome: storage_constants.BatchItemOutcome.NOT_FOUND };
2921
3033
  });
2922
- return true;
2923
3034
  }
2924
3035
  // --- Events & hooks ---
2925
3036
  on(event, listener, filter) {
@@ -2947,34 +3058,67 @@ class PortQueue {
2947
3058
  */
2948
3059
  async pauseQueue(options) {
2949
3060
  this.requireStarted("pauseQueue");
2950
- const mode = options.mode ?? storage_constants.PauseMode.PROCESSING;
2951
- const row = await this.setPaused(options.queue, true, mode === storage_constants.PauseMode.ALL);
2952
- this.runtime.registry.update(row);
2953
- this.events.emit(PortQueueEvent.QUEUE_PAUSED, { queue: options.queue, mode });
3061
+ const [item] = await this.pauseQueues({
3062
+ queues: [options.queue],
3063
+ ...options.mode ? { mode: options.mode } : {}
3064
+ });
3065
+ if (item?.outcome !== storage_constants.BatchItemOutcome.APPLIED) throw new migration.QueueNotFoundError(options.queue);
3066
+ }
3067
+ /**
3068
+ * Pause many queues in **one** statement, with the same `mode` and rules as {@link pauseQueue}.
3069
+ * Returns one item per name, in the order given: `APPLIED`, or `NOT_FOUND` for a name nothing has
3070
+ * ever used — reported, not thrown, so one stale name never blocks the rest.
3071
+ */
3072
+ async pauseQueues(options) {
3073
+ this.requireStarted("pauseQueues");
3074
+ assertBatchIds(options.queues, "pauseQueues({ queues })");
3075
+ const mode = options.mode ?? DEFAULT_PAUSE_MODE;
3076
+ const applied = await this.setPaused(options.queues, true, mode === storage_constants.PauseMode.ALL);
3077
+ for (const queue of applied) this.events.emit(PortQueueEvent.QUEUE_PAUSED, { queue, mode });
3078
+ return this.queueItems(options.queues, applied);
2954
3079
  }
2955
3080
  /** Resume claiming (and accepting) on this queue. See {@link pauseQueue} for what it touches. */
2956
3081
  async resumeQueue(options) {
2957
3082
  this.requireStarted("resumeQueue");
2958
- const row = await this.setPaused(options.queue, false, false);
2959
- this.runtime.registry.update(row);
2960
- this.runtime.wakeup.signal(options.queue);
2961
- this.events.emit(PortQueueEvent.QUEUE_RESUMED, { queue: options.queue });
3083
+ const [item] = await this.resumeQueues({ queues: [options.queue] });
3084
+ if (item?.outcome !== storage_constants.BatchItemOutcome.APPLIED) throw new migration.QueueNotFoundError(options.queue);
3085
+ }
3086
+ /** Resume many queues in **one** statement. Same per-name result as {@link pauseQueues}. */
3087
+ async resumeQueues(options) {
3088
+ this.requireStarted("resumeQueues");
3089
+ assertBatchIds(options.queues, "resumeQueues({ queues })");
3090
+ const applied = await this.setPaused(options.queues, false, false);
3091
+ for (const queue of applied) {
3092
+ this.runtime.wakeup.signal(queue);
3093
+ this.events.emit(PortQueueEvent.QUEUE_RESUMED, { queue });
3094
+ }
3095
+ return this.queueItems(options.queues, applied);
2962
3096
  }
2963
3097
  /**
2964
- * Write both pause flags and return the updated row, so the cached flags this process's workers
2965
- * read are refreshed without a second query. Throws {@link QueueNotFoundError} when the name
2966
- * matched nothing — there is no "paused nothing" outcome to report.
3098
+ * Write both pause flags on every named queue in one statement and return the names it updated.
3099
+ * The returned rows refresh the cached flags this process's workers read, so no second query is
3100
+ * needed.
2967
3101
  */
2968
- async setPaused(queue, processingPaused, acceptingPaused) {
2969
- if (this.runtime.registry.isRegistered(queue)) await this.runtime.registry.ensure(queue);
2970
- const row = await this.runtime.driver.setQueuePaused({
2971
- queueName: queue,
3102
+ async setPaused(queues, processingPaused, acceptingPaused) {
3103
+ if (!queues.length) return /* @__PURE__ */ new Set();
3104
+ for (const queue of new Set(queues)) {
3105
+ if (this.runtime.registry.isRegistered(queue)) await this.runtime.registry.ensure(queue);
3106
+ }
3107
+ const rows = await this.runtime.driver.setQueuesPaused({
3108
+ queueNames: queues,
2972
3109
  processingPaused,
2973
3110
  acceptingPaused,
2974
3111
  now: this.runtime.clock.now()
2975
3112
  });
2976
- if (!row) throw new migration.QueueNotFoundError(queue);
2977
- return row;
3113
+ for (const row of rows) this.runtime.registry.update(row);
3114
+ return new Set(rows.map((row) => row.name));
3115
+ }
3116
+ /** One item per requested name: `APPLIED` when its row was updated, `NOT_FOUND` otherwise. */
3117
+ queueItems(queues, applied) {
3118
+ return queues.map((queue) => ({
3119
+ queue,
3120
+ outcome: applied.has(queue) ? storage_constants.BatchItemOutcome.APPLIED : storage_constants.BatchItemOutcome.NOT_FOUND
3121
+ }));
2978
3122
  }
2979
3123
  /**
2980
3124
  * Manually remove a queue's row from the database. Refuses if the queue is still declared in
@@ -3005,29 +3149,50 @@ class PortQueue {
3005
3149
  /** Stop the named instance from claiming jobs (persisted; the target picks it up on heartbeat). */
3006
3150
  async pauseInstance(options) {
3007
3151
  this.requireStarted("pauseInstance");
3008
- await this.runtime.driver.setInstancePaused({
3009
- instanceKey: options.instanceKey,
3010
- processingPaused: true,
3011
- now: this.runtime.clock.now()
3012
- });
3013
- if (this.runtime.instances?.instanceKey === options.instanceKey) {
3014
- await this.runtime.instances.beat();
3152
+ await this.pauseInstances({ instanceKeys: [options.instanceKey] });
3153
+ }
3154
+ /**
3155
+ * Pause many instances in **one** statement. Returns one item per key, in the order given:
3156
+ * `APPLIED`, or `NOT_FOUND` for a key no instance has registered under.
3157
+ */
3158
+ async pauseInstances(options) {
3159
+ this.requireStarted("pauseInstances");
3160
+ assertBatchIds(options.instanceKeys, "pauseInstances({ instanceKeys })");
3161
+ const applied = await this.setInstancesPaused(options.instanceKeys, true);
3162
+ for (const instanceKey of applied) {
3163
+ this.events.emit(PortQueueEvent.INSTANCE_PAUSED, { instanceKey });
3015
3164
  }
3016
- this.events.emit(PortQueueEvent.INSTANCE_PAUSED, { instanceKey: options.instanceKey });
3165
+ return this.instanceItems(options.instanceKeys, applied);
3017
3166
  }
3018
3167
  /** Resume the named instance's job claiming. */
3019
3168
  async resumeInstance(options) {
3020
3169
  this.requireStarted("resumeInstance");
3021
- await this.runtime.driver.setInstancePaused({
3022
- instanceKey: options.instanceKey,
3023
- processingPaused: false,
3024
- now: this.runtime.clock.now()
3025
- });
3026
- if (this.runtime.instances?.instanceKey === options.instanceKey) {
3027
- await this.runtime.instances.beat();
3028
- }
3029
- this.runtime.wakeup.signalAll();
3030
- this.events.emit(PortQueueEvent.INSTANCE_RESUMED, { instanceKey: options.instanceKey });
3170
+ await this.resumeInstances({ instanceKeys: [options.instanceKey] });
3171
+ }
3172
+ /** Resume many instances in **one** statement. Same per-key result as {@link pauseInstances}. */
3173
+ async resumeInstances(options) {
3174
+ this.requireStarted("resumeInstances");
3175
+ assertBatchIds(options.instanceKeys, "resumeInstances({ instanceKeys })");
3176
+ const applied = await this.setInstancesPaused(options.instanceKeys, false);
3177
+ if (applied.size) this.runtime.wakeup.signalAll();
3178
+ for (const instanceKey of applied) {
3179
+ this.events.emit(PortQueueEvent.INSTANCE_RESUMED, { instanceKey });
3180
+ }
3181
+ return this.instanceItems(options.instanceKeys, applied);
3182
+ }
3183
+ /** Write the pause flag on every named instance in one statement; returns the keys it updated. */
3184
+ async setInstancesPaused(instanceKeys, processingPaused) {
3185
+ if (!instanceKeys.length) return /* @__PURE__ */ new Set();
3186
+ const applied = new Set(
3187
+ await this.runtime.driver.setInstancesPaused({
3188
+ instanceKeys,
3189
+ processingPaused,
3190
+ now: this.runtime.clock.now()
3191
+ })
3192
+ );
3193
+ const own = this.runtime.instances?.instanceKey;
3194
+ if (own !== void 0 && applied.has(own)) await this.runtime.instances.beat();
3195
+ return applied;
3031
3196
  }
3032
3197
  /**
3033
3198
  * Manually remove a long-inactive instance's monitoring row. Refuses unless the instance has not
@@ -3037,19 +3202,48 @@ class PortQueue {
3037
3202
  */
3038
3203
  async removeInstance(options) {
3039
3204
  this.requireStarted("removeInstance");
3040
- const row = await this.runtime.driver.getInstance({ instanceKey: options.instanceKey });
3041
- if (!row) return false;
3042
- const now = this.runtime.clock.now();
3205
+ const [item] = await this.removeInstances({ instanceKeys: [options.instanceKey] });
3206
+ if (item?.outcome === storage_constants.BatchItemOutcome.REFUSED) {
3207
+ throw new migration.InstanceActiveError(options.instanceKey);
3208
+ }
3209
+ return item?.outcome === storage_constants.BatchItemOutcome.APPLIED;
3210
+ }
3211
+ /**
3212
+ * Remove many long-inactive instances' monitoring rows in **one** delete, with the same 30-minute
3213
+ * rule as {@link removeInstance}. Returns one item per key, in the order given: `APPLIED`,
3214
+ * `REFUSED` for an instance seen too recently (reported, not thrown), or `NOT_FOUND`.
3215
+ */
3216
+ async removeInstances(options) {
3217
+ this.requireStarted("removeInstances");
3218
+ assertBatchIds(options.instanceKeys, "removeInstances({ instanceKeys })");
3219
+ if (!options.instanceKeys.length) return [];
3220
+ const rows = await this.runtime.driver.getInstancesByKeys({
3221
+ instanceKeys: options.instanceKeys
3222
+ });
3043
3223
  const staleAfterMs = migration.secondsToMs(
3044
3224
  INSTANCE_REMOVAL_STALE_SECONDS,
3045
3225
  "instance removal staleness window"
3046
3226
  );
3047
- if (row.lastSeenAt >= now - staleAfterMs) {
3048
- throw new migration.InstanceActiveError(options.instanceKey);
3227
+ const seenBefore = this.runtime.clock.now() - staleAfterMs;
3228
+ const stale = rows.filter((row) => row.lastSeenAt < seenBefore).map((row) => row.instanceKey);
3229
+ const removed = new Set(
3230
+ stale.length ? await this.runtime.driver.deleteInstances({ instanceKeys: stale, seenBefore }) : []
3231
+ );
3232
+ for (const instanceKey of removed) {
3233
+ this.events.emit(PortQueueEvent.INSTANCE_REMOVED, { instanceKey });
3049
3234
  }
3050
- const ok = await this.runtime.driver.deleteInstance({ instanceKey: options.instanceKey });
3051
- if (ok) this.events.emit(PortQueueEvent.INSTANCE_REMOVED, { instanceKey: options.instanceKey });
3052
- return ok;
3235
+ const existing = new Set(rows.map((row) => row.instanceKey));
3236
+ return options.instanceKeys.map((instanceKey) => ({
3237
+ instanceKey,
3238
+ outcome: removed.has(instanceKey) ? storage_constants.BatchItemOutcome.APPLIED : existing.has(instanceKey) ? storage_constants.BatchItemOutcome.REFUSED : storage_constants.BatchItemOutcome.NOT_FOUND
3239
+ }));
3240
+ }
3241
+ /** One item per requested key: `APPLIED` when its row was updated, `NOT_FOUND` otherwise. */
3242
+ instanceItems(instanceKeys, applied) {
3243
+ return instanceKeys.map((instanceKey) => ({
3244
+ instanceKey,
3245
+ outcome: applied.has(instanceKey) ? storage_constants.BatchItemOutcome.APPLIED : storage_constants.BatchItemOutcome.NOT_FOUND
3246
+ }));
3053
3247
  }
3054
3248
  /**
3055
3249
  * Every method that touches the database goes through this first. Before `init()` the driver is
@@ -3070,8 +3264,11 @@ exports.AFFINITY_PAGE_FACTOR = storage_constants.AFFINITY_PAGE_FACTOR;
3070
3264
  exports.AFFINITY_PAGE_MAX = storage_constants.AFFINITY_PAGE_MAX;
3071
3265
  exports.AFFINITY_PAGE_MIN_HEADROOM = storage_constants.AFFINITY_PAGE_MIN_HEADROOM;
3072
3266
  exports.BackoffStrategy = storage_constants.BackoffStrategy;
3267
+ exports.BatchItemOutcome = storage_constants.BatchItemOutcome;
3073
3268
  exports.CancelOutcome = storage_constants.CancelOutcome;
3269
+ exports.DEFAULT_HEADLESS_MIGRATION_MODE = storage_constants.DEFAULT_HEADLESS_MIGRATION_MODE;
3074
3270
  exports.DEFAULT_MAX_IDENTIFIER_LEN = storage_constants.DEFAULT_MAX_IDENTIFIER_LEN;
3271
+ exports.DEFAULT_MIGRATION_MODE = storage_constants.DEFAULT_MIGRATION_MODE;
3075
3272
  exports.DEFAULT_NAMESPACE = storage_constants.DEFAULT_NAMESPACE;
3076
3273
  exports.DEFAULT_TABLE_PREFIX = storage_constants.DEFAULT_TABLE_PREFIX;
3077
3274
  exports.DatabaseEngine = storage_constants.DatabaseEngine;
@@ -3120,19 +3317,24 @@ exports.wholeSecondsToMs = migration.wholeSecondsToMs;
3120
3317
  exports.ABORT_GRACE_SECONDS = ABORT_GRACE_SECONDS;
3121
3318
  exports.DASHBOARD_MAX_PAGE_LIMIT = DASHBOARD_MAX_PAGE_LIMIT;
3122
3319
  exports.DEFAULT_BACKOFF_FACTOR = DEFAULT_BACKOFF_FACTOR;
3320
+ exports.DEFAULT_BACKOFF_STRATEGY = DEFAULT_BACKOFF_STRATEGY;
3123
3321
  exports.DEFAULT_CONCURRENCY = DEFAULT_CONCURRENCY;
3322
+ exports.DEFAULT_CRON_TIMEZONE = DEFAULT_CRON_TIMEZONE;
3124
3323
  exports.DEFAULT_FAILURE_DETAIL = DEFAULT_FAILURE_DETAIL;
3125
3324
  exports.DEFAULT_HEARTBEAT_INTERVAL_SECONDS = DEFAULT_HEARTBEAT_INTERVAL_SECONDS;
3126
3325
  exports.DEFAULT_LOCK_DURATION_SECONDS = DEFAULT_LOCK_DURATION_SECONDS;
3127
3326
  exports.DEFAULT_PAGE_LIMIT = DEFAULT_PAGE_LIMIT;
3327
+ exports.DEFAULT_PAUSE_MODE = DEFAULT_PAUSE_MODE;
3128
3328
  exports.DEFAULT_POLL_INTERVAL_SECONDS = DEFAULT_POLL_INTERVAL_SECONDS;
3129
3329
  exports.DEFAULT_PRIORITY = DEFAULT_PRIORITY;
3130
3330
  exports.DEFAULT_RETRY_DELAY_SECONDS = DEFAULT_RETRY_DELAY_SECONDS;
3131
3331
  exports.DEFAULT_RETRY_MAX_ATTEMPTS = DEFAULT_RETRY_MAX_ATTEMPTS;
3132
3332
  exports.DEFAULT_SAMPLE_INTERVAL_SECONDS = DEFAULT_SAMPLE_INTERVAL_SECONDS;
3333
+ exports.DEFAULT_SHUTDOWN_GRACEFUL = DEFAULT_SHUTDOWN_GRACEFUL;
3133
3334
  exports.DEFAULT_SHUTDOWN_TIMEOUT_SECONDS = DEFAULT_SHUTDOWN_TIMEOUT_SECONDS;
3134
3335
  exports.DEFAULT_TICK_INTERVAL_SECONDS = DEFAULT_TICK_INTERVAL_SECONDS;
3135
3336
  exports.DRAIN_POLL_SECONDS = DRAIN_POLL_SECONDS;
3337
+ exports.EVENT_LOOP_HISTOGRAM_RESOLUTION_SECONDS = EVENT_LOOP_HISTOGRAM_RESOLUTION_SECONDS;
3136
3338
  exports.FAILURE_MESSAGE_MAX_CHARS = FAILURE_MESSAGE_MAX_CHARS;
3137
3339
  exports.FAILURE_MESSAGE_TRUNCATION_SUFFIX = FAILURE_MESSAGE_TRUNCATION_SUFFIX;
3138
3340
  exports.HEARTBEAT_STALE_BEATS = HEARTBEAT_STALE_BEATS;
@@ -3150,6 +3352,7 @@ exports.MIGRATION_WAIT_POLL_SECONDS = MIGRATION_WAIT_POLL_SECONDS;
3150
3352
  exports.MIGRATION_WAIT_TIMEOUT_SECONDS = MIGRATION_WAIT_TIMEOUT_SECONDS;
3151
3353
  exports.MIN_LOCK_HEARTBEAT_SECONDS = MIN_LOCK_HEARTBEAT_SECONDS;
3152
3354
  exports.MIN_SUBSCRIBER_POLL_SECONDS = MIN_SUBSCRIBER_POLL_SECONDS;
3355
+ exports.NANOS_PER_MS = NANOS_PER_MS;
3153
3356
  exports.PortQueue = PortQueue;
3154
3357
  exports.PortQueueEvent = PortQueueEvent;
3155
3358
  exports.Queue = Queue;