durability 4.1.1 → 4.2.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.
@@ -0,0 +1,72 @@
1
+ import type { DurabilityLifecycleEvent, LifecycleHook } from './lifecycle.js';
2
+ import { type DurabilityMigrationResult } from './migrations.js';
3
+ import { type DurabilityRetryOptions } from './policy.js';
4
+ import { type SchedulerAttachment } from './scheduler.js';
5
+ /** The newest staged version of one key, handed to `publish`. */
6
+ export type OutboxEntry<Value> = {
7
+ key: string;
8
+ /** Monotonic across the whole Durable Object; newer stages are larger. */
9
+ version: number;
10
+ value: Value;
11
+ /** One-based publication attempt for this version. */
12
+ attempt: number;
13
+ stagedAt: number;
14
+ /**
15
+ * Keeps this entry pending instead of acknowledging it when `publish`
16
+ * returns. Only callable while `publish` is running.
17
+ */
18
+ retry(delayMs?: number): void;
19
+ };
20
+ export type DurabilityOutboxConfig<Value> = SchedulerAttachment & {
21
+ /**
22
+ * Stable channel ID. Outboxes on one scheduler share storage, partitioned by
23
+ * channel, and each owns its own `publish`. Defaults to `default`.
24
+ */
25
+ channel?: string;
26
+ /**
27
+ * Publishes a batch of the newest pending versions. Returning acknowledges
28
+ * every entry not marked with `retry()`; throwing retries the whole batch.
29
+ * Sinks must be idempotent on `(key, version)` and keep the highest version.
30
+ */
31
+ publish(entries: OutboxEntry<Value>[]): unknown | Promise<unknown>;
32
+ /** Defaults to 50. */
33
+ maxBatchSize?: number;
34
+ /**
35
+ * Rounds first publication up to the next multiple of this delay so stages
36
+ * within one window share a batch. Defaults to 0.
37
+ */
38
+ batchDelayMs?: number;
39
+ /** Maximum duration of one `publish` call. Defaults to 60 seconds. */
40
+ attemptTimeoutMs?: number;
41
+ /** Publication is retried until acknowledged; only the delay is configurable. */
42
+ retries?: Pick<DurabilityRetryOptions, 'delay'>;
43
+ onLifecycleEvent?: LifecycleHook;
44
+ };
45
+ /** A lifecycle event for one of this outbox's entries. */
46
+ export type DurabilityOutboxEvent = Extract<DurabilityLifecycleEvent, {
47
+ entityKind: 'outbox_entry';
48
+ }>;
49
+ /**
50
+ * Package-internal: stages inside a transaction another helper already holds,
51
+ * so its reports commit atomically with that helper's own rows. Assigned by
52
+ * the class's static block.
53
+ */
54
+ export declare let stageWithin: <Value>(outbox: DurabilityOutbox<Value>, sql: SqlStorage, key: string, value: Value) => number;
55
+ /**
56
+ * A composable DO capability: keyed latest-state publication. Stage the
57
+ * newest value for a key in the same transaction as the state it describes;
58
+ * the outbox republishes the newest version until `publish` acknowledges it.
59
+ * Superseded versions are coalesced and may never be published.
60
+ */
61
+ export declare class DurabilityOutbox<Value = unknown> {
62
+ #private;
63
+ constructor(config: DurabilityOutboxConfig<Value>);
64
+ static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
65
+ alarm(info?: AlarmInvocationInfo): Promise<void>;
66
+ /**
67
+ * Durably stages the newest value for `key` and returns its version. On a
68
+ * SQLite-backed object, staging inside `ctx.storage.transaction()` commits
69
+ * atomically with the application's own writes in that transaction.
70
+ */
71
+ stage(key: string, value: Value): Promise<number>;
72
+ }
package/dist/outbox.js ADDED
@@ -0,0 +1,385 @@
1
+ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
2
+ if (kind === "m") throw new TypeError("Private method is not writable");
3
+ if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
4
+ if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
5
+ return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
6
+ };
7
+ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
8
+ if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
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
+ return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
+ };
12
+ var _DurabilityOutbox_instances, _DurabilityOutbox_engine, _DurabilityOutbox_channel, _DurabilityOutbox_publish, _DurabilityOutbox_maxBatchSize, _DurabilityOutbox_batchDelayMs, _DurabilityOutbox_attemptTimeoutMs, _DurabilityOutbox_delay, _DurabilityOutbox_emit, _DurabilityOutbox_running, _DurabilityOutbox_stageIn, _DurabilityOutbox_emitRegistered, _DurabilityOutbox_attach, _DurabilityOutbox_firstAttemptAt, _DurabilityOutbox_runDue, _DurabilityOutbox_runBatch, _DurabilityOutbox_publishBatch, _DurabilityOutbox_retryDelay, _DurabilityOutbox_deadline;
13
+ import { OutboxTimeoutError, reportFailure, serializeError, } from './errors.js';
14
+ import { durabilityOutboxMigrations, migrate, } from './migrations.js';
15
+ import { assertPositiveInteger, } from './policy.js';
16
+ import { engineFor, } from './scheduler.js';
17
+ import { deserialize, serialize } from './serialization.js';
18
+ import { claimAttempt, deleteAttempt, updateAttempt, } from './storage.js';
19
+ import { exponential, jitter } from './utils.js';
20
+ import { z } from 'zod';
21
+ const outboxTable = { name: 'durability_outbox', key: 'id' };
22
+ const outboxRowSchema = z.object({
23
+ id: z.string(),
24
+ channel: z.string(),
25
+ entry_key: z.string(),
26
+ version: z.number().int().positive(),
27
+ payload: z.string(),
28
+ status: z.literal('pending'),
29
+ attempt: z.number().int().nonnegative(),
30
+ next_attempt_at: z.number().int().nonnegative(),
31
+ last_error: z.string().nullable(),
32
+ last_error_name: z.string().nullable(),
33
+ created_at: z.number().int().nonnegative(),
34
+ generation_id: z.string(),
35
+ });
36
+ const versionRowSchema = z.object({ version: z.number().int().positive() });
37
+ const channelRowSchema = z.object({ channel: z.string() });
38
+ const listDueForChannel = (sql, channel, now, limit) => outboxRowSchema.array().parse(sql
39
+ .exec(`SELECT * FROM durability_outbox
40
+ WHERE channel = ? AND status = 'pending' AND next_attempt_at <= ?
41
+ ORDER BY next_attempt_at ASC, version ASC
42
+ LIMIT ?`, channel, now, limit)
43
+ .toArray());
44
+ /** Allocates a version from a durable counter that survives row deletion. */
45
+ const nextVersion = (sql) => {
46
+ const { version } = versionRowSchema.parse(sql
47
+ .exec(`UPDATE durability_outbox_seq
48
+ SET next_version = next_version + 1
49
+ WHERE id = 1
50
+ RETURNING next_version - 1 AS version`)
51
+ .toArray()[0]);
52
+ if (!Number.isSafeInteger(version + 1)) {
53
+ throw new RangeError('Outbox version exhausted');
54
+ }
55
+ return version;
56
+ };
57
+ /**
58
+ * Package-internal: stages inside a transaction another helper already holds,
59
+ * so its reports commit atomically with that helper's own rows. Assigned by
60
+ * the class's static block.
61
+ */
62
+ export let stageWithin;
63
+ const infrastructureRetryMs = 60000;
64
+ // setTimeout overflows past 2^31 - 1 ms, and it keeps every derived timestamp
65
+ // far inside the safe-integer range the storage indexes accept.
66
+ const maxDelayMs = 2 ** 31 - 1;
67
+ const orphanBatchSize = 50;
68
+ const channelsByEngine = new WeakMap();
69
+ const rowId = (channel, key) => JSON.stringify([channel, key]);
70
+ const entity = (row) => ({
71
+ entityKind: 'outbox_entry',
72
+ channel: row.channel,
73
+ id: row.entry_key,
74
+ generation: row.generation_id,
75
+ });
76
+ /**
77
+ * Rows of a channel no outbox registers would stay due forever and keep the
78
+ * alarm awake, so they are postponed like a removed fanout target's work.
79
+ */
80
+ const postponeOrphans = async (engine, channels) => {
81
+ const orphans = channelRowSchema
82
+ .array()
83
+ .parse(engine.sql
84
+ .exec('SELECT DISTINCT channel FROM durability_outbox ORDER BY channel')
85
+ .toArray())
86
+ .map((row) => row.channel)
87
+ .filter((channel) => !channels.has(channel));
88
+ for (const channel of orphans) {
89
+ const due = listDueForChannel(engine.sql, channel, Date.now(), orphanBatchSize);
90
+ if (due.length === 0) {
91
+ continue;
92
+ }
93
+ reportFailure('durability.outbox.channel_missing', { channel }, new Error(`Outbox channel "${channel}" is no longer configured; retaining entries`));
94
+ // eslint-disable-next-line no-await-in-loop
95
+ await engine.transaction((sql) => {
96
+ const postponedTo = Date.now() + infrastructureRetryMs;
97
+ for (const row of due) {
98
+ updateAttempt(sql, outboxTable, { key: row.id, generation: row.generation_id, attempt: row.attempt }, 'next_attempt_at = ?', postponedTo);
99
+ }
100
+ });
101
+ }
102
+ };
103
+ /**
104
+ * A composable DO capability: keyed latest-state publication. Stage the
105
+ * newest value for a key in the same transaction as the state it describes;
106
+ * the outbox republishes the newest version until `publish` acknowledges it.
107
+ * Superseded versions are coalesced and may never be published.
108
+ */
109
+ export class DurabilityOutbox {
110
+ constructor(config) {
111
+ _DurabilityOutbox_instances.add(this);
112
+ _DurabilityOutbox_engine.set(this, void 0);
113
+ _DurabilityOutbox_channel.set(this, void 0);
114
+ _DurabilityOutbox_publish.set(this, void 0);
115
+ _DurabilityOutbox_maxBatchSize.set(this, void 0);
116
+ _DurabilityOutbox_batchDelayMs.set(this, void 0);
117
+ _DurabilityOutbox_attemptTimeoutMs.set(this, void 0);
118
+ _DurabilityOutbox_delay.set(this, void 0);
119
+ _DurabilityOutbox_emit.set(this, void 0);
120
+ _DurabilityOutbox_running.set(this, void 0);
121
+ __classPrivateFieldSet(this, _DurabilityOutbox_channel, config.channel ?? 'default', "f");
122
+ if (typeof __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f") !== 'string' || __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f").length === 0) {
123
+ throw new TypeError('Outbox channel must be a non-empty string');
124
+ }
125
+ if (typeof config.publish !== 'function') {
126
+ throw new TypeError('Outbox requires a publish function');
127
+ }
128
+ __classPrivateFieldSet(this, _DurabilityOutbox_maxBatchSize, config.maxBatchSize ?? 50, "f");
129
+ assertPositiveInteger('maxBatchSize', __classPrivateFieldGet(this, _DurabilityOutbox_maxBatchSize, "f"));
130
+ __classPrivateFieldSet(this, _DurabilityOutbox_batchDelayMs, config.batchDelayMs ?? 0, "f");
131
+ if (!Number.isSafeInteger(__classPrivateFieldGet(this, _DurabilityOutbox_batchDelayMs, "f")) || __classPrivateFieldGet(this, _DurabilityOutbox_batchDelayMs, "f") < 0) {
132
+ throw new RangeError('batchDelayMs must be a non-negative integer');
133
+ }
134
+ __classPrivateFieldSet(this, _DurabilityOutbox_attemptTimeoutMs, config.attemptTimeoutMs ?? 60000, "f");
135
+ assertPositiveInteger('attemptTimeoutMs', __classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f"));
136
+ if (__classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f") > maxDelayMs) {
137
+ throw new RangeError(`attemptTimeoutMs must be at most ${maxDelayMs}`);
138
+ }
139
+ if (__classPrivateFieldGet(this, _DurabilityOutbox_batchDelayMs, "f") > maxDelayMs) {
140
+ throw new RangeError(`batchDelayMs must be at most ${maxDelayMs}`);
141
+ }
142
+ __classPrivateFieldSet(this, _DurabilityOutbox_delay, config.retries?.delay ?? ((attempt) => jitter(exponential(attempt))), "f");
143
+ __classPrivateFieldSet(this, _DurabilityOutbox_publish, config.publish, "f");
144
+ __classPrivateFieldSet(this, _DurabilityOutbox_engine, engineFor(config), "f");
145
+ __classPrivateFieldSet(this, _DurabilityOutbox_emit, __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").emitter(config.onLifecycleEvent), "f");
146
+ __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").migrateSchema('outbox', durabilityOutboxMigrations);
147
+ __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_attach).call(this);
148
+ }
149
+ static migrate(context, target) {
150
+ return migrate(context.storage, 'outbox', durabilityOutboxMigrations, target);
151
+ }
152
+ alarm(info) {
153
+ return __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").alarm(info);
154
+ }
155
+ /**
156
+ * Durably stages the newest value for `key` and returns its version. On a
157
+ * SQLite-backed object, staging inside `ctx.storage.transaction()` commits
158
+ * atomically with the application's own writes in that transaction.
159
+ */
160
+ async stage(key, value) {
161
+ const row = await __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").transaction((sql) => __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_stageIn).call(this, sql, key, value));
162
+ __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_emitRegistered).call(this, row);
163
+ return row.version;
164
+ }
165
+ }
166
+ _DurabilityOutbox_engine = new WeakMap(), _DurabilityOutbox_channel = new WeakMap(), _DurabilityOutbox_publish = new WeakMap(), _DurabilityOutbox_maxBatchSize = new WeakMap(), _DurabilityOutbox_batchDelayMs = new WeakMap(), _DurabilityOutbox_attemptTimeoutMs = new WeakMap(), _DurabilityOutbox_delay = new WeakMap(), _DurabilityOutbox_emit = new WeakMap(), _DurabilityOutbox_running = new WeakMap(), _DurabilityOutbox_instances = new WeakSet(), _DurabilityOutbox_stageIn = function _DurabilityOutbox_stageIn(sql, key, value) {
167
+ if (typeof key !== 'string' || key.length === 0) {
168
+ throw new TypeError('Outbox keys must be non-empty strings');
169
+ }
170
+ const payload = serialize(value);
171
+ const version = nextVersion(sql);
172
+ const createdAt = Date.now();
173
+ const staged = {
174
+ id: rowId(__classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"), key),
175
+ channel: __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"),
176
+ entry_key: key,
177
+ version,
178
+ payload,
179
+ status: 'pending',
180
+ attempt: 0,
181
+ next_attempt_at: __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_firstAttemptAt).call(this, createdAt),
182
+ last_error: null,
183
+ last_error_name: null,
184
+ created_at: createdAt,
185
+ generation_id: String(version),
186
+ };
187
+ // Replacing the generation fences any in-flight publication of an older
188
+ // version: its acknowledgement can no longer delete this row.
189
+ sql.exec(`INSERT OR REPLACE INTO durability_outbox
190
+ (id, channel, entry_key, version, payload, status, attempt,
191
+ next_attempt_at, last_error, last_error_name, created_at, generation_id)
192
+ VALUES (?, ?, ?, ?, ?, 'pending', 0, ?, NULL, NULL, ?, ?)`, staged.id, staged.channel, staged.entry_key, staged.version, staged.payload, staged.next_attempt_at, staged.created_at, staged.generation_id);
193
+ return staged;
194
+ }, _DurabilityOutbox_emitRegistered = function _DurabilityOutbox_emitRegistered(row) {
195
+ __classPrivateFieldGet(this, _DurabilityOutbox_emit, "f").call(this, {
196
+ ...entity(row),
197
+ type: 'registered',
198
+ timestamp: row.created_at,
199
+ attempt: 0,
200
+ });
201
+ }, _DurabilityOutbox_attach = function _DurabilityOutbox_attach() {
202
+ let channels = channelsByEngine.get(__classPrivateFieldGet(this, _DurabilityOutbox_engine, "f"));
203
+ if (!channels) {
204
+ const created = new Map();
205
+ const engine = __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f");
206
+ engine.register({
207
+ table: outboxTable,
208
+ runDue: async () => {
209
+ await Promise.all([...created.values()].map((run) => run()));
210
+ await postponeOrphans(engine, created);
211
+ },
212
+ });
213
+ channelsByEngine.set(engine, created);
214
+ channels = created;
215
+ }
216
+ if (channels.has(__classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"))) {
217
+ throw new Error(`An outbox for channel "${__classPrivateFieldGet(this, _DurabilityOutbox_channel, "f")}" is already attached to this scheduler`);
218
+ }
219
+ channels.set(__classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"), () => __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_runDue).call(this));
220
+ }, _DurabilityOutbox_firstAttemptAt = function _DurabilityOutbox_firstAttemptAt(createdAt) {
221
+ if (__classPrivateFieldGet(this, _DurabilityOutbox_batchDelayMs, "f") === 0) {
222
+ return createdAt;
223
+ }
224
+ return Math.ceil(createdAt / __classPrivateFieldGet(this, _DurabilityOutbox_batchDelayMs, "f")) * __classPrivateFieldGet(this, _DurabilityOutbox_batchDelayMs, "f");
225
+ }, _DurabilityOutbox_runDue = function _DurabilityOutbox_runDue() {
226
+ __classPrivateFieldSet(this, _DurabilityOutbox_running, __classPrivateFieldGet(this, _DurabilityOutbox_running, "f") ?? __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_runBatch).call(this).finally(() => {
227
+ __classPrivateFieldSet(this, _DurabilityOutbox_running, undefined, "f");
228
+ }), "f");
229
+ return __classPrivateFieldGet(this, _DurabilityOutbox_running, "f");
230
+ }, _DurabilityOutbox_runBatch = async function _DurabilityOutbox_runBatch() {
231
+ // Every transaction reconciles the alarm; one per idle run keeps re-arming
232
+ // it while anything else on the scheduler is due, such as a running operation.
233
+ if (listDueForChannel(__classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").sql, __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"), Date.now(), 1)
234
+ .length === 0) {
235
+ return;
236
+ }
237
+ const release = await __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").acquirePermit();
238
+ try {
239
+ const claims = await __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").transaction((sql) => {
240
+ const due = listDueForChannel(sql, __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"), Date.now(), __classPrivateFieldGet(this, _DurabilityOutbox_maxBatchSize, "f"));
241
+ const deadline = Date.now() + __classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f");
242
+ const claimed = [];
243
+ for (const row of due) {
244
+ const attempt = claimAttempt(sql, outboxTable, row.id, row.generation_id, Number.MAX_SAFE_INTEGER);
245
+ if (attempt === undefined) {
246
+ continue;
247
+ }
248
+ // A crash mid-publication leaves the claim due again at the deadline.
249
+ updateAttempt(sql, outboxTable, { key: row.id, generation: row.generation_id, attempt }, 'next_attempt_at = ?', deadline);
250
+ claimed.push({ ...row, attempt });
251
+ }
252
+ return claimed;
253
+ });
254
+ if (claims.length > 0) {
255
+ await __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_publishBatch).call(this, claims);
256
+ }
257
+ }
258
+ finally {
259
+ release();
260
+ }
261
+ }, _DurabilityOutbox_publishBatch = async function _DurabilityOutbox_publishBatch(claims) {
262
+ const startedAt = Date.now();
263
+ const retries = new Map();
264
+ let open = true;
265
+ const entries = claims.map((row) => ({
266
+ key: row.entry_key,
267
+ version: row.version,
268
+ value: deserialize(row.payload),
269
+ attempt: row.attempt,
270
+ stagedAt: row.created_at,
271
+ retry: (delayMs) => {
272
+ if (!open) {
273
+ throw new Error('Outbox entries can only be retried while publish is running');
274
+ }
275
+ if (delayMs !== undefined &&
276
+ (!Number.isSafeInteger(delayMs) ||
277
+ delayMs < 0 ||
278
+ delayMs > maxDelayMs)) {
279
+ throw new RangeError(`delayMs must be an integer from 0 to ${maxDelayMs}`);
280
+ }
281
+ retries.set(row.id, delayMs);
282
+ },
283
+ }));
284
+ for (const row of claims) {
285
+ __classPrivateFieldGet(this, _DurabilityOutbox_emit, "f").call(this, {
286
+ ...entity(row),
287
+ type: 'attempt_started',
288
+ timestamp: startedAt,
289
+ attempt: row.attempt,
290
+ });
291
+ }
292
+ let failure;
293
+ try {
294
+ await __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_deadline).call(this, () => __classPrivateFieldGet(this, _DurabilityOutbox_publish, "f").call(this, entries));
295
+ }
296
+ catch (error) {
297
+ failure = serializeError(error);
298
+ }
299
+ finally {
300
+ open = false;
301
+ }
302
+ const retryError = failure ?? {
303
+ name: 'Retry',
304
+ message: 'Retried by publisher',
305
+ };
306
+ const acknowledged = [];
307
+ const retried = [];
308
+ await __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").transaction((sql) => {
309
+ for (const row of claims) {
310
+ const ref = {
311
+ key: row.id,
312
+ generation: row.generation_id,
313
+ attempt: row.attempt,
314
+ };
315
+ if (failure === undefined && !retries.has(row.id)) {
316
+ if (deleteAttempt(sql, outboxTable, ref)) {
317
+ acknowledged.push(row);
318
+ }
319
+ continue;
320
+ }
321
+ const nextAttemptAt = Date.now() + (retries.get(row.id) ?? __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_retryDelay).call(this, row.attempt));
322
+ const settled = updateAttempt(sql, outboxTable, ref, 'next_attempt_at = ?, last_error = ?, last_error_name = ?', nextAttemptAt, retryError.message, retryError.name);
323
+ if (settled) {
324
+ retried.push({ row, nextAttemptAt });
325
+ }
326
+ }
327
+ });
328
+ const timestamp = Date.now();
329
+ const durationMs = Math.max(0, timestamp - startedAt);
330
+ for (const row of acknowledged) {
331
+ __classPrivateFieldGet(this, _DurabilityOutbox_emit, "f").call(this, {
332
+ ...entity(row),
333
+ type: 'attempt_settled',
334
+ timestamp,
335
+ attempt: row.attempt,
336
+ durationMs,
337
+ outcome: 'completed',
338
+ });
339
+ }
340
+ for (const { row, nextAttemptAt } of retried) {
341
+ __classPrivateFieldGet(this, _DurabilityOutbox_emit, "f").call(this, {
342
+ ...entity(row),
343
+ type: 'attempt_settled',
344
+ timestamp,
345
+ attempt: row.attempt,
346
+ durationMs,
347
+ outcome: 'retry_scheduled',
348
+ nextAttemptAt,
349
+ error: retryError,
350
+ });
351
+ }
352
+ }, _DurabilityOutbox_retryDelay = function _DurabilityOutbox_retryDelay(attempt) {
353
+ try {
354
+ const delay = Math.round(__classPrivateFieldGet(this, _DurabilityOutbox_delay, "f").call(this, attempt));
355
+ if (Number.isSafeInteger(delay) && delay >= 0 && delay <= maxDelayMs) {
356
+ return delay;
357
+ }
358
+ }
359
+ catch (error) {
360
+ reportFailure('durability.outbox.retry_policy_failed', { channel: __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f") }, error);
361
+ }
362
+ return infrastructureRetryMs;
363
+ }, _DurabilityOutbox_deadline = async function _DurabilityOutbox_deadline(run) {
364
+ let timer;
365
+ try {
366
+ await Promise.race([
367
+ Promise.resolve().then(run),
368
+ new Promise((_resolve, reject) => {
369
+ timer = setTimeout(() => reject(new OutboxTimeoutError(__classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f"))), __classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f"));
370
+ }),
371
+ ]);
372
+ }
373
+ finally {
374
+ if (timer !== undefined) {
375
+ clearTimeout(timer);
376
+ }
377
+ }
378
+ };
379
+ (() => {
380
+ stageWithin = (outbox, sql, key, value) => {
381
+ const row = __classPrivateFieldGet(outbox, _DurabilityOutbox_instances, "m", _DurabilityOutbox_stageIn).call(outbox, sql, key, value);
382
+ __classPrivateFieldGet(outbox, _DurabilityOutbox_instances, "m", _DurabilityOutbox_emitRegistered).call(outbox, row);
383
+ return row.version;
384
+ };
385
+ })();
package/dist/routing.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { type TransformContext, type TransformStub } from '@durability/transforms';
2
+ import { type DurableObjectTarget } from './durable-object-target.js';
2
3
  import { RoutingLoad, type EnqueueResult } from './load.js';
3
4
  import { type Sharding } from './routing-client.js';
4
5
  export type { EnqueueResult, LoadSnapshot, ProcessingLoad } from './load.js';
@@ -9,15 +10,7 @@ export type RoutingSession<Input, Value, Context = unknown> = {
9
10
  invoke(method: string, args: unknown[]): Promise<unknown>;
10
11
  };
11
12
  };
12
- export type DurabilityRoutingConfig<Target extends Rpc.DurableObjectBranded, Input, Value, Context = unknown> = {
13
- /** Application-owned exported Durable Object class. */
14
- target: {
15
- prototype: Target;
16
- };
17
- /** Injected by the Vite plugin; explicit for builds without it. */
18
- exportName?: string;
19
- /** Explicit namespace escape hatch for cross-worker or non-Vite consumers. */
20
- namespace?: () => DurableObjectNamespace<Target>;
13
+ export type DurabilityRoutingConfig<Target extends Rpc.DurableObjectBranded, Input, Value, Context = unknown> = DurableObjectTarget<Target> & {
21
14
  /** Chooses the application method/capability to invoke; never hardcoded. */
22
15
  invoke(stub: DurableObjectStub<Target>, input: Input): Promise<EnqueueResult<Value>>;
23
16
  sharding?: Sharding<Input, Context>;
package/dist/routing.js CHANGED
@@ -1,5 +1,5 @@
1
- import { exports as workerExports } from 'cloudflare:workers';
2
1
  import { createTransformStub, } from '@durability/transforms';
2
+ import { resolveNamespace, } from './durable-object-target.js';
3
3
  import { RoutingError } from './errors.js';
4
4
  import { RoutingLoad } from './load.js';
5
5
  import { RoutingClient } from './routing-client.js';
@@ -12,19 +12,7 @@ export class DurabilityRouting extends RoutingLoad {
12
12
  static client(config) {
13
13
  const client = new RoutingClient({
14
14
  invoke: (address, input) => {
15
- let namespace = config.namespace?.();
16
- if (!namespace) {
17
- if (!config.exportName) {
18
- throw new RoutingError('Use the durability Vite plugin, exportName, or an explicit namespace to resolve the routing target');
19
- }
20
- const exported = Reflect.get(workerExports, config.exportName);
21
- if (exported === null ||
22
- (typeof exported !== 'object' && typeof exported !== 'function') ||
23
- typeof Reflect.get(exported, 'getByName') !== 'function') {
24
- throw new RoutingError(`Export "${config.exportName}" is not a Durable Object namespace`);
25
- }
26
- namespace = exported;
27
- }
15
+ const namespace = resolveNamespace(config, (message) => new RoutingError(message));
28
16
  const stub = namespace.getByName(address.shard, address.locationHint === undefined
29
17
  ? undefined
30
18
  : { locationHint: address.locationHint });
@@ -1,4 +1,4 @@
1
- import { type Emit, type LifecycleEntity, type LifecycleHook } from './lifecycle.js';
1
+ import { type DurabilityLifecycleEvent, type Emit, type LifecycleEntity } from './lifecycle.js';
2
2
  import { type MigrationCapability } from './migrations.js';
3
3
  import { type AttemptPolicy } from './policy.js';
4
4
  import { type DurableTable } from './storage.js';
@@ -32,6 +32,8 @@ export type SchedulerAttachment = {
32
32
  export type Participant = {
33
33
  table: DurableTable;
34
34
  runDue(now: number, info: AlarmInvocationInfo | undefined): Promise<void>;
35
+ /** Earliest due time, for tables without `status` and `next_attempt_at` columns. */
36
+ nextPendingAt?(sql: SqlStorage): number | undefined;
35
37
  };
36
38
  /**
37
39
  * Called after a record may have settled. Successful completions pass the
@@ -89,7 +91,10 @@ export declare class Engine {
89
91
  constructor(context: DurabilityContext, options: DurabilitySchedulerOptions);
90
92
  register(participant: Participant): void;
91
93
  waitUntil(promise: Promise<unknown>, onError: (error: unknown) => void): void;
92
- emitter(hook: LifecycleHook | undefined): Emit;
94
+ emitter<Event extends {
95
+ entityKind: string;
96
+ type: string;
97
+ } = DurabilityLifecycleEvent>(hook: ((event: Event) => void | Promise<void>) | undefined): (event: Event) => void;
93
98
  /** Applies a helper's SQLite migrations. */
94
99
  migrateSchema(capability: MigrationCapability, migrations: DurableMigrations): void;
95
100
  /** Runs synchronous writes atomically without touching the physical alarm. */
@@ -117,11 +122,19 @@ export declare class Engine {
117
122
  acquirePermit(): Promise<() => void>;
118
123
  private createRelease;
119
124
  runConcurrent<Item>(items: Item[], worker: (item: Item) => Promise<void>): Promise<void>;
125
+ /**
126
+ * Runs due work and re-arms the physical alarm. A failure that would
127
+ * otherwise propagate to the platform is turned into a retry of our own,
128
+ * because the platform drops an alarm after a few failed deliveries.
129
+ */
130
+ alarm(info?: AlarmInvocationInfo): Promise<void>;
120
131
  /**
121
132
  * Runs every participant's due work, hands off to a fresh alarm if the
122
133
  * invocation approaches its wall-time limit, and re-arms the physical alarm.
123
134
  */
124
- alarm(info?: AlarmInvocationInfo): Promise<void>;
135
+ private runAlarm;
136
+ /** Arms the physical alarm directly, outside any transaction; the next run reconciles properly. */
137
+ private armFallbackAlarm;
125
138
  private armForHandoff;
126
139
  /**
127
140
  * Registers the execution in its active map synchronously, then claims and
package/dist/scheduler.js CHANGED
@@ -116,15 +116,21 @@ export class Engine {
116
116
  }
117
117
  /** Returns the earliest pending time and maintains its bounded physical fallback. */
118
118
  async reconcile(physicalAlarm) {
119
- const scheduled = this.participants.flatMap(({ table }) => nextAttemptRowSchema
120
- .array()
121
- .parse(this.sql
122
- .exec(`SELECT next_attempt_at FROM ${table.name}
119
+ const scheduled = this.participants.flatMap((participant) => {
120
+ if (participant.nextPendingAt) {
121
+ const at = participant.nextPendingAt(this.sql);
122
+ return at === undefined ? [] : [at];
123
+ }
124
+ return nextAttemptRowSchema
125
+ .array()
126
+ .parse(this.sql
127
+ .exec(`SELECT next_attempt_at FROM ${participant.table.name}
123
128
  WHERE status = 'pending'
124
129
  ORDER BY next_attempt_at ASC
125
130
  LIMIT 1`)
126
- .toArray())
127
- .map((row) => row.next_attempt_at));
131
+ .toArray())
132
+ .map((row) => row.next_attempt_at);
133
+ });
128
134
  const nextAlarmAt = scheduled.length === 0 ? undefined : Math.min(...scheduled);
129
135
  const currentAlarm = await physicalAlarm.getAlarm();
130
136
  if (nextAlarmAt === undefined) {
@@ -267,11 +273,30 @@ export class Engine {
267
273
  }
268
274
  }));
269
275
  }
276
+ /**
277
+ * Runs due work and re-arms the physical alarm. A failure that would
278
+ * otherwise propagate to the platform is turned into a retry of our own,
279
+ * because the platform drops an alarm after a few failed deliveries.
280
+ */
281
+ async alarm(info) {
282
+ try {
283
+ await this.runAlarm(info);
284
+ }
285
+ catch (error) {
286
+ // Throwing lets the platform retry, but it gives up after a few failures
287
+ // and drops the alarm, stranding pending work. Keeping our own alarm
288
+ // armed turns the failure into a retry we control instead.
289
+ if (!(await this.armFallbackAlarm())) {
290
+ throw error;
291
+ }
292
+ reportFailure('durability.alarm.failed', { retryInMs: this.alarmMinDelayMs }, error);
293
+ }
294
+ }
270
295
  /**
271
296
  * Runs every participant's due work, hands off to a fresh alarm if the
272
297
  * invocation approaches its wall-time limit, and re-arms the physical alarm.
273
298
  */
274
- async alarm(info) {
299
+ async runAlarm(info) {
275
300
  const startedAt = Date.now();
276
301
  const execution = Promise.all(this.participants.map((participant) => participant.runDue(startedAt, info))).then(() => undefined);
277
302
  void execution.catch(() => undefined);
@@ -298,6 +323,16 @@ export class Engine {
298
323
  }
299
324
  await this.scheduleNextAlarm();
300
325
  }
326
+ /** Arms the physical alarm directly, outside any transaction; the next run reconciles properly. */
327
+ async armFallbackAlarm() {
328
+ try {
329
+ await this.context.storage.setAlarm(Date.now() + this.alarmMinDelayMs);
330
+ return true;
331
+ }
332
+ catch {
333
+ return false;
334
+ }
335
+ }
301
336
  armForHandoff(timestamp) {
302
337
  return this.context.storage.transaction(async (physicalAlarm) => {
303
338
  const currentAlarm = await physicalAlarm.getAlarm();
@@ -0,0 +1,22 @@
1
+ import { type PermitGrant, type PermitRequest, type PermitSync, type PermitSyncResult, type SemaphoreRequest, type SemaphoreResponse } from './semaphore-protocol.js';
2
+ export type SemaphoreAddress = {
3
+ /** The semaphore key: the name of the Durable Object holding the limit. */
4
+ key: string;
5
+ locationHint?: DurableObjectLocationHint;
6
+ };
7
+ export type SemaphoreClientConfig = {
8
+ invoke(address: SemaphoreAddress, message: SemaphoreRequest): Promise<SemaphoreResponse>;
9
+ locationHint?: (key: string) => DurableObjectLocationHint | undefined;
10
+ };
11
+ /**
12
+ * Transport-independent protocol core. Validates responses and remembers each
13
+ * key's `nextRequestAt` so callers can pace requests the way the holder asked.
14
+ */
15
+ export declare class SemaphoreClient {
16
+ #private;
17
+ constructor(config: SemaphoreClientConfig);
18
+ /** Earliest time the holder of `key` accepts another request, if known. */
19
+ nextRequestAt(key: string): number | undefined;
20
+ request(key: string, message: PermitRequest): Promise<PermitGrant>;
21
+ sync(key: string, message: PermitSync): Promise<PermitSyncResult>;
22
+ }