durability 2.1.0 → 3.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 +300 -116
- package/dist/durability-alarms.d.ts +90 -0
- package/dist/durability-alarms.js +165 -0
- package/dist/durability.d.ts +158 -0
- package/dist/durability.js +260 -0
- package/dist/errors.d.ts +83 -0
- package/dist/errors.js +184 -0
- package/dist/fanout.d.ts +61 -0
- package/dist/fanout.js +528 -0
- package/dist/index.d.ts +10 -435
- package/dist/index.js +7 -1420
- package/dist/kv-storage.d.ts +2 -0
- package/dist/kv-storage.js +421 -0
- package/dist/lifecycle.d.ts +70 -0
- package/dist/lifecycle.js +36 -0
- package/dist/load.d.ts +40 -0
- package/dist/load.js +68 -0
- package/dist/migrations.d.ts +50 -0
- package/dist/migrations.js +379 -0
- package/dist/policy.d.ts +74 -0
- package/dist/policy.js +49 -0
- package/dist/routing-client.d.ts +28 -0
- package/dist/routing-client.js +109 -0
- package/dist/routing.d.ts +33 -0
- package/dist/routing.js +58 -0
- package/dist/scheduler.d.ts +149 -0
- package/dist/scheduler.js +424 -0
- package/dist/serialization.d.ts +2 -0
- package/dist/serialization.js +13 -0
- package/dist/sqlite-storage.d.ts +2 -0
- package/dist/sqlite-storage.js +251 -0
- package/dist/storage.d.ts +134 -0
- package/dist/storage.js +69 -0
- package/dist/stored-message.d.ts +29 -0
- package/dist/stored-message.js +1 -0
- package/package.json +7 -3
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
|
|
2
|
+
if (kind === "m") throw new TypeError("Private method is not writable");
|
|
3
|
+
if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
|
|
4
|
+
if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
|
|
5
|
+
return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
|
|
6
|
+
};
|
|
7
|
+
var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
|
|
8
|
+
if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
|
|
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
|
+
return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
|
|
11
|
+
};
|
|
12
|
+
var _DurabilityAlarmsCore_instances, _DurabilityAlarmsCore_engine, _DurabilityAlarmsCore_handlers, _DurabilityAlarmsCore_policy, _DurabilityAlarmsCore_emit, _DurabilityAlarmsCore_active, _DurabilityAlarmsCore_runDue, _DurabilityAlarmsCore_schedule, _DurabilityAlarmsCore_execute;
|
|
13
|
+
import { z } from 'zod';
|
|
14
|
+
import { DurableAlarmTimeoutError, DurableAttemptsExhaustedError, isErrorInstance, NonRetryableError, } from './errors.js';
|
|
15
|
+
import { durabilityNamedAlarmMigrations, migrate, } from './migrations.js';
|
|
16
|
+
import { alarmMethodOptionsSchema, createPolicyResolver, } from './policy.js';
|
|
17
|
+
import { engineFor, } from './scheduler.js';
|
|
18
|
+
const alarmHandlerSchema = z.custom((value) => typeof value === 'function');
|
|
19
|
+
const alarmEntity = (row) => ({
|
|
20
|
+
entityKind: 'named_alarm',
|
|
21
|
+
alarm: row.name,
|
|
22
|
+
id: row.name,
|
|
23
|
+
generation: row.generation_id,
|
|
24
|
+
});
|
|
25
|
+
class DurabilityAlarmsCore {
|
|
26
|
+
constructor(config) {
|
|
27
|
+
_DurabilityAlarmsCore_instances.add(this);
|
|
28
|
+
_DurabilityAlarmsCore_engine.set(this, void 0);
|
|
29
|
+
_DurabilityAlarmsCore_handlers.set(this, void 0);
|
|
30
|
+
_DurabilityAlarmsCore_policy.set(this, void 0);
|
|
31
|
+
_DurabilityAlarmsCore_emit.set(this, void 0);
|
|
32
|
+
_DurabilityAlarmsCore_active.set(this, new Map());
|
|
33
|
+
__classPrivateFieldSet(this, _DurabilityAlarmsCore_engine, engineFor(config), "f");
|
|
34
|
+
__classPrivateFieldSet(this, _DurabilityAlarmsCore_handlers, new Map(Object.entries(config.handlers).map(([name, handler]) => [name, alarmHandlerSchema.parse(handler)])), "f");
|
|
35
|
+
__classPrivateFieldSet(this, _DurabilityAlarmsCore_policy, createPolicyResolver(config, config.methods ?? {}, alarmMethodOptionsSchema), "f");
|
|
36
|
+
__classPrivateFieldSet(this, _DurabilityAlarmsCore_emit, __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").emitter(config.onLifecycleEvent), "f");
|
|
37
|
+
const reserved = new Set(Object.getOwnPropertyNames(DurabilityAlarmsCore.prototype));
|
|
38
|
+
for (const name of __classPrivateFieldGet(this, _DurabilityAlarmsCore_handlers, "f").keys()) {
|
|
39
|
+
if (reserved.has(name)) {
|
|
40
|
+
throw new Error(`"${name}" is reserved by DurabilityAlarms`);
|
|
41
|
+
}
|
|
42
|
+
Object.defineProperty(this, name, {
|
|
43
|
+
value: (scheduledTime) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_schedule).call(this, name, scheduledTime),
|
|
44
|
+
enumerable: true,
|
|
45
|
+
});
|
|
46
|
+
}
|
|
47
|
+
__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").migrateSchema('namedAlarms', durabilityNamedAlarmMigrations);
|
|
48
|
+
__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").register({
|
|
49
|
+
kind: 'alarms',
|
|
50
|
+
runDue: (now, info) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_runDue).call(this, now, info),
|
|
51
|
+
});
|
|
52
|
+
}
|
|
53
|
+
/** Applies or reverts the `durability_alarms` schema; see {@link migrate}. */
|
|
54
|
+
static migrate(context, target) {
|
|
55
|
+
return migrate(context.storage, 'namedAlarms', durabilityNamedAlarmMigrations, target);
|
|
56
|
+
}
|
|
57
|
+
/** Runs due named alarms and re-arms the physical alarm. */
|
|
58
|
+
alarm(info) {
|
|
59
|
+
return __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").alarm(info);
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Destructively removes named alarm records created strictly before the
|
|
63
|
+
* timestamp, regardless of status, and returns how many were removed.
|
|
64
|
+
*/
|
|
65
|
+
async purgeBefore(before) {
|
|
66
|
+
const count = await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").purge('alarms', before, __classPrivateFieldGet(this, _DurabilityAlarmsCore_active, "f"), 'Durable alarm was purged');
|
|
67
|
+
__classPrivateFieldGet(this, _DurabilityAlarmsCore_emit, "f").call(this, {
|
|
68
|
+
type: 'purged',
|
|
69
|
+
entityKind: 'named_alarm',
|
|
70
|
+
timestamp: Date.now(),
|
|
71
|
+
before,
|
|
72
|
+
count,
|
|
73
|
+
});
|
|
74
|
+
return count;
|
|
75
|
+
}
|
|
76
|
+
}
|
|
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(), _DurabilityAlarmsCore_runDue = async function _DurabilityAlarmsCore_runDue(now, info) {
|
|
78
|
+
const due = await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").storage.alarms.listDue(now, 100);
|
|
79
|
+
const failures = [];
|
|
80
|
+
await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").runConcurrent(due, async (row) => {
|
|
81
|
+
try {
|
|
82
|
+
await __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_execute).call(this, row, info);
|
|
83
|
+
}
|
|
84
|
+
catch (error) {
|
|
85
|
+
failures.push(error);
|
|
86
|
+
}
|
|
87
|
+
});
|
|
88
|
+
if (failures.length > 0) {
|
|
89
|
+
throw failures[0];
|
|
90
|
+
}
|
|
91
|
+
}, _DurabilityAlarmsCore_schedule = async function _DurabilityAlarmsCore_schedule(name, scheduledTime) {
|
|
92
|
+
if (!Number.isSafeInteger(scheduledTime) || scheduledTime < 0) {
|
|
93
|
+
throw new RangeError('scheduledTime must be a non-negative safe integer');
|
|
94
|
+
}
|
|
95
|
+
const generation = crypto.randomUUID();
|
|
96
|
+
const createdAt = Date.now();
|
|
97
|
+
await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").storage.transaction(async (transaction) => {
|
|
98
|
+
await transaction.alarms.upsert({
|
|
99
|
+
name,
|
|
100
|
+
generation_id: generation,
|
|
101
|
+
status: 'pending',
|
|
102
|
+
scheduled_at: scheduledTime,
|
|
103
|
+
next_attempt_at: scheduledTime,
|
|
104
|
+
attempt: 0,
|
|
105
|
+
last_error: null,
|
|
106
|
+
last_error_name: null,
|
|
107
|
+
created_at: createdAt,
|
|
108
|
+
});
|
|
109
|
+
await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").reconcile(transaction);
|
|
110
|
+
});
|
|
111
|
+
__classPrivateFieldGet(this, _DurabilityAlarmsCore_emit, "f").call(this, {
|
|
112
|
+
type: 'scheduled',
|
|
113
|
+
entityKind: 'named_alarm',
|
|
114
|
+
alarm: name,
|
|
115
|
+
id: name,
|
|
116
|
+
generation,
|
|
117
|
+
timestamp: createdAt,
|
|
118
|
+
attempt: 0,
|
|
119
|
+
scheduledTime,
|
|
120
|
+
});
|
|
121
|
+
}, _DurabilityAlarmsCore_execute = function _DurabilityAlarmsCore_execute(row, platform) {
|
|
122
|
+
const running = __classPrivateFieldGet(this, _DurabilityAlarmsCore_active, "f").get(row.name);
|
|
123
|
+
if (running) {
|
|
124
|
+
return running.settled;
|
|
125
|
+
}
|
|
126
|
+
const policy = __classPrivateFieldGet(this, _DurabilityAlarmsCore_policy, "f").call(this, row.name);
|
|
127
|
+
const retryTimeouts = policy.method?.retryTimeouts ?? false;
|
|
128
|
+
return __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").startExecution({
|
|
129
|
+
kind: 'alarms',
|
|
130
|
+
key: row.name,
|
|
131
|
+
row,
|
|
132
|
+
label: `named alarm "${row.name}"`,
|
|
133
|
+
entity: alarmEntity(row),
|
|
134
|
+
active: __classPrivateFieldGet(this, _DurabilityAlarmsCore_active, "f"),
|
|
135
|
+
policy,
|
|
136
|
+
emit: __classPrivateFieldGet(this, _DurabilityAlarmsCore_emit, "f"),
|
|
137
|
+
exhaustedError: () => new DurableAttemptsExhaustedError('named alarm', row.name, policy.maxAttempts),
|
|
138
|
+
timeoutError: () => new DurableAlarmTimeoutError(row.name, policy.attemptTimeoutMs),
|
|
139
|
+
invoke: (attempt, signal) => {
|
|
140
|
+
const handler = __classPrivateFieldGet(this, _DurabilityAlarmsCore_handlers, "f").get(row.name);
|
|
141
|
+
if (!handler) {
|
|
142
|
+
throw new NonRetryableError(`No named alarm handler registered for "${row.name}"`);
|
|
143
|
+
}
|
|
144
|
+
return handler({
|
|
145
|
+
name: row.name,
|
|
146
|
+
scheduledTime: row.scheduled_at,
|
|
147
|
+
attempt,
|
|
148
|
+
isRetry: attempt > 1,
|
|
149
|
+
retryCount: attempt - 1,
|
|
150
|
+
idempotencyKey: `durability-alarm:v1:${row.generation_id}`,
|
|
151
|
+
signal,
|
|
152
|
+
platform,
|
|
153
|
+
});
|
|
154
|
+
},
|
|
155
|
+
complete: async (_result, attempt) => {
|
|
156
|
+
const timestamp = Date.now();
|
|
157
|
+
const removed = await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").storage.alarms.remove(row.name, row.generation_id, attempt);
|
|
158
|
+
return removed ? timestamp : undefined;
|
|
159
|
+
},
|
|
160
|
+
isTerminal: (error) => isErrorInstance(error, DurableAlarmTimeoutError) && !retryTimeouts,
|
|
161
|
+
});
|
|
162
|
+
};
|
|
163
|
+
// See Durability: members derived from the handler names cannot be declared on
|
|
164
|
+
// the class, so the constructor is typed separately.
|
|
165
|
+
export const DurabilityAlarms = DurabilityAlarmsCore;
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
import { type LifecycleHook } from './lifecycle.js';
|
|
2
|
+
import { type DurabilityMigrationResult } from './migrations.js';
|
|
3
|
+
import { type DurabilityMethodOptions, type ExecutionPolicyOptions } from './policy.js';
|
|
4
|
+
import { type SchedulerAttachment } from './scheduler.js';
|
|
5
|
+
/**
|
|
6
|
+
* The context passed to a durable operation handler for each attempt.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* ```ts
|
|
10
|
+
* const sendEmail = async ({ id, payload, signal }: DurableCall<EmailPayload>) =>
|
|
11
|
+
* fetch(payload.url, {
|
|
12
|
+
* method: 'POST',
|
|
13
|
+
* headers: { 'Idempotency-Key': id },
|
|
14
|
+
* signal,
|
|
15
|
+
* });
|
|
16
|
+
* ```
|
|
17
|
+
*/
|
|
18
|
+
export type DurableCall<Payload> = {
|
|
19
|
+
/** The stable idempotency key supplied when the operation was registered. */
|
|
20
|
+
id: string;
|
|
21
|
+
/** The handler name used to register the operation. */
|
|
22
|
+
operation: string;
|
|
23
|
+
/** The JSON-serializable payload supplied when the operation was registered. */
|
|
24
|
+
payload: Payload;
|
|
25
|
+
/** The one-based attempt number. */
|
|
26
|
+
attempt: number;
|
|
27
|
+
/** Aborts when the attempt exceeds its configured timeout. */
|
|
28
|
+
signal: AbortSignal;
|
|
29
|
+
};
|
|
30
|
+
/** A function that executes one attempt of a durable operation. */
|
|
31
|
+
export type DurableHandler<Payload, Result> = (call: DurableCall<Payload>) => Result | Promise<Result>;
|
|
32
|
+
export type HandlerMap = Record<string, (...args: never[]) => unknown>;
|
|
33
|
+
type HandlerPayload<Handler> = Handler extends (call: DurableCall<infer Payload>) => unknown ? Payload : never;
|
|
34
|
+
type HandlerResult<Handler> = Handler extends (...args: never[]) => infer Result ? Awaited<Result> : never;
|
|
35
|
+
type DurableOperationInput<Handler> = {
|
|
36
|
+
/** Stable idempotency key used to deduplicate the operation. */
|
|
37
|
+
id: string;
|
|
38
|
+
/** JSON-serializable input passed to the operation handler. */
|
|
39
|
+
payload: HandlerPayload<Handler>;
|
|
40
|
+
};
|
|
41
|
+
/**
|
|
42
|
+
* The persisted state and result of a durable operation.
|
|
43
|
+
*
|
|
44
|
+
* Operation methods only wait for durable registration, not handler completion.
|
|
45
|
+
* Call `getResult` later and narrow on `status` before reading a result or error.
|
|
46
|
+
*/
|
|
47
|
+
export type DurableOperationResult<Result> = {
|
|
48
|
+
/** No operation exists for the supplied idempotency key. */
|
|
49
|
+
status: 'not_found';
|
|
50
|
+
} | {
|
|
51
|
+
/** The operation is waiting to run or retry. */
|
|
52
|
+
status: 'pending';
|
|
53
|
+
/** The number of attempts already started. */
|
|
54
|
+
attempt: number;
|
|
55
|
+
/** Unix timestamp in milliseconds when the next attempt becomes eligible. */
|
|
56
|
+
nextAttemptAt: number;
|
|
57
|
+
/** The previous attempt's error message, or null before the first attempt. */
|
|
58
|
+
lastError: string | null;
|
|
59
|
+
} | {
|
|
60
|
+
/** The operation exhausted its attempts or failed with a non-retryable error. */
|
|
61
|
+
status: 'failed';
|
|
62
|
+
/** The number of attempts that were started. */
|
|
63
|
+
attempt: number;
|
|
64
|
+
/** The terminal error's serialized name and message. */
|
|
65
|
+
error: {
|
|
66
|
+
name: string;
|
|
67
|
+
message: string;
|
|
68
|
+
};
|
|
69
|
+
} | {
|
|
70
|
+
/** The operation completed successfully. */
|
|
71
|
+
status: 'completed';
|
|
72
|
+
/** The handler's persisted return value. */
|
|
73
|
+
result: Result;
|
|
74
|
+
};
|
|
75
|
+
/** Registers calls for one handler and reads their persisted results. */
|
|
76
|
+
export type DurableOperation<Handler> = ((input: DurableOperationInput<Handler>) => Promise<void>) & {
|
|
77
|
+
/** Reads the persisted state for an idempotency key. */
|
|
78
|
+
getResult: (idempotencyKey: string) => Promise<DurableOperationResult<HandlerResult<Handler>>>;
|
|
79
|
+
};
|
|
80
|
+
/**
|
|
81
|
+
* Configuration for durable operations.
|
|
82
|
+
*
|
|
83
|
+
* @example
|
|
84
|
+
* ```ts
|
|
85
|
+
* const options: DurabilityOptions<typeof handlers> = {
|
|
86
|
+
* attemptTimeoutMs: 30_000,
|
|
87
|
+
* retries: { maxAttempts: 5 },
|
|
88
|
+
* methods: {
|
|
89
|
+
* resizeImage: { attemptTimeoutMs: 60_000, retries: { maxAttempts: 2 } },
|
|
90
|
+
* },
|
|
91
|
+
* };
|
|
92
|
+
* ```
|
|
93
|
+
*/
|
|
94
|
+
export type DurabilityOptions<Handlers extends HandlerMap = HandlerMap> = ExecutionPolicyOptions & {
|
|
95
|
+
/** Execution policy overrides keyed by handler name. */
|
|
96
|
+
methods?: Partial<Record<Extract<keyof NoInfer<Handlers>, string>, DurabilityMethodOptions>>;
|
|
97
|
+
/** Receives best-effort, non-durable lifecycle metrics events. */
|
|
98
|
+
onLifecycleEvent?: LifecycleHook;
|
|
99
|
+
};
|
|
100
|
+
/**
|
|
101
|
+
* Constructor configuration: the operation handlers, their policies, and
|
|
102
|
+
* either a shared `scheduler` or the Durable Object `context` (plus scheduler
|
|
103
|
+
* options) to create a private one.
|
|
104
|
+
*/
|
|
105
|
+
export type DurabilityConfig<Handlers extends HandlerMap = HandlerMap> = DurabilityOptions<Handlers> & SchedulerAttachment & {
|
|
106
|
+
/** Operation handlers keyed by the method names they become. */
|
|
107
|
+
handlers: Handlers;
|
|
108
|
+
};
|
|
109
|
+
declare class DurabilityCore<Handlers extends HandlerMap> {
|
|
110
|
+
#private;
|
|
111
|
+
constructor(config: DurabilityConfig<Handlers>);
|
|
112
|
+
/** Applies or reverts the `durability_calls` schema; see {@link migrate}. */
|
|
113
|
+
static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
|
|
114
|
+
/** Processes due operations and re-arms the physical alarm. */
|
|
115
|
+
alarm(info?: AlarmInvocationInfo): Promise<void>;
|
|
116
|
+
/**
|
|
117
|
+
* Destructively removes operation records created strictly before the
|
|
118
|
+
* timestamp, regardless of status, and returns how many were removed.
|
|
119
|
+
*/
|
|
120
|
+
purgeBefore(before: number): Promise<number>;
|
|
121
|
+
}
|
|
122
|
+
type OperationMethods<Handlers extends HandlerMap> = {
|
|
123
|
+
[Operation in keyof Handlers]: DurableOperation<Handlers[Operation]>;
|
|
124
|
+
};
|
|
125
|
+
/**
|
|
126
|
+
* Alarm-backed, effectively-once durable operations for one Durable Object.
|
|
127
|
+
*
|
|
128
|
+
* Every handler becomes a typed method on the instance. Methods resolve once
|
|
129
|
+
* the call is durably registered; read outcomes through `getResult`.
|
|
130
|
+
*
|
|
131
|
+
* @example
|
|
132
|
+
* ```ts
|
|
133
|
+
* class ImageJobs extends DurableObject<Env> {
|
|
134
|
+
* private readonly durability = new Durability({
|
|
135
|
+
* context: this.ctx,
|
|
136
|
+
* handlers: {
|
|
137
|
+
* resizeImage: async ({ id, payload }: DurableCall<{ imageId: string }>) =>
|
|
138
|
+
* this.env.IMAGES.resize(payload.imageId, { idempotencyKey: id }),
|
|
139
|
+
* },
|
|
140
|
+
* });
|
|
141
|
+
*
|
|
142
|
+
* resize(imageId: string) {
|
|
143
|
+
* return this.durability.resizeImage({ id: `resize:${imageId}`, payload: { imageId } });
|
|
144
|
+
* }
|
|
145
|
+
*
|
|
146
|
+
* alarm(info?: AlarmInvocationInfo) {
|
|
147
|
+
* return this.durability.alarm(info);
|
|
148
|
+
* }
|
|
149
|
+
* }
|
|
150
|
+
* ```
|
|
151
|
+
*/
|
|
152
|
+
export type Durability<Handlers extends HandlerMap> = DurabilityCore<Handlers> & OperationMethods<Handlers>;
|
|
153
|
+
export interface DurabilityConstructor {
|
|
154
|
+
new <Handlers extends HandlerMap>(config: DurabilityConfig<Handlers>): Durability<Handlers>;
|
|
155
|
+
migrate: typeof DurabilityCore.migrate;
|
|
156
|
+
}
|
|
157
|
+
export declare const Durability: DurabilityConstructor;
|
|
158
|
+
export {};
|
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
|
|
2
|
+
if (kind === "m") throw new TypeError("Private method is not writable");
|
|
3
|
+
if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
|
|
4
|
+
if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
|
|
5
|
+
return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
|
|
6
|
+
};
|
|
7
|
+
var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
|
|
8
|
+
if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
|
|
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
|
+
return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
|
|
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;
|
|
13
|
+
import { DuplicateDurableCallError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, isErrorInstance, NonRetryableError, reportFailure, } from './errors.js';
|
|
14
|
+
import { durabilityOperationMigrations, migrate, } from './migrations.js';
|
|
15
|
+
import { createPolicyResolver, methodOptionsSchema, } from './policy.js';
|
|
16
|
+
import { engineFor, } from './scheduler.js';
|
|
17
|
+
import { deserialize, serialize } from './serialization.js';
|
|
18
|
+
const assertOperation = (id, existingOperation, requestedOperation) => {
|
|
19
|
+
if (existingOperation !== requestedOperation) {
|
|
20
|
+
throw new DuplicateDurableCallError(id, existingOperation, requestedOperation);
|
|
21
|
+
}
|
|
22
|
+
};
|
|
23
|
+
const operationEntity = (call) => ({
|
|
24
|
+
entityKind: 'operation',
|
|
25
|
+
operation: call.operation,
|
|
26
|
+
id: call.id,
|
|
27
|
+
generation: call.generation_id,
|
|
28
|
+
});
|
|
29
|
+
class DurabilityCore {
|
|
30
|
+
constructor(config) {
|
|
31
|
+
_DurabilityCore_instances.add(this);
|
|
32
|
+
_DurabilityCore_engine.set(this, void 0);
|
|
33
|
+
_DurabilityCore_handlers.set(this, void 0);
|
|
34
|
+
_DurabilityCore_policy.set(this, void 0);
|
|
35
|
+
_DurabilityCore_emit.set(this, void 0);
|
|
36
|
+
_DurabilityCore_active.set(this, new Map());
|
|
37
|
+
_DurabilityCore_executionStarts.set(this, new Map());
|
|
38
|
+
const { handlers } = config;
|
|
39
|
+
__classPrivateFieldSet(this, _DurabilityCore_engine, engineFor(config), "f");
|
|
40
|
+
__classPrivateFieldSet(this, _DurabilityCore_handlers, handlers, "f");
|
|
41
|
+
__classPrivateFieldSet(this, _DurabilityCore_policy, createPolicyResolver(config, config.methods ?? {}, methodOptionsSchema), "f");
|
|
42
|
+
__classPrivateFieldSet(this, _DurabilityCore_emit, __classPrivateFieldGet(this, _DurabilityCore_engine, "f").emitter(config.onLifecycleEvent), "f");
|
|
43
|
+
const reserved = new Set(Object.getOwnPropertyNames(DurabilityCore.prototype));
|
|
44
|
+
for (const operation of Object.keys(handlers)) {
|
|
45
|
+
if (reserved.has(operation)) {
|
|
46
|
+
throw new Error(`"${operation}" is reserved by Durability`);
|
|
47
|
+
}
|
|
48
|
+
const method = (input) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_run).call(this, { ...input, operation });
|
|
49
|
+
method.getResult = (idempotencyKey) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_getResult).call(this, operation, idempotencyKey);
|
|
50
|
+
Object.defineProperty(this, operation, {
|
|
51
|
+
value: method,
|
|
52
|
+
enumerable: true,
|
|
53
|
+
});
|
|
54
|
+
}
|
|
55
|
+
__classPrivateFieldGet(this, _DurabilityCore_engine, "f").migrateSchema('operations', durabilityOperationMigrations);
|
|
56
|
+
__classPrivateFieldGet(this, _DurabilityCore_engine, "f").register({
|
|
57
|
+
kind: 'calls',
|
|
58
|
+
runDue: (now) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_runDue).call(this, now),
|
|
59
|
+
});
|
|
60
|
+
}
|
|
61
|
+
/** Applies or reverts the `durability_calls` schema; see {@link migrate}. */
|
|
62
|
+
static migrate(context, target) {
|
|
63
|
+
return migrate(context.storage, 'operations', durabilityOperationMigrations, target);
|
|
64
|
+
}
|
|
65
|
+
/** Processes due operations and re-arms the physical alarm. */
|
|
66
|
+
alarm(info) {
|
|
67
|
+
return __classPrivateFieldGet(this, _DurabilityCore_engine, "f").alarm(info);
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* Destructively removes operation records created strictly before the
|
|
71
|
+
* timestamp, regardless of status, and returns how many were removed.
|
|
72
|
+
*/
|
|
73
|
+
async purgeBefore(before) {
|
|
74
|
+
const count = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").purge('calls', before, __classPrivateFieldGet(this, _DurabilityCore_active, "f"), 'Durable operation was purged');
|
|
75
|
+
__classPrivateFieldGet(this, _DurabilityCore_emit, "f").call(this, {
|
|
76
|
+
type: 'purged',
|
|
77
|
+
entityKind: 'operation',
|
|
78
|
+
timestamp: Date.now(),
|
|
79
|
+
before,
|
|
80
|
+
count,
|
|
81
|
+
});
|
|
82
|
+
return count;
|
|
83
|
+
}
|
|
84
|
+
}
|
|
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(), _DurabilityCore_runDue = async function _DurabilityCore_runDue(now) {
|
|
86
|
+
const due = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").storage.calls.listDue(now, 100);
|
|
87
|
+
await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").runConcurrent(due, async ({ id }) => {
|
|
88
|
+
try {
|
|
89
|
+
await __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_execute).call(this, id);
|
|
90
|
+
}
|
|
91
|
+
catch {
|
|
92
|
+
return;
|
|
93
|
+
}
|
|
94
|
+
});
|
|
95
|
+
}, _DurabilityCore_getResult = async function _DurabilityCore_getResult(operation, idempotencyKey) {
|
|
96
|
+
const call = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").storage.calls.get(idempotencyKey);
|
|
97
|
+
if (!call) {
|
|
98
|
+
return { status: 'not_found' };
|
|
99
|
+
}
|
|
100
|
+
assertOperation(idempotencyKey, call.operation, operation);
|
|
101
|
+
if (call.status === 'pending') {
|
|
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) };
|
|
123
|
+
}, _DurabilityCore_run = async function _DurabilityCore_run(input) {
|
|
124
|
+
const payload = serialize(input.payload);
|
|
125
|
+
const now = Date.now();
|
|
126
|
+
const generation = crypto.randomUUID();
|
|
127
|
+
let inserted = false;
|
|
128
|
+
let winner;
|
|
129
|
+
await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").storage.transaction(async (transaction) => {
|
|
130
|
+
inserted = await transaction.calls.insert({
|
|
131
|
+
id: input.id,
|
|
132
|
+
operation: input.operation,
|
|
133
|
+
payload,
|
|
134
|
+
status: 'pending',
|
|
135
|
+
result: null,
|
|
136
|
+
attempt: 0,
|
|
137
|
+
next_attempt_at: now,
|
|
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) {
|
|
146
|
+
throw new Error(`Durable call "${input.id}" was not persisted`);
|
|
147
|
+
}
|
|
148
|
+
assertOperation(input.id, winner.operation, input.operation);
|
|
149
|
+
await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").reconcile(transaction);
|
|
150
|
+
});
|
|
151
|
+
if (!inserted || !winner) {
|
|
152
|
+
return;
|
|
153
|
+
}
|
|
154
|
+
__classPrivateFieldGet(this, _DurabilityCore_emit, "f").call(this, {
|
|
155
|
+
...operationEntity(winner),
|
|
156
|
+
type: 'registered',
|
|
157
|
+
timestamp: now,
|
|
158
|
+
attempt: 0,
|
|
159
|
+
});
|
|
160
|
+
// Start eagerly only when a permit is free; otherwise the reconciled alarm picks the row up.
|
|
161
|
+
const eagerPermit = __classPrivateFieldGet(this, _DurabilityCore_engine, "f").tryAcquirePermit();
|
|
162
|
+
if (!eagerPermit) {
|
|
163
|
+
return;
|
|
164
|
+
}
|
|
165
|
+
const onError = (error) => reportFailure('durability.background_execution.failed', { operation: input.operation, id: input.id }, error);
|
|
166
|
+
const background = __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_execute).call(this, input.id, eagerPermit)
|
|
167
|
+
.then(() => __classPrivateFieldGet(this, _DurabilityCore_engine, "f").scheduleNextAlarm())
|
|
168
|
+
.catch(onError);
|
|
169
|
+
__classPrivateFieldGet(this, _DurabilityCore_engine, "f").waitUntil(background, onError);
|
|
170
|
+
}, _DurabilityCore_execute =
|
|
171
|
+
/**
|
|
172
|
+
* Looks up a call and starts it unless the same generation is already
|
|
173
|
+
* running. Lookups for one ID are serialized so two concurrent callers
|
|
174
|
+
* cannot both miss the active map while awaiting storage.
|
|
175
|
+
*/
|
|
176
|
+
async function _DurabilityCore_execute(id, eagerPermit) {
|
|
177
|
+
const previousStart = __classPrivateFieldGet(this, _DurabilityCore_executionStarts, "f").get(id) ?? Promise.resolve();
|
|
178
|
+
let releaseStart;
|
|
179
|
+
const currentStart = new Promise((resolve) => {
|
|
180
|
+
releaseStart = resolve;
|
|
181
|
+
});
|
|
182
|
+
__classPrivateFieldGet(this, _DurabilityCore_executionStarts, "f").set(id, currentStart);
|
|
183
|
+
let permitTransferred = false;
|
|
184
|
+
try {
|
|
185
|
+
await previousStart;
|
|
186
|
+
const call = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").storage.calls.get(id);
|
|
187
|
+
if (!call || call.status !== 'pending') {
|
|
188
|
+
return;
|
|
189
|
+
}
|
|
190
|
+
const running = __classPrivateFieldGet(this, _DurabilityCore_active, "f").get(id);
|
|
191
|
+
if (running?.generation === call.generation_id) {
|
|
192
|
+
releaseStart();
|
|
193
|
+
await running.settled;
|
|
194
|
+
return;
|
|
195
|
+
}
|
|
196
|
+
const execution = __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_start).call(this, call, eagerPermit);
|
|
197
|
+
permitTransferred = true;
|
|
198
|
+
releaseStart();
|
|
199
|
+
return execution;
|
|
200
|
+
}
|
|
201
|
+
finally {
|
|
202
|
+
releaseStart();
|
|
203
|
+
if (__classPrivateFieldGet(this, _DurabilityCore_executionStarts, "f").get(id) === currentStart) {
|
|
204
|
+
__classPrivateFieldGet(this, _DurabilityCore_executionStarts, "f").delete(id);
|
|
205
|
+
}
|
|
206
|
+
if (!permitTransferred) {
|
|
207
|
+
eagerPermit?.();
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
}, _DurabilityCore_start = function _DurabilityCore_start(call, eagerPermit) {
|
|
211
|
+
const policy = __classPrivateFieldGet(this, _DurabilityCore_policy, "f").call(this, call.operation);
|
|
212
|
+
const handler = __classPrivateFieldGet(this, _DurabilityCore_handlers, "f")[call.operation];
|
|
213
|
+
return __classPrivateFieldGet(this, _DurabilityCore_engine, "f").startExecution({
|
|
214
|
+
kind: 'calls',
|
|
215
|
+
key: call.id,
|
|
216
|
+
row: call,
|
|
217
|
+
label: `operation "${call.operation}"`,
|
|
218
|
+
entity: operationEntity(call),
|
|
219
|
+
active: __classPrivateFieldGet(this, _DurabilityCore_active, "f"),
|
|
220
|
+
policy,
|
|
221
|
+
emit: __classPrivateFieldGet(this, _DurabilityCore_emit, "f"),
|
|
222
|
+
exhaustedError: () => new DurableAttemptsExhaustedError('operation', call.operation, policy.maxAttempts),
|
|
223
|
+
timeoutError: () => new DurableAttemptTimeoutError(call.operation, policy.attemptTimeoutMs),
|
|
224
|
+
invoke: (attempt, signal) => {
|
|
225
|
+
if (!handler) {
|
|
226
|
+
throw new NonRetryableError(`No handler registered for operation "${call.operation}"`);
|
|
227
|
+
}
|
|
228
|
+
return handler({
|
|
229
|
+
id: call.id,
|
|
230
|
+
operation: call.operation,
|
|
231
|
+
payload: deserialize(call.payload),
|
|
232
|
+
attempt,
|
|
233
|
+
signal,
|
|
234
|
+
});
|
|
235
|
+
},
|
|
236
|
+
complete: async (result, attempt) => {
|
|
237
|
+
let serialized;
|
|
238
|
+
try {
|
|
239
|
+
serialized = serialize(result);
|
|
240
|
+
}
|
|
241
|
+
catch (error) {
|
|
242
|
+
throw new DurableResultSerializationError(call.operation, error);
|
|
243
|
+
}
|
|
244
|
+
const timestamp = Date.now();
|
|
245
|
+
const updated = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").storage.calls.settle(call.id, call.generation_id, attempt, {
|
|
246
|
+
status: 'completed',
|
|
247
|
+
result: serialized,
|
|
248
|
+
last_error: null,
|
|
249
|
+
last_error_name: null,
|
|
250
|
+
completed_at: timestamp,
|
|
251
|
+
});
|
|
252
|
+
return updated ? timestamp : undefined;
|
|
253
|
+
},
|
|
254
|
+
isTerminal: (error) => isErrorInstance(error, DurableResultSerializationError),
|
|
255
|
+
}, eagerPermit);
|
|
256
|
+
};
|
|
257
|
+
// TypeScript cannot declare class members derived from a generic handler map,
|
|
258
|
+
// so the constructor is typed separately; the constructor installs and reserves
|
|
259
|
+
// every operation method at runtime.
|
|
260
|
+
export const Durability = DurabilityCore;
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Marks a handler failure as terminal so it is persisted without another retry.
|
|
3
|
+
*
|
|
4
|
+
* Use this for permanent failures such as invalid input. Transient errors should
|
|
5
|
+
* be thrown normally so the configured retry policy can handle them.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```ts
|
|
9
|
+
* if (!recipient.isValid) {
|
|
10
|
+
* throw new NonRetryableError('Recipient is invalid');
|
|
11
|
+
* }
|
|
12
|
+
* ```
|
|
13
|
+
*/
|
|
14
|
+
export declare class NonRetryableError extends Error {
|
|
15
|
+
constructor(message: string);
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Error recorded when a handler attempt exceeds its configured timeout.
|
|
19
|
+
*
|
|
20
|
+
* Durability creates this error and aborts the attempt's signal; consumers do
|
|
21
|
+
* not need to throw it themselves. Timeout failures follow the normal retry
|
|
22
|
+
* policy and are exposed by `getResult` if they become terminal.
|
|
23
|
+
*/
|
|
24
|
+
export declare class DurableAttemptTimeoutError extends Error {
|
|
25
|
+
constructor(operation: string, timeoutMs: number);
|
|
26
|
+
}
|
|
27
|
+
/** Error recorded when a named alarm attempt exceeds its configured timeout. */
|
|
28
|
+
export declare class DurableAlarmTimeoutError extends Error {
|
|
29
|
+
constructor(name: string, timeoutMs: number);
|
|
30
|
+
}
|
|
31
|
+
/** Error persisted when retry-delay evaluation fails or is unsafe. */
|
|
32
|
+
export declare class DurableRetryPolicyError extends Error {
|
|
33
|
+
constructor(entity: string, reason?: unknown);
|
|
34
|
+
}
|
|
35
|
+
/** Error persisted when a successful result cannot be JSON-serialized. */
|
|
36
|
+
export declare class DurableResultSerializationError extends Error {
|
|
37
|
+
constructor(operation: string, reason?: unknown);
|
|
38
|
+
}
|
|
39
|
+
/** Error persisted when pending work has already reached its attempt limit. */
|
|
40
|
+
export declare class DurableAttemptsExhaustedError extends Error {
|
|
41
|
+
constructor(entity: 'operation' | 'named alarm', name: string, max: number);
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Error thrown when an idempotency key is reused for another operation.
|
|
45
|
+
*
|
|
46
|
+
* A call ID permanently identifies its original operation so `getResult` cannot
|
|
47
|
+
* return a value with the wrong inferred type.
|
|
48
|
+
*/
|
|
49
|
+
export declare class DuplicateDurableCallError extends Error {
|
|
50
|
+
constructor(id: string, existingOperation: string, requestedOperation: string);
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Error thrown when a fanout delivery is settled twice.
|
|
54
|
+
*
|
|
55
|
+
* The first `ack`, `retry`, or `deadLetter` call is binding. A second call on
|
|
56
|
+
* the same delivery, or a call from a stale stub kept across deliveries, is a
|
|
57
|
+
* consumer bug and fails loudly instead of being silently ignored.
|
|
58
|
+
*/
|
|
59
|
+
export declare class FanoutSettlementError extends Error {
|
|
60
|
+
constructor(id: string, outcome?: string);
|
|
61
|
+
}
|
|
62
|
+
/** Error recorded when a target delivery exceeds its configured timeout. */
|
|
63
|
+
export declare class FanoutTimeoutError extends Error {
|
|
64
|
+
constructor(timeoutMs: number);
|
|
65
|
+
}
|
|
66
|
+
/** A definite rejection before the batch was durably accepted. */
|
|
67
|
+
export declare class FanoutEnqueueError extends Error {
|
|
68
|
+
constructor(message: string);
|
|
69
|
+
}
|
|
70
|
+
/** Error thrown when a sharding function returns an invalid shard key. */
|
|
71
|
+
export declare class RoutingError extends Error {
|
|
72
|
+
constructor(message: string);
|
|
73
|
+
}
|
|
74
|
+
export type SerializedError = {
|
|
75
|
+
name: string;
|
|
76
|
+
message: string;
|
|
77
|
+
};
|
|
78
|
+
/** Reduces any thrown value to a persistable name and message, never throwing. */
|
|
79
|
+
export declare const serializeError: (error: unknown) => SerializedError;
|
|
80
|
+
export declare const isErrorInstance: (error: unknown, constructor: new (...args: never[]) => Error) => boolean;
|
|
81
|
+
/** Recognizes this package's NonRetryableError and same-named errors from other packages. */
|
|
82
|
+
export declare const isNonRetryable: (error: unknown) => boolean;
|
|
83
|
+
export declare const reportFailure: (event: string, details: Record<string, unknown>, error: unknown) => void;
|