durability 4.1.2 → 4.3.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 (52) hide show
  1. package/README.md +406 -1
  2. package/dist/dev.d.ts +22 -0
  3. package/dist/dev.js +149 -0
  4. package/dist/durability-alarms.d.ts +1 -1
  5. package/dist/durability-alarms.js +6 -4
  6. package/dist/durability.d.ts +1 -1
  7. package/dist/durability.js +8 -5
  8. package/dist/durable-object-target.d.ts +12 -0
  9. package/dist/durable-object-target.js +17 -0
  10. package/dist/errors.d.ts +25 -0
  11. package/dist/errors.js +36 -0
  12. package/dist/experimental.d.ts +8 -0
  13. package/dist/experimental.js +6 -0
  14. package/dist/fanout.js +14 -9
  15. package/dist/index.d.ts +2 -1
  16. package/dist/index.js +1 -1
  17. package/dist/lifecycle.d.ts +14 -3
  18. package/dist/lifecycle.js +3 -2
  19. package/dist/log.js +26 -4
  20. package/dist/migrations.d.ts +74 -2
  21. package/dist/migrations.js +307 -36
  22. package/dist/outbox.d.ts +85 -0
  23. package/dist/outbox.js +433 -0
  24. package/dist/routing.d.ts +2 -9
  25. package/dist/routing.js +2 -14
  26. package/dist/scheduler.d.ts +14 -2
  27. package/dist/scheduler.js +38 -13
  28. package/dist/semaphore-client.d.ts +22 -0
  29. package/dist/semaphore-client.js +61 -0
  30. package/dist/semaphore-leases.d.ts +109 -0
  31. package/dist/semaphore-leases.js +272 -0
  32. package/dist/semaphore-protocol.d.ts +231 -0
  33. package/dist/semaphore-protocol.js +106 -0
  34. package/dist/semaphore-queue-store.d.ts +95 -0
  35. package/dist/semaphore-queue-store.js +248 -0
  36. package/dist/semaphore-queue.d.ts +119 -0
  37. package/dist/semaphore-queue.js +863 -0
  38. package/dist/semaphore-server.d.ts +89 -0
  39. package/dist/semaphore-server.js +518 -0
  40. package/dist/semaphore-store.d.ts +43 -0
  41. package/dist/semaphore-store.js +108 -0
  42. package/dist/semaphore.d.ts +42 -0
  43. package/dist/semaphore.js +57 -0
  44. package/dist/socket.js +19 -10
  45. package/dist/topology-client.d.ts +40 -0
  46. package/dist/topology-client.js +180 -0
  47. package/dist/topology-snapshot.d.ts +70 -0
  48. package/dist/topology-snapshot.js +48 -0
  49. package/dist/topology.d.ts +94 -0
  50. package/dist/topology.js +468 -0
  51. package/dist/tracker.js +2 -0
  52. package/package.json +6 -2
@@ -11,9 +11,10 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
11
11
  };
12
12
  var _DurabilityAlarmsCore_instances, _DurabilityAlarmsCore_engine, _DurabilityAlarmsCore_handlers, _DurabilityAlarmsCore_policy, _DurabilityAlarmsCore_lifecycle, _DurabilityAlarmsCore_emit, _DurabilityAlarmsCore_active, _DurabilityAlarmsCore_trackedSource, _DurabilityAlarmsCore_runDue, _DurabilityAlarmsCore_schedule, _DurabilityAlarmsCore_execute;
13
13
  import { z } from 'zod';
14
+ import { traceFunction, traceMethods } from './dev.js';
14
15
  import { DurableAlarmTimeoutError, DurableAttemptsExhaustedError, isErrorInstance, NonRetryableError, } from './errors.js';
15
16
  import { createLifecycleHooks, } from './lifecycle.js';
16
- import { durabilityNamedAlarmMigrations, migrate, } from './migrations.js';
17
+ import { durabilityNamedAlarmMigrations, migrateCapability, } from './migrations.js';
17
18
  import { alarmMethodOptionsSchema, createPolicyResolver, } from './policy.js';
18
19
  import { engineFor, } from './scheduler.js';
19
20
  import { deleteAttempt, listCreated } from './storage.js';
@@ -83,7 +84,7 @@ class DurabilityAlarmsCore {
83
84
  throw new Error(`"${name}" is reserved by DurabilityAlarms`);
84
85
  }
85
86
  Object.defineProperty(this, name, {
86
- value: (scheduledTime) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_schedule).call(this, name, scheduledTime),
87
+ value: traceFunction(`DurabilityAlarms.${name}`, (scheduledTime) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_schedule).call(this, name, scheduledTime)),
87
88
  enumerable: true,
88
89
  });
89
90
  }
