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
@@ -9,13 +9,14 @@ 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 _DurabilitySemaphoreServer_instances, _DurabilitySemaphoreServer_engine, _DurabilitySemaphoreServer_store, _DurabilitySemaphoreServer_limit, _DurabilitySemaphoreServer_groupLimit, _DurabilitySemaphoreServer_canGrant, _DurabilitySemaphoreServer_roundWaitMs, _DurabilitySemaphoreServer_roundPeriodMs, _DurabilitySemaphoreServer_grantTimeoutMs, _DurabilitySemaphoreServer_leases, _DurabilitySemaphoreServer_emit, _DurabilitySemaphoreServer_pending, _DurabilitySemaphoreServer_roundTimer, _DurabilitySemaphoreServer_round, _DurabilitySemaphoreServer_lastRoundAt, _DurabilitySemaphoreServer_contended, _DurabilitySemaphoreServer_grantRoom, _DurabilitySemaphoreServer_scheduleRound, _DurabilitySemaphoreServer_runRound, _DurabilitySemaphoreServer_allocate, _DurabilitySemaphoreServer_sync, _DurabilitySemaphoreServer_applyReports, _DurabilitySemaphoreServer_reclaim, _DurabilitySemaphoreServer_reclaimExpired, _DurabilitySemaphoreServer_resolveLimit, _DurabilitySemaphoreServer_groupPolicy;
12
+ var _DurabilitySemaphoreServer_instances, _DurabilitySemaphoreServer_engine, _DurabilitySemaphoreServer_store, _DurabilitySemaphoreServer_limit, _DurabilitySemaphoreServer_groupLimit, _DurabilitySemaphoreServer_canGrant, _DurabilitySemaphoreServer_roundWaitMs, _DurabilitySemaphoreServer_roundPeriodMs, _DurabilitySemaphoreServer_grantTimeoutMs, _DurabilitySemaphoreServer_leases, _DurabilitySemaphoreServer_emit, _DurabilitySemaphoreServer_pending, _DurabilitySemaphoreServer_roundScheduled, _DurabilitySemaphoreServer_round, _DurabilitySemaphoreServer_lastRoundAt, _DurabilitySemaphoreServer_contended, _DurabilitySemaphoreServer_grantRoom, _DurabilitySemaphoreServer_scheduleRound, _DurabilitySemaphoreServer_runRound, _DurabilitySemaphoreServer_allocate, _DurabilitySemaphoreServer_sync, _DurabilitySemaphoreServer_applyReports, _DurabilitySemaphoreServer_reclaim, _DurabilitySemaphoreServer_reclaimExpired, _DurabilitySemaphoreServer_resolveLimit, _DurabilitySemaphoreServer_groupPolicy;
13
13
  import * as v from 'valibot';
14
14
  import { traceLifecycle, traceMethods } from '../dev.js';
15
15
  import { SemaphoreProtocolError, reportFailure } from '../errors.js';
16
16
  import { durabilitySemaphoreMigrations } from './migrations.js';
17
17
  import { migrateCapability, } from '../migrations.js';
18
18
  import { assertPositiveInteger } from '../policy.js';
19
+ import { isFunction, isNumber } from '../predicates.js';
19
20
  import { allocateLeases, applyLeaseReports, budgets, clientKey, leaseFootprint, ownedBy, resolveLeasePolicy, } from './leases.js';
20
21
  import { assertChannel, defaultChannel, engineFor, } from '../scheduler/index.js';
21
22
  import { semaphoreRequestSchema, } from './protocol.js';
