durability 3.0.1 → 4.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 +398 -25
- package/dist/client.d.ts +94 -0
- package/dist/client.js +445 -0
- package/dist/durability-alarms.d.ts +14 -1
- package/dist/durability-alarms.js +121 -22
- package/dist/durability.d.ts +32 -1
- package/dist/durability.js +119 -61
- package/dist/errors.d.ts +22 -0
- package/dist/errors.js +31 -0
- package/dist/experimental.d.ts +8 -0
- package/dist/experimental.js +7 -0
- package/dist/fanout.d.ts +25 -2
- package/dist/fanout.js +273 -93
- package/dist/index.d.ts +8 -7
- package/dist/index.js +3 -2
- package/dist/lifecycle.d.ts +8 -0
- package/dist/lifecycle.js +22 -0
- package/dist/log.d.ts +201 -0
- package/dist/log.js +705 -0
- package/dist/migrations.d.ts +28 -1
- package/dist/migrations.js +100 -0
- package/dist/scheduler.d.ts +35 -20
- package/dist/scheduler.js +112 -90
- package/dist/socket-protocol.d.ts +95 -0
- package/dist/socket-protocol.js +71 -0
- package/dist/socket.d.ts +92 -0
- package/dist/socket.js +273 -0
- package/dist/storage.d.ts +39 -128
- package/dist/storage.js +64 -68
- package/dist/tracked-source.d.ts +87 -0
- package/dist/tracked-source.js +7 -0
- package/dist/tracker.d.ts +96 -0
- package/dist/tracker.js +171 -0
- package/package.json +18 -4
- package/dist/kv-storage.d.ts +0 -2
- package/dist/kv-storage.js +0 -421
- package/dist/sqlite-storage.d.ts +0 -2
- package/dist/sqlite-storage.js +0 -251
|
@@ -9,13 +9,54 @@ 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 _DurabilityAlarmsCore_instances, _DurabilityAlarmsCore_engine, _DurabilityAlarmsCore_handlers, _DurabilityAlarmsCore_policy, _DurabilityAlarmsCore_emit, _DurabilityAlarmsCore_active, _DurabilityAlarmsCore_runDue, _DurabilityAlarmsCore_schedule, _DurabilityAlarmsCore_execute;
|
|
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
14
|
import { DurableAlarmTimeoutError, DurableAttemptsExhaustedError, isErrorInstance, NonRetryableError, } from './errors.js';
|
|
15
|
+
import { createLifecycleHooks, } from './lifecycle.js';
|
|
15
16
|
import { durabilityNamedAlarmMigrations, migrate, } from './migrations.js';
|
|
16
17
|
import { alarmMethodOptionsSchema, createPolicyResolver, } from './policy.js';
|
|
17
18
|
import { engineFor, } from './scheduler.js';
|
|
19
|
+
import { deleteAttempt, listCreated } from './storage.js';
|
|
20
|
+
import { registerTrackedSource, } from './tracked-source.js';
|
|
21
|
+
const alarmRowSchema = z.object({
|
|
22
|
+
name: z.string(),
|
|
23
|
+
generation_id: z.string(),
|
|
24
|
+
status: z.enum(['pending', 'failed']),
|
|
25
|
+
scheduled_at: z.number().int().nonnegative(),
|
|
26
|
+
next_attempt_at: z.number().int().nonnegative(),
|
|
27
|
+
attempt: z.number().int().nonnegative(),
|
|
28
|
+
last_error: z.string().nullable(),
|
|
29
|
+
last_error_name: z.string().nullable(),
|
|
30
|
+
created_at: z.number().int().nonnegative(),
|
|
31
|
+
});
|
|
32
|
+
const alarmsTable = { name: 'durability_alarms', key: 'name' };
|
|
18
33
|
const alarmHandlerSchema = z.custom((value) => typeof value === 'function');
|
|
34
|
+
const readAlarm = (sql, name) => alarmRowSchema
|
|
35
|
+
.optional()
|
|
36
|
+
.parse(sql
|
|
37
|
+
.exec('SELECT * FROM durability_alarms WHERE name = ?', name)
|
|
38
|
+
.toArray()[0]);
|
|
39
|
+
const alarmRecord = (row) => ({
|
|
40
|
+
id: row.name,
|
|
41
|
+
name: row.name,
|
|
42
|
+
generation: row.generation_id,
|
|
43
|
+
createdAt: row.created_at,
|
|
44
|
+
state: row.status === 'pending'
|
|
45
|
+
? {
|
|
46
|
+
status: 'pending',
|
|
47
|
+
attempt: row.attempt,
|
|
48
|
+
nextAttemptAt: row.next_attempt_at,
|
|
49
|
+
lastError: row.last_error,
|
|
50
|
+
}
|
|
51
|
+
: {
|
|
52
|
+
status: 'failed',
|
|
53
|
+
attempt: row.attempt,
|
|
54
|
+
error: {
|
|
55
|
+
name: row.last_error_name ?? 'Error',
|
|
56
|
+
message: row.last_error ?? 'Durable alarm failed',
|
|
57
|
+
},
|
|
58
|
+
},
|
|
59
|
+
});
|
|
19
60
|
const alarmEntity = (row) => ({
|
|
20
61
|
entityKind: 'named_alarm',
|
|
21
62
|
alarm: row.name,
|
|
@@ -28,12 +69,14 @@ class DurabilityAlarmsCore {
|
|
|
28
69
|
_DurabilityAlarmsCore_engine.set(this, void 0);
|
|
29
70
|
_DurabilityAlarmsCore_handlers.set(this, void 0);
|
|
30
71
|
_DurabilityAlarmsCore_policy.set(this, void 0);
|
|
72
|
+
_DurabilityAlarmsCore_lifecycle.set(this, void 0);
|
|
31
73
|
_DurabilityAlarmsCore_emit.set(this, void 0);
|
|
32
74
|
_DurabilityAlarmsCore_active.set(this, new Map());
|
|
33
75
|
__classPrivateFieldSet(this, _DurabilityAlarmsCore_engine, engineFor(config), "f");
|
|
34
76
|
__classPrivateFieldSet(this, _DurabilityAlarmsCore_handlers, new Map(Object.entries(config.handlers).map(([name, handler]) => [name, alarmHandlerSchema.parse(handler)])), "f");
|
|
35
77
|
__classPrivateFieldSet(this, _DurabilityAlarmsCore_policy, createPolicyResolver(config, config.methods ?? {}, alarmMethodOptionsSchema), "f");
|
|
36
|
-
__classPrivateFieldSet(this,
|
|
78
|
+
__classPrivateFieldSet(this, _DurabilityAlarmsCore_lifecycle, createLifecycleHooks((hook) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").emitter(hook), config.onLifecycleEvent), "f");
|
|
79
|
+
__classPrivateFieldSet(this, _DurabilityAlarmsCore_emit, __classPrivateFieldGet(this, _DurabilityAlarmsCore_lifecycle, "f").emit, "f");
|
|
37
80
|
const reserved = new Set(Object.getOwnPropertyNames(DurabilityAlarmsCore.prototype));
|
|
38
81
|
for (const name of __classPrivateFieldGet(this, _DurabilityAlarmsCore_handlers, "f").keys()) {
|
|
39
82
|
if (reserved.has(name)) {
|
|
@@ -46,9 +89,10 @@ class DurabilityAlarmsCore {
|
|
|
46
89
|
}
|
|
47
90
|
__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").migrateSchema('namedAlarms', durabilityNamedAlarmMigrations);
|
|
48
91
|
__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").register({
|
|
49
|
-
|
|
92
|
+
table: alarmsTable,
|
|
50
93
|
runDue: (now, info) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_runDue).call(this, now, info),
|
|
51
94
|
});
|
|
95
|
+
registerTrackedSource(this, __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_trackedSource).call(this));
|
|
52
96
|
}
|
|
53
97
|
/** Applies or reverts the `durability_alarms` schema; see {@link migrate}. */
|
|
54
98
|
static migrate(context, target) {
|
|
@@ -58,12 +102,19 @@ class DurabilityAlarmsCore {
|
|
|
58
102
|
alarm(info) {
|
|
59
103
|
return __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").alarm(info);
|
|
60
104
|
}
|
|
105
|
+
/**
|
|
106
|
+
* Attaches a best-effort lifecycle hook alongside `onLifecycleEvent` and
|
|
107
|
+
* returns a function that detaches it.
|
|
108
|
+
*/
|
|
109
|
+
lifecycle(hook) {
|
|
110
|
+
return __classPrivateFieldGet(this, _DurabilityAlarmsCore_lifecycle, "f").add(hook);
|
|
111
|
+
}
|
|
61
112
|
/**
|
|
62
113
|
* Destructively removes named alarm records created strictly before the
|
|
63
114
|
* timestamp, regardless of status, and returns how many were removed.
|
|
64
115
|
*/
|
|
65
116
|
async purgeBefore(before) {
|
|
66
|
-
const count = await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").purge(
|
|
117
|
+
const count = await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").purge(alarmsTable, before, __classPrivateFieldGet(this, _DurabilityAlarmsCore_active, "f"), 'Durable alarm was purged');
|
|
67
118
|
__classPrivateFieldGet(this, _DurabilityAlarmsCore_emit, "f").call(this, {
|
|
68
119
|
type: 'purged',
|
|
69
120
|
entityKind: 'named_alarm',
|
|
@@ -74,8 +125,49 @@ class DurabilityAlarmsCore {
|
|
|
74
125
|
return count;
|
|
75
126
|
}
|
|
76
127
|
}
|
|
77
|
-
_DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = new WeakMap(), _DurabilityAlarmsCore_policy = new WeakMap(), _DurabilityAlarmsCore_emit = new WeakMap(), _DurabilityAlarmsCore_active = new WeakMap(), _DurabilityAlarmsCore_instances = new WeakSet(),
|
|
78
|
-
const
|
|
128
|
+
_DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = new WeakMap(), _DurabilityAlarmsCore_policy = new WeakMap(), _DurabilityAlarmsCore_lifecycle = new WeakMap(), _DurabilityAlarmsCore_emit = new WeakMap(), _DurabilityAlarmsCore_active = new WeakMap(), _DurabilityAlarmsCore_instances = new WeakSet(), _DurabilityAlarmsCore_trackedSource = function _DurabilityAlarmsCore_trackedSource() {
|
|
129
|
+
const sql = __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").sql;
|
|
130
|
+
return {
|
|
131
|
+
get: async (name) => {
|
|
132
|
+
const row = readAlarm(sql, name);
|
|
133
|
+
return row && alarmRecord(row);
|
|
134
|
+
},
|
|
135
|
+
list: async ({ limit, cursor, status, name }) => {
|
|
136
|
+
const page = listCreated(sql, alarmsTable, 'name', {
|
|
137
|
+
limit,
|
|
138
|
+
after: cursor,
|
|
139
|
+
status,
|
|
140
|
+
name,
|
|
141
|
+
});
|
|
142
|
+
const records = alarmRowSchema
|
|
143
|
+
.array()
|
|
144
|
+
.parse(page.rows)
|
|
145
|
+
.map(alarmRecord);
|
|
146
|
+
return page.next === undefined
|
|
147
|
+
? { records }
|
|
148
|
+
: { records, cursor: page.next };
|
|
149
|
+
},
|
|
150
|
+
watch: (name, listener) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").watch(alarmsTable, name, (completed) => {
|
|
151
|
+
if (!completed) {
|
|
152
|
+
listener();
|
|
153
|
+
return;
|
|
154
|
+
}
|
|
155
|
+
listener({
|
|
156
|
+
id: name,
|
|
157
|
+
name,
|
|
158
|
+
generation: completed.generation_id,
|
|
159
|
+
createdAt: completed.created_at,
|
|
160
|
+
state: { status: 'completed', result: undefined },
|
|
161
|
+
});
|
|
162
|
+
}),
|
|
163
|
+
};
|
|
164
|
+
}, _DurabilityAlarmsCore_runDue = async function _DurabilityAlarmsCore_runDue(now, info) {
|
|
165
|
+
const due = alarmRowSchema.array().parse(__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").sql
|
|
166
|
+
.exec(`SELECT * FROM durability_alarms
|
|
167
|
+
WHERE status = 'pending' AND next_attempt_at <= ?
|
|
168
|
+
ORDER BY next_attempt_at ASC
|
|
169
|
+
LIMIT 100`, now)
|
|
170
|
+
.toArray());
|
|
79
171
|
const failures = [];
|
|
80
172
|
await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").runConcurrent(due, async (row) => {
|
|
81
173
|
try {
|
|
@@ -94,20 +186,23 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
|
|
|
94
186
|
}
|
|
95
187
|
const generation = crypto.randomUUID();
|
|
96
188
|
const createdAt = Date.now();
|
|
97
|
-
await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").transaction(
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
189
|
+
await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").transaction((sql) => {
|
|
190
|
+
sql.exec(`INSERT INTO durability_alarms
|
|
191
|
+
(name, generation_id, status, scheduled_at, next_attempt_at,
|
|
192
|
+
attempt, last_error, last_error_name, created_at)
|
|
193
|
+
VALUES (?, ?, 'pending', ?, ?, 0, NULL, NULL, ?)
|
|
194
|
+
ON CONFLICT(name) DO UPDATE SET
|
|
195
|
+
generation_id = excluded.generation_id,
|
|
196
|
+
status = excluded.status,
|
|
197
|
+
scheduled_at = excluded.scheduled_at,
|
|
198
|
+
next_attempt_at = excluded.next_attempt_at,
|
|
199
|
+
attempt = excluded.attempt,
|
|
200
|
+
last_error = excluded.last_error,
|
|
201
|
+
last_error_name = excluded.last_error_name,
|
|
202
|
+
created_at = excluded.created_at`, name, generation, scheduledTime, scheduledTime, createdAt);
|
|
110
203
|
});
|
|
204
|
+
// A waiter on the replaced occurrence resolves now instead of at its timeout.
|
|
205
|
+
__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").notify(alarmsTable, name);
|
|
111
206
|
__classPrivateFieldGet(this, _DurabilityAlarmsCore_emit, "f").call(this, {
|
|
112
207
|
type: 'scheduled',
|
|
113
208
|
entityKind: 'named_alarm',
|
|
@@ -126,7 +221,7 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
|
|
|
126
221
|
const policy = __classPrivateFieldGet(this, _DurabilityAlarmsCore_policy, "f").call(this, row.name);
|
|
127
222
|
const retryTimeouts = policy.method?.retryTimeouts ?? false;
|
|
128
223
|
return __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").startExecution({
|
|
129
|
-
|
|
224
|
+
table: alarmsTable,
|
|
130
225
|
key: row.name,
|
|
131
226
|
row,
|
|
132
227
|
label: `named alarm "${row.name}"`,
|
|
@@ -152,9 +247,13 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
|
|
|
152
247
|
platform,
|
|
153
248
|
});
|
|
154
249
|
},
|
|
155
|
-
complete:
|
|
250
|
+
complete: (_result, attempt) => {
|
|
156
251
|
const timestamp = Date.now();
|
|
157
|
-
const removed =
|
|
252
|
+
const removed = deleteAttempt(__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").sql, alarmsTable, {
|
|
253
|
+
key: row.name,
|
|
254
|
+
generation: row.generation_id,
|
|
255
|
+
attempt,
|
|
256
|
+
});
|
|
158
257
|
return removed ? timestamp : undefined;
|
|
159
258
|
},
|
|
160
259
|
isTerminal: (error) => isErrorInstance(error, DurableAlarmTimeoutError) && !retryTimeouts,
|
package/dist/durability.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type LifecycleHook } from './lifecycle.js';
|
|
1
|
+
import { type DurabilityLifecycleEvent, type LifecycleHook } from './lifecycle.js';
|
|
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';
|
|
@@ -32,6 +32,10 @@ export type DurableHandler<Payload, Result> = (call: DurableCall<Payload>) => Re
|
|
|
32
32
|
export type HandlerMap = Record<string, (...args: never[]) => unknown>;
|
|
33
33
|
type HandlerPayload<Handler> = Handler extends (call: DurableCall<infer Payload>) => unknown ? Payload : never;
|
|
34
34
|
type HandlerResult<Handler> = Handler extends (...args: never[]) => infer Result ? Awaited<Result> : never;
|
|
35
|
+
/** Result types of every operation, keyed by handler name. */
|
|
36
|
+
export type OperationResults<Handlers extends HandlerMap> = {
|
|
37
|
+
[Operation in Extract<keyof Handlers, string>]: HandlerResult<Handlers[Operation]>;
|
|
38
|
+
};
|
|
35
39
|
type DurableOperationInput<Handler> = {
|
|
36
40
|
/** Stable idempotency key used to deduplicate the operation. */
|
|
37
41
|
id: string;
|
|
@@ -72,6 +76,26 @@ export type DurableOperationResult<Result> = {
|
|
|
72
76
|
/** The handler's persisted return value. */
|
|
73
77
|
result: Result;
|
|
74
78
|
};
|
|
79
|
+
type OperationEvent = Extract<DurabilityLifecycleEvent, {
|
|
80
|
+
entityKind: 'operation';
|
|
81
|
+
}>;
|
|
82
|
+
type TypedOperationEvent<Operation extends string, Result> = OperationEvent extends infer Event ? Event extends {
|
|
83
|
+
outcome: 'completed';
|
|
84
|
+
} ? Omit<Event, 'operation' | 'result'> & {
|
|
85
|
+
operation: Operation;
|
|
86
|
+
result: Result;
|
|
87
|
+
} : Event extends object ? Omit<Event, 'operation'> & {
|
|
88
|
+
operation: Operation;
|
|
89
|
+
} : never : never;
|
|
90
|
+
/**
|
|
91
|
+
* A lifecycle event for one of this instance's operations. Completed events
|
|
92
|
+
* carry the handler's typed result.
|
|
93
|
+
*/
|
|
94
|
+
export type DurabilityOperationEvent<Handlers extends HandlerMap> = {
|
|
95
|
+
[Operation in Extract<keyof Handlers, string>]: TypedOperationEvent<Operation, HandlerResult<Handlers[Operation]>>;
|
|
96
|
+
}[Extract<keyof Handlers, string>] | Extract<DurabilityLifecycleEvent, {
|
|
97
|
+
type: 'purged';
|
|
98
|
+
}>;
|
|
75
99
|
/** Registers calls for one handler and reads their persisted results. */
|
|
76
100
|
export type DurableOperation<Handler> = ((input: DurableOperationInput<Handler>) => Promise<void>) & {
|
|
77
101
|
/** Reads the persisted state for an idempotency key. */
|
|
@@ -113,6 +137,11 @@ declare class DurabilityCore<Handlers extends HandlerMap> {
|
|
|
113
137
|
static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
|
|
114
138
|
/** Processes due operations and re-arms the physical alarm. */
|
|
115
139
|
alarm(info?: AlarmInvocationInfo): Promise<void>;
|
|
140
|
+
/**
|
|
141
|
+
* Attaches a best-effort lifecycle hook alongside `onLifecycleEvent` and
|
|
142
|
+
* returns a function that detaches it.
|
|
143
|
+
*/
|
|
144
|
+
lifecycle(hook: (event: DurabilityOperationEvent<Handlers>) => void | Promise<void>): () => void;
|
|
116
145
|
/**
|
|
117
146
|
* Destructively removes operation records created strictly before the
|
|
118
147
|
* timestamp, regardless of status, and returns how many were removed.
|
|
@@ -150,6 +179,8 @@ type OperationMethods<Handlers extends HandlerMap> = {
|
|
|
150
179
|
* ```
|
|
151
180
|
*/
|
|
152
181
|
export type Durability<Handlers extends HandlerMap> = DurabilityCore<Handlers> & OperationMethods<Handlers>;
|
|
182
|
+
/** Any `Durability` instance, without the index signature of `Durability<HandlerMap>`. */
|
|
183
|
+
export type AnyDurability = DurabilityCore<HandlerMap>;
|
|
153
184
|
export interface DurabilityConstructor {
|
|
154
185
|
new <Handlers extends HandlerMap>(config: DurabilityConfig<Handlers>): Durability<Handlers>;
|
|
155
186
|
migrate: typeof DurabilityCore.migrate;
|
package/dist/durability.js
CHANGED
|
@@ -9,17 +9,70 @@ 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_emit, _DurabilityCore_active, _DurabilityCore_executionStarts, _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_active, _DurabilityCore_executionStarts, _DurabilityCore_trackedSource, _DurabilityCore_runDue, _DurabilityCore_getResult, _DurabilityCore_run, _DurabilityCore_execute, _DurabilityCore_start;
|
|
13
|
+
import { z } from 'zod';
|
|
13
14
|
import { DuplicateDurableCallError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, isErrorInstance, NonRetryableError, reportFailure, } from './errors.js';
|
|
15
|
+
import { createLifecycleHooks, } from './lifecycle.js';
|
|
14
16
|
import { durabilityOperationMigrations, migrate, } from './migrations.js';
|
|
15
17
|
import { createPolicyResolver, methodOptionsSchema, } from './policy.js';
|
|
16
18
|
import { engineFor, } from './scheduler.js';
|
|
17
19
|
import { deserialize, serialize } from './serialization.js';
|
|
20
|
+
import { listCreated, updateAttempt } from './storage.js';
|
|
21
|
+
import { registerTrackedSource, } from './tracked-source.js';
|
|
22
|
+
const callRowSchema = z.object({
|
|
23
|
+
id: z.string(),
|
|
24
|
+
operation: z.string(),
|
|
25
|
+
payload: z.string(),
|
|
26
|
+
status: z.enum(['pending', 'completed', 'failed']),
|
|
27
|
+
result: z.string().nullable(),
|
|
28
|
+
attempt: z.number().int().nonnegative(),
|
|
29
|
+
next_attempt_at: z.number().int().nonnegative(),
|
|
30
|
+
last_error: z.string().nullable(),
|
|
31
|
+
last_error_name: z.string().nullable(),
|
|
32
|
+
completed_at: z.number().int().nonnegative().nullable(),
|
|
33
|
+
created_at: z.number().int().nonnegative(),
|
|
34
|
+
generation_id: z.string(),
|
|
35
|
+
});
|
|
36
|
+
const callsTable = { name: 'durability_calls', key: 'id' };
|
|
37
|
+
const readCall = (sql, id) => callRowSchema
|
|
38
|
+
.optional()
|
|
39
|
+
.parse(sql.exec('SELECT * FROM durability_calls WHERE id = ?', id).toArray()[0]);
|
|
18
40
|
const assertOperation = (id, existingOperation, requestedOperation) => {
|
|
19
41
|
if (existingOperation !== requestedOperation) {
|
|
20
42
|
throw new DuplicateDurableCallError(id, existingOperation, requestedOperation);
|
|
21
43
|
}
|
|
22
44
|
};
|
|
45
|
+
const callState = (call) => {
|
|
46
|
+
if (call.status === 'pending') {
|
|
47
|
+
return {
|
|
48
|
+
status: 'pending',
|
|
49
|
+
attempt: call.attempt,
|
|
50
|
+
nextAttemptAt: call.next_attempt_at,
|
|
51
|
+
lastError: call.last_error,
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
if (call.status === 'failed') {
|
|
55
|
+
return {
|
|
56
|
+
status: 'failed',
|
|
57
|
+
attempt: call.attempt,
|
|
58
|
+
error: {
|
|
59
|
+
name: call.last_error_name ?? 'Error',
|
|
60
|
+
message: call.last_error ?? 'Durable operation failed',
|
|
61
|
+
},
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
if (call.result === null) {
|
|
65
|
+
throw new Error(`Completed durable call "${call.id}" has no result`);
|
|
66
|
+
}
|
|
67
|
+
return { status: 'completed', result: deserialize(call.result) };
|
|
68
|
+
};
|
|
69
|
+
const callRecord = (call) => ({
|
|
70
|
+
id: call.id,
|
|
71
|
+
name: call.operation,
|
|
72
|
+
generation: call.generation_id,
|
|
73
|
+
createdAt: call.created_at,
|
|
74
|
+
state: callState(call),
|
|
75
|
+
});
|
|
23
76
|
const operationEntity = (call) => ({
|
|
24
77
|
entityKind: 'operation',
|
|
25
78
|
operation: call.operation,
|
|
@@ -32,6 +85,7 @@ class DurabilityCore {
|
|
|
32
85
|
_DurabilityCore_engine.set(this, void 0);
|
|
33
86
|
_DurabilityCore_handlers.set(this, void 0);
|
|
34
87
|
_DurabilityCore_policy.set(this, void 0);
|
|
88
|
+
_DurabilityCore_lifecycle.set(this, void 0);
|
|
35
89
|
_DurabilityCore_emit.set(this, void 0);
|
|
36
90
|
_DurabilityCore_active.set(this, new Map());
|
|
37
91
|
_DurabilityCore_executionStarts.set(this, new Map());
|
|
@@ -39,7 +93,8 @@ class DurabilityCore {
|
|
|
39
93
|
__classPrivateFieldSet(this, _DurabilityCore_engine, engineFor(config), "f");
|
|
40
94
|
__classPrivateFieldSet(this, _DurabilityCore_handlers, handlers, "f");
|
|
41
95
|
__classPrivateFieldSet(this, _DurabilityCore_policy, createPolicyResolver(config, config.methods ?? {}, methodOptionsSchema), "f");
|
|
42
|
-
__classPrivateFieldSet(this,
|
|
96
|
+
__classPrivateFieldSet(this, _DurabilityCore_lifecycle, createLifecycleHooks((hook) => __classPrivateFieldGet(this, _DurabilityCore_engine, "f").emitter(hook), config.onLifecycleEvent), "f");
|
|
97
|
+
__classPrivateFieldSet(this, _DurabilityCore_emit, __classPrivateFieldGet(this, _DurabilityCore_lifecycle, "f").emit, "f");
|
|
43
98
|
const reserved = new Set(Object.getOwnPropertyNames(DurabilityCore.prototype));
|
|
44
99
|
for (const operation of Object.keys(handlers)) {
|
|
45
100
|
if (reserved.has(operation)) {
|
|
@@ -54,9 +109,10 @@ class DurabilityCore {
|
|
|
54
109
|
}
|
|
55
110
|
__classPrivateFieldGet(this, _DurabilityCore_engine, "f").migrateSchema('operations', durabilityOperationMigrations);
|
|
56
111
|
__classPrivateFieldGet(this, _DurabilityCore_engine, "f").register({
|
|
57
|
-
|
|
112
|
+
table: callsTable,
|
|
58
113
|
runDue: (now) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_runDue).call(this, now),
|
|
59
114
|
});
|
|
115
|
+
registerTrackedSource(this, __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_trackedSource).call(this));
|
|
60
116
|
}
|
|
61
117
|
/** Applies or reverts the `durability_calls` schema; see {@link migrate}. */
|
|
62
118
|
static migrate(context, target) {
|
|
@@ -66,12 +122,19 @@ class DurabilityCore {
|
|
|
66
122
|
alarm(info) {
|
|
67
123
|
return __classPrivateFieldGet(this, _DurabilityCore_engine, "f").alarm(info);
|
|
68
124
|
}
|
|
125
|
+
/**
|
|
126
|
+
* Attaches a best-effort lifecycle hook alongside `onLifecycleEvent` and
|
|
127
|
+
* returns a function that detaches it.
|
|
128
|
+
*/
|
|
129
|
+
lifecycle(hook) {
|
|
130
|
+
return __classPrivateFieldGet(this, _DurabilityCore_lifecycle, "f").add(hook);
|
|
131
|
+
}
|
|
69
132
|
/**
|
|
70
133
|
* Destructively removes operation records created strictly before the
|
|
71
134
|
* timestamp, regardless of status, and returns how many were removed.
|
|
72
135
|
*/
|
|
73
136
|
async purgeBefore(before) {
|
|
74
|
-
const count = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").purge(
|
|
137
|
+
const count = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").purge(callsTable, before, __classPrivateFieldGet(this, _DurabilityCore_active, "f"), 'Durable operation was purged');
|
|
75
138
|
__classPrivateFieldGet(this, _DurabilityCore_emit, "f").call(this, {
|
|
76
139
|
type: 'purged',
|
|
77
140
|
entityKind: 'operation',
|
|
@@ -82,8 +145,37 @@ class DurabilityCore {
|
|
|
82
145
|
return count;
|
|
83
146
|
}
|
|
84
147
|
}
|
|
85
|
-
_DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap(), _DurabilityCore_policy = new WeakMap(), _DurabilityCore_emit = new WeakMap(), _DurabilityCore_active = new WeakMap(), _DurabilityCore_executionStarts = new WeakMap(), _DurabilityCore_instances = new WeakSet(),
|
|
86
|
-
const
|
|
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() {
|
|
149
|
+
const sql = __classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql;
|
|
150
|
+
return {
|
|
151
|
+
get: async (id) => {
|
|
152
|
+
const call = readCall(sql, id);
|
|
153
|
+
return call && callRecord(call);
|
|
154
|
+
},
|
|
155
|
+
list: async ({ limit, cursor, status, name }) => {
|
|
156
|
+
const page = listCreated(sql, callsTable, 'operation', {
|
|
157
|
+
limit,
|
|
158
|
+
after: cursor,
|
|
159
|
+
status,
|
|
160
|
+
name,
|
|
161
|
+
});
|
|
162
|
+
const records = callRowSchema.array().parse(page.rows).map(callRecord);
|
|
163
|
+
return page.next === undefined
|
|
164
|
+
? { records }
|
|
165
|
+
: { records, cursor: page.next };
|
|
166
|
+
},
|
|
167
|
+
watch: (id, listener) => __classPrivateFieldGet(this, _DurabilityCore_engine, "f").watch(callsTable, id, () => listener()),
|
|
168
|
+
};
|
|
169
|
+
}, _DurabilityCore_runDue = async function _DurabilityCore_runDue(now) {
|
|
170
|
+
const due = z
|
|
171
|
+
.object({ id: z.string() })
|
|
172
|
+
.array()
|
|
173
|
+
.parse(__classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql
|
|
174
|
+
.exec(`SELECT id FROM durability_calls
|
|
175
|
+
WHERE status = 'pending' AND next_attempt_at <= ?
|
|
176
|
+
ORDER BY next_attempt_at ASC
|
|
177
|
+
LIMIT 100`, now)
|
|
178
|
+
.toArray());
|
|
87
179
|
await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").runConcurrent(due, async ({ id }) => {
|
|
88
180
|
try {
|
|
89
181
|
await __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_execute).call(this, id);
|
|
@@ -93,62 +185,33 @@ _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap()
|
|
|
93
185
|
}
|
|
94
186
|
});
|
|
95
187
|
}, _DurabilityCore_getResult = async function _DurabilityCore_getResult(operation, idempotencyKey) {
|
|
96
|
-
const call =
|
|
188
|
+
const call = readCall(__classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql, idempotencyKey);
|
|
97
189
|
if (!call) {
|
|
98
190
|
return { status: 'not_found' };
|
|
99
191
|
}
|
|
100
192
|
assertOperation(idempotencyKey, call.operation, operation);
|
|
101
|
-
|
|
102
|
-
return {
|
|
103
|
-
status: 'pending',
|
|
104
|
-
attempt: call.attempt,
|
|
105
|
-
nextAttemptAt: call.next_attempt_at,
|
|
106
|
-
lastError: call.last_error,
|
|
107
|
-
};
|
|
108
|
-
}
|
|
109
|
-
if (call.status === 'failed') {
|
|
110
|
-
return {
|
|
111
|
-
status: 'failed',
|
|
112
|
-
attempt: call.attempt,
|
|
113
|
-
error: {
|
|
114
|
-
name: call.last_error_name ?? 'Error',
|
|
115
|
-
message: call.last_error ?? 'Durable operation failed',
|
|
116
|
-
},
|
|
117
|
-
};
|
|
118
|
-
}
|
|
119
|
-
if (call.result === null) {
|
|
120
|
-
throw new Error(`Completed durable call "${idempotencyKey}" has no result`);
|
|
121
|
-
}
|
|
122
|
-
return { status: 'completed', result: deserialize(call.result) };
|
|
193
|
+
return callState(call);
|
|
123
194
|
}, _DurabilityCore_run = async function _DurabilityCore_run(input) {
|
|
124
195
|
const payload = serialize(input.payload);
|
|
125
196
|
const now = Date.now();
|
|
126
197
|
const generation = crypto.randomUUID();
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
last_error: null,
|
|
139
|
-
last_error_name: null,
|
|
140
|
-
completed_at: null,
|
|
141
|
-
created_at: now,
|
|
142
|
-
generation_id: generation,
|
|
143
|
-
});
|
|
144
|
-
winner = await transaction.calls.get(input.id);
|
|
145
|
-
if (!winner) {
|
|
198
|
+
const { inserted, winner } = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").transaction((sql) => {
|
|
199
|
+
const created = sql
|
|
200
|
+
.exec(`INSERT INTO durability_calls
|
|
201
|
+
(id, operation, payload, status, attempt, next_attempt_at,
|
|
202
|
+
created_at, generation_id)
|
|
203
|
+
VALUES (?, ?, ?, 'pending', 0, ?, ?, ?)
|
|
204
|
+
ON CONFLICT(id) DO NOTHING
|
|
205
|
+
RETURNING id`, input.id, input.operation, payload, now, now, generation)
|
|
206
|
+
.toArray().length > 0;
|
|
207
|
+
const current = readCall(sql, input.id);
|
|
208
|
+
if (!current) {
|
|
146
209
|
throw new Error(`Durable call "${input.id}" was not persisted`);
|
|
147
210
|
}
|
|
148
|
-
assertOperation(input.id,
|
|
149
|
-
|
|
211
|
+
assertOperation(input.id, current.operation, input.operation);
|
|
212
|
+
return { inserted: created, winner: current };
|
|
150
213
|
});
|
|
151
|
-
if (!inserted
|
|
214
|
+
if (!inserted) {
|
|
152
215
|
return;
|
|
153
216
|
}
|
|
154
217
|
__classPrivateFieldGet(this, _DurabilityCore_emit, "f").call(this, {
|
|
@@ -183,7 +246,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
|
|
|
183
246
|
let permitTransferred = false;
|
|
184
247
|
try {
|
|
185
248
|
await previousStart;
|
|
186
|
-
const call =
|
|
249
|
+
const call = readCall(__classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql, id);
|
|
187
250
|
if (!call || call.status !== 'pending') {
|
|
188
251
|
return;
|
|
189
252
|
}
|
|
@@ -211,7 +274,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
|
|
|
211
274
|
const policy = __classPrivateFieldGet(this, _DurabilityCore_policy, "f").call(this, call.operation);
|
|
212
275
|
const handler = __classPrivateFieldGet(this, _DurabilityCore_handlers, "f")[call.operation];
|
|
213
276
|
return __classPrivateFieldGet(this, _DurabilityCore_engine, "f").startExecution({
|
|
214
|
-
|
|
277
|
+
table: callsTable,
|
|
215
278
|
key: call.id,
|
|
216
279
|
row: call,
|
|
217
280
|
label: `operation "${call.operation}"`,
|
|
@@ -233,7 +296,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
|
|
|
233
296
|
signal,
|
|
234
297
|
});
|
|
235
298
|
},
|
|
236
|
-
complete:
|
|
299
|
+
complete: (result, attempt) => {
|
|
237
300
|
let serialized;
|
|
238
301
|
try {
|
|
239
302
|
serialized = serialize(result);
|
|
@@ -242,13 +305,8 @@ async function _DurabilityCore_execute(id, eagerPermit) {
|
|
|
242
305
|
throw new DurableResultSerializationError(call.operation, error);
|
|
243
306
|
}
|
|
244
307
|
const timestamp = Date.now();
|
|
245
|
-
const updated =
|
|
246
|
-
|
|
247
|
-
result: serialized,
|
|
248
|
-
last_error: null,
|
|
249
|
-
last_error_name: null,
|
|
250
|
-
completed_at: timestamp,
|
|
251
|
-
});
|
|
308
|
+
const updated = updateAttempt(__classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql, callsTable, { key: call.id, generation: call.generation_id, attempt }, `status = 'completed', result = ?, last_error = NULL,
|
|
309
|
+
last_error_name = NULL, completed_at = ?`, serialized, timestamp);
|
|
252
310
|
return updated ? timestamp : undefined;
|
|
253
311
|
},
|
|
254
312
|
isTerminal: (error) => isErrorInstance(error, DurableResultSerializationError),
|
package/dist/errors.d.ts
CHANGED
|
@@ -67,6 +67,28 @@ export declare class FanoutTimeoutError extends Error {
|
|
|
67
67
|
export declare class FanoutEnqueueError extends Error {
|
|
68
68
|
constructor(message: string);
|
|
69
69
|
}
|
|
70
|
+
/** A definite rejection before records were durably appended. */
|
|
71
|
+
export declare class LogAppendError extends Error {
|
|
72
|
+
constructor(message: string);
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Thrown when a read starts below the retained window, so a consumer that
|
|
76
|
+
* falls further behind than retention learns it lost records instead of
|
|
77
|
+
* silently skipping them.
|
|
78
|
+
*/
|
|
79
|
+
export declare class LogTruncatedError extends Error {
|
|
80
|
+
readonly requestedOffset: number;
|
|
81
|
+
readonly oldestOffset: number;
|
|
82
|
+
constructor(requestedOffset: number, oldestOffset: number);
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Thrown when settling a lease that no longer exists, was already settled, or
|
|
86
|
+
* was reclaimed by another worker. A stale ack must fail loudly rather than
|
|
87
|
+
* advance a range someone else now owns.
|
|
88
|
+
*/
|
|
89
|
+
export declare class LogLeaseError extends Error {
|
|
90
|
+
constructor(batchId: string);
|
|
91
|
+
}
|
|
70
92
|
/** Error thrown when a sharding function returns an invalid shard key. */
|
|
71
93
|
export declare class RoutingError extends Error {
|
|
72
94
|
constructor(message: string);
|
package/dist/errors.js
CHANGED
|
@@ -105,6 +105,37 @@ export class FanoutEnqueueError extends Error {
|
|
|
105
105
|
this.name = 'FanoutEnqueueError';
|
|
106
106
|
}
|
|
107
107
|
}
|
|
108
|
+
/** A definite rejection before records were durably appended. */
|
|
109
|
+
export class LogAppendError extends Error {
|
|
110
|
+
constructor(message) {
|
|
111
|
+
super(message);
|
|
112
|
+
this.name = 'LogAppendError';
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Thrown when a read starts below the retained window, so a consumer that
|
|
117
|
+
* falls further behind than retention learns it lost records instead of
|
|
118
|
+
* silently skipping them.
|
|
119
|
+
*/
|
|
120
|
+
export class LogTruncatedError extends Error {
|
|
121
|
+
constructor(requestedOffset, oldestOffset) {
|
|
122
|
+
super(`Log offset ${requestedOffset} was trimmed; the oldest retained offset is ${oldestOffset}`);
|
|
123
|
+
this.requestedOffset = requestedOffset;
|
|
124
|
+
this.oldestOffset = oldestOffset;
|
|
125
|
+
this.name = 'LogTruncatedError';
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Thrown when settling a lease that no longer exists, was already settled, or
|
|
130
|
+
* was reclaimed by another worker. A stale ack must fail loudly rather than
|
|
131
|
+
* advance a range someone else now owns.
|
|
132
|
+
*/
|
|
133
|
+
export class LogLeaseError extends Error {
|
|
134
|
+
constructor(batchId) {
|
|
135
|
+
super(`Log lease "${batchId}" is not held`);
|
|
136
|
+
this.name = 'LogLeaseError';
|
|
137
|
+
}
|
|
138
|
+
}
|
|
108
139
|
/** Error thrown when a sharding function returns an invalid shard key. */
|
|
109
140
|
export class RoutingError extends Error {
|
|
110
141
|
constructor(message) {
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* APIs that may change or be removed in a minor release. Pin an exact
|
|
3
|
+
* version of `durability` when depending on them.
|
|
4
|
+
*
|
|
5
|
+
* @packageDocumentation
|
|
6
|
+
*/
|
|
7
|
+
export { DurabilityTracker, type DurabilityTrackerConfig, type TrackedHandle, type TrackedItem, type TrackedResult, type TrackedWaitOptions, type TrackerHandle, type TrackerPage, type TrackerQuery, type TrackerRecord, type TrackerRecordPage, } from './tracker.js';
|
|
8
|
+
export type { TrackedEntry, TrackedPage, TrackedQuery, TrackedRecord, TrackedResults, TrackedSource, TrackedState, TrackedStatus, } from './tracked-source.js';
|