durability 4.1.2 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +406 -1
  2. package/dist/dev.d.ts +22 -0
  3. package/dist/dev.js +149 -0
  4. package/dist/durability-alarms.d.ts +1 -1
  5. package/dist/durability-alarms.js +6 -4
  6. package/dist/durability.d.ts +1 -1
  7. package/dist/durability.js +8 -5
  8. package/dist/durable-object-target.d.ts +12 -0
  9. package/dist/durable-object-target.js +17 -0
  10. package/dist/errors.d.ts +25 -0
  11. package/dist/errors.js +36 -0
  12. package/dist/experimental.d.ts +8 -0
  13. package/dist/experimental.js +6 -0
  14. package/dist/fanout.js +14 -9
  15. package/dist/index.d.ts +2 -1
  16. package/dist/index.js +1 -1
  17. package/dist/lifecycle.d.ts +14 -3
  18. package/dist/lifecycle.js +3 -2
  19. package/dist/log.js +26 -4
  20. package/dist/migrations.d.ts +74 -2
  21. package/dist/migrations.js +307 -36
  22. package/dist/outbox.d.ts +85 -0
  23. package/dist/outbox.js +433 -0
  24. package/dist/routing.d.ts +2 -9
  25. package/dist/routing.js +2 -14
  26. package/dist/scheduler.d.ts +14 -2
  27. package/dist/scheduler.js +38 -13
  28. package/dist/semaphore-client.d.ts +22 -0
  29. package/dist/semaphore-client.js +61 -0
  30. package/dist/semaphore-leases.d.ts +109 -0
  31. package/dist/semaphore-leases.js +272 -0
  32. package/dist/semaphore-protocol.d.ts +231 -0
  33. package/dist/semaphore-protocol.js +106 -0
  34. package/dist/semaphore-queue-store.d.ts +95 -0
  35. package/dist/semaphore-queue-store.js +248 -0
  36. package/dist/semaphore-queue.d.ts +119 -0
  37. package/dist/semaphore-queue.js +863 -0
  38. package/dist/semaphore-server.d.ts +89 -0
  39. package/dist/semaphore-server.js +518 -0
  40. package/dist/semaphore-store.d.ts +43 -0
  41. package/dist/semaphore-store.js +108 -0
  42. package/dist/semaphore.d.ts +42 -0
  43. package/dist/semaphore.js +57 -0
  44. package/dist/socket.js +19 -10
  45. package/dist/topology-client.d.ts +40 -0
  46. package/dist/topology-client.js +180 -0
  47. package/dist/topology-snapshot.d.ts +70 -0
  48. package/dist/topology-snapshot.js +48 -0
  49. package/dist/topology.d.ts +94 -0
  50. package/dist/topology.js +468 -0
  51. package/dist/tracker.js +2 -0
  52. package/package.json +6 -2
