durability 4.1.0 → 4.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -1
- package/dist/scheduler.d.ts +9 -1
- package/dist/scheduler.js +30 -1
- package/dist/serialization.js +23 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -86,7 +86,7 @@ switch (result.status) {
|
|
|
86
86
|
}
|
|
87
87
|
```
|
|
88
88
|
|
|
89
|
-
The completed result type is inferred from the handler. Looking up a key that belongs to another operation throws `DuplicateDurableCallError`. Payloads and results must be JSON-serializable.
|
|
89
|
+
The completed result type is inferred from the handler. Looking up a key that belongs to another operation throws `DuplicateDurableCallError`. Payloads and results must be JSON-serializable; as with `JSON.stringify`, `undefined` properties are dropped and `undefined` array elements become `null`.
|
|
90
90
|
|
|
91
91
|
An ID stays bound to its operation and payload. Registering it again with the same operation and the same data (object key order does not matter; array order and values do) is a no-op, which is what makes retries safe. Registering it with another operation throws `DuplicateDurableCallError`, and with a different payload `DuplicateDurablePayloadError`, instead of silently dropping the new call.
|
|
92
92
|
|
|
@@ -792,6 +792,10 @@ There is no per-record retry, timeout, or dead letter here: a log tracks positio
|
|
|
792
792
|
|
|
793
793
|
There is also no key compaction. `deduplicationKey` is unique per retained record, which is the opposite of a compaction key, and deduplication lasts only while the original record is retained — re-appending a key after its record was flushed or deleted creates a new record.
|
|
794
794
|
|
|
795
|
+
## When a run cannot finish
|
|
796
|
+
|
|
797
|
+
A Durable Object alarm whose handler throws is retried with backoff a limited number of times and then dropped. Every helper's `alarm()` ends by reconciling the physical alarm, and a storage error there would otherwise propagate, so enough of them in a row would leave pending work with nothing armed. Instead, a run that fails arms the physical alarm directly at `alarmMinDelayMs` from now and returns, reporting `durability.alarm.failed` with the error; the next run reconciles properly. Only when even that `setAlarm` fails does the failure reach the platform and its retries.
|
|
798
|
+
|
|
795
799
|
## Long-running alarm calls
|
|
796
800
|
|
|
797
801
|
Alarm invocations have a 15-minute wall-time limit. If work is still pending after `alarmHandoffMs` (default 14 minutes), the scheduler retains its promise in memory, arms a fallback after `alarmMinDelayMs`, and returns from the current invocation. The next alarm attaches to the same promise instead of starting the handler again. If the object is evicted during a handoff, the next alarm reconstructs and executes the persisted pending work.
|
package/dist/scheduler.d.ts
CHANGED
|
@@ -117,11 +117,19 @@ export declare class Engine {
|
|
|
117
117
|
acquirePermit(): Promise<() => void>;
|
|
118
118
|
private createRelease;
|
|
119
119
|
runConcurrent<Item>(items: Item[], worker: (item: Item) => Promise<void>): Promise<void>;
|
|
120
|
+
/**
|
|
121
|
+
* Runs due work and re-arms the physical alarm. A failure that would
|
|
122
|
+
* otherwise propagate to the platform is turned into a retry of our own,
|
|
123
|
+
* because the platform drops an alarm after a few failed deliveries.
|
|
124
|
+
*/
|
|
125
|
+
alarm(info?: AlarmInvocationInfo): Promise<void>;
|
|
120
126
|
/**
|
|
121
127
|
* Runs every participant's due work, hands off to a fresh alarm if the
|
|
122
128
|
* invocation approaches its wall-time limit, and re-arms the physical alarm.
|
|
123
129
|
*/
|
|
124
|
-
|
|
130
|
+
private runAlarm;
|
|
131
|
+
/** Arms the physical alarm directly, outside any transaction; the next run reconciles properly. */
|
|
132
|
+
private armFallbackAlarm;
|
|
125
133
|
private armForHandoff;
|
|
126
134
|
/**
|
|
127
135
|
* Registers the execution in its active map synchronously, then claims and
|
package/dist/scheduler.js
CHANGED
|
@@ -267,11 +267,30 @@ export class Engine {
|
|
|
267
267
|
}
|
|
268
268
|
}));
|
|
269
269
|
}
|
|
270
|
+
/**
|
|
271
|
+
* Runs due work and re-arms the physical alarm. A failure that would
|
|
272
|
+
* otherwise propagate to the platform is turned into a retry of our own,
|
|
273
|
+
* because the platform drops an alarm after a few failed deliveries.
|
|
274
|
+
*/
|
|
275
|
+
async alarm(info) {
|
|
276
|
+
try {
|
|
277
|
+
await this.runAlarm(info);
|
|
278
|
+
}
|
|
279
|
+
catch (error) {
|
|
280
|
+
// Throwing lets the platform retry, but it gives up after a few failures
|
|
281
|
+
// and drops the alarm, stranding pending work. Keeping our own alarm
|
|
282
|
+
// armed turns the failure into a retry we control instead.
|
|
283
|
+
if (!(await this.armFallbackAlarm())) {
|
|
284
|
+
throw error;
|
|
285
|
+
}
|
|
286
|
+
reportFailure('durability.alarm.failed', { retryInMs: this.alarmMinDelayMs }, error);
|
|
287
|
+
}
|
|
288
|
+
}
|
|
270
289
|
/**
|
|
271
290
|
* Runs every participant's due work, hands off to a fresh alarm if the
|
|
272
291
|
* invocation approaches its wall-time limit, and re-arms the physical alarm.
|
|
273
292
|
*/
|
|
274
|
-
async
|
|
293
|
+
async runAlarm(info) {
|
|
275
294
|
const startedAt = Date.now();
|
|
276
295
|
const execution = Promise.all(this.participants.map((participant) => participant.runDue(startedAt, info))).then(() => undefined);
|
|
277
296
|
void execution.catch(() => undefined);
|
|
@@ -298,6 +317,16 @@ export class Engine {
|
|
|
298
317
|
}
|
|
299
318
|
await this.scheduleNextAlarm();
|
|
300
319
|
}
|
|
320
|
+
/** Arms the physical alarm directly, outside any transaction; the next run reconciles properly. */
|
|
321
|
+
async armFallbackAlarm() {
|
|
322
|
+
try {
|
|
323
|
+
await this.context.storage.setAlarm(Date.now() + this.alarmMinDelayMs);
|
|
324
|
+
return true;
|
|
325
|
+
}
|
|
326
|
+
catch {
|
|
327
|
+
return false;
|
|
328
|
+
}
|
|
329
|
+
}
|
|
301
330
|
armForHandoff(timestamp) {
|
|
302
331
|
return this.context.storage.transaction(async (physicalAlarm) => {
|
|
303
332
|
const currentAlarm = await physicalAlarm.getAlarm();
|
package/dist/serialization.js
CHANGED
|
@@ -3,10 +3,32 @@ const storedValueSchema = z.discriminatedUnion('kind', [
|
|
|
3
3
|
z.object({ kind: z.literal('value'), value: z.json() }),
|
|
4
4
|
z.object({ kind: z.literal('undefined') }),
|
|
5
5
|
]);
|
|
6
|
+
/**
|
|
7
|
+
* What `JSON.stringify` would produce: `undefined` properties are dropped and
|
|
8
|
+
* `undefined` array elements become `null`. `z.json()` rejects both as given,
|
|
9
|
+
* although they are routine in values such as lifecycle events whose handler
|
|
10
|
+
* returned nothing.
|
|
11
|
+
*/
|
|
12
|
+
const asJson = (value) => {
|
|
13
|
+
if (Array.isArray(value)) {
|
|
14
|
+
return value.map((item) => (item === undefined ? null : asJson(item)));
|
|
15
|
+
}
|
|
16
|
+
if (value === null || typeof value !== 'object') {
|
|
17
|
+
return value;
|
|
18
|
+
}
|
|
19
|
+
// Only plain objects are rewritten; anything else must fail validation as is.
|
|
20
|
+
const prototype = Object.getPrototypeOf(value);
|
|
21
|
+
if (prototype === Object.prototype || prototype === null) {
|
|
22
|
+
return Object.fromEntries(Object.entries(value)
|
|
23
|
+
.filter(([, item]) => item !== undefined)
|
|
24
|
+
.map(([key, item]) => [key, asJson(item)]));
|
|
25
|
+
}
|
|
26
|
+
return value;
|
|
27
|
+
};
|
|
6
28
|
// Wrapping preserves a successful `undefined` result, which bare JSON cannot represent.
|
|
7
29
|
export const serialize = (value) => JSON.stringify(value === undefined
|
|
8
30
|
? { kind: 'undefined' }
|
|
9
|
-
: { kind: 'value', value: z.json().parse(value) });
|
|
31
|
+
: { kind: 'value', value: z.json().parse(asJson(value)) });
|
|
10
32
|
export const deserialize = (value) => {
|
|
11
33
|
const stored = storedValueSchema.parse(JSON.parse(value));
|
|
12
34
|
return stored.kind === 'undefined' ? undefined : stored.value;
|