durability 4.3.0 → 5.1.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.
@@ -2,6 +2,7 @@ import { type DurabilityLifecycleEvent, type LifecycleHook } from './lifecycle.j
2
2
  import { type DurabilityMigrationResult } from './migrations.js';
3
3
  import { type DurabilityMethodOptions, type ExecutionPolicyOptions } from './policy.js';
4
4
  import { type SchedulerAttachment } from './scheduler.js';
5
+ import { type DurableMemoize } from './memoize.js';
5
6
  /**
6
7
  * The context passed to a durable operation handler for each attempt.
7
8
  *
@@ -16,16 +17,27 @@ import { type SchedulerAttachment } from './scheduler.js';
16
17
  * ```
17
18
  */
18
19
  export type DurableCall<Payload> = {
19
- /** The stable idempotency key supplied when the operation was registered. */
20
+ /**
21
+ * The stable idempotency key supplied when the operation was registered. This
22
+ * is the operation's logical identity: key any external deduplication or
23
+ * once-only effect by `id`, never by `attempt`.
24
+ */
20
25
  id: string;
21
26
  /** The handler name used to register the operation. */
22
27
  operation: string;
23
28
  /** The JSON-serializable payload supplied when the operation was registered. */
24
29
  payload: Payload;
25
- /** The one-based attempt number. */
30
+ /**
31
+ * The one-based attempt ordinal, durably recorded before the handler runs. It
32
+ * is retry and logging context, not a record of what the handler did: never
33
+ * gate once-only work on it (such as `attempt === 1`). Key such work on
34
+ * durable state keyed by `id` instead. See the README identity glossary.
35
+ */
26
36
  attempt: number;
27
37
  /** Aborts when the attempt exceeds its configured timeout. */
28
38
  signal: AbortSignal;
39
+ /** Persists a callback's result by key so a retry of this operation reuses it. */
40
+ memoize: DurableMemoize;
29
41
  };
30
42
  /** A function that executes one attempt of a durable operation. */
31
43
  export type DurableHandler<Payload, Result> = (call: DurableCall<Payload>) => Result | Promise<Result>;
@@ -83,13 +95,15 @@ type TypedOperationEvent<Operation extends string, Result> = OperationEvent exte
83
95
  outcome: 'completed';
84
96
  } ? Omit<Event, 'operation' | 'result'> & {
85
97
  operation: Operation;
86
- result: Result;
98
+ /** Present only when the instance was created with `includeResults: true`. */
99
+ result?: Result;
87
100
  } : Event extends object ? Omit<Event, 'operation'> & {
88
101
  operation: Operation;
89
102
  } : never : never;
90
103
  /**
91
104
  * A lifecycle event for one of this instance's operations. Completed events
92
- * carry the handler's typed result.
105
+ * carry the handler's typed result only when the instance is created with
106
+ * `includeResults: true`.
93
107
  */
94
108
  export type DurabilityOperationEvent<Handlers extends HandlerMap> = {
95
109
  [Operation in Extract<keyof Handlers, string>]: TypedOperationEvent<Operation, HandlerResult<Handlers[Operation]>>;
@@ -120,6 +134,12 @@ export type DurabilityOptions<Handlers extends HandlerMap = HandlerMap> = Execut
120
134
  methods?: Partial<Record<Extract<keyof NoInfer<Handlers>, string>, DurabilityMethodOptions>>;
121
135
  /** Receives best-effort, non-durable lifecycle metrics events. */
122
136
  onLifecycleEvent?: LifecycleHook;
137
+ /**
138
+ * Attach the handler's return value to `completed` lifecycle events.
139
+ * Off by default so results never reach telemetry sinks unintentionally;
140
+ * enable only when the sink is trusted with result content.
141
+ */
142
+ includeResults?: boolean;
123
143
  };
