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.
Files changed (53) hide show
  1. package/README.md +23 -14
  2. package/dist/alarms/index.d.ts +1 -1
  3. package/dist/alarms/index.js +6 -3
  4. package/dist/dev.d.ts +7 -3
  5. package/dist/dev.js +17 -11
  6. package/dist/durable-object-target.js +8 -4
  7. package/dist/errors.d.ts +13 -7
  8. package/dist/errors.js +34 -32
  9. package/dist/fanout/index.d.ts +1 -1
  10. package/dist/fanout/index.js +15 -13
  11. package/dist/lifecycle.d.ts +1 -0
  12. package/dist/lifecycle.js +2 -2
  13. package/dist/log/index.js +5 -2
  14. package/dist/memoize/index.js +6 -1
  15. package/dist/operations/index.js +8 -4
  16. package/dist/outbox/index.d.ts +1 -1
  17. package/dist/outbox/index.js +7 -4
  18. package/dist/policy.d.ts +1 -1
  19. package/dist/policy.js +2 -1
  20. package/dist/predicates.d.ts +9 -0
  21. package/dist/predicates.js +10 -0
  22. package/dist/routing/client.js +3 -4
  23. package/dist/routing/index.d.ts +1 -1
  24. package/dist/routing/index.js +14 -10
  25. package/dist/schedule/index.d.ts +2 -2
  26. package/dist/schedule/index.js +16 -12
  27. package/dist/scheduler/index.d.ts +16 -13
  28. package/dist/scheduler/index.js +39 -33
  29. package/dist/semaphore/client.js +2 -1
  30. package/dist/semaphore/index.d.ts +1 -1
  31. package/dist/semaphore/index.js +10 -5
  32. package/dist/semaphore/leases.d.ts +3 -2
  33. package/dist/semaphore/leases.js +3 -2
  34. package/dist/semaphore/queue-store.js +2 -1
  35. package/dist/semaphore/queue.d.ts +1 -1
  36. package/dist/semaphore/queue.js +34 -22
  37. package/dist/semaphore/server.js +31 -22
  38. package/dist/serialization.d.ts +3 -2
  39. package/dist/serialization.js +16 -13
  40. package/dist/socket/client.d.ts +21 -7
  41. package/dist/socket/client.js +12 -5
  42. package/dist/socket/index.d.ts +20 -13
  43. package/dist/socket/index.js +40 -18
  44. package/dist/socket/protocol.d.ts +37 -17
  45. package/dist/socket/protocol.js +30 -36
  46. package/dist/topology/client.js +9 -6
  47. package/dist/topology/index.d.ts +3 -3
  48. package/dist/topology/index.js +38 -33
  49. package/dist/topology/snapshot.d.ts +6 -5
  50. package/dist/topology/snapshot.js +5 -2
  51. package/dist/tracker/index.js +10 -2
  52. package/dist/tracker/source.d.ts +6 -2
  53. package/package.json +2 -2
@@ -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
- return {
65
- attemptTimeoutMs: Math.min(timeoutMs * 2, maxTimeoutMs),
66
- ...(delay === undefined ? {} : { retries: { delay } }),
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 (typeof group !== 'string' || group.length === 0) {
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
- typeof Reflect.get(value, 'then') === 'function';
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) => v.parse(membersSchema, JSON.parse(row.members));
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
- (typeof publisher.write !== 'function' ||
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 || typeof channel.deliver !== 'function') {
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
- // The outbox only emits outbox events, which is all this hook accepts.
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 = (error) => reportFailure('durability.topology.restage_failed', { group }, error);
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 === null || typeof draft !== 'object') {
400
+ if (!isObject(draft)) {
392
401
  throw new TopologyError('update must return a draft object');
393
402
  }
394
- const members = Reflect.get(draft, 'members');
395
- const states = Reflect.get(draft, '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 === null ||
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
- return {
425
- id,
426
- state,
427
- ...(locationHint === undefined ? {} : { locationHint }),
428
- ...(meta === undefined ? {} : { meta }),
429
- joinedAt: joinedAt.get(id) ?? now,
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<import("../serialization.js").Json, v.ErrorMessage<v.CustomIssue> | undefined>, undefined>;
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 locationHint: v.OptionalSchema<v.PicklistSchema<readonly ["wnam", "enam", "sam", "weur", "eeur", "apac", "oc", "afr", "me"], undefined>, undefined>;
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
- locationHint?: "wnam" | "enam" | "sam" | "weur" | "eeur" | "apac" | "oc" | "afr" | "me" | undefined;
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
- return snapshot;
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
  };
@@ -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
- return __classPrivateFieldGet(this, _DurabilityTracker_instances, "m", _DurabilityTracker_handle).call(this, resolved, itemFor(key, record));
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 = (error) => finish(() => reject(error));
159
+ const fail = (cause) => finish(() => reject(cause));
152
160
  const resolveIfSettled = (result) => {
153
161
  if (result.status !== 'pending') {
154
162
  finish(() => resolve(result));
@@ -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
- export declare const registerTrackedSource: (owner: object, source: UntypedSource) => void;
89
- export declare const trackedSourceOf: (owner: object) => UntypedSource | undefined;
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.0",
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.6.2"
68
+ "@durability/transforms": "^0.7.0"
69
69
  },
70
70
  "peerDependencies": {
71
71
  "@cloudflare/workers-types": "^4.20260702.1"