package/dist/outbox.js ADDED
@@ -0,0 +1,433 @@
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_publishNow, _DurabilityOutbox_exclusive, _DurabilityOutbox_runBatch, _DurabilityOutbox_publishBatch, _DurabilityOutbox_retryDelay, _DurabilityOutbox_deadline;
13
+ import { traceLifecycle, traceMethods } from './dev.js';
14
+ import { OutboxTimeoutError, reportFailure, serializeError, } from './errors.js';
15
+ import { durabilityOutboxMigrations, migrateCapability, } from './migrations.js';
16
+ import { assertPositiveInteger, } from './policy.js';
17
+ import { engineFor, } from './scheduler.js';
18
+ import { deserialize, serialize } from './serialization.js';
19
+ import { claimAttempt, deleteAttempt, updateAttempt, } from './storage.js';
20
+ import { exponential, jitter } from './utils.js';
21
+ import { z } from 'zod';
22
+ const outboxTable = { name: 'durability_outbox', key: 'id' };
23
+ const outboxRowSchema = z.object({
24
+ id: z.string(),
25
+ channel: z.string(),
26
+ entry_key: z.string(),
27
+ version: z.number().int().positive(),
28
+ payload: z.string(),
29
+ status: z.literal('pending'),
30
+ attempt: z.number().int().nonnegative(),
31
+ next_attempt_at: z.number().int().nonnegative(),
32
+ last_error: z.string().nullable(),
33
+ last_error_name: z.string().nullable(),
34
+ created_at: z.number().int().nonnegative(),
35
+ generation_id: z.string(),
36
+ });
37
+ const versionRowSchema = z.object({ version: z.number().int().positive() });
38
+ const channelRowSchema = z.object({ channel: z.string() });
39
+ const listDueForChannel = (sql, channel, now, limit, key) => outboxRowSchema.array().parse(sql
40
+ .exec(`SELECT * FROM durability_outbox
41
+ WHERE channel = ? AND status = 'pending' AND next_attempt_at <= ?
42
+ AND (? IS NULL OR entry_key = ?)
43
+ ORDER BY next_attempt_at ASC, version ASC
44
+ LIMIT ?`, channel, now, key ?? null, key ?? null, limit)
45
+ .toArray());
46
+ /** Allocates a version from a durable counter that survives row deletion. */
47
+ const nextVersion = (sql) => {
48
+ const { version } = versionRowSchema.parse(sql
49
+ .exec(`UPDATE durability_outbox_seq
50
+ SET next_version = next_version + 1
51
+ WHERE id = 1
52
+ RETURNING next_version - 1 AS version`)
53
+ .toArray()[0]);
54
+ if (!Number.isSafeInteger(version + 1)) {
55
+ throw new RangeError('Outbox version exhausted');
56
+ }
57
+ return version;
58
+ };
59
+ /**
60
+ * Package-internal: stages inside a transaction another helper already holds,
61
+ * so its reports commit atomically with that helper's own rows. Assigned by
62
+ * the class's static block.
63
+ */
64
+ export let stageWithin;
65
+ /**
66
+ * Package-internal: drops a key's pending version inside a held transaction.
67
+ * An in-flight publication of it still completes, but its acknowledgement and
68
+ * retry both miss.
69
+ */
70
+ export let discardWithin;
71
+ /**
72
+ * Package-internal: publishes a key's pending version now, even one waiting
73
+ * out a retry delay or batch window, serialized with the channel's other
74
+ * publish runs, and reports whether nothing is left pending for it. Takes no
75
+ * scheduler permit, so a caller holding the last one cannot deadlock.
76
+ */
77
+ export let publishNow;
78
+ const infrastructureRetryMs = 60000;
79
+ // setTimeout overflows past 2^31 - 1 ms, and it keeps every derived timestamp
80
+ // far inside the safe-integer range the storage indexes accept.
81
+ const maxDelayMs = 2 ** 31 - 1;
82
+ const orphanBatchSize = 50;
83
+ const channelsByEngine = new WeakMap();
84
+ const rowId = (channel, key) => JSON.stringify([channel, key]);
85
+ const entity = (row) => ({
86
+ entityKind: 'outbox_entry',
87
+ channel: row.channel,
88
+ id: row.entry_key,
89
+ generation: row.generation_id,
90
+ });
91
+ /**
92
+ * Rows of a channel no outbox registers would stay due forever and keep the
93
+ * alarm awake, so they are postponed like a removed fanout target's work.
94
+ */
95
+ const postponeOrphans = async (engine, channels) => {
96
+ const orphans = channelRowSchema
97
+ .array()
98
+ .parse(engine.sql
99
+ .exec('SELECT DISTINCT channel FROM durability_outbox ORDER BY channel')
100
+ .toArray())
101
+ .map((row) => row.channel)
102
+ .filter((channel) => !channels.has(channel));
103
+ for (const channel of orphans) {
104
+ const due = listDueForChannel(engine.sql, channel, Date.now(), orphanBatchSize);
105
+ if (due.length === 0) {
106
+ continue;
107
+ }
108
+ reportFailure('durability.outbox.channel_missing', { channel }, new Error(`Outbox channel "${channel}" is no longer configured; retaining entries`));
109
+ // eslint-disable-next-line no-await-in-loop
110
+ await engine.transaction((sql) => {
111
+ const postponedTo = Date.now() + infrastructureRetryMs;
112
+ for (const row of due) {
113
+ updateAttempt(sql, outboxTable, { key: row.id, generation: row.generation_id, attempt: row.attempt }, 'next_attempt_at = ?', postponedTo);
114
+ }
115
+ });
116
+ }
117
+ };
118
+ /**
119
+ * A composable DO capability: keyed latest-state publication. Stage the
120
+ * newest value for a key in the same transaction as the state it describes;
121
+ * the outbox republishes the newest version until `publish` acknowledges it.
122
+ * Superseded versions are coalesced and may never be published.
123
+ */
124
+ export class DurabilityOutbox {
125
+ constructor(config) {
126
+ _DurabilityOutbox_instances.add(this);
127
+ _DurabilityOutbox_engine.set(this, void 0);
128
+ _DurabilityOutbox_channel.set(this, void 0);
129
+ _DurabilityOutbox_publish.set(this, void 0);
130
+ _DurabilityOutbox_maxBatchSize.set(this, void 0);
131
+ _DurabilityOutbox_batchDelayMs.set(this, void 0);
132
+ _DurabilityOutbox_attemptTimeoutMs.set(this, void 0);
133
+ _DurabilityOutbox_delay.set(this, void 0);
134
+ _DurabilityOutbox_emit.set(this, void 0);
135
+ /** The channel's one publish run, never one still waiting for a permit. */
136
+ _DurabilityOutbox_running.set(this, void 0);
137
+ __classPrivateFieldSet(this, _DurabilityOutbox_channel, config.channel ?? 'default', "f");
138
+ if (typeof __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f") !== 'string' || __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f").length === 0) {
139
+ throw new TypeError('Outbox channel must be a non-empty string');
140
+ }
141
+ if (typeof config.publish !== 'function') {
142
+ throw new TypeError('Outbox requires a publish function');
143
+ }
144
+ __classPrivateFieldSet(this, _DurabilityOutbox_maxBatchSize, config.maxBatchSize ?? 50, "f");
145
+ assertPositiveInteger('maxBatchSize', __classPrivateFieldGet(this, _DurabilityOutbox_maxBatchSize, "f"));
146
+ __classPrivateFieldSet(this, _DurabilityOutbox_batchDelayMs, config.batchDelayMs ?? 0, "f");
147
+ if (!Number.isSafeInteger(__classPrivateFieldGet(this, _DurabilityOutbox_batchDelayMs, "f")) || __classPrivateFieldGet(this, _DurabilityOutbox_batchDelayMs, "f") < 0) {
148
+ throw new RangeError('batchDelayMs must be a non-negative integer');
149
+ }
150
+ __classPrivateFieldSet(this, _DurabilityOutbox_attemptTimeoutMs, config.attemptTimeoutMs ?? 60000, "f");
151
+ assertPositiveInteger('attemptTimeoutMs', __classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f"));
152
+ if (__classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f") > maxDelayMs) {
153
+ throw new RangeError(`attemptTimeoutMs must be at most ${maxDelayMs}`);
154
+ }
155
+ if (__classPrivateFieldGet(this, _DurabilityOutbox_batchDelayMs, "f") > maxDelayMs) {
156
+ throw new RangeError(`batchDelayMs must be at most ${maxDelayMs}`);
157
+ }
158
+ __classPrivateFieldSet(this, _DurabilityOutbox_delay, config.retries?.delay ?? ((attempt) => jitter(exponential(attempt))), "f");
159
+ __classPrivateFieldSet(this, _DurabilityOutbox_publish, config.publish, "f");
160
+ __classPrivateFieldSet(this, _DurabilityOutbox_engine, engineFor(config), "f");
161
+ __classPrivateFieldSet(this, _DurabilityOutbox_emit, traceLifecycle(__classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").emitter(config.onLifecycleEvent)), "f");
162
+ __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").migrateSchema('outbox', durabilityOutboxMigrations);
163
+ __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_attach).call(this);
164
+ }
165
+ static migrate(context, target) {
166
+ return migrateCapability(context.storage, 'outbox', durabilityOutboxMigrations, target);
167
+ }
168
+ alarm(info) {
169
+ return __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").alarm(info);
170
+ }
171
+ /**
172
+ * Durably stages the newest value for `key` and returns its version. On a
173
+ * SQLite-backed object, staging inside `ctx.storage.transaction()` commits
174
+ * atomically with the application's own writes in that transaction.
175
+ */
176
+ async stage(key, value) {
177
+ const row = await __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").transaction((sql) => __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_stageIn).call(this, sql, key, value));
178
+ __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_emitRegistered).call(this, row);
179
+ return row.version;
180
+ }
181
+ }
182
+ _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) {
183
+ if (typeof key !== 'string' || key.length === 0) {
184
+ throw new TypeError('Outbox keys must be non-empty strings');
185
+ }
186
+ const payload = serialize(value);
187
+ const version = nextVersion(sql);
188
+ const createdAt = Date.now();
189
+ const staged = {
190
+ id: rowId(__classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"), key),
191
+ channel: __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"),
192
+ entry_key: key,
193
+ version,
194
+ payload,
195
+ status: 'pending',
196
+ attempt: 0,
197
+ next_attempt_at: __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_firstAttemptAt).call(this, createdAt),
198
+ last_error: null,
199
+ last_error_name: null,
200
+ created_at: createdAt,
201
+ generation_id: String(version),
202
+ };
203
+ // Replacing the generation fences any in-flight publication of an older
204
+ // version: its acknowledgement can no longer delete this row.
205
+ sql.exec(`INSERT OR REPLACE INTO durability_outbox
206
+ (id, channel, entry_key, version, payload, status, attempt,
207
+ next_attempt_at, last_error, last_error_name, created_at, generation_id)
208
+ 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);
209
+ return staged;
210
+ }, _DurabilityOutbox_emitRegistered = function _DurabilityOutbox_emitRegistered(row) {
211
+ __classPrivateFieldGet(this, _DurabilityOutbox_emit, "f").call(this, {
212
+ ...entity(row),
213
+ type: 'registered',
214
+ timestamp: row.created_at,
215
+ attempt: 0,
216
+ });
217
+ }, _DurabilityOutbox_attach = function _DurabilityOutbox_attach() {
218
+ let channels = channelsByEngine.get(__classPrivateFieldGet(this, _DurabilityOutbox_engine, "f"));
219
+ if (!channels) {
220
+ const created = new Map();
221
+ const engine = __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f");
222
+ engine.register({
223
+ table: outboxTable,
224
+ runDue: async () => {
225
+ await Promise.all([...created.values()].map((run) => run()));
226
+ await postponeOrphans(engine, created);
227
+ },
228
+ });
229
+ channelsByEngine.set(engine, created);
230
+ channels = created;
231
+ }
232
+ if (channels.has(__classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"))) {
233
+ throw new Error(`An outbox for channel "${__classPrivateFieldGet(this, _DurabilityOutbox_channel, "f")}" is already attached to this scheduler`);
234
+ }
235
+ channels.set(__classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"), () => __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_runDue).call(this));
236
+ }, _DurabilityOutbox_firstAttemptAt = function _DurabilityOutbox_firstAttemptAt(createdAt) {
237
+ if (__classPrivateFieldGet(this, _DurabilityOutbox_batchDelayMs, "f") === 0) {
238
+ return createdAt;
239
+ }
240
+ return Math.ceil(createdAt / __classPrivateFieldGet(this, _DurabilityOutbox_batchDelayMs, "f")) * __classPrivateFieldGet(this, _DurabilityOutbox_batchDelayMs, "f");
241
+ }, _DurabilityOutbox_runDue = async function _DurabilityOutbox_runDue() {
242
+ if (__classPrivateFieldGet(this, _DurabilityOutbox_running, "f")) {
243
+ return __classPrivateFieldGet(this, _DurabilityOutbox_running, "f");
244
+ }
245
+ // Every transaction reconciles the alarm; one per idle run keeps re-arming
246
+ // it while anything else on the scheduler is due, such as a running operation.
247
+ if (listDueForChannel(__classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").sql, __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"), Date.now(), 1)
248
+ .length === 0) {
249
+ return undefined;
250
+ }
251
+ // The permit is taken before claiming the channel, so nothing that holds
252
+ // the channel ever waits for a permit.
253
+ const release = await __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").acquirePermit();
254
+ try {
255
+ if (__classPrivateFieldGet(this, _DurabilityOutbox_running, "f")) {
256
+ return await __classPrivateFieldGet(this, _DurabilityOutbox_running, "f");
257
+ }
258
+ return await __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_exclusive).call(this, () => __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_runBatch).call(this));
259
+ }
260
+ finally {
261
+ release();
262
+ }
263
+ }, _DurabilityOutbox_publishNow = async function _DurabilityOutbox_publishNow(key) {
264
+ const pending = () => __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").sql
265
+ .exec('SELECT 1 FROM durability_outbox WHERE id = ?', rowId(__classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"), key))
266
+ .toArray().length > 0;
267
+ while (__classPrivateFieldGet(this, _DurabilityOutbox_running, "f")) {
268
+ // eslint-disable-next-line no-await-in-loop
269
+ await __classPrivateFieldGet(this, _DurabilityOutbox_running, "f").catch(() => undefined);
270
+ }
271
+ if (!pending()) {
272
+ return true;
273
+ }
274
+ await __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_exclusive).call(this, () => __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_runBatch).call(this, key));
275
+ return !pending();
276
+ }, _DurabilityOutbox_exclusive = function _DurabilityOutbox_exclusive(run) {
277
+ const running = run().finally(() => {
278
+ if (__classPrivateFieldGet(this, _DurabilityOutbox_running, "f") === running) {
279
+ __classPrivateFieldSet(this, _DurabilityOutbox_running, undefined, "f");
280
+ }
281
+ });
282
+ __classPrivateFieldSet(this, _DurabilityOutbox_running, running, "f");
283
+ return running;
284
+ }, _DurabilityOutbox_runBatch = async function _DurabilityOutbox_runBatch(key) {
285
+ const claims = await __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").transaction((sql) => {
286
+ // No run is in flight here, so a key's future attempt time is only a delay to skip.
287
+ const due = listDueForChannel(sql, __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"), key === undefined ? Date.now() : Number.MAX_SAFE_INTEGER, __classPrivateFieldGet(this, _DurabilityOutbox_maxBatchSize, "f"), key);
288
+ const deadline = Date.now() + __classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f");
289
+ const claimed = [];
290
+ for (const row of due) {
291
+ const attempt = claimAttempt(sql, outboxTable, row.id, row.generation_id, Number.MAX_SAFE_INTEGER);
292
+ if (attempt === undefined) {
293
+ continue;
294
+ }
295
+ // A crash mid-publication leaves the claim due again at the deadline.
296
+ updateAttempt(sql, outboxTable, { key: row.id, generation: row.generation_id, attempt }, 'next_attempt_at = ?', deadline);
297
+ claimed.push({ ...row, attempt });
298
+ }
299
+ return claimed;
300
+ });
301
+ if (claims.length > 0) {
302
+ await __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_publishBatch).call(this, claims);
303
+ }
304
+ }, _DurabilityOutbox_publishBatch = async function _DurabilityOutbox_publishBatch(claims) {
305
+ const startedAt = Date.now();
306
+ const retries = new Map();
307
+ let open = true;
308
+ const entries = claims.map((row) => ({
309
+ key: row.entry_key,
310
+ version: row.version,
311
+ value: deserialize(row.payload),
312
+ attempt: row.attempt,
313
+ stagedAt: row.created_at,
314
+ retry: (delayMs) => {
315
+ if (!open) {
316
+ throw new Error('Outbox entries can only be retried while publish is running');
317
+ }
318
+ if (delayMs !== undefined &&
319
+ (!Number.isSafeInteger(delayMs) ||
320
+ delayMs < 0 ||
321
+ delayMs > maxDelayMs)) {
322
+ throw new RangeError(`delayMs must be an integer from 0 to ${maxDelayMs}`);
323
+ }
324
+ retries.set(row.id, delayMs);
325
+ },
326
+ }));
327
+ for (const row of claims) {
328
+ __classPrivateFieldGet(this, _DurabilityOutbox_emit, "f").call(this, {
329
+ ...entity(row),
330
+ type: 'attempt_started',
331
+ timestamp: startedAt,
332
+ attempt: row.attempt,
333
+ });
334
+ }
335
+ let failure;
336
+ try {
337
+ await __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_deadline).call(this, () => __classPrivateFieldGet(this, _DurabilityOutbox_publish, "f").call(this, entries));
338
+ }
339
+ catch (error) {
340
+ failure = serializeError(error);
341
+ }
342
+ finally {
343
+ open = false;
344
+ }
345
+ const retryError = failure ?? {
346
+ name: 'Retry',
347
+ message: 'Retried by publisher',
348
+ };
349
+ const acknowledged = [];
350
+ const retried = [];
351
+ await __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").transaction((sql) => {
352
+ for (const row of claims) {
353
+ const ref = {
354
+ key: row.id,
355
+ generation: row.generation_id,
356
+ attempt: row.attempt,
357
+ };
358
+ if (failure === undefined && !retries.has(row.id)) {
359
+ if (deleteAttempt(sql, outboxTable, ref)) {
360
+ acknowledged.push(row);
361
+ }
362
+ continue;
363
+ }
364
+ const nextAttemptAt = Date.now() + (retries.get(row.id) ?? __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_retryDelay).call(this, row.attempt));
365
+ const settled = updateAttempt(sql, outboxTable, ref, 'next_attempt_at = ?, last_error = ?, last_error_name = ?', nextAttemptAt, retryError.message, retryError.name);
366
+ if (settled) {
367
+ retried.push({ row, nextAttemptAt });
368
+ }
369
+ }
370
+ });
371
+ const timestamp = Date.now();
372
+ const durationMs = Math.max(0, timestamp - startedAt);
373
+ for (const row of acknowledged) {
374
+ __classPrivateFieldGet(this, _DurabilityOutbox_emit, "f").call(this, {
375
+ ...entity(row),
376
+ type: 'attempt_settled',
377
+ timestamp,
378
+ attempt: row.attempt,
379
+ durationMs,
380
+ outcome: 'completed',
381
+ });
382
+ }
383
+ for (const { row, nextAttemptAt } of retried) {
384
+ __classPrivateFieldGet(this, _DurabilityOutbox_emit, "f").call(this, {
385
+ ...entity(row),
386
+ type: 'attempt_settled',
387
+ timestamp,
388
+ attempt: row.attempt,
389
+ durationMs,
390
+ outcome: 'retry_scheduled',
391
+ nextAttemptAt,
392
+ error: retryError,
393
+ });
394
+ }
395
+ }, _DurabilityOutbox_retryDelay = function _DurabilityOutbox_retryDelay(attempt) {
396
+ try {
397
+ const delay = Math.round(__classPrivateFieldGet(this, _DurabilityOutbox_delay, "f").call(this, attempt));
398
+ if (Number.isSafeInteger(delay) && delay >= 0 && delay <= maxDelayMs) {
399
+ return delay;
400
+ }
401
+ }
402
+ catch (error) {
403
+ reportFailure('durability.outbox.retry_policy_failed', { channel: __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f") }, error);
404
+ }
405
+ return infrastructureRetryMs;
406
+ }, _DurabilityOutbox_deadline = async function _DurabilityOutbox_deadline(run) {
407
+ let timer;
408
+ try {
409
+ await Promise.race([
410
+ Promise.resolve().then(run),
411
+ new Promise((_resolve, reject) => {
412
+ timer = setTimeout(() => reject(new OutboxTimeoutError(__classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f"))), __classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f"));
413
+ }),
414
+ ]);
415
+ }
416
+ finally {
417
+ if (timer !== undefined) {
418
+ clearTimeout(timer);
419
+ }
420
+ }
421
+ };
422
+ (() => {
423
+ stageWithin = (outbox, sql, key, value) => {
424
+ const row = __classPrivateFieldGet(outbox, _DurabilityOutbox_instances, "m", _DurabilityOutbox_stageIn).call(outbox, sql, key, value);
425
+ __classPrivateFieldGet(outbox, _DurabilityOutbox_instances, "m", _DurabilityOutbox_emitRegistered).call(outbox, row);
426
+ return row.version;
427
+ };
428
+ discardWithin = (outbox, sql, key) => {
429
+ sql.exec('DELETE FROM durability_outbox WHERE id = ?', rowId(__classPrivateFieldGet(outbox, _DurabilityOutbox_channel, "f"), key));
430
+ };
431
+ publishNow = (outbox, key) => __classPrivateFieldGet(outbox, _DurabilityOutbox_instances, "m", _DurabilityOutbox_publishNow).call(outbox, key);
432
+ })();
433
+ traceMethods(DurabilityOutbox.prototype, 'DurabilityOutbox');
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
@@ -77,10 +79,12 @@ export type ExecutionSpec = {
77
79
  export declare class Engine {
78
80
  readonly sql: SqlStorage;
79
81
  private readonly context;
82
+ private readonly storage;
80
83
  private readonly alarmConcurrency;
81
84
  private readonly alarmMinDelayMs;
82
85
  private readonly alarmHandoffMs;
83
86
  private readonly participants;
87
+ private readonly migrated;
84
88
  private availablePermits;
85
89
  private readonly permitWaiters;
86
90
  private alarmRefresh;
@@ -89,7 +93,15 @@ export declare class Engine {
89
93
  constructor(context: DurabilityContext, options: DurabilitySchedulerOptions);
90
94
  register(participant: Participant): void;
91
95
  waitUntil(promise: Promise<unknown>, onError: (error: unknown) => void): void;
92
- emitter(hook: LifecycleHook | undefined): Emit;
96
+ /**
97
+ * The owning Durable Object's ID. The public context type omits it, but the
98
+ * `DurableObjectState` applications pass at runtime carries it.
99
+ */
100
+ objectId(): string | undefined;
101
+ emitter<Event extends {
102
+ entityKind: string;
103
+ type: string;
104
+ } = DurabilityLifecycleEvent>(hook: ((event: Event) => void | Promise<void>) | undefined): (event: Event) => void;
93
105
  /** Applies a helper's SQLite migrations. */
94
106
  migrateSchema(capability: MigrationCapability, migrations: DurableMigrations): void;
95
107
  /** Runs synchronous writes atomically without touching the physical alarm. */
package/dist/scheduler.js CHANGED
@@ -1,7 +1,8 @@
1
1
  import { z } from 'zod';
2
+ import { trace, traceMethods, traceStorage } from './dev.js';
2
3
  import { DurableRetryPolicyError, isErrorInstance, isNonRetryable, reportFailure, serializeError, } from './errors.js';
3
4
  import { createEmitter, } from './lifecycle.js';
4
- import { migrate } from './migrations.js';
5
+ import { migrateCapability } from './migrations.js';
5
6
  import { assertPositiveInteger } from './policy.js';
6
7
  import { claimAttempt, exhaustAttempts, updateAttempt, } from './storage.js';
7
8
  const minAlarmDelayMs = 1000;
@@ -55,10 +56,12 @@ const decideRetry = (spec, attempt, error) => {
55
56
  export class Engine {
56
57
  constructor(context, options) {
57
58
  this.participants = [];
59
+ this.migrated = new Set();
58
60
  this.permitWaiters = [];
59
61
  this.watchers = new Map();
60
62
  this.context = context;
61
- this.sql = context.storage.sql;
63
+ this.storage = traceStorage(context.storage);
64
+ this.sql = this.storage.sql;
62
65
  this.alarmConcurrency = options.alarmConcurrency ?? 10;
63
66
  this.alarmMinDelayMs = options.alarmMinDelayMs ?? 15000;
64
67
  this.alarmHandoffMs = options.alarmHandoffMs ?? 14 * 60000;
@@ -89,16 +92,30 @@ export class Engine {
89
92
  onError(error);
90
93
  }
91
94
  }
95
+ /**
96
+ * The owning Durable Object's ID. The public context type omits it, but the
97
+ * `DurableObjectState` applications pass at runtime carries it.
98
+ */
99
+ objectId() {
100
+ const id = Reflect.get(this.context, 'id');
101
+ return id === undefined || id === null ? undefined : String(id);
102
+ }
92
103
  emitter(hook) {
93
104
  return createEmitter(hook, (promise) => this.context.waitUntil?.(promise));
94
105
  }
95
106
  /** Applies a helper's SQLite migrations. */
96
107
  migrateSchema(capability, migrations) {
97
- migrate(this.context.storage, capability, migrations, undefined);
108
+ // Helpers of one kind on one scheduler share their tables; checking the
109
+ // schema again for each would only add statements to every construction.
110
+ if (this.migrated.has(capability)) {
111
+ return;
112
+ }
113
+ migrateCapability(this.storage, capability, migrations, undefined);
114
+ this.migrated.add(capability);
98
115
  }
99
116
  /** Runs synchronous writes atomically without touching the physical alarm. */
100
117
  transactionSync(write) {
101
- return this.context.storage.transactionSync(() => write(this.sql));
118
+ return this.storage.transactionSync(() => write(this.sql));
102
119
  }
103
120
  /**
104
121
  * Runs the writes and reconciles the physical alarm in one storage
@@ -106,7 +123,7 @@ export class Engine {
106
123
  */
107
124
  async transaction(write) {
108
125
  let nextPendingAt;
109
- const result = await this.context.storage.transaction(async (transaction) => {
126
+ const result = await this.storage.transaction(async (transaction) => {
110
127
  const value = write(this.sql);
111
128
  nextPendingAt = await this.reconcile(transaction);
112
129
  return value;
@@ -116,15 +133,21 @@ export class Engine {
116
133
  }
117
134
  /** Returns the earliest pending time and maintains its bounded physical fallback. */
118
135
  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}
136
+ const scheduled = this.participants.flatMap((participant) => {
137
+ if (participant.nextPendingAt) {
138
+ const at = participant.nextPendingAt(this.sql);
139
+ return at === undefined ? [] : [at];
140
+ }
141
+ return nextAttemptRowSchema
142
+ .array()
143
+ .parse(this.sql
144
+ .exec(`SELECT next_attempt_at FROM ${participant.table.name}
123
145
  WHERE status = 'pending'
124
146
  ORDER BY next_attempt_at ASC
125
147
  LIMIT 1`)
126
- .toArray())
127
- .map((row) => row.next_attempt_at));
148
+ .toArray())
149
+ .map((row) => row.next_attempt_at);
150
+ });
128
151
  const nextAlarmAt = scheduled.length === 0 ? undefined : Math.min(...scheduled);
129
152
  const currentAlarm = await physicalAlarm.getAlarm();
130
153
  if (nextAlarmAt === undefined) {
@@ -159,6 +182,7 @@ export class Engine {
159
182
  return;
160
183
  }
161
184
  this.earlyAlarm = undefined;
185
+ trace('scheduler.early_alarm', { scheduledTime: timestamp });
162
186
  const onError = (error) => reportFailure('durability.background_execution.failed', { scheduledTime: timestamp }, error);
163
187
  const execution = this.alarm().catch(onError);
164
188
  this.waitUntil(execution, onError);
@@ -320,7 +344,7 @@ export class Engine {
320
344
  /** Arms the physical alarm directly, outside any transaction; the next run reconciles properly. */
321
345
  async armFallbackAlarm() {
322
346
  try {
323
- await this.context.storage.setAlarm(Date.now() + this.alarmMinDelayMs);
347
+ await this.storage.setAlarm(Date.now() + this.alarmMinDelayMs);
324
348
  return true;
325
349
  }
326
350
  catch {
@@ -328,7 +352,7 @@ export class Engine {
328
352
  }
329
353
  }
330
354
  armForHandoff(timestamp) {
331
- return this.context.storage.transaction(async (physicalAlarm) => {
355
+ return this.storage.transaction(async (physicalAlarm) => {
332
356
  const currentAlarm = await physicalAlarm.getAlarm();
333
357
  const target = Math.max(timestamp, Date.now() + this.alarmMinDelayMs);
334
358
  if (currentAlarm === null || currentAlarm > target) {
@@ -513,6 +537,7 @@ export class DurabilityScheduler {
513
537
  return engineFor({ scheduler: this }).alarm(info);
514
538
  }
515
539
  }
540
+ traceMethods(DurabilityScheduler.prototype, 'DurabilityScheduler');
516
541
  /**
517
542
  * Resolves the engine a helper should attach to: the shared one behind a
518
543
  * scheduler, or a private one built from the Durable Object context.