durability 4.1.1 → 4.1.2

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
@@ -792,6 +792,10 @@ There is no per-record retry, timeout, or dead letter here: a log tracks positio
792
792
 
793
793
  There is also no key compaction. `deduplicationKey` is unique per retained record, which is the opposite of a compaction key, and deduplication lasts only while the original record is retained — re-appending a key after its record was flushed or deleted creates a new record.
794
794
 
795
+ ## When a run cannot finish
796
+
797
+ A Durable Object alarm whose handler throws is retried with backoff a limited number of times and then dropped. Every helper's `alarm()` ends by reconciling the physical alarm, and a storage error there would otherwise propagate, so enough of them in a row would leave pending work with nothing armed. Instead, a run that fails arms the physical alarm directly at `alarmMinDelayMs` from now and returns, reporting `durability.alarm.failed` with the error; the next run reconciles properly. Only when even that `setAlarm` fails does the failure reach the platform and its retries.
798
+
795
799
  ## Long-running alarm calls
796
800
 
797
801
  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.
@@ -117,11 +117,19 @@ export declare class Engine {
117
117
  acquirePermit(): Promise<() => void>;
118
118
  private createRelease;
119
119
  runConcurrent<Item>(items: Item[], worker: (item: Item) => Promise<void>): Promise<void>;
120
+ /**
121
+ * Runs due work and re-arms the physical alarm. A failure that would
122
+ * otherwise propagate to the platform is turned into a retry of our own,
123
+ * because the platform drops an alarm after a few failed deliveries.
124
+ */
125
+ alarm(info?: AlarmInvocationInfo): Promise<void>;
120
126
  /**
121
127
  * Runs every participant's due work, hands off to a fresh alarm if the
122
128
  * invocation approaches its wall-time limit, and re-arms the physical alarm.
123
129
  */
124
- alarm(info?: AlarmInvocationInfo): Promise<void>;
130
+ private runAlarm;
131
+ /** Arms the physical alarm directly, outside any transaction; the next run reconciles properly. */
132
+ private armFallbackAlarm;
125
133
  private armForHandoff;
126
134
  /**
127
135
  * Registers the execution in its active map synchronously, then claims and
package/dist/scheduler.js CHANGED
@@ -267,11 +267,30 @@ export class Engine {
267
267
  }
268
268
  }));
269
269
  }
270
+ /**
271
+ * Runs due work and re-arms the physical alarm. A failure that would
272
+ * otherwise propagate to the platform is turned into a retry of our own,
273
+ * because the platform drops an alarm after a few failed deliveries.
274
+ */
275
+ async alarm(info) {
276
+ try {
277
+ await this.runAlarm(info);
278
+ }
279
+ catch (error) {
280
+ // Throwing lets the platform retry, but it gives up after a few failures
281
+ // and drops the alarm, stranding pending work. Keeping our own alarm
282
+ // armed turns the failure into a retry we control instead.
283
+ if (!(await this.armFallbackAlarm())) {
284
+ throw error;
285
+ }
286
+ reportFailure('durability.alarm.failed', { retryInMs: this.alarmMinDelayMs }, error);
287
+ }
288
+ }
270
289
  /**
271
290
  * Runs every participant's due work, hands off to a fresh alarm if the
272
291
  * invocation approaches its wall-time limit, and re-arms the physical alarm.
273
292
  */
274
- async alarm(info) {
293
+ async runAlarm(info) {
275
294
  const startedAt = Date.now();
276
295
  const execution = Promise.all(this.participants.map((participant) => participant.runDue(startedAt, info))).then(() => undefined);
277
296
  void execution.catch(() => undefined);
@@ -298,6 +317,16 @@ export class Engine {
298
317
  }
299
318
  await this.scheduleNextAlarm();
300
319
  }
320
+ /** Arms the physical alarm directly, outside any transaction; the next run reconciles properly. */
321
+ async armFallbackAlarm() {
322
+ try {
323
+ await this.context.storage.setAlarm(Date.now() + this.alarmMinDelayMs);
324
+ return true;
325
+ }
326
+ catch {
327
+ return false;
328
+ }
329
+ }
301
330
  armForHandoff(timestamp) {
302
331
  return this.context.storage.transaction(async (physicalAlarm) => {
303
332
  const currentAlarm = await physicalAlarm.getAlarm();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "durability",
3
- "version": "4.1.1",
3
+ "version": "4.1.2",
4
4
  "description": "Alarm-backed durable operations and typed WebSocket sync for Cloudflare Durable Objects",
5
5
  "type": "module",
6
6
  "license": "ISC",