@@ -94,9 +95,9 @@ class DurabilityAlarmsCore {
94
95
  });
95
96
  registerTrackedSource(this, __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_trackedSource).call(this));
96
97
  }
97
- /** Applies or reverts the `durability_alarms` schema; see {@link migrate}. */
98
+ /** Applies or reverts the `durability_alarms` schema; see {@link migrateCapability}. */
98
99
  static migrate(context, target) {
99
- return migrate(context.storage, 'namedAlarms', durabilityNamedAlarmMigrations, target);
100
+ return migrateCapability(context.storage, 'namedAlarms', durabilityNamedAlarmMigrations, target);
100
101
  }
101
102
  /** Runs due named alarms and re-arms the physical alarm. */
102
103
  alarm(info) {
@@ -259,6 +260,7 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
259
260
  isTerminal: (error) => isErrorInstance(error, DurableAlarmTimeoutError) && !retryTimeouts,
260
261
  });
261
262
  };
263
+ traceMethods(DurabilityAlarmsCore.prototype, 'DurabilityAlarms');
262
264
  // See Durability: members derived from the handler names cannot be declared on
263
265
  // the class, so the constructor is typed separately.
264
266
  export const DurabilityAlarms = DurabilityAlarmsCore;
@@ -133,7 +133,7 @@ export type DurabilityConfig<Handlers extends HandlerMap = HandlerMap> = Durabil
133
133
  declare class DurabilityCore<Handlers extends HandlerMap> {
134
134
  #private;
135
135
  constructor(config: DurabilityConfig<Handlers>);
136
- /** Applies or reverts the `durability_calls` schema; see {@link migrate}. */
136
+ /** Applies or reverts the `durability_calls` schema; see {@link migrateCapability}. */
137
137
  static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
138
138
  /** Processes due operations and re-arms the physical alarm. */
139
139
  alarm(info?: AlarmInvocationInfo): Promise<void>;
@@ -11,9 +11,10 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
11
11
  };
12
12
  var _DurabilityCore_instances, _DurabilityCore_engine, _DurabilityCore_handlers, _DurabilityCore_policy, _DurabilityCore_lifecycle, _DurabilityCore_emit, _DurabilityCore_active, _DurabilityCore_executionStarts, _DurabilityCore_trackedSource, _DurabilityCore_runDue, _DurabilityCore_getResult, _DurabilityCore_run, _DurabilityCore_execute, _DurabilityCore_start;
13
13
  import { z } from 'zod';
14
+ import { traceFunction, traceMethods } from './dev.js';
14
15
  import { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, isErrorInstance, NonRetryableError, reportFailure, } from './errors.js';
15
16
  import { createLifecycleHooks, } from './lifecycle.js';
16
- import { durabilityOperationMigrations, migrate, } from './migrations.js';
17
+ import { durabilityOperationMigrations, migrateCapability, } from './migrations.js';
17
18
  import { createPolicyResolver, methodOptionsSchema, } from './policy.js';
18
19
  import { engineFor, } from './scheduler.js';
19
20
  import { canonical, deserialize, serialize } from './serialization.js';
@@ -100,8 +101,9 @@ class DurabilityCore {
100
101
  if (reserved.has(operation)) {
101
102
  throw new Error(`"${operation}" is reserved by Durability`);
102
103
  }
103
- const method = (input) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_run).call(this, { ...input, operation });
104
- method.getResult = (idempotencyKey) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_getResult).call(this, operation, idempotencyKey);
104
+ const method = Object.assign(traceFunction(`Durability.${operation}`, (input) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_run).call(this, { ...input, operation })), {
105
+ getResult: traceFunction(`Durability.${operation}.getResult`, (idempotencyKey) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_getResult).call(this, operation, idempotencyKey)),
106
+ });
105
107
  Object.defineProperty(this, operation, {
106
108
  value: method,
107
109
  enumerable: true,
@@ -114,9 +116,9 @@ class DurabilityCore {
114
116
  });
115
117
  registerTrackedSource(this, __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_trackedSource).call(this));
116
118
  }
117
- /** Applies or reverts the `durability_calls` schema; see {@link migrate}. */
119
+ /** Applies or reverts the `durability_calls` schema; see {@link migrateCapability}. */
118
120
  static migrate(context, target) {
119
- return migrate(context.storage, 'operations', durabilityOperationMigrations, target);
121
+ return migrateCapability(context.storage, 'operations', durabilityOperationMigrations, target);
120
122
  }
121
123
  /** Processes due operations and re-arms the physical alarm. */
122
124
  alarm(info) {
@@ -317,6 +319,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
317
319
  isTerminal: (error) => isErrorInstance(error, DurableResultSerializationError),
318
320
  }, eagerPermit);
