durability 5.2.1 → 5.4.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 (56) hide show
  1. package/README.md +42 -18
  2. package/dist/alarms/index.d.ts +1 -1
  3. package/dist/alarms/index.js +6 -3
  4. package/dist/dev.d.ts +7 -3
  5. package/dist/dev.js +17 -11
  6. package/dist/durable-object-target.js +8 -4
  7. package/dist/errors.d.ts +13 -7
  8. package/dist/errors.js +34 -32
  9. package/dist/fanout/index.d.ts +1 -1
  10. package/dist/fanout/index.js +15 -26
  11. package/dist/lifecycle.d.ts +1 -0
  12. package/dist/lifecycle.js +2 -2
  13. package/dist/log/index.js +5 -2
  14. package/dist/memoize/index.js +6 -1
  15. package/dist/migrations.js +37 -37
  16. package/dist/operations/index.js +8 -4
  17. package/dist/outbox/index.d.ts +1 -1
  18. package/dist/outbox/index.js +7 -17
  19. package/dist/policy.d.ts +1 -1
  20. package/dist/policy.js +2 -1
  21. package/dist/predicates.d.ts +9 -0
  22. package/dist/predicates.js +10 -0
  23. package/dist/routing/client.js +3 -4
  24. package/dist/routing/index.d.ts +1 -1
  25. package/dist/routing/index.js +14 -10
  26. package/dist/schedule/index.d.ts +15 -3
  27. package/dist/schedule/index.js +55 -36
  28. package/dist/scheduler/index.d.ts +35 -14
  29. package/dist/scheduler/index.js +78 -74
  30. package/dist/semaphore/client.js +2 -1
  31. package/dist/semaphore/index.d.ts +1 -1
  32. package/dist/semaphore/index.js +10 -5
  33. package/dist/semaphore/leases.d.ts +3 -2
  34. package/dist/semaphore/leases.js +3 -2
  35. package/dist/semaphore/queue-store.js +2 -1
  36. package/dist/semaphore/queue.d.ts +1 -1
  37. package/dist/semaphore/queue.js +36 -37
  38. package/dist/semaphore/server.js +50 -32
  39. package/dist/serialization.d.ts +3 -2
  40. package/dist/serialization.js +16 -13
  41. package/dist/shared-timer.d.ts +27 -0
  42. package/dist/shared-timer.js +191 -0
  43. package/dist/socket/client.d.ts +21 -7
  44. package/dist/socket/client.js +37 -27
  45. package/dist/socket/index.d.ts +20 -13
  46. package/dist/socket/index.js +40 -18
  47. package/dist/socket/protocol.d.ts +37 -17
  48. package/dist/socket/protocol.js +30 -36
  49. package/dist/topology/client.js +36 -19
  50. package/dist/topology/index.d.ts +3 -3
  51. package/dist/topology/index.js +40 -49
  52. package/dist/topology/snapshot.d.ts +6 -5
  53. package/dist/topology/snapshot.js +5 -2
  54. package/dist/tracker/index.js +18 -7
  55. package/dist/tracker/source.d.ts +6 -2
  56. package/package.json +2 -2
