durability 2.0.0 → 2.1.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.
package/README.md CHANGED
@@ -1,8 +1,12 @@
1
1
  # Durability
2
2
 
3
- Alarm-backed, effectively-once operation execution for Cloudflare Durable Objects.
3
+ A small, alarm-backed independent-operation queue for Cloudflare Durable Objects.
4
4
 
5
- The package registers each operation and the first alarm in one Durable Object storage transaction. It only creates an alarm when none exists. Generated operation methods return `Promise<void>` after registration commits; they do not wait for the handler result. An alarm firing during execution attaches to the same in-memory promise. Failed calls are retried from later alarms, and a stable call ID deduplicates completed and concurrent calls. SQLite access and schema migrations are managed through `workers-qb`.
5
+ Durability is not an event-sourcing, replay-log, or workflow-orchestration engine. It registers independent operations and reconciles their earliest wake-up in one Durable Object storage transaction. Generated operation methods return `Promise<void>` after registration commits; they do not wait for the handler result. Failed calls are retried from later alarms, and a stable call ID deduplicates completed and concurrent calls. SQLite access and schema migrations are managed through `workers-qb`.
6
+
7
+ ## Migrating to v3
8
+
9
+ `purgeBefore` is now reserved by the generated durability API, so rename any operation with that name before upgrading.
6
10
 
7
11
  ```ts
8
12
  import { DurableObject } from 'cloudflare:workers';
@@ -30,6 +34,70 @@ export class ImageJobs extends DurableObject<Env> {
30
34
  }
31
35
  ```
32
36
 
37
+ ## Named alarms
38
+
39
+ Named alarms share the Durable Object's physical alarm with durable operation retries. Configure handlers through `alarms`, then schedule them through the typed method on `durability.alarm`:
40
+
41
+ ```ts
42
+ import ms from 'ms';
43
+ import { createDurability } from 'durability';
44
+ import { exponential, jitter } from 'durability/utils';
45
+
46
+ class ImageJobs extends DurableObject<Env> {
47
+ private readonly durability = createDurability(
48
+ this.ctx,
49
+ {
50
+ resizeImage: async ({ payload }) =>
51
+ this.env.IMAGES.resize(payload.imageId),
52
+ },
53
+ {
54
+ alarms: {
55
+ cleanup: async ({
56
+ scheduledTime,
57
+ attempt,
58
+ idempotencyKey,
59
+ signal,
60
+ platform,
61
+ }) => {
62
+ await this.env.CLEANUP.fetch('https://cleanup.internal/run', {
63
+ method: 'POST',
64
+ headers: { 'Idempotency-Key': idempotencyKey },
65
+ signal,
66
+ });
67
+ console.log({ scheduledTime, attempt, platform });
68
+ },
69
+ },
70
+ alarmMethods: {
71
+ cleanup: {
72
+ attemptTimeoutMs: 60_000,
73
+ retries: {
74
+ maxAttempts: 5,
75
+ delay: (attempt) => jitter(exponential(attempt)),
76
+ },
77
+ retryTimeouts: true,
78
+ },
79
+ },
80
+ }
81
+ );
82
+
83
+ scheduleCleanup() {
84
+ return this.durability.alarm.cleanup(Date.now() + ms('5 seconds'));
85
+ }
86
+
87
+ alarm(alarmInfo?: AlarmInvocationInfo) {
88
+ return this.durability.alarm(alarmInfo);
89
+ }
90
+ }
91
+ ```
92
+
93
+ Scheduling the same 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 Durable Object instance.
94
+
95
+ Each schedule receives a new internal occurrence ID. Its generated `idempotencyKey` remains stable across retries, while `attempt` starts at one and increments for every execution of that occurrence. A successful handler removes only the occurrence it executed, so it cannot delete a replacement scheduled while it was running.
96
+
97
+ Named alarms inherit the global attempt timeout and retry policy. `alarmMethods` overrides them for one name. Failures use the same jittered exponential delay as operations by default; `NonRetryableError` and exhausted attempts make the occurrence terminal. A timeout aborts the handler's `signal` and is terminal by default because the external outcome may be unknown. Set `retryTimeouts: true` only when the handler's side effects use the generated idempotency key or reconcile their outcome before retrying. If a handler ignores the signal, the scheduler retains its per-name execution lock until the handler actually settles, preventing an overlapping retry.
98
+
99
+ Named alarm handlers are still at-least-once across eviction or restart. Pass `idempotencyKey` to external systems that support deduplication.
100
+
33
101
  ## SQLite requirement
