durability 4.2.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 +340 -12
- package/dist/dev.d.ts +22 -0
- package/dist/dev.js +149 -0
- package/dist/durability-alarms.d.ts +16 -3
- package/dist/durability-alarms.js +21 -7
- package/dist/durability.d.ts +31 -6
- package/dist/durability.js +42 -16
- package/dist/errors.d.ts +31 -0
- package/dist/errors.js +45 -0
- package/dist/experimental.d.ts +5 -0
- package/dist/experimental.js +3 -0
- package/dist/fanout.d.ts +6 -0
- package/dist/fanout.js +20 -9
- package/dist/index.d.ts +4 -2
- package/dist/index.js +3 -2
- package/dist/lifecycle.d.ts +6 -1
- package/dist/lifecycle.js +3 -2
- package/dist/log.js +61 -16
- package/dist/memoize.d.ts +34 -0
- package/dist/memoize.js +136 -0
- package/dist/migrations.d.ts +64 -2
- package/dist/migrations.js +179 -34
- package/dist/outbox.d.ts +13 -0
- package/dist/outbox.js +78 -30
- package/dist/scheduler.d.ts +9 -0
- package/dist/scheduler.js +53 -11
- package/dist/semaphore-leases.js +15 -9
- package/dist/semaphore-queue-store.d.ts +12 -2
- package/dist/semaphore-queue-store.js +32 -5
- package/dist/semaphore-queue.js +109 -43
- package/dist/semaphore-server.js +7 -9
- package/dist/socket.js +19 -10
- package/dist/storage.d.ts +1 -0
- package/dist/storage.js +1 -1
- package/dist/topology-client.d.ts +40 -0
- package/dist/topology-client.js +180 -0
- package/dist/topology-snapshot.d.ts +70 -0
- package/dist/topology-snapshot.js +48 -0
- package/dist/topology.d.ts +94 -0
- package/dist/topology.js +468 -0
- package/dist/tracked-source.d.ts +2 -0
- package/dist/tracker.js +2 -0
- package/package.json +3 -2
package/dist/dev.js
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
import { serializeError } from './errors.js';
|
|
2
|
+
/**
|
|
3
|
+
* True only when the build defines `__DURABILITY_DEV__` as `true`. Bundlers
|
|
4
|
+
* fold the check to a constant, so production builds pay one branch per
|
|
5
|
+
* traced call and log nothing.
|
|
6
|
+
*/
|
|
7
|
+
const devMode = typeof __DURABILITY_DEV__ === 'boolean' && __DURABILITY_DEV__;
|
|
8
|
+
let sequence = 0;
|
|
9
|
+
/**
|
|
10
|
+
* Logs one dev-mode trace entry and returns its sequence number. The sequence
|
|
11
|
+
* is process-wide and monotonic so interleaved async work can be reordered
|
|
12
|
+
* and correlated when replaying a simulation.
|
|
13
|
+
*/
|
|
14
|
+
export const trace = (operation, details = {}) => {
|
|
15
|
+
if (!devMode) {
|
|
16
|
+
return 0;
|
|
17
|
+
}
|
|
18
|
+
sequence += 1;
|
|
19
|
+
// Tracing is best-effort: a logger that throws must not change the operation.
|
|
20
|
+
try {
|
|
21
|
+
console.debug({
|
|
22
|
+
event: `durability.dev.${operation}`,
|
|
23
|
+
seq: sequence,
|
|
24
|
+
at: Date.now(),
|
|
25
|
+
...details,
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
catch {
|
|
29
|
+
// Keep the sequence number so later entries still order correctly.
|
|
30
|
+
}
|
|
31
|
+
return sequence;
|
|
32
|
+
};
|
|
33
|
+
const traceCall = (operation, details, run) => {
|
|
34
|
+
const call = trace(operation, details);
|
|
35
|
+
let result;
|
|
36
|
+
try {
|
|
37
|
+
result = run();
|
|
38
|
+
}
|
|
39
|
+
catch (error) {
|
|
40
|
+
trace(`${operation}.throw`, { call, error: serializeError(error) });
|
|
41
|
+
throw error;
|
|
42
|
+
}
|
|
43
|
+
if (!(result instanceof Promise)) {
|
|
44
|
+
trace(`${operation}.return`, { call, result });
|
|
45
|
+
return result;
|
|
46
|
+
}
|
|
47
|
+
// Observes the promise without changing what the caller sees.
|
|
48
|
+
void result.then((value) => trace(`${operation}.return`, { call, result: value }), (error) => trace(`${operation}.throw`, { call, error: serializeError(error) }));
|
|
49
|
+
return result;
|
|
50
|
+
};
|
|
51
|
+
const loggableArgs = (args) => args.filter((arg) => typeof arg !== 'function');
|
|
52
|
+
/**
|
|
53
|
+
* Wraps a public function so dev mode logs its arguments and outcome. `details`
|
|
54
|
+
* identifies the receiver when the arguments alone do not.
|
|
55
|
+
*/
|
|
56
|
+
export const traceFunction = (method, fn, details = {}) => {
|
|
57
|
+
if (!devMode) {
|
|
58
|
+
return fn;
|
|
59
|
+
}
|
|
60
|
+
return function (...args) {
|
|
61
|
+
return traceCall('call', { method, ...details, args: loggableArgs(args) }, () => fn.apply(this, args));
|
|
62
|
+
};
|
|
63
|
+
};
|
|
64
|
+
/** Wraps every method on a class prototype with {@link traceFunction}. */
|
|
65
|
+
export const traceMethods = (prototype, owner) => {
|
|
66
|
+
if (!devMode) {
|
|
67
|
+
return;
|
|
68
|
+
}
|
|
69
|
+
for (const name of Object.getOwnPropertyNames(prototype)) {
|
|
70
|
+
const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
|
|
71
|
+
if (name === 'constructor' || typeof descriptor?.value !== 'function') {
|
|
72
|
+
continue;
|
|
73
|
+
}
|
|
74
|
+
Object.defineProperty(prototype, name, {
|
|
75
|
+
...descriptor,
|
|
76
|
+
value: traceFunction(`${owner}.${name}`, descriptor.value),
|
|
77
|
+
});
|
|
78
|
+
}
|
|
79
|
+
};
|
|
80
|
+
/** Logs each lifecycle event before `emit` hands it to the consumer's hooks. */
|
|
81
|
+
export const traceLifecycle = (emit) => {
|
|
82
|
+
if (!devMode) {
|
|
83
|
+
return emit;
|
|
84
|
+
}
|
|
85
|
+
return (event) => {
|
|
86
|
+
trace('lifecycle', event);
|
|
87
|
+
emit(event);
|
|
88
|
+
};
|
|
89
|
+
};
|
|
90
|
+
const compactQuery = (query) => query.replace(/\s+/g, ' ').trim();
|
|
91
|
+
const traceSql = (sql) => new Proxy(sql, {
|
|
92
|
+
get(target, key) {
|
|
93
|
+
const value = Reflect.get(target, key);
|
|
94
|
+
if (key === 'exec') {
|
|
95
|
+
return (query, ...bindings) => {
|
|
96
|
+
trace('sql', { query: compactQuery(query), bindings });
|
|
97
|
+
return target.exec(query, ...bindings);
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
return typeof value === 'function' ? value.bind(target) : value;
|
|
101
|
+
},
|
|
102
|
+
});
|
|
103
|
+
const proxyStorage = (storage, scope) => {
|
|
104
|
+
let sql;
|
|
105
|
+
return new Proxy(storage, {
|
|
106
|
+
get(target, key) {
|
|
107
|
+
const value = Reflect.get(target, key);
|
|
108
|
+
if (key === 'sql' && value !== undefined) {
|
|
109
|
+
sql ?? (sql = traceSql(value));
|
|
110
|
+
return sql;
|
|
111
|
+
}
|
|
112
|
+
if (typeof value !== 'function') {
|
|
113
|
+
return value;
|
|
114
|
+
}
|
|
115
|
+
const method = `${scope}.${String(key)}`;
|
|
116
|
+
return (...args) => {
|
|
117
|
+
// Alarm writes inside `transaction` go through the transaction object.
|
|
118
|
+
const forwarded = key === 'transaction' && typeof args[0] === 'function'
|
|
119
|
+
? [
|
|
120
|
+
(transaction) => args[0](proxyStorage(transaction, 'transaction')),
|
|
121
|
+
...args.slice(1),
|
|
122
|
+
]
|
|
123
|
+
: args;
|
|
124
|
+
return traceCall('storage', { method, args: loggableArgs(args) }, () => Reflect.apply(value, target, forwarded));
|
|
125
|
+
};
|
|
126
|
+
},
|
|
127
|
+
});
|
|
128
|
+
};
|
|
129
|
+
const tracedStorage = new WeakMap();
|
|
130
|
+
const storageProxies = new WeakSet();
|
|
131
|
+
/**
|
|
132
|
+
* In dev mode, returns a view of Durable Object storage that logs every SQL
|
|
133
|
+
* statement, transaction, and alarm read or write. Outside dev mode, returns
|
|
134
|
+
* the storage unchanged. Idempotent, so helpers sharing one storage log each
|
|
135
|
+
* call once.
|
|
136
|
+
*/
|
|
137
|
+
export const traceStorage = (storage) => {
|
|
138
|
+
if (!devMode || storageProxies.has(storage)) {
|
|
139
|
+
return storage;
|
|
140
|
+
}
|
|
141
|
+
const existing = tracedStorage.get(storage);
|
|
142
|
+
if (existing) {
|
|
143
|
+
return existing;
|
|
144
|
+
}
|
|
145
|
+
const traced = proxyStorage(storage, 'storage');
|
|
146
|
+
tracedStorage.set(storage, traced);
|
|
147
|
+
storageProxies.add(traced);
|
|
148
|
+
return traced;
|
|
149
|
+
};
|
|
@@ -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
|
};
|
|
@@ -50,7 +63,7 @@ export type DurableNamedAlarm = (scheduledTime: number) => Promise<void>;
|
|
|
50
63
|
declare class DurabilityAlarmsCore<Names extends string> {
|
|
51
64
|
#private;
|
|
52
65
|
constructor(config: DurabilityAlarmsConfig<Names>);
|
|
53
|
-
/** Applies or reverts the `durability_alarms` schema; see {@link
|
|
66
|
+
/** Applies or reverts the `durability_alarms` schema; see {@link migrateCapability}. */
|
|
54
67
|
static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
|
|
55
68
|
/** Runs due named alarms and re-arms the physical alarm. */
|
|
56
69
|
alarm(info?: AlarmInvocationInfo): Promise<void>;
|
|
@@ -11,11 +11,13 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
|
|
|
11
11
|
};
|
|
12
12
|
var _DurabilityAlarmsCore_instances, _DurabilityAlarmsCore_engine, _DurabilityAlarmsCore_handlers, _DurabilityAlarmsCore_policy, _DurabilityAlarmsCore_lifecycle, _DurabilityAlarmsCore_emit, _DurabilityAlarmsCore_active, _DurabilityAlarmsCore_trackedSource, _DurabilityAlarmsCore_runDue, _DurabilityAlarmsCore_schedule, _DurabilityAlarmsCore_execute;
|
|
13
13
|
import { z } from 'zod';
|
|
14
|
+
import { traceFunction, traceMethods } from './dev.js';
|
|
14
15
|
import { DurableAlarmTimeoutError, DurableAttemptsExhaustedError, isErrorInstance, NonRetryableError, } from './errors.js';
|
|
15
16
|
import { createLifecycleHooks, } from './lifecycle.js';
|
|
16
|
-
import { durabilityNamedAlarmMigrations,
|
|
17
|
+
import { durabilityNamedAlarmMigrations, durabilityMemoMigrations, migrateCapability, } from './migrations.js';
|
|
17
18
|
import { alarmMethodOptionsSchema, createPolicyResolver, } from './policy.js';
|
|
18
19
|
import { engineFor, } from './scheduler.js';
|
|
20
|
+
import { createMemoize, deleteMemos, deleteMemosOfDroppedTable, memoizedKeys, } from './memoize.js';
|
|
19
21
|
import { deleteAttempt, listCreated } from './storage.js';
|
|
20
22
|
import { registerTrackedSource, } from './tracked-source.js';
|
|
21
23
|
const alarmRowSchema = z.object({
|
|
@@ -36,7 +38,7 @@ const readAlarm = (sql, name) => alarmRowSchema
|
|
|
36
38
|
.parse(sql
|
|
37
39
|
.exec('SELECT * FROM durability_alarms WHERE name = ?', name)
|
|
38
40
|
.toArray()[0]);
|
|
39
|
-
const alarmRecord = (row) => ({
|
|
41
|
+
const alarmRecord = (sql, row) => ({
|
|
40
42
|
id: row.name,
|
|
41
43
|
name: row.name,
|
|
42
44
|
generation: row.generation_id,
|
|
@@ -47,6 +49,7 @@ const alarmRecord = (row) => ({
|
|
|
47
49
|
attempt: row.attempt,
|
|
48
50
|
nextAttemptAt: row.next_attempt_at,
|
|
49
51
|
lastError: row.last_error,
|
|
52
|
+
memoized: memoizedKeys(sql, alarmsTable, row.name, row.generation_id),
|
|
50
53
|
}
|
|
51
54
|
: {
|
|
52
55
|
status: 'failed',
|
|
@@ -83,20 +86,23 @@ class DurabilityAlarmsCore {
|
|
|
83
86
|
throw new Error(`"${name}" is reserved by DurabilityAlarms`);
|
|
84
87
|
}
|
|
85
88
|
Object.defineProperty(this, name, {
|
|
86
|
-
value: (scheduledTime) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_schedule).call(this, name, scheduledTime),
|
|
89
|
+
value: traceFunction(`DurabilityAlarms.${name}`, (scheduledTime) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_schedule).call(this, name, scheduledTime)),
|
|
87
90
|
enumerable: true,
|
|
88
91
|
});
|
|
89
92
|
}
|
|
90
93
|
__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").migrateSchema('namedAlarms', durabilityNamedAlarmMigrations);
|
|
94
|
+
__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").migrateSchema('memos', durabilityMemoMigrations);
|
|
91
95
|
__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").register({
|
|
92
96
|
table: alarmsTable,
|
|
93
97
|
runDue: (now, info) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_runDue).call(this, now, info),
|
|
94
98
|
});
|
|
95
99
|
registerTrackedSource(this, __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_trackedSource).call(this));
|
|
96
100
|
}
|
|
97
|
-
/** Applies or reverts the `durability_alarms` schema; see {@link
|
|
101
|
+
/** Applies or reverts the `durability_alarms` schema; see {@link migrateCapability}. */
|
|
98
102
|
static migrate(context, target) {
|
|
99
|
-
|
|
103
|
+
const result = migrateCapability(context.storage, 'namedAlarms', durabilityNamedAlarmMigrations, target);
|
|
104
|
+
deleteMemosOfDroppedTable(context.storage.sql, alarmsTable);
|
|
105
|
+
return result;
|
|
100
106
|
}
|
|
101
107
|
/** Runs due named alarms and re-arms the physical alarm. */
|
|
102
108
|
alarm(info) {
|
|
@@ -130,7 +136,7 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
|
|
|
130
136
|
return {
|
|
131
137
|
get: async (name) => {
|
|
132
138
|
const row = readAlarm(sql, name);
|
|
133
|
-
return row && alarmRecord(row);
|
|
139
|
+
return row && alarmRecord(sql, row);
|
|
134
140
|
},
|
|
135
141
|
list: async ({ limit, cursor, status, name }) => {
|
|
136
142
|
const page = listCreated(sql, alarmsTable, 'name', {
|
|
@@ -142,7 +148,7 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
|
|
|
142
148
|
const records = alarmRowSchema
|
|
143
149
|
.array()
|
|
144
150
|
.parse(page.rows)
|
|
145
|
-
.map(alarmRecord);
|
|
151
|
+
.map((row) => alarmRecord(sql, row));
|
|
146
152
|
return page.next === undefined
|
|
147
153
|
? { records }
|
|
148
154
|
: { records, cursor: page.next };
|
|
@@ -200,6 +206,8 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
|
|
|
200
206
|
last_error = excluded.last_error,
|
|
201
207
|
last_error_name = excluded.last_error_name,
|
|
202
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);
|
|
203
211
|
});
|
|
204
212
|
// A waiter on the replaced occurrence resolves now instead of at its timeout.
|
|
205
213
|
__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").notify(alarmsTable, name);
|
|
@@ -244,6 +252,11 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
|
|
|
244
252
|
retryCount: attempt - 1,
|
|
245
253
|
idempotencyKey: `durability-alarm:v1:${row.generation_id}`,
|
|
246
254
|
signal,
|
|
255
|
+
memoize: createMemoize(__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").sql, alarmsTable, {
|
|
256
|
+
key: row.name,
|
|
257
|
+
generation: row.generation_id,
|
|
258
|
+
attempt,
|
|
259
|
+
}),
|
|
247
260
|
platform,
|
|
248
261
|
});
|
|
249
262
|
},
|
|
@@ -259,6 +272,7 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
|
|
|
259
272
|
isTerminal: (error) => isErrorInstance(error, DurableAlarmTimeoutError) && !retryTimeouts,
|
|
260
273
|
});
|
|
261
274
|
};
|
|
275
|
+
traceMethods(DurabilityAlarmsCore.prototype, 'DurabilityAlarms');
|
|
262
276
|
// See Durability: members derived from the handler names cannot be declared on
|
|
263
277
|
// the class, so the constructor is typed separately.
|
|
264
278
|
export const DurabilityAlarms = DurabilityAlarmsCore;
|
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
|
|
@@ -133,7 +153,7 @@ export type DurabilityConfig<Handlers extends HandlerMap = HandlerMap> = Durabil
|
|
|
133
153
|
declare class DurabilityCore<Handlers extends HandlerMap> {
|
|
134
154
|
#private;
|
|
135
155
|
constructor(config: DurabilityConfig<Handlers>);
|
|
136
|
-
/** Applies or reverts the `durability_calls` schema; see {@link
|
|
156
|
+
/** Applies or reverts the `durability_calls` schema; see {@link migrateCapability}. */
|
|
137
157
|
static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
|
|
138
158
|
/** Processes due operations and re-arms the physical alarm. */
|
|
139
159
|
alarm(info?: AlarmInvocationInfo): Promise<void>;
|
|
@@ -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,14 +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
|
+
import { traceFunction, traceMethods } from './dev.js';
|
|
14
15
|
import { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, isErrorInstance, NonRetryableError, reportFailure, } from './errors.js';
|
|
15
16
|
import { createLifecycleHooks, } from './lifecycle.js';
|
|
16
|
-
import { durabilityOperationMigrations,
|
|
17
|
+
import { durabilityOperationMigrations, durabilityMemoMigrations, migrateCapability, } from './migrations.js';
|
|
17
18
|
import { createPolicyResolver, methodOptionsSchema, } from './policy.js';
|
|
18
19
|
import { engineFor, } from './scheduler.js';
|
|
19
20
|
import { canonical, deserialize, serialize } from './serialization.js';
|
|
21
|
+
import { createMemoize, deleteMemosOfDroppedTable, memoizedKeys, } from './memoize.js';
|
|
20
22
|
import { listCreated, updateAttempt } from './storage.js';
|
|
21
23
|
import { registerTrackedSource, } from './tracked-source.js';
|
|
22
24
|
const callRowSchema = z.object({
|
|
@@ -66,13 +68,21 @@ const callState = (call) => {
|
|
|
66
68
|
}
|
|
67
69
|
return { status: 'completed', result: deserialize(call.result) };
|
|
68
70
|
};
|
|
69
|
-
const callRecord = (call) =>
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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
|
+
};
|
|
76
86
|
const operationEntity = (call) => ({
|
|
77
87
|
entityKind: 'operation',
|
|
78
88
|
operation: call.operation,
|
|
@@ -87,6 +97,7 @@ class DurabilityCore {
|
|
|
87
97
|
_DurabilityCore_policy.set(this, void 0);
|
|
88
98
|
_DurabilityCore_lifecycle.set(this, void 0);
|
|
89
99
|
_DurabilityCore_emit.set(this, void 0);
|
|
100
|
+
_DurabilityCore_includeResults.set(this, void 0);
|
|
90
101
|
_DurabilityCore_active.set(this, new Map());
|
|
91
102
|
_DurabilityCore_executionStarts.set(this, new Map());
|
|
92
103
|
const { handlers } = config;
|
|
@@ -95,28 +106,33 @@ class DurabilityCore {
|
|
|
95
106
|
__classPrivateFieldSet(this, _DurabilityCore_policy, createPolicyResolver(config, config.methods ?? {}, methodOptionsSchema), "f");
|
|
96
107
|
__classPrivateFieldSet(this, _DurabilityCore_lifecycle, createLifecycleHooks((hook) => __classPrivateFieldGet(this, _DurabilityCore_engine, "f").emitter(hook), config.onLifecycleEvent), "f");
|
|
97
108
|
__classPrivateFieldSet(this, _DurabilityCore_emit, __classPrivateFieldGet(this, _DurabilityCore_lifecycle, "f").emit, "f");
|
|
109
|
+
__classPrivateFieldSet(this, _DurabilityCore_includeResults, config.includeResults ?? false, "f");
|
|
98
110
|
const reserved = new Set(Object.getOwnPropertyNames(DurabilityCore.prototype));
|
|
99
111
|
for (const operation of Object.keys(handlers)) {
|
|
100
112
|
if (reserved.has(operation)) {
|
|
101
113
|
throw new Error(`"${operation}" is reserved by Durability`);
|
|
102
114
|
}
|
|
103
|
-
const method = (input) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_run).call(this, { ...input, operation })
|
|
104
|
-
|
|
115
|
+
const method = Object.assign(traceFunction(`Durability.${operation}`, (input) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_run).call(this, { ...input, operation })), {
|
|
116
|
+
getResult: traceFunction(`Durability.${operation}.getResult`, (idempotencyKey) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_getResult).call(this, operation, idempotencyKey)),
|
|
117
|
+
});
|
|
105
118
|
Object.defineProperty(this, operation, {
|
|
106
119
|
value: method,
|
|
107
120
|
enumerable: true,
|
|
108
121
|
});
|
|
109
122
|
}
|
|
110
123
|
__classPrivateFieldGet(this, _DurabilityCore_engine, "f").migrateSchema('operations', durabilityOperationMigrations);
|
|
124
|
+
__classPrivateFieldGet(this, _DurabilityCore_engine, "f").migrateSchema('memos', durabilityMemoMigrations);
|
|
111
125
|
__classPrivateFieldGet(this, _DurabilityCore_engine, "f").register({
|
|
112
126
|
table: callsTable,
|
|
113
127
|
runDue: (now) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_runDue).call(this, now),
|
|
114
128
|
});
|
|
115
129
|
registerTrackedSource(this, __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_trackedSource).call(this));
|
|
116
130
|
}
|
|
117
|
-
/** Applies or reverts the `durability_calls` schema; see {@link
|
|
131
|
+
/** Applies or reverts the `durability_calls` schema; see {@link migrateCapability}. */
|
|
118
132
|
static migrate(context, target) {
|
|
119
|
-
|
|
133
|
+
const result = migrateCapability(context.storage, 'operations', durabilityOperationMigrations, target);
|
|
134
|
+
deleteMemosOfDroppedTable(context.storage.sql, callsTable);
|
|
135
|
+
return result;
|
|
120
136
|
}
|
|
121
137
|
/** Processes due operations and re-arms the physical alarm. */
|
|
122
138
|
alarm(info) {
|
|
@@ -145,12 +161,12 @@ class DurabilityCore {
|
|
|
145
161
|
return count;
|
|
146
162
|
}
|
|
147
163
|
}
|
|
148
|
-
_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() {
|
|
149
165
|
const sql = __classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql;
|
|
150
166
|
return {
|
|
151
167
|
get: async (id) => {
|
|
152
168
|
const call = readCall(sql, id);
|
|
153
|
-
return call && callRecord(call);
|
|
169
|
+
return call && callRecord(sql, call);
|
|
154
170
|
},
|
|
155
171
|
list: async ({ limit, cursor, status, name }) => {
|
|
156
172
|
const page = listCreated(sql, callsTable, 'operation', {
|
|
@@ -159,7 +175,10 @@ _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap()
|
|
|
159
175
|
status,
|
|
160
176
|
name,
|
|
161
177
|
});
|
|
162
|
-
const records = callRowSchema
|
|
178
|
+
const records = callRowSchema
|
|
179
|
+
.array()
|
|
180
|
+
.parse(page.rows)
|
|
181
|
+
.map((call) => callRecord(sql, call));
|
|
163
182
|
return page.next === undefined
|
|
164
183
|
? { records }
|
|
165
184
|
: { records, cursor: page.next };
|
|
@@ -287,6 +306,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
|
|
|
287
306
|
active: __classPrivateFieldGet(this, _DurabilityCore_active, "f"),
|
|
288
307
|
policy,
|
|
289
308
|
emit: __classPrivateFieldGet(this, _DurabilityCore_emit, "f"),
|
|
309
|
+
includeResult: __classPrivateFieldGet(this, _DurabilityCore_includeResults, "f"),
|
|
290
310
|
exhaustedError: () => new DurableAttemptsExhaustedError('operation', call.operation, policy.maxAttempts),
|
|
291
311
|
timeoutError: () => new DurableAttemptTimeoutError(call.operation, policy.attemptTimeoutMs),
|
|
292
312
|
invoke: (attempt, signal) => {
|
|
@@ -299,6 +319,11 @@ async function _DurabilityCore_execute(id, eagerPermit) {
|
|
|
299
319
|
payload: deserialize(call.payload),
|
|
300
320
|
attempt,
|
|
301
321
|
signal,
|
|
322
|
+
memoize: createMemoize(__classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql, callsTable, {
|
|
323
|
+
key: call.id,
|
|
324
|
+
generation: call.generation_id,
|
|
325
|
+
attempt,
|
|
326
|
+
}),
|
|
302
327
|
});
|
|
303
328
|
},
|
|
304
329
|
complete: (result, attempt) => {
|
|
@@ -317,6 +342,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
|
|
|
317
342
|
isTerminal: (error) => isErrorInstance(error, DurableResultSerializationError),
|
|
318
343
|
}, eagerPermit);
|
|
319
344
|
};
|
|
345
|
+
traceMethods(DurabilityCore.prototype, 'Durability');
|
|
320
346
|
// TypeScript cannot declare class members derived from a generic handler map,
|
|
321
347
|
// so the constructor is typed separately; the constructor installs and reserves
|
|
322
348
|
// every operation method at runtime.
|
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);
|
|
@@ -115,3 +129,20 @@ export declare const isErrorInstance: (error: unknown, constructor: new (...args
|
|
|
115
129
|
/** Recognizes this package's NonRetryableError and same-named errors from other packages. */
|
|
116
130
|
export declare const isNonRetryable: (error: unknown) => boolean;
|
|
117
131
|
export declare const reportFailure: (event: string, details: Record<string, unknown>, error: unknown) => void;
|
|
132
|
+
/** A definite rejection of a topology change or configuration. */
|
|
133
|
+
export declare class TopologyError extends Error {
|
|
134
|
+
constructor(message: string);
|
|
135
|
+
}
|
|
136
|
+
/** Why a topology client could not use the published snapshot. */
|
|
137
|
+
export type TopologyFallbackReason = 'missing' | 'invalid' | 'timeout' | 'error';
|
|
138
|
+
/**
|
|
139
|
+
* Thrown by a topology client when the published snapshot is unusable and no
|
|
140
|
+
* configured fallback produced one. The client never asks the coordinator.
|
|
141
|
+
*/
|
|
142
|
+
export declare class TopologyUnavailableError extends Error {
|
|
143
|
+
readonly group: string;
|
|
144
|
+
readonly reason: TopologyFallbackReason;
|
|
145
|
+
constructor(group: string, reason: TopologyFallbackReason, options?: {
|
|
146
|
+
cause?: unknown;
|
|
147
|
+
});
|
|
148
|
+
}
|
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) {
|
|
@@ -234,3 +257,25 @@ export const reportFailure = (event, details, error) => {
|
|
|
234
257
|
return;
|
|
235
258
|
}
|
|
236
259
|
};
|
|
260
|
+
/** A definite rejection of a topology change or configuration. */
|
|
261
|
+
export class TopologyError extends Error {
|
|
262
|
+
constructor(message) {
|
|
263
|
+
super(message);
|
|
264
|
+
this.name = 'TopologyError';
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
/**
|
|
268
|
+
* Thrown by a topology client when the published snapshot is unusable and no
|
|
269
|
+
* configured fallback produced one. The client never asks the coordinator.
|
|
270
|
+
*/
|
|
271
|
+
export class TopologyUnavailableError extends Error {
|
|
272
|
+
constructor(group, reason, options) {
|
|
273
|
+
super(`Topology for group "${group}" is unavailable: ${reason}`);
|
|
274
|
+
this.group = group;
|
|
275
|
+
this.reason = reason;
|
|
276
|
+
this.name = 'TopologyUnavailableError';
|
|
277
|
+
if (options?.cause !== undefined) {
|
|
278
|
+
Object.defineProperty(this, 'cause', { value: options.cause });
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
}
|
package/dist/experimental.d.ts
CHANGED
|
@@ -9,3 +9,8 @@ export type { TrackedEntry, TrackedPage, TrackedQuery, TrackedRecord, TrackedRes
|
|
|
9
9
|
export { DurabilityOutbox, type DurabilityOutboxConfig, type DurabilityOutboxEvent, type OutboxEntry, } from './outbox.js';
|
|
10
10
|
export { OutboxTimeoutError } from './errors.js';
|
|
11
11
|
export { durabilityOutboxMigrations } from './migrations.js';
|
|
12
|
+
export { DurabilityTopology, type DurabilityTopologyConfig, type DurabilityTopologyEvent, type TopologyChannel, type TopologyCurrent, type TopologyDraft, type TopologyPublisher, type TopologyRetryOptions, type TopologyRole, type TopologyStateUpdate, } from './topology.js';
|
|
13
|
+
export type { TopologyClient, TopologyClientConfig, TopologySource, TopologyView, } from './topology-client.js';
|
|
14
|
+
export type { TopologyMember, TopologyMemberInput, TopologyMemberState, TopologySnapshot, } from './topology-snapshot.js';
|
|
15
|
+
export { TopologyError, TopologyUnavailableError, type TopologyFallbackReason, } from './errors.js';
|
|
16
|
+
export { durabilityTopologyMigrations } from './migrations.js';
|
package/dist/experimental.js
CHANGED
|
@@ -8,3 +8,6 @@ export { DurabilityTracker, } from './tracker.js';
|
|
|
8
8
|
export { DurabilityOutbox, } from './outbox.js';
|
|
9
9
|
export { OutboxTimeoutError } from './errors.js';
|
|
10
10
|
export { durabilityOutboxMigrations } from './migrations.js';
|
|
11
|
+
export { DurabilityTopology, } from './topology.js';
|
|
12
|
+
export { TopologyError, TopologyUnavailableError, } from './errors.js';
|
|
13
|
+
export { durabilityTopologyMigrations } from './migrations.js';
|