durability 5.2.1 → 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 (56) hide show
  1. package/README.md +42 -18
  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 -26
  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/migrations.js +37 -37
  16. package/dist/operations/index.js +8 -4
  17. package/dist/outbox/index.d.ts +1 -1
  18. package/dist/outbox/index.js +7 -17
  19. package/dist/policy.d.ts +1 -1
  20. package/dist/policy.js +2 -1
  21. package/dist/predicates.d.ts +9 -0
  22. package/dist/predicates.js +10 -0
  23. package/dist/routing/client.js +3 -4
  24. package/dist/routing/index.d.ts +1 -1
  25. package/dist/routing/index.js +14 -10
  26. package/dist/schedule/index.d.ts +15 -3
  27. package/dist/schedule/index.js +55 -36
  28. package/dist/scheduler/index.d.ts +35 -14
  29. package/dist/scheduler/index.js +78 -74
  30. package/dist/semaphore/client.js +2 -1
  31. package/dist/semaphore/index.d.ts +1 -1
  32. package/dist/semaphore/index.js +10 -5
  33. package/dist/semaphore/leases.d.ts +3 -2
  34. package/dist/semaphore/leases.js +3 -2
  35. package/dist/semaphore/queue-store.js +2 -1
  36. package/dist/semaphore/queue.d.ts +1 -1
  37. package/dist/semaphore/queue.js +36 -37
  38. package/dist/semaphore/server.js +50 -32
  39. package/dist/serialization.d.ts +3 -2
  40. package/dist/serialization.js +16 -13
  41. package/dist/shared-timer.d.ts +27 -0
  42. package/dist/shared-timer.js +191 -0
  43. package/dist/socket/client.d.ts +21 -7
  44. package/dist/socket/client.js +37 -27
  45. package/dist/socket/index.d.ts +20 -13
  46. package/dist/socket/index.js +40 -18
  47. package/dist/socket/protocol.d.ts +37 -17
  48. package/dist/socket/protocol.js +30 -36
  49. package/dist/topology/client.js +36 -19
  50. package/dist/topology/index.d.ts +3 -3
  51. package/dist/topology/index.js +40 -49
  52. package/dist/topology/snapshot.d.ts +6 -5
  53. package/dist/topology/snapshot.js +5 -2
  54. package/dist/tracker/index.js +18 -7
  55. package/dist/tracker/source.d.ts +6 -2
  56. package/package.json +2 -2
@@ -12,6 +12,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
12
12
  var _TopologyClient_instances, _TopologyClient_config, _TopologyClient_readTimeoutMs, _TopologyClient_ttlMs, _TopologyClient_negativeTtlMs, _TopologyClient_cache, _TopologyClient_inflight, _TopologyClient_load, _TopologyClient_read, _TopologyClient_fallback, _TopologyClient_remember;
13
13
  import { TopologyUnavailableError, } from '../errors.js';
14
14
  import { assertPositiveInteger } from '../policy.js';
15
+ import { isFunction } from '../predicates.js';
15
16
  import { decodeSnapshot, } from './snapshot.js';
16
17
  // High-cardinality groups (one per tenant) must not grow an isolate without bound; the least recently used go first.
17
18
  const maxCachedGroups = 1024;
