durability 3.0.1 → 4.0.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.
package/dist/fanout.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { LifecycleHook } from './lifecycle.js';
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
4
  import { type ExecutionPolicyOptions } from './policy.js';
@@ -23,10 +23,17 @@ export type DurabilityFanoutMessage<Body = unknown> = {
23
23
  };
24
24
  export type FanoutTarget<Body> = ExecutionPolicyOptions & ({
25
25
  deliver(messages: DurabilityFanoutMessage<Body>[]): unknown | Promise<unknown>;
26
+ /**
27
+ * Acks every message the consumer leaves unsettled when `deliver`
28
+ * returns without throwing, in one transaction instead of one call
29
+ * per message. Explicit `retry()` and `deadLetter()` still apply.
30
+ */
31
+ ackOnReturn?: boolean;
26
32
  storage?: never;
27
33
  } | {
28
34
  storage: MessageWrite<Body>;
29
35
  deliver?: never;
36
+ ackOnReturn?: never;
30
37
  });
31
38
  export type FanoutEnqueueOptions = {
32
39
  /** Omit for all static targets. Redrive specifies only the failed target. */
@@ -35,11 +42,22 @@ export type FanoutEnqueueOptions = {
35
42
  export type DurabilityFanoutConfig<Body> = SchedulerAttachment & ExecutionPolicyOptions & {
36
43
  targets: Record<string, FanoutTarget<Body>>;
37
44
  routing?: RoutingLoad;
38
- /** Receives terminal failures. Without it, terminal work is retained. */
45
+ /** Receives terminal failures. Without it, terminal deliveries are dropped. */
39
46
  dlq?: MessageWrite<Body>;
40
47
  maxBatchSize?: number;
48
+ /**
49
+ * Holds first deliveries for up to this many milliseconds so messages
50
+ * arriving together share a batch. Defaults to 0 (deliver immediately).
51
+ */
52
+ batchDelayMs?: number;
41
53
  onLifecycleEvent?: LifecycleHook;
42
54
  };
55
+ /** A lifecycle event for one of this instance's deliveries. */
56
+ export type DurabilityFanoutEvent = Extract<DurabilityLifecycleEvent, {
57
+ entityKind: 'fanout_delivery';
58
+ }> | Extract<DurabilityLifecycleEvent, {
59
+ type: 'purged';
60
+ }>;
43
61
  /**
44
62
  * A composable DO capability: durable, independent delivery to static named
45
63
  * targets. Share a scheduler with operations/alarms on the same object.
@@ -50,6 +68,11 @@ export declare class DurabilityFanout<Body = unknown> {
50
68
  constructor(config: DurabilityFanoutConfig<Body>);
51
69
  static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): import("./migrations.js").DurabilityMigrationResult;
52
70
  alarm(info?: AlarmInvocationInfo): Promise<void>;
71
+ /**
72
+ * Attaches a best-effort lifecycle hook alongside `onLifecycleEvent` and
73
+ * returns a function that detaches it.
74
+ */
75
+ lifecycle(hook: (event: DurabilityFanoutEvent) => void | Promise<void>): () => void;
53
76
  load(): Promise<LoadSnapshot>;
54
77
  /**
55
78
  * Atomically accepts the whole batch, including its frozen target set.
package/dist/fanout.js CHANGED
@@ -9,13 +9,58 @@ 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 _DurabilityFanout_instances, _DurabilityFanout_engine, _DurabilityFanout_routing, _DurabilityFanout_targets, _DurabilityFanout_policies, _DurabilityFanout_dlq, _DurabilityFanout_maxBatchSize, _DurabilityFanout_emit, _DurabilityFanout_running, _DurabilityFanout_runDue, _DurabilityFanout_runTarget, _DurabilityFanout_postpone, _DurabilityFanout_deliver, _DurabilityFanout_message, _DurabilityFanout_remove, _DurabilityFanout_retry, _DurabilityFanout_deadLetter, _DurabilityFanout_deadline;
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
+ import { z } from 'zod';
13
14
  import { DurableRetryPolicyError, FanoutEnqueueError, FanoutSettlementError, FanoutTimeoutError, reportFailure, serializeError, } from './errors.js';
15
+ import { createLifecycleHooks, } from './lifecycle.js';
14
16
  import { RoutingLoad } from './load.js';
15
17
  import { durabilityFanoutMigrations, migrate } from './migrations.js';
16
18
  import { assertPositiveInteger, createPolicyResolver, methodOptionsSchema, } from './policy.js';
17
19
  import { engineFor, } from './scheduler.js';
18
20
  import { deserialize, serialize } from './serialization.js';
21
+ import { claimAttempt, deleteAttempt, updateAttempt, } from './storage.js';
22
+ const fanoutMessageRowSchema = z.object({
23
+ key: z.string(),
24
+ id: z.string(),
25
+ payload: z.string(),
26
+ targets: z.string(),
27
+ remaining: z.number().int().nonnegative(),
28
+ seq: z.number().int().nonnegative(),
29
+ created_at: z.number().int().nonnegative(),
30
+ generation_id: z.string(),
31
+ });
32
+ const deliveryRowSchema = z.object({
33
+ id: z.string(),
34
+ message_key: z.string(),
35
+ target_id: z.string(),
36
+ seq: z.number().int().nonnegative(),
37
+ status: z.literal('pending'),
38
+ phase: z.enum(['delivery', 'dead_letter']),
39
+ attempt: z.number().int().nonnegative(),
40
+ next_attempt_at: z.number().int().nonnegative(),
41
+ last_error: z.string().nullable(),
42
+ last_error_name: z.string().nullable(),
43
+ created_at: z.number().int().nonnegative(),
44
+ generation_id: z.string(),
45
+ dead_lettered_at: z.number().int().nonnegative().nullable(),
46
+ dead_letter_reason: z.enum(['explicit', 'exhausted']).nullable(),
47
+ });
48
+ const deliveriesTable = {
49
+ name: 'durability_fanout_deliveries',
50
+ key: 'id',
51
+ };
52
+ const countRowSchema = z.object({ count: z.number().int().nonnegative() });
53
+ const seqRowSchema = z.object({ seq: z.number().int().nonnegative() });
54
+ const readManifest = (sql, key) => fanoutMessageRowSchema
55
+ .optional()
56
+ .parse(sql
57
+ .exec('SELECT * FROM durability_fanout_messages WHERE key = ?', key)
58
+ .toArray()[0]);
59
+ const attemptOf = (row) => ({
60
+ key: row.id,
61
+ generation: row.generation_id,
62
+ attempt: row.attempt,
63
+ });
19
64
  const infrastructureRetryMs = 60000;
20
65
  const entity = (claim) => ({
21
66
  entityKind: 'fanout_delivery',
@@ -38,10 +83,23 @@ export class DurabilityFanout {
38
83
  _DurabilityFanout_policies.set(this, void 0);
39
84
  _DurabilityFanout_dlq.set(this, void 0);
40
85
  _DurabilityFanout_maxBatchSize.set(this, void 0);
86
+ _DurabilityFanout_batchDelayMs.set(this, void 0);
87
+ _DurabilityFanout_lifecycle.set(this, void 0);
41
88
  _DurabilityFanout_emit.set(this, void 0);
42
89
  _DurabilityFanout_running.set(this, new Map());
90
+ /**
91
+ * Cached pending-delivery count. Counting the table on every enqueue costs
92
+ * O(backlog), which made a shard that fell behind fall further behind. It is
93
+ * hydrated once and kept exact by inserts and removals; a failed transaction
94
+ * may leave it wrong, so it is discarded and recounted on the next read.
95
+ */
96
+ _DurabilityFanout_pending.set(this, void 0);
43
97
  __classPrivateFieldSet(this, _DurabilityFanout_maxBatchSize, config.maxBatchSize ?? 10, "f");
44
98
  assertPositiveInteger('maxBatchSize', __classPrivateFieldGet(this, _DurabilityFanout_maxBatchSize, "f"));
99
+ __classPrivateFieldSet(this, _DurabilityFanout_batchDelayMs, config.batchDelayMs ?? 0, "f");
100
+ if (!Number.isSafeInteger(__classPrivateFieldGet(this, _DurabilityFanout_batchDelayMs, "f")) || __classPrivateFieldGet(this, _DurabilityFanout_batchDelayMs, "f") < 0) {
101
+ throw new RangeError('batchDelayMs must be a non-negative integer');
102
+ }
45
103
  __classPrivateFieldSet(this, _DurabilityFanout_targets, new Map(Object.entries(config.targets).map(([id, target]) => [id, { ...target }])), "f");
46
104
  if (__classPrivateFieldGet(this, _DurabilityFanout_targets, "f").size === 0) {
47
105
  throw new TypeError('Fanout requires at least one static target');
@@ -58,9 +116,13 @@ export class DurabilityFanout {
58
116
  __classPrivateFieldSet(this, _DurabilityFanout_engine, engineFor(config), "f");
59
117
  __classPrivateFieldSet(this, _DurabilityFanout_routing, config.routing ?? new RoutingLoad(), "f");
60
118
  __classPrivateFieldSet(this, _DurabilityFanout_dlq, config.dlq, "f");
61
- __classPrivateFieldSet(this, _DurabilityFanout_emit, __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").emitter(config.onLifecycleEvent), "f");
119
+ __classPrivateFieldSet(this, _DurabilityFanout_lifecycle, createLifecycleHooks((hook) => __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").emitter(hook), config.onLifecycleEvent), "f");
120
+ __classPrivateFieldSet(this, _DurabilityFanout_emit, __classPrivateFieldGet(this, _DurabilityFanout_lifecycle, "f").emit, "f");
62
121
  __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").migrateSchema('fanout', durabilityFanoutMigrations);
63
- __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").register({ kind: 'deliveries', runDue: () => __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_runDue).call(this) });
122
+ __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").register({
123
+ table: deliveriesTable,
124
+ runDue: () => __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_runDue).call(this),
125
+ });
64
126
  }
65
127
  static migrate(context, target) {
66
128
  return migrate(context.storage, 'fanout', durabilityFanoutMigrations, target);
@@ -68,8 +130,15 @@ export class DurabilityFanout {
68
130
  alarm(info) {
69
131
  return __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").alarm(info);
70
132
  }
133
+ /**
134
+ * Attaches a best-effort lifecycle hook alongside `onLifecycleEvent` and
135
+ * returns a function that detaches it.
136
+ */
137
+ lifecycle(hook) {
138
+ return __classPrivateFieldGet(this, _DurabilityFanout_lifecycle, "f").add(hook);
139
+ }
71
140
  async load() {
72
- return __classPrivateFieldGet(this, _DurabilityFanout_routing, "f").snapshot(await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").storage.deliveries.pendingCount());
141
+ return __classPrivateFieldGet(this, _DurabilityFanout_routing, "f").snapshot(__classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_pendingCount).call(this));
73
142
  }
74
143
  /**
75
144
  * Atomically accepts the whole batch, including its frozen target set.
@@ -108,14 +177,12 @@ export class DurabilityFanout {
108
177
  load: await this.load(),
109
178
  };
110
179
  }
111
- const registered = [];
180
+ let registered;
112
181
  try {
113
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").transaction(async (transaction) => {
114
- registered.length = 0;
115
- const store = transaction.deliveries;
182
+ registered = await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_transaction).call(this, (sql) => {
183
+ const claims = [];
116
184
  for (const entry of entries) {
117
- // eslint-disable-next-line no-await-in-loop
118
- const existing = await store.getMessage(entry.key);
185
+ const existing = readManifest(sql, entry.key);
119
186
  if (existing) {
120
187
  if (existing.id !== entry.id ||
121
188
  existing.payload !== entry.payload ||
@@ -124,17 +191,24 @@ export class DurabilityFanout {
124
191
  }
125
192
  continue;
126
193
  }
194
+ const { seq } = seqRowSchema.parse(sql
195
+ .exec(`UPDATE durability_fanout_seq
196
+ SET next_seq = next_seq + 1
197
+ WHERE id = 1
198
+ RETURNING next_seq - 1 AS seq`)
199
+ .toArray()[0]);
127
200
  const message = {
128
201
  ...entry,
129
202
  targets: JSON.stringify(targets),
130
203
  remaining: targets.length,
131
- // eslint-disable-next-line no-await-in-loop
132
- seq: await store.nextSeq(),
204
+ seq,
133
205
  created_at: Date.now(),
134
206
  generation_id: crypto.randomUUID(),
135
207
  };
136
- // eslint-disable-next-line no-await-in-loop
137
- await store.insertMessage(message);
208
+ sql.exec(`INSERT INTO durability_fanout_messages
209
+ (key, id, payload, targets, remaining, seq, created_at,
210
+ generation_id)
211
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, message.key, message.id, message.payload, message.targets, message.remaining, message.seq, message.created_at, message.generation_id);
138
212
  for (const target of targets) {
139
213
  const row = {
140
214
  id: JSON.stringify([entry.key, target]),
@@ -146,20 +220,28 @@ export class DurabilityFanout {
146
220
  status: 'pending',
147
221
  phase: 'delivery',
148
222
  attempt: 0,
149
- next_attempt_at: message.created_at,
223
+ next_attempt_at: __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_firstAttemptAt).call(this, message.created_at),
150
224
  last_error: null,
151
225
  last_error_name: null,
152
226
  dead_lettered_at: null,
153
227
  dead_letter_reason: null,
154
228
  };
155
- // eslint-disable-next-line no-await-in-loop
156
- if (!(await store.insert(row))) {
229
+ const inserted = sql
230
+ .exec(`INSERT INTO durability_fanout_deliveries
231
+ (id, message_key, target_id, seq, status, phase, attempt,
232
+ next_attempt_at, created_at, generation_id)
233
+ VALUES (?, ?, ?, ?, 'pending', 'delivery', 0, ?, ?, ?)
234
+ ON CONFLICT(id) DO NOTHING
235
+ RETURNING id`, row.id, row.message_key, row.target_id, row.seq, row.next_attempt_at, row.created_at, row.generation_id)
236
+ .toArray().length > 0;
237
+ if (!inserted) {
157
238
  throw new Error('Fanout manifest and delivery state disagree');
158
239
  }
159
- registered.push({ row, message });
240
+ __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_adjustPending).call(this, 1);
241
+ claims.push({ row, message });
160
242
  }
161
243
  }
162
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").reconcile(transaction);
244
+ return claims;
163
245
  });
164
246
  }
165
247
  catch (error) {
@@ -185,7 +267,8 @@ export class DurabilityFanout {
185
267
  });
186
268
  }
187
269
  const load = await this.load();
188
- if (registered.length > 0) {
270
+ // Delayed first attempts are not due yet; the scheduler wakes for them.
271
+ if (registered.length > 0 && __classPrivateFieldGet(this, _DurabilityFanout_batchDelayMs, "f") === 0) {
189
272
  const onError = (error) => reportFailure('durability.fanout.failed', {}, error);
190
273
  const work = __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_runDue).call(this)
191
274
  .then(() => __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").scheduleNextAlarm())
@@ -195,8 +278,20 @@ export class DurabilityFanout {
195
278
  return { success: true, value: entries.map(({ id }) => id), load };
196
279
  }
197
280
  }
198
- _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMap(), _DurabilityFanout_targets = new WeakMap(), _DurabilityFanout_policies = new WeakMap(), _DurabilityFanout_dlq = new WeakMap(), _DurabilityFanout_maxBatchSize = new WeakMap(), _DurabilityFanout_emit = new WeakMap(), _DurabilityFanout_running = new WeakMap(), _DurabilityFanout_instances = new WeakSet(), _DurabilityFanout_runDue = async function _DurabilityFanout_runDue() {
199
- const targets = await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").storage.deliveries.listTargets();
281
+ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMap(), _DurabilityFanout_targets = new WeakMap(), _DurabilityFanout_policies = new WeakMap(), _DurabilityFanout_dlq = new WeakMap(), _DurabilityFanout_maxBatchSize = new WeakMap(), _DurabilityFanout_batchDelayMs = new WeakMap(), _DurabilityFanout_lifecycle = new WeakMap(), _DurabilityFanout_emit = new WeakMap(), _DurabilityFanout_running = new WeakMap(), _DurabilityFanout_pending = new WeakMap(), _DurabilityFanout_instances = new WeakSet(), _DurabilityFanout_firstAttemptAt = function _DurabilityFanout_firstAttemptAt(createdAt) {
282
+ if (__classPrivateFieldGet(this, _DurabilityFanout_batchDelayMs, "f") === 0) {
283
+ return createdAt;
284
+ }
285
+ return Math.ceil(createdAt / __classPrivateFieldGet(this, _DurabilityFanout_batchDelayMs, "f")) * __classPrivateFieldGet(this, _DurabilityFanout_batchDelayMs, "f");
286
+ }, _DurabilityFanout_runDue = async function _DurabilityFanout_runDue() {
287
+ const targets = z
288
+ .object({ target_id: z.string() })
289
+ .array()
290
+ .parse(__classPrivateFieldGet(this, _DurabilityFanout_engine, "f").sql
291
+ .exec(`SELECT DISTINCT target_id FROM durability_fanout_deliveries
292
+ ORDER BY target_id`)
293
+ .toArray())
294
+ .map((row) => row.target_id);
200
295
  // Each target advances independently; a missing or slow target cannot hide
201
296
  // another target behind a global LIMIT. Each pass processes one bounded batch.
202
297
  await Promise.all(targets.map((id) => {
@@ -211,42 +306,46 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
211
306
  }, _DurabilityFanout_runTarget = async function _DurabilityFanout_runTarget(id) {
212
307
  const release = await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").acquirePermit();
213
308
  try {
214
- const due = await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").storage.deliveries.listDueForTarget(id, Date.now(), __classPrivateFieldGet(this, _DurabilityFanout_maxBatchSize, "f"));
309
+ const due = __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_listDue).call(this, id, Date.now());
310
+ if (due.length === 0) {
311
+ return;
312
+ }
215
313
  const target = __classPrivateFieldGet(this, _DurabilityFanout_targets, "f").get(id);
216
314
  const policy = __classPrivateFieldGet(this, _DurabilityFanout_policies, "f").get(id);
217
315
  if (!target || !policy) {
218
- if (due.length > 0) {
219
- reportFailure('durability.fanout.target_missing', { target: id }, new Error(`Target "${id}" is no longer configured; retaining work`));
220
- await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_postpone).call(this, due);
221
- }
316
+ reportFailure('durability.fanout.target_missing', { target: id }, new Error(`Target "${id}" is no longer configured; retaining work`));
317
+ await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_postpone).call(this, due);
222
318
  return;
223
319
  }
224
- const claims = [];
225
- for (const row of due) {
226
- // eslint-disable-next-line no-await-in-loop
227
- const message = await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").storage.deliveries.getMessage(row.message_key);
228
- if (!message || message.generation_id !== row.generation_id) {
229
- throw new Error('Fanout delivery is missing its message manifest');
230
- }
231
- if (row.phase === 'dead_letter' || row.attempt >= policy.maxAttempts) {
232
- // eslint-disable-next-line no-await-in-loop
233
- await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_deadLetter).call(this, { row, message }, row.dead_letter_reason ?? 'exhausted');
234
- continue;
235
- }
236
- // eslint-disable-next-line no-await-in-loop
237
- const attempt = await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").transaction(async (transaction) => {
238
- const claimed = await transaction.deliveries.claimAttempt(row.id, row.generation_id, policy.maxAttempts);
239
- if (claimed !== undefined) {
240
- await transaction.deliveries.settle(row.id, row.generation_id, claimed, {
241
- next_attempt_at: Date.now() + policy.attemptTimeoutMs,
242
- });
243
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").reconcile(transaction);
320
+ // One transaction claims the whole batch: per-message transactions made the
321
+ // pass cost O(batch) commits, which capped a shard's throughput.
322
+ const { claims, terminal } = await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_transaction).call(this, (sql) => {
323
+ const claimed = [];
324
+ const exhausted = [];
325
+ const deadline = Date.now() + policy.attemptTimeoutMs;
326
+ for (const row of due) {
327
+ const message = readManifest(sql, row.message_key);
328
+ if (!message || message.generation_id !== row.generation_id) {
329
+ throw new Error('Fanout delivery is missing its message manifest');
244
330
  }
245
- return claimed;
246
- });
247
- if (attempt !== undefined) {
248
- claims.push({ row: { ...row, attempt }, message });
331
+ if (row.phase === 'dead_letter' ||
332
+ row.attempt >= policy.maxAttempts) {
333
+ exhausted.push({ row, message });
334
+ continue;
335
+ }
336
+ const attempt = claimAttempt(sql, deliveriesTable, row.id, row.generation_id, policy.maxAttempts);
337
+ if (attempt === undefined) {
338
+ continue;
339
+ }
340
+ const claim = { row: { ...row, attempt }, message };
341
+ updateAttempt(sql, deliveriesTable, attemptOf(claim.row), 'next_attempt_at = ?', deadline);
342
+ claimed.push(claim);
249
343
  }
344
+ return { claims: claimed, terminal: exhausted };
345
+ });
346
+ for (const claim of terminal) {
347
+ // eslint-disable-next-line no-await-in-loop
348
+ await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_deadLetter).call(this, claim, claim.row.dead_letter_reason ?? 'exhausted');
250
349
  }
251
350
  if (claims.length > 0) {
252
351
  await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_deliver).call(this, target, claims, policy);
@@ -256,14 +355,10 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
256
355
  release();
257
356
  }
258
357
  }, _DurabilityFanout_postpone = async function _DurabilityFanout_postpone(rows) {
259
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").transaction(async (transaction) => {
358
+ await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_transaction).call(this, (sql) => {
260
359
  for (const row of rows) {
261
- // eslint-disable-next-line no-await-in-loop
262
- await transaction.deliveries.settle(row.id, row.generation_id, row.attempt, {
263
- next_attempt_at: Date.now() + infrastructureRetryMs,
264
- });
360
+ updateAttempt(sql, deliveriesTable, attemptOf(row), 'next_attempt_at = ?', Date.now() + infrastructureRetryMs);
265
361
  }
266
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").reconcile(transaction);
267
362
  });
268
363
  }, _DurabilityFanout_deliver = async function _DurabilityFanout_deliver(target, claims, policy) {
269
364
  const startedAt = Date.now();
@@ -316,6 +411,9 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
316
411
  for (const state of states) {
317
412
  state.closed = true;
318
413
  }
414
+ if (!invocationFailed && target.ackOnReturn) {
415
+ __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_ackUnsettled).call(this, states, startedAt);
416
+ }
319
417
  // A callback failure must not bypass already-started settlements.
320
418
  // The outer deadline still bounds a hung storage or RPC operation.
321
419
  const settlements = await Promise.allSettled(states.map((state) => state.pending));
@@ -347,8 +445,11 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
347
445
  if (!state.finished) {
348
446
  continue;
349
447
  }
350
- // eslint-disable-next-line no-await-in-loop
351
- const current = await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").storage.deliveries.get(state.claim.row.id);
448
+ const current = deliveryRowSchema
449
+ .optional()
450
+ .parse(__classPrivateFieldGet(this, _DurabilityFanout_engine, "f").sql
451
+ .exec('SELECT * FROM durability_fanout_deliveries WHERE id = ?', state.claim.row.id)
452
+ .toArray()[0]);
352
453
  if (!current ||
353
454
  current.generation_id !== state.claim.row.generation_id ||
354
455
  current.attempt !== state.claim.row.attempt ||
@@ -360,6 +461,44 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
360
461
  // eslint-disable-next-line no-await-in-loop
361
462
  await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_retry).call(this, state.claim, policy, undefined, serializeError(failure), startedAt);
362
463
  }
464
+ }, _DurabilityFanout_ackUnsettled = function _DurabilityFanout_ackUnsettled(states, startedAt) {
465
+ const unsettled = states.filter((state) => state.outcome === undefined);
466
+ if (unsettled.length === 0) {
467
+ return;
468
+ }
469
+ const removed = __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_transaction).call(this, (sql) => {
470
+ const ids = new Set();
471
+ for (const { claim } of unsettled) {
472
+ if (__classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_removeDelivery).call(this, sql, claim.row)) {
473
+ ids.add(claim.row.id);
474
+ }
475
+ }
476
+ return ids;
477
+ });
478
+ for (const state of unsettled) {
479
+ state.outcome = 'ack';
480
+ state.pending = removed
481
+ .then((ids) => {
482
+ // A row a later attempt already reclaimed stays with that attempt.
483
+ if (!ids.has(state.claim.row.id)) {
484
+ return undefined;
485
+ }
486
+ state.completed = true;
487
+ __classPrivateFieldGet(this, _DurabilityFanout_emit, "f").call(this, {
488
+ ...entity(state.claim),
489
+ type: 'attempt_settled',
490
+ timestamp: Date.now(),
491
+ attempt: state.claim.row.attempt,
492
+ durationMs: Math.max(0, Date.now() - startedAt),
493
+ outcome: 'completed',
494
+ });
495
+ return undefined;
496
+ })
497
+ .finally(() => {
498
+ state.finished = true;
499
+ });
500
+ void state.pending.catch(() => undefined);
501
+ }
363
502
  }, _DurabilityFanout_message = function _DurabilityFanout_message(state, policy, startedAt) {
364
503
  const { row, message } = state.claim;
365
504
  const settle = (outcome, action) => {
@@ -408,12 +547,22 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
408
547
  deadLetter: () => settle('deadLetter', () => __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_deadLetter).call(this, state.claim, 'explicit')),
409
548
  };
410
549
  }, _DurabilityFanout_remove = async function _DurabilityFanout_remove(row) {
411
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").transaction(async (transaction) => {
412
- if (!(await transaction.deliveries.remove(row.id, row.generation_id, row.attempt))) {
550
+ await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_transaction).call(this, (sql) => {
551
+ if (!__classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_removeDelivery).call(this, sql, row)) {
413
552
  throw new FanoutSettlementError(row.id);
414
553
  }
415
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").reconcile(transaction);
416
554
  });
555
+ }, _DurabilityFanout_removeDelivery = function _DurabilityFanout_removeDelivery(sql, row) {
556
+ if (!deleteAttempt(sql, deliveriesTable, attemptOf(row))) {
557
+ return false;
558
+ }
559
+ __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_adjustPending).call(this, -1);
560
+ sql.exec(`UPDATE durability_fanout_messages
561
+ SET remaining = remaining - 1
562
+ WHERE key = ?`, row.message_key);
563
+ sql.exec(`DELETE FROM durability_fanout_messages
564
+ WHERE key = ? AND remaining = 0`, row.message_key);
565
+ return true;
417
566
  }, _DurabilityFanout_retry = async function _DurabilityFanout_retry(claim, policy, override, error, startedAt) {
418
567
  const { row } = claim;
419
568
  if (row.attempt >= policy.maxAttempts) {
@@ -435,16 +584,11 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
435
584
  await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_deadLetter).call(this, claim, 'exhausted', serializeError(caught));
436
585
  return;
437
586
  }
438
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").transaction(async (transaction) => {
439
- const updated = await transaction.deliveries.settle(row.id, row.generation_id, row.attempt, {
440
- next_attempt_at: nextAttemptAt,
441
- last_error: error.message,
442
- last_error_name: error.name,
443
- });
587
+ await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_transaction).call(this, (sql) => {
588
+ const updated = updateAttempt(sql, deliveriesTable, attemptOf(row), 'next_attempt_at = ?, last_error = ?, last_error_name = ?', nextAttemptAt, error.message, error.name);
444
589
  if (!updated) {
445
590
  throw new FanoutSettlementError(row.id);
446
591
  }
447
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").reconcile(transaction);
448
592
  });
449
593
  __classPrivateFieldGet(this, _DurabilityFanout_emit, "f").call(this, {
450
594
  ...entity(claim),
@@ -463,26 +607,23 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
463
607
  (row.last_error === null
464
608
  ? null
465
609
  : { name: row.last_error_name ?? 'Error', message: row.last_error });
610
+ // Without a DLQ nothing could ever accept this delivery, and retrying the
611
+ // dead-letter step would keep the object awake forever, so it is dropped.
612
+ if (!__classPrivateFieldGet(this, _DurabilityFanout_dlq, "f")) {
613
+ await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_remove).call(this, row);
614
+ __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_emitTerminal).call(this, claim, reason, error);
615
+ return;
616
+ }
466
617
  // Persist intent BEFORE external I/O: eviction or timeout must never turn
467
618
  // a terminal decision into another consumer delivery.
468
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").transaction(async (transaction) => {
469
- const updated = await transaction.deliveries.settle(row.id, row.generation_id, row.attempt, {
470
- phase: 'dead_letter',
471
- dead_lettered_at: timestamp,
472
- dead_letter_reason: reason,
473
- next_attempt_at: Date.now() + infrastructureRetryMs,
474
- last_error: error?.message ?? null,
475
- last_error_name: error?.name ?? null,
476
- });
619
+ await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_transaction).call(this, (sql) => {
620
+ const updated = updateAttempt(sql, deliveriesTable, attemptOf(row), `phase = 'dead_letter', dead_lettered_at = ?, dead_letter_reason = ?,
621
+ next_attempt_at = ?, last_error = ?, last_error_name = ?`, timestamp, reason, Date.now() + infrastructureRetryMs, error?.message ?? null, error?.name ?? null);
477
622
  if (!updated) {
478
623
  throw new FanoutSettlementError(row.id);
479
624
  }
480
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").reconcile(transaction);
481
625
  });
482
626
  try {
483
- if (!__classPrivateFieldGet(this, _DurabilityFanout_dlq, "f")) {
484
- throw new Error('No DLQ configured; retaining terminal delivery');
485
- }
486
627
  const stored = {
487
628
  id: deliveryIdentity(row),
488
629
  messageId: message.id,
@@ -495,21 +636,60 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
495
636
  };
496
637
  await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_deadline).call(this, () => __classPrivateFieldGet(this, _DurabilityFanout_dlq, "f")(stored), infrastructureRetryMs);
497
638
  await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_remove).call(this, row);
498
- __classPrivateFieldGet(this, _DurabilityFanout_emit, "f").call(this, {
499
- ...entity(claim),
500
- type: 'terminal',
501
- timestamp: Date.now(),
502
- attempt: row.attempt,
503
- reason: reason === 'explicit' ? 'dead_lettered' : 'attempts_exhausted',
504
- error: error ?? {
505
- name: 'DeadLetter',
506
- message: 'Dead-lettered by consumer',
507
- },
508
- });
639
+ __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_emitTerminal).call(this, claim, reason, error);
509
640
  }
510
641
  catch (caught) {
511
642
  reportFailure('durability.fanout.dead_letter_failed', { id: message.id, target: row.target_id }, caught);
512
643
  }
644
+ }, _DurabilityFanout_emitTerminal = function _DurabilityFanout_emitTerminal(claim, reason, error) {
645
+ __classPrivateFieldGet(this, _DurabilityFanout_emit, "f").call(this, {
646
+ ...entity(claim),
647
+ type: 'terminal',
648
+ timestamp: Date.now(),
649
+ attempt: claim.row.attempt,
650
+ reason: reason === 'explicit' ? 'dead_lettered' : 'attempts_exhausted',
651
+ error: error ?? {
652
+ name: 'DeadLetter',
653
+ message: 'Dead-lettered by consumer',
654
+ },
655
+ });
656
+ }, _DurabilityFanout_transaction = async function _DurabilityFanout_transaction(write) {
657
+ try {
658
+ return await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").transaction(write);
659
+ }
660
+ catch (error) {
661
+ __classPrivateFieldSet(this, _DurabilityFanout_pending, undefined, "f");
662
+ throw error;
663
+ }
664
+ }, _DurabilityFanout_pendingCount = function _DurabilityFanout_pendingCount() {
665
+ __classPrivateFieldSet(this, _DurabilityFanout_pending, __classPrivateFieldGet(this, _DurabilityFanout_pending, "f") ?? countRowSchema.parse(__classPrivateFieldGet(this, _DurabilityFanout_engine, "f").sql
666
+ .exec(`SELECT COUNT(*) AS count FROM durability_fanout_deliveries
667
+ WHERE status = 'pending'`)
668
+ .toArray()[0]).count, "f");
669
+ return __classPrivateFieldGet(this, _DurabilityFanout_pending, "f");
670
+ }, _DurabilityFanout_adjustPending = function _DurabilityFanout_adjustPending(delta) {
671
+ if (__classPrivateFieldGet(this, _DurabilityFanout_pending, "f") !== undefined) {
672
+ __classPrivateFieldSet(this, _DurabilityFanout_pending, __classPrivateFieldGet(this, _DurabilityFanout_pending, "f") + delta, "f");
673
+ }
674
+ }, _DurabilityFanout_listDue = function _DurabilityFanout_listDue(target, now) {
675
+ const first = deliveryRowSchema.array().parse(__classPrivateFieldGet(this, _DurabilityFanout_engine, "f").sql
676
+ .exec(`SELECT * FROM durability_fanout_deliveries
677
+ WHERE target_id = ? AND phase = 'delivery' AND status = 'pending'
678
+ AND attempt = 0 AND next_attempt_at <= ?
679
+ ORDER BY seq ASC
680
+ LIMIT ?`, target, now, __classPrivateFieldGet(this, _DurabilityFanout_maxBatchSize, "f"))
681
+ .toArray());
682
+ if (first.length >= __classPrivateFieldGet(this, _DurabilityFanout_maxBatchSize, "f")) {
683
+ return first;
684
+ }
685
+ const retries = deliveryRowSchema.array().parse(__classPrivateFieldGet(this, _DurabilityFanout_engine, "f").sql
686
+ .exec(`SELECT * FROM durability_fanout_deliveries
687
+ WHERE target_id = ? AND status = 'pending'
688
+ AND attempt > 0 AND next_attempt_at <= ?
689
+ ORDER BY seq ASC
690
+ LIMIT ?`, target, now, __classPrivateFieldGet(this, _DurabilityFanout_maxBatchSize, "f") - first.length)
691
+ .toArray());
692
+ return [...first, ...retries];
513
693
  }, _DurabilityFanout_deadline = async function _DurabilityFanout_deadline(run, timeoutMs) {
514
694
  let timer;
515
695
  try {
package/dist/index.d.ts CHANGED
@@ -1,10 +1,11 @@
1
- export { Durability, type DurabilityConfig, type DurabilityConstructor, type DurabilityOptions, type DurableCall, type DurableHandler, type DurableOperation, type DurableOperationResult, type HandlerMap, } from './durability.js';
2
- export { DurabilityAlarms, type DurabilityAlarmsConfig, type DurabilityAlarmsConstructor, type DurabilityAlarmsOptions, type DurableAlarmHandler, type DurableAlarmInfo, type DurableNamedAlarm, } from './durability-alarms.js';
3
- export { DurabilityFanout, type DurabilityFanoutConfig, type DurabilityFanoutMessage, type FanoutInput, type FanoutTarget, type FanoutEnqueueOptions, } from './fanout.js';
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
+ export { DurabilityAlarms, type DurabilityAlarmsConfig, type DurabilityAlarmsConstructor, type DurabilityAlarmsOptions, type DurabilityAlarmEvent, type DurableAlarmHandler, type DurableAlarmInfo, type DurableNamedAlarm, } from './durability-alarms.js';
3
+ export { DurabilityFanout, type DurabilityFanoutConfig, type DurabilityFanoutEvent, type DurabilityFanoutMessage, type FanoutInput, type FanoutTarget, type FanoutEnqueueOptions, } from './fanout.js';
4
+ 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';
4
5
  export { RoutingLoad, type EnqueueResult, type LoadSnapshot, type ProcessingLoad, } from './load.js';
5
6
  export type { MessageWrite, StoredMessage } from './stored-message.js';
6
- export { DurabilityScheduler, type DurabilityContext, type DurabilitySchedulerConfig, type DurabilitySchedulerOptions, type DurabilityStorageBackend, type SchedulerAttachment, } from './scheduler.js';
7
- export { DuplicateDurableCallError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, RoutingError, } from './errors.js';
8
- export type { DurabilityLifecycleEvent } from './lifecycle.js';
9
- export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, type DurabilityMigrationResult, type MigrationCapability, } from './migrations.js';
7
+ export { DurabilityScheduler, type DurabilityContext, type DurabilitySchedulerConfig, type DurabilitySchedulerOptions, type SchedulerAttachment, } from './scheduler.js';
8
+ export { DuplicateDurableCallError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
9
+ export type { DurabilityLifecycleEvent, LifecycleHook } from './lifecycle.js';
10
+ export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, type DurabilityMigrationResult, type MigrationCapability, } from './migrations.js';
10
11
  export type { DurabilityAlarmMethodOptions, DurabilityMethodOptions, DurabilityRetryOptions, } from './policy.js';
package/dist/index.js CHANGED
@@ -1,7 +1,8 @@
1
1
  export { Durability, } from './durability.js';
2
2
  export { DurabilityAlarms, } from './durability-alarms.js';
3
3
  export { DurabilityFanout, } from './fanout.js';
4
+ export { DurabilityLog, maxLogBytes, } from './log.js';
4
5
  export { RoutingLoad, } from './load.js';
5
6
  export { DurabilityScheduler, } from './scheduler.js';
6
- export { DuplicateDurableCallError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, RoutingError, } from './errors.js';
7
- export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, } from './migrations.js';
7
+ export { DuplicateDurableCallError, 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';