@@ -4,7 +4,9 @@ import { DurableRetryPolicyError, isErrorInstance, isNonRetryable, reportFailure
4
4
  import { createEmitter, } from '../lifecycle.js';
5
5
  import { isSchemaCurrent, migrateCapability, } from '../migrations.js';
6
6
  import { assertPositiveInteger } from '../policy.js';
7
+ import { isFunction, isNonEmptyString } from '../predicates.js';
7
8
  import { deleteMemos, deleteStaleMemos } from '../memoize/index.js';
9
+ import { SharedTimer } from '../shared-timer.js';
8
10
  import { channelBindings, channelClause, claimAttempt, exhaustAttempts, tableOwner, updateAttempt, } from '../storage.js';
9
11
  const minAlarmDelayMs = 1000;
10
12
  const failedRunRetryMs = 1000;
@@ -17,9 +19,6 @@ const schedulerOptionKeys = [
17
19
  'onAlarmRetry',
18
20
  ];
19
21
  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
22
  const pendingHeadRowSchema = v.object({
24
23
  pk: v.string(),
25
24
  channel: v.optional(v.string()),
@@ -36,18 +35,18 @@ const channelRowSchema = v.object({ channel: v.string() });
36
35
  const activeKey = (channel, key) => JSON.stringify([channel ?? null, key]);
37
36
  /** Rejects a channel name a helper would otherwise store rows under. */
38
37
  export const assertChannel = (helper, channel) => {
39
- if (typeof channel !== 'string' || channel.length === 0) {
38
+ if (!isNonEmptyString(channel)) {
40
39
  throw new TypeError(`${helper} channel must be a non-empty string`);
41
40
  }
42
41
  return channel;
43
42
  };
44
- const decideRetry = (spec, attempt, error) => {
45
- const terminal = isNonRetryable(error) ||
43
+ const decideRetry = (spec, attempt, cause) => {
44
+ const terminal = isNonRetryable(cause) ||
46
45
  attempt >= spec.policy.maxAttempts ||
47
- spec.isTerminal(error);
46
+ spec.isTerminal(cause);
48
47
  if (terminal) {
49
48
  const timestamp = Date.now();
50
- return { error, terminal, timestamp, nextAttemptAt: timestamp };
49
+ return { error: cause, terminal, timestamp, nextAttemptAt: timestamp };
51
50
  }
52
51
  try {
53
52
  const rawDelay = spec.policy.delay(attempt);
@@ -61,7 +60,7 @@ const decideRetry = (spec, attempt, error) => {
61
60
  throw new DurableRetryPolicyError(spec.label);
62
61
  }
63
62
  return {
64
- error,
63
+ error: cause,
65
64
  terminal: false,
66
65
  timestamp,
67
66
  nextAttemptAt: timestamp + delay,
@@ -85,6 +84,8 @@ const decideRetry = (spec, attempt, error) => {
85
84
  */
86
85
  export class Engine {
87
86
  constructor(context, options) {
87
+ /** Holds the timeouts of every helper on the object behind one native timer. */
88
+ this.timer = new SharedTimer();
88
89
  this.alarmConcurrency = defaultAlarmConcurrency;
89
90
  this.alarmMinDelayMs = 15000;
90
91
  this.alarmHandoffMs = 14 * 60000;
@@ -137,8 +138,7 @@ export class Engine {
137
138
  const alarmConcurrency = merged.alarmConcurrency ?? defaultAlarmConcurrency;
138
139
  const alarmMinDelayMs = merged.alarmMinDelayMs ?? 15000;
139
140
  const alarmHandoffMs = merged.alarmHandoffMs ?? 14 * 60000;
140
- if (merged.onAlarmRetry !== undefined &&
141
- typeof merged.onAlarmRetry !== 'function') {
141
+ if (merged.onAlarmRetry !== undefined && !isFunction(merged.onAlarmRetry)) {
142
142
  throw new TypeError('onAlarmRetry must be a function');
143
143
  }
144
144
  assertPositiveInteger('alarmConcurrency', alarmConcurrency);
@@ -206,7 +206,7 @@ export class Engine {
206
206
  if (participant.nextPendingAt !== undefined) {
207
207
  // Missing custom channels are dormant. Defer until construction finishes,
208
208
  // then restore their alarm without requiring a new application write.
209
- const onError = (error) => reportFailure('durability.channel_resume_failed', { table: table.name, channel }, error);
209
+ const onError = (cause) => reportFailure('durability.channel_resume_failed', { table: table.name, channel }, cause);
210
210
  const resumed = Promise.resolve()
211
211
  .then(() => {
212
212
  if (participant.nextPendingAt?.(this.sql) !== undefined) {
@@ -214,11 +214,11 @@ export class Engine {
214
214
  }
215
215
  return undefined;
216
216
  })
217
- .catch(async (error) => {
217
+ .catch(async (cause) => {
218
218
  if (await this.armFallbackAlarm()) {
219
219
  this.retryFailedRun();
220
220
  }
221
- onError(error);
221
+ onError(cause);
222
222
  });
223
223
  this.waitUntil(resumed, onError);
224
224
  }
@@ -284,7 +284,7 @@ export class Engine {
284
284
  * `DurableObjectState` applications pass at runtime carries it.
285
285
  */
286
286
  objectId() {
287
- const id = Reflect.get(this.context, 'id');
287
+ const id = 'id' in this.context ? this.context.id : undefined;
288
288
  return id === undefined || id === null ? undefined : String(id);
289
289
  }
290
290
  emitter(hook) {
@@ -428,7 +428,7 @@ export class Engine {
428
428
  return;
429
429
  }
430
430
  if (this.earlyAlarm) {
431
- clearTimeout(this.earlyAlarm.timer);
431
+ this.earlyAlarm.cancel();
432
432
  this.earlyAlarm = undefined;
433
433
  }
434
434
  if (timestamp === undefined) {
@@ -437,25 +437,21 @@ export class Engine {
437
437
  const delay = timestamp - Date.now();
438
438
  // Without liveTimers the in-memory timer only covers the sub-min-delay
439
439
  // window; the physical alarm handles everything beyond it. With liveTimers
440
- // it fires at the exact due time no matter how far out, except past the
441
- // timer's range where only the physical fallback can serve it.
440
+ // it fires at the exact due time no matter how far out.
442
441
  if (!this.liveTimers && delay >= this.alarmMinDelayMs) {
443
442
  return;
444
443
  }
445
- if (delay > maxTimerMs) {
446
- return;
447
- }
448
- const timer = setTimeout(() => {
449
- if (this.earlyAlarm?.timer !== timer) {
444
+ const cancel = this.timer.schedule(() => {
445
+ if (this.earlyAlarm?.cancel !== cancel) {
450
446
  return;
451
447
  }
452
448
  this.earlyAlarm = undefined;
453
449
  trace('scheduler.early_alarm', { scheduledTime: timestamp });
454
- const onError = (error) => reportFailure('durability.background_execution.failed', { scheduledTime: timestamp }, error);
450
+ const onError = (cause) => reportFailure('durability.background_execution.failed', { scheduledTime: timestamp }, cause);
455
451
  const execution = this.alarm().catch(onError);
456
452
  this.waitUntil(execution, onError);
457
- }, Math.max(delay, 0));
458
- this.earlyAlarm = { timestamp, timer };
453
+ }, delay);
454
+ this.earlyAlarm = { timestamp, cancel };
459
455
  }
460
456
  /** Coalesces refreshes without dropping requests arriving after the pending-work read. */
461
457
  scheduleNextAlarm() {
@@ -594,7 +590,7 @@ export class Engine {
594
590
  throw error;
595
591
  }
596
592
  reportFailure('durability.alarm.failed', { retryInMs: this.alarmMinDelayMs }, error);
597
- this.notifyAlarmRetry(error, info);
593
+ this.notifyAlarmRetry(serializeError(error), info);
598
594
  this.retryFailedRun();
599
595
  }
600
596
  }
@@ -609,24 +605,24 @@ export class Engine {
609
605
  const delay = Math.min(failedRunRetryMs * 2 ** (this.failedRuns - 1), this.alarmMinDelayMs);
610
606
  this.scheduleEarlyAlarm(Date.now() + delay);
611
607
  }
612
- notifyAlarmRetry(failure, invocation) {
608
+ notifyAlarmRetry(error, invocation) {
613
609
  const hook = this.onAlarmRetry;
614
610
  if (!hook) {
615
611
  return;
616
612
  }
617
613
  const objectId = this.objectId();
618
614
  const info = {
619
- error: serializeError(failure),
615
+ error,
620
616
  retryInMs: this.alarmMinDelayMs,
621
- ...(invocation === undefined
622
- ? {}
623
- : {
624
- retryCount: invocation.retryCount,
625
- isRetry: invocation.isRetry,
626
- }),
627
- ...(objectId === undefined ? {} : { objectId }),
628
617
  };
629
- const report = (hookError) => reportFailure('durability.alarm.retry_hook_failed', { retryInMs: info.retryInMs }, hookError);
618
+ if (invocation !== undefined) {
619
+ info.retryCount = invocation.retryCount;
620
+ info.isRetry = invocation.isRetry;
621
+ }
622
+ if (objectId !== undefined) {
623
+ info.objectId = objectId;
624
+ }
625
+ const report = (cause) => reportFailure('durability.alarm.retry_hook_failed', { retryInMs: info.retryInMs }, cause);
630
626
  try {
631
627
  const result = hook(info);
632
628
  if (result !== undefined) {
@@ -647,20 +643,18 @@ export class Engine {
647
643
  void execution.catch(() => undefined);
648
644
  const handoff = Symbol('alarm handoff');
649
645
  const remaining = this.alarmHandoffMs - (Date.now() - startedAt);
650
- let timeout;
646
+ let cancelTimeout;
651
647
  let result;
652
648
  try {
653
649
  result = await Promise.race([
654
650
  execution,
655
651
  new Promise((resolve) => {
656
- timeout = setTimeout(() => resolve(handoff), Math.max(remaining, 0));
652
+ cancelTimeout = this.timer.schedule(() => resolve(handoff), remaining);
657
653
  }),
658
654
  ]);
659
655
  }
660
656
  finally {
661
- if (timeout !== undefined) {
662
- clearTimeout(timeout);
663
- }
657
+ cancelTimeout?.();
664
658
  }
665
659
  if (result === handoff) {
666
660
  await this.armForHandoff(Date.now());
@@ -690,7 +684,10 @@ export class Engine {
690
684
  /**
691
685
  * Registers the execution in its active map synchronously, then claims and
692
686
  * runs one attempt in the background. The returned promise settles when the
693
- * 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.
694
691
  */
695
692
  startExecution(spec, eagerPermit) {
696
693
  const { key, row, policy } = spec;
@@ -706,15 +703,6 @@ export class Engine {
706
703
  spec.active.set(key, activeExecution);
707
704
  this.trackActive(spec.table.name, activeKey(spec.table.channel, key));
708
705
  let releasePermit = eagerPermit;
709
- let handlerStarted = false;
710
- let handlerSettled = false;
711
- let policySettled = false;
712
- const releaseIfSettled = () => {
713
- if (policySettled && (!handlerStarted || handlerSettled)) {
714
- releasePermit?.();
715
- settleActive();
716
- }
717
- };
718
706
  const execution = (async () => {
719
707
  releasePermit ?? (releasePermit = await this.acquirePermit());
720
708
  const attempt = claimAttempt(this.sql, spec.table, key, row.generation_id, policy.maxAttempts);
@@ -731,18 +719,13 @@ export class Engine {
731
719
  });
732
720
  const controller = new AbortController();
733
721
  activeExecution.controller = controller;
734
- let timeout;
722
+ let cancelTimeout;
735
723
  try {
736
- handlerStarted = true;
737
724
  const handlerResult = Promise.resolve().then(() => spec.invoke(attempt, controller.signal));
738
- void handlerResult
739
- .finally(() => {
740
- handlerSettled = true;
741
- releaseIfSettled();
742
- })
743
- .catch(() => undefined);
725
+ // After a timeout nothing awaits the handler, which may still reject.
726
+ void handlerResult.catch(() => undefined);
744
727
  const timeoutResult = new Promise((_resolve, reject) => {
745
- timeout = setTimeout(() => {
728
+ cancelTimeout = this.timer.schedule(() => {
746
729
  const error = spec.timeoutError();
747
730
  controller.abort(error);
748
731
  reject(error);
@@ -759,28 +742,29 @@ export class Engine {
759
742
  });
760
743
  if (timestamp !== undefined) {
761
744
  this.notify(spec.table, key, row);
762
- spec.emit({
745
+ const completed = {
763
746
  ...spec.entity,
764
747
  type: 'attempt_settled',
765
748
  timestamp,
766
749
  attempt,
767
750
  durationMs: Math.max(0, timestamp - startedAt),
768
751
  outcome: 'completed',
769
- ...(spec.includeResult ? { result } : {}),
770
- });
752
+ };
753
+ if (spec.includeResult) {
754
+ completed.result = result;
755
+ }
756
+ spec.emit(completed);
771
757
  }
772
758
  }
773
759
  catch (caught) {
774
760
  await this.settleFailure(spec, attempt, startedAt, caught);
775
761
  }
776
762
  finally {
777
- if (timeout !== undefined) {
778
- clearTimeout(timeout);
779
- }
763
+ cancelTimeout?.();
780
764
  }
781
765
  })().finally(() => {
782
- policySettled = true;
783
- releaseIfSettled();
766
+ releasePermit?.();
767
+ settleActive();
784
768
  });
785
769
  void settled.finally(() => {
786
770
  if (spec.active.get(key) === activeExecution) {
@@ -816,9 +800,9 @@ export class Engine {
816
800
  error: exhausted,
817
801
  });
818
802
  }
819
- async settleFailure(spec, attempt, startedAt, caught) {
803
+ async settleFailure(spec, attempt, startedAt, cause) {
820
804
  const { key, row } = spec;
821
- const decision = decideRetry(spec, attempt, caught);
805
+ const decision = decideRetry(spec, attempt, cause);
822
806
  const serializedError = serializeError(decision.error);
823
807
  const updated = await this.transaction((sql) => {
824
808
  const owned = updateAttempt(sql, spec.table, { key, generation: row.generation_id, attempt }, 'status = ?, next_attempt_at = ?, last_error = ?, last_error_name = ?', decision.terminal ? 'failed' : 'pending', decision.nextAttemptAt, serializedError.message, serializedError.name);
@@ -854,10 +838,11 @@ const engines = new WeakMap();
854
838
  // Every copy of this package in an isolate shares the registry, so a second
855
839
  // copy reaching the same object is caught instead of fighting over its alarm.
856
840
  const installation = Symbol('durability installation');
857
- const globalRegistry = globalThis;
858
841
  const registryKey = Symbol.for('durability.object-schedulers');
859
- globalRegistry[registryKey] ?? (globalRegistry[registryKey] = new WeakMap());
860
- const objectSchedulers = globalRegistry[registryKey];
842
+ // SAFETY: registryKey is this package's registered symbol, and every copy
843
+ // stores only a WeakMap<object, ObjectScheduler> under it on globalThis.
844
+ const globalRegistry = globalThis;
845
+ const objectSchedulers = (globalRegistry[registryKey] ?? (globalRegistry[registryKey] = new WeakMap()));
861
846
  /** The one engine behind every scheduler and helper of a Durable Object. */
862
847
  const engineForObject = (config) => {
863
848
  const { context } = config;
@@ -870,6 +855,8 @@ const engineForObject = (config) => {
870
855
  if (existing.installation !== installation) {
871
856
  throw new Error('Another copy of durability is already attached to this Durable Object; install durability once, for example as a peer dependency');
872
857
  }
858
+ // SAFETY: the installation matches, so this copy of the module created the
859
+ // entry above with `new Engine`.
873
860
  const engine = existing.engine;
874
861
  engine.attach(context, config);
875
862
  return engine;
@@ -911,6 +898,23 @@ export class DurabilityScheduler {
911
898
  alarm(info) {
912
899
  return engineFor({ scheduler: this }).alarm(info);
913
900
  }
901
+ /**
902
+ * Runs `callback` once after `delayMs`, like the global `setTimeout`, and
903
+ * returns a function that cancels it. The timeout shares one native timer
904
+ * with every helper on the object, so any number of them can be pending
905
+ * without reaching the runtime's limit of 10,000 native timers.
906
+ *
907
+ * The timeout exists only in memory and an eviction drops it; schedule work
908
+ * that must survive one with `DurabilityAlarms`. Callbacks due at the same
909
+ * time run one after another in the same task, and one that throws is
910
+ * reported as `durability.timer.callback_failed` instead of being thrown.
911
+ */
912
+ setTimeout(callback, delayMs) {
913
+ if (!isFunction(callback)) {
914
+ throw new TypeError('callback must be a function');
915
+ }
916
+ return engineFor({ scheduler: this }).timer.schedule(callback, delayMs);
917
+ }
914
918
  }
915
919
  traceMethods(DurabilityScheduler.prototype, 'DurabilityScheduler');
916
920
  /** Resolves the engine a helper attaches to: the object's one scheduler. */
@@ -12,6 +12,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
12
12
  var _SemaphoreClient_instances, _SemaphoreClient_config, _SemaphoreClient_nextRequestAt, _SemaphoreClient_address;
13
13
  import * as v from 'valibot';
14
14
  import { SemaphoreProtocolError } from '../errors.js';
15
+ import { isNonEmptyString } from '../predicates.js';
15
16
  import { permitGrantSchema, permitSyncResultSchema, } from './protocol.js';
16
17
  /**
17
18
  * Transport-independent protocol core. Validates responses and remembers each
@@ -54,7 +55,7 @@ export class SemaphoreClient {
54
55
  }
55
56
  }
56
57
  _SemaphoreClient_config = new WeakMap(), _SemaphoreClient_nextRequestAt = new WeakMap(), _SemaphoreClient_instances = new WeakSet(), _SemaphoreClient_address = function _SemaphoreClient_address(key) {
57
- if (typeof key !== 'string' || key.length === 0) {
58
+ if (!isNonEmptyString(key)) {
58
59
  throw new SemaphoreProtocolError('Semaphore keys must be non-empty strings');
59
60
  }
60
61
  const locationHint = __classPrivateFieldGet(this, _SemaphoreClient_config, "f").locationHint?.(key);
@@ -20,7 +20,7 @@ export type SemaphoreSession = {
20
20
  request(key: string, message: PermitRequest): Promise<PermitGrant>;
21
21
  sync(key: string, message: PermitSync): Promise<PermitSyncResult>;
22
22
  setContext(context: TransformContext): {
23
- invoke(method: string, args: unknown[]): Promise<unknown>;
23
+ invoke(method: string, args: unknown[]): Promise<PermitGrant | PermitSyncResult>;
24
24
  };
25
25
  };
26
26
  export type DurabilitySemaphoreClientConfig<Target extends Rpc.DurableObjectBranded> = DurableObjectTarget<Target> & {
@@ -24,7 +24,7 @@ export class DurabilitySemaphore extends DurabilitySemaphoreServer {
24
24
  * Caller transforms such as `timeout` apply; transform context is not used.
25
25
  */
26
26
  static client(config) {
27
- const client = new SemaphoreClient({
27
+ const clientConfig = {
28
28
  invoke: (address, message) => {
29
29
  const namespace = resolveNamespace(config, (text) => new SemaphoreProtocolError(text));
30
30
  const stub = namespace.getByName(address.key, address.locationHint === undefined
@@ -32,20 +32,25 @@ export class DurabilitySemaphore extends DurabilitySemaphoreServer {
32
32
  : { locationHint: address.locationHint });
33
33
  return config.invoke(stub, message);
34
34
  },
35
- ...(config.locationHint === undefined
36
- ? {}
37
- : { locationHint: config.locationHint }),
38
- });
35
+ };
36
+ if (config.locationHint !== undefined) {
37
+ clientConfig.locationHint = config.locationHint;
38
+ }
39
+ const client = new SemaphoreClient(clientConfig);
39
40
  const session = {
40
41
  request: (key, message) => client.request(key, message),
41
42
  sync: (key, message) => client.sync(key, message),
42
43
  setContext: () => ({
43
44
  invoke: (method, args) => {
45
+ // SAFETY: the transform stub forwards the arguments of a typed
46
+ // SemaphoreSession call, so args are [key, message] for `method`.
44
47
  const key = args[0];
45
48
  if (method === 'request') {
49
+ // SAFETY: see `key`; `request` takes a PermitRequest.
46
50
  return client.request(key, args[1]);
47
51
  }
48
52
  if (method === 'sync') {
53
+ // SAFETY: see `key`; `sync` takes a PermitSync.
49
54
  return client.sync(key, args[1]);
50
55
  }
51
56
  throw new SemaphoreProtocolError(`Unknown semaphore method "${method}"`);
@@ -67,12 +67,13 @@ type GroupPolicy = {
67
67
  blocked?: SemaphoreBlockedReason;
68
68
  };
69
69
  export declare const resolveLeasePolicy: (options: SemaphoreLeaseOptions) => LeasePolicy;
70
- /** Permits grants may use, and permits leases may hold, for one limit. */
71
- export declare const budgets: (provisioning: SemaphoreProvisioning, limit: number) => {
70
+ type PermitBudget = {
72
71
  grants: number;
73
72
  leases: number;
74
73
  shared: boolean;
75
74
  };
75
+ /** Permits grants may use, and permits leases may hold, for one limit. */
76
+ export declare const budgets: (provisioning: SemaphoreProvisioning, limit: number) => PermitBudget;
76
77
  export declare const leaseFootprint: (lease: LeaseRow) => number;
77
78
  export declare const leaseEligible: (policy: LeasePolicy, group: GroupPolicy) => boolean;
78
79
  export type LeaseReportOutcome = {
@@ -1,4 +1,5 @@
1
1
  import { assertPositiveInteger } from '../policy.js';
2
+ import { isNumber } from '../predicates.js';
2
3
  /** Map key for a client identity; JSON keeps raw IDs and channels unambiguous. */
3
4
  export const clientKey = (clientId, clientChannel) => JSON.stringify([clientId, clientChannel]);
4
5
  export const ownedBy = (row, client) => row.client_id === client.clientId &&
@@ -30,14 +31,14 @@ export const resolveLeasePolicy = (options) => {
30
31
  ? policy.provisioning.extra
31
32
  : undefined;
32
33
  if (amount !== undefined) {
33
- const value = typeof amount === 'number' ? amount : amount.ratio;
34
+ const value = isNumber(amount) ? amount : amount.ratio;
34
35
  if (!Number.isFinite(value) || value < 0) {
35
36
  throw new RangeError('lease provisioning amounts must be non-negative');
36
37
  }
37
38
  }
38
39
  return policy;
39
40
  };
40
- const scaled = (amount, limit) => typeof amount === 'number' ? amount : Math.floor(limit * amount.ratio);
41
+ const scaled = (amount, limit) => isNumber(amount) ? amount : Math.floor(limit * amount.ratio);
41
42
  /** Permits grants may use, and permits leases may hold, for one limit. */
42
43
  export const budgets = (provisioning, limit) => {
43
44
  if (provisioning.mode === 'over') {
@@ -1,4 +1,5 @@
1
1
  import * as v from 'valibot';
2
+ import { isNumber } from '../predicates.js';
2
3
  export const queueItemRowSchema = v.object({
3
4
  id: v.string(),
4
5
  key: v.string(),
@@ -250,7 +251,7 @@ export class QueueStore {
250
251
  WHERE channel = ? AND confirmed = 0
251
252
  )`, this.channel, this.channel, unnotified ? 1 : 0, notified ? 1 : 0, this.channel)
252
253
  .toArray()[0]?.['at'];
253
- return typeof at === 'number' ? at : undefined;
254
+ return isNumber(at) ? at : undefined;
254
255
  }
255
256
  items(query, ...bindings) {
256
257
  return v.parse(v.array(queueItemRowSchema), this.sql.exec(query, ...bindings).toArray());
@@ -58,7 +58,7 @@ export type DurabilitySemaphoreQueueConfig<Body> = SchedulerAttachment & {
58
58
  * Receives items once the holder has confirmed their permits, after the
59
59
  * admission commits. Retried until it returns; must be idempotent on item ID.
60
60
  */
61
- admit(items: AdmittedItem<Body>[]): unknown | Promise<unknown>;
61
+ admit(items: AdmittedItem<Body>[]): void | Promise<void>;
62
62
  /**
63
63
  * Returns which of these admitted items are done. The queue asks on its own
64
64
  * alarm and releases them, so a permit whose `release()` was lost (a
@@ -16,6 +16,7 @@ import { durabilitySemaphoreQueueMigrations } from './migrations.js';
16
16
  import { migrateCapability, } from '../migrations.js';
17
17
  import { DurabilityOutbox, stageWithin, } from '../outbox/index.js';
18
18
  import { assertPositiveInteger, } from '../policy.js';
19
+ import { isFunction, isNonEmptyString, isString } from '../predicates.js';
19
20
  import { DurabilityScheduler, assertChannel, defaultChannel, engineFor, } from '../scheduler/index.js';
20
21
  import { deserialize, serialize } from '../serialization.js';
21
22
  import { QueueStore, } from './queue-store.js';
@@ -38,6 +39,7 @@ const maxReportRetryMs = 5000;
38
39
  const demandScanLimit = 200;
39
40
  const maxDelayMs = 2 ** 31 - 1;
40
41
  const pairKey = (key, second) => JSON.stringify([key, second]);
42
+ // SAFETY: callers pass only outbox keys this queue staged, all built by pairKey.
41
43
  const parsePairKey = (value) => JSON.parse(value);
42
44
  const grantReport = (grant) => ({
43
45
  grantId: grant.grant_id,
@@ -46,12 +48,17 @@ const grantReport = (grant) => ({
46
48
  });
47
49
  // A lease stops drawing by moving its expiry to now, whoever retired it.
48
50
  const retiredLocally = (lease, now) => lease.expires_at <= now;
49
- const leaseReport = (lease) => ({
50
- leaseId: lease.lease_id,
51
- drawn: lease.drawn,
52
- released: lease.released,
53
- ...(retiredLocally(lease, Date.now()) ? { retired: true } : {}),
54
- });
51
+ const leaseReport = (lease) => {
52
+ const report = {
53
+ leaseId: lease.lease_id,
54
+ drawn: lease.drawn,
55
+ released: lease.released,
56
+ };
57
+ if (retiredLocally(lease, Date.now())) {
58
+ report.retired = true;
59
+ }
60
+ return report;
61
+ };
55
62
  /**
56
63
  * The holder sweeps a lease at its expiry by its own clock; stopping local
57
64
  * draws this long before it bounds the window a skewed clock could open.
@@ -94,10 +101,10 @@ export class DurabilitySemaphoreQueue {
94
101
  _DurabilitySemaphoreQueue_notifying.set(this, void 0);
95
102
  _DurabilitySemaphoreQueue_checking.set(this, void 0);
96
103
  const channel = assertChannel('Semaphore queue', config.channel ?? defaultChannel);
97
- if (typeof config.clientId !== 'string' || config.clientId.length === 0) {
104
+ if (!isNonEmptyString(config.clientId)) {
98
105
  throw new TypeError('clientId must be a non-empty string');
99
106
  }
100
- if (typeof config.admit !== 'function') {
107
+ if (!isFunction(config.admit)) {
101
108
  throw new TypeError('Semaphore queue requires an admit function');
102
109
  }
103
110
  __classPrivateFieldSet(this, _DurabilitySemaphoreQueue_server, config.server, "f");
@@ -109,8 +116,7 @@ export class DurabilitySemaphoreQueue {
109
116
  clientChannel: channel,
110
117
  }, "f");
111
118
  __classPrivateFieldSet(this, _DurabilitySemaphoreQueue_admit, config.admit, "f");
112
- if (config.finished !== undefined &&
113
- typeof config.finished !== 'function') {
119
+ if (config.finished !== undefined && !isFunction(config.finished)) {
114
120
  throw new TypeError('finished must be a function');
115
121
  }
116
122
  __classPrivateFieldSet(this, _DurabilitySemaphoreQueue_finished, config.finished, "f");
@@ -177,11 +183,9 @@ export class DurabilitySemaphoreQueue {
177
183
  async enqueue(items) {
178
184
  const rows = items.map((item) => {
179
185
  const id = item.id ?? crypto.randomUUID();
180
- if (typeof id !== 'string' ||
181
- id.length === 0 ||
182
- typeof item.key !== 'string' ||
183
- item.key.length === 0 ||
184
- (item.group !== undefined && typeof item.group !== 'string')) {
186
+ if (!isNonEmptyString(id) ||
187
+ !isNonEmptyString(item.key) ||
188
+ (item.group !== undefined && !isString(item.group))) {
185
189
  throw new TypeError('Semaphore items need a non-empty id, a semaphore key, and a string group');
186
190
  }
187
191
  const now = Date.now();
@@ -686,12 +690,15 @@ async function _DurabilitySemaphoreQueue_renewLeases(now) {
686
690
  }, _DurabilitySemaphoreQueue_stageReport = function _DurabilitySemaphoreQueue_stageReport(grant) {
687
691
  stageWithin(__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_outbox, "f"), __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_engine, "f").sql, pairKey(grant.key, `grant:${grant.grant_id}`), { kind: 'grant', claimed: grant.claimed, released: grant.released });
688
692
  }, _DurabilitySemaphoreQueue_stageLeaseReport = function _DurabilitySemaphoreQueue_stageLeaseReport(lease) {
689
- stageWithin(__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_outbox, "f"), __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_engine, "f").sql, pairKey(lease.key, `lease:${lease.lease_id}`), {
693
+ const report = {
690
694
  kind: 'lease',
691
695
  drawn: lease.drawn,
692
696
  released: lease.released,
693
- ...(retiredLocally(lease, Date.now()) ? { retired: true } : {}),
694
- });
697
+ };
698
+ if (retiredLocally(lease, Date.now())) {
699
+ report.retired = true;
700
+ }
701
+ stageWithin(__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_outbox, "f"), __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_engine, "f").sql, pairKey(lease.key, `lease:${lease.lease_id}`), report);
695
702
  }, _DurabilitySemaphoreQueue_publishReports =
696
703
  /** Outbox sink: one `sync` per key; a failed key keeps its entries pending. */
697
704
  async function _DurabilitySemaphoreQueue_publishReports(entries) {
@@ -713,12 +720,15 @@ async function _DurabilitySemaphoreQueue_publishReports(entries) {
713
720
  });
714
721
  }
715
722
  else {
716
- leases.push({
723
+ const report = {
717
724
  leaseId: id,
718
725
  drawn: entry.value.drawn,
719
726
  released: entry.value.released,
720
- ...(entry.value.retired ? { retired: true } : {}),
721
- });
727
+ };
728
+ if (entry.value.retired) {
729
+ report.retired = true;
730
+ }
731
+ leases.push(report);
722
732
  }
723
733
  }
724
734
  let synced;
@@ -754,7 +764,7 @@ async function _DurabilitySemaphoreQueue_publishReports(entries) {
754
764
  __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_instances, "m", _DurabilitySemaphoreQueue_refreshKey).call(this, key);
755
765
  });
756
766
  }));
757
- const onError = (error) => reportFailure('durability.semaphore_queue.notify_failed', {}, error);
767
+ const onError = (cause) => reportFailure('durability.semaphore_queue.notify_failed', {}, cause);
758
768
  __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_engine, "f").waitUntil(__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_instances, "m", _DurabilitySemaphoreQueue_notify).call(this).catch(onError), onError);
759
769
  }, _DurabilitySemaphoreQueue_releaseFinished =
760
770
  /** Releases admitted items `finished` reports done, one check at a time. */
@@ -843,6 +853,8 @@ async function _DurabilitySemaphoreQueue_notify() {
843
853
  id: row.id,
844
854
  key: row.key,
845
855
  group: row.grp,
856
+ // SAFETY: enqueue is the only writer of item payloads, each
857
+ // serialized from a Body.
846
858
  body: deserialize(row.payload),
847
859
  enqueuedAt: row.created_at,
848
860
  admittedAt: row.admitted_at ?? row.created_at,
@@ -903,20 +915,7 @@ async function _DurabilitySemaphoreQueue_notify() {
903
915
  reportFailure('durability.semaphore_queue.retry_policy_failed', {}, error);
904
916
  }
905
917
  return 60000;
906
- }, _DurabilitySemaphoreQueue_deadline = async function _DurabilitySemaphoreQueue_deadline(what, run) {
907
- let timer;
908
- try {
909
- return await Promise.race([
910
- Promise.resolve().then(run),
911
- new Promise((_resolve, reject) => {
912
- timer = setTimeout(() => reject(new Error(`Semaphore ${what} timed out after ${__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_attemptTimeoutMs, "f")}ms`)), __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_attemptTimeoutMs, "f"));
913
- }),
914
- ]);
915
- }
916
- finally {
917
- if (timer !== undefined) {
918
- clearTimeout(timer);
919
- }
920
- }
918
+ }, _DurabilitySemaphoreQueue_deadline = function _DurabilitySemaphoreQueue_deadline(what, run) {
919
+ return __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_engine, "f").timer.withTimeout(Promise.resolve().then(run), __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_attemptTimeoutMs, "f"), () => new Error(`Semaphore ${what} timed out after ${__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_attemptTimeoutMs, "f")}ms`));
921
920
  };
922
921
  traceMethods(DurabilitySemaphoreQueue.prototype, 'DurabilitySemaphoreQueue');