319
321
  };
322
+ traceMethods(DurabilityCore.prototype, 'Durability');
320
323
  // TypeScript cannot declare class members derived from a generic handler map,
321
324
  // so the constructor is typed separately; the constructor installs and reserves
322
325
  // every operation method at runtime.
@@ -0,0 +1,12 @@
1
+ /** An application-owned Durable Object class a client-side helper routes to. */
2
+ export type DurableObjectTarget<Target extends Rpc.DurableObjectBranded> = {
3
+ /** Application-owned exported Durable Object class. */
4
+ target: {
5
+ prototype: Target;
6
+ };
7
+ /** Injected by the Vite plugin; explicit for builds without it. */
8
+ exportName?: string;
9
+ /** Explicit namespace escape hatch for cross-worker or non-Vite consumers. */
10
+ namespace?: () => DurableObjectNamespace<Target>;
11
+ };
12
+ export declare const resolveNamespace: <Target extends Rpc.DurableObjectBranded>(config: DurableObjectTarget<Target>, error: (message: string) => Error) => DurableObjectNamespace<Target>;
@@ -0,0 +1,17 @@
1
+ import { exports as workerExports } from 'cloudflare:workers';
2
+ export const resolveNamespace = (config, error) => {
3
+ const namespace = config.namespace?.();
4
+ if (namespace) {
5
+ return namespace;
6
+ }
7
+ if (!config.exportName) {
8
+ throw error('Use the durability Vite plugin, exportName, or an explicit namespace to resolve the target');
9
+ }
10
+ const exported = Reflect.get(workerExports, config.exportName);
11
+ if (exported === null ||
12
+ (typeof exported !== 'object' && typeof exported !== 'function') ||
13
+ typeof Reflect.get(exported, 'getByName') !== 'function') {
14
+ throw error(`Export "${config.exportName}" is not a Durable Object namespace`);
15
+ }
16
+ return exported;
17
+ };
package/dist/errors.d.ts CHANGED
@@ -67,6 +67,10 @@ export declare class FanoutSettlementError extends Error {
67
67
  export declare class FanoutTimeoutError extends Error {
68
68
  constructor(timeoutMs: number);
69
69
  }
70
+ /** Error recorded when an outbox `publish` call exceeds its configured timeout. */
71
+ export declare class OutboxTimeoutError extends Error {
72
+ constructor(timeoutMs: number);
73
+ }
70
74
  /** A definite rejection before the batch was durably accepted. */
71
75
  export declare class FanoutEnqueueError extends Error {
72
76
  constructor(message: string);
@@ -93,6 +97,10 @@ export declare class LogTruncatedError extends Error {
93
97
  export declare class LogLeaseError extends Error {
94
98
  constructor(batchId: string);
95
99
  }
100
+ /** A malformed or unexpected semaphore message. */
101
+ export declare class SemaphoreProtocolError extends Error {
102
+ constructor(message: string);
103
+ }
96
104
  /** Error thrown when a sharding function returns an invalid shard key. */
97
105
  export declare class RoutingError extends Error {
98
106
  constructor(message: string);
@@ -107,3 +115,20 @@ export declare const isErrorInstance: (error: unknown, constructor: new (...args
107
115
  /** Recognizes this package's NonRetryableError and same-named errors from other packages. */
108
116
  export declare const isNonRetryable: (error: unknown) => boolean;
109
117
  export declare const reportFailure: (event: string, details: Record<string, unknown>, error: unknown) => void;
118
+ /** A definite rejection of a topology change or configuration. */
119
+ export declare class TopologyError extends Error {
120
+ constructor(message: string);
121
+ }
122
+ /** Why a topology client could not use the published snapshot. */
123
+ export type TopologyFallbackReason = 'missing' | 'invalid' | 'timeout' | 'error';
124
+ /**
125
+ * Thrown by a topology client when the published snapshot is unusable and no
126
+ * configured fallback produced one. The client never asks the coordinator.
127
+ */
128
+ export declare class TopologyUnavailableError extends Error {
129
+ readonly group: string;
130
+ readonly reason: TopologyFallbackReason;
131
+ constructor(group: string, reason: TopologyFallbackReason, options?: {
132
+ cause?: unknown;
133
+ });
134
+ }
package/dist/errors.js CHANGED
@@ -105,6 +105,13 @@ export class FanoutTimeoutError extends Error {
105
105
  this.name = 'FanoutTimeoutError';
106
106
  }
107
107
  }
108
+ /** Error recorded when an outbox `publish` call exceeds its configured timeout. */
109
+ export class OutboxTimeoutError extends Error {
110
+ constructor(timeoutMs) {
111
+ super(`Outbox publication timed out after ${timeoutMs}ms`);
112
+ this.name = 'OutboxTimeoutError';
113
+ }
114
+ }
108
115
  /** A definite rejection before the batch was durably accepted. */
109
116
  export class FanoutEnqueueError extends Error {
110
117
  constructor(message) {
@@ -143,6 +150,13 @@ export class LogLeaseError extends Error {
143
150
  this.name = 'LogLeaseError';
144
151
  }
145
152
  }
153
+ /** A malformed or unexpected semaphore message. */
154
+ export class SemaphoreProtocolError extends Error {
155
+ constructor(message) {
156
+ super(message);
157
+ this.name = 'SemaphoreProtocolError';
158
+ }
159
+ }
146
160
  /** Error thrown when a sharding function returns an invalid shard key. */
147
161
  export class RoutingError extends Error {
148
162
  constructor(message) {
@@ -220,3 +234,25 @@ export const reportFailure = (event, details, error) => {
220
234
  return;
221
235
  }
222
236
  };
237
+ /** A definite rejection of a topology change or configuration. */
238
+ export class TopologyError extends Error {
239
+ constructor(message) {
240
+ super(message);
241
+ this.name = 'TopologyError';
242
+ }
243
+ }
244
+ /**
245
+ * Thrown by a topology client when the published snapshot is unusable and no
246
+ * configured fallback produced one. The client never asks the coordinator.
247
+ */
248
+ export class TopologyUnavailableError extends Error {
249
+ constructor(group, reason, options) {
250
+ super(`Topology for group "${group}" is unavailable: ${reason}`);
251
+ this.group = group;
252
+ this.reason = reason;
253
+ this.name = 'TopologyUnavailableError';
254
+ if (options?.cause !== undefined) {
255
+ Object.defineProperty(this, 'cause', { value: options.cause });
256
+ }
257
+ }
258
+ }
@@ -6,3 +6,11 @@
6
6
  */
7
7
  export { DurabilityTracker, type DurabilityTrackerConfig, type TrackedHandle, type TrackedItem, type TrackedResult, type TrackedWaitOptions, type TrackerHandle, type TrackerPage, type TrackerQuery, type TrackerRecord, type TrackerRecordPage, } from './tracker.js';
8
8
  export type { TrackedEntry, TrackedPage, TrackedQuery, TrackedRecord, TrackedResults, TrackedSource, TrackedState, TrackedStatus, } from './tracked-source.js';
9
+ export { DurabilityOutbox, type DurabilityOutboxConfig, type DurabilityOutboxEvent, type OutboxEntry, } from './outbox.js';
10
+ export { OutboxTimeoutError } from './errors.js';
11
+ export { durabilityOutboxMigrations } from './migrations.js';
12
+ export { DurabilityTopology, type DurabilityTopologyConfig, type DurabilityTopologyEvent, type TopologyChannel, type TopologyCurrent, type TopologyDraft, type TopologyPublisher, type TopologyRetryOptions, type TopologyRole, type TopologyStateUpdate, } from './topology.js';
13
+ export type { TopologyClient, TopologyClientConfig, TopologySource, TopologyView, } from './topology-client.js';
14
+ export type { TopologyMember, TopologyMemberInput, TopologyMemberState, TopologySnapshot, } from './topology-snapshot.js';
15
+ export { TopologyError, TopologyUnavailableError, type TopologyFallbackReason, } from './errors.js';
16
+ export { durabilityTopologyMigrations } from './migrations.js';
@@ -5,3 +5,9 @@
5
5
  * @packageDocumentation
6
6
  */
7
7
  export { DurabilityTracker, } from './tracker.js';
8
+ export { DurabilityOutbox, } from './outbox.js';
9
+ export { OutboxTimeoutError } from './errors.js';
10
+ export { durabilityOutboxMigrations } from './migrations.js';
11
+ export { DurabilityTopology, } from './topology.js';
12
+ export { TopologyError, TopologyUnavailableError, } from './errors.js';
13
+ export { durabilityTopologyMigrations } from './migrations.js';
package/dist/fanout.js CHANGED
@@ -11,10 +11,11 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
11
11
  };
12
12
  var _DurabilityFanout_instances, _DurabilityFanout_engine, _DurabilityFanout_routing, _DurabilityFanout_targets, _DurabilityFanout_policies, _DurabilityFanout_dlq, _DurabilityFanout_maxBatchSize, _DurabilityFanout_batchDelayMs, _DurabilityFanout_lifecycle, _DurabilityFanout_emit, _DurabilityFanout_running, _DurabilityFanout_pending, _DurabilityFanout_firstAttemptAt, _DurabilityFanout_runDue, _DurabilityFanout_runTarget, _DurabilityFanout_postpone, _DurabilityFanout_deliver, _DurabilityFanout_ackUnsettled, _DurabilityFanout_message, _DurabilityFanout_remove, _DurabilityFanout_removeDelivery, _DurabilityFanout_retry, _DurabilityFanout_deadLetter, _DurabilityFanout_emitTerminal, _DurabilityFanout_transaction, _DurabilityFanout_pendingCount, _DurabilityFanout_adjustPending, _DurabilityFanout_listDue, _DurabilityFanout_deadline;
13
13
  import { z } from 'zod';
14
+ import { traceFunction, traceMethods } from './dev.js';
14
15
  import { DurableRetryPolicyError, FanoutEnqueueError, FanoutSettlementError, FanoutTimeoutError, reportFailure, serializeError, } from './errors.js';
15
16
  import { createLifecycleHooks, } from './lifecycle.js';
16
17
  import { RoutingLoad } from './load.js';
17
- import { durabilityFanoutMigrations, migrate } from './migrations.js';
18
+ import { durabilityFanoutMigrations, migrateCapability } from './migrations.js';
18
19
  import { assertPositiveInteger, createPolicyResolver, methodOptionsSchema, } from './policy.js';
19
20
  import { engineFor, } from './scheduler.js';
20
21
  import { deserialize, serialize } from './serialization.js';
@@ -125,7 +126,7 @@ export class DurabilityFanout {
125
126
  });
126
127
  }
127
128
  static migrate(context, target) {
128
- return migrate(context.storage, 'fanout', durabilityFanoutMigrations, target);
129
+ return migrateCapability(context.storage, 'fanout', durabilityFanoutMigrations, target);
129
130
  }
130
131
  alarm(info) {
131
132
  return __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").alarm(info);
@@ -501,6 +502,10 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
501
502
  }
502
503
  }, _DurabilityFanout_message = function _DurabilityFanout_message(state, policy, startedAt) {
503
504
  const { row, message } = state.claim;
505
+ const identity = {
506
+ deliveryId: deliveryIdentity(row),
507
+ target: row.target_id,
508
+ };
504
509
  const settle = (outcome, action) => {
505
510
  if (state.closed || state.outcome !== undefined) {
506
511
  return Promise.reject(new FanoutSettlementError(message.id, state.outcome));
@@ -519,12 +524,11 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
519
524
  };
520
525
  return {
521
526
  id: message.id,
522
- deliveryId: deliveryIdentity(row),
523
- target: row.target_id,
527
+ ...identity,
524
528
  body: deserialize(message.payload),
525
529
  enqueuedAt: message.created_at,
526
530
  attempt: row.attempt,
527
- ack: () => settle('ack', async () => {
531
+ ack: traceFunction('DurabilityFanoutMessage.ack', () => settle('ack', async () => {
528
532
  await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_remove).call(this, row);
529
533
  __classPrivateFieldGet(this, _DurabilityFanout_emit, "f").call(this, {
530
534
  ...entity(state.claim),
@@ -534,8 +538,8 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
534
538
  durationMs: Math.max(0, Date.now() - startedAt),
535
539
  outcome: 'completed',
536
540
  });
537
- }),
538
- retry: (delayMs) => {
541
+ }), identity),
542
+ retry: traceFunction('DurabilityFanoutMessage.retry', (delayMs) => {
539
543
  if (delayMs !== undefined &&
540
544
  (!Number.isSafeInteger(delayMs) ||
541
545
  delayMs < 0 ||
@@ -543,8 +547,8 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
543
547
  return Promise.reject(new RangeError('delayMs must produce a non-negative safe-integer timestamp'));
544
548
  }
545
549
  return settle('retry', () => __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_retry).call(this, state.claim, policy, delayMs, { name: 'Retry', message: 'Retried by consumer' }, startedAt));
546
- },
547
- deadLetter: () => settle('deadLetter', () => __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_deadLetter).call(this, state.claim, 'explicit')),
550
+ }, identity),
551
+ deadLetter: traceFunction('DurabilityFanoutMessage.deadLetter', () => settle('deadLetter', () => __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_deadLetter).call(this, state.claim, 'explicit')), identity),
548
552
  };
549
553
  }, _DurabilityFanout_remove = async function _DurabilityFanout_remove(row) {
550
554
  await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_transaction).call(this, (sql) => {
@@ -706,3 +710,4 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
706
710
  }
707
711
  }
708
712
  };
