durability 5.3.0 → 5.4.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 +23 -14
- package/dist/alarms/index.d.ts +1 -1
- package/dist/alarms/index.js +6 -3
- package/dist/dev.d.ts +7 -3
- package/dist/dev.js +17 -11
- package/dist/durable-object-target.js +8 -4
- package/dist/errors.d.ts +13 -7
- package/dist/errors.js +34 -32
- package/dist/fanout/index.d.ts +1 -1
- package/dist/fanout/index.js +15 -13
- package/dist/lifecycle.d.ts +1 -0
- package/dist/lifecycle.js +2 -2
- package/dist/log/index.js +5 -2
- package/dist/memoize/index.js +6 -1
- package/dist/operations/index.js +8 -4
- package/dist/outbox/index.d.ts +1 -1
- package/dist/outbox/index.js +7 -4
- package/dist/policy.d.ts +1 -1
- package/dist/policy.js +2 -1
- package/dist/predicates.d.ts +9 -0
- package/dist/predicates.js +10 -0
- package/dist/routing/client.js +3 -4
- package/dist/routing/index.d.ts +1 -1
- package/dist/routing/index.js +14 -10
- package/dist/schedule/index.d.ts +2 -2
- package/dist/schedule/index.js +16 -12
- package/dist/scheduler/index.d.ts +16 -13
- package/dist/scheduler/index.js +39 -33
- package/dist/semaphore/client.js +2 -1
- package/dist/semaphore/index.d.ts +1 -1
- package/dist/semaphore/index.js +10 -5
- package/dist/semaphore/leases.d.ts +3 -2
- package/dist/semaphore/leases.js +3 -2
- package/dist/semaphore/queue-store.js +2 -1
- package/dist/semaphore/queue.d.ts +1 -1
- package/dist/semaphore/queue.js +34 -22
- package/dist/semaphore/server.js +31 -22
- package/dist/serialization.d.ts +3 -2
- package/dist/serialization.js +16 -13
- package/dist/socket/client.d.ts +21 -7
- package/dist/socket/client.js +12 -5
- package/dist/socket/index.d.ts +20 -13
- package/dist/socket/index.js +40 -18
- package/dist/socket/protocol.d.ts +37 -17
- package/dist/socket/protocol.js +30 -36
- package/dist/topology/client.js +9 -6
- package/dist/topology/index.d.ts +3 -3
- package/dist/topology/index.js +38 -33
- package/dist/topology/snapshot.d.ts +6 -5
- package/dist/topology/snapshot.js +5 -2
- package/dist/tracker/index.js +10 -2
- package/dist/tracker/source.d.ts +6 -2
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -666,9 +666,9 @@ export class TodoList extends DurableObject<Env> {
|
|
|
666
666
|
readonly socket = new DurabilitySocket({
|
|
667
667
|
context: this.ctx,
|
|
668
668
|
inbound: {
|
|
669
|
-
//
|
|
670
|
-
list: () => [...this.todos.values()],
|
|
671
|
-
//
|
|
669
|
+
// Every handler validates its input; `list` takes none.
|
|
670
|
+
list: { input: v.undefined(), handle: () => [...this.todos.values()] },
|
|
671
|
+
// Here the handler is a durable operation.
|
|
672
672
|
createTodo: {
|
|
673
673
|
input: v.object({ id: v.string(), payload: TodoSchema }),
|
|
674
674
|
handle: this.durability.createTodo,
|
|
@@ -744,7 +744,7 @@ export default {
|
|
|
744
744
|
};
|
|
745
745
|
```
|
|
746
746
|
|
|
747
|
-
|
|
747
|
+
Every inbound handler is `{ input, handle }`, where `input` is any [Standard Schema](https://standardschema.dev) validator (zod, Valibot, ArkType, …) and `handle` receives the schema's output. A handler without a schema, or whose `handle` does not accept the schema's output, does not compile. A method that takes no input uses a schema for `undefined`, such as Valibot's `v.undefined()`, and the client calls it without arguments. Handlers receive `call.metadata`, the value `metadata(request)` returned at upgrade time; it is stored in the WebSocket attachment, so it survives hibernation. The fronting Worker is responsible for authentication and for routing the upgrade to the right object; the socket does no authorization of its own. `metadata` must be assignable to every `SocketCall<…>` annotation the handlers declare, and is required when any of them excludes `undefined`, so a handler never runs without the metadata it declares. A connection accepted before the socket had `metadata`, such as one from before the deploy that added it, carries none: its next frame closes it with code `1012` before reaching a handler, and the browser client reconnects with backoff so the new upgrade captures it.
|
|
748
748
|
|
|
749
749
|
Every outbound event is persisted to `durability_socket_events` with a sequence number before it is pushed. A reconnecting client subscribes from the last sequence it saw: events still within `retention` (default 1000) are replayed in order, otherwise the client is told to resync and should rebuild its state from an inbound snapshot call. Payloads must be JSON. Keep-alive pings are answered by the runtime through `setWebSocketAutoResponse`, so idle connections never wake the object. Frames over 1 MiB are rejected; malformed frames close the connection with code `4002`.
|
|
750
750
|
|
|
@@ -756,7 +756,9 @@ Like the other helpers, `DurabilitySocket` takes a `channel` option, `default` u
|
|
|
756
756
|
readonly librarySocket = new DurabilitySocket({
|
|
757
757
|
context: this.ctx,
|
|
758
758
|
channel: 'durable-alerts',
|
|
759
|
-
inbound: {
|
|
759
|
+
inbound: {
|
|
760
|
+
list: { input: v.undefined(), handle: () => this.alerts.list() },
|
|
761
|
+
},
|
|
760
762
|
outbound: { updated: event<Alert>() },
|
|
761
763
|
});
|
|
762
764
|
|
|
@@ -867,7 +869,7 @@ readonly socket = new DurabilitySocket({
|
|
|
867
869
|
inbound: {
|
|
868
870
|
work: {
|
|
869
871
|
input: v.object({ cursor: v.optional(v.string()) }),
|
|
870
|
-
handle: (query
|
|
872
|
+
handle: (query) => this.tracker.records(query),
|
|
871
873
|
},
|
|
872
874
|
},
|
|
873
875
|
outbound: { settled: event<DurabilityOperationEvent<typeof handlers>>() },
|
|
@@ -1017,10 +1019,11 @@ export class JobShard extends DurableObject<Env> {
|
|
|
1017
1019
|
scheduler: this.scheduler,
|
|
1018
1020
|
clientId: this.ctx.id.toString(),
|
|
1019
1021
|
server: limits.with(timeout, 5_000),
|
|
1020
|
-
admit: (items) =>
|
|
1021
|
-
Promise.all(
|
|
1022
|
+
admit: async (items) => {
|
|
1023
|
+
await Promise.all(
|
|
1022
1024
|
items.map((item) => this.jobs.run({ id: item.id, payload: item.body }))
|
|
1023
|
-
)
|
|
1025
|
+
);
|
|
1026
|
+
},
|
|
1024
1027
|
// The hook above is best-effort; this check returns any permit it missed.
|
|
1025
1028
|
finished: async (ids) => {
|
|
1026
1029
|
const results = await Promise.all(
|
|
@@ -1290,8 +1293,9 @@ export class Coordinator extends DurableObject<Env> {
|
|
|
1290
1293
|
private readonly topology = new DurabilityTopology({
|
|
1291
1294
|
scheduler: this.scheduler,
|
|
1292
1295
|
publish: {
|
|
1293
|
-
write: (snapshot, encoded) =>
|
|
1294
|
-
this.env.TOPOLOGY.put(`topology/${snapshot.group}`, encoded)
|
|
1296
|
+
write: async (snapshot, encoded) => {
|
|
1297
|
+
await this.env.TOPOLOGY.put(`topology/${snapshot.group}`, encoded);
|
|
1298
|
+
},
|
|
1295
1299
|
delete: (group) => this.env.TOPOLOGY.delete(`topology/${group}`),
|
|
1296
1300
|
},
|
|
1297
1301
|
states: {
|
|
@@ -1397,8 +1401,9 @@ private readonly libraryTopology = new DurabilityTopology({
|
|
|
1397
1401
|
scheduler: this.scheduler,
|
|
1398
1402
|
channel: 'library',
|
|
1399
1403
|
publish: {
|
|
1400
|
-
write: (snapshot, encoded) =>
|
|
1401
|
-
this.env.TOPOLOGY.put(`library/${snapshot.group}`, encoded)
|
|
1404
|
+
write: async (snapshot, encoded) => {
|
|
1405
|
+
await this.env.TOPOLOGY.put(`library/${snapshot.group}`, encoded);
|
|
1406
|
+
},
|
|
1402
1407
|
delete: (group) => this.env.TOPOLOGY.delete(`library/${group}`),
|
|
1403
1408
|
},
|
|
1404
1409
|
});
|
|
@@ -1491,7 +1496,11 @@ Records leave only through `trim()`, which enforces `maxAgeMs` and `maxRecords`,
|
|
|
1491
1496
|
```ts
|
|
1492
1497
|
private readonly alarms = new DurabilityAlarms({
|
|
1493
1498
|
scheduler: this.scheduler,
|
|
1494
|
-
handlers: {
|
|
1499
|
+
handlers: {
|
|
1500
|
+
compact: async () => {
|
|
1501
|
+
await this.log.trim();
|
|
1502
|
+
},
|
|
1503
|
+
},
|
|
1495
1504
|
});
|
|
1496
1505
|
|
|
1497
1506
|
alarm(info?: AlarmInvocationInfo) {
|
package/dist/alarms/index.d.ts
CHANGED
|
@@ -35,7 +35,7 @@ export type DurableAlarmInfo = {
|
|
|
35
35
|
platform: AlarmInvocationInfo | undefined;
|
|
36
36
|
};
|
|
37
37
|
/** A handler for one named logical alarm. */
|
|
38
|
-
export type DurableAlarmHandler = (info: DurableAlarmInfo) =>
|
|
38
|
+
export type DurableAlarmHandler = (info: DurableAlarmInfo) => void | Promise<void>;
|
|
39
39
|
/** Policy configuration for named alarms. */
|
|
40
40
|
export type DurabilityAlarmsOptions<Names extends string = string> = ExecutionPolicyOptions & {
|
|
41
41
|
/** Execution policy overrides keyed by alarm name. */
|
package/dist/alarms/index.js
CHANGED
|
@@ -18,6 +18,7 @@ import { durabilityNamedAlarmMigrations } from './migrations.js';
|
|
|
18
18
|
import { durabilityMemoMigrations } from '../memoize/migrations.js';
|
|
19
19
|
import { migrateCapability, } from '../migrations.js';
|
|
20
20
|
import { alarmMethodOptionsSchema, createPolicyResolver, } from '../policy.js';
|
|
21
|
+
import { isFunction } from '../predicates.js';
|
|
21
22
|
import { assertChannel, defaultChannel, engineFor, } from '../scheduler/index.js';
|
|
22
23
|
import { createMemoize, deleteMemos, deleteMemosOfDroppedTable, memoizedKeys, } from '../memoize/index.js';
|
|
23
24
|
import { deleteAttempt, listCreated } from '../storage.js';
|
|
@@ -35,7 +36,7 @@ const alarmRowSchema = v.object({
|
|
|
35
36
|
created_at: v.pipe(v.number(), v.safeInteger(), v.minValue(0)),
|
|
36
37
|
});
|
|
37
38
|
const alarmsTable = { name: 'durability_alarms', key: 'name' };
|
|
38
|
-
const alarmHandlerSchema = v.custom(
|
|
39
|
+
const alarmHandlerSchema = v.custom(isFunction);
|
|
39
40
|
const readAlarm = (sql, channel, name) => v.parse(v.optional(alarmRowSchema), sql
|
|
40
41
|
.exec('SELECT * FROM durability_alarms WHERE channel = ? AND name = ?', channel, name)
|
|
41
42
|
.toArray()[0]);
|
|
@@ -123,6 +124,8 @@ class DurabilityAlarmsCore {
|
|
|
123
124
|
* returns a function that detaches it.
|
|
124
125
|
*/
|
|
125
126
|
lifecycle(hook) {
|
|
127
|
+
// SAFETY: every event this instance emits, from scheduling, alarmEntity
|
|
128
|
+
// attempts, and purges, has entityKind 'named_alarm'.
|
|
126
129
|
return __classPrivateFieldGet(this, _DurabilityAlarmsCore_lifecycle, "f").add(hook);
|
|
127
130
|
}
|
|
128
131
|
/**
|
|
@@ -314,6 +317,6 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_channel = ne
|
|
|
314
317
|
});
|
|
315
318
|
};
|
|
316
319
|
traceMethods(DurabilityAlarmsCore.prototype, 'DurabilityAlarms');
|
|
317
|
-
//
|
|
318
|
-
// the
|
|
320
|
+
// SAFETY: the constructor defines a scheduling method for every handler name on
|
|
321
|
+
// the instance, members TypeScript cannot declare from a generic name union.
|
|
319
322
|
export const DurabilityAlarms = DurabilityAlarmsCore;
|
package/dist/dev.d.ts
CHANGED
|
@@ -3,14 +3,17 @@
|
|
|
3
3
|
* is process-wide and monotonic so interleaved async work can be reordered
|
|
4
4
|
* and correlated when replaying a simulation.
|
|
5
5
|
*/
|
|
6
|
-
export declare const trace: (operation: string, details?:
|
|
6
|
+
export declare const trace: <Details extends object>(operation: string, details?: Details) => number;
|
|
7
7
|
/**
|
|
8
8
|
* Wraps a public function so dev mode logs its arguments and outcome. `details`
|
|
9
9
|
* identifies the receiver when the arguments alone do not.
|
|
10
10
|
*/
|
|
11
|
-
export declare const traceFunction: <Args extends unknown[], Result>(method: string, fn: (...args: Args) => Result, details?:
|
|
11
|
+
export declare const traceFunction: <This, Args extends unknown[], Result, Details extends object>(method: string, fn: (this: This, ...args: Args) => Result, details?: Details) => ((this: This, ...args: Args) => Result);
|
|
12
|
+
type ClassPrototype = {
|
|
13
|
+
readonly constructor: Function;
|
|
14
|
+
};
|
|
12
15
|
/** Wraps every method on a class prototype with {@link traceFunction}. */
|
|
13
|
-
export declare const traceMethods: (prototype:
|
|
16
|
+
export declare const traceMethods: (prototype: ClassPrototype, owner: string) => void;
|
|
14
17
|
/** Logs each lifecycle event before `emit` hands it to the consumer's hooks. */
|
|
15
18
|
export declare const traceLifecycle: <Event extends Record<string, unknown>>(emit: (event: Event) => void) => ((event: Event) => void);
|
|
16
19
|
/**
|
|
@@ -20,3 +23,4 @@ export declare const traceLifecycle: <Event extends Record<string, unknown>>(emi
|
|
|
20
23
|
* call once.
|
|
21
24
|
*/
|
|
22
25
|
export declare const traceStorage: <Storage extends object>(storage: Storage) => Storage;
|
|
26
|
+
export {};
|
package/dist/dev.js
CHANGED
|
@@ -1,17 +1,18 @@
|
|
|
1
1
|
import { serializeError } from './errors.js';
|
|
2
|
+
import { isFunction } from './predicates.js';
|
|
2
3
|
/**
|
|
3
4
|
* True only when the build defines `__DURABILITY_DEV__` as `true`. Bundlers
|
|
4
5
|
* fold the check to a constant, so production builds pay one branch per
|
|
5
6
|
* traced call and log nothing.
|
|
6
7
|
*/
|
|
7
|
-
const devMode = typeof __DURABILITY_DEV__
|
|
8
|
+
const devMode = typeof __DURABILITY_DEV__ !== 'undefined' && __DURABILITY_DEV__ === true;
|
|
8
9
|
let sequence = 0;
|
|
9
10
|
/**
|
|
10
11
|
* Logs one dev-mode trace entry and returns its sequence number. The sequence
|
|
11
12
|
* is process-wide and monotonic so interleaved async work can be reordered
|
|
12
13
|
* and correlated when replaying a simulation.
|
|
13
14
|
*/
|
|
14
|
-
export const trace = (operation, details
|
|
15
|
+
export const trace = (operation, details) => {
|
|
15
16
|
if (!devMode) {
|
|
16
17
|
return 0;
|
|
17
18
|
}
|
|
@@ -45,15 +46,15 @@ const traceCall = (operation, details, run) => {
|
|
|
45
46
|
return result;
|
|
46
47
|
}
|
|
47
48
|
// Observes the promise without changing what the caller sees.
|
|
48
|
-
void result.then((value) => trace(`${operation}.return`, { call, result: value }), (
|
|
49
|
+
void result.then((value) => trace(`${operation}.return`, { call, result: value }), (cause) => trace(`${operation}.throw`, { call, error: serializeError(cause) }));
|
|
49
50
|
return result;
|
|
50
51
|
};
|
|
51
|
-
const loggableArgs = (args) => args.filter((arg) =>
|
|
52
|
+
const loggableArgs = (args) => args.filter((arg) => !isFunction(arg));
|
|
52
53
|
/**
|
|
53
54
|
* Wraps a public function so dev mode logs its arguments and outcome. `details`
|
|
54
55
|
* identifies the receiver when the arguments alone do not.
|
|
55
56
|
*/
|
|
56
|
-
export const traceFunction = (method, fn, details
|
|
57
|
+
export const traceFunction = (method, fn, details) => {
|
|
57
58
|
if (!devMode) {
|
|
58
59
|
return fn;
|
|
59
60
|
}
|
|
@@ -68,7 +69,7 @@ export const traceMethods = (prototype, owner) => {
|
|
|
68
69
|
}
|
|
69
70
|
for (const name of Object.getOwnPropertyNames(prototype)) {
|
|
70
71
|
const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
|
|
71
|
-
if (name === 'constructor' ||
|
|
72
|
+
if (name === 'constructor' || !isFunction(descriptor?.value)) {
|
|
72
73
|
continue;
|
|
73
74
|
}
|
|
74
75
|
Object.defineProperty(prototype, name, {
|
|
@@ -97,7 +98,7 @@ const traceSql = (sql) => new Proxy(sql, {
|
|
|
97
98
|
return target.exec(query, ...bindings);
|
|
98
99
|
};
|
|
99
100
|
}
|
|
100
|
-
return
|
|
101
|
+
return isFunction(value) ? value.bind(target) : value;
|
|
101
102
|
},
|
|
102
103
|
});
|
|
103
104
|
const proxyStorage = (storage, scope) => {
|
|
@@ -106,22 +107,25 @@ const proxyStorage = (storage, scope) => {
|
|
|
106
107
|
get(target, key) {
|
|
107
108
|
const value = Reflect.get(target, key);
|
|
108
109
|
if (key === 'sql' && value !== undefined) {
|
|
110
|
+
// SAFETY: proxyStorage wraps DurableObjectStorage, whose `sql` is a
|
|
111
|
+
// SqlStorage; a transaction has no `sql` and never reaches here.
|
|
109
112
|
sql ?? (sql = traceSql(value));
|
|
110
113
|
return sql;
|
|
111
114
|
}
|
|
112
|
-
if (
|
|
115
|
+
if (!isFunction(value)) {
|
|
113
116
|
return value;
|
|
114
117
|
}
|
|
115
118
|
const method = `${scope}.${String(key)}`;
|
|
116
119
|
return (...args) => {
|
|
120
|
+
const [closure] = args;
|
|
117
121
|
// Alarm writes inside `transaction` go through the transaction object.
|
|
118
|
-
const forwarded = key === 'transaction' &&
|
|
122
|
+
const forwarded = key === 'transaction' && isFunction(closure)
|
|
119
123
|
? [
|
|
120
|
-
(transaction) =>
|
|
124
|
+
(transaction) => closure(proxyStorage(transaction, 'transaction')),
|
|
121
125
|
...args.slice(1),
|
|
122
126
|
]
|
|
123
127
|
: args;
|
|
124
|
-
return traceCall('storage', { method, args: loggableArgs(args) }, () =>
|
|
128
|
+
return traceCall('storage', { method, args: loggableArgs(args) }, () => value.apply(target, forwarded));
|
|
125
129
|
};
|
|
126
130
|
},
|
|
127
131
|
});
|
|
@@ -140,6 +144,8 @@ export const traceStorage = (storage) => {
|
|
|
140
144
|
}
|
|
141
145
|
const existing = tracedStorage.get(storage);
|
|
142
146
|
if (existing) {
|
|
147
|
+
// SAFETY: tracedStorage maps a storage only to the proxy of that same
|
|
148
|
+
// storage, set below.
|
|
143
149
|
return existing;
|
|
144
150
|
}
|
|
145
151
|
const traced = proxyStorage(storage, 'storage');
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { exports as workerExports } from 'cloudflare:workers';
|
|
2
|
+
import { isFunction, isObjectOrFunction } from './predicates.js';
|
|
2
3
|
export const resolveNamespace = (config, error) => {
|
|
3
4
|
const namespace = config.namespace?.();
|
|
4
5
|
if (namespace) {
|
|
@@ -7,11 +8,14 @@ export const resolveNamespace = (config, error) => {
|
|
|
7
8
|
if (!config.exportName) {
|
|
8
9
|
throw error('Use the durability Vite plugin, exportName, or an explicit namespace to resolve the target');
|
|
9
10
|
}
|
|
10
|
-
const
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
11
|
+
const exportsByName = workerExports;
|
|
12
|
+
const exported = exportsByName[config.exportName];
|
|
13
|
+
if (!isObjectOrFunction(exported) ||
|
|
14
|
+
!('getByName' in exported) ||
|
|
15
|
+
!isFunction(exported.getByName)) {
|
|
14
16
|
throw error(`Export "${config.exportName}" is not a Durable Object namespace`);
|
|
15
17
|
}
|
|
18
|
+
// SAFETY: exportName names the binding of the target class (set by the Vite
|
|
19
|
+
// plugin or the caller), and the check above found its getByName.
|
|
16
20
|
return exported;
|
|
17
21
|
};
|
package/dist/errors.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { Json } from './serialization.js';
|
|
1
2
|
/**
|
|
2
3
|
* Marks a handler failure as terminal so it is persisted without another retry.
|
|
3
4
|
*
|
|
@@ -30,18 +31,18 @@ export declare class DurableAlarmTimeoutError extends Error {
|
|
|
30
31
|
}
|
|
31
32
|
/** Error persisted when retry-delay evaluation fails or is unsafe. */
|
|
32
33
|
export declare class DurableRetryPolicyError extends Error {
|
|
33
|
-
constructor(entity: string,
|
|
34
|
+
constructor(entity: string, cause?: unknown);
|
|
34
35
|
}
|
|
35
36
|
/** Error persisted when a successful result cannot be JSON-serialized. */
|
|
36
37
|
export declare class DurableResultSerializationError extends Error {
|
|
37
|
-
constructor(operation: string,
|
|
38
|
+
constructor(operation: string, cause?: unknown);
|
|
38
39
|
}
|
|
39
40
|
/**
|
|
40
41
|
* Error persisted when a memoized result cannot be JSON-serialized. It is
|
|
41
42
|
* terminal because every retry would fail the same way.
|
|
42
43
|
*/
|
|
43
44
|
export declare class DurableMemoSerializationError extends NonRetryableError {
|
|
44
|
-
constructor(key: string,
|
|
45
|
+
constructor(key: string, cause?: unknown);
|
|
45
46
|
}
|
|
46
47
|
/**
|
|
47
48
|
* Error persisted when work memoizes more keys, or a larger result, than the
|
|
@@ -139,11 +140,15 @@ export type SerializedError = {
|
|
|
139
140
|
message: string;
|
|
140
141
|
};
|
|
141
142
|
/** Reduces any thrown value to a persistable name and message, never throwing. */
|
|
142
|
-
export declare const serializeError: (
|
|
143
|
-
export declare const isErrorInstance: (error: unknown, constructor: new (...args: never[]) =>
|
|
143
|
+
export declare const serializeError: (cause: unknown) => SerializedError;
|
|
144
|
+
export declare const isErrorInstance: <Instance extends Error>(error: unknown, constructor: new (...args: never[]) => Instance) => error is Instance;
|
|
144
145
|
/** Recognizes this package's NonRetryableError and same-named errors from other packages. */
|
|
145
|
-
export declare const isNonRetryable: (
|
|
146
|
-
|
|
146
|
+
export declare const isNonRetryable: (cause: unknown) => boolean;
|
|
147
|
+
/** Fields logged with a failure to identify the work that failed. */
|
|
148
|
+
type FailureDetails = {
|
|
149
|
+
readonly [field: string]: Json;
|
|
150
|
+
};
|
|
151
|
+
export declare const reportFailure: (event: string, details: FailureDetails, cause: unknown) => void;
|
|
147
152
|
/** A definite rejection of a topology change or configuration. */
|
|
148
153
|
export declare class TopologyError extends Error {
|
|
149
154
|
constructor(message: string);
|
|
@@ -161,3 +166,4 @@ export declare class TopologyUnavailableError extends Error {
|
|
|
161
166
|
cause?: unknown;
|
|
162
167
|
});
|
|
163
168
|
}
|
|
169
|
+
export {};
|
package/dist/errors.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { isNonEmptyString, isObjectOrFunction } from './predicates.js';
|
|
1
2
|
/**
|
|
2
3
|
* Marks a handler failure as terminal so it is persisted without another retry.
|
|
3
4
|
*
|
|
@@ -39,21 +40,21 @@ export class DurableAlarmTimeoutError extends Error {
|
|
|
39
40
|
}
|
|
40
41
|
/** Error persisted when retry-delay evaluation fails or is unsafe. */
|
|
41
42
|
export class DurableRetryPolicyError extends Error {
|
|
42
|
-
constructor(entity,
|
|
43
|
+
constructor(entity, cause) {
|
|
43
44
|
super(`Retry policy for ${entity} must produce a non-negative safe-integer timestamp`);
|
|
44
45
|
this.name = 'DurableRetryPolicyError';
|
|
45
|
-
if (
|
|
46
|
-
Object.defineProperty(this, 'cause', { value:
|
|
46
|
+
if (cause !== undefined) {
|
|
47
|
+
Object.defineProperty(this, 'cause', { value: cause });
|
|
47
48
|
}
|
|
48
49
|
}
|
|
49
50
|
}
|
|
50
51
|
/** Error persisted when a successful result cannot be JSON-serialized. */
|
|
51
52
|
export class DurableResultSerializationError extends Error {
|
|
52
|
-
constructor(operation,
|
|
53
|
+
constructor(operation, cause) {
|
|
53
54
|
super(`Result for durable operation "${operation}" is not JSON-serializable`);
|
|
54
55
|
this.name = 'DurableResultSerializationError';
|
|
55
|
-
if (
|
|
56
|
-
Object.defineProperty(this, 'cause', { value:
|
|
56
|
+
if (cause !== undefined) {
|
|
57
|
+
Object.defineProperty(this, 'cause', { value: cause });
|
|
57
58
|
}
|
|
58
59
|
}
|
|
59
60
|
}
|
|
@@ -62,11 +63,11 @@ export class DurableResultSerializationError extends Error {
|
|
|
62
63
|
* terminal because every retry would fail the same way.
|
|
63
64
|
*/
|
|
64
65
|
export class DurableMemoSerializationError extends NonRetryableError {
|
|
65
|
-
constructor(key,
|
|
66
|
+
constructor(key, cause) {
|
|
66
67
|
super(`Memoized result for key ${JSON.stringify(key)} is not JSON-serializable`);
|
|
67
68
|
this.name = 'DurableMemoSerializationError';
|
|
68
|
-
if (
|
|
69
|
-
Object.defineProperty(this, 'cause', { value:
|
|
69
|
+
if (cause !== undefined) {
|
|
70
|
+
Object.defineProperty(this, 'cause', { value: cause });
|
|
70
71
|
}
|
|
71
72
|
}
|
|
72
73
|
}
|
|
@@ -213,26 +214,24 @@ export class RoutingError extends Error {
|
|
|
213
214
|
}
|
|
214
215
|
const readString = (value, property) => {
|
|
215
216
|
try {
|
|
216
|
-
const candidate =
|
|
217
|
-
return
|
|
218
|
-
? candidate
|
|
219
|
-
: undefined;
|
|
217
|
+
const candidate = value[property];
|
|
218
|
+
return isNonEmptyString(candidate) ? candidate : undefined;
|
|
220
219
|
}
|
|
221
220
|
catch {
|
|
222
221
|
return undefined;
|
|
223
222
|
}
|
|
224
223
|
};
|
|
225
224
|
/** Reduces any thrown value to a persistable name and message, never throwing. */
|
|
226
|
-
export const serializeError = (
|
|
227
|
-
if (
|
|
225
|
+
export const serializeError = (cause) => {
|
|
226
|
+
if (cause === null) {
|
|
228
227
|
return { name: 'Error', message: 'null' };
|
|
229
228
|
}
|
|
230
|
-
if (
|
|
231
|
-
return { name: 'Error', message: String(
|
|
229
|
+
if (!isObjectOrFunction(cause)) {
|
|
230
|
+
return { name: 'Error', message: String(cause) };
|
|
232
231
|
}
|
|
233
232
|
return {
|
|
234
|
-
name: readString(
|
|
235
|
-
message: readString(
|
|
233
|
+
name: readString(cause, 'name') ?? 'Error',
|
|
234
|
+
message: readString(cause, 'message') ?? 'Unknown thrown value',
|
|
236
235
|
};
|
|
237
236
|
};
|
|
238
237
|
export const isErrorInstance = (error, constructor) => {
|
|
@@ -244,37 +243,40 @@ export const isErrorInstance = (error, constructor) => {
|
|
|
244
243
|
}
|
|
245
244
|
};
|
|
246
245
|
/** Recognizes this package's NonRetryableError and same-named errors from other packages. */
|
|
247
|
-
export const isNonRetryable = (
|
|
248
|
-
if (isErrorInstance(
|
|
246
|
+
export const isNonRetryable = (cause) => {
|
|
247
|
+
if (isErrorInstance(cause, NonRetryableError)) {
|
|
249
248
|
return true;
|
|
250
249
|
}
|
|
251
|
-
if ((
|
|
252
|
-
error === null) {
|
|
250
|
+
if (!isObjectOrFunction(cause)) {
|
|
253
251
|
return false;
|
|
254
252
|
}
|
|
255
|
-
if (readString(
|
|
253
|
+
if (readString(cause, 'name') === 'NonRetryableError') {
|
|
256
254
|
return true;
|
|
257
255
|
}
|
|
258
256
|
try {
|
|
259
|
-
const constructor =
|
|
260
|
-
return (constructor
|
|
261
|
-
(typeof constructor === 'object' || typeof constructor === 'function') &&
|
|
257
|
+
const constructor = cause.constructor;
|
|
258
|
+
return (isObjectOrFunction(constructor) &&
|
|
262
259
|
readString(constructor, 'name') === 'NonRetryableError');
|
|
263
260
|
}
|
|
264
261
|
catch {
|
|
265
262
|
return false;
|
|
266
263
|
}
|
|
267
264
|
};
|
|
268
|
-
export const reportFailure = (event, details,
|
|
265
|
+
export const reportFailure = (event, details, cause) => {
|
|
269
266
|
try {
|
|
270
|
-
const stack =
|
|
271
|
-
(
|
|
272
|
-
? readString(error, 'stack')
|
|
267
|
+
const stack = isObjectOrFunction(cause)
|
|
268
|
+
? readString(cause, 'stack')
|
|
273
269
|
: undefined;
|
|
270
|
+
const logged = {
|
|
271
|
+
...serializeError(cause),
|
|
272
|
+
};
|
|
273
|
+
if (stack) {
|
|
274
|
+
logged.stack = stack;
|
|
275
|
+
}
|
|
274
276
|
console.error({
|
|
275
277
|
event,
|
|
276
278
|
...details,
|
|
277
|
-
error:
|
|
279
|
+
error: logged,
|
|
278
280
|
});
|
|
279
281
|
}
|
|
280
282
|
catch {
|
package/dist/fanout/index.d.ts
CHANGED
|
@@ -28,7 +28,7 @@ export type DurabilityFanoutMessage<Body = unknown> = {
|
|
|
28
28
|
deadLetter(): Promise<void>;
|
|
29
29
|
};
|
|
30
30
|
export type FanoutTarget<Body> = ExecutionPolicyOptions & ({
|
|
31
|
-
deliver(messages: DurabilityFanoutMessage<Body>[]):
|
|
31
|
+
deliver(messages: DurabilityFanoutMessage<Body>[]): void | Promise<void>;
|
|
32
32
|
/**
|
|
33
33
|
* Acks every message the consumer leaves unsettled when `deliver`
|
|
34
34
|
* returns without throwing, in one transaction instead of one call
|
package/dist/fanout/index.js
CHANGED
|
@@ -20,6 +20,7 @@ import { durabilityFanoutMigrations } from './migrations.js';
|
|
|
20
20
|
import { durabilityMemoMigrations } from '../memoize/migrations.js';
|
|
21
21
|
import { migrateCapability } from '../migrations.js';
|
|
22
22
|
import { assertPositiveInteger, createPolicyResolver, methodOptionsSchema, } from '../policy.js';
|
|
23
|
+
import { isFunction, isNonEmptyString } from '../predicates.js';
|
|
23
24
|
import { assertChannel, defaultChannel, engineFor, } from '../scheduler/index.js';
|
|
24
25
|
import { deserialize, serialize } from '../serialization.js';
|
|
25
26
|
import { claimAttempt, deleteAttempt, updateAttempt, } from '../storage.js';
|
|
@@ -116,9 +117,7 @@ export class DurabilityFanout {
|
|
|
116
117
|
}
|
|
117
118
|
__classPrivateFieldSet(this, _DurabilityFanout_policies, new Map(), "f");
|
|
118
119
|
for (const [id, target] of __classPrivateFieldGet(this, _DurabilityFanout_targets, "f")) {
|
|
119
|
-
if (!id ||
|
|
120
|
-
(typeof target.deliver !== 'function' &&
|
|
121
|
-
typeof target.storage !== 'function')) {
|
|
120
|
+
if (!id || (!isFunction(target.deliver) && !isFunction(target.storage))) {
|
|
122
121
|
throw new TypeError(`Invalid fanout target "${id}"`);
|
|
123
122
|
}
|
|
124
123
|
__classPrivateFieldGet(this, _DurabilityFanout_policies, "f").set(id, createPolicyResolver(config, { [id]: target }, methodOptionsSchema)(id));
|
|
@@ -150,6 +149,8 @@ export class DurabilityFanout {
|
|
|
150
149
|
* returns a function that detaches it.
|
|
151
150
|
*/
|
|
152
151
|
lifecycle(hook) {
|
|
152
|
+
// SAFETY: every event this instance emits spreads entity(claim), so it is
|
|
153
|
+
// a fanout_delivery event.
|
|
153
154
|
return __classPrivateFieldGet(this, _DurabilityFanout_lifecycle, "f").add(hook);
|
|
154
155
|
}
|
|
155
156
|
async load() {
|
|
@@ -175,10 +176,7 @@ export class DurabilityFanout {
|
|
|
175
176
|
entries = (Array.isArray(messages) ? messages : [messages]).map((message) => {
|
|
176
177
|
const id = message.id ?? crypto.randomUUID();
|
|
177
178
|
const key = message.deduplicationKey ?? id;
|
|
178
|
-
if (
|
|
179
|
-
!id ||
|
|
180
|
-
typeof key !== 'string' ||
|
|
181
|
-
!key) {
|
|
179
|
+
if (!isNonEmptyString(id) || !isNonEmptyString(key)) {
|
|
182
180
|
throw new FanoutEnqueueError('Message IDs and deduplication keys must be non-empty strings');
|
|
183
181
|
}
|
|
184
182
|
return { key, id, payload: serialize(message.body) };
|
|
@@ -284,7 +282,7 @@ export class DurabilityFanout {
|
|
|
284
282
|
const load = await this.load();
|
|
285
283
|
// Delayed first attempts are not due yet; the scheduler wakes for them.
|
|
286
284
|
if (registered.length > 0 && __classPrivateFieldGet(this, _DurabilityFanout_batchDelayMs, "f") === 0) {
|
|
287
|
-
const onError = (
|
|
285
|
+
const onError = (cause) => reportFailure('durability.fanout.failed', {}, cause);
|
|
288
286
|
const work = __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_runDue).call(this)
|
|
289
287
|
.then(() => __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").scheduleNextAlarm())
|
|
290
288
|
.catch(onError);
|
|
@@ -388,7 +386,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_channel = new WeakMa
|
|
|
388
386
|
attempt: claim.row.attempt,
|
|
389
387
|
});
|
|
390
388
|
}
|
|
391
|
-
let failure = new Error('Consumer returned without settling the message');
|
|
389
|
+
let failure = serializeError(new Error('Consumer returned without settling the message'));
|
|
392
390
|
try {
|
|
393
391
|
await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_deadline).call(this, async () => {
|
|
394
392
|
let invocationFailed = false;
|
|
@@ -439,7 +437,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_channel = new WeakMa
|
|
|
439
437
|
}, policy.attemptTimeoutMs);
|
|
440
438
|
}
|
|
441
439
|
catch (error) {
|
|
442
|
-
failure = error;
|
|
440
|
+
failure = serializeError(error);
|
|
443
441
|
}
|
|
444
442
|
finally {
|
|
445
443
|
for (const state of states) {
|
|
@@ -470,7 +468,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_channel = new WeakMa
|
|
|
470
468
|
}
|
|
471
469
|
state.outcome = 'retry';
|
|
472
470
|
// eslint-disable-next-line no-await-in-loop
|
|
473
|
-
await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_retry).call(this, state.claim, policy, undefined,
|
|
471
|
+
await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_retry).call(this, state.claim, policy, undefined, failure, startedAt);
|
|
474
472
|
}
|
|
475
473
|
}, _DurabilityFanout_ackUnsettled = function _DurabilityFanout_ackUnsettled(states, startedAt) {
|
|
476
474
|
const unsettled = states.filter((state) => state.outcome === undefined);
|
|
@@ -535,6 +533,8 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_channel = new WeakMa
|
|
|
535
533
|
return {
|
|
536
534
|
id: message.id,
|
|
537
535
|
...identity,
|
|
536
|
+
// SAFETY: enqueue is the only writer of message payloads, each
|
|
537
|
+
// serialized from a Body.
|
|
538
538
|
body: deserialize(message.payload),
|
|
539
539
|
enqueuedAt: message.created_at,
|
|
540
540
|
attempt: row.attempt,
|
|
@@ -644,6 +644,8 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_channel = new WeakMa
|
|
|
644
644
|
id: deliveryIdentity(row),
|
|
645
645
|
messageId: message.id,
|
|
646
646
|
target: row.target_id,
|
|
647
|
+
// SAFETY: enqueue is the only writer of message payloads, each
|
|
648
|
+
// serialized from a Body.
|
|
647
649
|
body: deserialize(message.payload),
|
|
648
650
|
enqueuedAt: message.created_at,
|
|
649
651
|
storedAt: timestamp,
|
|
@@ -706,7 +708,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_channel = new WeakMa
|
|
|
706
708
|
LIMIT ?`, __classPrivateFieldGet(this, _DurabilityFanout_channel, "f"), target, now, __classPrivateFieldGet(this, _DurabilityFanout_maxBatchSize, "f") - first.length)
|
|
707
709
|
.toArray());
|
|
708
710
|
return [...first, ...retries];
|
|
709
|
-
}, _DurabilityFanout_deadline =
|
|
710
|
-
|
|
711
|
+
}, _DurabilityFanout_deadline = function _DurabilityFanout_deadline(run, timeoutMs) {
|
|
712
|
+
return __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").timer.withTimeout(Promise.resolve().then(run), timeoutMs, () => new FanoutTimeoutError(timeoutMs));
|
|
711
713
|
};
|
|
712
714
|
traceMethods(DurabilityFanout.prototype, 'DurabilityFanout');
|
package/dist/lifecycle.d.ts
CHANGED
|
@@ -90,5 +90,6 @@ export declare const createLifecycleHooks: (emitter: (hook: LifecycleHook) => Em
|
|
|
90
90
|
export declare const createEmitter: <Event extends {
|
|
91
91
|
entityKind: string;
|
|
92
92
|
type: string;
|
|
93
|
+
id?: string;
|
|
93
94
|
} = DurabilityLifecycleEvent>(hook: ((event: Event) => void | Promise<void>) | undefined, waitUntil: ((promise: Promise<unknown>) => void) | undefined) => ((event: Event) => void);
|
|
94
95
|
export {};
|
package/dist/lifecycle.js
CHANGED
|
@@ -31,11 +31,11 @@ export const createEmitter = (hook, waitUntil) => {
|
|
|
31
31
|
return () => undefined;
|
|
32
32
|
}
|
|
33
33
|
return (event) => {
|
|
34
|
-
const report = (
|
|
34
|
+
const report = (cause) => reportFailure('durability.lifecycle_hook.failed', {
|
|
35
35
|
entityKind: event.entityKind,
|
|
36
36
|
lifecycleType: event.type,
|
|
37
37
|
entityId: 'id' in event ? event.id : 'durability',
|
|
38
|
-
},
|
|
38
|
+
}, cause);
|
|
39
39
|
try {
|
|
40
40
|
const result = hook(event);
|
|
41
41
|
if (result === undefined) {
|
package/dist/log/index.js
CHANGED
|
@@ -17,6 +17,7 @@ import { RoutingLoad, } from '../routing/load.js';
|
|
|
17
17
|
import { durabilityLogLeaseMigrations, durabilityLogMigrations, } from './migrations.js';
|
|
18
18
|
import { migrateCapability } from '../migrations.js';
|
|
19
19
|
import { assertPositiveInteger } from '../policy.js';
|
|
20
|
+
import { isNonEmptyString } from '../predicates.js';
|
|
20
21
|
import { assertChannel, defaultChannel, engineFor, } from '../scheduler/index.js';
|
|
21
22
|
import { deserialize, serialize } from '../serialization.js';
|
|
22
23
|
const logRecordRowSchema = v.object({
|
|
@@ -497,7 +498,7 @@ export class DurabilityLog {
|
|
|
497
498
|
lastOffset: last.offset,
|
|
498
499
|
records,
|
|
499
500
|
});
|
|
500
|
-
if (
|
|
501
|
+
if (!isNonEmptyString(locator)) {
|
|
501
502
|
throw new TypeError('Cold storage must return a non-empty locator');
|
|
502
503
|
}
|
|
503
504
|
// Indexed before deletion: a crash in between leaves the segment
|
|
@@ -683,6 +684,8 @@ async function _DurabilityLog_rehydrate(from, limit, bounds) {
|
|
|
683
684
|
return {
|
|
684
685
|
offset: row.offset,
|
|
685
686
|
deduplicationKey: row.dedup_key,
|
|
687
|
+
// SAFETY: append is the only writer of this channel's payloads, each
|
|
688
|
+
// serialized from a Body.
|
|
686
689
|
body: deserialize(row.payload),
|
|
687
690
|
appendedAt: row.appended_at,
|
|
688
691
|
};
|
|
@@ -768,7 +771,7 @@ async function _DurabilityLog_between(first, last) {
|
|
|
768
771
|
};
|
|
769
772
|
traceMethods(DurabilityLog.prototype, 'DurabilityLog');
|
|
770
773
|
const assertConsumer = (consumer) => {
|
|
771
|
-
if (
|
|
774
|
+
if (!isNonEmptyString(consumer)) {
|
|
772
775
|
throw new LogAppendError('Consumer must be a non-empty string');
|
|
773
776
|
}
|
|
774
777
|
};
|