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
@@ -4,6 +4,7 @@ import { DurableRetryPolicyError, isErrorInstance, isNonRetryable, reportFailure
4
4
  import { createEmitter, } from '../lifecycle.js';
5
5
  import { isSchemaCurrent, migrateCapability, } from '../migrations.js';
6
6
  import { assertPositiveInteger } from '../policy.js';
7
+ import { isFunction, isNonEmptyString } from '../predicates.js';
7
8
  import { deleteMemos, deleteStaleMemos } from '../memoize/index.js';
8
9
  import { SharedTimer } from '../shared-timer.js';
9
10
  import { channelBindings, channelClause, claimAttempt, exhaustAttempts, tableOwner, updateAttempt, } from '../storage.js';
@@ -34,18 +35,18 @@ const channelRowSchema = v.object({ channel: v.string() });
34
35
  const activeKey = (channel, key) => JSON.stringify([channel ?? null, key]);
35
36
  /** Rejects a channel name a helper would otherwise store rows under. */
36
37
  export const assertChannel = (helper, channel) => {
37
- if (typeof channel !== 'string' || channel.length === 0) {
38
+ if (!isNonEmptyString(channel)) {
38
39
  throw new TypeError(`${helper} channel must be a non-empty string`);
39
40
  }
40
41
  return channel;
41
42
  };
42
- const decideRetry = (spec, attempt, error) => {
43
- const terminal = isNonRetryable(error) ||
43
+ const decideRetry = (spec, attempt, cause) => {
44
+ const terminal = isNonRetryable(cause) ||
44
45
  attempt >= spec.policy.maxAttempts ||
45
- spec.isTerminal(error);
46
+ spec.isTerminal(cause);
46
47
  if (terminal) {
47
48
  const timestamp = Date.now();
48
- return { error, terminal, timestamp, nextAttemptAt: timestamp };
49
+ return { error: cause, terminal, timestamp, nextAttemptAt: timestamp };
49
50
  }
50
51
  try {
51
52
  const rawDelay = spec.policy.delay(attempt);
@@ -59,7 +60,7 @@ const decideRetry = (spec, attempt, error) => {
59
60
  throw new DurableRetryPolicyError(spec.label);
60
61
  }
61
62
  return {
62
- error,
63
+ error: cause,
63
64
  terminal: false,
64
65
  timestamp,
65
66
  nextAttemptAt: timestamp + delay,
@@ -137,8 +138,7 @@ export class Engine {
137
138
  const alarmConcurrency = merged.alarmConcurrency ?? defaultAlarmConcurrency;
138
139
  const alarmMinDelayMs = merged.alarmMinDelayMs ?? 15000;
139
140
  const alarmHandoffMs = merged.alarmHandoffMs ?? 14 * 60000;
140
- if (merged.onAlarmRetry !== undefined &&
141
- typeof merged.onAlarmRetry !== 'function') {
141
+ if (merged.onAlarmRetry !== undefined && !isFunction(merged.onAlarmRetry)) {
142
142
  throw new TypeError('onAlarmRetry must be a function');
143
143
  }
144
144
  assertPositiveInteger('alarmConcurrency', alarmConcurrency);
@@ -206,7 +206,7 @@ export class Engine {
206
206
  if (participant.nextPendingAt !== undefined) {
207
207
  // Missing custom channels are dormant. Defer until construction finishes,
208
208
  // then restore their alarm without requiring a new application write.
209
- const onError = (error) => reportFailure('durability.channel_resume_failed', { table: table.name, channel }, error);
209
+ const onError = (cause) => reportFailure('durability.channel_resume_failed', { table: table.name, channel }, cause);
210
210
  const resumed = Promise.resolve()
211
211
  .then(() => {
212
212
  if (participant.nextPendingAt?.(this.sql) !== undefined) {
@@ -214,11 +214,11 @@ export class Engine {
214
214
  }
215
215
  return undefined;
216
216
  })
217
- .catch(async (error) => {
217
+ .catch(async (cause) => {
218
218
  if (await this.armFallbackAlarm()) {
219
219
  this.retryFailedRun();
220
220
  }
221
- onError(error);
221
+ onError(cause);
222
222
  });
223
223
  this.waitUntil(resumed, onError);
224
224
  }
@@ -284,7 +284,7 @@ export class Engine {
284
284
  * `DurableObjectState` applications pass at runtime carries it.
285
285
  */
286
286
  objectId() {
287
- const id = Reflect.get(this.context, 'id');
287
+ const id = 'id' in this.context ? this.context.id : undefined;
288
288
  return id === undefined || id === null ? undefined : String(id);
289
289
  }
290
290
  emitter(hook) {
@@ -447,7 +447,7 @@ export class Engine {
447
447
  }
448
448
  this.earlyAlarm = undefined;
449
449
  trace('scheduler.early_alarm', { scheduledTime: timestamp });
450
- const onError = (error) => reportFailure('durability.background_execution.failed', { scheduledTime: timestamp }, error);
450
+ const onError = (cause) => reportFailure('durability.background_execution.failed', { scheduledTime: timestamp }, cause);
451
451
  const execution = this.alarm().catch(onError);
452
452
  this.waitUntil(execution, onError);
453
453
  }, delay);
@@ -590,7 +590,7 @@ export class Engine {
590
590
  throw error;
591
591
  }
592
592
  reportFailure('durability.alarm.failed', { retryInMs: this.alarmMinDelayMs }, error);
593
- this.notifyAlarmRetry(error, info);
593
+ this.notifyAlarmRetry(serializeError(error), info);
594
594
  this.retryFailedRun();
595
595
  }
596
596
  }
@@ -605,24 +605,24 @@ export class Engine {
605
605
  const delay = Math.min(failedRunRetryMs * 2 ** (this.failedRuns - 1), this.alarmMinDelayMs);
606
606
  this.scheduleEarlyAlarm(Date.now() + delay);
607
607
  }
608
- notifyAlarmRetry(failure, invocation) {
608
+ notifyAlarmRetry(error, invocation) {
609
609
  const hook = this.onAlarmRetry;
610
610
  if (!hook) {
611
611
  return;
612
612
  }
613
613
  const objectId = this.objectId();
614
614
  const info = {
615
- error: serializeError(failure),
615
+ error,
616
616
  retryInMs: this.alarmMinDelayMs,
617
- ...(invocation === undefined
618
- ? {}
619
- : {
620
- retryCount: invocation.retryCount,
621
- isRetry: invocation.isRetry,
622
- }),
623
- ...(objectId === undefined ? {} : { objectId }),
624
617
  };
625
- const report = (hookError) => reportFailure('durability.alarm.retry_hook_failed', { retryInMs: info.retryInMs }, hookError);
618
+ if (invocation !== undefined) {
619
+ info.retryCount = invocation.retryCount;
620
+ info.isRetry = invocation.isRetry;
621
+ }
622
+ if (objectId !== undefined) {
623
+ info.objectId = objectId;
624
+ }
625
+ const report = (cause) => reportFailure('durability.alarm.retry_hook_failed', { retryInMs: info.retryInMs }, cause);
626
626
  try {
627
627
  const result = hook(info);
628
628
  if (result !== undefined) {
@@ -742,15 +742,18 @@ export class Engine {
742
742
  });
743
743
  if (timestamp !== undefined) {
744
744
  this.notify(spec.table, key, row);
745
- spec.emit({
745
+ const completed = {
746
746
  ...spec.entity,
747
747
  type: 'attempt_settled',
748
748
  timestamp,
749
749
  attempt,
750
750
  durationMs: Math.max(0, timestamp - startedAt),
751
751
  outcome: 'completed',
752
- ...(spec.includeResult ? { result } : {}),
753
- });
752
+ };
753
+ if (spec.includeResult) {
754
+ completed.result = result;
755
+ }
756
+ spec.emit(completed);
754
757
  }
755
758
  }
756
759
  catch (caught) {
@@ -797,9 +800,9 @@ export class Engine {
797
800
  error: exhausted,
798
801
  });
799
802
  }
800
- async settleFailure(spec, attempt, startedAt, caught) {
803
+ async settleFailure(spec, attempt, startedAt, cause) {
801
804
  const { key, row } = spec;
802
- const decision = decideRetry(spec, attempt, caught);
805
+ const decision = decideRetry(spec, attempt, cause);
803
806
  const serializedError = serializeError(decision.error);
804
807
  const updated = await this.transaction((sql) => {
805
808
  const owned = updateAttempt(sql, spec.table, { key, generation: row.generation_id, attempt }, 'status = ?, next_attempt_at = ?, last_error = ?, last_error_name = ?', decision.terminal ? 'failed' : 'pending', decision.nextAttemptAt, serializedError.message, serializedError.name);
@@ -835,10 +838,11 @@ const engines = new WeakMap();
835
838
  // Every copy of this package in an isolate shares the registry, so a second
836
839
  // copy reaching the same object is caught instead of fighting over its alarm.
837
840
  const installation = Symbol('durability installation');
838
- const globalRegistry = globalThis;
839
841
  const registryKey = Symbol.for('durability.object-schedulers');
840
- globalRegistry[registryKey] ?? (globalRegistry[registryKey] = new WeakMap());
841
- const objectSchedulers = globalRegistry[registryKey];
842
+ // SAFETY: registryKey is this package's registered symbol, and every copy
843
+ // stores only a WeakMap<object, ObjectScheduler> under it on globalThis.
844
+ const globalRegistry = globalThis;
845
+ const objectSchedulers = (globalRegistry[registryKey] ?? (globalRegistry[registryKey] = new WeakMap()));
842
846
  /** The one engine behind every scheduler and helper of a Durable Object. */
843
847
  const engineForObject = (config) => {
844
848
  const { context } = config;
@@ -851,6 +855,8 @@ const engineForObject = (config) => {
851
855
  if (existing.installation !== installation) {
852
856
  throw new Error('Another copy of durability is already attached to this Durable Object; install durability once, for example as a peer dependency');
853
857
  }
858
+ // SAFETY: the installation matches, so this copy of the module created the
859
+ // entry above with `new Engine`.
854
860
  const engine = existing.engine;
855
861
  engine.attach(context, config);
856
862
  return engine;
@@ -904,7 +910,7 @@ export class DurabilityScheduler {
904
910
  * reported as `durability.timer.callback_failed` instead of being thrown.
905
911
  */
906
912
  setTimeout(callback, delayMs) {
907
- if (typeof callback !== 'function') {
913
+ if (!isFunction(callback)) {
908
914
  throw new TypeError('callback must be a function');
909
915
  }
910
916
  return engineFor({ scheduler: this }).timer.schedule(callback, delayMs);
@@ -12,6 +12,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
12
12
  var _SemaphoreClient_instances, _SemaphoreClient_config, _SemaphoreClient_nextRequestAt, _SemaphoreClient_address;
13
13
  import * as v from 'valibot';
14
14
  import { SemaphoreProtocolError } from '../errors.js';
15
+ import { isNonEmptyString } from '../predicates.js';
15
16
  import { permitGrantSchema, permitSyncResultSchema, } from './protocol.js';
16
17
  /**
17
18
  * Transport-independent protocol core. Validates responses and remembers each
@@ -54,7 +55,7 @@ export class SemaphoreClient {
54
55
  }
55
56
  }
56
57
  _SemaphoreClient_config = new WeakMap(), _SemaphoreClient_nextRequestAt = new WeakMap(), _SemaphoreClient_instances = new WeakSet(), _SemaphoreClient_address = function _SemaphoreClient_address(key) {
57
- if (typeof key !== 'string' || key.length === 0) {
58
+ if (!isNonEmptyString(key)) {
58
59
  throw new SemaphoreProtocolError('Semaphore keys must be non-empty strings');
59
60
  }
60
61
  const locationHint = __classPrivateFieldGet(this, _SemaphoreClient_config, "f").locationHint?.(key);
@@ -20,7 +20,7 @@ export type SemaphoreSession = {
20
20
  request(key: string, message: PermitRequest): Promise<PermitGrant>;
21
21
  sync(key: string, message: PermitSync): Promise<PermitSyncResult>;
22
22
  setContext(context: TransformContext): {
23
- invoke(method: string, args: unknown[]): Promise<unknown>;
23
+ invoke(method: string, args: unknown[]): Promise<PermitGrant | PermitSyncResult>;
24
24
  };
25
25
  };
26
26
  export type DurabilitySemaphoreClientConfig<Target extends Rpc.DurableObjectBranded> = DurableObjectTarget<Target> & {
@@ -24,7 +24,7 @@ export class DurabilitySemaphore extends DurabilitySemaphoreServer {
24
24
  * Caller transforms such as `timeout` apply; transform context is not used.
25
25
  */
26
26
  static client(config) {
27
- const client = new SemaphoreClient({
27
+ const clientConfig = {
28
28
  invoke: (address, message) => {
29
29
  const namespace = resolveNamespace(config, (text) => new SemaphoreProtocolError(text));
30
30
  const stub = namespace.getByName(address.key, address.locationHint === undefined
@@ -32,20 +32,25 @@ export class DurabilitySemaphore extends DurabilitySemaphoreServer {
32
32
  : { locationHint: address.locationHint });
33
33
  return config.invoke(stub, message);
34
34
  },
35
- ...(config.locationHint === undefined
36
- ? {}
37
- : { locationHint: config.locationHint }),
38
- });
35
+ };
36
+ if (config.locationHint !== undefined) {
37
+ clientConfig.locationHint = config.locationHint;
38
+ }
39
+ const client = new SemaphoreClient(clientConfig);
39
40
  const session = {
40
41
  request: (key, message) => client.request(key, message),
41
42
  sync: (key, message) => client.sync(key, message),
42
43
  setContext: () => ({
43
44
  invoke: (method, args) => {
45
+ // SAFETY: the transform stub forwards the arguments of a typed
46
+ // SemaphoreSession call, so args are [key, message] for `method`.
44
47
  const key = args[0];
45
48
  if (method === 'request') {
49
+ // SAFETY: see `key`; `request` takes a PermitRequest.
46
50
  return client.request(key, args[1]);
47
51
  }
48
52
  if (method === 'sync') {
53
+ // SAFETY: see `key`; `sync` takes a PermitSync.
49
54
  return client.sync(key, args[1]);
50
55
  }
51
56
  throw new SemaphoreProtocolError(`Unknown semaphore method "${method}"`);
@@ -67,12 +67,13 @@ type GroupPolicy = {
67
67
  blocked?: SemaphoreBlockedReason;
68
68
  };
69
69
  export declare const resolveLeasePolicy: (options: SemaphoreLeaseOptions) => LeasePolicy;
70
- /** Permits grants may use, and permits leases may hold, for one limit. */
71
- export declare const budgets: (provisioning: SemaphoreProvisioning, limit: number) => {
70
+ type PermitBudget = {
72
71
  grants: number;
73
72
  leases: number;
74
73
  shared: boolean;
75
74
  };
75
+ /** Permits grants may use, and permits leases may hold, for one limit. */
76
+ export declare const budgets: (provisioning: SemaphoreProvisioning, limit: number) => PermitBudget;
76
77
  export declare const leaseFootprint: (lease: LeaseRow) => number;
77
78
  export declare const leaseEligible: (policy: LeasePolicy, group: GroupPolicy) => boolean;
78
79
  export type LeaseReportOutcome = {
@@ -1,4 +1,5 @@
1
1
  import { assertPositiveInteger } from '../policy.js';
2
+ import { isNumber } from '../predicates.js';
2
3
  /** Map key for a client identity; JSON keeps raw IDs and channels unambiguous. */
3
4
  export const clientKey = (clientId, clientChannel) => JSON.stringify([clientId, clientChannel]);
4
5
  export const ownedBy = (row, client) => row.client_id === client.clientId &&
@@ -30,14 +31,14 @@ export const resolveLeasePolicy = (options) => {
30
31
  ? policy.provisioning.extra
31
32
  : undefined;
32
33
  if (amount !== undefined) {
33
- const value = typeof amount === 'number' ? amount : amount.ratio;
34
+ const value = isNumber(amount) ? amount : amount.ratio;
34
35
  if (!Number.isFinite(value) || value < 0) {
35
36
  throw new RangeError('lease provisioning amounts must be non-negative');
36
37
  }
37
38
  }
38
39
  return policy;
39
40
  };
40
- const scaled = (amount, limit) => typeof amount === 'number' ? amount : Math.floor(limit * amount.ratio);
41
+ const scaled = (amount, limit) => isNumber(amount) ? amount : Math.floor(limit * amount.ratio);
41
42
  /** Permits grants may use, and permits leases may hold, for one limit. */
42
43
  export const budgets = (provisioning, limit) => {
43
44
  if (provisioning.mode === 'over') {
@@ -1,4 +1,5 @@
1
1
  import * as v from 'valibot';
2
+ import { isNumber } from '../predicates.js';
2
3
  export const queueItemRowSchema = v.object({
3
4
  id: v.string(),
4
5
  key: v.string(),
@@ -250,7 +251,7 @@ export class QueueStore {
250
251
  WHERE channel = ? AND confirmed = 0
251
252
  )`, this.channel, this.channel, unnotified ? 1 : 0, notified ? 1 : 0, this.channel)
252
253
  .toArray()[0]?.['at'];
253
- return typeof at === 'number' ? at : undefined;
254
+ return isNumber(at) ? at : undefined;
254
255
  }
255
256
  items(query, ...bindings) {
256
257
  return v.parse(v.array(queueItemRowSchema), this.sql.exec(query, ...bindings).toArray());
@@ -58,7 +58,7 @@ export type DurabilitySemaphoreQueueConfig<Body> = SchedulerAttachment & {
58
58
  * Receives items once the holder has confirmed their permits, after the
59
59
  * admission commits. Retried until it returns; must be idempotent on item ID.
60
60
  */
61
- admit(items: AdmittedItem<Body>[]): unknown | Promise<unknown>;
61
+ admit(items: AdmittedItem<Body>[]): void | Promise<void>;
62
62
  /**
63
63
  * Returns which of these admitted items are done. The queue asks on its own
64
64
  * alarm and releases them, so a permit whose `release()` was lost (a
@@ -16,6 +16,7 @@ import { durabilitySemaphoreQueueMigrations } from './migrations.js';
16
16
  import { migrateCapability, } from '../migrations.js';
17
17
  import { DurabilityOutbox, stageWithin, } from '../outbox/index.js';
18
18
  import { assertPositiveInteger, } from '../policy.js';
19
+ import { isFunction, isNonEmptyString, isString } from '../predicates.js';
19
20
  import { DurabilityScheduler, assertChannel, defaultChannel, engineFor, } from '../scheduler/index.js';
20
21
  import { deserialize, serialize } from '../serialization.js';
21
22
  import { QueueStore, } from './queue-store.js';
@@ -38,6 +39,7 @@ const maxReportRetryMs = 5000;
38
39
  const demandScanLimit = 200;
39
40
  const maxDelayMs = 2 ** 31 - 1;
40
41
  const pairKey = (key, second) => JSON.stringify([key, second]);
42
+ // SAFETY: callers pass only outbox keys this queue staged, all built by pairKey.
41
43
  const parsePairKey = (value) => JSON.parse(value);
42
44
  const grantReport = (grant) => ({
43
45
  grantId: grant.grant_id,
@@ -46,12 +48,17 @@ const grantReport = (grant) => ({
46
48
  });
47
49
  // A lease stops drawing by moving its expiry to now, whoever retired it.
48
50
  const retiredLocally = (lease, now) => lease.expires_at <= now;
49
- const leaseReport = (lease) => ({
50
- leaseId: lease.lease_id,
51
- drawn: lease.drawn,
52
- released: lease.released,
53
- ...(retiredLocally(lease, Date.now()) ? { retired: true } : {}),
54
- });
51
+ const leaseReport = (lease) => {
52
+ const report = {
53
+ leaseId: lease.lease_id,
54
+ drawn: lease.drawn,
55
+ released: lease.released,
56
+ };
57
+ if (retiredLocally(lease, Date.now())) {
58
+ report.retired = true;
59
+ }
60
+ return report;
61
+ };
55
62
  /**
56
63
  * The holder sweeps a lease at its expiry by its own clock; stopping local
57
64
  * draws this long before it bounds the window a skewed clock could open.
@@ -94,10 +101,10 @@ export class DurabilitySemaphoreQueue {
94
101
  _DurabilitySemaphoreQueue_notifying.set(this, void 0);
95
102
  _DurabilitySemaphoreQueue_checking.set(this, void 0);
96
103
  const channel = assertChannel('Semaphore queue', config.channel ?? defaultChannel);
97
- if (typeof config.clientId !== 'string' || config.clientId.length === 0) {
104
+ if (!isNonEmptyString(config.clientId)) {
98
105
  throw new TypeError('clientId must be a non-empty string');
99
106
  }
100
- if (typeof config.admit !== 'function') {
107
+ if (!isFunction(config.admit)) {
101
108
  throw new TypeError('Semaphore queue requires an admit function');
102
109
  }
103
110
  __classPrivateFieldSet(this, _DurabilitySemaphoreQueue_server, config.server, "f");
@@ -109,8 +116,7 @@ export class DurabilitySemaphoreQueue {
109
116
  clientChannel: channel,
110
117
  }, "f");
111
118
  __classPrivateFieldSet(this, _DurabilitySemaphoreQueue_admit, config.admit, "f");
112
- if (config.finished !== undefined &&
113
- typeof config.finished !== 'function') {
119
+ if (config.finished !== undefined && !isFunction(config.finished)) {
114
120
  throw new TypeError('finished must be a function');
115
121
  }
116
122
  __classPrivateFieldSet(this, _DurabilitySemaphoreQueue_finished, config.finished, "f");
@@ -177,11 +183,9 @@ export class DurabilitySemaphoreQueue {
177
183
  async enqueue(items) {
178
184
  const rows = items.map((item) => {
179
185
  const id = item.id ?? crypto.randomUUID();
180
- if (typeof id !== 'string' ||
181
- id.length === 0 ||
182
- typeof item.key !== 'string' ||
183
- item.key.length === 0 ||
184
- (item.group !== undefined && typeof item.group !== 'string')) {
186
+ if (!isNonEmptyString(id) ||
187
+ !isNonEmptyString(item.key) ||
188
+ (item.group !== undefined && !isString(item.group))) {
185
189
  throw new TypeError('Semaphore items need a non-empty id, a semaphore key, and a string group');
186
190
  }
187
191
  const now = Date.now();
@@ -686,12 +690,15 @@ async function _DurabilitySemaphoreQueue_renewLeases(now) {
686
690
  }, _DurabilitySemaphoreQueue_stageReport = function _DurabilitySemaphoreQueue_stageReport(grant) {
687
691
  stageWithin(__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_outbox, "f"), __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_engine, "f").sql, pairKey(grant.key, `grant:${grant.grant_id}`), { kind: 'grant', claimed: grant.claimed, released: grant.released });
688
692
  }, _DurabilitySemaphoreQueue_stageLeaseReport = function _DurabilitySemaphoreQueue_stageLeaseReport(lease) {
689
- stageWithin(__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_outbox, "f"), __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_engine, "f").sql, pairKey(lease.key, `lease:${lease.lease_id}`), {
693
+ const report = {
690
694
  kind: 'lease',
691
695
  drawn: lease.drawn,
692
696
  released: lease.released,
693
- ...(retiredLocally(lease, Date.now()) ? { retired: true } : {}),
694
- });
697
+ };
698
+ if (retiredLocally(lease, Date.now())) {
699
+ report.retired = true;
700
+ }
701
+ stageWithin(__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_outbox, "f"), __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_engine, "f").sql, pairKey(lease.key, `lease:${lease.lease_id}`), report);
695
702
  }, _DurabilitySemaphoreQueue_publishReports =
696
703
  /** Outbox sink: one `sync` per key; a failed key keeps its entries pending. */
697
704
  async function _DurabilitySemaphoreQueue_publishReports(entries) {
@@ -713,12 +720,15 @@ async function _DurabilitySemaphoreQueue_publishReports(entries) {
713
720
  });
714
721
  }
715
722
  else {
716
- leases.push({
723
+ const report = {
717
724
  leaseId: id,
718
725
  drawn: entry.value.drawn,
719
726
  released: entry.value.released,
720
- ...(entry.value.retired ? { retired: true } : {}),
721
- });
727
+ };
728
+ if (entry.value.retired) {
729
+ report.retired = true;
730
+ }
731
+ leases.push(report);
722
732
  }
723
733
  }
724
734
  let synced;
@@ -754,7 +764,7 @@ async function _DurabilitySemaphoreQueue_publishReports(entries) {
754
764
  __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_instances, "m", _DurabilitySemaphoreQueue_refreshKey).call(this, key);
755
765
  });
756
766
  }));
757
- const onError = (error) => reportFailure('durability.semaphore_queue.notify_failed', {}, error);
767
+ const onError = (cause) => reportFailure('durability.semaphore_queue.notify_failed', {}, cause);
758
768
  __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_engine, "f").waitUntil(__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_instances, "m", _DurabilitySemaphoreQueue_notify).call(this).catch(onError), onError);
759
769
  }, _DurabilitySemaphoreQueue_releaseFinished =
760
770
  /** Releases admitted items `finished` reports done, one check at a time. */
@@ -843,6 +853,8 @@ async function _DurabilitySemaphoreQueue_notify() {
843
853
  id: row.id,
844
854
  key: row.key,
845
855
  group: row.grp,
856
+ // SAFETY: enqueue is the only writer of item payloads, each
857
+ // serialized from a Body.
846
858
  body: deserialize(row.payload),
847
859
  enqueuedAt: row.created_at,
848
860
  admittedAt: row.admitted_at ?? row.created_at,
@@ -16,6 +16,7 @@ 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
  });
@@ -93,9 +98,8 @@ export class DurabilitySemaphoreServer {
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");
@@ -206,7 +210,7 @@ _DurabilitySemaphoreServer_engine = new WeakMap(), _DurabilitySemaphoreServer_st
206
210
  __classPrivateFieldSet(this, _DurabilitySemaphoreServer_roundScheduled, true, "f");
207
211
  __classPrivateFieldGet(this, _DurabilitySemaphoreServer_engine, "f").timer.schedule(() => {
208
212
  __classPrivateFieldSet(this, _DurabilitySemaphoreServer_roundScheduled, false, "f");
209
- const onError = (error) => reportFailure('durability.semaphore.round_failed', {}, error);
213
+ const onError = (cause) => reportFailure('durability.semaphore.round_failed', {}, cause);
210
214
  __classPrivateFieldSet(this, _DurabilitySemaphoreServer_round, __classPrivateFieldGet(this, _DurabilitySemaphoreServer_instances, "m", _DurabilitySemaphoreServer_runRound).call(this)
211
215
  .catch(onError)
212
216
  .finally(() => {
@@ -247,15 +251,19 @@ _DurabilitySemaphoreServer_engine = new WeakMap(), _DurabilitySemaphoreServer_st
247
251
  __classPrivateFieldSet(this, _DurabilitySemaphoreServer_contended, round.contended, "f");
248
252
  for (const [entry, allocation] of round.allocations) {
249
253
  const { leases, ...rest } = allocation;
250
- entry.resolve({
254
+ const grant = {
251
255
  type: 'grant',
252
256
  ...acknowledgement(entry.request),
253
257
  ...rest,
254
258
  nextRequestAt,
255
- ...(entry.request.leases === undefined
256
- ? {}
257
- : { leases, ...(round.contended ? { contended: true } : {}) }),
258
- });
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);
259
267
  }
260
268
  for (const event of [...round.reclaimed, ...round.leaseEvents]) {
261
269
  __classPrivateFieldGet(this, _DurabilitySemaphoreServer_emit, "f").call(this, event);
@@ -451,17 +459,18 @@ _DurabilitySemaphoreServer_engine = new WeakMap(), _DurabilitySemaphoreServer_st
451
459
  : undefined;
452
460
  return { grantResults, leaseEchoes: leaseOutcome?.echoes };
453
461
  });
454
- return {
462
+ const synced = {
455
463
  type: 'synced',
456
464
  ...acknowledgement(message),
457
465
  grantResults: result.grantResults,
458
- ...(result.leaseEchoes === undefined
459
- ? {}
460
- : {
461
- leases: result.leaseEchoes,
462
- ...(__classPrivateFieldGet(this, _DurabilitySemaphoreServer_contended, "f") ? { contended: true } : {}),
463
- }),
464
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;
465
474
  }, _DurabilitySemaphoreServer_applyReports = function _DurabilitySemaphoreServer_applyReports(store, client, reports, now) {
466
475
  const results = [];
467
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)));