durability 3.0.1 → 4.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +398 -25
- package/dist/client.d.ts +94 -0
- package/dist/client.js +445 -0
- package/dist/durability-alarms.d.ts +14 -1
- package/dist/durability-alarms.js +121 -22
- package/dist/durability.d.ts +32 -1
- package/dist/durability.js +119 -61
- package/dist/errors.d.ts +22 -0
- package/dist/errors.js +31 -0
- package/dist/experimental.d.ts +8 -0
- package/dist/experimental.js +7 -0
- package/dist/fanout.d.ts +25 -2
- package/dist/fanout.js +273 -93
- package/dist/index.d.ts +8 -7
- package/dist/index.js +3 -2
- package/dist/lifecycle.d.ts +8 -0
- package/dist/lifecycle.js +22 -0
- package/dist/log.d.ts +201 -0
- package/dist/log.js +705 -0
- package/dist/migrations.d.ts +28 -1
- package/dist/migrations.js +100 -0
- package/dist/scheduler.d.ts +35 -20
- package/dist/scheduler.js +112 -90
- package/dist/socket-protocol.d.ts +95 -0
- package/dist/socket-protocol.js +71 -0
- package/dist/socket.d.ts +92 -0
- package/dist/socket.js +273 -0
- package/dist/storage.d.ts +39 -128
- package/dist/storage.js +64 -68
- package/dist/tracked-source.d.ts +87 -0
- package/dist/tracked-source.js +7 -0
- package/dist/tracker.d.ts +96 -0
- package/dist/tracker.js +171 -0
- package/package.json +18 -4
- package/dist/kv-storage.d.ts +0 -2
- package/dist/kv-storage.js +0 -421
- package/dist/sqlite-storage.d.ts +0 -2
- package/dist/sqlite-storage.js +0 -251
package/dist/migrations.d.ts
CHANGED
|
@@ -28,6 +28,33 @@ export declare const durabilityFanoutMigrations: {
|
|
|
28
28
|
up: string;
|
|
29
29
|
down: string;
|
|
30
30
|
}[];
|
|
31
|
+
/**
|
|
32
|
+
* Ordered SQLite migrations for the outbound event log owned by
|
|
33
|
+
* {@link DurabilitySocket}. Applied automatically on construction.
|
|
34
|
+
*/
|
|
35
|
+
export declare const durabilitySocketMigrations: {
|
|
36
|
+
name: string;
|
|
37
|
+
up: string;
|
|
38
|
+
down: string;
|
|
39
|
+
}[];
|
|
40
|
+
/**
|
|
41
|
+
* Ordered SQLite migrations for the retained log and its consumer cursors.
|
|
42
|
+
* Applied automatically on construction.
|
|
43
|
+
*/
|
|
44
|
+
export declare const durabilityLogMigrations: {
|
|
45
|
+
name: string;
|
|
46
|
+
up: string;
|
|
47
|
+
down: string;
|
|
48
|
+
}[];
|
|
49
|
+
/**
|
|
50
|
+
* Leases let several workers consume one log in parallel without handing the
|
|
51
|
+
* same offsets to two of them. Applied automatically when leases are enabled.
|
|
52
|
+
*/
|
|
53
|
+
export declare const durabilityLogLeaseMigrations: {
|
|
54
|
+
name: string;
|
|
55
|
+
up: string;
|
|
56
|
+
down: string;
|
|
57
|
+
}[];
|
|
31
58
|
/** Migration names changed by one migrate call. */
|
|
32
59
|
export type DurabilityMigrationResult = {
|
|
33
60
|
/** Migrations applied in ascending order. */
|
|
@@ -35,7 +62,7 @@ export type DurabilityMigrationResult = {
|
|
|
35
62
|
/** Migrations reverted in descending order. */
|
|
36
63
|
rolledBack: string[];
|
|
37
64
|
};
|
|
38
|
-
export type MigrationCapability = 'operations' | 'namedAlarms' | 'fanout';
|
|
65
|
+
export type MigrationCapability = 'operations' | 'namedAlarms' | 'fanout' | 'socket' | 'log' | 'logLeases';
|
|
39
66
|
type MigrationStorage = Pick<DurableObjectStorage, 'sql' | 'transactionSync'>;
|
|
40
67
|
/**
|
|
41
68
|
* Moves one capability's schema to a target migration, applying or reverting as
|
package/dist/migrations.js
CHANGED
|
@@ -222,6 +222,106 @@ export const durabilityFanoutMigrations = [
|
|
|
222
222
|
`,
|
|
223
223
|
},
|
|
224
224
|
];
|
|
225
|
+
/**
|
|
226
|
+
* Ordered SQLite migrations for the outbound event log owned by
|
|
227
|
+
* {@link DurabilitySocket}. Applied automatically on construction.
|
|
228
|
+
*/
|
|
229
|
+
export const durabilitySocketMigrations = [
|
|
230
|
+
{
|
|
231
|
+
name: 'durability_0006_create_socket_events',
|
|
232
|
+
up: `
|
|
233
|
+
CREATE TABLE IF NOT EXISTS durability_socket_events (
|
|
234
|
+
seq INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
235
|
+
name TEXT NOT NULL,
|
|
236
|
+
payload TEXT NOT NULL,
|
|
237
|
+
created_at INTEGER NOT NULL
|
|
238
|
+
);
|
|
239
|
+
`,
|
|
240
|
+
down: 'DROP TABLE IF EXISTS durability_socket_events;',
|
|
241
|
+
},
|
|
242
|
+
];
|
|
243
|
+
/**
|
|
244
|
+
* Ordered SQLite migrations for the retained log and its consumer cursors.
|
|
245
|
+
* Applied automatically on construction.
|
|
246
|
+
*/
|
|
247
|
+
export const durabilityLogMigrations = [
|
|
248
|
+
{
|
|
249
|
+
name: 'durability_0007_create_log',
|
|
250
|
+
up: `
|
|
251
|
+
CREATE TABLE IF NOT EXISTS durability_log_records (
|
|
252
|
+
"offset" INTEGER PRIMARY KEY,
|
|
253
|
+
dedup_key TEXT NOT NULL UNIQUE,
|
|
254
|
+
payload TEXT NOT NULL,
|
|
255
|
+
bytes INTEGER NOT NULL,
|
|
256
|
+
appended_at INTEGER NOT NULL
|
|
257
|
+
);
|
|
258
|
+
CREATE INDEX IF NOT EXISTS durability_log_records_appended_idx
|
|
259
|
+
ON durability_log_records (appended_at, "offset");
|
|
260
|
+
CREATE TABLE IF NOT EXISTS durability_log_cursors (
|
|
261
|
+
consumer TEXT PRIMARY KEY,
|
|
262
|
+
"offset" INTEGER NOT NULL,
|
|
263
|
+
committed_at INTEGER NOT NULL
|
|
264
|
+
);
|
|
265
|
+
CREATE TABLE IF NOT EXISTS durability_log_segments (
|
|
266
|
+
first_offset INTEGER PRIMARY KEY,
|
|
267
|
+
last_offset INTEGER NOT NULL,
|
|
268
|
+
locator TEXT NOT NULL,
|
|
269
|
+
bytes INTEGER NOT NULL,
|
|
270
|
+
flushed_at INTEGER NOT NULL
|
|
271
|
+
);
|
|
272
|
+
CREATE TABLE IF NOT EXISTS durability_log_seq (
|
|
273
|
+
id INTEGER PRIMARY KEY CHECK (id = 1),
|
|
274
|
+
next_offset INTEGER NOT NULL,
|
|
275
|
+
total_bytes INTEGER NOT NULL
|
|
276
|
+
);
|
|
277
|
+
INSERT OR IGNORE INTO durability_log_seq (id, next_offset, total_bytes)
|
|
278
|
+
VALUES (1, 0, 0);
|
|
279
|
+
`,
|
|
280
|
+
down: `
|
|
281
|
+
DROP INDEX IF EXISTS durability_log_records_appended_idx;
|
|
282
|
+
DROP TABLE IF EXISTS durability_log_records;
|
|
283
|
+
DROP TABLE IF EXISTS durability_log_cursors;
|
|
284
|
+
DROP TABLE IF EXISTS durability_log_segments;
|
|
285
|
+
DROP TABLE IF EXISTS durability_log_seq;
|
|
286
|
+
`,
|
|
287
|
+
},
|
|
288
|
+
];
|
|
289
|
+
/**
|
|
290
|
+
* Leases let several workers consume one log in parallel without handing the
|
|
291
|
+
* same offsets to two of them. Applied automatically when leases are enabled.
|
|
292
|
+
*/
|
|
293
|
+
export const durabilityLogLeaseMigrations = [
|
|
294
|
+
{
|
|
295
|
+
name: 'durability_0008_create_log_leases',
|
|
296
|
+
up: `
|
|
297
|
+
CREATE TABLE IF NOT EXISTS durability_log_leases (
|
|
298
|
+
batch_id TEXT PRIMARY KEY,
|
|
299
|
+
consumer TEXT NOT NULL,
|
|
300
|
+
first_offset INTEGER NOT NULL,
|
|
301
|
+
last_offset INTEGER NOT NULL,
|
|
302
|
+
state TEXT NOT NULL
|
|
303
|
+
CHECK (state IN ('active', 'pending', 'acked', 'skipped')),
|
|
304
|
+
attempt INTEGER NOT NULL,
|
|
305
|
+
expires_at INTEGER NOT NULL,
|
|
306
|
+
created_at INTEGER NOT NULL
|
|
307
|
+
);
|
|
308
|
+
CREATE INDEX IF NOT EXISTS durability_log_leases_claim_idx
|
|
309
|
+
ON durability_log_leases (consumer, state, expires_at, first_offset);
|
|
310
|
+
CREATE INDEX IF NOT EXISTS durability_log_leases_order_idx
|
|
311
|
+
ON durability_log_leases (consumer, first_offset);
|
|
312
|
+
CREATE TABLE IF NOT EXISTS durability_log_allocations (
|
|
313
|
+
consumer TEXT PRIMARY KEY,
|
|
314
|
+
allocated_offset INTEGER NOT NULL
|
|
315
|
+
);
|
|
316
|
+
`,
|
|
317
|
+
down: `
|
|
318
|
+
DROP INDEX IF EXISTS durability_log_leases_claim_idx;
|
|
319
|
+
DROP INDEX IF EXISTS durability_log_leases_order_idx;
|
|
320
|
+
DROP TABLE IF EXISTS durability_log_leases;
|
|
321
|
+
DROP TABLE IF EXISTS durability_log_allocations;
|
|
322
|
+
`,
|
|
323
|
+
},
|
|
324
|
+
];
|
|
225
325
|
/**
|
|
226
326
|
* Newer library versions may leave migrations this one does not know about.
|
|
227
327
|
* On downgrade their stored `down` scripts are run, but only this many, so an
|
package/dist/scheduler.d.ts
CHANGED
|
@@ -1,15 +1,12 @@
|
|
|
1
1
|
import { type Emit, type LifecycleEntity, type LifecycleHook } from './lifecycle.js';
|
|
2
2
|
import { type MigrationCapability } from './migrations.js';
|
|
3
3
|
import { type AttemptPolicy } from './policy.js';
|
|
4
|
-
import { type
|
|
4
|
+
import { type DurableTable } from './storage.js';
|
|
5
5
|
import type { DurableMigrations } from '@durability/storage';
|
|
6
6
|
/** The Durable Object state durability needs: storage plus optional `waitUntil`. */
|
|
7
7
|
export type DurabilityContext = Pick<DurableObjectState, 'storage'> & Partial<Pick<DurableObjectState, 'waitUntil'>>;
|
|
8
|
-
export type DurabilityStorageBackend = 'sqlite' | 'kv';
|
|
9
8
|
/** Options for the scheduler shared by every durability helper in one Durable Object. */
|
|
10
9
|
export type DurabilitySchedulerOptions = {
|
|
11
|
-
/** Storage backend configured for the Durable Object class. Defaults to SQLite. */
|
|
12
|
-
storageBackend?: DurabilityStorageBackend;
|
|
13
10
|
/** Maximum handlers running at once across eager operations and alarm work. Defaults to 10. */
|
|
14
11
|
alarmConcurrency?: number;
|
|
15
12
|
/** Physical-alarm delay from 1 to 15 seconds. Defaults to 15 seconds. */
|
|
@@ -31,11 +28,17 @@ export type SchedulerAttachment = {
|
|
|
31
28
|
} | (DurabilitySchedulerConfig & {
|
|
32
29
|
scheduler?: never;
|
|
33
30
|
});
|
|
34
|
-
/** One record
|
|
31
|
+
/** One record table attached to the scheduler: how to find and run its due work. */
|
|
35
32
|
export type Participant = {
|
|
36
|
-
|
|
33
|
+
table: DurableTable;
|
|
37
34
|
runDue(now: number, info: AlarmInvocationInfo | undefined): Promise<void>;
|
|
38
35
|
};
|
|
36
|
+
/**
|
|
37
|
+
* Called after a record may have settled. Successful completions pass the
|
|
38
|
+
* executed row because some tables delete it on success; other changes pass
|
|
39
|
+
* nothing and listeners re-read storage.
|
|
40
|
+
*/
|
|
41
|
+
export type SettlementListener = (completed?: ExecutionSpec['row']) => void;
|
|
39
42
|
export type ActiveExecution = {
|
|
40
43
|
generation: string;
|
|
41
44
|
createdAt: number;
|
|
@@ -44,9 +47,12 @@ export type ActiveExecution = {
|
|
|
44
47
|
};
|
|
45
48
|
/** Everything that differs between running a durable operation and a named alarm attempt. */
|
|
46
49
|
export type ExecutionSpec = {
|
|
47
|
-
|
|
50
|
+
table: DurableTable;
|
|
48
51
|
key: string;
|
|
49
|
-
row:
|
|
52
|
+
row: {
|
|
53
|
+
generation_id: string;
|
|
54
|
+
created_at: number;
|
|
55
|
+
};
|
|
50
56
|
label: string;
|
|
51
57
|
entity: LifecycleEntity;
|
|
52
58
|
active: Map<string, ActiveExecution>;
|
|
@@ -60,17 +66,16 @@ export type ExecutionSpec = {
|
|
|
60
66
|
* undefined when a newer generation won. May throw to turn the success into
|
|
61
67
|
* a failure.
|
|
62
68
|
*/
|
|
63
|
-
complete: (result: unknown, attempt: number) =>
|
|
69
|
+
complete: (result: unknown, attempt: number) => number | undefined;
|
|
64
70
|
/** Kind-specific terminal rule beyond non-retryable errors and exhausted attempts. */
|
|
65
71
|
isTerminal: (error: unknown) => boolean;
|
|
66
72
|
};
|
|
67
73
|
/**
|
|
68
|
-
* Shared machinery behind {@link DurabilityScheduler}:
|
|
74
|
+
* Shared machinery behind {@link DurabilityScheduler}: transactions, the physical
|
|
69
75
|
* alarm, the concurrency pool, and the attempt lifecycle. Package-internal.
|
|
70
76
|
*/
|
|
71
77
|
export declare class Engine {
|
|
72
|
-
readonly
|
|
73
|
-
private readonly backend;
|
|
78
|
+
readonly sql: SqlStorage;
|
|
74
79
|
private readonly context;
|
|
75
80
|
private readonly alarmConcurrency;
|
|
76
81
|
private readonly alarmMinDelayMs;
|
|
@@ -80,24 +85,34 @@ export declare class Engine {
|
|
|
80
85
|
private readonly permitWaiters;
|
|
81
86
|
private alarmRefresh;
|
|
82
87
|
private earlyAlarm;
|
|
83
|
-
private readonly
|
|
88
|
+
private readonly watchers;
|
|
84
89
|
constructor(context: DurabilityContext, options: DurabilitySchedulerOptions);
|
|
85
90
|
register(participant: Participant): void;
|
|
86
91
|
waitUntil(promise: Promise<unknown>, onError: (error: unknown) => void): void;
|
|
87
92
|
emitter(hook: LifecycleHook | undefined): Emit;
|
|
88
|
-
/** Applies a helper's SQLite migrations
|
|
93
|
+
/** Applies a helper's SQLite migrations. */
|
|
89
94
|
migrateSchema(capability: MigrationCapability, migrations: DurableMigrations): void;
|
|
90
|
-
/** Runs
|
|
91
|
-
|
|
92
|
-
|
|
95
|
+
/** Runs synchronous writes atomically without touching the physical alarm. */
|
|
96
|
+
transactionSync<T>(write: (sql: SqlStorage) => T): T;
|
|
97
|
+
/**
|
|
98
|
+
* Runs the writes and reconciles the physical alarm in one storage
|
|
99
|
+
* transaction, then publishes the in-memory timer only after commit.
|
|
100
|
+
*/
|
|
101
|
+
transaction<T>(write: (sql: SqlStorage) => T): Promise<T>;
|
|
102
|
+
/** Returns the earliest pending time and maintains its bounded physical fallback. */
|
|
103
|
+
private reconcile;
|
|
93
104
|
private scheduleEarlyAlarm;
|
|
94
105
|
/** Coalesces concurrent refresh requests into one reconciliation transaction. */
|
|
95
106
|
scheduleNextAlarm(): Promise<void>;
|
|
96
107
|
/**
|
|
97
108
|
* Aborts matching active handlers, then deletes one kind's records created
|
|
98
|
-
* before the timestamp
|
|
109
|
+
* before the timestamp and reconciles the alarm in the same transaction.
|
|
99
110
|
*/
|
|
100
|
-
purge(
|
|
111
|
+
purge(table: DurableTable, before: number, active: Map<string, ActiveExecution>, abortReason: string): Promise<number>;
|
|
112
|
+
/** In-memory only: listeners never survive eviction. */
|
|
113
|
+
watch(table: DurableTable, key: string, listener: SettlementListener): () => void;
|
|
114
|
+
/** Call only after the change has committed. */
|
|
115
|
+
notify(table: DurableTable, key: string, completed?: ExecutionSpec['row']): void;
|
|
101
116
|
tryAcquirePermit(): (() => void) | undefined;
|
|
102
117
|
acquirePermit(): Promise<() => void>;
|
|
103
118
|
private createRelease;
|
|
@@ -118,7 +133,7 @@ export declare class Engine {
|
|
|
118
133
|
private settleFailure;
|
|
119
134
|
}
|
|
120
135
|
/**
|
|
121
|
-
* Owns the Durable Object's physical alarm, storage
|
|
136
|
+
* Owns the Durable Object's physical alarm, storage, and concurrency
|
|
122
137
|
* pool so {@link Durability} and {@link DurabilityAlarms} can share them.
|
|
123
138
|
*
|
|
124
139
|
* Construct one per Durable Object when using both helpers, pass it to each,
|
package/dist/scheduler.js
CHANGED
|
@@ -1,14 +1,15 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
2
|
import { DurableRetryPolicyError, isErrorInstance, isNonRetryable, reportFailure, serializeError, } from './errors.js';
|
|
3
|
-
import { createKvDurabilityStorage } from './kv-storage.js';
|
|
4
3
|
import { createEmitter, } from './lifecycle.js';
|
|
5
4
|
import { migrate } from './migrations.js';
|
|
6
5
|
import { assertPositiveInteger } from './policy.js';
|
|
7
|
-
import {
|
|
8
|
-
import { reconcilePhysicalAlarm, } from './storage.js';
|
|
9
|
-
const storageBackendSchema = z.enum(['sqlite', 'kv']);
|
|
6
|
+
import { claimAttempt, exhaustAttempts, updateAttempt, } from './storage.js';
|
|
10
7
|
const minAlarmDelayMs = 1000;
|
|
11
8
|
const maxAlarmDelayMs = 15000;
|
|
9
|
+
const nextAttemptRowSchema = z.object({
|
|
10
|
+
next_attempt_at: z.number().int().nonnegative(),
|
|
11
|
+
});
|
|
12
|
+
const countRowSchema = z.object({ count: z.number().int().nonnegative() });
|
|
12
13
|
const decideRetry = (spec, attempt, error) => {
|
|
13
14
|
const terminal = isNonRetryable(error) ||
|
|
14
15
|
attempt >= spec.policy.maxAttempts ||
|
|
@@ -48,20 +49,16 @@ const decideRetry = (spec, attempt, error) => {
|
|
|
48
49
|
}
|
|
49
50
|
};
|
|
50
51
|
/**
|
|
51
|
-
* Shared machinery behind {@link DurabilityScheduler}:
|
|
52
|
+
* Shared machinery behind {@link DurabilityScheduler}: transactions, the physical
|
|
52
53
|
* alarm, the concurrency pool, and the attempt lifecycle. Package-internal.
|
|
53
54
|
*/
|
|
54
55
|
export class Engine {
|
|
55
56
|
constructor(context, options) {
|
|
56
57
|
this.participants = [];
|
|
57
58
|
this.permitWaiters = [];
|
|
58
|
-
this.
|
|
59
|
+
this.watchers = new Map();
|
|
59
60
|
this.context = context;
|
|
60
|
-
this.
|
|
61
|
-
this.storage =
|
|
62
|
-
this.backend === 'kv'
|
|
63
|
-
? createKvDurabilityStorage(context.storage)
|
|
64
|
-
: createSqliteDurabilityStorage(context.storage);
|
|
61
|
+
this.sql = context.storage.sql;
|
|
65
62
|
this.alarmConcurrency = options.alarmConcurrency ?? 10;
|
|
66
63
|
this.alarmMinDelayMs = options.alarmMinDelayMs ?? 15000;
|
|
67
64
|
this.alarmHandoffMs = options.alarmHandoffMs ?? 14 * 60000;
|
|
@@ -75,8 +72,9 @@ export class Engine {
|
|
|
75
72
|
this.availablePermits = this.alarmConcurrency;
|
|
76
73
|
}
|
|
77
74
|
register(participant) {
|
|
78
|
-
|
|
79
|
-
|
|
75
|
+
const { name } = participant.table;
|
|
76
|
+
if (this.participants.some(({ table }) => table.name === name)) {
|
|
77
|
+
throw new Error(`A ${name} helper is already attached to this scheduler`);
|
|
80
78
|
}
|
|
81
79
|
this.participants.push(participant);
|
|
82
80
|
}
|
|
@@ -94,37 +92,55 @@ export class Engine {
|
|
|
94
92
|
emitter(hook) {
|
|
95
93
|
return createEmitter(hook, (promise) => this.context.waitUntil?.(promise));
|
|
96
94
|
}
|
|
97
|
-
/** Applies a helper's SQLite migrations
|
|
95
|
+
/** Applies a helper's SQLite migrations. */
|
|
98
96
|
migrateSchema(capability, migrations) {
|
|
99
|
-
|
|
100
|
-
migrate(this.context.storage, capability, migrations, undefined);
|
|
101
|
-
}
|
|
97
|
+
migrate(this.context.storage, capability, migrations, undefined);
|
|
102
98
|
}
|
|
103
|
-
/** Runs
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
99
|
+
/** Runs synchronous writes atomically without touching the physical alarm. */
|
|
100
|
+
transactionSync(write) {
|
|
101
|
+
return this.context.storage.transactionSync(() => write(this.sql));
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Runs the writes and reconciles the physical alarm in one storage
|
|
105
|
+
* transaction, then publishes the in-memory timer only after commit.
|
|
106
|
+
*/
|
|
107
|
+
async transaction(write) {
|
|
108
|
+
let nextPendingAt;
|
|
109
|
+
const result = await this.context.storage.transaction(async (transaction) => {
|
|
110
|
+
const value = write(this.sql);
|
|
111
|
+
nextPendingAt = await this.reconcile(transaction);
|
|
112
|
+
return value;
|
|
115
113
|
});
|
|
116
|
-
|
|
117
|
-
this.scheduleEarlyAlarm(reconciliation.nextPendingAt);
|
|
118
|
-
}
|
|
114
|
+
this.scheduleEarlyAlarm(nextPendingAt);
|
|
119
115
|
return result;
|
|
120
116
|
}
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
117
|
+
/** Returns the earliest pending time and maintains its bounded physical fallback. */
|
|
118
|
+
async reconcile(physicalAlarm) {
|
|
119
|
+
const scheduled = this.participants.flatMap(({ table }) => nextAttemptRowSchema
|
|
120
|
+
.array()
|
|
121
|
+
.parse(this.sql
|
|
122
|
+
.exec(`SELECT next_attempt_at FROM ${table.name}
|
|
123
|
+
WHERE status = 'pending'
|
|
124
|
+
ORDER BY next_attempt_at ASC
|
|
125
|
+
LIMIT 1`)
|
|
126
|
+
.toArray())
|
|
127
|
+
.map((row) => row.next_attempt_at));
|
|
128
|
+
const nextAlarmAt = scheduled.length === 0 ? undefined : Math.min(...scheduled);
|
|
129
|
+
const currentAlarm = await physicalAlarm.getAlarm();
|
|
130
|
+
if (nextAlarmAt === undefined) {
|
|
131
|
+
if (currentAlarm !== null) {
|
|
132
|
+
await physicalAlarm.deleteAlarm();
|
|
133
|
+
}
|
|
134
|
+
return undefined;
|
|
125
135
|
}
|
|
126
|
-
|
|
127
|
-
reconciliation
|
|
136
|
+
const target = Math.max(nextAlarmAt, Date.now() + this.alarmMinDelayMs);
|
|
137
|
+
// Preserve a fallback inside this range so frequent reconciliation cannot push it later.
|
|
138
|
+
if (currentAlarm === null ||
|
|
139
|
+
currentAlarm < nextAlarmAt ||
|
|
140
|
+
currentAlarm > target) {
|
|
141
|
+
await physicalAlarm.setAlarm(target);
|
|
142
|
+
}
|
|
143
|
+
return nextAlarmAt;
|
|
128
144
|
}
|
|
129
145
|
scheduleEarlyAlarm(timestamp) {
|
|
130
146
|
if (this.earlyAlarm?.timestamp === timestamp) {
|
|
@@ -154,16 +170,16 @@ export class Engine {
|
|
|
154
170
|
if (this.alarmRefresh) {
|
|
155
171
|
return this.alarmRefresh;
|
|
156
172
|
}
|
|
157
|
-
this.alarmRefresh = this.transaction((
|
|
173
|
+
this.alarmRefresh = this.transaction(() => undefined).finally(() => {
|
|
158
174
|
this.alarmRefresh = undefined;
|
|
159
175
|
});
|
|
160
176
|
return this.alarmRefresh;
|
|
161
177
|
}
|
|
162
178
|
/**
|
|
163
179
|
* Aborts matching active handlers, then deletes one kind's records created
|
|
164
|
-
* before the timestamp
|
|
180
|
+
* before the timestamp and reconciles the alarm in the same transaction.
|
|
165
181
|
*/
|
|
166
|
-
async purge(
|
|
182
|
+
async purge(table, before, active, abortReason) {
|
|
167
183
|
if (!Number.isSafeInteger(before) || before < 0) {
|
|
168
184
|
throw new RangeError('timestamp must be a non-negative safe integer');
|
|
169
185
|
}
|
|
@@ -172,18 +188,40 @@ export class Engine {
|
|
|
172
188
|
running.controller?.abort(new Error(abortReason));
|
|
173
189
|
}
|
|
174
190
|
}
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
191
|
+
const removed = await this.transaction((sql) => {
|
|
192
|
+
const { count } = countRowSchema.parse(sql
|
|
193
|
+
.exec(`SELECT COUNT(*) AS count FROM ${table.name} WHERE created_at < ?`, before)
|
|
194
|
+
.toArray()[0]);
|
|
195
|
+
sql.exec(`DELETE FROM ${table.name} WHERE created_at < ?`, before);
|
|
196
|
+
return count;
|
|
197
|
+
});
|
|
198
|
+
if (removed > 0) {
|
|
199
|
+
for (const key of this.watchers.get(table.name)?.keys() ?? []) {
|
|
200
|
+
this.notify(table, key);
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
return removed;
|
|
204
|
+
}
|
|
205
|
+
/** In-memory only: listeners never survive eviction. */
|
|
206
|
+
watch(table, key, listener) {
|
|
207
|
+
const byKey = this.watchers.get(table.name) ??
|
|
208
|
+
new Map();
|
|
209
|
+
this.watchers.set(table.name, byKey);
|
|
210
|
+
const listeners = byKey.get(key) ?? new Set();
|
|
211
|
+
byKey.set(key, listeners);
|
|
212
|
+
listeners.add(listener);
|
|
213
|
+
return () => {
|
|
214
|
+
listeners.delete(listener);
|
|
215
|
+
if (listeners.size === 0 && byKey.get(key) === listeners) {
|
|
216
|
+
byKey.delete(key);
|
|
217
|
+
}
|
|
218
|
+
};
|
|
219
|
+
}
|
|
220
|
+
/** Call only after the change has committed. */
|
|
221
|
+
notify(table, key, completed) {
|
|
222
|
+
for (const listener of this.watchers.get(table.name)?.get(key) ?? []) {
|
|
223
|
+
listener(completed);
|
|
224
|
+
}
|
|
187
225
|
}
|
|
188
226
|
tryAcquirePermit() {
|
|
189
227
|
if (this.availablePermits === 0) {
|
|
@@ -261,7 +299,7 @@ export class Engine {
|
|
|
261
299
|
await this.scheduleNextAlarm();
|
|
262
300
|
}
|
|
263
301
|
armForHandoff(timestamp) {
|
|
264
|
-
return this.storage.transaction(async (
|
|
302
|
+
return this.context.storage.transaction(async (physicalAlarm) => {
|
|
265
303
|
const currentAlarm = await physicalAlarm.getAlarm();
|
|
266
304
|
const target = Math.max(timestamp, Date.now() + this.alarmMinDelayMs);
|
|
267
305
|
if (currentAlarm === null || currentAlarm > target) {
|
|
@@ -298,7 +336,7 @@ export class Engine {
|
|
|
298
336
|
};
|
|
299
337
|
const execution = (async () => {
|
|
300
338
|
releasePermit ?? (releasePermit = await this.acquirePermit());
|
|
301
|
-
const attempt =
|
|
339
|
+
const attempt = claimAttempt(this.sql, spec.table, key, row.generation_id, policy.maxAttempts);
|
|
302
340
|
if (attempt === undefined) {
|
|
303
341
|
await this.failExhausted(spec);
|
|
304
342
|
return;
|
|
@@ -330,8 +368,9 @@ export class Engine {
|
|
|
330
368
|
}, policy.attemptTimeoutMs);
|
|
331
369
|
});
|
|
332
370
|
const result = await Promise.race([handlerResult, timeoutResult]);
|
|
333
|
-
const timestamp =
|
|
371
|
+
const timestamp = spec.complete(result, attempt);
|
|
334
372
|
if (timestamp !== undefined) {
|
|
373
|
+
this.notify(spec.table, key, row);
|
|
335
374
|
spec.emit({
|
|
336
375
|
...spec.entity,
|
|
337
376
|
type: 'attempt_settled',
|
|
@@ -339,6 +378,7 @@ export class Engine {
|
|
|
339
378
|
attempt,
|
|
340
379
|
durationMs: Math.max(0, timestamp - startedAt),
|
|
341
380
|
outcome: 'completed',
|
|
381
|
+
result,
|
|
342
382
|
});
|
|
343
383
|
}
|
|
344
384
|
}
|
|
@@ -363,50 +403,32 @@ export class Engine {
|
|
|
363
403
|
}
|
|
364
404
|
async failExhausted(spec) {
|
|
365
405
|
const { key, row, policy } = spec;
|
|
366
|
-
const
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
current.attempt < policy.maxAttempts) {
|
|
406
|
+
const exhausted = serializeError(spec.exhaustedError());
|
|
407
|
+
const attempt = await this.transaction((sql) => exhaustAttempts(sql, spec.table, key, row.generation_id, policy.maxAttempts, exhausted));
|
|
408
|
+
if (attempt === undefined) {
|
|
370
409
|
return;
|
|
371
410
|
}
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
await this.reconcile(transaction);
|
|
411
|
+
this.notify(spec.table, key);
|
|
412
|
+
spec.emit({
|
|
413
|
+
...spec.entity,
|
|
414
|
+
type: 'terminal',
|
|
415
|
+
timestamp: Date.now(),
|
|
416
|
+
attempt,
|
|
417
|
+
reason: 'attempts_exhausted',
|
|
418
|
+
error: exhausted,
|
|
381
419
|
});
|
|
382
|
-
if (updated) {
|
|
383
|
-
spec.emit({
|
|
384
|
-
...spec.entity,
|
|
385
|
-
type: 'terminal',
|
|
386
|
-
timestamp: Date.now(),
|
|
387
|
-
attempt: current.attempt,
|
|
388
|
-
reason: 'attempts_exhausted',
|
|
389
|
-
error: exhausted,
|
|
390
|
-
});
|
|
391
|
-
}
|
|
392
420
|
}
|
|
393
421
|
async settleFailure(spec, attempt, startedAt, caught) {
|
|
394
422
|
const { key, row } = spec;
|
|
395
423
|
const decision = decideRetry(spec, attempt, caught);
|
|
396
424
|
const serializedError = serializeError(decision.error);
|
|
397
|
-
|
|
398
|
-
await this.transaction(async (transaction) => {
|
|
399
|
-
updated = await transaction[spec.kind].settle(key, row.generation_id, attempt, {
|
|
400
|
-
status: decision.terminal ? 'failed' : 'pending',
|
|
401
|
-
next_attempt_at: decision.nextAttemptAt,
|
|
402
|
-
last_error: serializedError.message,
|
|
403
|
-
last_error_name: serializedError.name,
|
|
404
|
-
});
|
|
405
|
-
await this.reconcile(transaction);
|
|
406
|
-
});
|
|
425
|
+
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));
|
|
407
426
|
if (!updated) {
|
|
408
427
|
return;
|
|
409
428
|
}
|
|
429
|
+
if (decision.terminal) {
|
|
430
|
+
this.notify(spec.table, key);
|
|
431
|
+
}
|
|
410
432
|
const settled = {
|
|
411
433
|
...spec.entity,
|
|
412
434
|
type: 'attempt_settled',
|
|
@@ -426,7 +448,7 @@ export class Engine {
|
|
|
426
448
|
}
|
|
427
449
|
const engines = new WeakMap();
|
|
428
450
|
/**
|
|
429
|
-
* Owns the Durable Object's physical alarm, storage
|
|
451
|
+
* Owns the Durable Object's physical alarm, storage, and concurrency
|
|
430
452
|
* pool so {@link Durability} and {@link DurabilityAlarms} can share them.
|
|
431
453
|
*
|
|
432
454
|
* Construct one per Durable Object when using both helpers, pass it to each,
|