durability 3.0.1 → 4.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 +400 -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 +33 -2
- package/dist/durability.js +126 -63
- package/dist/errors.d.ts +26 -0
- package/dist/errors.js +38 -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/serialization.d.ts +5 -0
- package/dist/serialization.js +16 -0
- 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 +19 -5
- 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/storage.d.ts
CHANGED
|
@@ -1,134 +1,45 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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;
|
|
1
|
+
/**
|
|
2
|
+
* A table of durable records: a primary key column plus `generation_id`,
|
|
3
|
+
* `status`, `attempt`, `next_attempt_at`, and `created_at`.
|
|
4
|
+
*/
|
|
5
|
+
export type DurableTable = {
|
|
6
|
+
name: string;
|
|
7
|
+
key: string;
|
|
77
8
|
};
|
|
78
|
-
/**
|
|
79
|
-
export type
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
last_error_name: string;
|
|
9
|
+
/** One attempt of one record generation. */
|
|
10
|
+
export type AttemptRef = {
|
|
11
|
+
key: string;
|
|
12
|
+
generation: string;
|
|
13
|
+
attempt: number;
|
|
84
14
|
};
|
|
85
|
-
/**
|
|
86
|
-
export
|
|
15
|
+
/** Starts the next attempt and returns its number, unless the generation is gone or out of attempts. */
|
|
16
|
+
export declare const claimAttempt: (sql: SqlStorage, table: DurableTable, key: string, generation: string, maxAttempts: number) => number | undefined;
|
|
87
17
|
/**
|
|
88
|
-
*
|
|
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.
|
|
18
|
+
* Applies `assignments` (a SQL `SET` list) to the record if the attempt still
|
|
19
|
+
* owns it, and reports whether it did.
|
|
92
20
|
*/
|
|
93
|
-
export
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
/**
|
|
104
|
-
|
|
105
|
-
|
|
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;
|
|
21
|
+
export declare const updateAttempt: (sql: SqlStorage, table: DurableTable, ref: AttemptRef, assignments: string, ...values: SqlStorageValue[]) => boolean;
|
|
22
|
+
/** Deletes the record if the attempt still owns it, and reports whether it did. */
|
|
23
|
+
export declare const deleteAttempt: (sql: SqlStorage, table: DurableTable, ref: AttemptRef) => boolean;
|
|
24
|
+
/** Fails a generation that has used every attempt and returns its attempt count. */
|
|
25
|
+
export declare const exhaustAttempts: (sql: SqlStorage, table: DurableTable, key: string, generation: string, maxAttempts: number, error: {
|
|
26
|
+
name: string;
|
|
27
|
+
message: string;
|
|
28
|
+
}) => number | undefined;
|
|
29
|
+
export type CreatedQuery = {
|
|
30
|
+
limit: number;
|
|
31
|
+
/** Opaque position from a previous page's `next`. */
|
|
32
|
+
after?: string | undefined;
|
|
33
|
+
status?: string | undefined;
|
|
34
|
+
name?: string | undefined;
|
|
125
35
|
};
|
|
126
|
-
export type
|
|
127
|
-
|
|
128
|
-
|
|
36
|
+
export type CreatedPage = {
|
|
37
|
+
rows: Record<string, SqlStorageValue>[];
|
|
38
|
+
/** Present only when more records follow. */
|
|
39
|
+
next?: string;
|
|
129
40
|
};
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
export declare const
|
|
41
|
+
/**
|
|
42
|
+
* Lists records in creation order, then by key, filtered by status and by the
|
|
43
|
+
* value of `nameColumn`.
|
|
44
|
+
*/
|
|
45
|
+
export declare const listCreated: (sql: SqlStorage, table: DurableTable, nameColumn: string, query: CreatedQuery) => CreatedPage;
|
package/dist/storage.js
CHANGED
|
@@ -1,73 +1,69 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
-
|
|
3
|
-
id: z.string(),
|
|
4
|
-
operation: z.string(),
|
|
5
|
-
payload: z.string(),
|
|
6
|
-
status: z.enum(['pending', 'completed', 'failed']),
|
|
7
|
-
result: z.string().nullable(),
|
|
2
|
+
const attemptRowSchema = z.object({
|
|
8
3
|
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
4
|
});
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
export const
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
/**
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
const
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
5
|
+
// Every write is conditional on the record's generation and pending status, so a
|
|
6
|
+
// stale execution can never overwrite a replacement or a later attempt.
|
|
7
|
+
const pendingGeneration = (table) => `${table.key} = ? AND generation_id = ? AND status = 'pending'`;
|
|
8
|
+
/** Starts the next attempt and returns its number, unless the generation is gone or out of attempts. */
|
|
9
|
+
export const claimAttempt = (sql, table, key, generation, maxAttempts) => attemptRowSchema.optional().parse(sql
|
|
10
|
+
.exec(`UPDATE ${table.name}
|
|
11
|
+
SET attempt = attempt + 1
|
|
12
|
+
WHERE ${pendingGeneration(table)} AND attempt < ?
|
|
13
|
+
RETURNING attempt`, key, generation, maxAttempts)
|
|
14
|
+
.toArray()[0])?.attempt;
|
|
15
|
+
/**
|
|
16
|
+
* Applies `assignments` (a SQL `SET` list) to the record if the attempt still
|
|
17
|
+
* owns it, and reports whether it did.
|
|
18
|
+
*/
|
|
19
|
+
export const updateAttempt = (sql, table, ref, assignments, ...values) => sql
|
|
20
|
+
.exec(`UPDATE ${table.name}
|
|
21
|
+
SET ${assignments}
|
|
22
|
+
WHERE ${pendingGeneration(table)} AND attempt = ?
|
|
23
|
+
RETURNING ${table.key}`, ...values, ref.key, ref.generation, ref.attempt)
|
|
24
|
+
.toArray().length > 0;
|
|
25
|
+
/** Deletes the record if the attempt still owns it, and reports whether it did. */
|
|
26
|
+
export const deleteAttempt = (sql, table, ref) => sql
|
|
27
|
+
.exec(`DELETE FROM ${table.name}
|
|
28
|
+
WHERE ${pendingGeneration(table)} AND attempt = ?
|
|
29
|
+
RETURNING ${table.key}`, ref.key, ref.generation, ref.attempt)
|
|
30
|
+
.toArray().length > 0;
|
|
31
|
+
/** Fails a generation that has used every attempt and returns its attempt count. */
|
|
32
|
+
export const exhaustAttempts = (sql, table, key, generation, maxAttempts, error) => attemptRowSchema.optional().parse(sql
|
|
33
|
+
.exec(`UPDATE ${table.name}
|
|
34
|
+
SET status = 'failed', last_error = ?, last_error_name = ?
|
|
35
|
+
WHERE ${pendingGeneration(table)} AND attempt >= ?
|
|
36
|
+
RETURNING attempt`, error.message, error.name, key, generation, maxAttempts)
|
|
37
|
+
.toArray()[0])?.attempt;
|
|
38
|
+
const createdCursorSchema = z.tuple([
|
|
39
|
+
z.number().int().nonnegative(),
|
|
40
|
+
z.string(),
|
|
41
|
+
]);
|
|
42
|
+
/**
|
|
43
|
+
* Lists records in creation order, then by key, filtered by status and by the
|
|
44
|
+
* value of `nameColumn`.
|
|
45
|
+
*/
|
|
46
|
+
export const listCreated = (sql, table, nameColumn, query) => {
|
|
47
|
+
const [createdAt, key] = query.after === undefined
|
|
48
|
+
? [-1, '']
|
|
49
|
+
: createdCursorSchema.parse(JSON.parse(query.after));
|
|
50
|
+
const status = query.status ?? null;
|
|
51
|
+
const name = query.name ?? null;
|
|
52
|
+
const found = sql
|
|
53
|
+
.exec(`SELECT * FROM ${table.name}
|
|
54
|
+
WHERE (? IS NULL OR status = ?)
|
|
55
|
+
AND (? IS NULL OR ${nameColumn} = ?)
|
|
56
|
+
AND (created_at > ? OR (created_at = ? AND ${table.key} > ?))
|
|
57
|
+
ORDER BY created_at ASC, ${table.key} ASC
|
|
58
|
+
LIMIT ?`, status, status, name, name, createdAt, createdAt, key, query.limit + 1)
|
|
59
|
+
.toArray();
|
|
60
|
+
const rows = found.slice(0, query.limit);
|
|
61
|
+
const last = rows[rows.length - 1];
|
|
62
|
+
if (found.length <= query.limit || !last) {
|
|
63
|
+
return { rows };
|
|
71
64
|
}
|
|
72
|
-
return
|
|
65
|
+
return {
|
|
66
|
+
rows,
|
|
67
|
+
next: JSON.stringify([last['created_at'], last[table.key]]),
|
|
68
|
+
};
|
|
73
69
|
};
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
/** Result types keyed by record name: operation, alarm name, or custom names. */
|
|
2
|
+
export type TrackedResults = Record<string, unknown>;
|
|
3
|
+
export type TrackedStatus = 'pending' | 'completed' | 'failed';
|
|
4
|
+
/**
|
|
5
|
+
* The persisted state of one tracked record. Finer outcomes, such as
|
|
6
|
+
* cancellation or expiry, are `failed` with a specific `error.name`.
|
|
7
|
+
*/
|
|
8
|
+
export type TrackedState<Result> = {
|
|
9
|
+
status: 'pending';
|
|
10
|
+
attempt?: number;
|
|
11
|
+
nextAttemptAt?: number;
|
|
12
|
+
lastError?: string | null;
|
|
13
|
+
} | {
|
|
14
|
+
status: 'completed';
|
|
15
|
+
result: Result;
|
|
16
|
+
} | {
|
|
17
|
+
status: 'failed';
|
|
18
|
+
attempt?: number;
|
|
19
|
+
error: {
|
|
20
|
+
name: string;
|
|
21
|
+
message: string;
|
|
22
|
+
};
|
|
23
|
+
};
|
|
24
|
+
export type Names<Results> = Extract<keyof Results, string>;
|
|
25
|
+
export type TrackedEntry<Name extends string, Result> = {
|
|
26
|
+
/** Unique within its source. */
|
|
27
|
+
id: string;
|
|
28
|
+
name: Name;
|
|
29
|
+
/** Opaque; changes when an id is reused for new work. */
|
|
30
|
+
generation: string;
|
|
31
|
+
createdAt: number;
|
|
32
|
+
state: TrackedState<Result>;
|
|
33
|
+
};
|
|
34
|
+
/** One record of a source, narrowed by `name` to that name's result type. */
|
|
35
|
+
export type TrackedRecord<Results extends TrackedResults> = {
|
|
36
|
+
[Name in Names<Results>]: TrackedEntry<Name, Results[Name]>;
|
|
37
|
+
}[Names<Results>];
|
|
38
|
+
export type TrackedQuery<Results extends TrackedResults> = {
|
|
39
|
+
limit: number;
|
|
40
|
+
/** Opaque position from a previous page. */
|
|
41
|
+
cursor?: string | undefined;
|
|
42
|
+
status?: TrackedStatus | undefined;
|
|
43
|
+
name?: Names<Results> | undefined;
|
|
44
|
+
};
|
|
45
|
+
export type TrackedPage<Results extends TrackedResults> = {
|
|
46
|
+
/** May hold fewer than `limit` records even when `cursor` is present. */
|
|
47
|
+
records: TrackedRecord<Results>[];
|
|
48
|
+
/** Present when more records may follow; omit it at the end. */
|
|
49
|
+
cursor?: string;
|
|
50
|
+
};
|
|
51
|
+
/**
|
|
52
|
+
* What a tracker reads from a source. New members are always optional, so
|
|
53
|
+
* custom sources keep compiling across releases.
|
|
54
|
+
*
|
|
55
|
+
* @experimental
|
|
56
|
+
*/
|
|
57
|
+
export type TrackedSource<Results extends TrackedResults> = {
|
|
58
|
+
get(id: string): Promise<TrackedRecord<Results> | undefined>;
|
|
59
|
+
list(query: TrackedQuery<Results>): Promise<TrackedPage<Results>>;
|
|
60
|
+
/**
|
|
61
|
+
* Calls `listener` after the record may have settled and returns an
|
|
62
|
+
* unsubscribe function. Pass the settled record when it can no longer be
|
|
63
|
+
* read, for example because success deletes it; otherwise pass nothing and
|
|
64
|
+
* the tracker re-reads. Without `watch`, `wait` re-reads at its timeout.
|
|
65
|
+
*/
|
|
66
|
+
watch?(id: string, listener: (settled?: TrackedRecord<Results>) => void): () => void;
|
|
67
|
+
};
|
|
68
|
+
export type UntypedRecord = TrackedEntry<string, unknown>;
|
|
69
|
+
/**
|
|
70
|
+
* Any source regardless of its result types. Written out structurally because
|
|
71
|
+
* `TrackedSource<R>` uses `keyof R`, which makes it invariant in `R`.
|
|
72
|
+
*/
|
|
73
|
+
export type UntypedSource = {
|
|
74
|
+
get(id: string): Promise<UntypedRecord | undefined>;
|
|
75
|
+
list(query: {
|
|
76
|
+
limit: number;
|
|
77
|
+
cursor?: string | undefined;
|
|
78
|
+
status?: TrackedStatus | undefined;
|
|
79
|
+
name?: string | undefined;
|
|
80
|
+
}): Promise<{
|
|
81
|
+
records: UntypedRecord[];
|
|
82
|
+
cursor?: string;
|
|
83
|
+
}>;
|
|
84
|
+
watch?(id: string, listener: (settled?: UntypedRecord) => void): () => void;
|
|
85
|
+
};
|
|
86
|
+
export declare const registerTrackedSource: (owner: object, source: UntypedSource) => void;
|
|
87
|
+
export declare const trackedSourceOf: (owner: object) => UntypedSource | undefined;
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
// Built-in capabilities register here instead of exposing a method, so the
|
|
2
|
+
// experimental contract never appears on their public types.
|
|
3
|
+
const builtInSources = new WeakMap();
|
|
4
|
+
export const registerTrackedSource = (owner, source) => {
|
|
5
|
+
builtInSources.set(owner, source);
|
|
6
|
+
};
|
|
7
|
+
export const trackedSourceOf = (owner) => builtInSources.get(owner);
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import type { AnyDurabilityAlarms, DurabilityAlarms } from './durability-alarms.js';
|
|
2
|
+
import type { AnyDurability, Durability, OperationResults } from './durability.js';
|
|
3
|
+
import { type Names, type TrackedEntry, type TrackedResults, type TrackedSource, type TrackedState, type TrackedStatus, type UntypedSource } from './tracked-source.js';
|
|
4
|
+
/** A tracked state, or `not_found` when the record or its generation is gone. */
|
|
5
|
+
export type TrackedResult<Result> = TrackedState<Result> | {
|
|
6
|
+
status: 'not_found';
|
|
7
|
+
};
|
|
8
|
+
type TrackerSources = Record<string, UntypedSource | AnyDurability | AnyDurabilityAlarms>;
|
|
9
|
+
type SourceResults<Source> = Source extends Durability<infer Handlers> ? OperationResults<Handlers> : Source extends DurabilityAlarms<infer AlarmNames> ? Record<AlarmNames, undefined> : Source extends TrackedSource<infer Results> ? Results : never;
|
|
10
|
+
type SourceKey<Sources> = Extract<keyof Sources, string>;
|
|
11
|
+
export type TrackedWaitOptions = {
|
|
12
|
+
/** Maximum time to wait before returning the latest state. */
|
|
13
|
+
timeoutMs: number;
|
|
14
|
+
};
|
|
15
|
+
/**
|
|
16
|
+
* A record plus the key of the source it came from. Plain data, so it can be
|
|
17
|
+
* sent over JSON transports such as `DurabilitySocket`.
|
|
18
|
+
*/
|
|
19
|
+
export type TrackedItem<Source extends string, Results extends TrackedResults> = {
|
|
20
|
+
[Name in Names<Results>]: TrackedEntry<Name, Results[Name]> & {
|
|
21
|
+
source: Source;
|
|
22
|
+
};
|
|
23
|
+
}[Names<Results>];
|
|
24
|
+
/**
|
|
25
|
+
* A record snapshot plus functions to read or wait on it. Over Workers RPC or
|
|
26
|
+
* Cap'n Web the data is copied and the functions become stubs.
|
|
27
|
+
*/
|
|
28
|
+
export type TrackedHandle<Source extends string, Results extends TrackedResults> = {
|
|
29
|
+
[Name in Names<Results>]: TrackedEntry<Name, Results[Name]> & {
|
|
30
|
+
source: Source;
|
|
31
|
+
/** Reads the latest state of this generation. */
|
|
32
|
+
get(): Promise<TrackedResult<Results[Name]>>;
|
|
33
|
+
/** Resolves on settlement, or returns the latest state after the timeout. */
|
|
34
|
+
wait(options: TrackedWaitOptions): Promise<TrackedResult<Results[Name]>>;
|
|
35
|
+
};
|
|
36
|
+
}[Names<Results>];
|
|
37
|
+
export type TrackerRecord<Sources extends TrackerSources, Key extends SourceKey<Sources> = SourceKey<Sources>> = {
|
|
38
|
+
[K in Key]: TrackedItem<K, SourceResults<Sources[K]>>;
|
|
39
|
+
}[Key];
|
|
40
|
+
export type TrackerHandle<Sources extends TrackerSources, Key extends SourceKey<Sources> = SourceKey<Sources>> = {
|
|
41
|
+
[K in Key]: TrackedHandle<K, SourceResults<Sources[K]>>;
|
|
42
|
+
}[Key];
|
|
43
|
+
export type TrackerQuery<Sources extends TrackerSources, Key extends SourceKey<Sources> = SourceKey<Sources>> = {
|
|
44
|
+
source?: Key | undefined;
|
|
45
|
+
name?: string | undefined;
|
|
46
|
+
status?: TrackedStatus | undefined;
|
|
47
|
+
/** Defaults to 50; at most 100 because every handle carries RPC stubs. */
|
|
48
|
+
limit?: number | undefined;
|
|
49
|
+
cursor?: string | undefined;
|
|
50
|
+
};
|
|
51
|
+
export type TrackerPage<Sources extends TrackerSources, Key extends SourceKey<Sources> = SourceKey<Sources>> = {
|
|
52
|
+
items: TrackerHandle<Sources, Key>[];
|
|
53
|
+
cursor?: string;
|
|
54
|
+
};
|
|
55
|
+
export type TrackerRecordPage<Sources extends TrackerSources, Key extends SourceKey<Sources> = SourceKey<Sources>> = {
|
|
56
|
+
records: TrackerRecord<Sources, Key>[];
|
|
57
|
+
cursor?: string;
|
|
58
|
+
};
|
|
59
|
+
export type DurabilityTrackerConfig<Sources extends TrackerSources> = {
|
|
60
|
+
/** Keys name each source and become the records' `source` discriminator. */
|
|
61
|
+
sources: Sources;
|
|
62
|
+
};
|
|
63
|
+
/**
|
|
64
|
+
* Lists work across `Durability`, `DurabilityAlarms`, and custom sources.
|
|
65
|
+
* `list` and `get` return handles that can be read or waited on, locally or
|
|
66
|
+
* over RPC; `records` returns the same pages as plain data.
|
|
67
|
+
*
|
|
68
|
+
* @experimental
|
|
69
|
+
*
|
|
70
|
+
* @example
|
|
71
|
+
* ```ts
|
|
72
|
+
* class ImageJobs extends DurableObject<Env> {
|
|
73
|
+
* private readonly tracker = new DurabilityTracker({
|
|
74
|
+
* sources: { jobs: this.durability, alarms: this.alarms },
|
|
75
|
+
* });
|
|
76
|
+
*
|
|
77
|
+
* listWork(cursor?: string) {
|
|
78
|
+
* return this.tracker.list({ status: 'pending', cursor });
|
|
79
|
+
* }
|
|
80
|
+
* }
|
|
81
|
+
* ```
|
|
82
|
+
*/
|
|
83
|
+
export declare class DurabilityTracker<Sources extends TrackerSources> {
|
|
84
|
+
#private;
|
|
85
|
+
constructor(config: DurabilityTrackerConfig<Sources>);
|
|
86
|
+
/** Returns one page of handles; pass `cursor` back with the same query. */
|
|
87
|
+
list<Key extends SourceKey<Sources> = SourceKey<Sources>>(query?: TrackerQuery<Sources, Key>): Promise<TrackerPage<Sources, Key>>;
|
|
88
|
+
/**
|
|
89
|
+
* Returns one page of plain records, for transports that cannot carry
|
|
90
|
+
* functions; pass `cursor` back with the same query.
|
|
91
|
+
*/
|
|
92
|
+
records<Key extends SourceKey<Sources> = SourceKey<Sources>>(query?: TrackerQuery<Sources, Key>): Promise<TrackerRecordPage<Sources, Key>>;
|
|
93
|
+
/** Reacquires a handle by id, for example after an RPC disconnect. */
|
|
94
|
+
get<Key extends SourceKey<Sources>>(source: Key, id: string): Promise<TrackerHandle<Sources, Key> | undefined>;
|
|
95
|
+
}
|
|
96
|
+
export {};
|