124
144
  /**
125
145
  * Constructor configuration: the operation handlers, their policies, and
@@ -152,11 +172,16 @@ type OperationMethods<Handlers extends HandlerMap> = {
152
172
  [Operation in keyof Handlers]: DurableOperation<Handlers[Operation]>;
153
173
  };
154
174
  /**
155
- * Alarm-backed, effectively-once durable operations for one Durable Object.
175
+ * Alarm-backed, at-least-once durable operations for one Durable Object.
156
176
  *
157
177
  * Every handler becomes a typed method on the instance. Methods resolve once
158
178
  * the call is durably registered; read outcomes through `getResult`.
159
179
  *
180
+ * Delivery is at least once: a handler may run again after a crash, timeout, or
181
+ * eviction. The call `id` is a stable idempotency key; pass it to external
182
+ * systems and make effects idempotent or reconcilable to reach an effectively
183
+ * once outcome. See the README "Delivery and safety contract".
184
+ *
160
185
  * @example
161
186
  * ```ts
162
187
  * class ImageJobs extends DurableObject<Env> {
@@ -9,15 +9,16 @@ 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 _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;
12
+ var _DurabilityCore_instances, _DurabilityCore_engine, _DurabilityCore_handlers, _DurabilityCore_policy, _DurabilityCore_lifecycle, _DurabilityCore_emit, _DurabilityCore_includeResults, _DurabilityCore_active, _DurabilityCore_executionStarts, _DurabilityCore_trackedSource, _DurabilityCore_runDue, _DurabilityCore_getResult, _DurabilityCore_run, _DurabilityCore_execute, _DurabilityCore_start;
13
13
  import { z } from 'zod';
14
14
  import { traceFunction, traceMethods } from './dev.js';
15
15
  import { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, isErrorInstance, NonRetryableError, reportFailure, } from './errors.js';
16
16
  import { createLifecycleHooks, } from './lifecycle.js';
17
- import { durabilityOperationMigrations, migrateCapability, } from './migrations.js';
17
+ import { durabilityOperationMigrations, durabilityMemoMigrations, migrateCapability, } from './migrations.js';
18
18
  import { createPolicyResolver, methodOptionsSchema, } from './policy.js';
19
19
  import { engineFor, } from './scheduler.js';
20
20
  import { canonical, deserialize, serialize } from './serialization.js';
21
+ import { createMemoize, deleteMemosOfDroppedTable, memoizedKeys, } from './memoize.js';
21
22
  import { listCreated, updateAttempt } from './storage.js';
22
23
  import { registerTrackedSource, } from './tracked-source.js';
23
24
  const callRowSchema = z.object({
@@ -67,13 +68,21 @@ const callState = (call) => {
67
68
  }
68
69
  return { status: 'completed', result: deserialize(call.result) };
69
70
  };
70
- const callRecord = (call) => ({
71
- id: call.id,
72
- name: call.operation,
73
- generation: call.generation_id,
74
- createdAt: call.created_at,
75
- state: callState(call),
76
- });
71
+ const callRecord = (sql, call) => {
72
+ const state = callState(call);
73
+ return {
74
+ id: call.id,
75
+ name: call.operation,
76
+ generation: call.generation_id,
77
+ createdAt: call.created_at,
78
+ state: state.status === 'pending'
79
+ ? {
80
+ ...state,
81
+ memoized: memoizedKeys(sql, callsTable, call.id, call.generation_id),
82
+ }
83
+ : state,
84
+ };
85
+ };
77
86
  const operationEntity = (call) => ({
78
87
  entityKind: 'operation',
79
88
  operation: call.operation,
@@ -88,6 +97,7 @@ class DurabilityCore {
88
97
  _DurabilityCore_policy.set(this, void 0);
89
98
  _DurabilityCore_lifecycle.set(this, void 0);
90
99
  _DurabilityCore_emit.set(this, void 0);
100
+ _DurabilityCore_includeResults.set(this, void 0);
91
101
  _DurabilityCore_active.set(this, new Map());
92
102
  _DurabilityCore_executionStarts.set(this, new Map());
93
103
  const { handlers } = config;
@@ -96,6 +106,7 @@ class DurabilityCore {
96
106
  __classPrivateFieldSet(this, _DurabilityCore_policy, createPolicyResolver(config, config.methods ?? {}, methodOptionsSchema), "f");
97
107
  __classPrivateFieldSet(this, _DurabilityCore_lifecycle, createLifecycleHooks((hook) => __classPrivateFieldGet(this, _DurabilityCore_engine, "f").emitter(hook), config.onLifecycleEvent), "f");
98
108
  __classPrivateFieldSet(this, _DurabilityCore_emit, __classPrivateFieldGet(this, _DurabilityCore_lifecycle, "f").emit, "f");
109
+ __classPrivateFieldSet(this, _DurabilityCore_includeResults, config.includeResults ?? false, "f");
99
110
  const reserved = new Set(Object.getOwnPropertyNames(DurabilityCore.prototype));
100
111
  for (const operation of Object.keys(handlers)) {
101
112
  if (reserved.has(operation)) {
@@ -110,6 +121,7 @@ class DurabilityCore {
110
121
  });
111
122
  }
112
123
  __classPrivateFieldGet(this, _DurabilityCore_engine, "f").migrateSchema('operations', durabilityOperationMigrations);
124
+ __classPrivateFieldGet(this, _DurabilityCore_engine, "f").migrateSchema('memos', durabilityMemoMigrations);
113
125
  __classPrivateFieldGet(this, _DurabilityCore_engine, "f").register({
114
126
  table: callsTable,
115
127
  runDue: (now) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_runDue).call(this, now),
@@ -118,7 +130,9 @@ class DurabilityCore {
118
130
  }
119
131
  /** Applies or reverts the `durability_calls` schema; see {@link migrateCapability}. */
