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
@@ -16,6 +16,7 @@ import { reportFailure, ScheduledOutcomeTimeoutError, ScheduledRunInterruptedErr
16
16
  import { durabilityScheduleMigrations } from './migrations.js';
17
17
  import { migrateCapability, } from '../migrations.js';
18
18
  import { assertPositiveInteger, } from '../policy.js';
19
+ import { isFunction, isNonEmptyString, isNumber, isObject, } from '../predicates.js';
19
20
  import { assertChannel, defaultChannel, engineFor, } from '../scheduler/index.js';
20
21
  import { exponential, jitter } from '../utils.js';
21
22
  const runsTable = {
@@ -105,11 +106,11 @@ const assertJitter = (name, value) => {
105
106
  }
106
107
  };
107
108
  const pickJitter = (jitterMs = 0) => {
108
- if (typeof jitterMs === 'number') {
109
+ if (isNumber(jitterMs)) {
109
110
  assertJitter('Schedule jitterMs', jitterMs);
110
111
  return jitterMs;
111
112
  }
112
- if (typeof jitterMs !== 'object' || jitterMs === null) {
113
+ if (!isObject(jitterMs)) {
113
114
  throw new TypeError('Schedule jitterMs must be a number or { maxMs }');
114
115
  }
115
116
  assertJitter('Schedule jitterMs.maxMs', jitterMs.maxMs);
@@ -121,22 +122,6 @@ const assertDelay = (name, value) => {
121
122
  throw new RangeError(`${name} must be at most ${maxDelayMs}`);
122
123
  }
123
124
  };
124
- const deadline = async (work, timeoutMs, onTimeout) => {
125
- let timer;
126
- try {
127
- await Promise.race([
128
- work,
129
- new Promise((_resolve, reject) => {
130
- timer = setTimeout(() => reject(onTimeout()), timeoutMs);
131
- }),
132
- ]);
133
- }
134
- finally {
135
- if (timer !== undefined) {
136
- clearTimeout(timer);
137
- }
138
- }
139
- };
140
125
  /**
141
126
  * Experimental. One recurring schedule per channel of a Durable Object whose
142
127
  * ticks start individually tracked, overlapping runs and report each run's
@@ -171,7 +156,7 @@ export class DurabilitySchedule {
171
156
  _DurabilitySchedule_wakeSleeper.set(this, void 0);
172
157
  __classPrivateFieldSet(this, _DurabilitySchedule_channel, assertChannel('DurabilitySchedule', config.channel ?? defaultChannel), "f");
173
158
  for (const name of ['nextOccurrence', 'run', 'onOutcome']) {
174
- if (typeof config[name] !== 'function') {
159
+ if (!isFunction(config[name])) {
175
160
  throw new TypeError(`Schedule requires a ${name} function`);
176
161
  }
177
162
  }
@@ -235,7 +220,7 @@ export class DurabilitySchedule {
235
220
  */
236
221
  async set(definition) {
237
222
  const { expression, version } = definition;
238
- if (typeof expression !== 'string' || expression.length === 0) {
223
+ if (!isNonEmptyString(expression)) {
239
224
  throw new TypeError('Schedule expression must be a non-empty string');
240
225
  }
241
226
  assertNonNegative('Schedule version', version);
@@ -258,6 +243,39 @@ export class DurabilitySchedule {
258
243
  __classPrivateFieldGet(this, _DurabilitySchedule_instances, "m", _DurabilitySchedule_wake).call(this);
259
244
  return applied;
260
245
  }
246
+ /**
247
+ * Recomputes the stored next tick with `nextOccurrence`, for when its answers
248
+ * changed for a reason durability can't see, and resolves `true` when the
249
+ * stored next tick changed. Resolves `false` when it didn't, when no schedule
250
+ * is live, or when the stored tick is already due: the alarm fires it, and
251
+ * the advance after it asks `nextOccurrence` again. The search starts from
252
+ * `now - jitterMs`, so a tick whose firing time is still ahead is kept and
253
+ * one whose firing time passed is skipped, not run. The version, the stored
254
+ * jitter, cancellations, and runs are unchanged.
255
+ */
256
+ async reschedule() {
257
+ const changed = await __classPrivateFieldGet(this, _DurabilitySchedule_engine, "f").transaction((sql) => {
258
+ const schedule = readSchedule(sql, __classPrivateFieldGet(this, _DurabilitySchedule_channel, "f"));
259
+ if (schedule === undefined || schedule.expression === null) {
260
+ return false;
261
+ }
262
+ const now = Date.now();
263
+ const dueAt = firesAt(schedule);
264
+ if (dueAt !== undefined && dueAt <= now) {
265
+ return false;
266
+ }
267
+ const nextAt = __classPrivateFieldGet(this, _DurabilitySchedule_instances, "m", _DurabilitySchedule_nextAfter).call(this, schedule.expression, now - schedule.jitter_ms) ?? null;
268
+ if (nextAt === schedule.next_at) {
269
+ return false;
270
+ }
271
+ sql.exec('UPDATE durability_schedule SET next_at = ? WHERE channel = ? AND id = 1', nextAt, __classPrivateFieldGet(this, _DurabilitySchedule_channel, "f"));
272
+ return true;
273
+ });
274
+ if (changed) {
275
+ __classPrivateFieldGet(this, _DurabilitySchedule_instances, "m", _DurabilitySchedule_wake).call(this);
276
+ }
277
+ return changed;
278
+ }
261
279
  /**
262
280
  * Stops future ticks and resolves `true` when a schedule was live. Runs
263
281
  * already due or running still finish and report. With `version`, the
@@ -381,20 +399,17 @@ _DurabilitySchedule_engine = new WeakMap(), _DurabilitySchedule_channel = new We
381
399
  if (__classPrivateFieldGet(this, _DurabilitySchedule_woken, "f")) {
382
400
  return;
383
401
  }
384
- let timer;
402
+ let cancelTimeout;
385
403
  try {
386
404
  await new Promise((resolve) => {
387
405
  __classPrivateFieldSet(this, _DurabilitySchedule_wakeSleeper, resolve, "f");
388
406
  if (until !== undefined) {
389
- const delay = Math.min(Math.max(until - Date.now(), 0), maxDelayMs);
390
- timer = setTimeout(resolve, delay);
407
+ cancelTimeout = __classPrivateFieldGet(this, _DurabilitySchedule_engine, "f").timer.schedule(resolve, until - Date.now());
391
408
  }
392
409
  });
393
410
  }
394
411
  finally {
395
- if (timer !== undefined) {
396
- clearTimeout(timer);
397
- }
412
+ cancelTimeout?.();
398
413
  __classPrivateFieldSet(this, _DurabilitySchedule_wakeSleeper, undefined, "f");
399
414
  }
400
415
  }, _DurabilitySchedule_nextWakeAt = function _DurabilitySchedule_nextWakeAt() {
@@ -552,14 +567,15 @@ async function _DurabilitySchedule_reserveSlots(mark) {
552
567
  __classPrivateFieldGet(this, _DurabilitySchedule_emit, "f").call(this, { ...__classPrivateFieldGet(this, _DurabilitySchedule_instances, "m", _DurabilitySchedule_entity).call(this, scheduledTime), type: 'started' });
553
568
  const controller = new AbortController();
554
569
  const handler = Promise.resolve().then(() => __classPrivateFieldGet(this, _DurabilitySchedule_run, "f").call(this, { ...run, signal: controller.signal }));
555
- const recorded = deadline(handler, __classPrivateFieldGet(this, _DurabilitySchedule_runTimeoutMs, "f"), () => {
570
+ const recorded = __classPrivateFieldGet(this, _DurabilitySchedule_engine, "f").timer
571
+ .withTimeout(handler, __classPrivateFieldGet(this, _DurabilitySchedule_runTimeoutMs, "f"), () => {
556
572
  const error = new ScheduledRunTimeoutError(__classPrivateFieldGet(this, _DurabilitySchedule_runTimeoutMs, "f"));
557
573
  controller.abort(error);
558
574
  return error;
559
575
  })
560
- .then(() => ({ status: 'complete' }), (error) => ({
576
+ .then(() => ({ status: 'complete' }), (cause) => ({
561
577
  status: 'errored',
562
- error: serializeError(error),
578
+ error: serializeError(cause),
563
579
  }))
564
580
  .then((outcome) => __classPrivateFieldGet(this, _DurabilitySchedule_instances, "m", _DurabilitySchedule_record).call(this, run, outcome, startedAt))
565
581
  .catch((error) => reportFailure('durability.schedule.record_failed', { scheduledTime }, error));
@@ -582,13 +598,16 @@ async function _DurabilitySchedule_reserveSlots(mark) {
582
598
  return;
583
599
  }
584
600
  const entity = __classPrivateFieldGet(this, _DurabilitySchedule_instances, "m", _DurabilitySchedule_entity).call(this, run.scheduledTime);
585
- __classPrivateFieldGet(this, _DurabilitySchedule_emit, "f").call(this, {
601
+ const settled = {
586
602
  ...entity,
587
603
  type: 'settled',
588
604
  outcome: outcome.status,
589
605
  durationMs: Math.max(0, entity.timestamp - startedAt),
590
- ...(error === undefined ? {} : { error }),
591
- });
606
+ };
607
+ if (error !== undefined) {
608
+ settled.error = error;
609
+ }
610
+ __classPrivateFieldGet(this, _DurabilitySchedule_emit, "f").call(this, settled);
592
611
  __classPrivateFieldGet(this, _DurabilitySchedule_instances, "m", _DurabilitySchedule_deliver).call(this, run, outcome, 1);
593
612
  }, _DurabilitySchedule_deliverDue = function _DurabilitySchedule_deliverDue() {
594
613
  const due = v.parse(v.array(runRowSchema), __classPrivateFieldGet(this, _DurabilitySchedule_engine, "f").sql
@@ -612,7 +631,7 @@ async function _DurabilitySchedule_reserveSlots(mark) {
612
631
  });
613
632
  }, _DurabilitySchedule_deliverOnce = async function _DurabilitySchedule_deliverOnce(run, outcome, attempt) {
614
633
  try {
615
- await deadline(Promise.resolve().then(() => __classPrivateFieldGet(this, _DurabilitySchedule_onOutcome, "f").call(this, { ...run, attempt }, outcome)), __classPrivateFieldGet(this, _DurabilitySchedule_outcomeTimeoutMs, "f"), () => new ScheduledOutcomeTimeoutError(__classPrivateFieldGet(this, _DurabilitySchedule_outcomeTimeoutMs, "f")));
634
+ await __classPrivateFieldGet(this, _DurabilitySchedule_engine, "f").timer.withTimeout(Promise.resolve().then(() => __classPrivateFieldGet(this, _DurabilitySchedule_onOutcome, "f").call(this, { ...run, attempt }, outcome)), __classPrivateFieldGet(this, _DurabilitySchedule_outcomeTimeoutMs, "f"), () => new ScheduledOutcomeTimeoutError(__classPrivateFieldGet(this, _DurabilitySchedule_outcomeTimeoutMs, "f")));
616
635
  }
617
636
  catch (failure) {
618
637
  await __classPrivateFieldGet(this, _DurabilitySchedule_instances, "m", _DurabilitySchedule_failDelivery).call(this, run, attempt, failure);
@@ -622,14 +641,14 @@ async function _DurabilitySchedule_reserveSlots(mark) {
622
641
  sql.exec(`DELETE FROM durability_schedule_runs
623
642
  WHERE channel = ? AND scheduled_time = ?`, __classPrivateFieldGet(this, _DurabilitySchedule_channel, "f"), run.scheduledTime);
624
643
  });
625
- }, _DurabilitySchedule_failDelivery = async function _DurabilitySchedule_failDelivery(run, attempt, failure) {
626
- const error = serializeError(failure);
644
+ }, _DurabilitySchedule_failDelivery = async function _DurabilitySchedule_failDelivery(run, attempt, cause) {
645
+ const error = serializeError(cause);
627
646
  if (attempt >= __classPrivateFieldGet(this, _DurabilitySchedule_maxOutcomeAttempts, "f")) {
628
647
  await __classPrivateFieldGet(this, _DurabilitySchedule_engine, "f").transaction((sql) => {
629
648
  sql.exec(`DELETE FROM durability_schedule_runs
630
649
  WHERE channel = ? AND scheduled_time = ?`, __classPrivateFieldGet(this, _DurabilitySchedule_channel, "f"), run.scheduledTime);
631
650
  });
632
- reportFailure('durability.schedule.outcome_dead_lettered', { scheduledTime: run.scheduledTime, attempt }, failure);
651
+ reportFailure('durability.schedule.outcome_dead_lettered', { scheduledTime: run.scheduledTime, attempt }, cause);
633
652
  __classPrivateFieldGet(this, _DurabilitySchedule_emit, "f").call(this, {
634
653
  ...__classPrivateFieldGet(this, _DurabilitySchedule_instances, "m", _DurabilitySchedule_entity).call(this, run.scheduledTime),
635
654
  type: 'dead_lettered',
@@ -2,6 +2,7 @@ import { type SerializedError } from '../errors.js';
2
2
  import { type DurabilityLifecycleEvent, type Emit, type LifecycleEntity } from '../lifecycle.js';
3
3
  import { type MigrationCapability } from '../migrations.js';
4
4
  import { type AttemptPolicy } from '../policy.js';
5
+ import { SharedTimer } from '../shared-timer.js';
5
6
  import { type DurableTable } from '../storage.js';
6
7
  import type { DurableMigrations } from '@durability/storage';
7
8
  /** The Durable Object state durability needs: storage plus optional `waitUntil`. */
@@ -86,27 +87,28 @@ export type ChannelParticipant = Participant & {
86
87
  channelTables?: readonly string[];
87
88
  };
88
89
  /** Rejects a channel name a helper would otherwise store rows under. */
89
- export declare const assertChannel: (helper: string, channel: unknown) => string;
90
+ export declare const assertChannel: (helper: string, channel: string) => string;
90
91
  /**
91
92
  * Called after a record may have settled. Successful completions pass the
92
93
  * executed row because some tables delete it on success; other changes pass
93
94
  * nothing and listeners re-read storage.
94
95
  */
95
- export type SettlementListener = (completed?: ExecutionSpec['row']) => void;
96
+ export type SettlementListener = (completed?: ExecutionRow) => void;
96
97
  export type ActiveExecution = {
97
98
  generation: string;
98
99
  createdAt: number;
99
100
  settled: Promise<void>;
100
101
  controller?: AbortController;
101
102
  };
103
+ type ExecutionRow = {
104
+ generation_id: string;
105
+ created_at: number;
106
+ };
102
107
  /** Everything that differs between running a durable operation and a named alarm attempt. */
103
- export type ExecutionSpec = {
108
+ export type ExecutionSpec<Result> = {
104
109
  table: DurableTable;
105
110
  key: string;
106
- row: {
107
- generation_id: string;
108
- created_at: number;
109
- };
111
+ row: ExecutionRow;
110
112
  label: string;
111
113
  entity: LifecycleEntity;
112
114
  active: Map<string, ActiveExecution>;
@@ -116,15 +118,15 @@ export type ExecutionSpec = {
116
118
  includeResult?: boolean;
117
119
  exhaustedError: () => Error;
118
120
  timeoutError: () => Error;
119
- invoke: (attempt: number, signal: AbortSignal) => unknown;
121
+ invoke: (attempt: number, signal: AbortSignal) => Result | Promise<Result>;
120
122
  /**
121
123
  * Persists a successful attempt and returns its settlement timestamp, or
122
124
  * undefined when a newer generation won. May throw to turn the success into
123
125
  * a failure.
124
126
  */
125
- complete: (result: unknown, attempt: number) => number | undefined;
127
+ complete: (result: Result, attempt: number) => number | undefined;
126
128
  /** Kind-specific terminal rule beyond non-retryable errors and exhausted attempts. */
127
- isTerminal: (error: unknown) => boolean;
129
+ isTerminal: (cause: unknown) => boolean;
128
130
  };
129
131
  /**
130
132
  * Shared machinery behind {@link DurabilityScheduler}: transactions, the physical
@@ -132,6 +134,8 @@ export type ExecutionSpec = {
132
134
  */
133
135
  export declare class Engine {
134
136
  readonly sql: SqlStorage;
137
+ /** Holds the timeouts of every helper on the object behind one native timer. */
138
+ readonly timer: SharedTimer;
135
139
  private context;
136
140
  private readonly storage;
137
141
  private alarmConcurrency;
@@ -176,7 +180,7 @@ export declare class Engine {
176
180
  * are kept and looked at again later, since their owner may return.
177
181
  */
178
182
  private postponeUnattachedChannels;
179
- waitUntil(promise: Promise<unknown>, onError: (error: unknown) => void): void;
183
+ waitUntil(promise: Promise<unknown>, onError: (cause: unknown) => void): void;
180
184
  /**
181
185
  * The owning Durable Object's ID. The public context type omits it, but the
182
186
  * `DurableObjectState` applications pass at runtime carries it.
@@ -185,6 +189,7 @@ export declare class Engine {
185
189
  emitter<Event extends {
186
190
  entityKind: string;
187
191
  type: string;
192
+ id?: string;
188
193
  } = DurabilityLifecycleEvent>(hook: ((event: Event) => void | Promise<void>) | undefined): (event: Event) => void;
189
194
  /** Applies a helper's SQLite migrations. */
190
195
  migrateSchema(capability: MigrationCapability, migrations: DurableMigrations): void;
@@ -220,7 +225,7 @@ export declare class Engine {
220
225
  /** In-memory only: listeners never survive eviction. */
221
226
  watch(table: DurableTable, key: string, listener: SettlementListener): () => void;
222
227
  /** Call only after the change has committed. */
223
- notify(table: DurableTable, key: string, completed?: ExecutionSpec['row']): void;
228
+ notify(table: DurableTable, key: string, completed?: ExecutionRow): void;
224
229
  tryAcquirePermit(): (() => void) | undefined;
225
230
  acquirePermit(): Promise<() => void>;
226
231
  private createRelease;
@@ -250,9 +255,12 @@ export declare class Engine {
250
255
  /**
251
256
  * Registers the execution in its active map synchronously, then claims and
252
257
  * runs one attempt in the background. The returned promise settles when the
253
- * attempt's outcome has been persisted, not when a timed-out handler settles.
258
+ * attempt's outcome has been persisted. The key leaves the active map and
259
+ * its permit is released then too, whether or not a timed-out handler has
260
+ * settled: nothing can stop a handler, and one that never settles would
261
+ * otherwise keep its retry from ever starting.
254
262
  */
255
- startExecution(spec: ExecutionSpec, eagerPermit?: () => void): Promise<void>;
263
+ startExecution<Result>(spec: ExecutionSpec<Result>, eagerPermit?: () => void): Promise<void>;
256
264
  private failExhausted;
257
265
  private settleFailure;
258
266
  }
@@ -289,6 +297,19 @@ export declare class DurabilityScheduler {
289
297
  constructor(config: DurabilitySchedulerConfig);
290
298
  /** Runs due work for every attached helper and re-arms the physical alarm. */
291
299
  alarm(info?: AlarmInvocationInfo): Promise<void>;
300
+ /**
301
+ * Runs `callback` once after `delayMs`, like the global `setTimeout`, and
302
+ * returns a function that cancels it. The timeout shares one native timer
303
+ * with every helper on the object, so any number of them can be pending
304
+ * without reaching the runtime's limit of 10,000 native timers.
305
+ *
306
+ * The timeout exists only in memory and an eviction drops it; schedule work
307
+ * that must survive one with `DurabilityAlarms`. Callbacks due at the same
308
+ * time run one after another in the same task, and one that throws is
309
+ * reported as `durability.timer.callback_failed` instead of being thrown.
310
+ */
311
+ setTimeout(callback: () => void, delayMs: number): () => void;
292
312
  }
293
313
  /** Resolves the engine a helper attaches to: the object's one scheduler. */
294
314
  export declare const engineFor: (attachment: SchedulerAttachment) => Engine;
315
+ export {};