durability 2.1.0 → 3.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 +300 -116
- package/dist/durability-alarms.d.ts +90 -0
- package/dist/durability-alarms.js +165 -0
- package/dist/durability.d.ts +158 -0
- package/dist/durability.js +260 -0
- package/dist/errors.d.ts +83 -0
- package/dist/errors.js +184 -0
- package/dist/fanout.d.ts +61 -0
- package/dist/fanout.js +528 -0
- package/dist/index.d.ts +10 -435
- package/dist/index.js +7 -1420
- package/dist/kv-storage.d.ts +2 -0
- package/dist/kv-storage.js +421 -0
- package/dist/lifecycle.d.ts +70 -0
- package/dist/lifecycle.js +36 -0
- package/dist/load.d.ts +40 -0
- package/dist/load.js +68 -0
- package/dist/migrations.d.ts +50 -0
- package/dist/migrations.js +379 -0
- package/dist/policy.d.ts +74 -0
- package/dist/policy.js +49 -0
- package/dist/routing-client.d.ts +28 -0
- package/dist/routing-client.js +109 -0
- package/dist/routing.d.ts +33 -0
- package/dist/routing.js +58 -0
- package/dist/scheduler.d.ts +149 -0
- package/dist/scheduler.js +424 -0
- package/dist/serialization.d.ts +2 -0
- package/dist/serialization.js +13 -0
- package/dist/sqlite-storage.d.ts +2 -0
- package/dist/sqlite-storage.js +251 -0
- package/dist/storage.d.ts +134 -0
- package/dist/storage.js +69 -0
- package/dist/stored-message.d.ts +29 -0
- package/dist/stored-message.js +1 -0
- package/package.json +7 -3
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { alarmRowSchema, callRowSchema, deliveryRowSchema, fanoutMessageRowSchema, } from './storage.js';
|
|
3
|
+
const callTable = {
|
|
4
|
+
table: 'durability_calls',
|
|
5
|
+
key: 'id',
|
|
6
|
+
schema: callRowSchema,
|
|
7
|
+
columns: callRowSchema.keyof().options,
|
|
8
|
+
};
|
|
9
|
+
const alarmTable = {
|
|
10
|
+
table: 'durability_alarms',
|
|
11
|
+
key: 'name',
|
|
12
|
+
schema: alarmRowSchema,
|
|
13
|
+
columns: alarmRowSchema.keyof().options,
|
|
14
|
+
};
|
|
15
|
+
const deliveryTable = {
|
|
16
|
+
table: 'durability_fanout_deliveries',
|
|
17
|
+
key: 'id',
|
|
18
|
+
schema: deliveryRowSchema,
|
|
19
|
+
columns: deliveryRowSchema.keyof().options,
|
|
20
|
+
dueOrder: 'attempt ASC, seq ASC',
|
|
21
|
+
};
|
|
22
|
+
const attemptRowSchema = z.object({
|
|
23
|
+
attempt: z.number().int().nonnegative(),
|
|
24
|
+
});
|
|
25
|
+
const countRowSchema = z.object({ count: z.number().int().nonnegative() });
|
|
26
|
+
const messageKeyRowSchema = z.object({ message_key: z.string() });
|
|
27
|
+
const messageCountRowSchema = z.object({
|
|
28
|
+
message_key: z.string(),
|
|
29
|
+
count: z.number().int().positive(),
|
|
30
|
+
});
|
|
31
|
+
const seqRowSchema = z.object({ seq: z.number().int().nonnegative() });
|
|
32
|
+
const definedEntries = (patch) => Object.entries(patch).filter((entry) => entry[1] !== undefined);
|
|
33
|
+
class SqliteTable {
|
|
34
|
+
constructor(sql, spec, atomically) {
|
|
35
|
+
this.sql = sql;
|
|
36
|
+
this.spec = spec;
|
|
37
|
+
this.atomically = atomically;
|
|
38
|
+
}
|
|
39
|
+
async get(key) {
|
|
40
|
+
return this.rows(`SELECT * FROM ${this.spec.table} WHERE ${this.spec.key} = ? LIMIT 1`, key)[0];
|
|
41
|
+
}
|
|
42
|
+
async listDue(now, limit) {
|
|
43
|
+
return this.rows(`SELECT * FROM ${this.spec.table}
|
|
44
|
+
WHERE status = 'pending' AND next_attempt_at <= ?
|
|
45
|
+
ORDER BY ${this.spec.dueOrder ?? 'next_attempt_at ASC'}
|
|
46
|
+
LIMIT ?`, now, limit);
|
|
47
|
+
}
|
|
48
|
+
async nextPendingAt() {
|
|
49
|
+
return this.rows(`SELECT * FROM ${this.spec.table}
|
|
50
|
+
WHERE status = 'pending'
|
|
51
|
+
ORDER BY next_attempt_at ASC
|
|
52
|
+
LIMIT 1`)[0]?.next_attempt_at;
|
|
53
|
+
}
|
|
54
|
+
async insert(row) {
|
|
55
|
+
const { table, key, columns } = this.spec;
|
|
56
|
+
return this.changed(`INSERT INTO ${table} (${columns.join(', ')})
|
|
57
|
+
VALUES (${columns.map(() => '?').join(', ')})
|
|
58
|
+
ON CONFLICT(${key}) DO NOTHING
|
|
59
|
+
RETURNING ${key}`, ...this.values(row));
|
|
60
|
+
}
|
|
61
|
+
async upsert(row) {
|
|
62
|
+
const { table, key, columns } = this.spec;
|
|
63
|
+
const replacements = columns
|
|
64
|
+
.filter((column) => column !== key)
|
|
65
|
+
.map((column) => `${column} = excluded.${column}`);
|
|
66
|
+
this.sql.exec(`INSERT INTO ${table} (${columns.join(', ')})
|
|
67
|
+
VALUES (${columns.map(() => '?').join(', ')})
|
|
68
|
+
ON CONFLICT(${key}) DO UPDATE SET ${replacements.join(', ')}`, ...this.values(row));
|
|
69
|
+
}
|
|
70
|
+
async claimAttempt(key, generation, maxAttempts) {
|
|
71
|
+
return attemptRowSchema.optional().parse(this.sql
|
|
72
|
+
.exec(`UPDATE ${this.spec.table}
|
|
73
|
+
SET attempt = attempt + 1
|
|
74
|
+
WHERE ${this.spec.key} = ? AND generation_id = ?
|
|
75
|
+
AND status = 'pending' AND attempt < ?
|
|
76
|
+
RETURNING attempt`, key, generation, maxAttempts)
|
|
77
|
+
.toArray()[0])?.attempt;
|
|
78
|
+
}
|
|
79
|
+
async settle(key, generation, attempt, patch) {
|
|
80
|
+
return this.update(key, generation, '=', attempt, patch);
|
|
81
|
+
}
|
|
82
|
+
async exhaust(key, generation, maxAttempts, patch) {
|
|
83
|
+
return this.update(key, generation, '>=', maxAttempts, patch);
|
|
84
|
+
}
|
|
85
|
+
async remove(key, generation, attempt) {
|
|
86
|
+
return this.changed(`DELETE FROM ${this.spec.table}
|
|
87
|
+
WHERE ${this.spec.key} = ? AND generation_id = ?
|
|
88
|
+
AND status = 'pending' AND attempt = ?
|
|
89
|
+
RETURNING ${this.spec.key}`, key, generation, attempt);
|
|
90
|
+
}
|
|
91
|
+
async deleteCreatedBefore(before) {
|
|
92
|
+
return this.atomically((sql) => {
|
|
93
|
+
const { count } = countRowSchema.parse(sql
|
|
94
|
+
.exec(`SELECT COUNT(*) AS count FROM ${this.spec.table} WHERE created_at < ?`, before)
|
|
95
|
+
.toArray()[0]);
|
|
96
|
+
sql.exec(`DELETE FROM ${this.spec.table} WHERE created_at < ?`, before);
|
|
97
|
+
return count;
|
|
98
|
+
});
|
|
99
|
+
}
|
|
100
|
+
update(key, generation, attemptOperator, attemptBound, patch) {
|
|
101
|
+
const entries = definedEntries(patch);
|
|
102
|
+
const unknown = entries
|
|
103
|
+
.map(([column]) => column)
|
|
104
|
+
.filter((column) => !this.spec.columns.includes(column));
|
|
105
|
+
if (unknown.length > 0) {
|
|
106
|
+
throw new Error(`Unknown ${this.spec.table} columns: ${unknown.join(', ')}`);
|
|
107
|
+
}
|
|
108
|
+
return this.changed(`UPDATE ${this.spec.table}
|
|
109
|
+
SET ${entries.map(([column]) => `${column} = ?`).join(', ')}
|
|
110
|
+
WHERE ${this.spec.key} = ? AND generation_id = ?
|
|
111
|
+
AND status = 'pending' AND attempt ${attemptOperator} ?
|
|
112
|
+
RETURNING ${this.spec.key}`, ...entries.map(([, value]) => value), key, generation, attemptBound);
|
|
113
|
+
}
|
|
114
|
+
values(row) {
|
|
115
|
+
// Rows are schema-validated, so every column is present; `?? null` only satisfies the index type.
|
|
116
|
+
return this.spec.columns.map((column) => row[column] ?? null);
|
|
117
|
+
}
|
|
118
|
+
rows(query, ...bindings) {
|
|
119
|
+
return this.spec.schema
|
|
120
|
+
.array()
|
|
121
|
+
.parse(this.sql.exec(query, ...bindings).toArray());
|
|
122
|
+
}
|
|
123
|
+
changed(query, ...bindings) {
|
|
124
|
+
return this.sql.exec(query, ...bindings).toArray().length > 0;
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
class SqliteDeliveryTable extends SqliteTable {
|
|
128
|
+
constructor(sql, atomically) {
|
|
129
|
+
super(sql, deliveryTable, atomically);
|
|
130
|
+
}
|
|
131
|
+
async nextSeq() {
|
|
132
|
+
return this.atomically((sql) => seqRowSchema.parse(sql
|
|
133
|
+
.exec(`UPDATE durability_fanout_seq
|
|
134
|
+
SET next_seq = next_seq + 1
|
|
135
|
+
WHERE id = 1
|
|
136
|
+
RETURNING next_seq - 1 AS seq`)
|
|
137
|
+
.toArray()[0]).seq);
|
|
138
|
+
}
|
|
139
|
+
async getMessage(key) {
|
|
140
|
+
return fanoutMessageRowSchema
|
|
141
|
+
.optional()
|
|
142
|
+
.parse(this.sql
|
|
143
|
+
.exec('SELECT * FROM durability_fanout_messages WHERE key = ? LIMIT 1', key)
|
|
144
|
+
.toArray()[0]);
|
|
145
|
+
}
|
|
146
|
+
async insertMessage(row) {
|
|
147
|
+
const columns = fanoutMessageRowSchema.keyof().options;
|
|
148
|
+
return this.changed(`INSERT INTO durability_fanout_messages (${columns.join(', ')})
|
|
149
|
+
VALUES (${columns.map(() => '?').join(', ')})
|
|
150
|
+
ON CONFLICT(key) DO NOTHING
|
|
151
|
+
RETURNING key`, row.key, row.id, row.payload, row.targets, row.remaining, row.seq, row.created_at, row.generation_id);
|
|
152
|
+
}
|
|
153
|
+
async listTargets() {
|
|
154
|
+
return z
|
|
155
|
+
.string()
|
|
156
|
+
.array()
|
|
157
|
+
.parse(this.sql
|
|
158
|
+
.exec(`SELECT DISTINCT target_id FROM durability_fanout_deliveries
|
|
159
|
+
ORDER BY target_id`)
|
|
160
|
+
.toArray()
|
|
161
|
+
.map((row) => row['target_id']));
|
|
162
|
+
}
|
|
163
|
+
async listDueForTarget(target, now, limit) {
|
|
164
|
+
return this.rows(`SELECT * FROM durability_fanout_deliveries
|
|
165
|
+
WHERE target_id = ? AND status = 'pending'
|
|
166
|
+
AND next_attempt_at <= ?
|
|
167
|
+
ORDER BY CASE WHEN attempt = 0 THEN 0 ELSE 1 END ASC, seq ASC
|
|
168
|
+
LIMIT ?`, target, now, limit);
|
|
169
|
+
}
|
|
170
|
+
async pendingCount() {
|
|
171
|
+
return countRowSchema.parse(this.sql
|
|
172
|
+
.exec(`SELECT COUNT(*) AS count FROM durability_fanout_deliveries
|
|
173
|
+
WHERE status = 'pending'`)
|
|
174
|
+
.toArray()[0]).count;
|
|
175
|
+
}
|
|
176
|
+
async listDue(now, limit) {
|
|
177
|
+
return this.rows(`SELECT * FROM durability_fanout_deliveries
|
|
178
|
+
WHERE status = 'pending' AND next_attempt_at <= ?
|
|
179
|
+
ORDER BY CASE WHEN attempt = 0 THEN 0 ELSE 1 END ASC, seq ASC
|
|
180
|
+
LIMIT ?`, now, limit);
|
|
181
|
+
}
|
|
182
|
+
async nextPendingAt() {
|
|
183
|
+
return this.rows(`SELECT * FROM durability_fanout_deliveries
|
|
184
|
+
WHERE status = 'pending'
|
|
185
|
+
ORDER BY next_attempt_at ASC
|
|
186
|
+
LIMIT 1`)[0]?.next_attempt_at;
|
|
187
|
+
}
|
|
188
|
+
async remove(key, generation, attempt) {
|
|
189
|
+
return this.atomically((sql) => {
|
|
190
|
+
const messageKey = messageKeyRowSchema.optional().parse(sql
|
|
191
|
+
.exec(`DELETE FROM durability_fanout_deliveries
|
|
192
|
+
WHERE id = ? AND generation_id = ?
|
|
193
|
+
AND status = 'pending' AND attempt = ?
|
|
194
|
+
RETURNING message_key`, key, generation, attempt)
|
|
195
|
+
.toArray()[0])?.message_key;
|
|
196
|
+
if (messageKey === undefined) {
|
|
197
|
+
return false;
|
|
198
|
+
}
|
|
199
|
+
sql.exec(`UPDATE durability_fanout_messages
|
|
200
|
+
SET remaining = remaining - 1
|
|
201
|
+
WHERE key = ?`, messageKey);
|
|
202
|
+
sql.exec(`DELETE FROM durability_fanout_messages
|
|
203
|
+
WHERE key = ? AND remaining = 0`, messageKey);
|
|
204
|
+
return true;
|
|
205
|
+
});
|
|
206
|
+
}
|
|
207
|
+
async deleteCreatedBefore(before) {
|
|
208
|
+
return this.atomically((sql) => {
|
|
209
|
+
const messageCounts = messageCountRowSchema.array().parse(sql
|
|
210
|
+
.exec(`SELECT message_key, COUNT(*) AS count
|
|
211
|
+
FROM durability_fanout_deliveries
|
|
212
|
+
WHERE created_at < ?
|
|
213
|
+
GROUP BY message_key`, before)
|
|
214
|
+
.toArray());
|
|
215
|
+
if (messageCounts.length === 0) {
|
|
216
|
+
return 0;
|
|
217
|
+
}
|
|
218
|
+
const { count } = countRowSchema.parse(sql
|
|
219
|
+
.exec(`SELECT COUNT(*) AS count FROM durability_fanout_deliveries
|
|
220
|
+
WHERE created_at < ?`, before)
|
|
221
|
+
.toArray()[0]);
|
|
222
|
+
sql.exec('DELETE FROM durability_fanout_deliveries WHERE created_at < ?', before);
|
|
223
|
+
for (const { message_key: messageKey, count: removed } of messageCounts) {
|
|
224
|
+
sql.exec(`UPDATE durability_fanout_messages
|
|
225
|
+
SET remaining = remaining - ?
|
|
226
|
+
WHERE key = ?`, removed, messageKey);
|
|
227
|
+
sql.exec(`DELETE FROM durability_fanout_messages
|
|
228
|
+
WHERE key = ? AND remaining = 0`, messageKey);
|
|
229
|
+
}
|
|
230
|
+
return count;
|
|
231
|
+
});
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
class SqliteSession {
|
|
235
|
+
constructor(sql, physicalAlarm, atomically) {
|
|
236
|
+
this.physicalAlarm = physicalAlarm;
|
|
237
|
+
this.calls = new SqliteTable(sql, callTable, atomically);
|
|
238
|
+
this.alarms = new SqliteTable(sql, alarmTable, atomically);
|
|
239
|
+
this.deliveries = new SqliteDeliveryTable(sql, atomically);
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
export const createSqliteDurabilityStorage = (storage) => {
|
|
243
|
+
const transaction = (callback) => storage.transaction((durableTransaction) => callback(new SqliteSession(storage.sql, durableTransaction, (run) => Promise.resolve(run(storage.sql)))));
|
|
244
|
+
const session = new SqliteSession(storage.sql, storage, (run) => storage.transaction(() => Promise.resolve(run(storage.sql))));
|
|
245
|
+
return {
|
|
246
|
+
calls: session.calls,
|
|
247
|
+
alarms: session.alarms,
|
|
248
|
+
deliveries: session.deliveries,
|
|
249
|
+
transaction,
|
|
250
|
+
};
|
|
251
|
+
};
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
export declare const callRowSchema: z.ZodObject<{
|
|
3
|
+
id: z.ZodString;
|
|
4
|
+
operation: z.ZodString;
|
|
5
|
+
payload: z.ZodString;
|
|
6
|
+
status: z.ZodEnum<{
|
|
7
|
+
completed: "completed";
|
|
8
|
+
failed: "failed";
|
|
9
|
+
pending: "pending";
|
|
10
|
+
}>;
|
|
11
|
+
result: z.ZodNullable<z.ZodString>;
|
|
12
|
+
attempt: z.ZodNumber;
|
|
13
|
+
next_attempt_at: z.ZodNumber;
|
|
14
|
+
last_error: z.ZodNullable<z.ZodString>;
|
|
15
|
+
last_error_name: z.ZodNullable<z.ZodString>;
|
|
16
|
+
completed_at: z.ZodNullable<z.ZodNumber>;
|
|
17
|
+
created_at: z.ZodNumber;
|
|
18
|
+
generation_id: z.ZodString;
|
|
19
|
+
}, z.core.$strip>;
|
|
20
|
+
export type CallRow = z.infer<typeof callRowSchema>;
|
|
21
|
+
export declare const alarmRowSchema: z.ZodObject<{
|
|
22
|
+
name: z.ZodString;
|
|
23
|
+
generation_id: z.ZodString;
|
|
24
|
+
status: z.ZodEnum<{
|
|
25
|
+
failed: "failed";
|
|
26
|
+
pending: "pending";
|
|
27
|
+
}>;
|
|
28
|
+
scheduled_at: z.ZodNumber;
|
|
29
|
+
next_attempt_at: z.ZodNumber;
|
|
30
|
+
attempt: z.ZodNumber;
|
|
31
|
+
last_error: z.ZodNullable<z.ZodString>;
|
|
32
|
+
last_error_name: z.ZodNullable<z.ZodString>;
|
|
33
|
+
created_at: z.ZodNumber;
|
|
34
|
+
}, z.core.$strip>;
|
|
35
|
+
export type AlarmRow = z.infer<typeof alarmRowSchema>;
|
|
36
|
+
export declare const fanoutMessageRowSchema: z.ZodObject<{
|
|
37
|
+
key: z.ZodString;
|
|
38
|
+
id: z.ZodString;
|
|
39
|
+
payload: z.ZodString;
|
|
40
|
+
targets: z.ZodString;
|
|
41
|
+
remaining: z.ZodNumber;
|
|
42
|
+
seq: z.ZodNumber;
|
|
43
|
+
created_at: z.ZodNumber;
|
|
44
|
+
generation_id: z.ZodString;
|
|
45
|
+
}, z.core.$strip>;
|
|
46
|
+
export type FanoutMessageRow = z.infer<typeof fanoutMessageRowSchema>;
|
|
47
|
+
export declare const deliveryRowSchema: z.ZodObject<{
|
|
48
|
+
id: z.ZodString;
|
|
49
|
+
message_key: z.ZodString;
|
|
50
|
+
target_id: z.ZodString;
|
|
51
|
+
seq: z.ZodNumber;
|
|
52
|
+
status: z.ZodLiteral<"pending">;
|
|
53
|
+
phase: z.ZodEnum<{
|
|
54
|
+
delivery: "delivery";
|
|
55
|
+
dead_letter: "dead_letter";
|
|
56
|
+
}>;
|
|
57
|
+
attempt: z.ZodNumber;
|
|
58
|
+
next_attempt_at: z.ZodNumber;
|
|
59
|
+
last_error: z.ZodNullable<z.ZodString>;
|
|
60
|
+
last_error_name: z.ZodNullable<z.ZodString>;
|
|
61
|
+
created_at: z.ZodNumber;
|
|
62
|
+
generation_id: z.ZodString;
|
|
63
|
+
dead_lettered_at: z.ZodNullable<z.ZodNumber>;
|
|
64
|
+
dead_letter_reason: z.ZodNullable<z.ZodEnum<{
|
|
65
|
+
explicit: "explicit";
|
|
66
|
+
exhausted: "exhausted";
|
|
67
|
+
}>>;
|
|
68
|
+
}, z.core.$strip>;
|
|
69
|
+
export type DeliveryRow = z.infer<typeof deliveryRowSchema>;
|
|
70
|
+
export type ColumnValue = string | number | null;
|
|
71
|
+
export type DurableRecord = Record<string, ColumnValue> & {
|
|
72
|
+
generation_id: string;
|
|
73
|
+
status: string;
|
|
74
|
+
attempt: number;
|
|
75
|
+
next_attempt_at: number;
|
|
76
|
+
created_at: number;
|
|
77
|
+
};
|
|
78
|
+
/** Failure columns shared by every record kind, so generic code can settle without knowing the row. */
|
|
79
|
+
export type FailurePatch = {
|
|
80
|
+
status: 'pending' | 'failed';
|
|
81
|
+
next_attempt_at?: number;
|
|
82
|
+
last_error: string;
|
|
83
|
+
last_error_name: string;
|
|
84
|
+
};
|
|
85
|
+
/** Columns a settlement may change; identity, generation, attempt, and creation time are fixed. */
|
|
86
|
+
export type RecordPatch<Row extends DurableRecord> = FailurePatch | Partial<Omit<Row, 'id' | 'name' | 'generation_id' | 'attempt' | 'created_at'>>;
|
|
87
|
+
/**
|
|
88
|
+
* Compare-and-set access to one kind of durable record.
|
|
89
|
+
*
|
|
90
|
+
* Every mutation is conditional on the record's generation and attempt so a
|
|
91
|
+
* stale execution can never overwrite a replacement or a later attempt.
|
|
92
|
+
*/
|
|
93
|
+
export interface RecordStore<Row extends DurableRecord> {
|
|
94
|
+
get(key: string): Promise<Row | undefined>;
|
|
95
|
+
listDue(now: number, limit: number): Promise<Row[]>;
|
|
96
|
+
nextPendingAt(): Promise<number | undefined>;
|
|
97
|
+
insert(row: Row): Promise<boolean>;
|
|
98
|
+
upsert(row: Row): Promise<void>;
|
|
99
|
+
claimAttempt(key: string, generation: string, maxAttempts: number): Promise<number | undefined>;
|
|
100
|
+
settle(key: string, generation: string, attempt: number, patch: RecordPatch<Row>): Promise<boolean>;
|
|
101
|
+
exhaust(key: string, generation: string, maxAttempts: number, patch: RecordPatch<Row>): Promise<boolean>;
|
|
102
|
+
remove(key: string, generation: string, attempt: number): Promise<boolean>;
|
|
103
|
+
/**
|
|
104
|
+
* Deletes records created before the timestamp and returns how many were
|
|
105
|
+
* removed. Backends may delete a bounded batch; callers loop until zero.
|
|
106
|
+
*/
|
|
107
|
+
deleteCreatedBefore(before: number): Promise<number>;
|
|
108
|
+
}
|
|
109
|
+
export type PhysicalAlarm = Pick<DurableObjectTransaction, 'getAlarm' | 'setAlarm' | 'deleteAlarm'>;
|
|
110
|
+
export interface DeliveryStore extends RecordStore<DeliveryRow> {
|
|
111
|
+
/** Allocates a sequence number from a durable counter, including an empty queue. */
|
|
112
|
+
nextSeq(): Promise<number>;
|
|
113
|
+
getMessage(key: string): Promise<FanoutMessageRow | undefined>;
|
|
114
|
+
insertMessage(row: FanoutMessageRow): Promise<boolean>;
|
|
115
|
+
/** Returns targets represented by persisted delivery rows. */
|
|
116
|
+
listTargets(): Promise<string[]>;
|
|
117
|
+
listDueForTarget(target: string, now: number, limit: number): Promise<DeliveryRow[]>;
|
|
118
|
+
/** Returns the exact number of active delivery children. */
|
|
119
|
+
pendingCount(): Promise<number>;
|
|
120
|
+
}
|
|
121
|
+
export type RecordStores = {
|
|
122
|
+
calls: RecordStore<CallRow>;
|
|
123
|
+
alarms: RecordStore<AlarmRow>;
|
|
124
|
+
deliveries: DeliveryStore;
|
|
125
|
+
};
|
|
126
|
+
export type RecordKind = keyof RecordStores;
|
|
127
|
+
export type DurabilityStorageTransaction = RecordStores & {
|
|
128
|
+
physicalAlarm: PhysicalAlarm;
|
|
129
|
+
};
|
|
130
|
+
export type DurabilityStorage = RecordStores & {
|
|
131
|
+
transaction<T>(callback: (transaction: DurabilityStorageTransaction) => Promise<T>): Promise<T>;
|
|
132
|
+
};
|
|
133
|
+
/** Points the shared physical alarm at the earliest pending record among the given kinds. */
|
|
134
|
+
export declare const reconcilePhysicalAlarm: (transaction: DurabilityStorageTransaction, kinds: readonly RecordKind[]) => Promise<void>;
|
package/dist/storage.js
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
export const callRowSchema = z.object({
|
|
3
|
+
id: z.string(),
|
|
4
|
+
operation: z.string(),
|
|
5
|
+
payload: z.string(),
|
|
6
|
+
status: z.enum(['pending', 'completed', 'failed']),
|
|
7
|
+
result: z.string().nullable(),
|
|
8
|
+
attempt: z.number().int().nonnegative(),
|
|
9
|
+
next_attempt_at: z.number().int().nonnegative(),
|
|
10
|
+
last_error: z.string().nullable(),
|
|
11
|
+
last_error_name: z.string().nullable(),
|
|
12
|
+
completed_at: z.number().int().nonnegative().nullable(),
|
|
13
|
+
created_at: z.number().int().nonnegative(),
|
|
14
|
+
generation_id: z.string(),
|
|
15
|
+
});
|
|
16
|
+
export const alarmRowSchema = z.object({
|
|
17
|
+
name: z.string(),
|
|
18
|
+
generation_id: z.string(),
|
|
19
|
+
status: z.enum(['pending', 'failed']),
|
|
20
|
+
scheduled_at: z.number().int().nonnegative(),
|
|
21
|
+
next_attempt_at: z.number().int().nonnegative(),
|
|
22
|
+
attempt: z.number().int().nonnegative(),
|
|
23
|
+
last_error: z.string().nullable(),
|
|
24
|
+
last_error_name: z.string().nullable(),
|
|
25
|
+
created_at: z.number().int().nonnegative(),
|
|
26
|
+
});
|
|
27
|
+
export const fanoutMessageRowSchema = z.object({
|
|
28
|
+
key: z.string(),
|
|
29
|
+
id: z.string(),
|
|
30
|
+
payload: z.string(),
|
|
31
|
+
targets: z.string(),
|
|
32
|
+
remaining: z.number().int().nonnegative(),
|
|
33
|
+
seq: z.number().int().nonnegative(),
|
|
34
|
+
created_at: z.number().int().nonnegative(),
|
|
35
|
+
generation_id: z.string(),
|
|
36
|
+
});
|
|
37
|
+
export const deliveryRowSchema = z.object({
|
|
38
|
+
id: z.string(),
|
|
39
|
+
message_key: z.string(),
|
|
40
|
+
target_id: z.string(),
|
|
41
|
+
seq: z.number().int().nonnegative(),
|
|
42
|
+
status: z.literal('pending'),
|
|
43
|
+
phase: z.enum(['delivery', 'dead_letter']),
|
|
44
|
+
attempt: z.number().int().nonnegative(),
|
|
45
|
+
next_attempt_at: z.number().int().nonnegative(),
|
|
46
|
+
last_error: z.string().nullable(),
|
|
47
|
+
last_error_name: z.string().nullable(),
|
|
48
|
+
created_at: z.number().int().nonnegative(),
|
|
49
|
+
generation_id: z.string(),
|
|
50
|
+
dead_lettered_at: z.number().int().nonnegative().nullable(),
|
|
51
|
+
dead_letter_reason: z.enum(['explicit', 'exhausted']).nullable(),
|
|
52
|
+
});
|
|
53
|
+
/** Points the shared physical alarm at the earliest pending record among the given kinds. */
|
|
54
|
+
export const reconcilePhysicalAlarm = async (transaction, kinds) => {
|
|
55
|
+
const candidates = await Promise.all(kinds.map((kind) => transaction[kind].nextPendingAt()));
|
|
56
|
+
const scheduled = candidates.filter((value) => value !== undefined);
|
|
57
|
+
const nextAlarmAt = scheduled.length === 0 ? undefined : Math.min(...scheduled);
|
|
58
|
+
const currentAlarm = await transaction.physicalAlarm.getAlarm();
|
|
59
|
+
if (nextAlarmAt === undefined) {
|
|
60
|
+
if (currentAlarm !== null) {
|
|
61
|
+
await transaction.physicalAlarm.deleteAlarm();
|
|
62
|
+
}
|
|
63
|
+
return;
|
|
64
|
+
}
|
|
65
|
+
const target = Math.max(nextAlarmAt, Date.now());
|
|
66
|
+
if (currentAlarm !== target) {
|
|
67
|
+
await transaction.physicalAlarm.setAlarm(target);
|
|
68
|
+
}
|
|
69
|
+
};
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { SerializedError } from './errors.js';
|
|
2
|
+
/**
|
|
3
|
+
* One message as handed to a storage destination. Archive and dead-letter
|
|
4
|
+
* writes share this envelope; only `failure` distinguishes them.
|
|
5
|
+
*/
|
|
6
|
+
export type StoredMessage<Body = unknown> = {
|
|
7
|
+
/** Unique to this registration and target; stable across delivery attempts. */
|
|
8
|
+
id: string;
|
|
9
|
+
messageId: string;
|
|
10
|
+
target: string;
|
|
11
|
+
body: Body;
|
|
12
|
+
enqueuedAt: number;
|
|
13
|
+
storedAt: number;
|
|
14
|
+
attempts: number;
|
|
15
|
+
/** Present only when a target gave up on this message. */
|
|
16
|
+
failure?: {
|
|
17
|
+
reason: 'exhausted' | 'explicit';
|
|
18
|
+
error: SerializedError | null;
|
|
19
|
+
} | undefined;
|
|
20
|
+
};
|
|
21
|
+
/**
|
|
22
|
+
* Everything a storage destination must provide. Fanout only ever writes, so
|
|
23
|
+
* any function is a valid storage target or dead-letter destination.
|
|
24
|
+
*
|
|
25
|
+
* Key each entry by `id` and refuse to overwrite it, so a retried write is
|
|
26
|
+
* idempotent and a redrive removes exactly what it re-enqueued. Reading entries
|
|
27
|
+
* back for replay or redrive is the application's concern.
|
|
28
|
+
*/
|
|
29
|
+
export type MessageWrite<Body = unknown> = (message: StoredMessage<Body>) => Promise<void>;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "durability",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "3.0.0",
|
|
4
4
|
"description": "Alarm-backed durable operations for Cloudflare Durable Objects",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "ISC",
|
|
@@ -15,6 +15,10 @@
|
|
|
15
15
|
"types": "./dist/index.d.ts",
|
|
16
16
|
"import": "./dist/index.js"
|
|
17
17
|
},
|
|
18
|
+
"./routing": {
|
|
19
|
+
"types": "./dist/routing.d.ts",
|
|
20
|
+
"import": "./dist/routing.js"
|
|
21
|
+
},
|
|
18
22
|
"./utils": {
|
|
19
23
|
"types": "./dist/utils.d.ts",
|
|
20
24
|
"import": "./dist/utils.js"
|
|
@@ -42,9 +46,9 @@
|
|
|
42
46
|
"workers"
|
|
43
47
|
],
|
|
44
48
|
"dependencies": {
|
|
45
|
-
"workers-qb": "1.11.2",
|
|
46
49
|
"zod": "^4.4.3",
|
|
47
|
-
"@durability/storage": "^0.1.1"
|
|
50
|
+
"@durability/storage": "^0.1.1",
|
|
51
|
+
"@durability/transforms": "^0.3.0"
|
|
48
52
|
},
|
|
49
53
|
"peerDependencies": {
|
|
50
54
|
"@cloudflare/workers-types": "^4.20260702.1"
|