120
132
  static migrate(context, target) {
121
- return migrateCapability(context.storage, 'operations', durabilityOperationMigrations, target);
133
+ const result = migrateCapability(context.storage, 'operations', durabilityOperationMigrations, target);
134
+ deleteMemosOfDroppedTable(context.storage.sql, callsTable);
135
+ return result;
122
136
  }
123
137
  /** Processes due operations and re-arms the physical alarm. */
124
138
  alarm(info) {
@@ -147,12 +161,12 @@ class DurabilityCore {
147
161
  return count;
148
162
  }
149
163
  }
150
- _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap(), _DurabilityCore_policy = new WeakMap(), _DurabilityCore_lifecycle = new WeakMap(), _DurabilityCore_emit = new WeakMap(), _DurabilityCore_active = new WeakMap(), _DurabilityCore_executionStarts = new WeakMap(), _DurabilityCore_instances = new WeakSet(), _DurabilityCore_trackedSource = function _DurabilityCore_trackedSource() {
164
+ _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap(), _DurabilityCore_policy = new WeakMap(), _DurabilityCore_lifecycle = new WeakMap(), _DurabilityCore_emit = new WeakMap(), _DurabilityCore_includeResults = new WeakMap(), _DurabilityCore_active = new WeakMap(), _DurabilityCore_executionStarts = new WeakMap(), _DurabilityCore_instances = new WeakSet(), _DurabilityCore_trackedSource = function _DurabilityCore_trackedSource() {
151
165
  const sql = __classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql;
152
166
  return {
153
167
  get: async (id) => {
154
168
  const call = readCall(sql, id);
155
- return call && callRecord(call);
169
+ return call && callRecord(sql, call);
156
170
  },
157
171
  list: async ({ limit, cursor, status, name }) => {
158
172
  const page = listCreated(sql, callsTable, 'operation', {
@@ -161,7 +175,10 @@ _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap()
161
175
  status,
162
176
  name,
163
177
  });
164
- const records = callRowSchema.array().parse(page.rows).map(callRecord);
178
+ const records = callRowSchema
179
+ .array()
180
+ .parse(page.rows)
181
+ .map((call) => callRecord(sql, call));
165
182
  return page.next === undefined
166
183
  ? { records }
167
184
  : { records, cursor: page.next };
@@ -178,7 +195,12 @@ _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap()
178
195
  ORDER BY next_attempt_at ASC
179
196
  LIMIT 100`, now)
180
197
  .toArray());
181
- await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").runConcurrent(due, async ({ id }) => {
198
+ // With liveTimers an active operation reschedules itself when it settles, so
199
+ // skipping it keeps a long handler from blocking a concurrent alarm pass.
200
+ const pending = __classPrivateFieldGet(this, _DurabilityCore_engine, "f").liveTimers
201
+ ? due.filter(({ id }) => !__classPrivateFieldGet(this, _DurabilityCore_active, "f").has(id))
202
+ : due;
203
+ await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").runConcurrent(pending, async ({ id }) => {
182
204
  try {
183
205
  await __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_execute).call(this, id);
184
206
  }
@@ -289,6 +311,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
289
311
  active: __classPrivateFieldGet(this, _DurabilityCore_active, "f"),
290
312
  policy,
291
313
  emit: __classPrivateFieldGet(this, _DurabilityCore_emit, "f"),
314
+ includeResult: __classPrivateFieldGet(this, _DurabilityCore_includeResults, "f"),
292
315
  exhaustedError: () => new DurableAttemptsExhaustedError('operation', call.operation, policy.maxAttempts),
293
316
  timeoutError: () => new DurableAttemptTimeoutError(call.operation, policy.attemptTimeoutMs),
294
317
  invoke: (attempt, signal) => {
@@ -301,6 +324,11 @@ async function _DurabilityCore_execute(id, eagerPermit) {
301
324
  payload: deserialize(call.payload),
302
325
  attempt,
303
326
  signal,
327
+ memoize: createMemoize(__classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql, callsTable, {
328
+ key: call.id,
329
+ generation: call.generation_id,
330
+ attempt,
331
+ }),
304
332
  });
305
333
  },
306
334
  complete: (result, attempt) => {
package/dist/errors.d.ts CHANGED
@@ -36,6 +36,20 @@ export declare class DurableRetryPolicyError extends Error {
36
36
  export declare class DurableResultSerializationError extends Error {
37
37
  constructor(operation: string, reason?: unknown);
38
38
  }
39
+ /**
40
+ * Error persisted when a memoized result cannot be JSON-serialized. It is
41
+ * terminal because every retry would fail the same way.
42
+ */
43
+ export declare class DurableMemoSerializationError extends NonRetryableError {
44
+ constructor(key: string, reason?: unknown);
45
+ }
46
+ /**
47
+ * Error persisted when work memoizes more keys, or a larger result, than the
48
+ * limits allow. It is terminal because every retry would fail the same way.
49
+ */
50
+ export declare class DurableMemoLimitError extends NonRetryableError {
51
+ constructor(message: string);
52
+ }
39
53
  /** Error persisted when pending work has already reached its attempt limit. */
40
54
  export declare class DurableAttemptsExhaustedError extends Error {
41
55
  constructor(entity: 'operation' | 'named alarm', name: string, max: number);
@@ -71,6 +85,21 @@ export declare class FanoutTimeoutError extends Error {
71
85
  export declare class OutboxTimeoutError extends Error {
72
86
  constructor(timeoutMs: number);
73
87
  }
88
+ /** Outcome error of a scheduled run that exceeded `runTimeoutMs`. */
89
+ export declare class ScheduledRunTimeoutError extends Error {
90
+ constructor(timeoutMs: number);
91
+ }
92
+ /**
93
+ * Outcome error of a scheduled run that was still marked running when no live
94
+ * instance was executing it, for example after its object was evicted or reset.
95
+ */
96
+ export declare class ScheduledRunInterruptedError extends Error {
97
+ constructor();
98
+ }
99
+ /** Error recorded when one `onOutcome` delivery exceeds `outcomeTimeoutMs`. */
100
+ export declare class ScheduledOutcomeTimeoutError extends Error {
101
+ constructor(timeoutMs: number);
102
+ }
74
103
  /** A definite rejection before the batch was durably accepted. */
75
104
  export declare class FanoutEnqueueError extends Error {
76
105
  constructor(message: string);
package/dist/errors.js CHANGED
@@ -57,6 +57,29 @@ export class DurableResultSerializationError extends Error {
57
57
  }
58
58
  }
59
59
  }
60
+ /**
61
+ * Error persisted when a memoized result cannot be JSON-serialized. It is
62
+ * terminal because every retry would fail the same way.
63
+ */
64
+ export class DurableMemoSerializationError extends NonRetryableError {
65
+ constructor(key, reason) {
66
+ super(`Memoized result for key ${JSON.stringify(key)} is not JSON-serializable`);
67
+ this.name = 'DurableMemoSerializationError';
68
+ if (reason !== undefined) {
69
+ Object.defineProperty(this, 'cause', { value: reason });
70
+ }
71
+ }
72
+ }
73
+ /**
74
+ * Error persisted when work memoizes more keys, or a larger result, than the
75
+ * limits allow. It is terminal because every retry would fail the same way.
76
+ */
77
+ export class DurableMemoLimitError extends NonRetryableError {
78
+ constructor(message) {
79
+ super(message);
80
+ this.name = 'DurableMemoLimitError';
81
+ }
82
+ }
60
83
  /** Error persisted when pending work has already reached its attempt limit. */
61
84
  export class DurableAttemptsExhaustedError extends Error {
62
85
  constructor(entity, name, max) {
@@ -112,6 +135,30 @@ export class OutboxTimeoutError extends Error {
112
135
  this.name = 'OutboxTimeoutError';
113
136
  }
114
137
  }
138
+ /** Outcome error of a scheduled run that exceeded `runTimeoutMs`. */
139
+ export class ScheduledRunTimeoutError extends Error {
140
+ constructor(timeoutMs) {
141
+ super(`Scheduled run timed out after ${timeoutMs}ms`);
142
+ this.name = 'ScheduledRunTimeoutError';
143
+ }
144
+ }
145
+ /**
146
+ * Outcome error of a scheduled run that was still marked running when no live
147
+ * instance was executing it, for example after its object was evicted or reset.
148
+ */
149
+ export class ScheduledRunInterruptedError extends Error {
150
+ constructor() {
151
+ super('Scheduled run was interrupted before it reported an outcome');
152
+ this.name = 'ScheduledRunInterruptedError';
153
+ }
154
+ }
155
+ /** Error recorded when one `onOutcome` delivery exceeds `outcomeTimeoutMs`. */
156
+ export class ScheduledOutcomeTimeoutError extends Error {
157
+ constructor(timeoutMs) {
158
+ super(`Scheduled run outcome delivery timed out after ${timeoutMs}ms`);
159
+ this.name = 'ScheduledOutcomeTimeoutError';
160
+ }
161
+ }
115
162
  /** A definite rejection before the batch was durably accepted. */
116
163
  export class FanoutEnqueueError extends Error {
117
164
  constructor(message) {
@@ -14,3 +14,6 @@ export type { TopologyClient, TopologyClientConfig, TopologySource, TopologyView
14
14
  export type { TopologyMember, TopologyMemberInput, TopologyMemberState, TopologySnapshot, } from './topology-snapshot.js';
15
15
  export { TopologyError, TopologyUnavailableError, type TopologyFallbackReason, } from './errors.js';
16
16
  export { durabilityTopologyMigrations } from './migrations.js';
17
+ export { DurabilitySchedule, type DurabilityScheduleConfig, type DurabilityScheduleEvent, type ScheduleDefinition, type ScheduledOutcomeDelivery, type ScheduledRun, type ScheduledRunContext, type ScheduledRunOutcome, type ScheduleState, } from './schedule.js';
18
+ export { ScheduledOutcomeTimeoutError, ScheduledRunInterruptedError, ScheduledRunTimeoutError, } from './errors.js';
19
+ export { durabilityScheduleMigrations } from './migrations.js';
@@ -11,3 +11,6 @@ export { durabilityOutboxMigrations } from './migrations.js';
11
11
  export { DurabilityTopology, } from './topology.js';
12
12
  export { TopologyError, TopologyUnavailableError, } from './errors.js';
13
13
  export { durabilityTopologyMigrations } from './migrations.js';
14
+ export { DurabilitySchedule, } from './schedule.js';
15
+ export { ScheduledOutcomeTimeoutError, ScheduledRunInterruptedError, ScheduledRunTimeoutError, } from './errors.js';
16
+ export { durabilityScheduleMigrations } from './migrations.js';
package/dist/fanout.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { type DurabilityLifecycleEvent, type LifecycleHook } from './lifecycle.js';
2
2
  import { RoutingLoad, type EnqueueResult, type LoadSnapshot } from './load.js';
3
3
  import type { MessageWrite } from './stored-message.js';
4
+ import { type DurableMemoize } from './memoize.js';
4
5
  import { type ExecutionPolicyOptions } from './policy.js';
5
6
  import { type SchedulerAttachment } from './scheduler.js';
6
7
  export type FanoutInput<Body = unknown> = {
@@ -17,6 +18,11 @@ export type DurabilityFanoutMessage<Body = unknown> = {
17
18
  body: Body;
18
19
  attempt: number;
19
20
  enqueuedAt: number;
21
+ /**
22
+ * Persists a callback's result by key for this message and target, so a
23
+ * retried delivery reuses it. Deleted when the delivery is acked or dead-lettered.
24
+ */
25
+ memoize: DurableMemoize;
20
26
  ack(): Promise<void>;
21
27
  retry(delayMs?: number): Promise<void>;
22
28
  deadLetter(): Promise<void>;
package/dist/fanout.js CHANGED
@@ -15,7 +15,8 @@ import { traceFunction, traceMethods } from './dev.js';
15
15
  import { DurableRetryPolicyError, FanoutEnqueueError, FanoutSettlementError, FanoutTimeoutError, reportFailure, serializeError, } from './errors.js';
16
16
  import { createLifecycleHooks, } from './lifecycle.js';
17
17
  import { RoutingLoad } from './load.js';
18
- import { durabilityFanoutMigrations, migrateCapability } from './migrations.js';
18
+ import { createMemoize, deleteMemos, deleteMemosOfDroppedTable, } from './memoize.js';
19
+ import { durabilityFanoutMigrations, durabilityMemoMigrations, migrateCapability, } from './migrations.js';
19
20
  import { assertPositiveInteger, createPolicyResolver, methodOptionsSchema, } from './policy.js';
20
21
  import { engineFor, } from './scheduler.js';
21
22
  import { deserialize, serialize } from './serialization.js';
@@ -120,13 +121,16 @@ export class DurabilityFanout {
120
121
  __classPrivateFieldSet(this, _DurabilityFanout_lifecycle, createLifecycleHooks((hook) => __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").emitter(hook), config.onLifecycleEvent), "f");
121
122
  __classPrivateFieldSet(this, _DurabilityFanout_emit, __classPrivateFieldGet(this, _DurabilityFanout_lifecycle, "f").emit, "f");
122
123
  __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").migrateSchema('fanout', durabilityFanoutMigrations);
124
+ __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").migrateSchema('memos', durabilityMemoMigrations);
123
125
  __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").register({
124
126
  table: deliveriesTable,
125
127
  runDue: () => __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_runDue).call(this),
126
128
  });
127
129
  }
128
130
  static migrate(context, target) {
129
- return migrateCapability(context.storage, 'fanout', durabilityFanoutMigrations, target);
131
+ const result = migrateCapability(context.storage, 'fanout', durabilityFanoutMigrations, target);
132
+ deleteMemosOfDroppedTable(context.storage.sql, deliveriesTable);
133
+ return result;
130
134
  }
131
135
  alarm(info) {
132
136
  return __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").alarm(info);
@@ -334,13 +338,11 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
334
338
  exhausted.push({ row, message });
335
339
  continue;
336
340
  }
337
- const attempt = claimAttempt(sql, deliveriesTable, row.id, row.generation_id, policy.maxAttempts);
341
+ const attempt = claimAttempt(sql, deliveriesTable, row.id, row.generation_id, policy.maxAttempts, deadline);
338
342
  if (attempt === undefined) {
339
343
  continue;
340
344
  }
341
- const claim = { row: { ...row, attempt }, message };
342
- updateAttempt(sql, deliveriesTable, attemptOf(claim.row), 'next_attempt_at = ?', deadline);
343
- claimed.push(claim);
345
+ claimed.push({ row: { ...row, attempt }, message });
344
346
  }
345
347
  return { claims: claimed, terminal: exhausted };
346
348
  });
@@ -528,6 +530,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
528
530
  body: deserialize(message.payload),
529
531
  enqueuedAt: message.created_at,
530
532
  attempt: row.attempt,
533
+ memoize: createMemoize(__classPrivateFieldGet(this, _DurabilityFanout_engine, "f").sql, deliveriesTable, attemptOf(row)),
531
534
  ack: traceFunction('DurabilityFanoutMessage.ack', () => settle('ack', async () => {
532
535
  await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_remove).call(this, row);
533
536
  __classPrivateFieldGet(this, _DurabilityFanout_emit, "f").call(this, {
@@ -560,6 +563,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
560
563
  if (!deleteAttempt(sql, deliveriesTable, attemptOf(row))) {
561
564
  return false;
562
565
  }
566
+ deleteMemos(sql, deliveriesTable, row.id);
563
567
  __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_adjustPending).call(this, -1);
564
568
  sql.exec(`UPDATE durability_fanout_messages
565
569
  SET remaining = remaining - 1
package/dist/index.d.ts CHANGED
@@ -1,12 +1,13 @@
1
1
  export { Durability, type DurabilityConfig, type DurabilityConstructor, type DurabilityOptions, type DurableCall, type DurableHandler, type DurableOperation, type DurableOperationResult, type DurabilityOperationEvent, type HandlerMap, } from './durability.js';
2
2
  export { DurabilityAlarms, type DurabilityAlarmsConfig, type DurabilityAlarmsConstructor, type DurabilityAlarmsOptions, type DurabilityAlarmEvent, type DurableAlarmHandler, type DurableAlarmInfo, type DurableNamedAlarm, } from './durability-alarms.js';
3
+ export { maxMemoBytes, maxMemosPerRecord, type DurableMemoize, } from './memoize.js';
3
4
  export { DurabilityFanout, type DurabilityFanoutConfig, type DurabilityFanoutEvent, type DurabilityFanoutMessage, type FanoutInput, type FanoutTarget, type FanoutEnqueueOptions, } from './fanout.js';
4
5
  export { DurabilityLog, maxLogBytes, type DurabilityLogConfig, type LogAppendInput, type LogColdStorage, type LogLease, type LogLeaseOptions, type LogPage, type LogReadOptions, type LogRecord, type LogRetention, type LogSegment, type LogBounds, } from './log.js';
5
6
  export { RoutingLoad, type EnqueueResult, type LoadSnapshot, type ProcessingLoad, } from './load.js';
6
7
  export type { MessageWrite, StoredMessage } from './stored-message.js';
7
- export { DurabilityScheduler, type DurabilityContext, type DurabilitySchedulerConfig, type DurabilitySchedulerOptions, type SchedulerAttachment, } from './scheduler.js';
8
- export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
8
+ export { DurabilityScheduler, type AlarmRetryInfo, type DurabilityContext, type DurabilitySchedulerConfig, type DurabilitySchedulerOptions, type SchedulerAttachment, } from './scheduler.js';
9
+ export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, DurableMemoLimitError, DurableMemoSerializationError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
9
10
  export type { DurabilityLifecycleEvent, LifecycleHook } from './lifecycle.js';
10
- export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, migrate, type DurabilityMigrationResult, type MigrateOptions, type MigrationCapability, } from './migrations.js';
11
+ export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, durabilityMemoMigrations, migrate, type DurabilityMigrationResult, type MigrateOptions, type MigrationCapability, } from './migrations.js';
11
12
  export type { DurableMigrations } from '@durability/storage';
12
13
  export type { DurabilityAlarmMethodOptions, DurabilityMethodOptions, DurabilityRetryOptions, } from './policy.js';
package/dist/index.js CHANGED
@@ -1,8 +1,9 @@
1
1
  export { Durability, } from './durability.js';
2
2
  export { DurabilityAlarms, } from './durability-alarms.js';
3
+ export { maxMemoBytes, maxMemosPerRecord, } from './memoize.js';
3
4
  export { DurabilityFanout, } from './fanout.js';
4
5
  export { DurabilityLog, maxLogBytes, } from './log.js';
5
6
  export { RoutingLoad, } from './load.js';
6
7
  export { DurabilityScheduler, } from './scheduler.js';
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, migrate, } from './migrations.js';
8
+ export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, DurableMemoLimitError, DurableMemoSerializationError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
9
+ export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, durabilityMemoMigrations, migrate, } from './migrations.js';
@@ -48,7 +48,12 @@ export type DurabilityLifecycleEvent = ((OperationLifecycleEntity | FanoutLifecy
48
48
  attempt: number;
49
49
  }) | (LifecycleEntity & AttemptSettled & {
50
50
  outcome: 'completed';
51
- /** The handler's return value. Absent for fanout acknowledgements. */
51
+ /**
52
+ * The handler's return value. Omitted by default to keep result
53
+ * content out of telemetry; present only when the emitting instance
54
+ * opts in (e.g. Durability's `includeResults`). Always absent for
55
+ * fanout acknowledgements.
56
+ */
52
57
  result?: unknown;
53
58
  }) | (LifecycleEntity & AttemptSettled & {
54
59
  outcome: 'retry_scheduled';
package/dist/log.js CHANGED
@@ -252,7 +252,7 @@ const settleLease = (sql, batchId, state, expiresAt) => sql
252
252
  */
253
253
  const leasesFrom = (sql, consumer, from, limit) => logLeaseRowSchema.array().parse(sql
254
254
  .exec(`SELECT * FROM durability_log_leases
255
- WHERE consumer = ? AND first_offset >= ?
255
+ WHERE consumer = ? AND last_offset >= ?
256
256
  ORDER BY first_offset ASC
257
257
  LIMIT ?`, consumer, from, limit)
258
258
  .toArray());
@@ -541,7 +541,11 @@ export class DurabilityLog {
541
541
  }
542
542
  // Terminal intent is durable before the callback runs, so a failing
543
543
  // handler cannot resurrect a range that already exhausted its attempts.
544
- __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_settle).call(this, reclaimed.batch_id, 'skipped');
544
+ // A skipped range counts as settled, so the cursor moves past it as for an ack.
545
+ __classPrivateFieldGet(this, _DurabilityLog_engine, "f").transactionSync(() => {
546
+ __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_settle).call(this, reclaimed.batch_id, 'skipped');
547
+ __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_advance).call(this, consumer);
548
+ });
545
549
  try {
546
550
  await leases.onPoison(lease);
547
551
  }
