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/README.md +147 -20
- package/dist/durability-alarms.d.ts +15 -2
- package/dist/durability-alarms.js +17 -5
- package/dist/durability.d.ts +30 -5
- package/dist/durability.js +36 -13
- package/dist/errors.d.ts +14 -0
- package/dist/errors.js +23 -0
- package/dist/fanout.d.ts +6 -0
- package/dist/fanout.js +8 -2
- package/dist/index.d.ts +3 -2
- package/dist/index.js +3 -2
- package/dist/lifecycle.d.ts +6 -1
- package/dist/log.js +35 -12
- package/dist/memoize.d.ts +34 -0
- package/dist/memoize.js +136 -0
- package/dist/migrations.d.ts +18 -1
- package/dist/migrations.js +49 -0
- package/dist/scheduler.d.ts +2 -0
- package/dist/scheduler.js +29 -6
- package/dist/storage.d.ts +1 -0
- package/dist/storage.js +1 -1
- package/dist/tracked-source.d.ts +2 -0
- package/package.json +2 -1
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 {
|
|
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
|
-
|
|
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';
|
package/dist/lifecycle.d.ts
CHANGED
|
@@ -48,7 +48,12 @@ export type DurabilityLifecycleEvent = ((OperationLifecycleEntity | FanoutLifecy
|
|
|
48
48
|
attempt: number;
|
|
49
49
|
}) | (LifecycleEntity & AttemptSettled & {
|
|
50
50
|
outcome: 'completed';
|
|
51
|
-
/**
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
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
|
-
|
|
700
|
-
|
|
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;
|
package/dist/memoize.js
ADDED
|
@@ -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
|
+
};
|
package/dist/migrations.d.ts
CHANGED
|
@@ -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
|
package/dist/migrations.js
CHANGED
|
@@ -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
|
package/dist/scheduler.d.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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) =>
|
|
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) =>
|
|
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}
|
package/dist/tracked-source.d.ts
CHANGED
|
@@ -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": "
|
|
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",
|