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 +147 -20
- package/dist/durability-alarms.d.ts +15 -2
- package/dist/durability-alarms.js +17 -5
- package/dist/durability.d.ts +30 -5
- package/dist/durability.js +36 -13
- package/dist/errors.d.ts +14 -0
- package/dist/errors.js +23 -0
- package/dist/fanout.d.ts +6 -0
- package/dist/fanout.js +8 -2
- package/dist/index.d.ts +3 -2
- package/dist/index.js +3 -2
- package/dist/lifecycle.d.ts +6 -1
- package/dist/log.js +35 -12
- package/dist/memoize.d.ts +34 -0
- package/dist/memoize.js +136 -0
- package/dist/migrations.d.ts +18 -1
- package/dist/migrations.js +49 -0
- package/dist/scheduler.d.ts +2 -0
- package/dist/scheduler.js +29 -6
- package/dist/storage.d.ts +1 -0
- package/dist/storage.js +1 -1
- package/dist/tracked-source.d.ts +2 -0
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Composable capabilities for application-owned Cloudflare Durable Objects:
|
|
4
4
|
|
|
5
|
-
- **`Durability`** —
|
|
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`
|
|
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
|
-
|
|
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 (
|
|
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 (
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
},
|
package/dist/durability.d.ts
CHANGED
|
@@ -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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
|
|
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,
|
|
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> {
|
package/dist/durability.js
CHANGED
|
@@ -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
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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
|
-
|
|
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
|
|
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);
|