@@ -37,12 +38,15 @@ const clientOf = (message) => ({
37
38
  * Echoes the protocol identity so the client can verify which queue was counted.
38
39
  * Version 1 retains the response shape older clients expect.
39
40
  */
40
- const acknowledgement = (message) => ({
41
- v: message.v,
42
- ...(message.clientChannel === undefined
43
- ? {}
44
- : { clientChannel: message.clientChannel }),
45
- });
41
+ const acknowledgement = (message) => {
42
+ const echo = {
43
+ v: message.v,
44
+ };
45
+ if (message.clientChannel !== undefined) {
46
+ echo.clientChannel = message.clientChannel;
47
+ }
48
+ return echo;
49
+ };
46
50
  /** Permits left queued per (group, reason) across one round's allocations. */
47
51
  const blockedCounts = (allocations) => {
48
52
  const counts = new Map();
@@ -59,6 +63,7 @@ const blockedCounts = (allocations) => {
59
63
  }
60
64
  }
61
65
  return [...counts].map(([key, count]) => {
66
+ // SAFETY: every key was built above by JSON.stringify([group, reason]).
62
67
  const [group, reason] = JSON.parse(key);
63
68
  return [group, reason, count];
64
69
  });
@@ -86,16 +91,15 @@ export class DurabilitySemaphoreServer {
86
91
  _DurabilitySemaphoreServer_leases.set(this, void 0);
87
92
  _DurabilitySemaphoreServer_emit.set(this, void 0);
88
93
  _DurabilitySemaphoreServer_pending.set(this, []);
89
- _DurabilitySemaphoreServer_roundTimer.set(this, void 0);
94
+ _DurabilitySemaphoreServer_roundScheduled.set(this, false);
90
95
  _DurabilitySemaphoreServer_round.set(this, void 0);
91
96
  _DurabilitySemaphoreServer_lastRoundAt.set(this, -Infinity);
92
97
  // From the last round; tells clients in later syncs to return idle lease headroom.
93
98
  _DurabilitySemaphoreServer_contended.set(this, false);
94
99
  const channel = assertChannel('Semaphore', config.channel ?? defaultChannel);
95
100
  const limit = config.limit;
96
- __classPrivateFieldSet(this, _DurabilitySemaphoreServer_limit, typeof limit === 'function' ? limit : () => limit, "f");
97
- if (typeof limit === 'number' &&
98
- (!Number.isSafeInteger(limit) || limit < 0)) {
101
+ __classPrivateFieldSet(this, _DurabilitySemaphoreServer_limit, isFunction(limit) ? limit : () => limit, "f");
102
+ if (isNumber(limit) && (!Number.isSafeInteger(limit) || limit < 0)) {
99
103
  throw new RangeError('limit must be a non-negative safe integer');
100
104
  }
101
105
  __classPrivateFieldSet(this, _DurabilitySemaphoreServer_groupLimit, config.groupLimit, "f");
@@ -191,21 +195,22 @@ export class DurabilitySemaphoreServer {
191
195
  };
192
196
  }
193
197
  }
194
- _DurabilitySemaphoreServer_engine = new WeakMap(), _DurabilitySemaphoreServer_store = new WeakMap(), _DurabilitySemaphoreServer_limit = new WeakMap(), _DurabilitySemaphoreServer_groupLimit = new WeakMap(), _DurabilitySemaphoreServer_canGrant = new WeakMap(), _DurabilitySemaphoreServer_roundWaitMs = new WeakMap(), _DurabilitySemaphoreServer_roundPeriodMs = new WeakMap(), _DurabilitySemaphoreServer_grantTimeoutMs = new WeakMap(), _DurabilitySemaphoreServer_leases = new WeakMap(), _DurabilitySemaphoreServer_emit = new WeakMap(), _DurabilitySemaphoreServer_pending = new WeakMap(), _DurabilitySemaphoreServer_roundTimer = new WeakMap(), _DurabilitySemaphoreServer_round = new WeakMap(), _DurabilitySemaphoreServer_lastRoundAt = new WeakMap(), _DurabilitySemaphoreServer_contended = new WeakMap(), _DurabilitySemaphoreServer_instances = new WeakSet(), _DurabilitySemaphoreServer_grantRoom = function _DurabilitySemaphoreServer_grantRoom(limit, granted, leased) {
198
+ _DurabilitySemaphoreServer_engine = new WeakMap(), _DurabilitySemaphoreServer_store = new WeakMap(), _DurabilitySemaphoreServer_limit = new WeakMap(), _DurabilitySemaphoreServer_groupLimit = new WeakMap(), _DurabilitySemaphoreServer_canGrant = new WeakMap(), _DurabilitySemaphoreServer_roundWaitMs = new WeakMap(), _DurabilitySemaphoreServer_roundPeriodMs = new WeakMap(), _DurabilitySemaphoreServer_grantTimeoutMs = new WeakMap(), _DurabilitySemaphoreServer_leases = new WeakMap(), _DurabilitySemaphoreServer_emit = new WeakMap(), _DurabilitySemaphoreServer_pending = new WeakMap(), _DurabilitySemaphoreServer_roundScheduled = new WeakMap(), _DurabilitySemaphoreServer_round = new WeakMap(), _DurabilitySemaphoreServer_lastRoundAt = new WeakMap(), _DurabilitySemaphoreServer_contended = new WeakMap(), _DurabilitySemaphoreServer_instances = new WeakSet(), _DurabilitySemaphoreServer_grantRoom = function _DurabilitySemaphoreServer_grantRoom(limit, granted, leased) {
195
199
  if (!__classPrivateFieldGet(this, _DurabilitySemaphoreServer_leases, "f")) {
196
200
  return Math.max(0, limit - granted);
197
201
  }
198
202
  const budget = budgets(__classPrivateFieldGet(this, _DurabilitySemaphoreServer_leases, "f").provisioning, limit);
199
203
  return Math.max(0, budget.grants - granted - (budget.shared ? leased : 0));
200
204
  }, _DurabilitySemaphoreServer_scheduleRound = function _DurabilitySemaphoreServer_scheduleRound() {
201
- if (__classPrivateFieldGet(this, _DurabilitySemaphoreServer_roundTimer, "f") !== undefined || __classPrivateFieldGet(this, _DurabilitySemaphoreServer_round, "f") !== undefined) {
205
+ if (__classPrivateFieldGet(this, _DurabilitySemaphoreServer_roundScheduled, "f") || __classPrivateFieldGet(this, _DurabilitySemaphoreServer_round, "f") !== undefined) {
202
206
  return;
203
207
  }
204
208
  const earliest = __classPrivateFieldGet(this, _DurabilitySemaphoreServer_lastRoundAt, "f") + __classPrivateFieldGet(this, _DurabilitySemaphoreServer_roundPeriodMs, "f");
205
209
  const delay = Math.max(__classPrivateFieldGet(this, _DurabilitySemaphoreServer_roundWaitMs, "f"), earliest - Date.now());
206
- __classPrivateFieldSet(this, _DurabilitySemaphoreServer_roundTimer, setTimeout(() => {
207
- __classPrivateFieldSet(this, _DurabilitySemaphoreServer_roundTimer, undefined, "f");
208
- const onError = (error) => reportFailure('durability.semaphore.round_failed', {}, error);
210
+ __classPrivateFieldSet(this, _DurabilitySemaphoreServer_roundScheduled, true, "f");
211
+ __classPrivateFieldGet(this, _DurabilitySemaphoreServer_engine, "f").timer.schedule(() => {
212
+ __classPrivateFieldSet(this, _DurabilitySemaphoreServer_roundScheduled, false, "f");
213
+ const onError = (cause) => reportFailure('durability.semaphore.round_failed', {}, cause);
209
214
  __classPrivateFieldSet(this, _DurabilitySemaphoreServer_round, __classPrivateFieldGet(this, _DurabilitySemaphoreServer_instances, "m", _DurabilitySemaphoreServer_runRound).call(this)
210
215
  .catch(onError)
211
216
  .finally(() => {
@@ -215,7 +220,7 @@ _DurabilitySemaphoreServer_engine = new WeakMap(), _DurabilitySemaphoreServer_st
215
220
  }
216
221
  }), "f");
217
222
  __classPrivateFieldGet(this, _DurabilitySemaphoreServer_engine, "f").waitUntil(__classPrivateFieldGet(this, _DurabilitySemaphoreServer_round, "f"), onError);
218
- }, delay), "f");
223
+ }, delay);
219
224
  }, _DurabilitySemaphoreServer_runRound = async function _DurabilitySemaphoreServer_runRound() {
220
225
  const pending = __classPrivateFieldGet(this, _DurabilitySemaphoreServer_pending, "f");
221
226
  __classPrivateFieldSet(this, _DurabilitySemaphoreServer_pending, [], "f");
@@ -246,15 +251,19 @@ _DurabilitySemaphoreServer_engine = new WeakMap(), _DurabilitySemaphoreServer_st
246
251
  __classPrivateFieldSet(this, _DurabilitySemaphoreServer_contended, round.contended, "f");
247
252
  for (const [entry, allocation] of round.allocations) {
248
253
  const { leases, ...rest } = allocation;
249
- entry.resolve({
254
+ const grant = {
250
255
  type: 'grant',
251
256
  ...acknowledgement(entry.request),
252
257
  ...rest,
253
258
  nextRequestAt,
254
- ...(entry.request.leases === undefined
255
- ? {}
256
- : { leases, ...(round.contended ? { contended: true } : {}) }),
257
- });
259
+ };
260
+ if (entry.request.leases !== undefined) {
261
+ grant.leases = leases;
262
+ if (round.contended) {
263
+ grant.contended = true;
264
+ }
265
+ }
266
+ entry.resolve(grant);
258
267
  }
259
268
  for (const event of [...round.reclaimed, ...round.leaseEvents]) {
260
269
  __classPrivateFieldGet(this, _DurabilitySemaphoreServer_emit, "f").call(this, event);
@@ -308,9 +317,15 @@ _DurabilitySemaphoreServer_engine = new WeakMap(), _DurabilitySemaphoreServer_st
308
317
  ? budgets(__classPrivateFieldGet(this, _DurabilitySemaphoreServer_leases, "f").provisioning, limit)
309
318
  : { grants: limit, leases: 0, shared: false };
310
319
  let leased = 0;
311
- if (__classPrivateFieldGet(this, _DurabilitySemaphoreServer_leases, "f") && budget.shared) {
320
+ // A group's limit counts its live lease footprint in every mode, retired
321
+ // leases included until their clients confirm. Kept apart from `used`,
322
+ // which the lease pass reads as grants only.
323
+ const leasedByGroup = new Map();
324
+ if (__classPrivateFieldGet(this, _DurabilitySemaphoreServer_leases, "f")) {
312
325
  for (const lease of store.listLeases()) {
313
- leased += leaseFootprint(lease);
326
+ const footprint = leaseFootprint(lease);
327
+ leased += footprint;
328
+ leasedByGroup.set(lease.grp, (leasedByGroup.get(lease.grp) ?? 0) + footprint);
314
329
  }
315
330
  }
316
331
  let remaining = budget.grants - total - (budget.shared ? leased : 0);
@@ -333,7 +348,9 @@ _DurabilitySemaphoreServer_engine = new WeakMap(), _DurabilitySemaphoreServer_st
333
348
  continue;
334
349
  }
335
350
  const groupUsed = used.get(demand.group) ?? 0;
336
- const groupRemaining = policy.limit === undefined ? Infinity : policy.limit - groupUsed;
351
+ const groupRemaining = policy.limit === undefined
352
+ ? Infinity
353
+ : policy.limit - groupUsed - (leasedByGroup.get(demand.group) ?? 0);
337
354
  const give = Math.max(0, Math.min(demand.count, groupRemaining, remaining));
338
355
  if (give > 0) {
339
356
  const grant = {
@@ -442,17 +459,18 @@ _DurabilitySemaphoreServer_engine = new WeakMap(), _DurabilitySemaphoreServer_st
442
459
  : undefined;
443
460
  return { grantResults, leaseEchoes: leaseOutcome?.echoes };
444
461
  });
445
- return {
462
+ const synced = {
446
463
  type: 'synced',
447
464
  ...acknowledgement(message),
448
465
  grantResults: result.grantResults,
449
- ...(result.leaseEchoes === undefined
450
- ? {}
451
- : {
452
- leases: result.leaseEchoes,
453
- ...(__classPrivateFieldGet(this, _DurabilitySemaphoreServer_contended, "f") ? { contended: true } : {}),
454
- }),
455
466
  };
467
+ if (result.leaseEchoes !== undefined) {
468
+ synced.leases = result.leaseEchoes;
469
+ if (__classPrivateFieldGet(this, _DurabilitySemaphoreServer_contended, "f")) {
470
+ synced.contended = true;
471
+ }
472
+ }
473
+ return synced;
456
474
  }, _DurabilitySemaphoreServer_applyReports = function _DurabilitySemaphoreServer_applyReports(store, client, reports, now) {
457
475
  const results = [];
458
476
  for (const report of reports) {
@@ -1,10 +1,11 @@
1
1
  import * as v from 'valibot';
2
- export type Json = string | number | boolean | null | Json[] | {
2
+ export type Json = string | number | boolean | null | Json[] | JsonObject;
3
+ export type JsonObject = {
3
4
  [key: string]: Json;
4
5
  };
5
6
  export declare const jsonSchema: v.CustomSchema<Json, v.ErrorMessage<v.CustomIssue> | undefined>;
6
7
  export declare const serialize: (value: unknown) => string;
7
- export declare const deserialize: (value: string) => unknown;
8
+ export declare const deserialize: (value: string) => Json | undefined;
8
9
  /**
9
10
  * The stored form with object keys sorted at every depth, so two payloads
10
11
  * compare equal when they carry the same data regardless of key order.
@@ -1,4 +1,5 @@
1
1
  import * as v from 'valibot';
2
+ import { isJsonObject } from './predicates.js';
2
3
  const isPlainObject = (value) => {
3
4
  if (value === null || typeof value !== 'object') {
4
5
  return false;
@@ -33,27 +34,28 @@ const storedValueSchema = v.variant('kind', [
33
34
  v.object({ kind: v.literal('undefined') }),
34
35
  ]);
35
36
  /**
36
- * What `JSON.stringify` would produce: `undefined` properties are dropped and
37
- * `undefined` array elements become `null`. `jsonSchema` rejects both as given,
38
- * although they are routine in values such as lifecycle events whose handler
39
- * returned nothing.
37
+ * Parses a value into what `JSON.stringify` would produce: `undefined`
38
+ * properties are dropped and `undefined` array elements become `null`.
39
+ * `jsonSchema` rejects both as given, although they are routine in values such
40
+ * as lifecycle events whose handler returned nothing.
40
41
  */
41
- const asJson = (value) => {
42
+ const toJson = (value) => {
42
43
  if (Array.isArray(value)) {
43
- return value.map((item) => (item === undefined ? null : asJson(item)));
44
+ // `map` keeps the holes of a sparse array, which are not JSON.
45
+ return v.parse(jsonSchema, value.map((item) => (item === undefined ? null : toJson(item))));
44
46
  }
45
47
  // Only plain objects are rewritten; anything else must fail validation as is.
46
48
  if (!isPlainObject(value)) {
47
- return value;
49
+ return v.parse(jsonSchema, value);
48
50
  }
49
51
  return Object.fromEntries(Object.entries(value)
50
52
  .filter(([, item]) => item !== undefined)
51
- .map(([key, item]) => [key, asJson(item)]));
53
+ .map(([key, item]) => [key, toJson(item)]));
52
54
  };
53
55
  // Wrapping preserves a successful `undefined` result, which bare JSON cannot represent.
54
56
  export const serialize = (value) => JSON.stringify(value === undefined
55
57
  ? { kind: 'undefined' }
56
- : { kind: 'value', value: v.parse(jsonSchema, asJson(value)) });
58
+ : { kind: 'value', value: toJson(value) });
57
59
  export const deserialize = (value) => {
58
60
  const stored = v.parse(storedValueSchema, JSON.parse(value));
59
61
  return stored.kind === 'undefined' ? undefined : stored.value;
@@ -62,10 +64,10 @@ const canonicalize = (value) => {
62
64
  if (Array.isArray(value)) {
63
65
  return value.map(canonicalize);
64
66
  }
65
- if (value !== null && typeof value === 'object') {
66
- return Object.fromEntries(Object.keys(value)
67
- .sort()
68
- .map((key) => [key, canonicalize(value[key])]));
67
+ if (isJsonObject(value)) {
68
+ return Object.fromEntries(Object.entries(value)
69
+ .sort(([left], [right]) => (left < right ? -1 : 1))
70
+ .map(([key, item]) => [key, canonicalize(item)]));
69
71
  }
70
72
  return value;
71
73
  };
@@ -73,4 +75,5 @@ const canonicalize = (value) => {
73
75
  * The stored form with object keys sorted at every depth, so two payloads
74
76
  * compare equal when they carry the same data regardless of key order.
75
77
  */
78
+ // SAFETY: JSON.parse yields only JSON values.
76
79
  export const canonical = (stored) => JSON.stringify(canonicalize(JSON.parse(stored)));
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Runs callbacks after a delay like `setTimeout`, but keeps every pending
3
+ * callback in a min-heap ordered by due time and sets one native timer for the
4
+ * earliest. workerd makes `setTimeout` throw once 10,000 native timers are
5
+ * pending, so an object whose open timeouts grow with its workload schedules
6
+ * them here instead of setting a native timer for each.
7
+ *
8
+ * Callbacks due together run one after another in the same task, so promise
9
+ * reactions queued by one do not run before the next as they would between
10
+ * separate native timers. A callback scheduled by one of them runs in a later
11
+ * task even with no delay.
12
+ *
13
+ * A native timer belongs to the request or Durable Object that set it, so an
14
+ * instance must not be shared between them.
15
+ */
16
+ export declare class SharedTimer {
17
+ #private;
18
+ /** Callbacks that have neither run nor been cancelled. */
19
+ get pendingCount(): number;
20
+ /** Runs `callback` once after `delayMs` and returns a function that cancels it. */
21
+ schedule(callback: () => void, delayMs: number): () => void;
22
+ /**
23
+ * Settles like `work`, or rejects with the error from `onTimeout` when
24
+ * `work` is still pending after `timeoutMs`.
25
+ */
26
+ withTimeout<T>(work: Promise<T>, timeoutMs: number, onTimeout: () => Error): Promise<T>;
27
+ }
@@ -0,0 +1,191 @@
1
+ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
2
+ if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
3
+ 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");
4
+ return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
5
+ };
6
+ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
7
+ if (kind === "m") throw new TypeError("Private method is not writable");
8
+ if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
9
+ if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
10
+ return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
11
+ };
12
+ var _SharedTimer_instances, _SharedTimer_heap, _SharedTimer_scheduledCount, _SharedTimer_nativeTimer, _SharedTimer_setNativeTimer, _SharedTimer_runDue, _SharedTimer_remove, _SharedTimer_place, _SharedTimer_moveUp, _SharedTimer_moveDown;
13
+ import { reportFailure } from './errors.js';
14
+ // setTimeout overflows past 2^31 - 1 ms and fires at once. A longer wait is
15
+ // set for this long, finds nothing due when it fires, and is set again.
16
+ const maxNativeDelayMs = 2 ** 31 - 1;
17
+ const isBefore = (firstEntry, secondEntry) => firstEntry.dueAt < secondEntry.dueAt ||
18
+ (firstEntry.dueAt === secondEntry.dueAt &&
19
+ firstEntry.order < secondEntry.order);
20
+ /**
21
+ * Runs callbacks after a delay like `setTimeout`, but keeps every pending
22
+ * callback in a min-heap ordered by due time and sets one native timer for the
23
+ * earliest. workerd makes `setTimeout` throw once 10,000 native timers are
24
+ * pending, so an object whose open timeouts grow with its workload schedules
25
+ * them here instead of setting a native timer for each.
26
+ *
27
+ * Callbacks due together run one after another in the same task, so promise
28
+ * reactions queued by one do not run before the next as they would between
29
+ * separate native timers. A callback scheduled by one of them runs in a later
30
+ * task even with no delay.
31
+ *
32
+ * A native timer belongs to the request or Durable Object that set it, so an
33
+ * instance must not be shared between them.
34
+ */
35
+ export class SharedTimer {
36
+ constructor() {
37
+ _SharedTimer_instances.add(this);
38
+ _SharedTimer_heap.set(this, []);
39
+ _SharedTimer_scheduledCount.set(this, 0);
40
+ _SharedTimer_nativeTimer.set(this, void 0);
41
+ }
42
+ /** Callbacks that have neither run nor been cancelled. */
43
+ get pendingCount() {
44
+ return __classPrivateFieldGet(this, _SharedTimer_heap, "f").length;
45
+ }
46
+ /** Runs `callback` once after `delayMs` and returns a function that cancels it. */
47
+ schedule(callback, delayMs) {
48
+ var _a, _b;
49
+ const entry = {
50
+ // performance.now() rather than Date.now(): a native timer counts
51
+ // elapsed time, which a change to the wall clock does not affect.
52
+ dueAt: performance.now() + (delayMs > 0 ? delayMs : 0),
53
+ order: (__classPrivateFieldSet(this, _SharedTimer_scheduledCount, (_b = __classPrivateFieldGet(this, _SharedTimer_scheduledCount, "f"), _a = _b++, _b), "f"), _a),
54
+ index: __classPrivateFieldGet(this, _SharedTimer_heap, "f").length,
55
+ callback,
56
+ };
57
+ __classPrivateFieldGet(this, _SharedTimer_heap, "f").push(entry);
58
+ __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_moveUp).call(this, entry);
59
+ // The native timer is also missing if setting it failed in #runDue; the
60
+ // entries left without one get it back here.
61
+ if (entry.index === 0 || __classPrivateFieldGet(this, _SharedTimer_nativeTimer, "f") === undefined) {
62
+ try {
63
+ __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_setNativeTimer).call(this);
64
+ }
65
+ catch (error) {
66
+ // The caller gets the error instead of a cancel function, so the
67
+ // callback must not stay behind and run later.
68
+ __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_remove).call(this, entry);
69
+ throw error;
70
+ }
71
+ }
72
+ return () => {
73
+ entry.callback = undefined;
74
+ if (entry.index === -1) {
75
+ return;
76
+ }
77
+ const wasEarliest = entry.index === 0;
78
+ __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_remove).call(this, entry);
79
+ if (wasEarliest) {
80
+ __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_setNativeTimer).call(this);
81
+ }
82
+ };
83
+ }
84
+ /**
85
+ * Settles like `work`, or rejects with the error from `onTimeout` when
86
+ * `work` is still pending after `timeoutMs`.
87
+ */
88
+ async withTimeout(work, timeoutMs, onTimeout) {
89
+ let cancelTimeout;
90
+ try {
91
+ return await Promise.race([
92
+ work,
93
+ new Promise((_resolve, reject) => {
94
+ cancelTimeout = this.schedule(() => reject(onTimeout()), timeoutMs);
95
+ }),
96
+ ]);
97
+ }
98
+ finally {
99
+ cancelTimeout?.();
100
+ }
101
+ }
102
+ }
103
+ _SharedTimer_heap = new WeakMap(), _SharedTimer_scheduledCount = new WeakMap(), _SharedTimer_nativeTimer = new WeakMap(), _SharedTimer_instances = new WeakSet(), _SharedTimer_setNativeTimer = function _SharedTimer_setNativeTimer() {
104
+ clearTimeout(__classPrivateFieldGet(this, _SharedTimer_nativeTimer, "f"));
105
+ __classPrivateFieldSet(this, _SharedTimer_nativeTimer, undefined, "f");
106
+ const earliest = __classPrivateFieldGet(this, _SharedTimer_heap, "f")[0];
107
+ if (earliest === undefined) {
108
+ return;
109
+ }
110
+ const now = performance.now();
111
+ const wakeAt = Math.min(earliest.dueAt, now + maxNativeDelayMs);
112
+ __classPrivateFieldSet(this, _SharedTimer_nativeTimer, setTimeout(() => __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_runDue).call(this, wakeAt), Math.max(wakeAt - now, 0)), "f");
113
+ }, _SharedTimer_runDue = function _SharedTimer_runDue(wakeAt) {
114
+ // setTimeout drops the fraction of a delay, so it can fire just before the
115
+ // clock reaches `wakeAt`. Counting that as reached runs the callback now
116
+ // instead of setting another timer for the remaining fraction.
117
+ const now = Math.max(performance.now(), wakeAt);
118
+ const due = [];
119
+ let earliest = __classPrivateFieldGet(this, _SharedTimer_heap, "f")[0];
120
+ while (earliest !== undefined && earliest.dueAt <= now) {
121
+ __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_remove).call(this, earliest);
122
+ due.push(earliest);
123
+ earliest = __classPrivateFieldGet(this, _SharedTimer_heap, "f")[0];
124
+ }
125
+ // Set before the callbacks run, and by clearing the native timer that is
126
+ // firing: workerd counts it as pending until this function returns, and a
127
+ // callback could take the last one the runtime allows. Clearing one and
128
+ // setting one cannot fail at that limit, so the entries still in the heap
129
+ // always keep a native timer.
130
+ try {
131
+ __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_setNativeTimer).call(this);
132
+ }
133
+ catch (error) {
134
+ reportFailure('durability.timer.set_failed', { pendingCount: __classPrivateFieldGet(this, _SharedTimer_heap, "f").length }, error);
135
+ }
136
+ for (const entry of due) {
137
+ try {
138
+ entry.callback?.();
139
+ }
140
+ catch (error) {
141
+ // A throw must not keep the callbacks behind it from running.
142
+ reportFailure('durability.timer.callback_failed', { dueAt: entry.dueAt, scheduledOrder: entry.order }, error);
143
+ }
144
+ }
145
+ }, _SharedTimer_remove = function _SharedTimer_remove(entry) {
146
+ const { index } = entry;
147
+ entry.index = -1;
148
+ const last = __classPrivateFieldGet(this, _SharedTimer_heap, "f").pop();
149
+ if (last === undefined || last === entry) {
150
+ return;
151
+ }
152
+ __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_place).call(this, last, index);
153
+ __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_moveUp).call(this, last);
154
+ __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_moveDown).call(this, last);
155
+ }, _SharedTimer_place = function _SharedTimer_place(entry, index) {
156
+ __classPrivateFieldGet(this, _SharedTimer_heap, "f")[index] = entry;
157
+ entry.index = index;
158
+ }, _SharedTimer_moveUp = function _SharedTimer_moveUp(entry) {
159
+ let { index } = entry;
160
+ while (index > 0) {
161
+ const parentIndex = (index - 1) >> 1;
162
+ const parent = __classPrivateFieldGet(this, _SharedTimer_heap, "f")[parentIndex];
163
+ if (parent === undefined || !isBefore(entry, parent)) {
164
+ break;
165
+ }
166
+ __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_place).call(this, parent, index);
167
+ index = parentIndex;
168
+ }
169
+ __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_place).call(this, entry, index);
170
+ }, _SharedTimer_moveDown = function _SharedTimer_moveDown(entry) {
171
+ let { index } = entry;
172
+ for (;;) {
173
+ const leftIndex = 2 * index + 1;
174
+ const left = __classPrivateFieldGet(this, _SharedTimer_heap, "f")[leftIndex];
175
+ if (left === undefined) {
176
+ break;
177
+ }
178
+ const right = __classPrivateFieldGet(this, _SharedTimer_heap, "f")[leftIndex + 1];
179
+ let child = left;
180
+ if (right !== undefined && isBefore(right, left)) {
181
+ child = right;
182
+ }
183
+ if (!isBefore(child, entry)) {
184
+ break;
185
+ }
186
+ const childIndex = child.index;
187
+ __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_place).call(this, child, index);
188
+ index = childIndex;
189
+ }
190
+ __classPrivateFieldGet(this, _SharedTimer_instances, "m", _SharedTimer_place).call(this, entry, index);
191
+ };
@@ -1,5 +1,5 @@
1
1
  import { type SerializedError } from '../errors.js';
