durability 4.3.0 → 5.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +245 -20
- package/dist/durability-alarms.d.ts +25 -3
- package/dist/durability-alarms.js +50 -8
- package/dist/durability.d.ts +30 -5
- package/dist/durability.js +42 -14
- package/dist/errors.d.ts +29 -0
- package/dist/errors.js +47 -0
- package/dist/experimental.d.ts +3 -0
- package/dist/experimental.js +3 -0
- package/dist/fanout.d.ts +6 -0
- package/dist/fanout.js +10 -6
- package/dist/index.d.ts +4 -3
- 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 +27 -1
- package/dist/migrations.js +93 -1
- package/dist/outbox.js +2 -3
- package/dist/schedule.d.ts +157 -0
- package/dist/schedule.js +651 -0
- package/dist/scheduler.d.ts +53 -1
- package/dist/scheduler.js +164 -30
- package/dist/semaphore-queue-store.js +23 -19
- package/dist/storage.d.ts +6 -2
- package/dist/storage.js +13 -7
- package/dist/tracked-source.d.ts +2 -0
- package/package.json +2 -1
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 };
|
|
@@ -178,7 +195,12 @@ _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap()
|
|
|
178
195
|
ORDER BY next_attempt_at ASC
|
|
179
196
|
LIMIT 100`, now)
|
|
180
197
|
.toArray());
|
|
181
|
-
|
|
198
|
+
// With liveTimers an active operation reschedules itself when it settles, so
|
|
199
|
+
// skipping it keeps a long handler from blocking a concurrent alarm pass.
|
|
200
|
+
const pending = __classPrivateFieldGet(this, _DurabilityCore_engine, "f").liveTimers
|
|
201
|
+
? due.filter(({ id }) => !__classPrivateFieldGet(this, _DurabilityCore_active, "f").has(id))
|
|
202
|
+
: due;
|
|
203
|
+
await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").runConcurrent(pending, async ({ id }) => {
|
|
182
204
|
try {
|
|
183
205
|
await __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_execute).call(this, id);
|
|
184
206
|
}
|
|
@@ -289,6 +311,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
|
|
|
289
311
|
active: __classPrivateFieldGet(this, _DurabilityCore_active, "f"),
|
|
290
312
|
policy,
|
|
291
313
|
emit: __classPrivateFieldGet(this, _DurabilityCore_emit, "f"),
|
|
314
|
+
includeResult: __classPrivateFieldGet(this, _DurabilityCore_includeResults, "f"),
|
|
292
315
|
exhaustedError: () => new DurableAttemptsExhaustedError('operation', call.operation, policy.maxAttempts),
|
|
293
316
|
timeoutError: () => new DurableAttemptTimeoutError(call.operation, policy.attemptTimeoutMs),
|
|
294
317
|
invoke: (attempt, signal) => {
|
|
@@ -301,6 +324,11 @@ async function _DurabilityCore_execute(id, eagerPermit) {
|
|
|
301
324
|
payload: deserialize(call.payload),
|
|
302
325
|
attempt,
|
|
303
326
|
signal,
|
|
327
|
+
memoize: createMemoize(__classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql, callsTable, {
|
|
328
|
+
key: call.id,
|
|
329
|
+
generation: call.generation_id,
|
|
330
|
+
attempt,
|
|
331
|
+
}),
|
|
304
332
|
});
|
|
305
333
|
},
|
|
306
334
|
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);
|
|
@@ -71,6 +85,21 @@ export declare class FanoutTimeoutError extends Error {
|
|
|
71
85
|
export declare class OutboxTimeoutError extends Error {
|
|
72
86
|
constructor(timeoutMs: number);
|
|
73
87
|
}
|
|
88
|
+
/** Outcome error of a scheduled run that exceeded `runTimeoutMs`. */
|
|
89
|
+
export declare class ScheduledRunTimeoutError extends Error {
|
|
90
|
+
constructor(timeoutMs: number);
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Outcome error of a scheduled run that was still marked running when no live
|
|
94
|
+
* instance was executing it, for example after its object was evicted or reset.
|
|
95
|
+
*/
|
|
96
|
+
export declare class ScheduledRunInterruptedError extends Error {
|
|
97
|
+
constructor();
|
|
98
|
+
}
|
|
99
|
+
/** Error recorded when one `onOutcome` delivery exceeds `outcomeTimeoutMs`. */
|
|
100
|
+
export declare class ScheduledOutcomeTimeoutError extends Error {
|
|
101
|
+
constructor(timeoutMs: number);
|
|
102
|
+
}
|
|
74
103
|
/** A definite rejection before the batch was durably accepted. */
|
|
75
104
|
export declare class FanoutEnqueueError extends Error {
|
|
76
105
|
constructor(message: string);
|
package/dist/errors.js
CHANGED
|
@@ -57,6 +57,29 @@ export class DurableResultSerializationError extends Error {
|
|
|
57
57
|
}
|
|
58
58
|
}
|
|
59
59
|
}
|
|
60
|
+
/**
|
|
61
|
+
* Error persisted when a memoized result cannot be JSON-serialized. It is
|
|
62
|
+
* terminal because every retry would fail the same way.
|
|
63
|
+
*/
|
|
64
|
+
export class DurableMemoSerializationError extends NonRetryableError {
|
|
65
|
+
constructor(key, reason) {
|
|
66
|
+
super(`Memoized result for key ${JSON.stringify(key)} is not JSON-serializable`);
|
|
67
|
+
this.name = 'DurableMemoSerializationError';
|
|
68
|
+
if (reason !== undefined) {
|
|
69
|
+
Object.defineProperty(this, 'cause', { value: reason });
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Error persisted when work memoizes more keys, or a larger result, than the
|
|
75
|
+
* limits allow. It is terminal because every retry would fail the same way.
|
|
76
|
+
*/
|
|
77
|
+
export class DurableMemoLimitError extends NonRetryableError {
|
|
78
|
+
constructor(message) {
|
|
79
|
+
super(message);
|
|
80
|
+
this.name = 'DurableMemoLimitError';
|
|
81
|
+
}
|
|
82
|
+
}
|
|
60
83
|
/** Error persisted when pending work has already reached its attempt limit. */
|
|
61
84
|
export class DurableAttemptsExhaustedError extends Error {
|
|
62
85
|
constructor(entity, name, max) {
|
|
@@ -112,6 +135,30 @@ export class OutboxTimeoutError extends Error {
|
|
|
112
135
|
this.name = 'OutboxTimeoutError';
|
|
113
136
|
}
|
|
114
137
|
}
|
|
138
|
+
/** Outcome error of a scheduled run that exceeded `runTimeoutMs`. */
|
|
139
|
+
export class ScheduledRunTimeoutError extends Error {
|
|
140
|
+
constructor(timeoutMs) {
|
|
141
|
+
super(`Scheduled run timed out after ${timeoutMs}ms`);
|
|
142
|
+
this.name = 'ScheduledRunTimeoutError';
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* Outcome error of a scheduled run that was still marked running when no live
|
|
147
|
+
* instance was executing it, for example after its object was evicted or reset.
|
|
148
|
+
*/
|
|
149
|
+
export class ScheduledRunInterruptedError extends Error {
|
|
150
|
+
constructor() {
|
|
151
|
+
super('Scheduled run was interrupted before it reported an outcome');
|
|
152
|
+
this.name = 'ScheduledRunInterruptedError';
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
/** Error recorded when one `onOutcome` delivery exceeds `outcomeTimeoutMs`. */
|
|
156
|
+
export class ScheduledOutcomeTimeoutError extends Error {
|
|
157
|
+
constructor(timeoutMs) {
|
|
158
|
+
super(`Scheduled run outcome delivery timed out after ${timeoutMs}ms`);
|
|
159
|
+
this.name = 'ScheduledOutcomeTimeoutError';
|
|
160
|
+
}
|
|
161
|
+
}
|
|
115
162
|
/** A definite rejection before the batch was durably accepted. */
|
|
116
163
|
export class FanoutEnqueueError extends Error {
|
|
117
164
|
constructor(message) {
|
package/dist/experimental.d.ts
CHANGED
|
@@ -14,3 +14,6 @@ export type { TopologyClient, TopologyClientConfig, TopologySource, TopologyView
|
|
|
14
14
|
export type { TopologyMember, TopologyMemberInput, TopologyMemberState, TopologySnapshot, } from './topology-snapshot.js';
|
|
15
15
|
export { TopologyError, TopologyUnavailableError, type TopologyFallbackReason, } from './errors.js';
|
|
16
16
|
export { durabilityTopologyMigrations } from './migrations.js';
|
|
17
|
+
export { DurabilitySchedule, type DurabilityScheduleConfig, type DurabilityScheduleEvent, type ScheduleDefinition, type ScheduledOutcomeDelivery, type ScheduledRun, type ScheduledRunContext, type ScheduledRunOutcome, type ScheduleState, } from './schedule.js';
|
|
18
|
+
export { ScheduledOutcomeTimeoutError, ScheduledRunInterruptedError, ScheduledRunTimeoutError, } from './errors.js';
|
|
19
|
+
export { durabilityScheduleMigrations } from './migrations.js';
|
package/dist/experimental.js
CHANGED
|
@@ -11,3 +11,6 @@ export { durabilityOutboxMigrations } from './migrations.js';
|
|
|
11
11
|
export { DurabilityTopology, } from './topology.js';
|
|
12
12
|
export { TopologyError, TopologyUnavailableError, } from './errors.js';
|
|
13
13
|
export { durabilityTopologyMigrations } from './migrations.js';
|
|
14
|
+
export { DurabilitySchedule, } from './schedule.js';
|
|
15
|
+
export { ScheduledOutcomeTimeoutError, ScheduledRunInterruptedError, ScheduledRunTimeoutError, } from './errors.js';
|
|
16
|
+
export { durabilityScheduleMigrations } from './migrations.js';
|
package/dist/fanout.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { type DurabilityLifecycleEvent, type LifecycleHook } from './lifecycle.js';
|
|
2
2
|
import { RoutingLoad, type EnqueueResult, type LoadSnapshot } from './load.js';
|
|
3
3
|
import type { MessageWrite } from './stored-message.js';
|
|
4
|
+
import { type DurableMemoize } from './memoize.js';
|
|
4
5
|
import { type ExecutionPolicyOptions } from './policy.js';
|
|
5
6
|
import { type SchedulerAttachment } from './scheduler.js';
|
|
6
7
|
export type FanoutInput<Body = unknown> = {
|
|
@@ -17,6 +18,11 @@ export type DurabilityFanoutMessage<Body = unknown> = {
|
|
|
17
18
|
body: Body;
|
|
18
19
|
attempt: number;
|
|
19
20
|
enqueuedAt: number;
|
|
21
|
+
/**
|
|
22
|
+
* Persists a callback's result by key for this message and target, so a
|
|
23
|
+
* retried delivery reuses it. Deleted when the delivery is acked or dead-lettered.
|
|
24
|
+
*/
|
|
25
|
+
memoize: DurableMemoize;
|
|
20
26
|
ack(): Promise<void>;
|
|
21
27
|
retry(delayMs?: number): Promise<void>;
|
|
22
28
|
deadLetter(): Promise<void>;
|
package/dist/fanout.js
CHANGED
|
@@ -15,7 +15,8 @@ import { traceFunction, traceMethods } from './dev.js';
|
|
|
15
15
|
import { DurableRetryPolicyError, FanoutEnqueueError, FanoutSettlementError, FanoutTimeoutError, reportFailure, serializeError, } from './errors.js';
|
|
16
16
|
import { createLifecycleHooks, } from './lifecycle.js';
|
|
17
17
|
import { RoutingLoad } from './load.js';
|
|
18
|
-
import {
|
|
18
|
+
import { createMemoize, deleteMemos, deleteMemosOfDroppedTable, } from './memoize.js';
|
|
19
|
+
import { durabilityFanoutMigrations, durabilityMemoMigrations, migrateCapability, } from './migrations.js';
|
|
19
20
|
import { assertPositiveInteger, createPolicyResolver, methodOptionsSchema, } from './policy.js';
|
|
20
21
|
import { engineFor, } from './scheduler.js';
|
|
21
22
|
import { deserialize, serialize } from './serialization.js';
|
|
@@ -120,13 +121,16 @@ export class DurabilityFanout {
|
|
|
120
121
|
__classPrivateFieldSet(this, _DurabilityFanout_lifecycle, createLifecycleHooks((hook) => __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").emitter(hook), config.onLifecycleEvent), "f");
|
|
121
122
|
__classPrivateFieldSet(this, _DurabilityFanout_emit, __classPrivateFieldGet(this, _DurabilityFanout_lifecycle, "f").emit, "f");
|
|
122
123
|
__classPrivateFieldGet(this, _DurabilityFanout_engine, "f").migrateSchema('fanout', durabilityFanoutMigrations);
|
|
124
|
+
__classPrivateFieldGet(this, _DurabilityFanout_engine, "f").migrateSchema('memos', durabilityMemoMigrations);
|
|
123
125
|
__classPrivateFieldGet(this, _DurabilityFanout_engine, "f").register({
|
|
124
126
|
table: deliveriesTable,
|
|
125
127
|
runDue: () => __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_runDue).call(this),
|
|
126
128
|
});
|
|
127
129
|
}
|
|
128
130
|
static migrate(context, target) {
|
|
129
|
-
|
|
131
|
+
const result = migrateCapability(context.storage, 'fanout', durabilityFanoutMigrations, target);
|
|
132
|
+
deleteMemosOfDroppedTable(context.storage.sql, deliveriesTable);
|
|
133
|
+
return result;
|
|
130
134
|
}
|
|
131
135
|
alarm(info) {
|
|
132
136
|
return __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").alarm(info);
|
|
@@ -334,13 +338,11 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
|
|
|
334
338
|
exhausted.push({ row, message });
|
|
335
339
|
continue;
|
|
336
340
|
}
|
|
337
|
-
const attempt = claimAttempt(sql, deliveriesTable, row.id, row.generation_id, policy.maxAttempts);
|
|
341
|
+
const attempt = claimAttempt(sql, deliveriesTable, row.id, row.generation_id, policy.maxAttempts, deadline);
|
|
338
342
|
if (attempt === undefined) {
|
|
339
343
|
continue;
|
|
340
344
|
}
|
|
341
|
-
|
|
342
|
-
updateAttempt(sql, deliveriesTable, attemptOf(claim.row), 'next_attempt_at = ?', deadline);
|
|
343
|
-
claimed.push(claim);
|
|
345
|
+
claimed.push({ row: { ...row, attempt }, message });
|
|
344
346
|
}
|
|
345
347
|
return { claims: claimed, terminal: exhausted };
|
|
346
348
|
});
|
|
@@ -528,6 +530,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
|
|
|
528
530
|
body: deserialize(message.payload),
|
|
529
531
|
enqueuedAt: message.created_at,
|
|
530
532
|
attempt: row.attempt,
|
|
533
|
+
memoize: createMemoize(__classPrivateFieldGet(this, _DurabilityFanout_engine, "f").sql, deliveriesTable, attemptOf(row)),
|
|
531
534
|
ack: traceFunction('DurabilityFanoutMessage.ack', () => settle('ack', async () => {
|
|
532
535
|
await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_remove).call(this, row);
|
|
533
536
|
__classPrivateFieldGet(this, _DurabilityFanout_emit, "f").call(this, {
|
|
@@ -560,6 +563,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
|
|
|
560
563
|
if (!deleteAttempt(sql, deliveriesTable, attemptOf(row))) {
|
|
561
564
|
return false;
|
|
562
565
|
}
|
|
566
|
+
deleteMemos(sql, deliveriesTable, row.id);
|
|
563
567
|
__classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_adjustPending).call(this, -1);
|
|
564
568
|
sql.exec(`UPDATE durability_fanout_messages
|
|
565
569
|
SET remaining = remaining - 1
|
package/dist/index.d.ts
CHANGED
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
export { Durability, type DurabilityConfig, type DurabilityConstructor, type DurabilityOptions, type DurableCall, type DurableHandler, type DurableOperation, type DurableOperationResult, type DurabilityOperationEvent, type HandlerMap, } from './durability.js';
|
|
2
2
|
export { DurabilityAlarms, type DurabilityAlarmsConfig, type DurabilityAlarmsConstructor, type DurabilityAlarmsOptions, type DurabilityAlarmEvent, type DurableAlarmHandler, type DurableAlarmInfo, type DurableNamedAlarm, } from './durability-alarms.js';
|
|
3
|
+
export { maxMemoBytes, maxMemosPerRecord, type DurableMemoize, } from './memoize.js';
|
|
3
4
|
export { DurabilityFanout, type DurabilityFanoutConfig, type DurabilityFanoutEvent, type DurabilityFanoutMessage, type FanoutInput, type FanoutTarget, type FanoutEnqueueOptions, } from './fanout.js';
|
|
4
5
|
export { DurabilityLog, maxLogBytes, type DurabilityLogConfig, type LogAppendInput, type LogColdStorage, type LogLease, type LogLeaseOptions, type LogPage, type LogReadOptions, type LogRecord, type LogRetention, type LogSegment, type LogBounds, } from './log.js';
|
|
5
6
|
export { RoutingLoad, type EnqueueResult, type LoadSnapshot, type ProcessingLoad, } from './load.js';
|
|
6
7
|
export type { MessageWrite, StoredMessage } from './stored-message.js';
|
|
7
|
-
export { DurabilityScheduler, type DurabilityContext, type DurabilitySchedulerConfig, type DurabilitySchedulerOptions, type SchedulerAttachment, } from './scheduler.js';
|
|
8
|
-
export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
|
|
8
|
+
export { DurabilityScheduler, type AlarmRetryInfo, type DurabilityContext, type DurabilitySchedulerConfig, type DurabilitySchedulerOptions, type SchedulerAttachment, } from './scheduler.js';
|
|
9
|
+
export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, DurableMemoLimitError, DurableMemoSerializationError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
|
|
9
10
|
export type { DurabilityLifecycleEvent, LifecycleHook } from './lifecycle.js';
|
|
10
|
-
export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, migrate, type DurabilityMigrationResult, type MigrateOptions, type MigrationCapability, } from './migrations.js';
|
|
11
|
+
export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, durabilityMemoMigrations, migrate, type DurabilityMigrationResult, type MigrateOptions, type MigrationCapability, } from './migrations.js';
|
|
11
12
|
export type { DurableMigrations } from '@durability/storage';
|
|
12
13
|
export type { DurabilityAlarmMethodOptions, DurabilityMethodOptions, DurabilityRetryOptions, } from './policy.js';
|
package/dist/index.js
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
export { Durability, } from './durability.js';
|
|
2
2
|
export { DurabilityAlarms, } from './durability-alarms.js';
|
|
3
|
+
export { maxMemoBytes, maxMemosPerRecord, } from './memoize.js';
|
|
3
4
|
export { DurabilityFanout, } from './fanout.js';
|
|
4
5
|
export { DurabilityLog, maxLogBytes, } from './log.js';
|
|
5
6
|
export { RoutingLoad, } from './load.js';
|
|
6
7
|
export { DurabilityScheduler, } from './scheduler.js';
|
|
7
|
-
export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
|
|
8
|
-
export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, migrate, } from './migrations.js';
|
|
8
|
+
export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, DurableMemoLimitError, DurableMemoSerializationError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
|
|
9
|
+
export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, durabilityMemoMigrations, migrate, } from './migrations.js';
|
package/dist/lifecycle.d.ts
CHANGED
|
@@ -48,7 +48,12 @@ export type DurabilityLifecycleEvent = ((OperationLifecycleEntity | FanoutLifecy
|
|
|
48
48
|
attempt: number;
|
|
49
49
|
}) | (LifecycleEntity & AttemptSettled & {
|
|
50
50
|
outcome: 'completed';
|
|
51
|
-
/**
|
|
51
|
+
/**
|
|
52
|
+
* The handler's return value. Omitted by default to keep result
|
|
53
|
+
* content out of telemetry; present only when the emitting instance
|
|
54
|
+
* opts in (e.g. Durability's `includeResults`). Always absent for
|
|
55
|
+
* fanout acknowledgements.
|
|
56
|
+
*/
|
|
52
57
|
result?: unknown;
|
|
53
58
|
}) | (LifecycleEntity & AttemptSettled & {
|
|
54
59
|
outcome: 'retry_scheduled';
|
package/dist/log.js
CHANGED
|
@@ -252,7 +252,7 @@ const settleLease = (sql, batchId, state, expiresAt) => sql
|
|
|
252
252
|
*/
|
|
253
253
|
const leasesFrom = (sql, consumer, from, limit) => logLeaseRowSchema.array().parse(sql
|
|
254
254
|
.exec(`SELECT * FROM durability_log_leases
|
|
255
|
-
WHERE consumer = ? AND
|
|
255
|
+
WHERE consumer = ? AND last_offset >= ?
|
|
256
256
|
ORDER BY first_offset ASC
|
|
257
257
|
LIMIT ?`, consumer, from, limit)
|
|
258
258
|
.toArray());
|
|
@@ -541,7 +541,11 @@ export class DurabilityLog {
|
|
|
541
541
|
}
|
|
542
542
|
// Terminal intent is durable before the callback runs, so a failing
|
|
543
543
|
// handler cannot resurrect a range that already exhausted its attempts.
|
|
544
|
-
|
|
544
|
+
// A skipped range counts as settled, so the cursor moves past it as for an ack.
|
|
545
|
+
__classPrivateFieldGet(this, _DurabilityLog_engine, "f").transactionSync(() => {
|
|
546
|
+
__classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_settle).call(this, reclaimed.batch_id, 'skipped');
|
|
547
|
+
__classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_advance).call(this, consumer);
|
|
548
|
+
});
|
|
545
549
|
try {
|
|
546
550
|
await leases.onPoison(lease);
|
|
547
551
|
}
|
|
@@ -675,17 +679,23 @@ async function _DurabilityLog_rehydrate(from, limit, bounds) {
|
|
|
675
679
|
// Offsets below the retained window are gone for everyone; a cursor
|
|
676
680
|
// stranded there could never meet the ranges leased after them.
|
|
677
681
|
const from = Math.max(readCursor(sql, consumer) ?? 0, readBounds(sql).oldestOffset);
|
|
678
|
-
const candidates = leasesFrom(sql, consumer, from, __classPrivateFieldGet(this, _DurabilityLog_maxBatchSize, "f"));
|
|
679
682
|
let cursor = from;
|
|
680
683
|
const settled = [];
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
684
|
+
// Ranges settled while an earlier one was outstanding wait behind it; when
|
|
685
|
+
// it settles the cursor must pass all of them, however many pages that is.
|
|
686
|
+
for (let page = true; page;) {
|
|
687
|
+
const candidates = leasesFrom(sql, consumer, cursor, __classPrivateFieldGet(this, _DurabilityLog_maxBatchSize, "f"));
|
|
688
|
+
page = candidates.length === __classPrivateFieldGet(this, _DurabilityLog_maxBatchSize, "f");
|
|
689
|
+
for (const row of candidates) {
|
|
690
|
+
const contiguous = row.first_offset <= cursor;
|
|
691
|
+
const done = row.state === 'acked' || row.state === 'skipped';
|
|
692
|
+
if (!contiguous || !done) {
|
|
693
|
+
page = false;
|
|
694
|
+
break;
|
|
695
|
+
}
|
|
696
|
+
cursor = Math.max(cursor, row.last_offset + 1);
|
|
697
|
+
settled.push(row.batch_id);
|
|
686
698
|
}
|
|
687
|
-
cursor = Math.max(cursor, row.last_offset + 1);
|
|
688
|
-
settled.push(row.batch_id);
|
|
689
699
|
}
|
|
690
700
|
if (settled.length === 0) {
|
|
691
701
|
return;
|
|
@@ -696,8 +706,21 @@ async function _DurabilityLog_rehydrate(from, limit, bounds) {
|
|
|
696
706
|
/** Reads a stored range, rehydrating it when retention already flushed it. */
|
|
697
707
|
async function _DurabilityLog_between(first, last) {
|
|
698
708
|
const bounds = readBounds(__classPrivateFieldGet(this, _DurabilityLog_engine, "f").sql);
|
|
699
|
-
|
|
700
|
-
|
|
709
|
+
// One read stops at the end of a cold segment, and a range redelivered
|
|
710
|
+
// after a flush can span several segments and the hot window.
|
|
711
|
+
const records = [];
|
|
712
|
+
let from = first;
|
|
713
|
+
while (from <= last) {
|
|
714
|
+
// eslint-disable-next-line no-await-in-loop
|
|
715
|
+
const page = await __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_readFrom).call(this, from, last - from + 1, bounds);
|
|
716
|
+
const inRange = page.filter((record) => record.offset <= last);
|
|
717
|
+
if (inRange.length === 0) {
|
|
718
|
+
break;
|
|
719
|
+
}
|
|
720
|
+
records.push(...inRange);
|
|
721
|
+
from = inRange[inRange.length - 1].offset + 1;
|
|
722
|
+
}
|
|
723
|
+
return records;
|
|
701
724
|
}, _DurabilityLog_readFrom = async function _DurabilityLog_readFrom(from, limit, bounds) {
|
|
702
725
|
if (from < bounds.hotOffset && from < bounds.nextOffset) {
|
|
703
726
|
return __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_rehydrate).call(this, from, limit, bounds);
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { type AttemptRef, type DurableTable } from './storage.js';
|
|
2
|
+
/**
|
|
3
|
+
* Runs `callback` once per key for a durable operation or named alarm
|
|
4
|
+
* occurrence and persists its result, so a retried attempt returns the result
|
|
5
|
+
* instead of running the callback again. A callback that throws persists
|
|
6
|
+
* nothing and runs again on the next call with that key.
|
|
7
|
+
*
|
|
8
|
+
* Calls with the same key return the same result, within one attempt and
|
|
9
|
+
* across attempts. A call for a key whose callback is still running rejects,
|
|
10
|
+
* including one made from that callback. Results are deleted when the
|
|
11
|
+
* operation, alarm occurrence, or fanout delivery settles.
|
|
12
|
+
*
|
|
13
|
+
* At most {@link maxMemosPerRecord} keys and {@link maxMemoBytes} per result;
|
|
14
|
+
* exceeding either fails the work with `DurableMemoLimitError`.
|
|
15
|
+
*/
|
|
16
|
+
export type DurableMemoize = <T>(key: string, callback: () => T | Promise<T>) => Promise<T>;
|
|
17
|
+
/** The most keys one operation, alarm occurrence, or fanout delivery may memoize. */
|
|
18
|
+
export declare const maxMemosPerRecord = 1000;
|
|
19
|
+
/** The largest serialized memoized result, in UTF-8 bytes. */
|
|
20
|
+
export declare const maxMemoBytes = 1048576;
|
|
21
|
+
/** Memoization for one attempt; only that attempt may persist new results. */
|
|
22
|
+
export declare const createMemoize: (sql: SqlStorage, table: DurableTable, ref: AttemptRef) => DurableMemoize;
|
|
23
|
+
/** Keys a record's current generation has results for, in the order they were saved. */
|
|
24
|
+
export declare const memoizedKeys: (sql: SqlStorage, table: DurableTable, key: string, generation: string) => string[];
|
|
25
|
+
/** Deletes every memoized result of a record, whichever generation wrote it. */
|
|
26
|
+
export declare const deleteMemos: (sql: SqlStorage, table: DurableTable, key: string) => void;
|
|
27
|
+
/** Deletes memoized results whose record generation is no longer pending. */
|
|
28
|
+
export declare const deleteStaleMemos: (sql: SqlStorage, table: DurableTable) => void;
|
|
29
|
+
/**
|
|
30
|
+
* Deletes the memoized results of a helper whose schema was reverted. The
|
|
31
|
+
* shared table stays for the other helper, but the removed records' results
|
|
32
|
+
* must not.
|
|
33
|
+
*/
|
|
34
|
+
export declare const deleteMemosOfDroppedTable: (sql: SqlStorage, table: DurableTable) => void;
|