durability 4.3.0 → 5.1.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 +245 -20
- package/dist/durability-alarms.d.ts +25 -3
- package/dist/durability-alarms.js +50 -8
- package/dist/durability.d.ts +30 -5
- package/dist/durability.js +42 -14
- package/dist/errors.d.ts +29 -0
- package/dist/errors.js +47 -0
- package/dist/experimental.d.ts +3 -0
- package/dist/experimental.js +3 -0
- package/dist/fanout.d.ts +6 -0
- package/dist/fanout.js +10 -6
- package/dist/index.d.ts +4 -3
- 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 +27 -1
- package/dist/migrations.js +93 -1
- package/dist/outbox.js +2 -3
- package/dist/schedule.d.ts +157 -0
- package/dist/schedule.js +651 -0
- package/dist/scheduler.d.ts +53 -1
- package/dist/scheduler.js +164 -30
- package/dist/semaphore-queue-store.js +23 -19
- package/dist/storage.d.ts +6 -2
- package/dist/storage.js +13 -7
- package/dist/tracked-source.d.ts +2 -0
- package/package.json +2 -1
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.
|
|
@@ -92,6 +102,15 @@ export declare const durabilityTopologyMigrations: {
|
|
|
92
102
|
up: string;
|
|
93
103
|
down: string;
|
|
94
104
|
}[];
|
|
105
|
+
/**
|
|
106
|
+
* Ordered SQLite migrations for the experimental schedule. Applied
|
|
107
|
+
* automatically on construction.
|
|
108
|
+
*/
|
|
109
|
+
export declare const durabilityScheduleMigrations: {
|
|
110
|
+
name: string;
|
|
111
|
+
up: string;
|
|
112
|
+
down: string;
|
|
113
|
+
}[];
|
|
95
114
|
/** Migration names changed by one migrate call. */
|
|
96
115
|
export type DurabilityMigrationResult = {
|
|
97
116
|
/** Migrations applied in ascending order. */
|
|
@@ -99,8 +118,15 @@ export type DurabilityMigrationResult = {
|
|
|
99
118
|
/** Migrations reverted in descending order. */
|
|
100
119
|
rolledBack: string[];
|
|
101
120
|
};
|
|
102
|
-
export type MigrationCapability = 'operations' | 'namedAlarms' | 'fanout' | 'socket' | 'log' | 'logLeases' | 'outbox' | 'semaphore' | 'semaphoreQueue' | 'topology';
|
|
121
|
+
export type MigrationCapability = 'operations' | 'namedAlarms' | 'memos' | 'fanout' | 'socket' | 'log' | 'logLeases' | 'outbox' | 'semaphore' | 'semaphoreQueue' | 'topology' | 'schedule';
|
|
103
122
|
type MigrationStorage = Pick<DurableObjectStorage, 'sql' | 'transactionSync'>;
|
|
123
|
+
/**
|
|
124
|
+
* Whether a capability's history already lists exactly these migrations with
|
|
125
|
+
* these `down` scripts, so construction can skip {@link migrateCapability}. Every Durable
|
|
126
|
+
* Object wake constructs its helpers, and each statement there is one more way
|
|
127
|
+
* for the wake to fail, so the common case costs one read.
|
|
128
|
+
*/
|
|
129
|
+
export declare const isSchemaCurrent: (sql: SqlStorage, capability: MigrationCapability, migrations: DurableMigrations) => boolean;
|
|
104
130
|
/**
|
|
105
131
|
* Moves one capability's schema to a target migration, applying or reverting as
|
|
106
132
|
* 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.
|
|
@@ -549,6 +570,49 @@ export const durabilityTopologyMigrations = [
|
|
|
549
570
|
`,
|
|
550
571
|
},
|
|
551
572
|
];
|
|
573
|
+
/**
|
|
574
|
+
* Ordered SQLite migrations for the experimental schedule. Applied
|
|
575
|
+
* automatically on construction.
|
|
576
|
+
*/
|
|
577
|
+
export const durabilityScheduleMigrations = [
|
|
578
|
+
{
|
|
579
|
+
name: 'durability_0013_create_schedule',
|
|
580
|
+
// INTEGER PRIMARY KEY aliases the rowid, so each table is a single b-tree
|
|
581
|
+
// with no secondary index for per-run writes to maintain.
|
|
582
|
+
up: `
|
|
583
|
+
CREATE TABLE IF NOT EXISTS durability_schedule (
|
|
584
|
+
id INTEGER PRIMARY KEY CHECK (id = 1),
|
|
585
|
+
version INTEGER NOT NULL,
|
|
586
|
+
expression TEXT,
|
|
587
|
+
next_at INTEGER
|
|
588
|
+
);
|
|
589
|
+
CREATE TABLE IF NOT EXISTS durability_schedule_runs (
|
|
590
|
+
scheduled_time INTEGER PRIMARY KEY,
|
|
591
|
+
state TEXT NOT NULL
|
|
592
|
+
CHECK (state IN ('queued', 'running', 'complete', 'errored')),
|
|
593
|
+
next_at INTEGER NOT NULL,
|
|
594
|
+
attempt INTEGER NOT NULL DEFAULT 0,
|
|
595
|
+
error TEXT
|
|
596
|
+
);
|
|
597
|
+
`,
|
|
598
|
+
down: `
|
|
599
|
+
DROP TABLE IF EXISTS durability_schedule_runs;
|
|
600
|
+
DROP TABLE IF EXISTS durability_schedule;
|
|
601
|
+
`,
|
|
602
|
+
},
|
|
603
|
+
{
|
|
604
|
+
name: 'durability_0014_add_schedule_jitter',
|
|
605
|
+
up: `
|
|
606
|
+
ALTER TABLE durability_schedule ADD COLUMN jitter_ms INTEGER NOT NULL DEFAULT 0;
|
|
607
|
+
ALTER TABLE durability_schedule_runs ADD COLUMN due_at INTEGER;
|
|
608
|
+
UPDATE durability_schedule_runs SET due_at = scheduled_time;
|
|
609
|
+
`,
|
|
610
|
+
down: `
|
|
611
|
+
ALTER TABLE durability_schedule_runs DROP COLUMN due_at;
|
|
612
|
+
ALTER TABLE durability_schedule DROP COLUMN jitter_ms;
|
|
613
|
+
`,
|
|
614
|
+
},
|
|
615
|
+
];
|
|
552
616
|
/**
|
|
553
617
|
* Newer library versions may leave migrations this one does not know about.
|
|
554
618
|
* On downgrade their stored `down` scripts are run, but only this many, so an
|
|
@@ -641,6 +705,34 @@ const revertFutureMigrations = (storage, scope, history, known) => {
|
|
|
641
705
|
});
|
|
642
706
|
return future.map(({ name }) => name);
|
|
643
707
|
};
|
|
708
|
+
const currentRowSchema = z.object({
|
|
709
|
+
name: z.string(),
|
|
710
|
+
down: z.string().nullable(),
|
|
711
|
+
});
|
|
712
|
+
/**
|
|
713
|
+
* Whether a capability's history already lists exactly these migrations with
|
|
714
|
+
* these `down` scripts, so construction can skip {@link migrateCapability}. Every Durable
|
|
715
|
+
* Object wake constructs its helpers, and each statement there is one more way
|
|
716
|
+
* for the wake to fail, so the common case costs one read.
|
|
717
|
+
*/
|
|
718
|
+
export const isSchemaCurrent = (sql, capability, migrations) => {
|
|
719
|
+
let rows;
|
|
720
|
+
try {
|
|
721
|
+
rows = currentRowSchema
|
|
722
|
+
.array()
|
|
723
|
+
.parse(sql
|
|
724
|
+
.exec(`SELECT name, down FROM ${migrationTableName} WHERE capability = ?`, capability)
|
|
725
|
+
.toArray());
|
|
726
|
+
}
|
|
727
|
+
catch {
|
|
728
|
+
// A first construction has no history table, and an older one lacks the
|
|
729
|
+
// capability column; migrateCapability() creates both, and retries any other failure.
|
|
730
|
+
return false;
|
|
731
|
+
}
|
|
732
|
+
const known = new Map(migrations.map(({ name, down }) => [name, down]));
|
|
733
|
+
return (rows.length === known.size &&
|
|
734
|
+
rows.every((row) => known.get(row.name) === row.down));
|
|
735
|
+
};
|
|
644
736
|
const migrateScope = (storage, scope, migrations, target) => {
|
|
645
737
|
storage = traceStorage(storage);
|
|
646
738
|
const resolvedTarget = target === undefined
|
|
@@ -671,7 +763,7 @@ const migrateScope = (storage, scope, migrations, target) => {
|
|
|
671
763
|
.filter(({ name }) => !applied.has(name));
|
|
672
764
|
const toRefresh = migrations
|
|
673
765
|
.slice(0, targetIndex + 1)
|
|
674
|
-
.filter(({ name, down }) => applied.get(name)?.down !== down);
|
|
766
|
+
.filter(({ name, down }) => applied.has(name) && applied.get(name)?.down !== down);
|
|
675
767
|
storage.transactionSync(() => {
|
|
676
768
|
for (const migration of toRevert) {
|
|
677
769
|
runDown(storage.sql, scope.table, migration.name, migration.down);
|
package/dist/outbox.js
CHANGED
|
@@ -288,12 +288,11 @@ _DurabilityOutbox_engine = new WeakMap(), _DurabilityOutbox_channel = new WeakMa
|
|
|
288
288
|
const deadline = Date.now() + __classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f");
|
|
289
289
|
const claimed = [];
|
|
290
290
|
for (const row of due) {
|
|
291
|
-
|
|
291
|
+
// A crash mid-publication leaves the claim due again at the deadline.
|
|
292
|
+
const attempt = claimAttempt(sql, outboxTable, row.id, row.generation_id, Number.MAX_SAFE_INTEGER, deadline);
|
|
292
293
|
if (attempt === undefined) {
|
|
293
294
|
continue;
|
|
294
295
|
}
|
|
295
|
-
// A crash mid-publication leaves the claim due again at the deadline.
|
|
296
|
-
updateAttempt(sql, outboxTable, { key: row.id, generation: row.generation_id, attempt }, 'next_attempt_at = ?', deadline);
|
|
297
296
|
claimed.push({ ...row, attempt });
|
|
298
297
|
}
|
|
299
298
|
return claimed;
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
import { type SerializedError } from './errors.js';
|
|
2
|
+
import { type DurabilityMigrationResult } from './migrations.js';
|
|
3
|
+
import { type DurabilityRetryOptions } from './policy.js';
|
|
4
|
+
import { type SchedulerAttachment } from './scheduler.js';
|
|
5
|
+
/** A schedule as passed to {@link DurabilitySchedule.set}. */
|
|
6
|
+
export type ScheduleDefinition = {
|
|
7
|
+
/** Opaque to durability: only `nextOccurrence` interprets it. */
|
|
8
|
+
expression: string;
|
|
9
|
+
/**
|
|
10
|
+
* Orders updates: `set` stores only a version higher than the stored one,
|
|
11
|
+
* and the same version only re-arms a lost alarm.
|
|
12
|
+
*/
|
|
13
|
+
version: number;
|
|
14
|
+
/**
|
|
15
|
+
* Delays every tick by one fixed offset after its nominal time, to spread
|
|
16
|
+
* objects that share an expression. A number is the offset; `{ maxMs }`
|
|
17
|
+
* picks one uniformly in `[0, maxMs]` when the version is stored, so
|
|
18
|
+
* resending that version keeps it. Defaults to 0, at most 2^31 - 1. Keep
|
|
19
|
+
* it below the expression's interval.
|
|
20
|
+
*/
|
|
21
|
+
jitterMs?: number | {
|
|
22
|
+
maxMs: number;
|
|
23
|
+
};
|
|
24
|
+
};
|
|
25
|
+
/** The stored schedule returned by {@link DurabilitySchedule.get}. */
|
|
26
|
+
export type ScheduleState = {
|
|
27
|
+
expression: string;
|
|
28
|
+
version: number;
|
|
29
|
+
/** The stored offset, including one picked from `{ maxMs }`. */
|
|
30
|
+
jitterMs: number;
|
|
31
|
+
/**
|
|
32
|
+
* The next tick's nominal time, or `undefined` once `nextOccurrence`
|
|
33
|
+
* returned none. It fires at `nextAt + jitterMs`.
|
|
34
|
+
*/
|
|
35
|
+
nextAt: number | undefined;
|
|
36
|
+
};
|
|
37
|
+
/** One tick's run. */
|
|
38
|
+
export type ScheduledRun = {
|
|
39
|
+
/** The tick's nominal time, as `nextOccurrence` returned it. */
|
|
40
|
+
scheduledTime: number;
|
|
41
|
+
/**
|
|
42
|
+
* When the tick fired: `scheduledTime` plus the schedule's `jitterMs`. A run
|
|
43
|
+
* that waited for a slot starts later.
|
|
44
|
+
*/
|
|
45
|
+
dueAt: number;
|
|
46
|
+
/**
|
|
47
|
+
* `<objectId>:<scheduledTime>`, or the bare scheduled time when the context
|
|
48
|
+
* has no object ID. A tick fires at most once, so the key is unique per run.
|
|
49
|
+
*/
|
|
50
|
+
idempotencyKey: string;
|
|
51
|
+
};
|
|
52
|
+
/** What `run` receives. */
|
|
53
|
+
export type ScheduledRunContext = ScheduledRun & {
|
|
54
|
+
/** Aborted when the run exceeds `runTimeoutMs`. */
|
|
55
|
+
signal: AbortSignal;
|
|
56
|
+
};
|
|
57
|
+
/** What a run ended with, as passed to `onOutcome`. */
|
|
58
|
+
export type ScheduledRunOutcome = {
|
|
59
|
+
status: 'complete';
|
|
60
|
+
} | {
|
|
61
|
+
status: 'errored';
|
|
62
|
+
error: SerializedError;
|
|
63
|
+
};
|
|
64
|
+
/** The run an `onOutcome` call reports. */
|
|
65
|
+
export type ScheduledOutcomeDelivery = ScheduledRun & {
|
|
66
|
+
/** One-based delivery attempt of this outcome. */
|
|
67
|
+
attempt: number;
|
|
68
|
+
};
|
|
69
|
+
type ScheduledRunEntity = {
|
|
70
|
+
entityKind: 'scheduled_run';
|
|
71
|
+
/** The run's idempotency key. */
|
|
72
|
+
id: string;
|
|
73
|
+
scheduledTime: number;
|
|
74
|
+
timestamp: number;
|
|
75
|
+
};
|
|
76
|
+
/** Best-effort lifecycle signal for one scheduled run. */
|
|
77
|
+
export type DurabilityScheduleEvent = ScheduledRunEntity & ({
|
|
78
|
+
/** A tick recorded the run; `queued` when no run slot was free. */
|
|
79
|
+
type: 'due';
|
|
80
|
+
queued: boolean;
|
|
81
|
+
} | {
|
|
82
|
+
type: 'started';
|
|
83
|
+
} | {
|
|
84
|
+
/**
|
|
85
|
+
* The outcome was recorded. An interrupted run has no `durationMs` and
|
|
86
|
+
* a `ScheduledRunInterruptedError`.
|
|
87
|
+
*/
|
|
88
|
+
type: 'settled';
|
|
89
|
+
outcome: ScheduledRunOutcome['status'];
|
|
90
|
+
error?: SerializedError;
|
|
91
|
+
durationMs?: number;
|
|
92
|
+
} | {
|
|
93
|
+
type: 'outcome_retry';
|
|
94
|
+
attempt: number;
|
|
95
|
+
error: SerializedError;
|
|
96
|
+
nextAttemptAt: number;
|
|
97
|
+
} | {
|
|
98
|
+
/** `onOutcome` failed `maxAttempts` times; the run's row is deleted. */
|
|
99
|
+
type: 'dead_lettered';
|
|
100
|
+
attempt: number;
|
|
101
|
+
error: SerializedError;
|
|
102
|
+
});
|
|
103
|
+
export type DurabilityScheduleConfig = SchedulerAttachment & {
|
|
104
|
+
/**
|
|
105
|
+
* Returns the first tick strictly after `after`, or `undefined` for none.
|
|
106
|
+
* Must be synchronous and deterministic; durability ships no cron parser.
|
|
107
|
+
*/
|
|
108
|
+
nextOccurrence(expression: string, after: number): number | undefined;
|
|
109
|
+
/** The work of one tick. Throwing or timing out makes the run `errored`. */
|
|
110
|
+
run(run: ScheduledRunContext): unknown;
|
|
111
|
+
/**
|
|
112
|
+
* Receives each run's outcome at least once. Returning acknowledges it and
|
|
113
|
+
* deletes the run's row; throwing retries it with `outcomeRetries`.
|
|
114
|
+
*/
|
|
115
|
+
onOutcome(run: ScheduledOutcomeDelivery, outcome: ScheduledRunOutcome): unknown;
|
|
116
|
+
/** Runs in flight at once; later runs wait durably in order. Defaults to 10. */
|
|
117
|
+
maxConcurrentRuns?: number;
|
|
118
|
+
/** Maximum duration of one run. Defaults to 15 minutes. */
|
|
119
|
+
runTimeoutMs?: number;
|
|
120
|
+
/** Maximum duration of one `onOutcome` call. Defaults to 60 seconds. */
|
|
121
|
+
outcomeTimeoutMs?: number;
|
|
122
|
+
/** `onOutcome` retries. `maxAttempts` defaults to 10, counting the first. */
|
|
123
|
+
outcomeRetries?: DurabilityRetryOptions;
|
|
124
|
+
onLifecycleEvent?: (event: DurabilityScheduleEvent) => void | Promise<void>;
|
|
125
|
+
};
|
|
126
|
+
/**
|
|
127
|
+
* Experimental. One recurring schedule per Durable Object whose ticks start
|
|
128
|
+
* individually tracked, overlapping runs and report each run's outcome once,
|
|
129
|
+
* keeping a run's row only until its outcome is delivered.
|
|
130
|
+
*
|
|
131
|
+
* A tick inserts its run in the transaction that advances the stored next
|
|
132
|
+
* tick, so a tick fires at most once without retaining finished runs. Missed
|
|
133
|
+
* ticks collapse into one run for the earliest missed time.
|
|
134
|
+
*/
|
|
135
|
+
export declare class DurabilitySchedule {
|
|
136
|
+
#private;
|
|
137
|
+
constructor(config: DurabilityScheduleConfig);
|
|
138
|
+
static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
|
|
139
|
+
alarm(info?: AlarmInvocationInfo): Promise<void>;
|
|
140
|
+
/** The stored schedule, or `undefined` when none is set or it was cancelled. */
|
|
141
|
+
get(): ScheduleState | undefined;
|
|
142
|
+
/**
|
|
143
|
+
* Stores the schedule and its next tick when `version` is higher than the
|
|
144
|
+
* stored one, and resolves `true` when it did. A lower version is ignored; the
|
|
145
|
+
* same version changes nothing, keeping its stored jitter, but re-arms the
|
|
146
|
+
* alarm if it was lost.
|
|
147
|
+
*/
|
|
148
|
+
set(definition: ScheduleDefinition): Promise<boolean>;
|
|
149
|
+
/**
|
|
150
|
+
* Stops future ticks and resolves `true` when a schedule was live. Runs
|
|
151
|
+
* already due or running still finish and report. With `version`, the
|
|
152
|
+
* cancellation is ignored when the stored version is higher, and is
|
|
153
|
+
* otherwise recorded so a later `set` of that version or lower is ignored.
|
|
154
|
+
*/
|
|
155
|
+
cancel(version?: number): Promise<boolean>;
|
|
156
|
+
}
|
|
157
|
+
export {};
|