durability 5.2.0 → 5.3.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.
@@ -1,10 +1,11 @@
1
- import { z } from 'zod';
1
+ import * as v from 'valibot';
2
2
  import { trace, traceMethods, traceStorage } from '../dev.js';
3
3
  import { DurableRetryPolicyError, isErrorInstance, isNonRetryable, reportFailure, serializeError, } from '../errors.js';
4
4
  import { createEmitter, } from '../lifecycle.js';
5
5
  import { isSchemaCurrent, migrateCapability, } from '../migrations.js';
6
6
  import { assertPositiveInteger } from '../policy.js';
7
7
  import { deleteMemos, deleteStaleMemos } from '../memoize/index.js';
8
+ import { SharedTimer } from '../shared-timer.js';
8
9
  import { channelBindings, channelClause, claimAttempt, exhaustAttempts, tableOwner, updateAttempt, } from '../storage.js';
9
10
  const minAlarmDelayMs = 1000;
10
11
  const failedRunRetryMs = 1000;
@@ -17,20 +18,19 @@ const schedulerOptionKeys = [
17
18
  'onAlarmRetry',
18
19
  ];
19
20
  const maxAlarmDelayMs = 15000;
20
- // setTimeout treats delays past this as zero, so anything further out can only
21
- // be served by the physical alarm fallback.
22
- const maxTimerMs = 2 ** 31 - 1;
23
- const pendingHeadRowSchema = z.object({
24
- pk: z.string(),
25
- channel: z.string().optional(),
26
- next_attempt_at: z.number().int().nonnegative(),
21
+ const pendingHeadRowSchema = v.object({
22
+ pk: v.string(),
23
+ channel: v.optional(v.string()),
24
+ next_attempt_at: v.pipe(v.number(), v.safeInteger(), v.minValue(0)),
25
+ });
26
+ const countRowSchema = v.object({
27
+ count: v.pipe(v.number(), v.safeInteger(), v.minValue(0)),
27
28
  });
28
- const countRowSchema = z.object({ count: z.number().int().nonnegative() });
29
29
  /** The channel every helper uses when it is not given one. */
30
30
  export const defaultChannel = 'default';
31
31
  /** How long records of a channel no instance attached wait before they are looked at again. */
32
32
  const unattachedChannelRetryMs = 60000;
33
- const channelRowSchema = z.object({ channel: z.string() });
33
+ const channelRowSchema = v.object({ channel: v.string() });
34
34
  const activeKey = (channel, key) => JSON.stringify([channel ?? null, key]);
35
35
  /** Rejects a channel name a helper would otherwise store rows under. */
36
36
  export const assertChannel = (helper, channel) => {
@@ -83,6 +83,8 @@ const decideRetry = (spec, attempt, error) => {
83
83
  */
84
84
  export class Engine {
85
85
  constructor(context, options) {
86
+ /** Holds the timeouts of every helper on the object behind one native timer. */
87
+ this.timer = new SharedTimer();
86
88
  this.alarmConcurrency = defaultAlarmConcurrency;
87
89
  this.alarmMinDelayMs = 15000;
88
90
  this.alarmHandoffMs = 14 * 60000;
@@ -239,9 +241,8 @@ export class Engine {
239
241
  .join(' UNION ')
240
242
  : `SELECT DISTINCT channel FROM ${table.name}
241
243
  WHERE status = 'pending' AND next_attempt_at <= ?`;
242
- const unattached = channelRowSchema
243
- .array()
244
- .parse(this.sql.exec(query, ...(customTiming ? [] : [now])).toArray())
244
+ const unattached = v
245
+ .parse(v.array(channelRowSchema), this.sql.exec(query, ...(customTiming ? [] : [now])).toArray())
245
246
  .map((row) => row.channel)
246
247
  .filter((channel) => !channels.has(channel));
247
248
  if (unattached.length === 0) {
@@ -378,7 +379,7 @@ export class Engine {
378
379
  const active = this.activeByTable.get(participant.table.name);
379
380
  const partitioned = this.channelsByTable.has(participant.table.name);
380
381
  const limit = (active?.size ?? 0) + 1;
381
- const rows = pendingHeadRowSchema.array().parse(this.sql
382
+ const rows = v.parse(v.array(pendingHeadRowSchema), this.sql
382
383
  .exec(`SELECT ${participant.table.key} AS pk, next_attempt_at${partitioned ? ', channel' : ''}
383
384
  FROM ${participant.table.name}
384
385
  WHERE status = 'pending'
@@ -427,7 +428,7 @@ export class Engine {
427
428
  return;
428
429
  }
429
430
  if (this.earlyAlarm) {
430
- clearTimeout(this.earlyAlarm.timer);
431
+ this.earlyAlarm.cancel();
431
432
  this.earlyAlarm = undefined;
432
433
  }
433
434
  if (timestamp === undefined) {
@@ -436,16 +437,12 @@ export class Engine {
436
437
  const delay = timestamp - Date.now();
437
438
  // Without liveTimers the in-memory timer only covers the sub-min-delay
438
439
  // window; the physical alarm handles everything beyond it. With liveTimers
439
- // it fires at the exact due time no matter how far out, except past the
440
- // timer's range where only the physical fallback can serve it.
440
+ // it fires at the exact due time no matter how far out.
441
441
  if (!this.liveTimers && delay >= this.alarmMinDelayMs) {
442
442
  return;
443
443
  }
444
- if (delay > maxTimerMs) {
445
- return;
446
- }
447
- const timer = setTimeout(() => {
448
- if (this.earlyAlarm?.timer !== timer) {
444
+ const cancel = this.timer.schedule(() => {
445
+ if (this.earlyAlarm?.cancel !== cancel) {
449
446
  return;
450
447
  }
451
448
  this.earlyAlarm = undefined;
@@ -453,8 +450,8 @@ export class Engine {
453
450
  const onError = (error) => reportFailure('durability.background_execution.failed', { scheduledTime: timestamp }, error);
454
451
  const execution = this.alarm().catch(onError);
455
452
  this.waitUntil(execution, onError);
456
- }, Math.max(delay, 0));
457
- this.earlyAlarm = { timestamp, timer };
453
+ }, delay);
454
+ this.earlyAlarm = { timestamp, cancel };
458
455
  }
459
456
  /** Coalesces refreshes without dropping requests arriving after the pending-work read. */
460
457
  scheduleNextAlarm() {
@@ -493,7 +490,7 @@ export class Engine {
493
490
  const where = `created_at < ?${channelClause(table)}`;
494
491
  const params = [before, ...channelBindings(table)];
495
492
  const removed = await this.transaction((sql) => {
496
- const { count } = countRowSchema.parse(sql
493
+ const { count } = v.parse(countRowSchema, sql
497
494
  .exec(`SELECT COUNT(*) AS count FROM ${table.name} WHERE ${where}`, ...params)
498
495
  .toArray()[0]);
499
496
  sql.exec(`DELETE FROM ${table.name} WHERE ${where}`, ...params);
@@ -646,20 +643,18 @@ export class Engine {
646
643
  void execution.catch(() => undefined);
647
644
  const handoff = Symbol('alarm handoff');
648
645
  const remaining = this.alarmHandoffMs - (Date.now() - startedAt);
649
- let timeout;
646
+ let cancelTimeout;
650
647
  let result;
651
648
  try {
652
649
  result = await Promise.race([
653
650
  execution,
654
651
  new Promise((resolve) => {
655
- timeout = setTimeout(() => resolve(handoff), Math.max(remaining, 0));
652
+ cancelTimeout = this.timer.schedule(() => resolve(handoff), remaining);
656
653
  }),
657
654
  ]);
658
655
  }
659
656
  finally {
660
- if (timeout !== undefined) {
661
- clearTimeout(timeout);
662
- }
657
+ cancelTimeout?.();
663
658
  }
664
659
  if (result === handoff) {
665
660
  await this.armForHandoff(Date.now());
@@ -689,7 +684,10 @@ export class Engine {
689
684
  /**
690
685
  * Registers the execution in its active map synchronously, then claims and
691
686
  * runs one attempt in the background. The returned promise settles when the
692
- * attempt's outcome has been persisted, not when a timed-out handler settles.
687
+ * attempt's outcome has been persisted. The key leaves the active map and
688
+ * its permit is released then too, whether or not a timed-out handler has
689
+ * settled: nothing can stop a handler, and one that never settles would
690
+ * otherwise keep its retry from ever starting.
693
691
  */
694
692
  startExecution(spec, eagerPermit) {
695
693
  const { key, row, policy } = spec;
@@ -705,15 +703,6 @@ export class Engine {
705
703
  spec.active.set(key, activeExecution);
706
704
  this.trackActive(spec.table.name, activeKey(spec.table.channel, key));
707
705
  let releasePermit = eagerPermit;
708
- let handlerStarted = false;
709
- let handlerSettled = false;
710
- let policySettled = false;
711
- const releaseIfSettled = () => {
712
- if (policySettled && (!handlerStarted || handlerSettled)) {
713
- releasePermit?.();
714
- settleActive();
715
- }
716
- };
717
706
  const execution = (async () => {
718
707
  releasePermit ?? (releasePermit = await this.acquirePermit());
719
708
  const attempt = claimAttempt(this.sql, spec.table, key, row.generation_id, policy.maxAttempts);
@@ -730,18 +719,13 @@ export class Engine {
730
719
  });
731
720
  const controller = new AbortController();
732
721
  activeExecution.controller = controller;
733
- let timeout;
722
+ let cancelTimeout;
734
723
  try {
735
- handlerStarted = true;
736
724
  const handlerResult = Promise.resolve().then(() => spec.invoke(attempt, controller.signal));
737
- void handlerResult
738
- .finally(() => {
739
- handlerSettled = true;
740
- releaseIfSettled();
741
- })
742
- .catch(() => undefined);
725
+ // After a timeout nothing awaits the handler, which may still reject.
726
+ void handlerResult.catch(() => undefined);
743
727
  const timeoutResult = new Promise((_resolve, reject) => {
744
- timeout = setTimeout(() => {
728
+ cancelTimeout = this.timer.schedule(() => {
745
729
  const error = spec.timeoutError();
746
730
  controller.abort(error);
747
731
  reject(error);
@@ -773,13 +757,11 @@ export class Engine {
773
757
  await this.settleFailure(spec, attempt, startedAt, caught);
774
758
  }
775
759
  finally {
776
- if (timeout !== undefined) {
777
- clearTimeout(timeout);
778
- }
760
+ cancelTimeout?.();
779
761
  }
780
762
  })().finally(() => {
781
- policySettled = true;
782
- releaseIfSettled();
763
+ releasePermit?.();
764
+ settleActive();
783
765
  });
784
766
  void settled.finally(() => {
785
767
  if (spec.active.get(key) === activeExecution) {
@@ -910,6 +892,23 @@ export class DurabilityScheduler {
910
892
  alarm(info) {
911
893
  return engineFor({ scheduler: this }).alarm(info);
912
894
  }
895
+ /**
896
+ * Runs `callback` once after `delayMs`, like the global `setTimeout`, and
897
+ * returns a function that cancels it. The timeout shares one native timer
898
+ * with every helper on the object, so any number of them can be pending
899
+ * without reaching the runtime's limit of 10,000 native timers.
900
+ *
901
+ * The timeout exists only in memory and an eviction drops it; schedule work
902
+ * that must survive one with `DurabilityAlarms`. Callbacks due at the same
903
+ * time run one after another in the same task, and one that throws is
904
+ * reported as `durability.timer.callback_failed` instead of being thrown.
905
+ */
906
+ setTimeout(callback, delayMs) {
907
+ if (typeof callback !== 'function') {
908
+ throw new TypeError('callback must be a function');
909
+ }
910
+ return engineFor({ scheduler: this }).timer.schedule(callback, delayMs);
911
+ }
913
912
  }
914
913
  traceMethods(DurabilityScheduler.prototype, 'DurabilityScheduler');
915
914
  /** Resolves the engine a helper attaches to: the object's one scheduler. */
@@ -10,6 +10,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
10
10
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
11
  };
12
12
  var _SemaphoreClient_instances, _SemaphoreClient_config, _SemaphoreClient_nextRequestAt, _SemaphoreClient_address;
13
+ import * as v from 'valibot';
13
14
  import { SemaphoreProtocolError } from '../errors.js';
14
15
  import { permitGrantSchema, permitSyncResultSchema, } from './protocol.js';
15
16
  /**
@@ -29,11 +30,11 @@ export class SemaphoreClient {
29
30
  }
30
31
  async request(key, message) {
31
32
  const response = await __classPrivateFieldGet(this, _SemaphoreClient_config, "f").invoke(__classPrivateFieldGet(this, _SemaphoreClient_instances, "m", _SemaphoreClient_address).call(this, key), message);
32
- const parsed = permitGrantSchema.safeParse(response);
33
+ const parsed = v.safeParse(permitGrantSchema, response);
33
34
  if (!parsed.success) {
34
35
  throw new SemaphoreProtocolError(`Unexpected response to a permit request for "${key}"`);
35
36
  }
36
- __classPrivateFieldGet(this, _SemaphoreClient_nextRequestAt, "f").set(key, parsed.data.nextRequestAt);
37
+ __classPrivateFieldGet(this, _SemaphoreClient_nextRequestAt, "f").set(key, parsed.output.nextRequestAt);
37
38
  // Advisory state must stay bounded for high-cardinality keys.
38
39
  if (__classPrivateFieldGet(this, _SemaphoreClient_nextRequestAt, "f").size > 1024) {
39
40
  const oldest = __classPrivateFieldGet(this, _SemaphoreClient_nextRequestAt, "f").keys().next().value;
@@ -41,15 +42,15 @@ export class SemaphoreClient {
41
42
  __classPrivateFieldGet(this, _SemaphoreClient_nextRequestAt, "f").delete(oldest);
42
43
  }
43
44
  }
44
- return parsed.data;
45
+ return parsed.output;
45
46
  }
46
47
  async sync(key, message) {
47
48
  const response = await __classPrivateFieldGet(this, _SemaphoreClient_config, "f").invoke(__classPrivateFieldGet(this, _SemaphoreClient_instances, "m", _SemaphoreClient_address).call(this, key), message);
48
- const parsed = permitSyncResultSchema.safeParse(response);
49
+ const parsed = v.safeParse(permitSyncResultSchema, response);
49
50
  if (!parsed.success) {
50
51
  throw new SemaphoreProtocolError(`Unexpected response to a permit sync for "${key}"`);
51
52
  }
52
- return parsed.data;
53
+ return parsed.output;
53
54
  }
54
55
  }
55
56
  _SemaphoreClient_config = new WeakMap(), _SemaphoreClient_nextRequestAt = new WeakMap(), _SemaphoreClient_instances = new WeakSet(), _SemaphoreClient_address = function _SemaphoreClient_address(key) {