34
102
 
35
103
  The Durable Object class must use SQLite storage:
@@ -40,7 +108,7 @@ The Durable Object class must use SQLite storage:
40
108
  }
41
109
  ```
42
110
 
43
- `createDurability` migrates to the latest schema and stores calls in the `durability_calls` table. Each package migration has `up` and `down` SQL and is tracked in the namespaced `durability_migrations` table.
111
+ `createDurability` migrates to the latest schema and stores operations in `durability_calls` and named schedules in `durability_alarms`. Each package migration has `up` and `down` SQL and is tracked in the namespaced `durability_migrations` table. The v4 migration adds generation and creation timestamps; existing records receive the migration time. Rolling back to `null` removes the durability tables and `durability_migrations`, without touching application tables.
44
112
 
45
113
  Rollbacks are explicit because rolling back the initial migration deletes durable call records:
46
114
 
@@ -111,7 +179,7 @@ const handlers = {
111
179
  };
112
180
  ```
113
181
 
114
- A timed-out attempt aborts its signal and follows the normal retry policy. Abort-aware APIs stop promptly; arbitrary handler code cannot be forcibly terminated.
182
+ A timed-out operation aborts its signal and follows the normal retry policy. Named alarm timeouts remain terminal by default unless `retryTimeouts` is enabled. If a handler ignores abort, its in-memory ID lock and shared concurrency permit remain held until the real handler settles, so a same-isolate retry cannot overlap it. Across eviction or restart, delivery remains at least once.
115
183
 
116
184
  Throw `NonRetryableError` to move a call directly to `failed` without another attempt:
117
185
 
@@ -123,17 +191,36 @@ throw new NonRetryableError('Recipient permanently rejected');
123
191
 
124
192
  Errors created by `NonRetryableError` from `cloudflare:workflows` are also recognized.
125
193
 
126
- ## Delivery semantics
194
+ ## Delivery semantics and concurrency
127
195
 
128
- Calls are delivered at least once and deduplicated by ID after completion. Arbitrary external side effects cannot be made strictly exactly-once: a process can stop after the side effect succeeds but before its completion record commits. Pass the call ID to external services as an idempotency key to obtain effectively-once behavior.
196
+ Calls are delivered at least once and deduplicated by ID after completion. Arbitrary external side effects cannot be made strictly exactly-once: a process can stop after the side effect succeeds but before its completion record commits. Handlers should be idempotent, and should pass the call ID to external services as an idempotency key when supported.
197
+
198
+ `alarmConcurrency` defaults to 10 and is one FIFO concurrency limit shared by eager operation handlers, alarm-driven operation handlers, and named-alarm handlers. Newly registered operations start eagerly only when a permit is immediately available; otherwise their persisted row is left for the reconciled alarm without creating an in-memory waiter. A timed-out handler that has not settled continues to occupy its permit.
129
199
 
130
200
  Completion records are retained indefinitely so IDs remain deduplicated. The helper owns the Durable Object's alarm; compose unrelated scheduled work through the same alarm handler instead of independently replacing its alarm.
131
201
 
132
- ## Durable Object-to-Object coordination
202
+ ## Destructive retention purge
203
+
204
+ `purgeBefore(timestamp)` deletes every operation and named-alarm record whose creation time is strictly less than `timestamp`, regardless of status or scheduled time. Records created exactly at the cutoff are retained. The timestamp must be a non-negative safe integer.
133
205
 
