durability 4.3.0 → 5.0.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
@@ -2,7 +2,7 @@
2
2
 
3
3
  Composable capabilities for application-owned Cloudflare Durable Objects:
4
4
 
5
- - **`Durability`** — effectively-once operations with retries, idempotency, and result lookup.
5
+ - **`Durability`** — at-least-once operations with stable idempotency keys, retries, and result lookup.
6
6
  - **`DurabilityAlarms`** — named logical alarms with retries and stable idempotency keys.
7
7
  - **`DurabilityFanout`** — durable batch acceptance and independent delivery to static consumer or storage targets.
8
8
  - **`DurabilityOutbox`** _(experimental, `durability/experimental`)_ — keyed latest-state publication: stage the newest value for a key with the state it describes, and it is republished until acknowledged.
@@ -14,7 +14,47 @@ Composable capabilities for application-owned Cloudflare Durable Objects:
14
14
 
15
15
  Durable capabilities own their storage and migrations. Routing observations are in-memory and advisory. When an object composes durable capabilities, one `DurabilityScheduler` shares its physical alarm and concurrency pool. No queue factory, generated DO class, or special consumer superclass is required.
16
16
 
17
- Durability is not an event-sourcing, replay-log, or workflow-orchestration engine. Operation methods return `Promise<void>` after registration commits; they do not wait for the handler result. Failed work is retried from later alarms. Only SQLite-backed Durable Object classes are supported.
17
+ Durability is not an event-sourcing, replay-log, or workflow-orchestration engine: [memoized](#memoize) results only last while one operation or alarm occurrence is retried, and are deleted when it settles. Operation methods return `Promise<void>` after registration commits; they do not wait for the handler result. Failed work is retried from later alarms. Only SQLite-backed Durable Object classes are supported.
18
+
19
+ ## Delivery and safety contract
20
+
21
+ Durability executes work **at least once** with a stable idempotency key per operation or named alarm. "Effectively once" is a business outcome you earn by making the receiver deduplicate that key or reconcile an uncertain prior outcome; it is never an unconditional platform guarantee. Read this before copying an example that mutates an external system.
22
+
23
+ | Concern | Guarantee |
24
+ | -------------------------- | ---------------------------------------------------------------------------- |
25
+ | Registration / scheduling | Exactly once — the durable record commits atomically or not at all. |
26
+ | Local completion record | Deduplicated by the stable key, so retries never double-record a result. |
27
+ | Handler delivery | At least once — a handler may run again after a crash, timeout, or eviction. |
28
+ | External side effect | At least once — the library cannot close a cross-system transaction. |
29
+ | "Effectively once" outcome | Your responsibility — requires an idempotent or reconciling receiver. |
30
+
31
+ The unavoidable window: a handler asks an external system to commit an effect, the system commits it, then the acknowledgement is lost or the object stops before the local completion record commits. Durability retries the same stable key. Pass that key (`DurableCall.id`, or an alarm handler's `idempotencyKey`) to the external system so it can collapse the duplicate. An HTTP success — or failure — is not proof of the committed outcome after a lost acknowledgement.
32
+
33
+ The stable key is the call `id` you choose (or an alarm name). Namespace it per logical operation (`resize:${imageId}`), keep it stable across retries, and never reuse one key for different payloads: an ID stays bound to its operation and payload for the life of the record. A receiver-side idempotency table turns at-least-once delivery into an effectively-once effect by keying committed effects on it:
34
+
35
+ ```ts
36
+ // In the receiving Durable Object, keyed on the caller's stable id.
37
+ async chargeOnce(key: string, amountCents: number) {
38
+ const prior = this.ctx.storage.sql
39
+ .exec<{ result: string }>('SELECT result FROM charges WHERE key = ?', key)
40
+ .toArray();
41
+ if (prior.length > 0) {
42
+ return JSON.parse(prior[0]!.result); // replay: return the first committed outcome
43
+ }
44
+
45
+ const result = await this.gateway.charge(amountCents);
46
+ this.ctx.storage.sql.exec(
47
+ 'INSERT INTO charges (key, result) VALUES (?, ?)',
48
+ key,
49
+ JSON.stringify(result)
50
+ );
51
+ return result;
52
+ }
53
+ ```
54
+
55
+ The sketch assumes one call per key at a time; the gateway `await` lets other requests interleave, so concurrent calls for the same key need a pending row or the gateway's own idempotency key.
56
+
57
+ When a receiver can neither deduplicate the key nor reconcile the prior outcome, do not retry the effect automatically: compensate (a saga) or require a human decision instead.
18
58
 
19
59
  ## Migrating to v3
20
60
 
@@ -128,7 +168,7 @@ Scheduling a name again replaces its pending occurrence. If that name is already
128
168
 
129
169
  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.
130
170
 
131
- 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.
171
+ Each occurrence receives a new internal generation. Its `idempotencyKey` stays stable across retries, while `attempt` records which attempt the handler is running. The ordinal advances each time an attempt is claimed and is retry context, not a unique per-handler-entry token (see [Identity and attempt numbers](#identity-and-attempt-numbers)). A successful handler removes only the occurrence it executed, so it cannot delete a replacement scheduled while it was running.
132
172
 
133
173
  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
174
 
@@ -167,6 +207,36 @@ export class ImageJobs extends DurableObject<Env> {
167
207
 
168
208
  A helper configured with `context` instead of `scheduler` creates a private scheduler and accepts the scheduler options (`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.
169
209
 
210
+ ## Memoize
211
+
212
+ A retried attempt runs the whole handler again. Wrap work that must not repeat in `memoize(key, callback)`, which operation handlers, named alarm handlers, and [fanout messages](#independent-delivery) all receive. Once a key's callback succeeds, its result is persisted and every later call with that key returns it instead of running the callback:
213
+
214
+ ```ts
215
+ const deliver = async ({ payload, memoize }: DurableCall<Batch>) => {
216
+ const targets = await memoize('targets', () => lookUpTargets(payload));
217
+ const results = await Promise.allSettled(
218
+ targets.map((target) =>
219
+ memoize(`send:${target.id}`, () => send(target, payload.events))
220
+ )
221
+ );
222
+ const failed = results.filter((result) => result.status === 'rejected');
223
+ if (failed.length > 0) {
224
+ throw new AggregateError(failed.map((result) => result.reason));
225
+ }
226
+ };
227
+ ```
228
+
229
+ Here a retry sends only to the targets that failed, and does not look them up again.
230
+
231
+ - **Keys.** A key is a non-empty string that identifies one piece of work within the operation or alarm occurrence. Calling a key again returns its result, whether the call comes from a later attempt, later in the same attempt, or from inside another key's callback. A call for a key whose callback is still running rejects instead of waiting, including one made from that callback, which would otherwise wait on itself; await the first call instead.
232
+ - **Results.** A callback that throws persists nothing; the next call with that key runs it again. Results must be JSON-serializable, and `memoize` returns the persisted form even on the first run, so a replay sees the same value. A result that cannot be serialized fails the work with `DurableMemoSerializationError` and no retry.
233
+ - **Ownership.** Only the attempt that owns the record can run or persist a callback. Once its alarm is rescheduled or its record purged, a `memoize` call rejects without running, and one already running rejects instead of writing.
234
+ - **Limits.** One operation, alarm occurrence, or fanout delivery may memoize at most `maxMemosPerRecord` (1,000) keys, and each serialized result may be at most `maxMemoBytes` (1 MiB) of UTF-8. A call that would exceed either fails the work with `DurableMemoLimitError` and no retry; a key that would exceed the count is rejected before its callback runs.
235
+ - **Cleanup.** Memoized results are deleted in the transaction that settles the operation (completed or failed), the alarm occurrence, or the fanout delivery (acked or dead-lettered), when a named alarm is rescheduled, and by `purgeBefore`. Nothing is kept once the work is done.
236
+ - **Tracking.** Pending operations and alarms list their memoized keys as `state.memoized` in [`DurabilityTracker`](#tracking-work-experimental) records, in the order they were saved. Results themselves are not exposed.
237
+
238
+ Memoizing does not change delivery semantics. A process can stop after a callback's side effect succeeds but before its result commits, so the callback can run again; keep its side effects idempotent.
239
+
170
240
  ## Storage
171
241
 
172
242
  Durability stores its records in the object's SQLite database. Configure the Durable Object class with `new_sqlite_classes`:
@@ -177,7 +247,7 @@ Durability stores its records in the object's SQLite database. Configure the Dur
177
247
  }
178
248
  ```
179
249
 
180
- `Durability` creates and migrates `durability_calls`; `DurabilityAlarms` does the same for `durability_alarms`. Both histories are tracked in the shared `durability_migrations` table and only the constructed helpers' tables exist.
250
+ `Durability` creates and migrates `durability_calls`; `DurabilityAlarms` does the same for `durability_alarms`. Both also create `durability_memos`, which they share. All histories are tracked in the shared `durability_migrations` table and only the constructed helpers' tables exist. Reverting either helper's schema leaves `durability_memos` in place for the other.
181
251
 
182
252
  ### Explicit migrations
183
253
 
@@ -252,14 +322,48 @@ Each attempt receives its own `AbortSignal`. A timed-out operation follows the n
252
322
 
253
323
  Throw `NonRetryableError` to move work directly to `failed` without another attempt. Errors named `NonRetryableError` from other packages, such as `cloudflare:workflows`, are recognized too.
254
324
 
325
+ ## Identity and attempt numbers
326
+
327
+ A handler receives several identifiers; only some are stable:
328
+
329
+ - **Operation `id`** (operations) and **`idempotencyKey`** (named alarms) are the logical identity. They are stable across every attempt and retry, so they are the only safe deduplication keys for downstream services.
330
+ - **`operation` / `name`** is the handler the work was registered under.
331
+ - **`attempt`** is the one-based ordinal of the current attempt, claimed in a durable write before the handler runs. It is retry/logging context, not an execution identity.
332
+ - **Named-alarm generation** is an internal token minted per scheduled occurrence; it backs `idempotencyKey` and is not exposed directly.
333
+
334
+ `attempt` is operational context for retry policies and logging, not a record of what the handler did. It is not strictly unique per handler entry: an entry whose claim write never commits can see the same number again on recovery. Cloudflare's output gates hold that entry's outbound fetches and RPCs until its storage writes are confirmed and discard them if the write is lost, so a replayed ordinal never corresponds to an escaped external effect — but it is still not a reliable "what already happened" signal.
335
+
336
+ That is why `attempt === 1` is not a durable "first run" gate. Attempt 1 can fail or time out before or after its effect, and retries carry a higher ordinal, so gating on the number either skips the effect forever once it increments or cannot tell whether the effect already ran. Gate once-only work on durable state keyed by the stable `id` instead, preferably in the authoritative receiver:
337
+
338
+ ```ts
339
+ // Wrong: attempt is not a record of whether the effect ran. If attempt 1
340
+ // fails after charging, the retry (attempt 2) skips the charge; if it fails
341
+ // before, nothing distinguishes that from success.
342
+ if (attempt === 1) {
343
+ await chargeCard(payload);
344
+ }
345
+
346
+ // Right: the receiver dedupes on the stable id, independent of attempt.
347
+ await this.env.BILLING.chargeOnce(id, payload);
348
+ ```
349
+
255
350
  ## Delivery semantics and concurrency
256
351
 
257
- 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.
352
+ Work is delivered at least once, as the [delivery and safety contract](#delivery-and-safety-contract) describes. 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.
258
353
 
259
354
  `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.
260
355
 
261
356
  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.
262
357
 
358
+ ## Load envelope
359
+
360
+ `pnpm bench:load` runs an opt-in Workerd characterization suite (`bench/`, excluded from `pnpm test`) that drains large backlogs, a zero-delay retry storm, and a mixed operation plus named-alarm workload, emitting one machine-readable `BENCH {...}` JSON line per scenario. The numbers below come from that suite on `compatibility_date` `2026-07-07` with the default `alarmConcurrency` of 10; treat them as a tested envelope on one machine, not a platform capacity promise.
361
+
362
+ - A live object drains its backlog eagerly and through in-memory timers, so 100, 1,000, and 10,000 simultaneously due operations all complete with no lost calls, no extra terminal transitions, and nothing left pending. The physical alarm is a post-eviction fallback, not the live drain path.
363
+ - Each retained completed row costs roughly 200–260 bytes plus the serialized payload and result; 10,000 empty-payload operations occupy about 2 MB of `databaseSize`. Rows are never reclaimed automatically, so storage grows linearly until `purgeBefore` runs.
364
+ - `alarmConcurrency` is one shared budget: a mixed backlog of overlapping operations and a named alarm never exceeds 10 concurrent handlers in total, rather than 10 per category.
365
+ - A zero-delay retry storm performs exactly one attempt per retry with no extra work and settles every operation.
366
+
263
367
  ## Destructive retention purge
264
368
 
265
369
  `purgeBefore(timestamp)` on either helper deletes that helper's records created strictly before `timestamp`, regardless of status, and returns the count. Records created exactly at the cutoff are retained.
@@ -285,11 +389,28 @@ const durability = new Durability({
285
389
 
286
390
  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.
287
391
 
288
- Further hooks attach after construction with `lifecycle(hook)`, which returns a function that detaches it. `Durability` hooks are typed per operation: a `completed` settlement carries the handler's `result`.
392
+ Events are built to be safe to forward to shared telemetry sinks: they carry structural fields (entity kind, operation or alarm name, idempotency `id`, `generation`, `attempt`, `durationMs`, `nextAttemptAt`) and a normalized `error` of `{ name, message }` with no stack, but **no payloads and no handler results by default**. The `id` is the raw idempotency key you chose, so hash or drop it before exporting to a metrics backend if it is high-cardinality or sensitive. Because an event is emitted per attempt, retry, and purge, treat these as counters and durations rather than an audit trail.
393
+
394
+ To include a `completed` settlement's handler `result` — for example to bridge results to a WebSocket or cache — opt in with `includeResults: true`. Enable it only when every attached hook is trusted with result content, since results may contain sensitive data:
395
+
396
+ ```ts
397
+ const durability = new Durability({
398
+ context: this.ctx,
399
+ handlers,
400
+ includeResults: true,
401
+ onLifecycleEvent: (event) => recordDurabilityMetric(event),
402
+ });
403
+ ```
404
+
405
+ Further hooks attach after construction with `lifecycle(hook)`, which returns a function that detaches it. `Durability` hooks are typed per operation: a `completed` settlement carries the handler's `result` only when `includeResults` is enabled, so the field is typed as optional.
289
406
 
290
407
  ```ts
291
408
  const detach = durability.lifecycle((event) => {
292
- if (event.type === 'attempt_settled' && event.outcome === 'completed') {
409
+ if (
410
+ event.type === 'attempt_settled' &&
411
+ event.outcome === 'completed' &&
412
+ event.result !== undefined
413
+ ) {
293
414
  publish(event.operation, event.result);
294
415
  }
295
416
  });
@@ -299,16 +420,16 @@ const detach = durability.lifecycle((event) => {
299
420
 
300
421
  Define `__DURABILITY_DEV__` as `true` at build time to log every operation the package performs. Each entry is a structured `console.debug` object whose `event` starts with `durability.dev.`:
301
422
 
302
- | `event` | Logged for |
303
- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
304
- | `durability.dev.call` | Each public method call on every helper, including the experimental outbox and semaphores, generated operation, alarm, and socket outbound methods, and fanout `ack`, `retry`, and `deadLetter`, with its arguments. |
305
- | `durability.dev.call.return` / `.call.throw` | The call's result or serialized error, linked to the call by `call`. |
306
- | `durability.dev.storage` | Each storage method: transactions and alarm reads and writes, including those inside `transaction`. |
307
- | `durability.dev.storage.return` / `.storage.throw` | The storage call's result or serialized error, linked by `call`. |
308
- | `durability.dev.sql` | Each SQL statement, whitespace-compacted, with its bindings. |
309
- | `durability.dev.lifecycle` | Every lifecycle event, whether or not a hook is attached. |
310
- | `durability.dev.scheduler.early_alarm` | An in-memory timer that runs due work before the physical alarm. |
311
- | `durability.dev.socket.send` / `.socket.close` | Each frame sent to a browser socket, and each socket closed for a protocol error. |
423
+ | `event` | Logged for |
424
+ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
425
+ | `durability.dev.call` | Each public method call on every helper, including the experimental outbox and semaphores, generated operation, alarm, and socket outbound methods, `memoize`, and fanout `ack`, `retry`, and `deadLetter`, with its arguments. |
426
+ | `durability.dev.call.return` / `.call.throw` | The call's result or serialized error, linked to the call by `call`. |
427
+ | `durability.dev.storage` | Each storage method: transactions and alarm reads and writes, including those inside `transaction`. |
428
+ | `durability.dev.storage.return` / `.storage.throw` | The storage call's result or serialized error, linked by `call`. |
429
+ | `durability.dev.sql` | Each SQL statement, whitespace-compacted, with its bindings. |
430
+ | `durability.dev.lifecycle` | Every lifecycle event, whether or not a hook is attached. |
431
+ | `durability.dev.scheduler.early_alarm` | An in-memory timer that runs due work before the physical alarm. |
432
+ | `durability.dev.socket.send` / `.socket.close` | Each frame sent to a browser socket, and each socket closed for a protocol error. |
312
433
 
313
434
  Every entry carries `seq`, a process-wide counter that orders entries across interleaved async work, and `at`, the `Date.now()` reading when it was logged. A deterministic simulation that controls time, randomness, and scheduling gets a replayable transcript by collecting the entries in order, for example with `vi.spyOn(console, 'debug')`.
314
435
 
@@ -361,6 +482,8 @@ export class TodoList extends DurableObject<Env> {
361
482
  return payload;
362
483
  },
363
484
  },
485
+ // Lifecycle events omit handler results unless this is set.
486
+ includeResults: true,
364
487
  });
365
488
 
366
489
  readonly socket = new DurabilitySocket({
@@ -400,7 +523,11 @@ export class TodoList extends DurableObject<Env> {
400
523
  super(ctx, env);
401
524
  // Push a durable operation's result to every subscriber once it has committed.
402
525
  this.durability.lifecycle((e) => {
403
- if (e.type === 'attempt_settled' && e.outcome === 'completed') {
526
+ if (
527
+ e.type === 'attempt_settled' &&
528
+ e.outcome === 'completed' &&
529
+ e.result !== undefined
530
+ ) {
404
531
  this.socket.created(e.result);
405
532
  }
406
533
  });
@@ -511,7 +638,7 @@ All three methods take the same query: `{ source, name, status, limit, cursor }`
511
638
  - `get(source, id)` returns one such handle, or `undefined`.
512
639
  - `records(query)` returns `{ records, cursor }` with the same data and no functions.
513
640
 
514
- Narrowing on `source` and `name` narrows `state.result` to that handler's result type.
641
+ Narrowing on `source` and `name` narrows `state.result` to that handler's result type. A pending operation or alarm also lists `state.memoized`, the keys its next attempt will [reuse](#memoize).
515
642
 
516
643
  ### Handles over RPC
517
644
 
@@ -813,7 +940,7 @@ First deliveries are ordered by enqueue sequence per shard and target. Waiting r
813
940
 
814
941
  Set `batchDelayMs` to hold first deliveries for up to that many milliseconds, so messages enqueued together reach the consumer as one batch instead of one call each. Each first attempt is rounded up to the next multiple of `batchDelayMs`, so messages enqueued within the same window become due at the same time. It delays delivery, not acceptance: `enqueue` still returns once the batch commits. Retries keep their policy delay.
815
942
 
816
- Consumer callbacks may forward the batch to any ordinary WorkerEntrypoint RPC method. Messages include `id`, `deliveryId`, `target`, `body`, `attempt`, `enqueuedAt`, and callable settlement capabilities:
943
+ Consumer callbacks may forward the batch to any ordinary WorkerEntrypoint RPC method. Messages include `id`, `deliveryId`, `target`, `body`, `attempt`, `enqueuedAt`, a [`memoize`](#memoize) scoped to that message and target, so a retried delivery reuses work an earlier attempt finished, and callable settlement capabilities:
817
944
 
818
945
  - `ack()` settles this target only.
819
946
  - `retry(10)` schedules eligibility after 10 ms, overriding the policy delay. It is not a real-time delivery guarantee.
@@ -2,22 +2,35 @@ import { type DurabilityLifecycleEvent, type LifecycleHook } from './lifecycle.j
2
2
  import { type DurabilityMigrationResult } from './migrations.js';
3
3
  import { type DurabilityAlarmMethodOptions, type ExecutionPolicyOptions } from './policy.js';
4
4
  import { type SchedulerAttachment } from './scheduler.js';
5
+ import { type DurableMemoize } from './memoize.js';
5
6
  /** Information passed to a named alarm handler for one execution attempt. */
6
7
  export type DurableAlarmInfo = {
7
8
  /** Configured name of the logical alarm. */
8
9
  name: string;
9
10
  /** Timestamp originally passed to the named alarm method. */
10
11
  scheduledTime: number;
11
- /** One-based execution attempt for this scheduled occurrence. */
12
+ /**
13
+ * One-based attempt ordinal for this scheduled occurrence, durably recorded
14
+ * before the handler runs. It is retry and logging context, not a record of
15
+ * what the handler did: never gate once-only work on it (such as
16
+ * `attempt === 1`). Key such work on durable state keyed by `idempotencyKey`
17
+ * instead. See the README identity glossary.
18
+ */
12
19
  attempt: number;
13
20
  /** Whether this scheduled occurrence has run before. */
14
21
  isRetry: boolean;
15
22
  /** Number of previous attempts for this scheduled occurrence. */
16
23
  retryCount: number;
17
- /** Stable key shared by every attempt of this scheduled occurrence. */
24
+ /**
25
+ * Stable key shared by every attempt of this scheduled occurrence. This is
26
+ * the occurrence's logical identity: pass it to downstream services for
27
+ * deduplication rather than relying on `attempt`.
28
+ */
18
29
  idempotencyKey: string;
19
30
  /** Aborts when the attempt exceeds its configured timeout. */
20
31
  signal: AbortSignal;
32
+ /** Persists a callback's result by key so a retry of this occurrence reuses it. */
33
+ memoize: DurableMemoize;
21
34
  /** Invocation information for the shared physical Durable Object alarm. */
22
35
  platform: AlarmInvocationInfo | undefined;
23
36
  };
@@ -14,9 +14,10 @@ import { z } from 'zod';
14
14
  import { traceFunction, traceMethods } from './dev.js';
15
15
  import { DurableAlarmTimeoutError, DurableAttemptsExhaustedError, isErrorInstance, NonRetryableError, } from './errors.js';
16
16
  import { createLifecycleHooks, } from './lifecycle.js';
17
- import { durabilityNamedAlarmMigrations, migrateCapability, } from './migrations.js';
17
+ import { durabilityNamedAlarmMigrations, durabilityMemoMigrations, migrateCapability, } from './migrations.js';
18
18
  import { alarmMethodOptionsSchema, createPolicyResolver, } from './policy.js';
19
19
  import { engineFor, } from './scheduler.js';
20
+ import { createMemoize, deleteMemos, deleteMemosOfDroppedTable, memoizedKeys, } from './memoize.js';
20
21
  import { deleteAttempt, listCreated } from './storage.js';
21
22
  import { registerTrackedSource, } from './tracked-source.js';
22
23
  const alarmRowSchema = z.object({
@@ -37,7 +38,7 @@ const readAlarm = (sql, name) => alarmRowSchema
37
38
  .parse(sql
38
39
  .exec('SELECT * FROM durability_alarms WHERE name = ?', name)
39
40
  .toArray()[0]);
40
- const alarmRecord = (row) => ({
41
+ const alarmRecord = (sql, row) => ({
41
42
  id: row.name,
42
43
  name: row.name,
43
44
  generation: row.generation_id,
@@ -48,6 +49,7 @@ const alarmRecord = (row) => ({
48
49
  attempt: row.attempt,
49
50
  nextAttemptAt: row.next_attempt_at,
50
51
  lastError: row.last_error,
52
+ memoized: memoizedKeys(sql, alarmsTable, row.name, row.generation_id),
51
53
  }
52
54
  : {
53
55
  status: 'failed',
@@ -89,6 +91,7 @@ class DurabilityAlarmsCore {
89
91
  });
90
92
  }
91
93
  __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").migrateSchema('namedAlarms', durabilityNamedAlarmMigrations);
94
+ __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").migrateSchema('memos', durabilityMemoMigrations);
92
95
  __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").register({
93
96
  table: alarmsTable,
94
97
  runDue: (now, info) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_runDue).call(this, now, info),
@@ -97,7 +100,9 @@ class DurabilityAlarmsCore {
97
100
  }
98
101
  /** Applies or reverts the `durability_alarms` schema; see {@link migrateCapability}. */
99
102
  static migrate(context, target) {
100
- return migrateCapability(context.storage, 'namedAlarms', durabilityNamedAlarmMigrations, target);
103
+ const result = migrateCapability(context.storage, 'namedAlarms', durabilityNamedAlarmMigrations, target);
104
+ deleteMemosOfDroppedTable(context.storage.sql, alarmsTable);
105
+ return result;
101
106
  }
102
107
  /** Runs due named alarms and re-arms the physical alarm. */
103
108
  alarm(info) {
@@ -131,7 +136,7 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
131
136
  return {
132
137
  get: async (name) => {
133
138
  const row = readAlarm(sql, name);
134
- return row && alarmRecord(row);
139
+ return row && alarmRecord(sql, row);
135
140
  },
136
141
  list: async ({ limit, cursor, status, name }) => {
137
142
  const page = listCreated(sql, alarmsTable, 'name', {
@@ -143,7 +148,7 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
143
148
  const records = alarmRowSchema
144
149
  .array()
145
150
  .parse(page.rows)
146
- .map(alarmRecord);
151
+ .map((row) => alarmRecord(sql, row));
147
152
  return page.next === undefined
148
153
  ? { records }
149
154
  : { records, cursor: page.next };
@@ -201,6 +206,8 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
201
206
  last_error = excluded.last_error,
202
207
  last_error_name = excluded.last_error_name,
203
208
  created_at = excluded.created_at`, name, generation, scheduledTime, scheduledTime, createdAt);
209
+ // Memoized results belong to the replaced occurrence, never to the new one.
210
+ deleteMemos(sql, alarmsTable, name);
204
211
  });
205
212
  // A waiter on the replaced occurrence resolves now instead of at its timeout.
206
213
  __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").notify(alarmsTable, name);
@@ -245,6 +252,11 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
245
252
  retryCount: attempt - 1,
246
253
  idempotencyKey: `durability-alarm:v1:${row.generation_id}`,
247
254
  signal,
255
+ memoize: createMemoize(__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").sql, alarmsTable, {
256
+ key: row.name,
257
+ generation: row.generation_id,
258
+ attempt,
259
+ }),
248
260
  platform,
249
261
  });
250
262
  },
@@ -2,6 +2,7 @@ import { type DurabilityLifecycleEvent, type LifecycleHook } from './lifecycle.j
2
2
  import { type DurabilityMigrationResult } from './migrations.js';
3
3
  import { type DurabilityMethodOptions, type ExecutionPolicyOptions } from './policy.js';
4
4
  import { type SchedulerAttachment } from './scheduler.js';
5
+ import { type DurableMemoize } from './memoize.js';
5
6
  /**
6
7
  * The context passed to a durable operation handler for each attempt.
7
8
  *
@@ -16,16 +17,27 @@ import { type SchedulerAttachment } from './scheduler.js';
16
17
  * ```
17
18
  */
18
19
  export type DurableCall<Payload> = {
19
- /** The stable idempotency key supplied when the operation was registered. */
20
+ /**
21
+ * The stable idempotency key supplied when the operation was registered. This
22
+ * is the operation's logical identity: key any external deduplication or
23
+ * once-only effect by `id`, never by `attempt`.
24
+ */
20
25
  id: string;
21
26
  /** The handler name used to register the operation. */
22
27
  operation: string;
23
28
  /** The JSON-serializable payload supplied when the operation was registered. */
24
29
  payload: Payload;
25
- /** The one-based attempt number. */
30
+ /**
31
+ * The one-based attempt ordinal, durably recorded before the handler runs. It
32
+ * is retry and logging context, not a record of what the handler did: never
33
+ * gate once-only work on it (such as `attempt === 1`). Key such work on
34
+ * durable state keyed by `id` instead. See the README identity glossary.
35
+ */
26
36
  attempt: number;
27
37
  /** Aborts when the attempt exceeds its configured timeout. */
28
38
  signal: AbortSignal;
39
+ /** Persists a callback's result by key so a retry of this operation reuses it. */
40
+ memoize: DurableMemoize;
29
41
  };
30
42
  /** A function that executes one attempt of a durable operation. */
31
43
  export type DurableHandler<Payload, Result> = (call: DurableCall<Payload>) => Result | Promise<Result>;
@@ -83,13 +95,15 @@ type TypedOperationEvent<Operation extends string, Result> = OperationEvent exte
83
95
  outcome: 'completed';
84
96
  } ? Omit<Event, 'operation' | 'result'> & {
85
97
  operation: Operation;
86
- result: Result;
98
+ /** Present only when the instance was created with `includeResults: true`. */
99
+ result?: Result;
87
100
  } : Event extends object ? Omit<Event, 'operation'> & {
88
101
  operation: Operation;
89
102
  } : never : never;
90
103
  /**
91
104
  * A lifecycle event for one of this instance's operations. Completed events
92
- * carry the handler's typed result.
105
+ * carry the handler's typed result only when the instance is created with
106
+ * `includeResults: true`.
93
107
  */
94
108
  export type DurabilityOperationEvent<Handlers extends HandlerMap> = {
95
109
  [Operation in Extract<keyof Handlers, string>]: TypedOperationEvent<Operation, HandlerResult<Handlers[Operation]>>;
@@ -120,6 +134,12 @@ export type DurabilityOptions<Handlers extends HandlerMap = HandlerMap> = Execut
120
134
  methods?: Partial<Record<Extract<keyof NoInfer<Handlers>, string>, DurabilityMethodOptions>>;
121
135
  /** Receives best-effort, non-durable lifecycle metrics events. */
122
136
  onLifecycleEvent?: LifecycleHook;
137
+ /**
138
+ * Attach the handler's return value to `completed` lifecycle events.
139
+ * Off by default so results never reach telemetry sinks unintentionally;
140
+ * enable only when the sink is trusted with result content.
141
+ */
142
+ includeResults?: boolean;
123
143
  };
124
144
  /**
125
145
  * Constructor configuration: the operation handlers, their policies, and
@@ -152,11 +172,16 @@ type OperationMethods<Handlers extends HandlerMap> = {
152
172
  [Operation in keyof Handlers]: DurableOperation<Handlers[Operation]>;
153
173
  };
154
174
  /**
155
- * Alarm-backed, effectively-once durable operations for one Durable Object.
175
+ * Alarm-backed, at-least-once durable operations for one Durable Object.
156
176
  *
157
177
  * Every handler becomes a typed method on the instance. Methods resolve once
158
178
  * the call is durably registered; read outcomes through `getResult`.
159
179
  *
180
+ * Delivery is at least once: a handler may run again after a crash, timeout, or
181
+ * eviction. The call `id` is a stable idempotency key; pass it to external
182
+ * systems and make effects idempotent or reconcilable to reach an effectively
183
+ * once outcome. See the README "Delivery and safety contract".
184
+ *
160
185
  * @example
161
186
  * ```ts
162
187
  * class ImageJobs extends DurableObject<Env> {
@@ -9,15 +9,16 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
9
9
  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
10
10
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
11
  };
12
- var _DurabilityCore_instances, _DurabilityCore_engine, _DurabilityCore_handlers, _DurabilityCore_policy, _DurabilityCore_lifecycle, _DurabilityCore_emit, _DurabilityCore_active, _DurabilityCore_executionStarts, _DurabilityCore_trackedSource, _DurabilityCore_runDue, _DurabilityCore_getResult, _DurabilityCore_run, _DurabilityCore_execute, _DurabilityCore_start;
12
+ var _DurabilityCore_instances, _DurabilityCore_engine, _DurabilityCore_handlers, _DurabilityCore_policy, _DurabilityCore_lifecycle, _DurabilityCore_emit, _DurabilityCore_includeResults, _DurabilityCore_active, _DurabilityCore_executionStarts, _DurabilityCore_trackedSource, _DurabilityCore_runDue, _DurabilityCore_getResult, _DurabilityCore_run, _DurabilityCore_execute, _DurabilityCore_start;
13
13
  import { z } from 'zod';
14
14
  import { traceFunction, traceMethods } from './dev.js';
15
15
  import { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, isErrorInstance, NonRetryableError, reportFailure, } from './errors.js';
16
16
  import { createLifecycleHooks, } from './lifecycle.js';
17
- import { durabilityOperationMigrations, migrateCapability, } from './migrations.js';
17
+ import { durabilityOperationMigrations, durabilityMemoMigrations, migrateCapability, } from './migrations.js';
18
18
  import { createPolicyResolver, methodOptionsSchema, } from './policy.js';
19
19
  import { engineFor, } from './scheduler.js';
20
20
  import { canonical, deserialize, serialize } from './serialization.js';
21
+ import { createMemoize, deleteMemosOfDroppedTable, memoizedKeys, } from './memoize.js';
21
22
  import { listCreated, updateAttempt } from './storage.js';
22
23
  import { registerTrackedSource, } from './tracked-source.js';
23
24
  const callRowSchema = z.object({
@@ -67,13 +68,21 @@ const callState = (call) => {
67
68
  }
68
69
  return { status: 'completed', result: deserialize(call.result) };
69
70
  };
70
- const callRecord = (call) => ({
71
- id: call.id,
72
- name: call.operation,
73
- generation: call.generation_id,
74
- createdAt: call.created_at,
75
- state: callState(call),
76
- });
71
+ const callRecord = (sql, call) => {
72
+ const state = callState(call);
73
+ return {
74
+ id: call.id,
75
+ name: call.operation,
76
+ generation: call.generation_id,
77
+ createdAt: call.created_at,
78
+ state: state.status === 'pending'
79
+ ? {
80
+ ...state,
81
+ memoized: memoizedKeys(sql, callsTable, call.id, call.generation_id),
82
+ }
83
+ : state,
84
+ };
85
+ };
77
86
  const operationEntity = (call) => ({
78
87
  entityKind: 'operation',
79
88
  operation: call.operation,
@@ -88,6 +97,7 @@ class DurabilityCore {
88
97
  _DurabilityCore_policy.set(this, void 0);
89
98
  _DurabilityCore_lifecycle.set(this, void 0);
90
99
  _DurabilityCore_emit.set(this, void 0);
100
+ _DurabilityCore_includeResults.set(this, void 0);
91
101
  _DurabilityCore_active.set(this, new Map());
92
102
  _DurabilityCore_executionStarts.set(this, new Map());
93
103
  const { handlers } = config;
@@ -96,6 +106,7 @@ class DurabilityCore {
96
106
  __classPrivateFieldSet(this, _DurabilityCore_policy, createPolicyResolver(config, config.methods ?? {}, methodOptionsSchema), "f");
97
107
  __classPrivateFieldSet(this, _DurabilityCore_lifecycle, createLifecycleHooks((hook) => __classPrivateFieldGet(this, _DurabilityCore_engine, "f").emitter(hook), config.onLifecycleEvent), "f");
98
108
  __classPrivateFieldSet(this, _DurabilityCore_emit, __classPrivateFieldGet(this, _DurabilityCore_lifecycle, "f").emit, "f");
109
+ __classPrivateFieldSet(this, _DurabilityCore_includeResults, config.includeResults ?? false, "f");
99
110
  const reserved = new Set(Object.getOwnPropertyNames(DurabilityCore.prototype));
100
111
  for (const operation of Object.keys(handlers)) {
101
112
  if (reserved.has(operation)) {
@@ -110,6 +121,7 @@ class DurabilityCore {
110
121
  });
111
122
  }
112
123
  __classPrivateFieldGet(this, _DurabilityCore_engine, "f").migrateSchema('operations', durabilityOperationMigrations);
124
+ __classPrivateFieldGet(this, _DurabilityCore_engine, "f").migrateSchema('memos', durabilityMemoMigrations);
113
125
  __classPrivateFieldGet(this, _DurabilityCore_engine, "f").register({
114
126
  table: callsTable,
115
127
  runDue: (now) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_runDue).call(this, now),
@@ -118,7 +130,9 @@ class DurabilityCore {
118
130
  }
119
131
  /** Applies or reverts the `durability_calls` schema; see {@link migrateCapability}. */
120
132
  static migrate(context, target) {
121
- return migrateCapability(context.storage, 'operations', durabilityOperationMigrations, target);
133
+ const result = migrateCapability(context.storage, 'operations', durabilityOperationMigrations, target);
134
+ deleteMemosOfDroppedTable(context.storage.sql, callsTable);
135
+ return result;
122
136
  }
123
137
  /** Processes due operations and re-arms the physical alarm. */
124
138
  alarm(info) {
@@ -147,12 +161,12 @@ class DurabilityCore {
147
161
  return count;
148
162
  }
149
163
  }
150
- _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap(), _DurabilityCore_policy = new WeakMap(), _DurabilityCore_lifecycle = new WeakMap(), _DurabilityCore_emit = new WeakMap(), _DurabilityCore_active = new WeakMap(), _DurabilityCore_executionStarts = new WeakMap(), _DurabilityCore_instances = new WeakSet(), _DurabilityCore_trackedSource = function _DurabilityCore_trackedSource() {
164
+ _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap(), _DurabilityCore_policy = new WeakMap(), _DurabilityCore_lifecycle = new WeakMap(), _DurabilityCore_emit = new WeakMap(), _DurabilityCore_includeResults = new WeakMap(), _DurabilityCore_active = new WeakMap(), _DurabilityCore_executionStarts = new WeakMap(), _DurabilityCore_instances = new WeakSet(), _DurabilityCore_trackedSource = function _DurabilityCore_trackedSource() {
151
165
  const sql = __classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql;
152
166
  return {
153
167
  get: async (id) => {
154
168
  const call = readCall(sql, id);
155
- return call && callRecord(call);
169
+ return call && callRecord(sql, call);
156
170
  },
157
171
  list: async ({ limit, cursor, status, name }) => {
158
172
  const page = listCreated(sql, callsTable, 'operation', {
@@ -161,7 +175,10 @@ _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap()
161
175
  status,
162
176
  name,
163
177
  });
164
- const records = callRowSchema.array().parse(page.rows).map(callRecord);
178
+ const records = callRowSchema
179
+ .array()
180
+ .parse(page.rows)
181
+ .map((call) => callRecord(sql, call));
165
182
  return page.next === undefined
166
183
  ? { records }
167
184
  : { records, cursor: page.next };
@@ -289,6 +306,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
289
306
  active: __classPrivateFieldGet(this, _DurabilityCore_active, "f"),
290
307
  policy,
291
308
  emit: __classPrivateFieldGet(this, _DurabilityCore_emit, "f"),
309
+ includeResult: __classPrivateFieldGet(this, _DurabilityCore_includeResults, "f"),
292
310
  exhaustedError: () => new DurableAttemptsExhaustedError('operation', call.operation, policy.maxAttempts),
293
311
  timeoutError: () => new DurableAttemptTimeoutError(call.operation, policy.attemptTimeoutMs),
294
312
  invoke: (attempt, signal) => {
@@ -301,6 +319,11 @@ async function _DurabilityCore_execute(id, eagerPermit) {
301
319
  payload: deserialize(call.payload),
302
320
  attempt,
303
321
  signal,
322
+ memoize: createMemoize(__classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql, callsTable, {
323
+ key: call.id,
324
+ generation: call.generation_id,
325
+ attempt,
326
+ }),
304
327
  });
305
328
  },
306
329
  complete: (result, attempt) => {
package/dist/errors.d.ts CHANGED
@@ -36,6 +36,20 @@ export declare class DurableRetryPolicyError extends Error {
36
36
  export declare class DurableResultSerializationError extends Error {
37
37
  constructor(operation: string, reason?: unknown);
38
38
  }
39
+ /**
40
+ * Error persisted when a memoized result cannot be JSON-serialized. It is
41
+ * terminal because every retry would fail the same way.
42
+ */
43
+ export declare class DurableMemoSerializationError extends NonRetryableError {
44
+ constructor(key: string, reason?: unknown);
45
+ }
46
+ /**
47
+ * Error persisted when work memoizes more keys, or a larger result, than the
48
+ * limits allow. It is terminal because every retry would fail the same way.
49
+ */
50
+ export declare class DurableMemoLimitError extends NonRetryableError {
51
+ constructor(message: string);
52
+ }
39
53
  /** Error persisted when pending work has already reached its attempt limit. */
40
54
  export declare class DurableAttemptsExhaustedError extends Error {
41
55
  constructor(entity: 'operation' | 'named alarm', name: string, max: number);