@@ -675,17 +679,23 @@ async function _DurabilityLog_rehydrate(from, limit, bounds) {
675
679
  // Offsets below the retained window are gone for everyone; a cursor
676
680
  // stranded there could never meet the ranges leased after them.
677
681
  const from = Math.max(readCursor(sql, consumer) ?? 0, readBounds(sql).oldestOffset);
678
- const candidates = leasesFrom(sql, consumer, from, __classPrivateFieldGet(this, _DurabilityLog_maxBatchSize, "f"));
679
682
  let cursor = from;
680
683
  const settled = [];
681
- for (const row of candidates) {
682
- const contiguous = row.first_offset <= cursor;
683
- const done = row.state === 'acked' || row.state === 'skipped';
684
- if (!contiguous || !done) {
685
- break;
684
+ // Ranges settled while an earlier one was outstanding wait behind it; when
685
+ // it settles the cursor must pass all of them, however many pages that is.
686
+ for (let page = true; page;) {
687
+ const candidates = leasesFrom(sql, consumer, cursor, __classPrivateFieldGet(this, _DurabilityLog_maxBatchSize, "f"));
688
+ page = candidates.length === __classPrivateFieldGet(this, _DurabilityLog_maxBatchSize, "f");
689
+ for (const row of candidates) {
690
+ const contiguous = row.first_offset <= cursor;
691
+ const done = row.state === 'acked' || row.state === 'skipped';
692
+ if (!contiguous || !done) {
693
+ page = false;
694
+ break;
695
+ }
696
+ cursor = Math.max(cursor, row.last_offset + 1);
697
+ settled.push(row.batch_id);
686
698
  }
687
- cursor = Math.max(cursor, row.last_offset + 1);
688
- settled.push(row.batch_id);
689
699
  }
690
700
  if (settled.length === 0) {
691
701
  return;
@@ -696,8 +706,21 @@ async function _DurabilityLog_rehydrate(from, limit, bounds) {
696
706
  /** Reads a stored range, rehydrating it when retention already flushed it. */
697
707
  async function _DurabilityLog_between(first, last) {
698
708
  const bounds = readBounds(__classPrivateFieldGet(this, _DurabilityLog_engine, "f").sql);
699
- const records = await __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_readFrom).call(this, first, last - first + 1, bounds);
700
- return records.filter((record) => record.offset <= last);
709
+ // One read stops at the end of a cold segment, and a range redelivered
710
+ // after a flush can span several segments and the hot window.
711
+ const records = [];
712
+ let from = first;
713
+ while (from <= last) {
714
+ // eslint-disable-next-line no-await-in-loop
715
+ const page = await __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_readFrom).call(this, from, last - from + 1, bounds);
716
+ const inRange = page.filter((record) => record.offset <= last);
717
+ if (inRange.length === 0) {
718
+ break;
719
+ }
720
+ records.push(...inRange);
721
+ from = inRange[inRange.length - 1].offset + 1;
722
+ }
723
+ return records;
701
724
  }, _DurabilityLog_readFrom = async function _DurabilityLog_readFrom(from, limit, bounds) {
702
725
  if (from < bounds.hotOffset && from < bounds.nextOffset) {
703
726
  return __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_rehydrate).call(this, from, limit, bounds);
@@ -0,0 +1,34 @@
1
+ import { type AttemptRef, type DurableTable } from './storage.js';
2
+ /**
3
+ * Runs `callback` once per key for a durable operation or named alarm
4
+ * occurrence and persists its result, so a retried attempt returns the result
5
+ * instead of running the callback again. A callback that throws persists
6
+ * nothing and runs again on the next call with that key.
7
+ *
8
+ * Calls with the same key return the same result, within one attempt and
9
+ * across attempts. A call for a key whose callback is still running rejects,
10
+ * including one made from that callback. Results are deleted when the
11
+ * operation, alarm occurrence, or fanout delivery settles.
12
+ *
13
+ * At most {@link maxMemosPerRecord} keys and {@link maxMemoBytes} per result;
14
+ * exceeding either fails the work with `DurableMemoLimitError`.
15
+ */
16
+ export type DurableMemoize = <T>(key: string, callback: () => T | Promise<T>) => Promise<T>;
17
+ /** The most keys one operation, alarm occurrence, or fanout delivery may memoize. */
18
+ export declare const maxMemosPerRecord = 1000;
19
+ /** The largest serialized memoized result, in UTF-8 bytes. */
20
+ export declare const maxMemoBytes = 1048576;
21
+ /** Memoization for one attempt; only that attempt may persist new results. */
22
+ export declare const createMemoize: (sql: SqlStorage, table: DurableTable, ref: AttemptRef) => DurableMemoize;
23
+ /** Keys a record's current generation has results for, in the order they were saved. */
24
+ export declare const memoizedKeys: (sql: SqlStorage, table: DurableTable, key: string, generation: string) => string[];
25
+ /** Deletes every memoized result of a record, whichever generation wrote it. */
26
+ export declare const deleteMemos: (sql: SqlStorage, table: DurableTable, key: string) => void;
27
+ /** Deletes memoized results whose record generation is no longer pending. */
28
+ export declare const deleteStaleMemos: (sql: SqlStorage, table: DurableTable) => void;
29
+ /**
30
+ * Deletes the memoized results of a helper whose schema was reverted. The
31
+ * shared table stays for the other helper, but the removed records' results
32
+ * must not.
33
+ */
34
+ export declare const deleteMemosOfDroppedTable: (sql: SqlStorage, table: DurableTable) => void;