713
+ traceMethods(DurabilityFanout.prototype, 'DurabilityFanout');
package/dist/index.d.ts CHANGED
@@ -7,5 +7,6 @@ export type { MessageWrite, StoredMessage } from './stored-message.js';
7
7
  export { DurabilityScheduler, type DurabilityContext, type DurabilitySchedulerConfig, type DurabilitySchedulerOptions, type SchedulerAttachment, } from './scheduler.js';
8
8
  export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
9
9
  export type { DurabilityLifecycleEvent, LifecycleHook } from './lifecycle.js';
10
- export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, type DurabilityMigrationResult, type MigrationCapability, } from './migrations.js';
10
+ export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, migrate, type DurabilityMigrationResult, type MigrateOptions, type MigrationCapability, } from './migrations.js';
11
+ export type { DurableMigrations } from '@durability/storage';
11
12
  export type { DurabilityAlarmMethodOptions, DurabilityMethodOptions, DurabilityRetryOptions, } from './policy.js';
package/dist/index.js CHANGED
@@ -5,4 +5,4 @@ export { DurabilityLog, maxLogBytes, } from './log.js';
5
5
  export { RoutingLoad, } from './load.js';
6
6
  export { DurabilityScheduler, } from './scheduler.js';
7
7
  export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
8
- export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, } from './migrations.js';
8
+ export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, migrate, } from './migrations.js';
@@ -17,7 +17,15 @@ export type FanoutLifecycleEntity = {
17
17
  target: string;
18
18
  generation: string;
19
19
  };