134
- When an operation spans multiple Durable Objects, a durability-enabled coordinator can retry each step after a crash, while durability-enabled participants deduplicate those retries using stable operation IDs. This supports sagas and other two-phase coordination scenarios with eventual consistency; it does not create one atomic storage transaction across the objects.
206
+ ```ts
207
+ const removed = await this.durability.purgeBefore(retentionCutoff);
208
+ console.log(removed.operations, removed.namedAlarms, removed.total);
209
+ ```
210
+
211
+ The purge uses aggregate counts, deletes and reconciles the physical alarm in one storage transaction, and never touches application or migration tables. It best-effort aborts matching active handlers, but JavaScript cannot force an abort-ignoring handler to stop. Operation IDs can be reused immediately; a late old generation cannot overwrite the replacement record, but its already-started external side effects may still complete. A replacement named alarm remains serialized behind an abort-ignoring old handler with the same name until that handler settles or the isolate is evicted. Treat this API as intentionally destructive.
212
+
213
+ ## Lifecycle metrics hook
214
+
215
+ `onLifecycleEvent` receives compact events for registration or scheduling, attempt start and settlement, pre-invocation attempt exhaustion, and purge aggregates. Events include timestamps, attempts, identities, and generation IDs needed to attribute metrics.
216
+
217
+ ```ts
218
+ const durability = createDurability(this.ctx, handlers, {
219
+ onLifecycleEvent: (event) => recordDurabilityMetric(event),
220
+ });
221
+ ```
135
222
 
136
- Intermediate states may be visible until every participant completes. Persist the coordination state, propagate stable IDs to every participant, and explicitly handle terminal failures or compensating operations when the operation can be aborted.
223
+ The hook is best-effort and non-blocking, is not a durable journal, and may duplicate or drop events across crashes. Hook failures are reported to `console.error` and never change queue state. Returned promises are attached to `waitUntil` when the context exposes it.
137
224
 
138
225
  ## Long-running alarm calls
139
226
 
package/dist/index.d.ts CHANGED
@@ -59,6 +59,27 @@ export type DurabilityRetryOptions = {
59
59
  maxAttempts?: number;
60
60
  };
61
61
  type HandlerMap = Record<string, (...args: never[]) => unknown>;
62
+ /** Information passed to a named alarm handler for one execution attempt. */
63
+ export type DurableAlarmInfo = {
64
+ /** Configured name of the logical alarm. */
65
+ name: string;
66
+ /** Timestamp originally passed to the named alarm method. */
67
+ scheduledTime: number;
68
+ /** One-based execution attempt for this scheduled occurrence. */
69
+ attempt: number;
70
+ /** Whether this scheduled occurrence has run before. */
71
+ isRetry: boolean;
72
+ /** Number of previous attempts for this scheduled occurrence. */
73
+ retryCount: number;
74
+ /** Stable key shared by every attempt of this scheduled occurrence. */
75
+ idempotencyKey: string;
76
+ /** Aborts when the attempt exceeds its configured timeout. */
77
+ signal: AbortSignal;
78
+ /** Invocation information for the shared physical Durable Object alarm. */
79
+ platform: AlarmInvocationInfo | undefined;
80
+ };
81
+ /** A handler for one named logical alarm. */
82
+ export type DurableAlarmHandler = (info: DurableAlarmInfo) => unknown | Promise<unknown>;
62
83
  /**
63
84
  * Execution policy overrides for one durable operation method.
64
85
  *
@@ -76,11 +97,16 @@ export type DurabilityMethodOptions = {
76
97
  /** Retry policy overrides for this method. */
77
98
  retries?: DurabilityRetryOptions;
78
99
  };
100
+ /** Execution policy overrides for one named alarm. */
101
+ export type DurabilityAlarmMethodOptions = DurabilityMethodOptions & {
102
+ /** Retry timed-out attempts only when their side effects are idempotent or reconciled. */
103
+ retryTimeouts?: boolean;
104
+ };
79
105
  /**
80
106
  * Configuration for a durability instance.
81
107
  *
82
- * Method-level values override global timeout and retry values without changing
83
- * the policy for other handlers.
108
+ * Operation and named-alarm overrides replace global timeout and retry values
109
+ * without changing the policy for other handlers.
84
110
  *
85
111
  * @example
86
112
  * ```ts
@@ -97,8 +123,79 @@ export type DurabilityMethodOptions = {
97
123
  * };
98
124
  * ```
99
125
  */
