durability 4.3.0 → 5.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/errors.js CHANGED
@@ -57,6 +57,29 @@ export class DurableResultSerializationError extends Error {
57
57
  }
58
58
  }
59
59
  }
60
+ /**
61
+ * Error persisted when a memoized result cannot be JSON-serialized. It is
62
+ * terminal because every retry would fail the same way.
63
+ */
64
+ export class DurableMemoSerializationError extends NonRetryableError {
65
+ constructor(key, reason) {
66
+ super(`Memoized result for key ${JSON.stringify(key)} is not JSON-serializable`);
67
+ this.name = 'DurableMemoSerializationError';
68
+ if (reason !== undefined) {
69
+ Object.defineProperty(this, 'cause', { value: reason });
70
+ }
71
+ }
72
+ }
73
+ /**
74
+ * Error persisted when work memoizes more keys, or a larger result, than the
75
+ * limits allow. It is terminal because every retry would fail the same way.
76
+ */
77
+ export class DurableMemoLimitError extends NonRetryableError {
78
+ constructor(message) {
79
+ super(message);
80
+ this.name = 'DurableMemoLimitError';
81
+ }
82
+ }
60
83
  /** Error persisted when pending work has already reached its attempt limit. */
61
84
  export class DurableAttemptsExhaustedError extends Error {
62
85
  constructor(entity, name, max) {
package/dist/fanout.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { type DurabilityLifecycleEvent, type LifecycleHook } from './lifecycle.js';
2
2
  import { RoutingLoad, type EnqueueResult, type LoadSnapshot } from './load.js';
3
3
  import type { MessageWrite } from './stored-message.js';
4
+ import { type DurableMemoize } from './memoize.js';
4
5
  import { type ExecutionPolicyOptions } from './policy.js';
5
6
  import { type SchedulerAttachment } from './scheduler.js';
6
7
  export type FanoutInput<Body = unknown> = {
@@ -17,6 +18,11 @@ export type DurabilityFanoutMessage<Body = unknown> = {
17
18
  body: Body;
18
19
  attempt: number;
19
20
  enqueuedAt: number;
21
+ /**
22
+ * Persists a callback's result by key for this message and target, so a
23
+ * retried delivery reuses it. Deleted when the delivery is acked or dead-lettered.
24
+ */
25
+ memoize: DurableMemoize;
20
26
  ack(): Promise<void>;
21
27
  retry(delayMs?: number): Promise<void>;
22
28
  deadLetter(): Promise<void>;
package/dist/fanout.js CHANGED
@@ -15,7 +15,8 @@ import { traceFunction, traceMethods } from './dev.js';
15
15
  import { DurableRetryPolicyError, FanoutEnqueueError, FanoutSettlementError, FanoutTimeoutError, reportFailure, serializeError, } from './errors.js';
16
16
  import { createLifecycleHooks, } from './lifecycle.js';
17
17
  import { RoutingLoad } from './load.js';
18
- import { durabilityFanoutMigrations, migrateCapability } from './migrations.js';
18
+ import { createMemoize, deleteMemos, deleteMemosOfDroppedTable, } from './memoize.js';
19
+ import { durabilityFanoutMigrations, durabilityMemoMigrations, migrateCapability, } from './migrations.js';
19
20
  import { assertPositiveInteger, createPolicyResolver, methodOptionsSchema, } from './policy.js';
20
21
  import { engineFor, } from './scheduler.js';
21
22
  import { deserialize, serialize } from './serialization.js';
@@ -120,13 +121,16 @@ export class DurabilityFanout {
120
121
  __classPrivateFieldSet(this, _DurabilityFanout_lifecycle, createLifecycleHooks((hook) => __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").emitter(hook), config.onLifecycleEvent), "f");
121
122
  __classPrivateFieldSet(this, _DurabilityFanout_emit, __classPrivateFieldGet(this, _DurabilityFanout_lifecycle, "f").emit, "f");
122
123
  __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").migrateSchema('fanout', durabilityFanoutMigrations);
124
+ __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").migrateSchema('memos', durabilityMemoMigrations);
123
125
  __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").register({
124
126
  table: deliveriesTable,
125
127
  runDue: () => __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_runDue).call(this),
126
128
  });
127
129
  }
128
130
  static migrate(context, target) {
129
- return migrateCapability(context.storage, 'fanout', durabilityFanoutMigrations, target);
131
+ const result = migrateCapability(context.storage, 'fanout', durabilityFanoutMigrations, target);
132
+ deleteMemosOfDroppedTable(context.storage.sql, deliveriesTable);
133
+ return result;
130
134
  }
131
135
  alarm(info) {
132
136
  return __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").alarm(info);
@@ -528,6 +532,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
528
532
  body: deserialize(message.payload),
529
533
  enqueuedAt: message.created_at,
530
534
  attempt: row.attempt,
535
+ memoize: createMemoize(__classPrivateFieldGet(this, _DurabilityFanout_engine, "f").sql, deliveriesTable, attemptOf(row)),
531
536
  ack: traceFunction('DurabilityFanoutMessage.ack', () => settle('ack', async () => {
532
537
  await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_remove).call(this, row);
533
538
  __classPrivateFieldGet(this, _DurabilityFanout_emit, "f").call(this, {
@@ -560,6 +565,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
560
565
  if (!deleteAttempt(sql, deliveriesTable, attemptOf(row))) {
561
566
  return false;
562
567
  }
568
+ deleteMemos(sql, deliveriesTable, row.id);
563
569
  __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_adjustPending).call(this, -1);
564
570
  sql.exec(`UPDATE durability_fanout_messages
565
571
  SET remaining = remaining - 1
package/dist/index.d.ts CHANGED
@@ -1,12 +1,13 @@
1
1
  export { Durability, type DurabilityConfig, type DurabilityConstructor, type DurabilityOptions, type DurableCall, type DurableHandler, type DurableOperation, type DurableOperationResult, type DurabilityOperationEvent, type HandlerMap, } from './durability.js';
2
2
  export { DurabilityAlarms, type DurabilityAlarmsConfig, type DurabilityAlarmsConstructor, type DurabilityAlarmsOptions, type DurabilityAlarmEvent, type DurableAlarmHandler, type DurableAlarmInfo, type DurableNamedAlarm, } from './durability-alarms.js';
3
+ export { maxMemoBytes, maxMemosPerRecord, type DurableMemoize, } from './memoize.js';
3
4
  export { DurabilityFanout, type DurabilityFanoutConfig, type DurabilityFanoutEvent, type DurabilityFanoutMessage, type FanoutInput, type FanoutTarget, type FanoutEnqueueOptions, } from './fanout.js';
4
5
  export { DurabilityLog, maxLogBytes, type DurabilityLogConfig, type LogAppendInput, type LogColdStorage, type LogLease, type LogLeaseOptions, type LogPage, type LogReadOptions, type LogRecord, type LogRetention, type LogSegment, type LogBounds, } from './log.js';
5
6
  export { RoutingLoad, type EnqueueResult, type LoadSnapshot, type ProcessingLoad, } from './load.js';
6
7
  export type { MessageWrite, StoredMessage } from './stored-message.js';
7
8
  export { DurabilityScheduler, type DurabilityContext, type DurabilitySchedulerConfig, type DurabilitySchedulerOptions, type SchedulerAttachment, } from './scheduler.js';
8
- export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
9
+ export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, DurableMemoLimitError, DurableMemoSerializationError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
9
10
  export type { DurabilityLifecycleEvent, LifecycleHook } from './lifecycle.js';
10
- export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, migrate, type DurabilityMigrationResult, type MigrateOptions, type MigrationCapability, } from './migrations.js';
11
+ export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, durabilityMemoMigrations, migrate, type DurabilityMigrationResult, type MigrateOptions, type MigrationCapability, } from './migrations.js';
11
12
  export type { DurableMigrations } from '@durability/storage';
12
13
  export type { DurabilityAlarmMethodOptions, DurabilityMethodOptions, DurabilityRetryOptions, } from './policy.js';
package/dist/index.js CHANGED
@@ -1,8 +1,9 @@
1
1
  export { Durability, } from './durability.js';
2
2
  export { DurabilityAlarms, } from './durability-alarms.js';
3
+ export { maxMemoBytes, maxMemosPerRecord, } from './memoize.js';
3
4
  export { DurabilityFanout, } from './fanout.js';
4
5
  export { DurabilityLog, maxLogBytes, } from './log.js';
5
6
  export { RoutingLoad, } from './load.js';
6
7
  export { DurabilityScheduler, } from './scheduler.js';
7
- export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
8
- export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, migrate, } from './migrations.js';
8
+ export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, DurableMemoLimitError, DurableMemoSerializationError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
9
+ export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, durabilityMemoMigrations, migrate, } from './migrations.js';
@@ -48,7 +48,12 @@ export type DurabilityLifecycleEvent = ((OperationLifecycleEntity | FanoutLifecy
48
48
  attempt: number;
49
49
  }) | (LifecycleEntity & AttemptSettled & {
50
50
  outcome: 'completed';
51
- /** The handler's return value. Absent for fanout acknowledgements. */
51
+ /**
52
+ * The handler's return value. Omitted by default to keep result
53
+ * content out of telemetry; present only when the emitting instance
54
+ * opts in (e.g. Durability's `includeResults`). Always absent for
55
+ * fanout acknowledgements.
56
+ */
52
57
  result?: unknown;
53
58
  }) | (LifecycleEntity & AttemptSettled & {
54
59
  outcome: 'retry_scheduled';
package/dist/log.js CHANGED
@@ -252,7 +252,7 @@ const settleLease = (sql, batchId, state, expiresAt) => sql
252
252
  */
253
253
  const leasesFrom = (sql, consumer, from, limit) => logLeaseRowSchema.array().parse(sql
254
254
  .exec(`SELECT * FROM durability_log_leases
255
- WHERE consumer = ? AND first_offset >= ?
255
+ WHERE consumer = ? AND last_offset >= ?
256
256
  ORDER BY first_offset ASC
257
257
  LIMIT ?`, consumer, from, limit)
258
258
  .toArray());
@@ -541,7 +541,11 @@ export class DurabilityLog {
541
541
  }
542
542
  // Terminal intent is durable before the callback runs, so a failing
543
543
  // handler cannot resurrect a range that already exhausted its attempts.
544
- __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_settle).call(this, reclaimed.batch_id, 'skipped');
544
+ // A skipped range counts as settled, so the cursor moves past it as for an ack.
545
+ __classPrivateFieldGet(this, _DurabilityLog_engine, "f").transactionSync(() => {
546
+ __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_settle).call(this, reclaimed.batch_id, 'skipped');
547
+ __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_advance).call(this, consumer);
548
+ });
545
549
  try {
546
550
  await leases.onPoison(lease);
547
551
  }
@@ -675,17 +679,23 @@ async function _DurabilityLog_rehydrate(from, limit, bounds) {
675
679
  // Offsets below the retained window are gone for everyone; a cursor
676
680
  // stranded there could never meet the ranges leased after them.
677
681
  const from = Math.max(readCursor(sql, consumer) ?? 0, readBounds(sql).oldestOffset);
678
- const candidates = leasesFrom(sql, consumer, from, __classPrivateFieldGet(this, _DurabilityLog_maxBatchSize, "f"));
679
682
  let cursor = from;
680
683
  const settled = [];
681
- for (const row of candidates) {
682
- const contiguous = row.first_offset <= cursor;
683
- const done = row.state === 'acked' || row.state === 'skipped';
684
- if (!contiguous || !done) {
685
- break;
684
+ // Ranges settled while an earlier one was outstanding wait behind it; when
685
+ // it settles the cursor must pass all of them, however many pages that is.
686
+ for (let page = true; page;) {
687
+ const candidates = leasesFrom(sql, consumer, cursor, __classPrivateFieldGet(this, _DurabilityLog_maxBatchSize, "f"));
688
+ page = candidates.length === __classPrivateFieldGet(this, _DurabilityLog_maxBatchSize, "f");
689
+ for (const row of candidates) {
690
+ const contiguous = row.first_offset <= cursor;
691
+ const done = row.state === 'acked' || row.state === 'skipped';
692
+ if (!contiguous || !done) {
693
+ page = false;
694
+ break;
695
+ }
696
+ cursor = Math.max(cursor, row.last_offset + 1);
697
+ settled.push(row.batch_id);
686
698
  }
687
- cursor = Math.max(cursor, row.last_offset + 1);
688
- settled.push(row.batch_id);
689
699
  }
690
700
  if (settled.length === 0) {
691
701
  return;
@@ -696,8 +706,21 @@ async function _DurabilityLog_rehydrate(from, limit, bounds) {
696
706
  /** Reads a stored range, rehydrating it when retention already flushed it. */
697
707
  async function _DurabilityLog_between(first, last) {
698
708
  const bounds = readBounds(__classPrivateFieldGet(this, _DurabilityLog_engine, "f").sql);
699
- const records = await __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_readFrom).call(this, first, last - first + 1, bounds);
700
- return records.filter((record) => record.offset <= last);
709
+ // One read stops at the end of a cold segment, and a range redelivered
710
+ // after a flush can span several segments and the hot window.
711
+ const records = [];
712
+ let from = first;
713
+ while (from <= last) {
714
+ // eslint-disable-next-line no-await-in-loop
715
+ const page = await __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_readFrom).call(this, from, last - from + 1, bounds);
716
+ const inRange = page.filter((record) => record.offset <= last);
717
+ if (inRange.length === 0) {
718
+ break;
719
+ }
720
+ records.push(...inRange);
721
+ from = inRange[inRange.length - 1].offset + 1;
722
+ }
723
+ return records;
701
724
  }, _DurabilityLog_readFrom = async function _DurabilityLog_readFrom(from, limit, bounds) {
702
725
  if (from < bounds.hotOffset && from < bounds.nextOffset) {
703
726
  return __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_rehydrate).call(this, from, limit, bounds);
@@ -0,0 +1,34 @@
1
+ import { type AttemptRef, type DurableTable } from './storage.js';
2
+ /**
3
+ * Runs `callback` once per key for a durable operation or named alarm
4
+ * occurrence and persists its result, so a retried attempt returns the result
5
+ * instead of running the callback again. A callback that throws persists
6
+ * nothing and runs again on the next call with that key.
7
+ *
8
+ * Calls with the same key return the same result, within one attempt and
9
+ * across attempts. A call for a key whose callback is still running rejects,
10
+ * including one made from that callback. Results are deleted when the
11
+ * operation, alarm occurrence, or fanout delivery settles.
12
+ *
13
+ * At most {@link maxMemosPerRecord} keys and {@link maxMemoBytes} per result;
14
+ * exceeding either fails the work with `DurableMemoLimitError`.
15
+ */
16
+ export type DurableMemoize = <T>(key: string, callback: () => T | Promise<T>) => Promise<T>;
17
+ /** The most keys one operation, alarm occurrence, or fanout delivery may memoize. */
18
+ export declare const maxMemosPerRecord = 1000;
19
+ /** The largest serialized memoized result, in UTF-8 bytes. */
20
+ export declare const maxMemoBytes = 1048576;
21
+ /** Memoization for one attempt; only that attempt may persist new results. */
22
+ export declare const createMemoize: (sql: SqlStorage, table: DurableTable, ref: AttemptRef) => DurableMemoize;
23
+ /** Keys a record's current generation has results for, in the order they were saved. */
24
+ export declare const memoizedKeys: (sql: SqlStorage, table: DurableTable, key: string, generation: string) => string[];
25
+ /** Deletes every memoized result of a record, whichever generation wrote it. */
26
+ export declare const deleteMemos: (sql: SqlStorage, table: DurableTable, key: string) => void;
27
+ /** Deletes memoized results whose record generation is no longer pending. */
28
+ export declare const deleteStaleMemos: (sql: SqlStorage, table: DurableTable) => void;
29
+ /**
30
+ * Deletes the memoized results of a helper whose schema was reverted. The
31
+ * shared table stays for the other helper, but the removed records' results
32
+ * must not.
33
+ */
34
+ export declare const deleteMemosOfDroppedTable: (sql: SqlStorage, table: DurableTable) => void;
@@ -0,0 +1,136 @@
1
+ import { z } from 'zod';
2
+ import { traceFunction } from './dev.js';
3
+ import { DurableMemoLimitError, DurableMemoSerializationError, } from './errors.js';
4
+ import { deserialize, serialize } from './serialization.js';
5
+ import { pendingGeneration, } from './storage.js';
6
+ /** The most keys one operation, alarm occurrence, or fanout delivery may memoize. */
7
+ export const maxMemosPerRecord = 1000;
8
+ /** The largest serialized memoized result, in UTF-8 bytes. */
9
+ export const maxMemoBytes = 1048576;
10
+ const memoLookupSchema = z.object({
11
+ result: z.string().nullable(),
12
+ owned: z.number().int(),
13
+ saved: z.number().int(),
14
+ });
15
+ const supersededError = (key) => new Error(`Memoized key ${JSON.stringify(key)} belongs to a superseded attempt`);
16
+ /** Memoization for one attempt; only that attempt may persist new results. */
17
+ export const createMemoize = (sql, table, ref) => {
18
+ const running = new Set();
19
+ /** Serializes, checks, and writes a callback's result, then returns its persisted form. */
20
+ const save = (key, value) => {
21
+ let serialized;
22
+ try {
23
+ serialized = serialize(value);
24
+ }
25
+ catch (error) {
26
+ throw new DurableMemoSerializationError(key, error);
27
+ }
28
+ const bytes = new TextEncoder().encode(serialized).byteLength;
29
+ if (bytes > maxMemoBytes) {
30
+ throw new DurableMemoLimitError(`Memoized result for ${JSON.stringify(key)} is ${bytes} bytes, over the ${maxMemoBytes}-byte limit`);
31
+ }
32
+ // A timed-out attempt that finishes late must not write over its successor.
33
+ const written = sql
34
+ .exec(`INSERT INTO durability_memos
35
+ (owner, key, generation_id, memo_key, result)
36
+ SELECT ?, ?, ?, ?, ?
37
+ WHERE EXISTS (
38
+ SELECT 1 FROM ${table.name}
39
+ WHERE ${pendingGeneration(table)} AND attempt = ?
40
+ )
41
+ RETURNING memo_key`, table.name, ref.key, ref.generation, key, serialized, ref.key, ref.generation, ref.attempt)
42
+ .toArray().length > 0;
43
+ if (!written) {
44
+ throw supersededError(key);
45
+ }
46
+ // Return what a replay would return, so later code sees one shape either way.
47
+ return deserialize(serialized);
48
+ };
49
+ // Everything up to the callback runs synchronously, so a concurrent call
50
+ // with the same key sees either the saved result or this key as running.
51
+ const run = async (key, callback) => {
52
+ if (typeof key !== 'string' || key === '') {
53
+ throw new TypeError('Memoize keys must be non-empty strings');
54
+ }
55
+ const lookup = memoLookupSchema.parse(sql
56
+ .exec(`SELECT
57
+ (SELECT result FROM durability_memos
58
+ WHERE owner = ? AND key = ? AND generation_id = ? AND memo_key = ?)
59
+ AS result,
60
+ EXISTS (
61
+ SELECT 1 FROM ${table.name}
62
+ WHERE ${pendingGeneration(table)} AND attempt = ?
63
+ ) AS owned,
64
+ (SELECT COUNT(*) FROM durability_memos
65
+ WHERE owner = ? AND key = ? AND generation_id = ?) AS saved`, table.name, ref.key, ref.generation, key, ref.key, ref.generation, ref.attempt, table.name, ref.key, ref.generation)
66
+ .toArray()[0]);
67
+ if (lookup.result !== null) {
68
+ return deserialize(lookup.result);
69
+ }
70
+ // A rescheduled or purged attempt must not start side effects it can never record.
71
+ if (lookup.owned === 0) {
72
+ throw supersededError(key);
73
+ }
74
+ // Waiting on the running call would deadlock a callback that memoizes its own key.
75
+ if (running.has(key)) {
76
+ throw new Error(`Memoized key ${JSON.stringify(key)} is already running; await the first call instead`);
77
+ }
78
+ // Running callbacks count too: each may save a result when it settles.
79
+ if (lookup.saved + running.size >= maxMemosPerRecord) {
80
+ throw new DurableMemoLimitError(`Memoizing ${JSON.stringify(key)} would exceed ${maxMemosPerRecord} keys`);
81
+ }
82
+ // The key stays running through serialization, so a getter that memoizes
83
+ // it again is rejected instead of running the callback a second time.
84
+ running.add(key);
85
+ try {
86
+ return save(key, await callback());
87
+ }
88
+ finally {
89
+ running.delete(key);
90
+ }
91
+ };
92
+ return (key, callback) => traceFunction('memoize', () => run(key, callback), {
93
+ owner: table.name,
94
+ key: ref.key,
95
+ attempt: ref.attempt,
96
+ memoKey: key,
97
+ })();
98
+ };
99
+ const memoKeySchema = z.object({ memo_key: z.string() });
100
+ /** Keys a record's current generation has results for, in the order they were saved. */
101
+ export const memoizedKeys = (sql, table, key, generation) => memoKeySchema
102
+ .array()
103
+ .parse(sql
104
+ .exec(`SELECT memo_key FROM durability_memos
105
+ WHERE owner = ? AND key = ? AND generation_id = ?
106
+ ORDER BY rowid`, table.name, key, generation)
107
+ .toArray())
108
+ .map((row) => row.memo_key);
109
+ /** Deletes every memoized result of a record, whichever generation wrote it. */
110
+ export const deleteMemos = (sql, table, key) => {
111
+ sql.exec('DELETE FROM durability_memos WHERE owner = ? AND key = ?', table.name, key);
112
+ };
113
+ /** Deletes memoized results whose record generation is no longer pending. */
114
+ export const deleteStaleMemos = (sql, table) => {
115
+ sql.exec(`DELETE FROM durability_memos
116
+ WHERE owner = ? AND NOT EXISTS (
117
+ SELECT 1 FROM ${table.name} AS record
118
+ WHERE record.${table.key} = durability_memos.key
119
+ AND record.generation_id = durability_memos.generation_id
120
+ AND record.status = 'pending'
121
+ )`, table.name);
122
+ };
123
+ const tableExists = (sql, name) => sql
124
+ .exec(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?`, name)
125
+ .toArray().length > 0;
126
+ /**
127
+ * Deletes the memoized results of a helper whose schema was reverted. The
128
+ * shared table stays for the other helper, but the removed records' results
129
+ * must not.
130
+ */
131
+ export const deleteMemosOfDroppedTable = (sql, table) => {
132
+ if (!tableExists(sql, 'durability_memos') || tableExists(sql, table.name)) {
133
+ return;
134
+ }
135
+ sql.exec('DELETE FROM durability_memos WHERE owner = ?', table.name);
136
+ };
@@ -19,6 +19,16 @@ export declare const durabilityNamedAlarmMigrations: {
19
19
  up: string;
20
20
  down: string;
21
21
  }[];
22
+ /**
23
+ * Ordered SQLite migrations for `durability_memos`, the memoized results that
24
+ * {@link Durability} and {@link DurabilityAlarms} share. Applied by whichever
25
+ * helper is constructed first.
26
+ */
27
+ export declare const durabilityMemoMigrations: {
28
+ name: string;
29
+ up: string;
30
+ down: string;
31
+ }[];
22
32
  /**
23
33
  * Ordered SQLite migrations for fanout manifests and deliveries. Applied
24
34
  * automatically on construction.
@@ -99,8 +109,15 @@ export type DurabilityMigrationResult = {
99
109
  /** Migrations reverted in descending order. */
100
110
  rolledBack: string[];
101
111
  };
102
- export type MigrationCapability = 'operations' | 'namedAlarms' | 'fanout' | 'socket' | 'log' | 'logLeases' | 'outbox' | 'semaphore' | 'semaphoreQueue' | 'topology';
112
+ export type MigrationCapability = 'operations' | 'namedAlarms' | 'memos' | 'fanout' | 'socket' | 'log' | 'logLeases' | 'outbox' | 'semaphore' | 'semaphoreQueue' | 'topology';
103
113
  type MigrationStorage = Pick<DurableObjectStorage, 'sql' | 'transactionSync'>;
114
+ /**
115
+ * Whether a capability's history already lists exactly these migrations with
116
+ * these `down` scripts, so construction can skip {@link migrateCapability}. Every Durable
117
+ * Object wake constructs its helpers, and each statement there is one more way
118
+ * for the wake to fail, so the common case costs one read.
119
+ */
120
+ export declare const isSchemaCurrent: (sql: SqlStorage, capability: MigrationCapability, migrations: DurableMigrations) => boolean;
104
121
  /**
105
122
  * Moves one capability's schema to a target migration, applying or reverting as
106
123
  * needed. `null` reverts every migration in the list; the shared migration
@@ -166,6 +166,27 @@ export const durabilityNamedAlarmMigrations = [
166
166
  `,
167
167
  },
168
168
  ];
169
+ /**
170
+ * Ordered SQLite migrations for `durability_memos`, the memoized results that
171
+ * {@link Durability} and {@link DurabilityAlarms} share. Applied by whichever
172
+ * helper is constructed first.
173
+ */
174
+ export const durabilityMemoMigrations = [
175
+ {
176
+ name: 'durability_0012_create_memos',
177
+ up: `
178
+ CREATE TABLE IF NOT EXISTS durability_memos (
179
+ owner TEXT NOT NULL,
180
+ key TEXT NOT NULL,
181
+ generation_id TEXT NOT NULL,
182
+ memo_key TEXT NOT NULL,
183
+ result TEXT NOT NULL,
184
+ PRIMARY KEY (owner, key, generation_id, memo_key)
185
+ );
186
+ `,
187
+ down: 'DROP TABLE IF EXISTS durability_memos;',
188
+ },
189
+ ];
169
190
  /**
170
191
  * Ordered SQLite migrations for fanout manifests and deliveries. Applied
171
192
  * automatically on construction.
@@ -641,6 +662,34 @@ const revertFutureMigrations = (storage, scope, history, known) => {
641
662
  });
642
663
  return future.map(({ name }) => name);
643
664
  };
665
+ const currentRowSchema = z.object({
666
+ name: z.string(),
667
+ down: z.string().nullable(),
668
+ });
669
+ /**
670
+ * Whether a capability's history already lists exactly these migrations with
671
+ * these `down` scripts, so construction can skip {@link migrateCapability}. Every Durable
672
+ * Object wake constructs its helpers, and each statement there is one more way
673
+ * for the wake to fail, so the common case costs one read.
674
+ */
675
+ export const isSchemaCurrent = (sql, capability, migrations) => {
676
+ let rows;
677
+ try {
678
+ rows = currentRowSchema
679
+ .array()
680
+ .parse(sql
681
+ .exec(`SELECT name, down FROM ${migrationTableName} WHERE capability = ?`, capability)
682
+ .toArray());
683
+ }
684
+ catch {
685
+ // A first construction has no history table, and an older one lacks the
686
+ // capability column; migrateCapability() creates both, and retries any other failure.
687
+ return false;
688
+ }
689
+ const known = new Map(migrations.map(({ name, down }) => [name, down]));
690
+ return (rows.length === known.size &&
691
+ rows.every((row) => known.get(row.name) === row.down));
692
+ };
644
693
  const migrateScope = (storage, scope, migrations, target) => {
645
694
  storage = traceStorage(storage);
646
695
  const resolvedTarget = target === undefined
@@ -60,6 +60,8 @@ export type ExecutionSpec = {
60
60
  active: Map<string, ActiveExecution>;
61
61
  policy: AttemptPolicy;
62
62
  emit: Emit;
63
+ /** When true, the completed event carries the handler result; omitted by default to keep results out of telemetry. */
64
+ includeResult?: boolean;
63
65
  exhaustedError: () => Error;
64
66
  timeoutError: () => Error;
65
67
  invoke: (attempt: number, signal: AbortSignal) => unknown;
package/dist/scheduler.js CHANGED
@@ -2,8 +2,9 @@ import { z } from 'zod';
2
2
  import { trace, traceMethods, traceStorage } from './dev.js';
3
3
  import { DurableRetryPolicyError, isErrorInstance, isNonRetryable, reportFailure, serializeError, } from './errors.js';
4
4
  import { createEmitter, } from './lifecycle.js';
5
- import { migrateCapability } from './migrations.js';
5
+ import { isSchemaCurrent, migrateCapability, } from './migrations.js';
6
6
  import { assertPositiveInteger } from './policy.js';
7
+ import { deleteMemos, deleteStaleMemos } from './memoize.js';
7
8
  import { claimAttempt, exhaustAttempts, updateAttempt, } from './storage.js';
8
9
  const minAlarmDelayMs = 1000;
9
10
  const maxAlarmDelayMs = 15000;
@@ -110,7 +111,9 @@ export class Engine {
110
111
  if (this.migrated.has(capability)) {
111
112
  return;
112
113
  }
113
- migrateCapability(this.storage, capability, migrations, undefined);
114
+ if (!isSchemaCurrent(this.sql, capability, migrations)) {
115
+ migrateCapability(this.storage, capability, migrations, undefined);
116
+ }
114
117
  this.migrated.add(capability);
115
118
  }
116
119
  /** Runs synchronous writes atomically without touching the physical alarm. */
@@ -217,6 +220,7 @@ export class Engine {
217
220
  .exec(`SELECT COUNT(*) AS count FROM ${table.name} WHERE created_at < ?`, before)
218
221
  .toArray()[0]);
219
222
  sql.exec(`DELETE FROM ${table.name} WHERE created_at < ?`, before);
223
+ deleteStaleMemos(sql, table);
220
224
  return count;
221
225
  });
222
226
  if (removed > 0) {
@@ -421,7 +425,14 @@ export class Engine {
421
425
  }, policy.attemptTimeoutMs);
422
426
  });
423
427
  const result = await Promise.race([handlerResult, timeoutResult]);
424
- const timestamp = spec.complete(result, attempt);
428
+ // One transaction: a failed memo cleanup must undo the completion, not orphan the memos.
429
+ const timestamp = this.transactionSync((sql) => {
430
+ const completedAt = spec.complete(result, attempt);
431
+ if (completedAt !== undefined) {
432
+ deleteMemos(sql, spec.table, key);
433
+ }
434
+ return completedAt;
435
+ });
425
436
  if (timestamp !== undefined) {
426
437
  this.notify(spec.table, key, row);
427
438
  spec.emit({
@@ -431,7 +442,7 @@ export class Engine {
431
442
  attempt,
432
443
  durationMs: Math.max(0, timestamp - startedAt),
433
444
  outcome: 'completed',
434
- result,
445
+ ...(spec.includeResult ? { result } : {}),
435
446
  });
436
447
  }
437
448
  }
@@ -457,7 +468,13 @@ export class Engine {
457
468
  async failExhausted(spec) {
458
469
  const { key, row, policy } = spec;
459
470
  const exhausted = serializeError(spec.exhaustedError());
460
- const attempt = await this.transaction((sql) => exhaustAttempts(sql, spec.table, key, row.generation_id, policy.maxAttempts, exhausted));
471
+ const attempt = await this.transaction((sql) => {
472
+ const exhaustedAttempt = exhaustAttempts(sql, spec.table, key, row.generation_id, policy.maxAttempts, exhausted);
473
+ if (exhaustedAttempt !== undefined) {
474
+ deleteMemos(sql, spec.table, key);
475
+ }
476
+ return exhaustedAttempt;
477
+ });
461
478
  if (attempt === undefined) {
462
479
  return;
463
480
  }
@@ -475,7 +492,13 @@ export class Engine {
475
492
  const { key, row } = spec;
476
493
  const decision = decideRetry(spec, attempt, caught);
477
494
  const serializedError = serializeError(decision.error);
478
- const updated = await this.transaction((sql) => updateAttempt(sql, spec.table, { key, generation: row.generation_id, attempt }, 'status = ?, next_attempt_at = ?, last_error = ?, last_error_name = ?', decision.terminal ? 'failed' : 'pending', decision.nextAttemptAt, serializedError.message, serializedError.name));
495
+ const updated = await this.transaction((sql) => {
496
+ const owned = updateAttempt(sql, spec.table, { key, generation: row.generation_id, attempt }, 'status = ?, next_attempt_at = ?, last_error = ?, last_error_name = ?', decision.terminal ? 'failed' : 'pending', decision.nextAttemptAt, serializedError.message, serializedError.name);
497
+ if (owned && decision.terminal) {
498
+ deleteMemos(sql, spec.table, key);
499
+ }
500
+ return owned;
501
+ });
479
502
  if (!updated) {
480
503
  return;
481
504
  }
package/dist/storage.d.ts CHANGED
@@ -12,6 +12,7 @@ export type AttemptRef = {
12
12
  generation: string;
13
13
  attempt: number;
14
14
  };
15
+ export declare const pendingGeneration: (table: DurableTable) => string;
15
16
  /** Starts the next attempt and returns its number, unless the generation is gone or out of attempts. */
16
17
  export declare const claimAttempt: (sql: SqlStorage, table: DurableTable, key: string, generation: string, maxAttempts: number) => number | undefined;
17
18
  /**
package/dist/storage.js CHANGED
@@ -4,7 +4,7 @@ const attemptRowSchema = z.object({
4
4
  });
5
5
  // Every write is conditional on the record's generation and pending status, so a
6
6
  // stale execution can never overwrite a replacement or a later attempt.
7
- const pendingGeneration = (table) => `${table.key} = ? AND generation_id = ? AND status = 'pending'`;
7
+ export const pendingGeneration = (table) => `${table.key} = ? AND generation_id = ? AND status = 'pending'`;
8
8
  /** Starts the next attempt and returns its number, unless the generation is gone or out of attempts. */
9
9
  export const claimAttempt = (sql, table, key, generation, maxAttempts) => attemptRowSchema.optional().parse(sql
10
10
  .exec(`UPDATE ${table.name}
@@ -10,6 +10,8 @@ export type TrackedState<Result> = {
10
10
  attempt?: number;
11
11
  nextAttemptAt?: number;
12
12
  lastError?: string | null;
13
+ /** Keys whose memoized results the next attempt reuses, in the order they were saved. */
14
+ memoized?: string[];
13
15
  } | {
14
16
  status: 'completed';
15
17
  result: Result;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "durability",
3
- "version": "4.3.0",
3
+ "version": "5.0.0",
4
4
  "description": "Alarm-backed durable operations and typed WebSocket sync for Cloudflare Durable Objects",
5
5
  "type": "module",
6
6
  "license": "ISC",
@@ -86,6 +86,7 @@
86
86
  "@durability/typescript-config": "0.0.0"
87
87
  },
88
88
  "scripts": {
89
+ "bench:load": "vitest run --config vitest.bench.config.ts",
89
90
  "build": "rm -rf dist && tsc -p tsconfig.build.json",
90
91
  "lint": "oxlint",
91
92
  "test": "vitest run && vitest run --config vitest.workers.config.ts",