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/dist/topology/index.js
CHANGED
|
@@ -16,8 +16,9 @@ import { durabilityTopologyMigrations } from './migrations.js';
|
|
|
16
16
|
import { migrateCapability } from '../migrations.js';
|
|
17
17
|
import { DurabilityOutbox, discardWithin, publishNow, stageWithin, } from '../outbox/index.js';
|
|
18
18
|
import { assertPositiveInteger } from '../policy.js';
|
|
19
|
+
import { isFunction, isNonEmptyString, isObject } from '../predicates.js';
|
|
19
20
|
import { assertChannel, defaultChannel, DurabilityScheduler, engineFor, } from '../scheduler/index.js';
|
|
20
|
-
import { canonical, deserialize, serialize } from '../serialization.js';
|
|
21
|
+
import { canonical, deserialize, serialize, } from '../serialization.js';
|
|
21
22
|
import { TopologyClient } from './client.js';
|
|
22
23
|
import { encodeSnapshot, memberInputSchema, membersSchema, } from './snapshot.js';
|
|
23
24
|
const outboxChannelPrefix = 'durability.topology';
|
|
@@ -61,10 +62,11 @@ const timeoutOf = (options, fallback) => {
|
|
|
61
62
|
*/
|
|
62
63
|
const outboxOptions = (timeoutMs, options, fallback) => {
|
|
63
64
|
const delay = options?.retries?.delay ?? fallback.retries?.delay;
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
}
|
|
65
|
+
const outboxConfig = { attemptTimeoutMs: Math.min(timeoutMs * 2, maxTimeoutMs) };
|
|
66
|
+
if (delay !== undefined) {
|
|
67
|
+
outboxConfig.retries = { delay };
|
|
68
|
+
}
|
|
69
|
+
return outboxConfig;
|
|
68
70
|
};
|
|
69
71
|
/**
|
|
70
72
|
* How long after its timeout an abandoned publisher write is assumed able to
|
|
@@ -85,14 +87,15 @@ const outstandingWritesUntil = (sql, ownerChannel, group, now) => {
|
|
|
85
87
|
return until ?? undefined;
|
|
86
88
|
};
|
|
87
89
|
const assertGroup = (group) => {
|
|
88
|
-
if (
|
|
90
|
+
if (!isNonEmptyString(group)) {
|
|
89
91
|
throw new TopologyError('Group must be a non-empty string');
|
|
90
92
|
}
|
|
91
93
|
};
|
|
92
94
|
const deliveryKey = (group, member) => JSON.stringify([group, member]);
|
|
93
95
|
const isThenable = (value) => value !== null &&
|
|
94
96
|
typeof value === 'object' &&
|
|
95
|
-
|
|
97
|
+
'then' in value &&
|
|
98
|
+
typeof value.then === 'function';
|
|
96
99
|
const readGroup = (sql, ownerChannel, group) => v.parse(v.optional(groupRowSchema), sql
|
|
97
100
|
.exec(`SELECT group_id, version, members, deleted
|
|
98
101
|
FROM durability_topology_groups
|
|
@@ -102,7 +105,11 @@ const readStates = (sql, ownerChannel, group) => v.parse(v.array(stateRowSchema)
|
|
|
102
105
|
.exec(`SELECT channel, value FROM durability_topology_states
|
|
103
106
|
WHERE owner_channel = ? AND group_id = ?`, ownerChannel, group)
|
|
104
107
|
.toArray());
|
|
105
|
-
const parseMembers = (row) =>
|
|
108
|
+
const parseMembers = (row) => {
|
|
109
|
+
const members = v.parse(membersSchema, JSON.parse(row.members));
|
|
110
|
+
// SAFETY: `meta` is validated only as JSON; this coordinator wrote it from a `TopologyMemberInput<Meta>`.
|
|
111
|
+
return members;
|
|
112
|
+
};
|
|
106
113
|
const inRole = (member, role) => role === 'read' || member.state === 'active';
|
|
107
114
|
/**
|
|
108
115
|
* Experimental. Holds the membership of shard groups inside one coordinator
|
|
@@ -132,8 +139,7 @@ export class DurabilityTopology {
|
|
|
132
139
|
__classPrivateFieldGet(this, _DurabilityTopology_engine, "f").migrateSchema('topology', durabilityTopologyMigrations);
|
|
133
140
|
const publisher = config.publish;
|
|
134
141
|
if (publisher !== undefined &&
|
|
135
|
-
(
|
|
136
|
-
typeof publisher.delete !== 'function')) {
|
|
142
|
+
(!isFunction(publisher.write) || !isFunction(publisher.delete))) {
|
|
137
143
|
throw new TopologyError('publish needs write and delete functions');
|
|
138
144
|
}
|
|
139
145
|
const publication = publisher === undefined
|
|
@@ -141,7 +147,7 @@ export class DurabilityTopology {
|
|
|
141
147
|
: { publisher, timeoutMs: timeoutOf(publisher, config) };
|
|
142
148
|
const states = config.states ?? {};
|
|
143
149
|
const channels = Object.entries(states).map(([name, channel]) => {
|
|
144
|
-
if (!name ||
|
|
150
|
+
if (!name || !isFunction(channel.deliver)) {
|
|
145
151
|
throw new TopologyError(`Invalid topology channel "${name}"`);
|
|
146
152
|
}
|
|
147
153
|
return {
|
|
@@ -153,7 +159,8 @@ export class DurabilityTopology {
|
|
|
153
159
|
// Validate before claiming so config validation failures leave the channel
|
|
154
160
|
// free. Even without outboxes, an instance still owns its channel's groups.
|
|
155
161
|
__classPrivateFieldGet(this, _DurabilityTopology_engine, "f").claimChannel('durability_topology_groups', ownerChannel, 'DurabilityTopology');
|
|
156
|
-
//
|
|
162
|
+
// SAFETY: the outbox only emits outbox events, which is all this hook
|
|
163
|
+
// accepts.
|
|
157
164
|
const onLifecycleEvent = config.onLifecycleEvent;
|
|
158
165
|
const lifecycle = onLifecycleEvent === undefined ? {} : { onLifecycleEvent };
|
|
159
166
|
if (publication !== undefined) {
|
|
@@ -205,6 +212,8 @@ export class DurabilityTopology {
|
|
|
205
212
|
const live = row?.deleted === 0 ? row : undefined;
|
|
206
213
|
const before = live ? parseMembers(live) : [];
|
|
207
214
|
const stateRows = readStates(sql, __classPrivateFieldGet(this, _DurabilityTopology_ownerChannel, "f"), group);
|
|
215
|
+
// SAFETY: #writeStates is the only writer of state rows, storing each
|
|
216
|
+
// channel's value from a Partial<States>.
|
|
208
217
|
const states = Object.fromEntries(stateRows.map((state) => [state.channel, deserialize(state.value)]));
|
|
209
218
|
// A copy, so an updater that mutates `current` cannot make a change look like a no-op.
|
|
210
219
|
const draft = next({ members: structuredClone(before), states });
|
|
@@ -344,7 +353,7 @@ async function _DurabilityTopology_publishSnapshots(publisher, entries, timeoutM
|
|
|
344
353
|
}
|
|
345
354
|
}));
|
|
346
355
|
}, _DurabilityTopology_settleLate = function _DurabilityTopology_settleLate(group, id, write) {
|
|
347
|
-
const onError = (
|
|
356
|
+
const onError = (cause) => reportFailure('durability.topology.restage_failed', { group }, cause);
|
|
348
357
|
const settled = write
|
|
349
358
|
.then(() => undefined, () => undefined)
|
|
350
359
|
.then(() => __classPrivateFieldGet(this, _DurabilityTopology_engine, "f").transaction((sql) => {
|
|
@@ -388,23 +397,18 @@ async function _DurabilityTopology_publishSnapshots(publisher, entries, timeoutM
|
|
|
388
397
|
}
|
|
389
398
|
}));
|
|
390
399
|
}, _DurabilityTopology_parseDraft = function _DurabilityTopology_parseDraft(draft) {
|
|
391
|
-
if (draft
|
|
400
|
+
if (!isObject(draft)) {
|
|
392
401
|
throw new TopologyError('update must return a draft object');
|
|
393
402
|
}
|
|
394
|
-
const members =
|
|
395
|
-
const states =
|
|
403
|
+
const members = 'members' in draft ? draft.members : undefined;
|
|
404
|
+
const states = ('states' in draft ? draft.states : undefined) ?? {};
|
|
396
405
|
if (members !== undefined && !Array.isArray(members)) {
|
|
397
406
|
throw new TopologyError('Draft members must be an array');
|
|
398
407
|
}
|
|
399
|
-
if (states
|
|
400
|
-
typeof states !== 'object' ||
|
|
401
|
-
Array.isArray(states)) {
|
|
408
|
+
if (!isObject(states) || Array.isArray(states)) {
|
|
402
409
|
throw new TopologyError('Draft states must be an object');
|
|
403
410
|
}
|
|
404
|
-
return {
|
|
405
|
-
members: members,
|
|
406
|
-
states: states,
|
|
407
|
-
};
|
|
411
|
+
return { members, states };
|
|
408
412
|
}, _DurabilityTopology_normalize = function _DurabilityTopology_normalize(inputs, before, now) {
|
|
409
413
|
if (inputs.length === 0) {
|
|
410
414
|
throw new TopologyError('A group needs at least one member; use delete() to remove it');
|
|
@@ -421,13 +425,16 @@ async function _DurabilityTopology_publishSnapshots(publisher, entries, timeoutM
|
|
|
421
425
|
throw new TopologyError(`Duplicate member "${id}"`);
|
|
422
426
|
}
|
|
423
427
|
seen.add(id);
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
}
|
|
428
|
+
const member = { id, state };
|
|
429
|
+
if (locationHint !== undefined) {
|
|
430
|
+
member.locationHint = locationHint;
|
|
431
|
+
}
|
|
432
|
+
if (meta !== undefined) {
|
|
433
|
+
member.meta = meta;
|
|
434
|
+
}
|
|
435
|
+
member.joinedAt = joinedAt.get(id) ?? now;
|
|
436
|
+
// SAFETY: `meta` is the input's Meta, which passed jsonSchema unchanged.
|
|
437
|
+
return member;
|
|
431
438
|
});
|
|
432
439
|
return members.sort((a, b) => (a.id < b.id ? -1 : 1));
|
|
433
440
|
}, _DurabilityTopology_writeStates = function _DurabilityTopology_writeStates(sql, group, changes, current) {
|
|
@@ -459,9 +466,7 @@ async function _DurabilityTopology_publishSnapshots(publisher, entries, timeoutM
|
|
|
459
466
|
row.value,
|
|
460
467
|
]));
|
|
461
468
|
for (const [name, channel] of __classPrivateFieldGet(this, _DurabilityTopology_channels, "f")) {
|
|
462
|
-
const previous = new Set(before
|
|
463
|
-
.filter((member) => inRole(member, channel.role))
|
|
464
|
-
.map(({ id }) => id));
|
|
469
|
+
const previous = new Set(before.flatMap((member) => inRole(member, channel.role) ? [member.id] : []));
|
|
465
470
|
const targets = after.filter((member) => inRole(member, channel.role));
|
|
466
471
|
const kept = new Set(targets.map(({ id }) => id));
|
|
467
472
|
for (const id of previous) {
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import * as v from 'valibot';
|
|
2
|
+
import { type Json } from '../serialization.js';
|
|
2
3
|
/** `active` members are in the write and read sets; `draining` members only in the read set. */
|
|
3
4
|
export type TopologyMemberState = 'active' | 'draining';
|
|
4
5
|
type MetaField<Meta> = undefined extends Meta ? {
|
|
@@ -29,20 +30,20 @@ export declare const memberInputSchema: v.ObjectSchema<{
|
|
|
29
30
|
readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
|
|
30
31
|
readonly state: v.PicklistSchema<["active", "draining"], undefined>;
|
|
31
32
|
readonly locationHint: v.OptionalSchema<v.PicklistSchema<readonly ["wnam", "enam", "sam", "weur", "eeur", "apac", "oc", "afr", "me"], undefined>, undefined>;
|
|
32
|
-
readonly meta: v.OptionalSchema<v.CustomSchema<
|
|
33
|
+
readonly meta: v.OptionalSchema<v.CustomSchema<Json, v.ErrorMessage<v.CustomIssue> | undefined>, undefined>;
|
|
33
34
|
}, undefined>;
|
|
34
35
|
export declare const membersSchema: v.SchemaWithPipe<readonly [v.ArraySchema<v.ObjectSchema<{
|
|
36
|
+
readonly locationHint: v.ExactOptionalSchema<v.PicklistSchema<readonly ["wnam", "enam", "sam", "weur", "eeur", "apac", "oc", "afr", "me"], undefined>, undefined>;
|
|
35
37
|
readonly joinedAt: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
|
|
36
38
|
readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
|
|
37
39
|
readonly state: v.PicklistSchema<["active", "draining"], undefined>;
|
|
38
|
-
readonly
|
|
39
|
-
readonly meta: v.OptionalSchema<v.CustomSchema<import("../serialization.js").Json, v.ErrorMessage<v.CustomIssue> | undefined>, undefined>;
|
|
40
|
+
readonly meta: v.OptionalSchema<v.CustomSchema<Json, v.ErrorMessage<v.CustomIssue> | undefined>, undefined>;
|
|
40
41
|
}, undefined>, undefined>, v.CheckAction<{
|
|
42
|
+
locationHint?: "wnam" | "enam" | "sam" | "weur" | "eeur" | "apac" | "oc" | "afr" | "me";
|
|
41
43
|
joinedAt: number;
|
|
42
44
|
id: string;
|
|
43
45
|
state: "active" | "draining";
|
|
44
|
-
|
|
45
|
-
meta?: import("../serialization.js").Json | undefined;
|
|
46
|
+
meta?: Json | undefined;
|
|
46
47
|
}[], "Members must be sorted by ID and unique">]>;
|
|
47
48
|
export declare const encodeSnapshot: <Meta>(snapshot: TopologySnapshot<Meta>) => string;
|
|
48
49
|
/** The stored value crossed a trust boundary, so every field is re-validated. */
|
|
@@ -20,6 +20,7 @@ export const memberInputSchema = v.object({
|
|
|
20
20
|
});
|
|
21
21
|
const memberSchema = v.object({
|
|
22
22
|
...memberInputSchema.entries,
|
|
23
|
+
locationHint: v.exactOptional(v.picklist(locationHints)),
|
|
23
24
|
joinedAt: v.pipe(v.number(), v.safeInteger(), v.minValue(0)),
|
|
24
25
|
});
|
|
25
26
|
export const membersSchema = v.pipe(v.array(memberSchema), v.check((members) => members.every((member, index) => index === 0 || members[index - 1].id < member.id), 'Members must be sorted by ID and unique'));
|
|
@@ -33,6 +34,8 @@ const encodedSchema = v.object({
|
|
|
33
34
|
export const encodeSnapshot = (snapshot) => JSON.stringify({ format: 1, ...snapshot });
|
|
34
35
|
/** The stored value crossed a trust boundary, so every field is re-validated. */
|
|
35
36
|
export const decodeSnapshot = (encoded) => {
|
|
36
|
-
const { format: _format, ...snapshot } = v.parse(encodedSchema, JSON.parse(encoded));
|
|
37
|
-
|
|
37
|
+
const { format: _format, members, ...snapshot } = v.parse(encodedSchema, JSON.parse(encoded));
|
|
38
|
+
const decoded = members;
|
|
39
|
+
// SAFETY: `meta` is validated only as JSON; the coordinator wrote it from the caller's `TopologyMemberInput<Meta>`.
|
|
40
|
+
return { ...snapshot, members: decoded };
|
|
38
41
|
};
|
package/dist/tracker/index.js
CHANGED
|
@@ -59,6 +59,8 @@ export class DurabilityTracker {
|
|
|
59
59
|
_DurabilityTracker_timer.set(this, new SharedTimer());
|
|
60
60
|
__classPrivateFieldSet(this, _DurabilityTracker_sources, Object.entries(config.sources).map(([key, input]) => [
|
|
61
61
|
key,
|
|
62
|
+
// SAFETY: Durability and DurabilityAlarms register a source in their
|
|
63
|
+
// constructors, so an input without one is a custom UntypedSource.
|
|
62
64
|
trackedSourceOf(input) ?? input,
|
|
63
65
|
]), "f");
|
|
64
66
|
}
|
|
@@ -67,6 +69,8 @@ export class DurabilityTracker {
|
|
|
67
69
|
const { found, cursor } = await __classPrivateFieldGet(this, _DurabilityTracker_instances, "m", _DurabilityTracker_collect).call(this, query);
|
|
68
70
|
const items = found.map(({ source, item }) => __classPrivateFieldGet(this, _DurabilityTracker_instances, "m", _DurabilityTracker_handle).call(this, source, item));
|
|
69
71
|
const page = cursor === undefined ? { items } : { items, cursor };
|
|
72
|
+
// SAFETY: each item is a record of the source registered under its
|
|
73
|
+
// `source` key, so its name and result match Sources[source].
|
|
70
74
|
return page;
|
|
71
75
|
}
|
|
72
76
|
/**
|
|
@@ -77,6 +81,8 @@ export class DurabilityTracker {
|
|
|
77
81
|
const { found, cursor } = await __classPrivateFieldGet(this, _DurabilityTracker_instances, "m", _DurabilityTracker_collect).call(this, query);
|
|
78
82
|
const records = found.map(({ item }) => item);
|
|
79
83
|
const page = cursor === undefined ? { records } : { records, cursor };
|
|
84
|
+
// SAFETY: each record comes from the source registered under its
|
|
85
|
+
// `source` key, so its name and result match Sources[source].
|
|
80
86
|
return page;
|
|
81
87
|
}
|
|
82
88
|
/** Reacquires a handle by id, for example after an RPC disconnect. */
|
|
@@ -86,7 +92,9 @@ export class DurabilityTracker {
|
|
|
86
92
|
if (!record) {
|
|
87
93
|
return undefined;
|
|
88
94
|
}
|
|
89
|
-
|
|
95
|
+
const handle = __classPrivateFieldGet(this, _DurabilityTracker_instances, "m", _DurabilityTracker_handle).call(this, resolved, itemFor(key, record));
|
|
96
|
+
// SAFETY: `record` was read from the source registered under `source`.
|
|
97
|
+
return handle;
|
|
90
98
|
}
|
|
91
99
|
}
|
|
92
100
|
_DurabilityTracker_sources = new WeakMap(), _DurabilityTracker_timer = new WeakMap(), _DurabilityTracker_instances = new WeakSet(), _DurabilityTracker_collect = async function _DurabilityTracker_collect(query) {
|
|
@@ -148,7 +156,7 @@ _DurabilityTracker_sources = new WeakMap(), _DurabilityTracker_timer = new WeakM
|
|
|
148
156
|
unwatch?.();
|
|
149
157
|
settle();
|
|
150
158
|
};
|
|
151
|
-
const fail = (
|
|
159
|
+
const fail = (cause) => finish(() => reject(cause));
|
|
152
160
|
const resolveIfSettled = (result) => {
|
|
153
161
|
if (result.status !== 'pending') {
|
|
154
162
|
finish(() => resolve(result));
|
package/dist/tracker/source.d.ts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import type { AnyDurabilityAlarms } from '../alarms/index.js';
|
|
2
|
+
import type { AnyDurability } from '../operations/index.js';
|
|
1
3
|
/** Result types keyed by record name: operation, alarm name, or custom names. */
|
|
2
4
|
export type TrackedResults = Record<string, unknown>;
|
|
3
5
|
export type TrackedStatus = 'pending' | 'completed' | 'failed';
|
|
@@ -85,5 +87,7 @@ export type UntypedSource = {
|
|
|
85
87
|
}>;
|
|
86
88
|
watch?(id: string, listener: (settled?: UntypedRecord) => void): () => void;
|
|
87
89
|
};
|
|
88
|
-
|
|
89
|
-
export declare const
|
|
90
|
+
type BuiltInSourceOwner = AnyDurability | AnyDurabilityAlarms;
|
|
91
|
+
export declare const registerTrackedSource: (owner: BuiltInSourceOwner, source: UntypedSource) => void;
|
|
92
|
+
export declare const trackedSourceOf: (owner: BuiltInSourceOwner | UntypedSource) => UntypedSource | undefined;
|
|
93
|
+
export {};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "durability",
|
|
3
|
-
"version": "5.
|
|
3
|
+
"version": "5.4.0",
|
|
4
4
|
"description": "Alarm-backed durable operations and typed WebSocket sync for Cloudflare Durable Objects",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "ISC",
|
|
@@ -65,7 +65,7 @@
|
|
|
65
65
|
"@standard-schema/spec": "^1.1.0",
|
|
66
66
|
"valibot": "^1.5.0",
|
|
67
67
|
"@durability/storage": "^0.1.1",
|
|
68
|
-
"@durability/transforms": "^0.
|
|
68
|
+
"@durability/transforms": "^0.7.0"
|
|
69
69
|
},
|
|
70
70
|
"peerDependencies": {
|
|
71
71
|
"@cloudflare/workers-types": "^4.20260702.1"
|