100
- export type DurabilityOptions<Handlers extends HandlerMap = HandlerMap> = {
101
- /** Maximum immediate operations executed concurrently by an alarm. Defaults to 10. */
126
+ type SerializedError = {
127
+ name: string;
128
+ message: string;
129
+ };
130
+ type OperationLifecycleEntity = {
131
+ entityKind: 'operation';
132
+ operation: string;
133
+ id: string;
134
+ generation: string;
135
+ };
136
+ type AlarmLifecycleEntity = {
137
+ entityKind: 'named_alarm';
138
+ alarm: string;
139
+ id: string;
140
+ generation: string;
141
+ };
142
+ type LifecycleEntity = OperationLifecycleEntity | AlarmLifecycleEntity;
143
+ /** Best-effort metrics signal for queue lifecycle changes. */
144
+ export type DurabilityLifecycleEvent = (OperationLifecycleEntity & {
145
+ type: 'registered';
146
+ timestamp: number;
147
+ attempt: 0;
148
+ }) | (AlarmLifecycleEntity & {
149
+ type: 'scheduled';
150
+ timestamp: number;
151
+ attempt: 0;
152
+ scheduledTime: number;
153
+ }) | (LifecycleEntity & {
154
+ type: 'attempt_started';
155
+ timestamp: number;
156
+ attempt: number;
157
+ }) | (LifecycleEntity & {
158
+ type: 'attempt_settled';
159
+ timestamp: number;
160
+ attempt: number;
161
+ durationMs: number;
162
+ outcome: 'completed';
163
+ }) | (LifecycleEntity & {
164
+ type: 'attempt_settled';
165
+ timestamp: number;
166
+ attempt: number;
167
+ durationMs: number;
168
+ outcome: 'retry_scheduled';
169
+ error: SerializedError;
170
+ nextAttemptAt: number;
171
+ }) | (LifecycleEntity & {
172
+ type: 'attempt_settled';
173
+ timestamp: number;
174
+ attempt: number;
175
+ durationMs: number;
176
+ outcome: 'failed';
177
+ error: SerializedError;
178
+ }) | (LifecycleEntity & {
179
+ type: 'terminal';
180
+ timestamp: number;
181
+ attempt: number;
182
+ reason: 'attempts_exhausted';
183
+ error: SerializedError;
184
+ }) | {
185
+ type: 'purged';
186
+ entityKind: 'durability';
187
+ timestamp: number;
188
+ before: number;
189
+ operations: number;
190
+ namedAlarms: number;
191
+ total: number;
192
+ };
193
+ export type DurabilityOptions<Handlers extends HandlerMap = HandlerMap, AlarmNames extends string = never> = {
194
+ /** Named logical alarms sharing the Durable Object's physical alarm. */
195
+ alarms?: Record<AlarmNames, DurableAlarmHandler>;
196
+ /** Execution policy overrides keyed by named alarm. */
197
+ alarmMethods?: [AlarmNames] extends [never] ? never : Partial<Record<NoInfer<AlarmNames>, DurabilityAlarmMethodOptions>>;
198
+ /** Maximum handlers shared by eager operations and alarm work. Defaults to 10. */
102
199
  alarmConcurrency?: number;
103
200
  /** Time before a running alarm hands unfinished work to a new alarm. Defaults to 14 minutes. */
104
201
  alarmHandoffMs?: number;
@@ -108,6 +205,8 @@ export type DurabilityOptions<Handlers extends HandlerMap = HandlerMap> = {
108
205
  methods?: Partial<Record<Extract<keyof Handlers, string>, DurabilityMethodOptions>>;
109
206
  /** Retry policy shared by handlers without a method-level override. */
110
207
  retries?: DurabilityRetryOptions;
208
+ /** Receives best-effort, non-durable lifecycle metrics events. */
209
+ onLifecycleEvent?: (event: DurabilityLifecycleEvent) => void | Promise<void>;
111
210
  };
112
211
  type HandlerPayload<Handler> = Handler extends (call: DurableCall<infer Payload>) => unknown ? Payload : never;
113
212
  type DurableOperationInput<Handler> = {
@@ -185,9 +284,19 @@ type DurableOperation<Handler> = ((input: DurableOperationInput<Handler>) => Pro
185
284
  * const alarm = (info: AlarmInvocationInfo) => durability.alarm(info);
186
285
  * ```
187
286
  */
188
- export type Durability<Handlers extends HandlerMap> = {
189
- /** Processes due operations. Forward the Durable Object's alarm handler here. */
190
- alarm: (alarmInfo?: AlarmInvocationInfo) => Promise<void>;
287
+ type DurableNamedAlarm = (scheduledTime: number) => Promise<void>;
288
+ type DurabilityAlarm<AlarmNames extends string> = ((alarmInfo?: AlarmInvocationInfo) => Promise<void>) & Record<AlarmNames, DurableNamedAlarm>;
289
+ /** Aggregate counts returned by a destructive purge. */
290
+ export type DurablePurgeResult = {
291
+ operations: number;
292
+ namedAlarms: number;
293
+ total: number;
294
+ };
295
+ export type Durability<Handlers extends HandlerMap, AlarmNames extends string = never> = {
296
+ /** Processes due work and exposes methods for scheduling named alarms. */
297
+ alarm: DurabilityAlarm<AlarmNames>;
298
+ /** Destructively removes all queue records created before a timestamp. */
299
+ purgeBefore: (timestamp: number) => Promise<DurablePurgeResult>;
191
300
  } & {
192
301
  [Operation in keyof Handlers]: DurableOperation<Handlers[Operation]>;
193
302
  };
@@ -290,6 +399,22 @@ export declare class NonRetryableError extends Error {
290
399
  export declare class DurableAttemptTimeoutError extends Error {
291
400
  constructor(operation: string, timeoutMs: number);
292
401
  }
402
+ /** Error recorded when a named alarm attempt exceeds its configured timeout. */
403
+ export declare class DurableAlarmTimeoutError extends Error {
404
+ constructor(name: string, timeoutMs: number);
405
+ }
406
+ /** Error persisted when retry-delay evaluation fails or is unsafe. */
407
+ export declare class DurableRetryPolicyError extends Error {
408
+ constructor(entity: string, reason?: unknown);
409
+ }
410
+ /** Error persisted when a successful result cannot be JSON-serialized. */
411
+ export declare class DurableResultSerializationError extends Error {
412
+ constructor(operation: string, reason?: unknown);
413
+ }
414
+ /** Error persisted when pending work has already reached its attempt limit. */
415
+ export declare class DurableAttemptsExhaustedError extends Error {
416
+ constructor(entity: 'operation' | 'named alarm', name: string, max: number);
417
+ }
293
418
  /**
294
419
  * Error thrown when an idempotency key is reused for another operation.
295
420
  *
@@ -306,45 +431,5 @@ export declare class DurableAttemptTimeoutError extends Error {
306
431
  export declare class DuplicateDurableCallError extends Error {
307
432
  constructor(id: string, existingOperation: string, requestedOperation: string);
308
433
  }
309
- /**
310
- * Creates typed, alarm-backed durable methods from an operation handler map.
311
- *
312
- * Registered calls persist before execution and are deduplicated by their IDs.
313
- * Generated methods resolve after registration; read handler results with each
314
- * method's `getResult` function.
315
- *
316
- * The Durable Object class must use SQLite storage, and its `alarm` method must
317
- * delegate to the returned alarm handler. External side effects should use the
318
- * call ID as an idempotency key because a crash can occur after a side effect but
319
- * before the completion record commits.
320
- *
321
- * @example
322
- * ```ts
323
- * class ImageJobs extends DurableObject<Env> {
324
- * private readonly durability = createDurability(this.ctx, {
325
- * resizeImage: async ({ id, payload, signal }) =>
326
- * this.env.IMAGES.resize(payload.imageId, {
327
- * idempotencyKey: id,
328
- * signal,
329
- * }),
330
- * });
331
- *
332
- * resize(imageId: string) {
333
- * return this.durability.resizeImage({
334
- * id: `resize:${imageId}`,
335
- * payload: { imageId },
336
- * });
337
- * }
338
- *
339
- * alarm(info: AlarmInvocationInfo) {
340
- * return this.durability.alarm(info);
341
- * }
342
- * }
343
- * ```
344
- *
345
- * @param context Durable Object context containing SQLite-backed storage.
346
- * @param handlers Operation handlers keyed by their public method names.
347
- * @param options Concurrency, timeout, and retry policy configuration.
348
- */
349
- export declare const createDurability: <Handlers extends HandlerMap>(context: Pick<DurableObjectState, "storage">, handlers: Handlers, options?: DurabilityOptions<Handlers>) => Durability<Handlers>;
434
+ export declare const createDurability: <Handlers extends HandlerMap, const AlarmNames extends string = never>(context: Pick<DurableObjectState, "storage"> & Partial<Pick<DurableObjectState, "waitUntil">>, handlers: Handlers, options?: DurabilityOptions<Handlers, AlarmNames>) => Durability<Handlers, AlarmNames>;
350
435
  export {};