durability 3.0.0 → 3.0.1

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.
package/README.md CHANGED
@@ -119,6 +119,8 @@ export class Subscription extends DurableObject<Env> {
119
119
 
120
120
  Scheduling a name again replaces its pending occurrence. If that name is already running, the current handler continues and the replacement runs afterward. Different names may run concurrently, but one name never has more than one active handler in the same instance.
121
121
 
122
+ Named alarms inside the scheduler's `alarmMinDelayMs` window start from an in-memory timer at their requested time. The option accepts 1 to 15 seconds and defaults to 15 seconds; the scheduler never sets the physical alarm sooner than that delay; the physical alarm remains as a durable fallback for restarts. If concurrency capacity is full when the timer fires, execution waits in the shared FIFO queue. The scheduling method resolves after persistence and never waits for the handler to finish.
123
+
122
124
  Each occurrence receives a new internal generation. Its `idempotencyKey` stays stable across retries while `attempt` increments. A successful handler removes only the occurrence it executed, so it cannot delete a replacement scheduled while it was running.
123
125
 
124
126
  A timeout aborts the handler's `signal` and is terminal by default because the external outcome is unknown. Set `retryTimeouts: true` only when the handler's side effects use the idempotency key or reconcile their outcome before retrying. Named alarms remain at-least-once across eviction or restart.
@@ -134,6 +136,7 @@ export class ImageJobs extends DurableObject<Env> {
134
136
  private readonly scheduler = new DurabilityScheduler({
135
137
  context: this.ctx,
136
138
  alarmConcurrency: 10,
139
+ alarmMinDelayMs: 15_000,
137
140
  });
138
141
 
139
142
  private readonly durability = new Durability({
@@ -155,7 +158,7 @@ export class ImageJobs extends DurableObject<Env> {
155
158
  }
156
159
  ```
157
160
 
158
- A helper configured with `context` instead of `scheduler` creates a private scheduler and accepts the scheduler options (`storageBackend`, `alarmConcurrency`, `alarmHandoffMs`) in the same object. Two helpers on the same object must share one scheduler; otherwise each would reconcile the physical alarm against only its own records.
161
+ A helper configured with `context` instead of `scheduler` creates a private scheduler and accepts the scheduler options (`storageBackend`, `alarmConcurrency`, `alarmMinDelayMs`, `alarmHandoffMs`) in the same object. Two helpers on the same object must share one scheduler; otherwise each would reconcile the physical alarm against only its own records.
159
162
 
160
163
  ## Storage backends
161
164
 
@@ -238,7 +241,7 @@ Throw `NonRetryableError` to move work directly to `failed` without another atte
238
241
 
239
242
  Work is delivered at least once. A process can stop after a side effect succeeds but before its completion record commits, so handlers should be idempotent and pass the call ID or alarm `idempotencyKey` to external services.
240
243
 
241
- `alarmConcurrency` defaults to 10 and is one FIFO limit shared by eager operation handlers, alarm-driven operation handlers, and named alarm handlers attached to the same scheduler. Newly registered operations start eagerly only when a permit is immediately available; otherwise the reconciled alarm picks them up.
244
+ `alarmConcurrency` defaults to 10 and is one FIFO limit shared by eager operation handlers, timer-driven work, and physical-alarm work attached to the same scheduler. Newly registered operations start eagerly only when a permit is immediately available. Work due before the physical-alarm minimum enters the same queue when its in-memory timer fires.
242
245
 
243
246
  Completion records are retained indefinitely so IDs remain deduplicated. The scheduler owns the Durable Object's alarm; compose unrelated scheduled work as named alarms instead of replacing the physical alarm.
244
247
 
@@ -416,4 +419,4 @@ Loopback namespaces need the application DO declared in Wrangler migrations (or
416
419
 
417
420
  ## Long-running alarm calls
418
421
 
419
- Alarm invocations have a 15-minute wall-time limit. If work is still pending after `alarmHandoffMs` (default 14 minutes), the scheduler retains its promise in memory, arms an immediate alarm, and returns from the current invocation. The next alarm attaches to the same promise instead of starting the handler again. If the object is evicted during a handoff, the next alarm reconstructs and executes the persisted pending work.
422
+ Alarm invocations have a 15-minute wall-time limit. If work is still pending after `alarmHandoffMs` (default 14 minutes), the scheduler retains its promise in memory, arms a fallback after `alarmMinDelayMs`, and returns from the current invocation. The next alarm attaches to the same promise instead of starting the handler again. If the object is evicted during a handoff, the next alarm reconstructs and executes the persisted pending work.
@@ -94,7 +94,7 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
94
94
  }
95
95
  const generation = crypto.randomUUID();
96
96
  const createdAt = Date.now();
97
- await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").storage.transaction(async (transaction) => {
97
+ await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").transaction(async (transaction) => {
98
98
  await transaction.alarms.upsert({
99
99
  name,
100
100
  generation_id: generation,
@@ -126,7 +126,7 @@ _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap()
126
126
  const generation = crypto.randomUUID();
127
127
  let inserted = false;
128
128
  let winner;
129
- await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").storage.transaction(async (transaction) => {
129
+ await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").transaction(async (transaction) => {
130
130
  inserted = await transaction.calls.insert({
131
131
  id: input.id,
132
132
  operation: input.operation,
package/dist/fanout.js CHANGED
@@ -110,7 +110,7 @@ export class DurabilityFanout {
110
110
  }
111
111
  const registered = [];
112
112
  try {
113
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").storage.transaction(async (transaction) => {
113
+ await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").transaction(async (transaction) => {
114
114
  registered.length = 0;
115
115
  const store = transaction.deliveries;
116
116
  for (const entry of entries) {
@@ -234,7 +234,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
234
234
  continue;
235
235
  }
236
236
  // eslint-disable-next-line no-await-in-loop
237
- const attempt = await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").storage.transaction(async (transaction) => {
237
+ const attempt = await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").transaction(async (transaction) => {
238
238
  const claimed = await transaction.deliveries.claimAttempt(row.id, row.generation_id, policy.maxAttempts);
239
239
  if (claimed !== undefined) {
240
240
  await transaction.deliveries.settle(row.id, row.generation_id, claimed, {
@@ -256,7 +256,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
256
256
  release();
257
257
  }
258
258
  }, _DurabilityFanout_postpone = async function _DurabilityFanout_postpone(rows) {
259
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").storage.transaction(async (transaction) => {
259
+ await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").transaction(async (transaction) => {
260
260
  for (const row of rows) {
261
261
  // eslint-disable-next-line no-await-in-loop
262
262
  await transaction.deliveries.settle(row.id, row.generation_id, row.attempt, {
@@ -408,7 +408,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
408
408
  deadLetter: () => settle('deadLetter', () => __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_deadLetter).call(this, state.claim, 'explicit')),
409
409
  };
410
410
  }, _DurabilityFanout_remove = async function _DurabilityFanout_remove(row) {
411
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").storage.transaction(async (transaction) => {
411
+ await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").transaction(async (transaction) => {
412
412
  if (!(await transaction.deliveries.remove(row.id, row.generation_id, row.attempt))) {
413
413
  throw new FanoutSettlementError(row.id);
414
414
  }
@@ -435,7 +435,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
435
435
  await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_deadLetter).call(this, claim, 'exhausted', serializeError(caught));
436
436
  return;
437
437
  }
438
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").storage.transaction(async (transaction) => {
438
+ await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").transaction(async (transaction) => {
439
439
  const updated = await transaction.deliveries.settle(row.id, row.generation_id, row.attempt, {
440
440
  next_attempt_at: nextAttemptAt,
441
441
  last_error: error.message,
@@ -465,7 +465,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
465
465
  : { name: row.last_error_name ?? 'Error', message: row.last_error });
466
466
  // Persist intent BEFORE external I/O: eviction or timeout must never turn
467
467
  // a terminal decision into another consumer delivery.
468
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").storage.transaction(async (transaction) => {
468
+ await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").transaction(async (transaction) => {
469
469
  const updated = await transaction.deliveries.settle(row.id, row.generation_id, row.attempt, {
470
470
  phase: 'dead_letter',
471
471
  dead_lettered_at: timestamp,
@@ -12,6 +12,8 @@ export type DurabilitySchedulerOptions = {
12
12
  storageBackend?: DurabilityStorageBackend;
13
13
  /** Maximum handlers running at once across eager operations and alarm work. Defaults to 10. */
14
14
  alarmConcurrency?: number;
15
+ /** Physical-alarm delay from 1 to 15 seconds. Defaults to 15 seconds. */
16
+ alarmMinDelayMs?: number;
15
17
  /** Time before a running alarm hands unfinished work to a new alarm. Defaults to 14 minutes. */
16
18
  alarmHandoffMs?: number;
17
19
  };
@@ -71,18 +73,24 @@ export declare class Engine {
71
73
  private readonly backend;
72
74
  private readonly context;
73
75
  private readonly alarmConcurrency;
76
+ private readonly alarmMinDelayMs;
74
77
  private readonly alarmHandoffMs;
75
78
  private readonly participants;
76
79
  private availablePermits;
77
80
  private readonly permitWaiters;
78
81
  private alarmRefresh;
82
+ private earlyAlarm;
83
+ private readonly transactionReconciliations;
79
84
  constructor(context: DurabilityContext, options: DurabilitySchedulerOptions);
80
85
  register(participant: Participant): void;
81
86
  waitUntil(promise: Promise<unknown>, onError: (error: unknown) => void): void;
82
87
  emitter(hook: LifecycleHook | undefined): Emit;
83
88
  /** Applies a helper's SQLite migrations; KV storage has no schema. */
84
89
  migrateSchema(capability: MigrationCapability, migrations: DurableMigrations): void;
90
+ /** Runs a storage transaction and publishes its timer state only after commit. */
91
+ transaction<T>(callback: (transaction: DurabilityStorageTransaction) => Promise<T>): Promise<T>;
85
92
  reconcile(transaction: DurabilityStorageTransaction): Promise<void>;
93
+ private scheduleEarlyAlarm;
86
94
  /** Coalesces concurrent refresh requests into one reconciliation transaction. */
87
95
  scheduleNextAlarm(): Promise<void>;
88
96
  /**
package/dist/scheduler.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import { DurableRetryPolicyError, isErrorInstance, isNonRetryable, serializeError, } from './errors.js';
2
+ import { DurableRetryPolicyError, isErrorInstance, isNonRetryable, reportFailure, serializeError, } from './errors.js';
3
3
  import { createKvDurabilityStorage } from './kv-storage.js';
4
4
  import { createEmitter, } from './lifecycle.js';
5
5
  import { migrate } from './migrations.js';
@@ -7,6 +7,8 @@ import { assertPositiveInteger } from './policy.js';
7
7
  import { createSqliteDurabilityStorage } from './sqlite-storage.js';
8
8
  import { reconcilePhysicalAlarm, } from './storage.js';
9
9
  const storageBackendSchema = z.enum(['sqlite', 'kv']);
10
+ const minAlarmDelayMs = 1000;
11
+ const maxAlarmDelayMs = 15000;
10
12
  const decideRetry = (spec, attempt, error) => {
11
13
  const terminal = isNonRetryable(error) ||
12
14
  attempt >= spec.policy.maxAttempts ||
@@ -53,6 +55,7 @@ export class Engine {
53
55
  constructor(context, options) {
54
56
  this.participants = [];
55
57
  this.permitWaiters = [];
58
+ this.transactionReconciliations = new WeakMap();
56
59
  this.context = context;
57
60
  this.backend = storageBackendSchema.parse(options.storageBackend ?? 'sqlite');
58
61
  this.storage =
@@ -60,8 +63,14 @@ export class Engine {
60
63
  ? createKvDurabilityStorage(context.storage)
61
64
  : createSqliteDurabilityStorage(context.storage);
62
65
  this.alarmConcurrency = options.alarmConcurrency ?? 10;
66
+ this.alarmMinDelayMs = options.alarmMinDelayMs ?? 15000;
63
67
  this.alarmHandoffMs = options.alarmHandoffMs ?? 14 * 60000;
64
68
  assertPositiveInteger('alarmConcurrency', this.alarmConcurrency);
69
+ assertPositiveInteger('alarmMinDelayMs', this.alarmMinDelayMs);
70
+ if (this.alarmMinDelayMs < minAlarmDelayMs ||
71
+ this.alarmMinDelayMs > maxAlarmDelayMs) {
72
+ throw new RangeError(`alarmMinDelayMs must be between ${minAlarmDelayMs} and ${maxAlarmDelayMs}`);
73
+ }
65
74
  assertPositiveInteger('alarmHandoffMs', this.alarmHandoffMs);
66
75
  this.availablePermits = this.alarmConcurrency;
67
76
  }
@@ -91,17 +100,61 @@ export class Engine {
91
100
  migrate(this.context.storage, capability, migrations, undefined);
92
101
  }
93
102
  }
94
- reconcile(transaction) {
95
- return reconcilePhysicalAlarm(transaction, this.participants.map(({ kind }) => kind));
103
+ /** Runs a storage transaction and publishes its timer state only after commit. */
104
+ async transaction(callback) {
105
+ let reconciliation;
106
+ const result = await this.storage.transaction(async (transaction) => {
107
+ reconciliation = { nextPendingAt: undefined, reconciled: false };
108
+ this.transactionReconciliations.set(transaction, reconciliation);
109
+ try {
110
+ return await callback(transaction);
111
+ }
112
+ finally {
113
+ this.transactionReconciliations.delete(transaction);
114
+ }
115
+ });
116
+ if (reconciliation?.reconciled) {
117
+ this.scheduleEarlyAlarm(reconciliation.nextPendingAt);
118
+ }
119
+ return result;
120
+ }
121
+ async reconcile(transaction) {
122
+ const reconciliation = this.transactionReconciliations.get(transaction);
123
+ if (!reconciliation) {
124
+ throw new Error('Scheduler reconciliation requires an Engine transaction');
125
+ }
126
+ reconciliation.nextPendingAt = await reconcilePhysicalAlarm(transaction, this.participants.map(({ kind }) => kind), this.alarmMinDelayMs);
127
+ reconciliation.reconciled = true;
128
+ }
129
+ scheduleEarlyAlarm(timestamp) {
130
+ if (this.earlyAlarm?.timestamp === timestamp) {
131
+ return;
132
+ }
133
+ if (this.earlyAlarm) {
134
+ clearTimeout(this.earlyAlarm.timer);
135
+ this.earlyAlarm = undefined;
136
+ }
137
+ if (timestamp === undefined ||
138
+ timestamp >= Date.now() + this.alarmMinDelayMs) {
139
+ return;
140
+ }
141
+ const timer = setTimeout(() => {
142
+ if (this.earlyAlarm?.timer !== timer) {
143
+ return;
144
+ }
145
+ this.earlyAlarm = undefined;
146
+ const onError = (error) => reportFailure('durability.background_execution.failed', { scheduledTime: timestamp }, error);
147
+ const execution = this.alarm().catch(onError);
148
+ this.waitUntil(execution, onError);
149
+ }, Math.max(timestamp - Date.now(), 0));
150
+ this.earlyAlarm = { timestamp, timer };
96
151
  }
97
152
  /** Coalesces concurrent refresh requests into one reconciliation transaction. */
98
153
  scheduleNextAlarm() {
99
154
  if (this.alarmRefresh) {
100
155
  return this.alarmRefresh;
101
156
  }
102
- this.alarmRefresh = this.storage
103
- .transaction((transaction) => this.reconcile(transaction))
104
- .finally(() => {
157
+ this.alarmRefresh = this.transaction((transaction) => this.reconcile(transaction)).finally(() => {
105
158
  this.alarmRefresh = undefined;
106
159
  });
107
160
  return this.alarmRefresh;
@@ -123,7 +176,7 @@ export class Engine {
123
176
  let removed = 0;
124
177
  do {
125
178
  // eslint-disable-next-line no-await-in-loop
126
- removed = await this.storage.transaction(async (transaction) => {
179
+ removed = await this.transaction(async (transaction) => {
127
180
  const count = await transaction[kind].deleteCreatedBefore(before);
128
181
  await this.reconcile(transaction);
129
182
  return count;
@@ -210,8 +263,9 @@ export class Engine {
210
263
  armForHandoff(timestamp) {
211
264
  return this.storage.transaction(async ({ physicalAlarm }) => {
212
265
  const currentAlarm = await physicalAlarm.getAlarm();
213
- if (currentAlarm === null || currentAlarm > timestamp) {
214
- await physicalAlarm.setAlarm(timestamp);
266
+ const target = Math.max(timestamp, Date.now() + this.alarmMinDelayMs);
267
+ if (currentAlarm === null || currentAlarm > target) {
268
+ await physicalAlarm.setAlarm(target);
215
269
  }
216
270
  });
217
271
  }
@@ -317,7 +371,7 @@ export class Engine {
317
371
  }
318
372
  const exhausted = serializeError(spec.exhaustedError());
319
373
  let updated = false;
320
- await this.storage.transaction(async (transaction) => {
374
+ await this.transaction(async (transaction) => {
321
375
  updated = await transaction[spec.kind].exhaust(key, row.generation_id, policy.maxAttempts, {
322
376
  status: 'failed',
323
377
  last_error: exhausted.message,
@@ -341,7 +395,7 @@ export class Engine {
341
395
  const decision = decideRetry(spec, attempt, caught);
342
396
  const serializedError = serializeError(decision.error);
343
397
  let updated = false;
344
- await this.storage.transaction(async (transaction) => {
398
+ await this.transaction(async (transaction) => {
345
399
  updated = await transaction[spec.kind].settle(key, row.generation_id, attempt, {
346
400
  status: decision.terminal ? 'failed' : 'pending',
347
401
  next_attempt_at: decision.nextAttemptAt,
package/dist/storage.d.ts CHANGED
@@ -130,5 +130,5 @@ export type DurabilityStorageTransaction = RecordStores & {
130
130
  export type DurabilityStorage = RecordStores & {
131
131
  transaction<T>(callback: (transaction: DurabilityStorageTransaction) => Promise<T>): Promise<T>;
132
132
  };
133
- /** Points the shared physical alarm at the earliest pending record among the given kinds. */
134
- export declare const reconcilePhysicalAlarm: (transaction: DurabilityStorageTransaction, kinds: readonly RecordKind[]) => Promise<void>;
133
+ /** Returns the earliest pending time and maintains its bounded physical fallback. */
134
+ export declare const reconcilePhysicalAlarm: (transaction: DurabilityStorageTransaction, kinds: readonly RecordKind[], minimumDelayMs: number) => Promise<number | undefined>;
package/dist/storage.js CHANGED
@@ -50,8 +50,8 @@ export const deliveryRowSchema = z.object({
50
50
  dead_lettered_at: z.number().int().nonnegative().nullable(),
51
51
  dead_letter_reason: z.enum(['explicit', 'exhausted']).nullable(),
52
52
  });
53
- /** Points the shared physical alarm at the earliest pending record among the given kinds. */
54
- export const reconcilePhysicalAlarm = async (transaction, kinds) => {
53
+ /** Returns the earliest pending time and maintains its bounded physical fallback. */
54
+ export const reconcilePhysicalAlarm = async (transaction, kinds, minimumDelayMs) => {
55
55
  const candidates = await Promise.all(kinds.map((kind) => transaction[kind].nextPendingAt()));
56
56
  const scheduled = candidates.filter((value) => value !== undefined);
57
57
  const nextAlarmAt = scheduled.length === 0 ? undefined : Math.min(...scheduled);
@@ -60,10 +60,14 @@ export const reconcilePhysicalAlarm = async (transaction, kinds) => {
60
60
  if (currentAlarm !== null) {
61
61
  await transaction.physicalAlarm.deleteAlarm();
62
62
  }
63
- return;
63
+ return undefined;
64
64
  }
65
- const target = Math.max(nextAlarmAt, Date.now());
66
- if (currentAlarm !== target) {
65
+ const target = Math.max(nextAlarmAt, Date.now() + minimumDelayMs);
66
+ // Preserve a fallback inside this range so frequent reconciliation cannot push it later.
67
+ if (currentAlarm === null ||
68
+ currentAlarm < nextAlarmAt ||
69
+ currentAlarm > target) {
67
70
  await transaction.physicalAlarm.setAlarm(target);
68
71
  }
72
+ return nextAlarmAt;
69
73
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "durability",
3
- "version": "3.0.0",
3
+ "version": "3.0.1",
4
4
  "description": "Alarm-backed durable operations for Cloudflare Durable Objects",
5
5
  "type": "module",
6
6
  "license": "ISC",
@@ -47,8 +47,8 @@
47
47
  ],
48
48
  "dependencies": {
49
49
  "zod": "^4.4.3",
50
- "@durability/storage": "^0.1.1",
51
- "@durability/transforms": "^0.3.0"
50
+ "@durability/transforms": "^0.3.0",
51
+ "@durability/storage": "^0.1.1"
52
52
  },
53
53
  "peerDependencies": {
54
54
  "@cloudflare/workers-types": "^4.20260702.1"