20
- export type LifecycleEntity = OperationLifecycleEntity | AlarmLifecycleEntity | FanoutLifecycleEntity;
20
+ export type OutboxLifecycleEntity = {
21
+ entityKind: 'outbox_entry';
22
+ channel: string;
23
+ /** The staged key. */
24
+ id: string;
25
+ /** The staged version, as a string. */
26
+ generation: string;
27
+ };
28
+ export type LifecycleEntity = OperationLifecycleEntity | AlarmLifecycleEntity | FanoutLifecycleEntity | OutboxLifecycleEntity;
21
29
  type AttemptSettled = {
22
30
  type: 'attempt_settled';
23
31
  timestamp: number;
@@ -25,7 +33,7 @@ type AttemptSettled = {
25
33
  durationMs: number;
26
34
  };
27
35
  /** Best-effort metrics signal for queue lifecycle changes. */
28
- export type DurabilityLifecycleEvent = ((OperationLifecycleEntity | FanoutLifecycleEntity) & {
36
+ export type DurabilityLifecycleEvent = ((OperationLifecycleEntity | FanoutLifecycleEntity | OutboxLifecycleEntity) & {
29
37
  type: 'registered';
30
38
  timestamp: number;
31
39
  attempt: 0;
@@ -74,5 +82,8 @@ export declare const createLifecycleHooks: (emitter: (hook: LifecycleHook) => Em
74
82
  * Wraps a consumer hook so it can never affect queue state: synchronous throws
75
83
  * and rejections are logged, and promises ride on `waitUntil` when available.
76
84
  */
77
- export declare const createEmitter: (hook: LifecycleHook | undefined, waitUntil: ((promise: Promise<unknown>) => void) | undefined) => Emit;
85
+ export declare const createEmitter: <Event extends {
86
+ entityKind: string;
87
+ type: string;
88
+ } = DurabilityLifecycleEvent>(hook: ((event: Event) => void | Promise<void>) | undefined, waitUntil: ((promise: Promise<unknown>) => void) | undefined) => ((event: Event) => void);
78
89
  export {};
package/dist/lifecycle.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { traceLifecycle } from './dev.js';
1
2
  import { reportFailure } from './errors.js';
2
3
  /** Fans one helper's lifecycle events out to every attached hook. */
3
4
  export const createLifecycleHooks = (emitter, initial) => {
@@ -13,11 +14,11 @@ export const createLifecycleHooks = (emitter, initial) => {
13
14
  add(initial);
14
15
  }
15
16
  return {
16
- emit: (event) => {
17
+ emit: traceLifecycle((event) => {
17
18
  for (const emit of emits) {
18
19
  emit(event);
19
20
  }
20
- },
21
+ }),
21
22
  add,
22
23
  };
23
24
  };
package/dist/log.js CHANGED
@@ -9,11 +9,12 @@ 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 _DurabilityLog_instances, _DurabilityLog_engine, _DurabilityLog_routing, _DurabilityLog_retention, _DurabilityLog_cold, _DurabilityLog_leases, _DurabilityLog_maxParallelism, _DurabilityLog_leaseMs, _DurabilityLog_maxBatchSize, _DurabilityLog_encoder, _DurabilityLog_rehydrate, _DurabilityLog_record, _DurabilityLog_settle, _DurabilityLog_advance, _DurabilityLog_between, _DurabilityLog_readFrom, _DurabilityLog_requireLeases;
12
+ var _DurabilityLog_instances, _DurabilityLog_engine, _DurabilityLog_routing, _DurabilityLog_retention, _DurabilityLog_cold, _DurabilityLog_leases, _DurabilityLog_maxParallelism, _DurabilityLog_leaseMs, _DurabilityLog_maxBatchSize, _DurabilityLog_encoder, _DurabilityLog_rehydrate, _DurabilityLog_record, _DurabilityLog_settle, _DurabilityLog_dropTrimmed, _DurabilityLog_advance, _DurabilityLog_between, _DurabilityLog_readFrom, _DurabilityLog_requireLeases;
13
13
  import { z } from 'zod';
14
+ import { traceMethods } from './dev.js';
14
15
  import { LogAppendError, LogLeaseError, LogTruncatedError, reportFailure, serializeError, } from './errors.js';
15
16
  import { RoutingLoad } from './load.js';
16
- import { durabilityLogLeaseMigrations, durabilityLogMigrations, migrate, } from './migrations.js';
17
+ import { durabilityLogLeaseMigrations, durabilityLogMigrations, migrateCapability, } from './migrations.js';
17
18
  import { assertPositiveInteger } from './policy.js';
18
19
  import { engineFor, } from './scheduler.js';
19
20
  import { deserialize, serialize } from './serialization.js';
@@ -321,7 +322,7 @@ export class DurabilityLog {
321
322
  __classPrivateFieldGet(this, _DurabilityLog_engine, "f").migrateSchema('log', durabilityLogMigrations);
322
323
  }
323
324
  static migrate(context, target) {
324
- return migrate(context.storage, 'log', durabilityLogMigrations, target);
325
+ return migrateCapability(context.storage, 'log', durabilityLogMigrations, target);
325
326
  }
326
327
  /**
327
328
  * Appends the batch atomically. Definite input rejections return
@@ -518,6 +519,11 @@ export class DurabilityLog {
518
519
  const sql = __classPrivateFieldGet(this, _DurabilityLog_engine, "f").sql;
519
520
  const reclaimed = claimExpired(sql, consumer, now, crypto.randomUUID(), now + __classPrivateFieldGet(this, _DurabilityLog_leaseMs, "f"));
520
521
  if (reclaimed) {
522
+ const { oldestOffset } = readBounds(sql);
523
+ if (reclaimed.first_offset < oldestOffset) {
524
+ __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_dropTrimmed).call(this, consumer, reclaimed, oldestOffset);
525
+ throw new LogTruncatedError(reclaimed.first_offset, oldestOffset);
526
+ }
521
527
  const poisoned = leases.maxAttempts !== undefined &&
522
528
  leases.onPoison !== undefined &&
523
529
  reclaimed.attempt > leases.maxAttempts;
@@ -651,9 +657,24 @@ async function _DurabilityLog_rehydrate(from, limit, bounds) {
651
657
  // Either the batch never existed, was fenced by a redelivery, or was
652
658
  // already settled; all three are the caller holding a stale handle.
653
659
  throw new LogLeaseError(batchId);
660
+ }, _DurabilityLog_dropTrimmed = function _DurabilityLog_dropTrimmed(consumer, lease, oldestOffset) {
661
+ __classPrivateFieldGet(this, _DurabilityLog_engine, "f").transactionSync((sql) => {
662
+ if (lease.last_offset < oldestOffset) {
663
+ deleteLeases(sql, [lease.batch_id]);
664
+ }
665
+ else {
666
+ sql.exec(`UPDATE durability_log_leases
667
+ SET first_offset = ?, state = 'pending', attempt = attempt - 1,
668
+ expires_at = 0
669
+ WHERE batch_id = ?`, oldestOffset, lease.batch_id);
670
+ }
671
+ __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_advance).call(this, consumer);
672
+ });
654
673
  }, _DurabilityLog_advance = function _DurabilityLog_advance(consumer) {
655
674
  const sql = __classPrivateFieldGet(this, _DurabilityLog_engine, "f").sql;
656
- const from = readCursor(sql, consumer) ?? 0;
675
+ // Offsets below the retained window are gone for everyone; a cursor
676
+ // stranded there could never meet the ranges leased after them.
677
+ const from = Math.max(readCursor(sql, consumer) ?? 0, readBounds(sql).oldestOffset);
657
678
  const candidates = leasesFrom(sql, consumer, from, __classPrivateFieldGet(this, _DurabilityLog_maxBatchSize, "f"));
658
679
  let cursor = from;
659
680
  const settled = [];
@@ -688,6 +709,7 @@ async function _DurabilityLog_between(first, last) {
688
709
  }
689
710
  return __classPrivateFieldGet(this, _DurabilityLog_leases, "f");
690
711
  };
712
+ traceMethods(DurabilityLog.prototype, 'DurabilityLog');
691
713
  const assertConsumer = (consumer) => {
692
714
  if (typeof consumer !== 'string' || consumer.length === 0) {
693
715
  throw new LogAppendError('Consumer must be a non-empty string');
@@ -55,6 +55,43 @@ export declare const durabilityLogLeaseMigrations: {
55
55
  up: string;
56
56
  down: string;
57
57
  }[];
58
+ /**
59
+ * Ordered SQLite migrations for outbox channels. Applied automatically on
60
+ * construction.
61
+ */
62
+ export declare const durabilityOutboxMigrations: {
63
+ name: string;
64
+ up: string;
65
+ down: string;
66
+ }[];
67
+ /**
68
+ * Ordered SQLite migrations for semaphore grants. Applied automatically on
69
+ * construction.
70
+ */
71
+ export declare const durabilitySemaphoreMigrations: {
72
+ name: string;
73
+ up: string;
74
+ down: string;
75
+ }[];
76
+ /**
77
+ * Ordered SQLite migrations for a semaphore client's queue. Applied
78
+ * automatically on construction.
79
+ */
80
+ export declare const durabilitySemaphoreQueueMigrations: {
81
+ name: string;
82
+ up: string;
83
+ down: string;
84
+ }[];
85
+ /**
86
+ * Ordered SQLite migrations for the experimental topology coordinator.
87
+ * Publication and sync ride on outbox channels. Applied automatically on
88
+ * construction.
89
+ */
90
+ export declare const durabilityTopologyMigrations: {
91
+ name: string;
92
+ up: string;
93
+ down: string;
94
+ }[];
58
95
  /** Migration names changed by one migrate call. */
59
96
  export type DurabilityMigrationResult = {
60
97
  /** Migrations applied in ascending order. */
@@ -62,7 +99,7 @@ export type DurabilityMigrationResult = {
62
99
  /** Migrations reverted in descending order. */
63
100
  rolledBack: string[];
64
101
  };
65
- export type MigrationCapability = 'operations' | 'namedAlarms' | 'fanout' | 'socket' | 'log' | 'logLeases';
102
+ export type MigrationCapability = 'operations' | 'namedAlarms' | 'fanout' | 'socket' | 'log' | 'logLeases' | 'outbox' | 'semaphore' | 'semaphoreQueue' | 'topology';
66
103
  type MigrationStorage = Pick<DurableObjectStorage, 'sql' | 'transactionSync'>;
67
104
  /**
68
105
  * Moves one capability's schema to a target migration, applying or reverting as
@@ -73,5 +110,40 @@ type MigrationStorage = Pick<DurableObjectStorage, 'sql' | 'transactionSync'>;
73
110
  * downgrade of the library can still revert it. Batches of migrations apply or
74
111
  * revert atomically.
75
112
  */
76
- export declare const migrate: (storage: MigrationStorage, capability: MigrationCapability, migrations: DurableMigrations, target: string | null | undefined) => DurabilityMigrationResult;
113
+ export declare const migrateCapability: (storage: MigrationStorage, capability: MigrationCapability, migrations: DurableMigrations, target: string | null | undefined) => DurabilityMigrationResult;
114
+ /** Options for {@link migrate}. */
115
+ export type MigrateOptions = {
116
+ /** History table for these migrations. Defaults to `schema_migrations`. */
117
+ table?: string;
118
+ /**
119
+ * Migration to move the schema to. Defaults to the last one; `null` reverts
120
+ * every migration.
121
+ */
122
+ target?: string | null;
123
+ };
124
+ /**
125
+ * Moves an application's own schema to a target migration, with the same
126
+ * guarantees durability gives its tables: each batch applies or reverts in one
127
+ * synchronous transaction, every history row stores its `down` script, and a
128
+ * Durable Object running older code reverts up to two migrations it does not
129
+ * know before refusing.
130
+ *
131
+ * The history lives in its own table, apart from `durability_migrations`, and
132
+ * is dropped once no migration remains applied.
133
+ *
134
+ * @example
135
+ * ```ts
136
+ * constructor(ctx: DurableObjectState, env: Env) {
137
+ * super(ctx, env);
138
+ * migrate(ctx.storage, [
139
+ * {
140
+ * name: '0001_create_jobs',
141
+ * up: 'CREATE TABLE jobs (id TEXT PRIMARY KEY);',
142
+ * down: 'DROP TABLE jobs;',
143
+ * },
144
+ * ]);
145
+ * }
146
+ * ```
147
+ */
148
+ export declare const migrate: (storage: MigrationStorage, migrations: DurableMigrations, options?: MigrateOptions) => DurabilityMigrationResult;
77
149
  export {};