@@ -28,7 +29,7 @@ export class TopologyClient {
28
29
  _TopologyClient_negativeTtlMs.set(this, void 0);
29
30
  _TopologyClient_cache.set(this, new Map());
30
31
  _TopologyClient_inflight.set(this, new Map());
31
- if (typeof config.read !== 'function') {
32
+ if (!isFunction(config.read)) {
32
33
  throw new TypeError('A topology client needs a read function');
33
34
  }
34
35
  __classPrivateFieldSet(this, _TopologyClient_readTimeoutMs, config.readTimeoutMs ?? 1000, "f");
@@ -74,33 +75,49 @@ _TopologyClient_config = new WeakMap(), _TopologyClient_readTimeoutMs = new Weak
74
75
  const previous = __classPrivateFieldGet(this, _TopologyClient_cache, "f").get(group);
75
76
  const result = await __classPrivateFieldGet(this, _TopologyClient_instances, "m", _TopologyClient_read).call(this, group);
76
77
  const now = Date.now();
78
+ let failure;
77
79
  if ('snapshot' in result) {
78
80
  const { snapshot } = result;
79
81
  // The store is eventually consistent; a lagging replica must not move readers backwards.
80
82
  // Versions only compare within one coordinator: a group moved to another starts over.
81
- const keep = previous?.view !== undefined &&
82
- previous.view.coordinator === snapshot.coordinator &&
83
- previous.view.version > snapshot.version;
84
- const view = keep
85
- ? previous.view
86
- : { ...snapshot, source: 'published', fetchedAt: now };
87
- const expiresAt = now + jittered(__classPrivateFieldGet(this, _TopologyClient_ttlMs, "f"));
88
- __classPrivateFieldGet(this, _TopologyClient_instances, "m", _TopologyClient_remember).call(this, group, {
89
- view,
90
- expiresAt,
91
- staleUntil: expiresAt + (__classPrivateFieldGet(this, _TopologyClient_config, "f").staleIfErrorMs ?? 0),
92
- });
93
- return view;
83
+ const outdated = previous?.newestSeen !== undefined &&
84
+ previous.newestSeen.coordinator === snapshot.coordinator &&
85
+ previous.newestSeen.version > snapshot.version;
86
+ if (!outdated || previous.view !== undefined) {
87
+ const view = outdated
88
+ ? previous.view
89
+ : { ...snapshot, source: 'published', fetchedAt: now };
90
+ const expiresAt = now + jittered(__classPrivateFieldGet(this, _TopologyClient_ttlMs, "f"));
91
+ __classPrivateFieldGet(this, _TopologyClient_instances, "m", _TopologyClient_remember).call(this, group, {
92
+ view,
93
+ newestSeen: {
94
+ coordinator: view.coordinator,
95
+ version: view.version,
96
+ },
97
+ expiresAt,
98
+ staleUntil: expiresAt + (__classPrivateFieldGet(this, _TopologyClient_config, "f").staleIfErrorMs ?? 0),
99
+ });
100
+ return view;
101
+ }
102
+ // Only a failed read leaves a newer version seen without a view, so the
103
+ // older snapshot answers the same way that read did.
104
+ failure = previous.failure;
105
+ }
106
+ else {
107
+ failure = result.failure;
94
108
  }
95
109
  const entry = {
96
- // A missing group is not an error, so nothing stale may be served for it.
97
- ...(result.failure.reason === 'missing' || !previous?.view
98
- ? {}
99
- : { view: previous.view }),
100
110
  staleUntil: previous?.staleUntil ?? 0,
101
111
  expiresAt: now + jittered(__classPrivateFieldGet(this, _TopologyClient_negativeTtlMs, "f")),
102
- failure: result.failure,
112
+ failure,
103
113
  };
114
+ // A missing group is not an error, so nothing stale may be served for it.
115
+ if (failure.reason !== 'missing' && previous?.view) {
116
+ entry.view = previous.view;
117
+ }
118
+ if (previous?.newestSeen) {
119
+ entry.newestSeen = previous.newestSeen;
120
+ }
104
121
  __classPrivateFieldGet(this, _TopologyClient_instances, "m", _TopologyClient_remember).call(this, group, entry);
105
122
  return __classPrivateFieldGet(this, _TopologyClient_instances, "m", _TopologyClient_fallback).call(this, group, entry);
106
123
  }, _TopologyClient_read = async function _TopologyClient_read(group) {
@@ -23,13 +23,13 @@ export type TopologyStateUpdate<Value> = {
23
23
  };
24
24
  export type TopologyPublisher<Meta> = TopologyRetryOptions & {
25
25
  /** Must be idempotent. Store `encoded` as is: it is what the client reads. */
26
- write(snapshot: TopologySnapshot<Meta>, encoded: string): Promise<unknown>;
27
- delete(group: string, version: number): Promise<unknown>;
26
+ write(snapshot: TopologySnapshot<Meta>, encoded: string): Promise<void>;
27
+ delete(group: string, version: number): Promise<void>;
28
28
  };
29
29
  export type TopologyChannel<Value, Meta> = TopologyRetryOptions & {
30
30
  /** Defaults to `write`. */
31
31
  members?: TopologyRole;
32
- deliver(member: TopologyMember<Meta>, update: TopologyStateUpdate<Value>): unknown;
32
+ deliver(member: TopologyMember<Meta>, update: TopologyStateUpdate<Value>): void | Promise<void>;
33
33
  };
34
34
  /**
35
35
  * Publication and sync run on outbox channels keyed by group and by
@@ -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';
@@ -45,20 +46,6 @@ class TopologyTimeoutError extends Error {
45
46
  this.name = 'TopologyTimeoutError';
46
47
  }
47
48
  }
48
- const withTimeout = async (work, timeoutMs, label) => {
49
- let timer;
50
- try {
51
- return await Promise.race([
52
- work,
53
- new Promise((_resolve, reject) => {
54
- timer = setTimeout(() => reject(new TopologyTimeoutError(label, timeoutMs)), timeoutMs);
55
- }),
56
- ]);
57
- }
58
- finally {
59
- clearTimeout(timer);
60
- }
61
- };
62
49
  // setTimeout overflows past this, and the outbox enforces the same ceiling.
63
50
  const maxTimeoutMs = 2 ** 31 - 1;
64
51
  const timeoutOf = (options, fallback) => {
@@ -75,10 +62,11 @@ const timeoutOf = (options, fallback) => {
75
62
  */
76
63
  const outboxOptions = (timeoutMs, options, fallback) => {
77
64
  const delay = options?.retries?.delay ?? fallback.retries?.delay;
78
- return {
79
- attemptTimeoutMs: Math.min(timeoutMs * 2, maxTimeoutMs),
80
- ...(delay === undefined ? {} : { retries: { delay } }),
81
- };
65
+ const outboxConfig = { attemptTimeoutMs: Math.min(timeoutMs * 2, maxTimeoutMs) };
66
+ if (delay !== undefined) {
67
+ outboxConfig.retries = { delay };
68
+ }
69
+ return outboxConfig;
82
70
  };
83
71
  /**
84
72
  * How long after its timeout an abandoned publisher write is assumed able to
@@ -99,14 +87,15 @@ const outstandingWritesUntil = (sql, ownerChannel, group, now) => {
99
87
  return until ?? undefined;
100
88
  };
101
89
  const assertGroup = (group) => {
102
- if (typeof group !== 'string' || group.length === 0) {
90
+ if (!isNonEmptyString(group)) {
103
91
  throw new TopologyError('Group must be a non-empty string');
104
92
  }
105
93
  };
106
94
  const deliveryKey = (group, member) => JSON.stringify([group, member]);
107
95
  const isThenable = (value) => value !== null &&
108
96
  typeof value === 'object' &&
109
- typeof Reflect.get(value, 'then') === 'function';
97
+ 'then' in value &&
98
+ typeof value.then === 'function';
110
99
  const readGroup = (sql, ownerChannel, group) => v.parse(v.optional(groupRowSchema), sql
111
100
  .exec(`SELECT group_id, version, members, deleted
112
101
  FROM durability_topology_groups
@@ -116,7 +105,11 @@ const readStates = (sql, ownerChannel, group) => v.parse(v.array(stateRowSchema)
116
105
  .exec(`SELECT channel, value FROM durability_topology_states
117
106
  WHERE owner_channel = ? AND group_id = ?`, ownerChannel, group)
118
107
  .toArray());
119
- 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
+ };
120
113
  const inRole = (member, role) => role === 'read' || member.state === 'active';
121
114
  /**
122
115
  * Experimental. Holds the membership of shard groups inside one coordinator
@@ -146,8 +139,7 @@ export class DurabilityTopology {
146
139
  __classPrivateFieldGet(this, _DurabilityTopology_engine, "f").migrateSchema('topology', durabilityTopologyMigrations);
147
140
  const publisher = config.publish;
148
141
  if (publisher !== undefined &&
149
- (typeof publisher.write !== 'function' ||
150
- typeof publisher.delete !== 'function')) {
142
+ (!isFunction(publisher.write) || !isFunction(publisher.delete))) {
151
143
  throw new TopologyError('publish needs write and delete functions');
152
144
  }
153
145
  const publication = publisher === undefined
@@ -155,7 +147,7 @@ export class DurabilityTopology {
155
147
  : { publisher, timeoutMs: timeoutOf(publisher, config) };
156
148
  const states = config.states ?? {};
157
149
  const channels = Object.entries(states).map(([name, channel]) => {
158
- if (!name || typeof channel.deliver !== 'function') {
150
+ if (!name || !isFunction(channel.deliver)) {
159
151
  throw new TopologyError(`Invalid topology channel "${name}"`);
160
152
  }
161
153
  return {
@@ -167,7 +159,8 @@ export class DurabilityTopology {
167
159
  // Validate before claiming so config validation failures leave the channel
168
160
  // free. Even without outboxes, an instance still owns its channel's groups.
169
161
  __classPrivateFieldGet(this, _DurabilityTopology_engine, "f").claimChannel('durability_topology_groups', ownerChannel, 'DurabilityTopology');
170
- // 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.
171
164
  const onLifecycleEvent = config.onLifecycleEvent;
172
165
  const lifecycle = onLifecycleEvent === undefined ? {} : { onLifecycleEvent };
173
166
  if (publication !== undefined) {
@@ -219,6 +212,8 @@ export class DurabilityTopology {
219
212
  const live = row?.deleted === 0 ? row : undefined;
220
213
  const before = live ? parseMembers(live) : [];
221
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>.
222
217
  const states = Object.fromEntries(stateRows.map((state) => [state.channel, deserialize(state.value)]));
223
218
  // A copy, so an updater that mutates `current` cannot make a change look like a no-op.
224
219
  const draft = next({ members: structuredClone(before), states });
@@ -335,7 +330,7 @@ async function _DurabilityTopology_publishSnapshots(publisher, entries, timeoutM
335
330
  ? publisher.delete(publication.deleted.group, publication.deleted.version)
336
331
  : publisher.write(publication.snapshot, encodeSnapshot(publication.snapshot)));
337
332
  try {
338
- await withTimeout(write, timeoutMs, 'publish');
333
+ await __classPrivateFieldGet(this, _DurabilityTopology_engine, "f").timer.withTimeout(write, timeoutMs, () => new TopologyTimeoutError('publish', timeoutMs));
339
334
  }
340
335
  catch (error) {
341
336
  if (error instanceof TopologyTimeoutError) {
@@ -358,7 +353,7 @@ async function _DurabilityTopology_publishSnapshots(publisher, entries, timeoutM
358
353
  }
359
354
  }));
360
355
  }, _DurabilityTopology_settleLate = function _DurabilityTopology_settleLate(group, id, write) {
361
- const onError = (error) => reportFailure('durability.topology.restage_failed', { group }, error);
356
+ const onError = (cause) => reportFailure('durability.topology.restage_failed', { group }, cause);
362
357
  const settled = write
363
358
  .then(() => undefined, () => undefined)
364
359
  .then(() => __classPrivateFieldGet(this, _DurabilityTopology_engine, "f").transaction((sql) => {
@@ -394,7 +389,7 @@ async function _DurabilityTopology_publishSnapshots(publisher, entries, timeoutM
394
389
  };
395
390
  try {
396
391
  // Members ignore versions they have passed, so an abandoned delivery landing late is harmless.
397
- await withTimeout(Promise.resolve().then(() => channel.deliver(member, update)), timeoutMs, 'delivery');
392
+ await __classPrivateFieldGet(this, _DurabilityTopology_engine, "f").timer.withTimeout(Promise.resolve().then(() => channel.deliver(member, update)), timeoutMs, () => new TopologyTimeoutError('delivery', timeoutMs));
398
393
  }
399
394
  catch (error) {
400
395
  reportFailure('durability.topology.delivery_failed', { group, channel: name, member: member.id, attempt: entry.attempt }, error);
@@ -402,23 +397,18 @@ async function _DurabilityTopology_publishSnapshots(publisher, entries, timeoutM
402
397
  }
403
398
  }));
404
399
  }, _DurabilityTopology_parseDraft = function _DurabilityTopology_parseDraft(draft) {
405
- if (draft === null || typeof draft !== 'object') {
400
+ if (!isObject(draft)) {
406
401
  throw new TopologyError('update must return a draft object');
407
402
  }
408
- const members = Reflect.get(draft, 'members');
409
- const states = Reflect.get(draft, 'states') ?? {};
403
+ const members = 'members' in draft ? draft.members : undefined;
404
+ const states = ('states' in draft ? draft.states : undefined) ?? {};
410
405
  if (members !== undefined && !Array.isArray(members)) {
411
406
  throw new TopologyError('Draft members must be an array');
412
407
  }
413
- if (states === null ||
414
- typeof states !== 'object' ||
415
- Array.isArray(states)) {
408
+ if (!isObject(states) || Array.isArray(states)) {
416
409
  throw new TopologyError('Draft states must be an object');
417
410
  }
418
- return {
419
- members: members,
420
- states: states,
421
- };
411
+ return { members, states };
422
412
  }, _DurabilityTopology_normalize = function _DurabilityTopology_normalize(inputs, before, now) {
423
413
  if (inputs.length === 0) {
424
414
  throw new TopologyError('A group needs at least one member; use delete() to remove it');
@@ -435,13 +425,16 @@ async function _DurabilityTopology_publishSnapshots(publisher, entries, timeoutM
435
425
  throw new TopologyError(`Duplicate member "${id}"`);
436
426
  }
437
427
  seen.add(id);
438
- return {
439
- id,
440
- state,
441
- ...(locationHint === undefined ? {} : { locationHint }),
442
- ...(meta === undefined ? {} : { meta }),
443
- joinedAt: joinedAt.get(id) ?? now,
444
- };
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;
445
438
  });
446
439
  return members.sort((a, b) => (a.id < b.id ? -1 : 1));
447
440
  }, _DurabilityTopology_writeStates = function _DurabilityTopology_writeStates(sql, group, changes, current) {
@@ -473,9 +466,7 @@ async function _DurabilityTopology_publishSnapshots(publisher, entries, timeoutM
473
466
  row.value,
474
467
  ]));
475
468
  for (const [name, channel] of __classPrivateFieldGet(this, _DurabilityTopology_channels, "f")) {
476
- const previous = new Set(before
477
- .filter((member) => inRole(member, channel.role))
478
- .map(({ id }) => id));
469
+ const previous = new Set(before.flatMap((member) => inRole(member, channel.role) ? [member.id] : []));
479
470
  const targets = after.filter((member) => inRole(member, channel.role));
480
471
  const kept = new Set(targets.map(({ id }) => id));
481
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
  };
@@ -9,9 +9,10 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
9
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
10
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
11
  };
12
- var _DurabilityTracker_instances, _DurabilityTracker_sources, _DurabilityTracker_collect, _DurabilityTracker_source, _DurabilityTracker_handle, _DurabilityTracker_wait;
12
+ var _DurabilityTracker_instances, _DurabilityTracker_sources, _DurabilityTracker_timer, _DurabilityTracker_collect, _DurabilityTracker_source, _DurabilityTracker_handle, _DurabilityTracker_wait;
13
13
  import * as v from 'valibot';
14
14
  import { traceMethods } from '../dev.js';
15
+ import { SharedTimer } from '../shared-timer.js';
15
16
  import { trackedSourceOf, } from './source.js';
16
17
  const limitSchema = v.pipe(v.number(), v.safeInteger(), v.minValue(1), v.maxValue(100));
17
18
  const cursorSchema = v.strictTuple([
@@ -54,8 +55,12 @@ export class DurabilityTracker {
54
55
  constructor(config) {
55
56
  _DurabilityTracker_instances.add(this);
56
57
  _DurabilityTracker_sources.set(this, void 0);
58
+ // Every wait holds a timeout, and nothing limits how many waits are open.
59
+ _DurabilityTracker_timer.set(this, new SharedTimer());
57
60
  __classPrivateFieldSet(this, _DurabilityTracker_sources, Object.entries(config.sources).map(([key, input]) => [
58
61
  key,
62
+ // SAFETY: Durability and DurabilityAlarms register a source in their
63
+ // constructors, so an input without one is a custom UntypedSource.
59
64
  trackedSourceOf(input) ?? input,
60
65
  ]), "f");
61
66
  }
@@ -64,6 +69,8 @@ export class DurabilityTracker {
64
69
  const { found, cursor } = await __classPrivateFieldGet(this, _DurabilityTracker_instances, "m", _DurabilityTracker_collect).call(this, query);
65
70
  const items = found.map(({ source, item }) => __classPrivateFieldGet(this, _DurabilityTracker_instances, "m", _DurabilityTracker_handle).call(this, source, item));
66
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].
67
74
  return page;
68
75
  }
69
76
  /**
@@ -74,6 +81,8 @@ export class DurabilityTracker {
74
81
  const { found, cursor } = await __classPrivateFieldGet(this, _DurabilityTracker_instances, "m", _DurabilityTracker_collect).call(this, query);
75
82
  const records = found.map(({ item }) => item);
76
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].
77
86
  return page;
78
87
  }
79
88
  /** Reacquires a handle by id, for example after an RPC disconnect. */
@@ -83,10 +92,12 @@ export class DurabilityTracker {
83
92
  if (!record) {
84
93
  return undefined;
85
94
  }
86
- 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;
87
98
  }
88
99
  }
89
- _DurabilityTracker_sources = new WeakMap(), _DurabilityTracker_instances = new WeakSet(), _DurabilityTracker_collect = async function _DurabilityTracker_collect(query) {
100
+ _DurabilityTracker_sources = new WeakMap(), _DurabilityTracker_timer = new WeakMap(), _DurabilityTracker_instances = new WeakSet(), _DurabilityTracker_collect = async function _DurabilityTracker_collect(query) {
90
101
  const limit = v.parse(limitSchema, query.limit ?? 50);
91
102
  const candidates = query.source === undefined ? __classPrivateFieldGet(this, _DurabilityTracker_sources, "f") : [__classPrivateFieldGet(this, _DurabilityTracker_instances, "m", _DurabilityTracker_source).call(this, query.source)];
92
103
  const [start, startCursor] = query.cursor === undefined
@@ -135,17 +146,17 @@ _DurabilityTracker_sources = new WeakMap(), _DurabilityTracker_instances = new W
135
146
  return new Promise((resolve, reject) => {
136
147
  let done = false;
137
148
  let unwatch;
138
- let timer;
149
+ let cancelTimeout;
139
150
  const finish = (settle) => {
140
151
  if (done) {
141
152
  return;
142
153
  }
143
154
  done = true;
144
- clearTimeout(timer);
155
+ cancelTimeout?.();
145
156
  unwatch?.();
146
157
  settle();
147
158
  };
148
- const fail = (error) => finish(() => reject(error));
159
+ const fail = (cause) => finish(() => reject(cause));
149
160
  const resolveIfSettled = (result) => {
150
161
  if (result.status !== 'pending') {
151
162
  finish(() => resolve(result));
@@ -164,7 +175,7 @@ _DurabilityTracker_sources = new WeakMap(), _DurabilityTracker_instances = new W
164
175
  unwatch?.();
165
176
  return;
166
177
  }
167
- timer = setTimeout(() => {
178
+ cancelTimeout = __classPrivateFieldGet(this, _DurabilityTracker_timer, "f").schedule(() => {
168
179
  read().then((result) => finish(() => resolve(result)), fail);
169
180
  }, timeoutMs);
170
181
  check();
@@ -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.2.1",
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.1"
68
+ "@durability/transforms": "^0.7.0"
69
69
  },
70
70
  "peerDependencies": {
71
71
  "@cloudflare/workers-types": "^4.20260702.1"