2
- import { type AnySocketShape, type InboundOf, type OutboundOf, type SocketInboundInput, type SocketInboundOutput, type SocketOutboundPayload } from './protocol.js';
2
+ import { type AnyDurabilitySocket, type InboundOf, type OutboundOf, type SocketInboundInput, type SocketInboundOutput, type SocketOutboundPayload } from './protocol.js';
3
3
  /** Rejection for calls still waiting when `close()` was called. */
4
4
  export declare class SocketClosedError extends Error {
5
5
  constructor();
@@ -30,6 +30,8 @@ export type SocketTransform = (call: {
30
30
  input: unknown;
31
31
  next: (input?: unknown) => Promise<unknown>;
32
32
  }) => Promise<unknown>;
33
+ /** The part of a `WebSocket` the client uses. */
34
+ type SocketClientWebSocket = Pick<WebSocket, 'addEventListener' | 'close' | 'send'>;
33
35
  export type DurabilitySocketClientConfig = {
34
36
  /** Builds the WebSocket URL for one Durable Object. */
35
37
  url: (id: string) => string;
@@ -38,9 +40,9 @@ export type DurabilitySocketClientConfig = {
38
40
  /** Interval between keep-alive pings; a silent connection is dropped after two. Defaults to 30 seconds. */
39
41
  pingIntervalMs?: number;
40
42
  /** WebSocket implementation. Defaults to the global `WebSocket`. */
41
- webSocket?: new (url: string) => WebSocket;
43
+ webSocket?: new (url: string) => SocketClientWebSocket;
42
44
  };
43
- type RpcMethod<Input, Output> = [Input] extends [void] ? () => Promise<Output> : unknown extends Input ? (input?: unknown) => Promise<Output> : (input: Input) => Promise<Output>;
45
+ type RpcMethod<Input, Output> = [Input] extends [void] ? () => Promise<Output> : (input: Input) => Promise<Output>;
44
46
  type RpcMethods<Inbound> = {
45
47
  [Method in keyof Inbound]: RpcMethod<SocketInboundInput<Inbound[Method]>, SocketInboundOutput<Inbound[Method]>>;
46
48
  };
@@ -60,7 +62,7 @@ export type SocketResync = {
60
62
  names: string[];
61
63
  };
62
64
  /** One connection to one Durable Object. */
63
- export type SocketConnection<Socket extends AnySocketShape> = {
65
+ export type SocketConnection<Socket extends AnyDurabilitySocket> = {
64
66
  rpc: RpcMethods<InboundOf<Socket>>;
65
67
  on: EventHandlers<OutboundOf<Socket>>;
66
68
  readonly status: SocketStatus;
@@ -82,13 +84,25 @@ export type SocketConnection<Socket extends AnySocketShape> = {
82
84
  * conn.on.resync(() => reload());
83
85
  * ```
84
86
  */
85
- export declare class DurabilitySocketClient<Socket extends AnySocketShape> {
87
+ export declare class DurabilitySocketClient<Socket extends AnyDurabilitySocket> {
86
88
  #private;
87
89
  constructor(config: DurabilitySocketClientConfig, transforms?: readonly SocketTransform[]);
88
90
  /** Returns a client that also applies `transform` around every call. */
89
91
  with(transform: SocketTransform): DurabilitySocketClient<Socket>;
90
92
  connect(id: string): SocketConnection<Socket>;
91
93
  }
94
+ /** One call recorded by {@link logging}: its output if it resolved, or its error. */
95
+ export type SocketCallLog = {
96
+ method: string;
97
+ input: unknown;
98
+ output: unknown;
99
+ durationMs: number;
100
+ } | {
101
+ method: string;
102
+ input: unknown;
103
+ error: unknown;
104
+ durationMs: number;
105
+ };
92
106
  /** Logs every call's input, output or error, and duration. */
93
- export declare const logging: (log?: (entry: Record<string, unknown>) => void) => SocketTransform;
94
- export { socketShape, type AnySocketShape, type InboundOf, type OutboundOf, type SocketInboundInput, type SocketInboundOutput, type SocketOutboundPayload, type SocketShape, } from './protocol.js';
107
+ export declare const logging: (log?: (entry: SocketCallLog) => void) => SocketTransform;
108
+ export { socketMessageMaps, type AnyDurabilitySocket, type InboundOf, type OutboundOf, type SocketInboundInput, type SocketInboundOutput, type SocketMessageMaps, type SocketOutboundPayload, } from './protocol.js';