durability 2.1.0 → 3.0.1
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 +303 -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 +157 -0
- package/dist/scheduler.js +478 -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 +73 -0
- package/dist/stored-message.d.ts +29 -0
- package/dist/stored-message.js +1 -0
- package/package.json +6 -2
package/dist/errors.js
ADDED
|
@@ -0,0 +1,184 @@
|
|
|
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 class NonRetryableError extends Error {
|
|
15
|
+
constructor(message) {
|
|
16
|
+
super(message);
|
|
17
|
+
this.name = 'NonRetryableError';
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Error recorded when a handler attempt exceeds its configured timeout.
|
|
22
|
+
*
|
|
23
|
+
* Durability creates this error and aborts the attempt's signal; consumers do
|
|
24
|
+
* not need to throw it themselves. Timeout failures follow the normal retry
|
|
25
|
+
* policy and are exposed by `getResult` if they become terminal.
|
|
26
|
+
*/
|
|
27
|
+
export class DurableAttemptTimeoutError extends Error {
|
|
28
|
+
constructor(operation, timeoutMs) {
|
|
29
|
+
super(`Durable operation "${operation}" timed out after ${timeoutMs}ms`);
|
|
30
|
+
this.name = 'DurableAttemptTimeoutError';
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
/** Error recorded when a named alarm attempt exceeds its configured timeout. */
|
|
34
|
+
export class DurableAlarmTimeoutError extends Error {
|
|
35
|
+
constructor(name, timeoutMs) {
|
|
36
|
+
super(`Durable alarm "${name}" timed out after ${timeoutMs}ms`);
|
|
37
|
+
this.name = 'DurableAlarmTimeoutError';
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
/** Error persisted when retry-delay evaluation fails or is unsafe. */
|
|
41
|
+
export class DurableRetryPolicyError extends Error {
|
|
42
|
+
constructor(entity, reason) {
|
|
43
|
+
super(`Retry policy for ${entity} must produce a non-negative safe-integer timestamp`);
|
|
44
|
+
this.name = 'DurableRetryPolicyError';
|
|
45
|
+
if (reason !== undefined) {
|
|
46
|
+
Object.defineProperty(this, 'cause', { value: reason });
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
/** Error persisted when a successful result cannot be JSON-serialized. */
|
|
51
|
+
export class DurableResultSerializationError extends Error {
|
|
52
|
+
constructor(operation, reason) {
|
|
53
|
+
super(`Result for durable operation "${operation}" is not JSON-serializable`);
|
|
54
|
+
this.name = 'DurableResultSerializationError';
|
|
55
|
+
if (reason !== undefined) {
|
|
56
|
+
Object.defineProperty(this, 'cause', { value: reason });
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
/** Error persisted when pending work has already reached its attempt limit. */
|
|
61
|
+
export class DurableAttemptsExhaustedError extends Error {
|
|
62
|
+
constructor(entity, name, max) {
|
|
63
|
+
super(`Durable ${entity} "${name}" exhausted its ${max} attempts`);
|
|
64
|
+
this.name = 'DurableAttemptsExhaustedError';
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Error thrown when an idempotency key is reused for another operation.
|
|
69
|
+
*
|
|
70
|
+
* A call ID permanently identifies its original operation so `getResult` cannot
|
|
71
|
+
* return a value with the wrong inferred type.
|
|
72
|
+
*/
|
|
73
|
+
export class DuplicateDurableCallError extends Error {
|
|
74
|
+
constructor(id, existingOperation, requestedOperation) {
|
|
75
|
+
super(`Durable call "${id}" already belongs to operation "${existingOperation}", not "${requestedOperation}"`);
|
|
76
|
+
this.name = 'DuplicateDurableCallError';
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Error thrown when a fanout delivery is settled twice.
|
|
81
|
+
*
|
|
82
|
+
* The first `ack`, `retry`, or `deadLetter` call is binding. A second call on
|
|
83
|
+
* the same delivery, or a call from a stale stub kept across deliveries, is a
|
|
84
|
+
* consumer bug and fails loudly instead of being silently ignored.
|
|
85
|
+
*/
|
|
86
|
+
export class FanoutSettlementError extends Error {
|
|
87
|
+
constructor(id, outcome) {
|
|
88
|
+
super(outcome === undefined
|
|
89
|
+
? `Fanout delivery "${id}" is stale`
|
|
90
|
+
: `Fanout delivery "${id}" was already settled as "${outcome}"`);
|
|
91
|
+
this.name = 'FanoutSettlementError';
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
/** Error recorded when a target delivery exceeds its configured timeout. */
|
|
95
|
+
export class FanoutTimeoutError extends Error {
|
|
96
|
+
constructor(timeoutMs) {
|
|
97
|
+
super(`Fanout delivery timed out after ${timeoutMs}ms`);
|
|
98
|
+
this.name = 'FanoutTimeoutError';
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
/** A definite rejection before the batch was durably accepted. */
|
|
102
|
+
export class FanoutEnqueueError extends Error {
|
|
103
|
+
constructor(message) {
|
|
104
|
+
super(message);
|
|
105
|
+
this.name = 'FanoutEnqueueError';
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
/** Error thrown when a sharding function returns an invalid shard key. */
|
|
109
|
+
export class RoutingError extends Error {
|
|
110
|
+
constructor(message) {
|
|
111
|
+
super(message);
|
|
112
|
+
this.name = 'RoutingError';
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
const readString = (value, property) => {
|
|
116
|
+
try {
|
|
117
|
+
const candidate = Reflect.get(value, property);
|
|
118
|
+
return typeof candidate === 'string' && candidate.length > 0
|
|
119
|
+
? candidate
|
|
120
|
+
: undefined;
|
|
121
|
+
}
|
|
122
|
+
catch {
|
|
123
|
+
return undefined;
|
|
124
|
+
}
|
|
125
|
+
};
|
|
126
|
+
/** Reduces any thrown value to a persistable name and message, never throwing. */
|
|
127
|
+
export const serializeError = (error) => {
|
|
128
|
+
if (error === null) {
|
|
129
|
+
return { name: 'Error', message: 'null' };
|
|
130
|
+
}
|
|
131
|
+
if (typeof error !== 'object' && typeof error !== 'function') {
|
|
132
|
+
return { name: 'Error', message: String(error) };
|
|
133
|
+
}
|
|
134
|
+
return {
|
|
135
|
+
name: readString(error, 'name') ?? 'Error',
|
|
136
|
+
message: readString(error, 'message') ?? 'Unknown thrown value',
|
|
137
|
+
};
|
|
138
|
+
};
|
|
139
|
+
export const isErrorInstance = (error, constructor) => {
|
|
140
|
+
try {
|
|
141
|
+
return error instanceof constructor;
|
|
142
|
+
}
|
|
143
|
+
catch {
|
|
144
|
+
return false;
|
|
145
|
+
}
|
|
146
|
+
};
|
|
147
|
+
/** Recognizes this package's NonRetryableError and same-named errors from other packages. */
|
|
148
|
+
export const isNonRetryable = (error) => {
|
|
149
|
+
if (isErrorInstance(error, NonRetryableError)) {
|
|
150
|
+
return true;
|
|
151
|
+
}
|
|
152
|
+
if ((typeof error !== 'object' && typeof error !== 'function') ||
|
|
153
|
+
error === null) {
|
|
154
|
+
return false;
|
|
155
|
+
}
|
|
156
|
+
if (readString(error, 'name') === 'NonRetryableError') {
|
|
157
|
+
return true;
|
|
158
|
+
}
|
|
159
|
+
try {
|
|
160
|
+
const constructor = Reflect.get(error, 'constructor');
|
|
161
|
+
return (constructor !== null &&
|
|
162
|
+
(typeof constructor === 'object' || typeof constructor === 'function') &&
|
|
163
|
+
readString(constructor, 'name') === 'NonRetryableError');
|
|
164
|
+
}
|
|
165
|
+
catch {
|
|
166
|
+
return false;
|
|
167
|
+
}
|
|
168
|
+
};
|
|
169
|
+
export const reportFailure = (event, details, error) => {
|
|
170
|
+
try {
|
|
171
|
+
const stack = error !== null &&
|
|
172
|
+
(typeof error === 'object' || typeof error === 'function')
|
|
173
|
+
? readString(error, 'stack')
|
|
174
|
+
: undefined;
|
|
175
|
+
console.error({
|
|
176
|
+
event,
|
|
177
|
+
...details,
|
|
178
|
+
error: { ...serializeError(error), ...(stack ? { stack } : {}) },
|
|
179
|
+
});
|
|
180
|
+
}
|
|
181
|
+
catch {
|
|
182
|
+
return;
|
|
183
|
+
}
|
|
184
|
+
};
|
package/dist/fanout.d.ts
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import type { LifecycleHook } from './lifecycle.js';
|
|
2
|
+
import { RoutingLoad, type EnqueueResult, type LoadSnapshot } from './load.js';
|
|
3
|
+
import type { MessageWrite } from './stored-message.js';
|
|
4
|
+
import { type ExecutionPolicyOptions } from './policy.js';
|
|
5
|
+
import { type SchedulerAttachment } from './scheduler.js';
|
|
6
|
+
export type FanoutInput<Body = unknown> = {
|
|
7
|
+
id?: string;
|
|
8
|
+
body: Body;
|
|
9
|
+
/** Defaults to id. Redrive uses the DLQ entry ID to register fresh attempts. */
|
|
10
|
+
deduplicationKey?: string;
|
|
11
|
+
};
|
|
12
|
+
/** Each target receives its own settlement capability for each message. */
|
|
13
|
+
export type DurabilityFanoutMessage<Body = unknown> = {
|
|
14
|
+
id: string;
|
|
15
|
+
deliveryId: string;
|
|
16
|
+
target: string;
|
|
17
|
+
body: Body;
|
|
18
|
+
attempt: number;
|
|
19
|
+
enqueuedAt: number;
|
|
20
|
+
ack(): Promise<void>;
|
|
21
|
+
retry(delayMs?: number): Promise<void>;
|
|
22
|
+
deadLetter(): Promise<void>;
|
|
23
|
+
};
|
|
24
|
+
export type FanoutTarget<Body> = ExecutionPolicyOptions & ({
|
|
25
|
+
deliver(messages: DurabilityFanoutMessage<Body>[]): unknown | Promise<unknown>;
|
|
26
|
+
storage?: never;
|
|
27
|
+
} | {
|
|
28
|
+
storage: MessageWrite<Body>;
|
|
29
|
+
deliver?: never;
|
|
30
|
+
});
|
|
31
|
+
export type FanoutEnqueueOptions = {
|
|
32
|
+
/** Omit for all static targets. Redrive specifies only the failed target. */
|
|
33
|
+
targets?: readonly string[];
|
|
34
|
+
};
|
|
35
|
+
export type DurabilityFanoutConfig<Body> = SchedulerAttachment & ExecutionPolicyOptions & {
|
|
36
|
+
targets: Record<string, FanoutTarget<Body>>;
|
|
37
|
+
routing?: RoutingLoad;
|
|
38
|
+
/** Receives terminal failures. Without it, terminal work is retained. */
|
|
39
|
+
dlq?: MessageWrite<Body>;
|
|
40
|
+
maxBatchSize?: number;
|
|
41
|
+
onLifecycleEvent?: LifecycleHook;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* A composable DO capability: durable, independent delivery to static named
|
|
45
|
+
* targets. Share a scheduler with operations/alarms on the same object.
|
|
46
|
+
* Register targets under stable IDs; removing a target pauses its pending work.
|
|
47
|
+
*/
|
|
48
|
+
export declare class DurabilityFanout<Body = unknown> {
|
|
49
|
+
#private;
|
|
50
|
+
constructor(config: DurabilityFanoutConfig<Body>);
|
|
51
|
+
static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): import("./migrations.js").DurabilityMigrationResult;
|
|
52
|
+
alarm(info?: AlarmInvocationInfo): Promise<void>;
|
|
53
|
+
load(): Promise<LoadSnapshot>;
|
|
54
|
+
/**
|
|
55
|
+
* Atomically accepts the whole batch, including its frozen target set.
|
|
56
|
+
* Definite input conflicts return success:false. Storage/commit uncertainty
|
|
57
|
+
* throws: a transport failure is never represented as definite rejection.
|
|
58
|
+
* IDs deduplicate while their registration is retained, not forever.
|
|
59
|
+
*/
|
|
60
|
+
enqueue(messages: FanoutInput<Body> | FanoutInput<Body>[], options?: FanoutEnqueueOptions): Promise<EnqueueResult<string[]>>;
|
|
61
|
+
}
|