durability 4.1.1 → 4.2.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 +208 -0
- package/dist/durable-object-target.d.ts +12 -0
- package/dist/durable-object-target.js +17 -0
- package/dist/errors.d.ts +8 -0
- package/dist/errors.js +14 -0
- package/dist/experimental.d.ts +3 -0
- package/dist/experimental.js +3 -0
- package/dist/lifecycle.d.ts +14 -3
- package/dist/migrations.d.ts +28 -1
- package/dist/migrations.js +175 -0
- package/dist/outbox.d.ts +72 -0
- package/dist/outbox.js +385 -0
- package/dist/routing.d.ts +2 -9
- package/dist/routing.js +2 -14
- package/dist/scheduler.d.ts +16 -3
- package/dist/scheduler.js +42 -7
- package/dist/semaphore-client.d.ts +22 -0
- package/dist/semaphore-client.js +61 -0
- package/dist/semaphore-leases.d.ts +109 -0
- package/dist/semaphore-leases.js +266 -0
- package/dist/semaphore-protocol.d.ts +231 -0
- package/dist/semaphore-protocol.js +106 -0
- package/dist/semaphore-queue-store.d.ts +85 -0
- package/dist/semaphore-queue-store.js +221 -0
- package/dist/semaphore-queue.d.ts +119 -0
- package/dist/semaphore-queue.js +797 -0
- package/dist/semaphore-server.d.ts +89 -0
- package/dist/semaphore-server.js +520 -0
- package/dist/semaphore-store.d.ts +43 -0
- package/dist/semaphore-store.js +108 -0
- package/dist/semaphore.d.ts +42 -0
- package/dist/semaphore.js +57 -0
- package/package.json +6 -2
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
/**
|
|
3
|
+
* Messages between a semaphore client and the Durable Object holding the
|
|
4
|
+
* limit. Both sides tolerate unknown fields so mixed deployments keep working;
|
|
5
|
+
* new fields must be optional.
|
|
6
|
+
*/
|
|
7
|
+
const nonNegative = z.number().int().nonnegative();
|
|
8
|
+
const nonEmpty = z.string().min(1);
|
|
9
|
+
/** Bounds one message's work so a client cannot monopolize the holder. */
|
|
10
|
+
export const maxDemandEntries = 100;
|
|
11
|
+
export const maxGrantReports = 200;
|
|
12
|
+
/** Cumulative counts for one grant. Replaying a report can never free capacity twice. */
|
|
13
|
+
export const grantReportSchema = z.object({
|
|
14
|
+
grantId: nonEmpty,
|
|
15
|
+
/** Permits of this grant the client has used, as a high-water mark. */
|
|
16
|
+
claimed: nonNegative,
|
|
17
|
+
/** Claimed permits the client has returned, as a high-water mark. */
|
|
18
|
+
released: nonNegative,
|
|
19
|
+
});
|
|
20
|
+
/** Cumulative counts for one lease the client holds. */
|
|
21
|
+
export const leaseReportSchema = z.object({
|
|
22
|
+
leaseId: nonEmpty,
|
|
23
|
+
/** Permits drawn locally so far, as a high-water mark. */
|
|
24
|
+
drawn: nonNegative,
|
|
25
|
+
/** Drawn permits returned, as a high-water mark. */
|
|
26
|
+
released: nonNegative,
|
|
27
|
+
/** The client stopped drawing: the lease's undrawn permits are returned. */
|
|
28
|
+
retired: z.boolean().optional(),
|
|
29
|
+
});
|
|
30
|
+
export const leaseGrantSchema = z.object({
|
|
31
|
+
leaseId: nonEmpty,
|
|
32
|
+
group: z.string(),
|
|
33
|
+
permits: nonNegative,
|
|
34
|
+
/** `expiresAt <= now` retires the lease: stop drawing immediately. */
|
|
35
|
+
expiresAt: nonNegative,
|
|
36
|
+
});
|
|
37
|
+
export const permitRequestSchema = z.object({
|
|
38
|
+
type: z.literal('request'),
|
|
39
|
+
v: z.literal(1),
|
|
40
|
+
clientId: nonEmpty,
|
|
41
|
+
/** Sparse demand per group with the oldest queued time, for FIFO allocation. */
|
|
42
|
+
demand: z
|
|
43
|
+
.object({
|
|
44
|
+
group: z.string(),
|
|
45
|
+
count: z.number().int().positive(),
|
|
46
|
+
oldestAt: nonNegative,
|
|
47
|
+
})
|
|
48
|
+
.array()
|
|
49
|
+
.max(maxDemandEntries),
|
|
50
|
+
grants: grantReportSchema.array().max(maxGrantReports),
|
|
51
|
+
leases: leaseReportSchema.array().max(maxGrantReports).optional(),
|
|
52
|
+
});
|
|
53
|
+
export const permitSyncSchema = z.object({
|
|
54
|
+
type: z.literal('sync'),
|
|
55
|
+
v: z.literal(1),
|
|
56
|
+
clientId: nonEmpty,
|
|
57
|
+
grants: grantReportSchema.array().max(maxGrantReports),
|
|
58
|
+
leases: leaseReportSchema.array().max(maxGrantReports).optional(),
|
|
59
|
+
});
|
|
60
|
+
export const semaphoreRequestSchema = z.discriminatedUnion('type', [
|
|
61
|
+
permitRequestSchema,
|
|
62
|
+
permitSyncSchema,
|
|
63
|
+
]);
|
|
64
|
+
export const semaphoreBlockedReasonSchema = z.enum([
|
|
65
|
+
'group_limit',
|
|
66
|
+
'limit',
|
|
67
|
+
'limit_resolution_error',
|
|
68
|
+
'not_permitted',
|
|
69
|
+
]);
|
|
70
|
+
export const grantResultSchema = z.object({
|
|
71
|
+
grantId: nonEmpty,
|
|
72
|
+
/** Server-clamped claim high-water mark; the client admits only up to this. */
|
|
73
|
+
claimed: nonNegative,
|
|
74
|
+
status: z.enum(['ok', 'not_found', 'expired']),
|
|
75
|
+
});
|
|
76
|
+
export const permitGrantSchema = z.object({
|
|
77
|
+
type: z.literal('grant'),
|
|
78
|
+
v: z.literal(1),
|
|
79
|
+
grants: z
|
|
80
|
+
.object({
|
|
81
|
+
grantId: nonEmpty,
|
|
82
|
+
group: z.string(),
|
|
83
|
+
permits: z.number().int().positive(),
|
|
84
|
+
})
|
|
85
|
+
.array(),
|
|
86
|
+
blocked: z
|
|
87
|
+
.object({ group: z.string(), reason: semaphoreBlockedReasonSchema })
|
|
88
|
+
.array(),
|
|
89
|
+
/** The client must not send another request before this. */
|
|
90
|
+
nextRequestAt: nonNegative,
|
|
91
|
+
grantResults: grantResultSchema.array(),
|
|
92
|
+
leases: leaseGrantSchema.array().optional(),
|
|
93
|
+
/** Demand went unserved: return undrawn lease permits in groups with nothing queued. */
|
|
94
|
+
contended: z.boolean().optional(),
|
|
95
|
+
});
|
|
96
|
+
export const permitSyncResultSchema = z.object({
|
|
97
|
+
type: z.literal('synced'),
|
|
98
|
+
v: z.literal(1),
|
|
99
|
+
grantResults: grantResultSchema.array(),
|
|
100
|
+
leases: leaseGrantSchema.array().optional(),
|
|
101
|
+
contended: z.boolean().optional(),
|
|
102
|
+
});
|
|
103
|
+
export const semaphoreResponseSchema = z.discriminatedUnion('type', [
|
|
104
|
+
permitGrantSchema,
|
|
105
|
+
permitSyncResultSchema,
|
|
106
|
+
]);
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
export declare const queueItemRowSchema: z.ZodObject<{
|
|
3
|
+
id: z.ZodString;
|
|
4
|
+
key: z.ZodString;
|
|
5
|
+
grp: z.ZodString;
|
|
6
|
+
payload: z.ZodString;
|
|
7
|
+
status: z.ZodEnum<{
|
|
8
|
+
queued: "queued";
|
|
9
|
+
claiming: "claiming";
|
|
10
|
+
admitted: "admitted";
|
|
11
|
+
}>;
|
|
12
|
+
grant_id: z.ZodNullable<z.ZodString>;
|
|
13
|
+
lease_id: z.ZodNullable<z.ZodString>;
|
|
14
|
+
created_at: z.ZodNumber;
|
|
15
|
+
admitted_at: z.ZodNullable<z.ZodNumber>;
|
|
16
|
+
notified: z.ZodNumber;
|
|
17
|
+
attempt: z.ZodNumber;
|
|
18
|
+
next_attempt_at: z.ZodNumber;
|
|
19
|
+
}, z.core.$strip>;
|
|
20
|
+
export type QueueItemRow = z.infer<typeof queueItemRowSchema>;
|
|
21
|
+
export declare const queueGrantRowSchema: z.ZodObject<{
|
|
22
|
+
grant_id: z.ZodString;
|
|
23
|
+
key: z.ZodString;
|
|
24
|
+
grp: z.ZodString;
|
|
25
|
+
permits: z.ZodNumber;
|
|
26
|
+
claimed: z.ZodNumber;
|
|
27
|
+
confirmed: z.ZodNumber;
|
|
28
|
+
admitted: z.ZodNumber;
|
|
29
|
+
released: z.ZodNumber;
|
|
30
|
+
created_at: z.ZodNumber;
|
|
31
|
+
}, z.core.$strip>;
|
|
32
|
+
export type QueueGrantRow = z.infer<typeof queueGrantRowSchema>;
|
|
33
|
+
export declare const queueKeyRowSchema: z.ZodObject<{
|
|
34
|
+
key: z.ZodString;
|
|
35
|
+
next_request_at: z.ZodNumber;
|
|
36
|
+
queued: z.ZodNumber;
|
|
37
|
+
}, z.core.$strip>;
|
|
38
|
+
export type QueueKeyRow = z.infer<typeof queueKeyRowSchema>;
|
|
39
|
+
export declare const queueLeaseRowSchema: z.ZodObject<{
|
|
40
|
+
lease_id: z.ZodString;
|
|
41
|
+
key: z.ZodString;
|
|
42
|
+
grp: z.ZodString;
|
|
43
|
+
permits: z.ZodNumber;
|
|
44
|
+
drawn: z.ZodNumber;
|
|
45
|
+
released: z.ZodNumber;
|
|
46
|
+
created_at: z.ZodNumber;
|
|
47
|
+
expires_at: z.ZodNumber;
|
|
48
|
+
}, z.core.$strip>;
|
|
49
|
+
export type QueueLeaseRow = z.infer<typeof queueLeaseRowSchema>;
|
|
50
|
+
/**
|
|
51
|
+
* A semaphore client's queue: items, the grants it holds per key, and per-key
|
|
52
|
+
* request pacing. Due work is a key whose request time has passed with items
|
|
53
|
+
* queued, or an admitted item whose `admit()` notification is outstanding.
|
|
54
|
+
*/
|
|
55
|
+
export declare class QueueStore {
|
|
56
|
+
private readonly sql;
|
|
57
|
+
constructor(sql: SqlStorage);
|
|
58
|
+
getItem(id: string): QueueItemRow | undefined;
|
|
59
|
+
insertItem(row: QueueItemRow): boolean;
|
|
60
|
+
updateItem(row: QueueItemRow): void;
|
|
61
|
+
removeItem(id: string): void;
|
|
62
|
+
listItems(key: string, status: QueueItemRow['status'], limit: number): QueueItemRow[];
|
|
63
|
+
listItemsByGrant(grantId: string): QueueItemRow[];
|
|
64
|
+
/** Notified items whose `finished` check is due; `next_attempt_at` holds the check time. */
|
|
65
|
+
listCheckDue(now: number, limit: number): QueueItemRow[];
|
|
66
|
+
listUnnotified(now: number, limit: number): QueueItemRow[];
|
|
67
|
+
countItems(): Record<QueueItemRow['status'], number>;
|
|
68
|
+
getGrant(grantId: string): QueueGrantRow | undefined;
|
|
69
|
+
insertGrant(row: QueueGrantRow): boolean;
|
|
70
|
+
updateGrant(row: QueueGrantRow): void;
|
|
71
|
+
removeGrant(grantId: string): void;
|
|
72
|
+
listGrants(key: string): QueueGrantRow[];
|
|
73
|
+
getLease(leaseId: string): QueueLeaseRow | undefined;
|
|
74
|
+
insertLease(row: QueueLeaseRow): boolean;
|
|
75
|
+
updateLease(row: QueueLeaseRow): void;
|
|
76
|
+
/** Drops leases that stopped drawing before `before` and have every drawn permit back. */
|
|
77
|
+
removeSpentLeases(before: number): void;
|
|
78
|
+
listLeases(key: string): QueueLeaseRow[];
|
|
79
|
+
getKey(key: string): QueueKeyRow | undefined;
|
|
80
|
+
upsertKey(row: QueueKeyRow): void;
|
|
81
|
+
removeKey(key: string): void;
|
|
82
|
+
listDueKeys(now: number): QueueKeyRow[];
|
|
83
|
+
nextPendingAt(checksFinished: boolean): number | undefined;
|
|
84
|
+
private items;
|
|
85
|
+
}
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
export const queueItemRowSchema = z.object({
|
|
3
|
+
id: z.string(),
|
|
4
|
+
key: z.string(),
|
|
5
|
+
grp: z.string(),
|
|
6
|
+
payload: z.string(),
|
|
7
|
+
/** queued: waiting for permits; claiming: counted against a grant, awaiting confirmation; admitted: running. */
|
|
8
|
+
status: z.enum(['queued', 'claiming', 'admitted']),
|
|
9
|
+
grant_id: z.string().nullable(),
|
|
10
|
+
lease_id: z.string().nullable(),
|
|
11
|
+
created_at: z.number().int().nonnegative(),
|
|
12
|
+
admitted_at: z.number().int().nonnegative().nullable(),
|
|
13
|
+
/** 0 until `admit()` has returned for this item. */
|
|
14
|
+
notified: z.number().int().min(0).max(1),
|
|
15
|
+
attempt: z.number().int().nonnegative(),
|
|
16
|
+
next_attempt_at: z.number().int().nonnegative(),
|
|
17
|
+
});
|
|
18
|
+
export const queueGrantRowSchema = z.object({
|
|
19
|
+
grant_id: z.string(),
|
|
20
|
+
key: z.string(),
|
|
21
|
+
grp: z.string(),
|
|
22
|
+
permits: z.number().int().nonnegative(),
|
|
23
|
+
/** Permits counted against this grant locally, as a high-water mark. */
|
|
24
|
+
claimed: z.number().int().nonnegative(),
|
|
25
|
+
/** Claims the holder has confirmed. */
|
|
26
|
+
confirmed: z.number().int().nonnegative(),
|
|
27
|
+
/** Items handed to `admit()` from this grant; never derived from live rows. */
|
|
28
|
+
admitted: z.number().int().nonnegative(),
|
|
29
|
+
released: z.number().int().nonnegative(),
|
|
30
|
+
created_at: z.number().int().nonnegative(),
|
|
31
|
+
});
|
|
32
|
+
export const queueKeyRowSchema = z.object({
|
|
33
|
+
key: z.string(),
|
|
34
|
+
/** Earliest time the next permit request for this key may be sent. */
|
|
35
|
+
next_request_at: z.number().int().nonnegative(),
|
|
36
|
+
queued: z.number().int().nonnegative(),
|
|
37
|
+
});
|
|
38
|
+
export const queueLeaseRowSchema = z.object({
|
|
39
|
+
lease_id: z.string(),
|
|
40
|
+
key: z.string(),
|
|
41
|
+
grp: z.string(),
|
|
42
|
+
permits: z.number().int().nonnegative(),
|
|
43
|
+
/** Permits drawn so far; a drawn permit is never drawable again. */
|
|
44
|
+
drawn: z.number().int().nonnegative(),
|
|
45
|
+
released: z.number().int().nonnegative(),
|
|
46
|
+
created_at: z.number().int().nonnegative(),
|
|
47
|
+
expires_at: z.number().int().nonnegative(),
|
|
48
|
+
});
|
|
49
|
+
const queueItemColumns = queueItemRowSchema.keyof().options;
|
|
50
|
+
const queueGrantColumns = queueGrantRowSchema.keyof().options;
|
|
51
|
+
const queueLeaseColumns = queueLeaseRowSchema.keyof().options;
|
|
52
|
+
const statusCountSchema = z.object({
|
|
53
|
+
status: queueItemRowSchema.shape.status,
|
|
54
|
+
count: z.number().int().nonnegative(),
|
|
55
|
+
});
|
|
56
|
+
/**
|
|
57
|
+
* A semaphore client's queue: items, the grants it holds per key, and per-key
|
|
58
|
+
* request pacing. Due work is a key whose request time has passed with items
|
|
59
|
+
* queued, or an admitted item whose `admit()` notification is outstanding.
|
|
60
|
+
*/
|
|
61
|
+
export class QueueStore {
|
|
62
|
+
constructor(sql) {
|
|
63
|
+
this.sql = sql;
|
|
64
|
+
}
|
|
65
|
+
getItem(id) {
|
|
66
|
+
return this.items('SELECT * FROM durability_semaphore_queue_items WHERE id = ? LIMIT 1', id)[0];
|
|
67
|
+
}
|
|
68
|
+
insertItem(row) {
|
|
69
|
+
return (this.sql
|
|
70
|
+
.exec(`INSERT INTO durability_semaphore_queue_items (${queueItemColumns.join(', ')})
|
|
71
|
+
VALUES (${queueItemColumns.map(() => '?').join(', ')})
|
|
72
|
+
ON CONFLICT(id) DO NOTHING
|
|
73
|
+
RETURNING id`, ...queueItemColumns.map((column) => row[column]))
|
|
74
|
+
.toArray().length > 0);
|
|
75
|
+
}
|
|
76
|
+
updateItem(row) {
|
|
77
|
+
this.sql.exec(`UPDATE durability_semaphore_queue_items
|
|
78
|
+
SET status = ?, grant_id = ?, lease_id = ?, admitted_at = ?, notified = ?,
|
|
79
|
+
attempt = ?, next_attempt_at = ?
|
|
80
|
+
WHERE id = ?`, row.status, row.grant_id, row.lease_id, row.admitted_at, row.notified, row.attempt, row.next_attempt_at, row.id);
|
|
81
|
+
}
|
|
82
|
+
removeItem(id) {
|
|
83
|
+
this.sql.exec('DELETE FROM durability_semaphore_queue_items WHERE id = ?', id);
|
|
84
|
+
}
|
|
85
|
+
listItems(key, status, limit) {
|
|
86
|
+
return this.items(`SELECT * FROM durability_semaphore_queue_items
|
|
87
|
+
WHERE key = ? AND status = ?
|
|
88
|
+
ORDER BY created_at ASC, id ASC
|
|
89
|
+
LIMIT ?`, key, status, limit);
|
|
90
|
+
}
|
|
91
|
+
listItemsByGrant(grantId) {
|
|
92
|
+
return this.items(`SELECT * FROM durability_semaphore_queue_items
|
|
93
|
+
WHERE grant_id = ?
|
|
94
|
+
ORDER BY created_at ASC, id ASC`, grantId);
|
|
95
|
+
}
|
|
96
|
+
/** Notified items whose `finished` check is due; `next_attempt_at` holds the check time. */
|
|
97
|
+
listCheckDue(now, limit) {
|
|
98
|
+
return this.items(`SELECT * FROM durability_semaphore_queue_items
|
|
99
|
+
WHERE status = 'admitted' AND notified = 1 AND next_attempt_at <= ?
|
|
100
|
+
ORDER BY next_attempt_at ASC
|
|
101
|
+
LIMIT ?`, now, limit);
|
|
102
|
+
}
|
|
103
|
+
listUnnotified(now, limit) {
|
|
104
|
+
return this.items(`SELECT * FROM durability_semaphore_queue_items
|
|
105
|
+
WHERE status = 'admitted' AND notified = 0 AND next_attempt_at <= ?
|
|
106
|
+
ORDER BY next_attempt_at ASC
|
|
107
|
+
LIMIT ?`, now, limit);
|
|
108
|
+
}
|
|
109
|
+
countItems() {
|
|
110
|
+
const counts = { queued: 0, claiming: 0, admitted: 0 };
|
|
111
|
+
for (const row of statusCountSchema.array().parse(this.sql
|
|
112
|
+
.exec(`SELECT status, COUNT(*) AS count FROM durability_semaphore_queue_items
|
|
113
|
+
GROUP BY status`)
|
|
114
|
+
.toArray())) {
|
|
115
|
+
counts[row.status] = row.count;
|
|
116
|
+
}
|
|
117
|
+
return counts;
|
|
118
|
+
}
|
|
119
|
+
getGrant(grantId) {
|
|
120
|
+
return queueGrantRowSchema
|
|
121
|
+
.optional()
|
|
122
|
+
.parse(this.sql
|
|
123
|
+
.exec('SELECT * FROM durability_semaphore_queue_grants WHERE grant_id = ? LIMIT 1', grantId)
|
|
124
|
+
.toArray()[0]);
|
|
125
|
+
}
|
|
126
|
+
insertGrant(row) {
|
|
127
|
+
return (this.sql
|
|
128
|
+
.exec(`INSERT INTO durability_semaphore_queue_grants (${queueGrantColumns.join(', ')})
|
|
129
|
+
VALUES (${queueGrantColumns.map(() => '?').join(', ')})
|
|
130
|
+
ON CONFLICT(grant_id) DO NOTHING
|
|
131
|
+
RETURNING grant_id`, ...queueGrantColumns.map((column) => row[column]))
|
|
132
|
+
.toArray().length > 0);
|
|
133
|
+
}
|
|
134
|
+
updateGrant(row) {
|
|
135
|
+
this.sql.exec(`UPDATE durability_semaphore_queue_grants
|
|
136
|
+
SET permits = ?, claimed = ?, confirmed = ?, admitted = ?, released = ?
|
|
137
|
+
WHERE grant_id = ?`, row.permits, row.claimed, row.confirmed, row.admitted, row.released, row.grant_id);
|
|
138
|
+
}
|
|
139
|
+
removeGrant(grantId) {
|
|
140
|
+
this.sql.exec('DELETE FROM durability_semaphore_queue_grants WHERE grant_id = ?', grantId);
|
|
141
|
+
}
|
|
142
|
+
listGrants(key) {
|
|
143
|
+
return queueGrantRowSchema.array().parse(this.sql
|
|
144
|
+
.exec(`SELECT * FROM durability_semaphore_queue_grants
|
|
145
|
+
WHERE key = ? ORDER BY created_at ASC, grant_id ASC`, key)
|
|
146
|
+
.toArray());
|
|
147
|
+
}
|
|
148
|
+
getLease(leaseId) {
|
|
149
|
+
return queueLeaseRowSchema
|
|
150
|
+
.optional()
|
|
151
|
+
.parse(this.sql
|
|
152
|
+
.exec('SELECT * FROM durability_semaphore_queue_leases WHERE lease_id = ? LIMIT 1', leaseId)
|
|
153
|
+
.toArray()[0]);
|
|
154
|
+
}
|
|
155
|
+
insertLease(row) {
|
|
156
|
+
return (this.sql
|
|
157
|
+
.exec(`INSERT INTO durability_semaphore_queue_leases (${queueLeaseColumns.join(', ')})
|
|
158
|
+
VALUES (${queueLeaseColumns.map(() => '?').join(', ')})
|
|
159
|
+
ON CONFLICT(lease_id) DO NOTHING
|
|
160
|
+
RETURNING lease_id`, ...queueLeaseColumns.map((column) => row[column]))
|
|
161
|
+
.toArray().length > 0);
|
|
162
|
+
}
|
|
163
|
+
updateLease(row) {
|
|
164
|
+
this.sql.exec(`UPDATE durability_semaphore_queue_leases
|
|
165
|
+
SET permits = ?, drawn = ?, released = ?, expires_at = ?
|
|
166
|
+
WHERE lease_id = ?`, row.permits, row.drawn, row.released, row.expires_at, row.lease_id);
|
|
167
|
+
}
|
|
168
|
+
/** Drops leases that stopped drawing before `before` and have every drawn permit back. */
|
|
169
|
+
removeSpentLeases(before) {
|
|
170
|
+
this.sql.exec(`DELETE FROM durability_semaphore_queue_leases
|
|
171
|
+
WHERE expires_at < ? AND released >= drawn`, before);
|
|
172
|
+
}
|
|
173
|
+
listLeases(key) {
|
|
174
|
+
return queueLeaseRowSchema.array().parse(this.sql
|
|
175
|
+
.exec(`SELECT * FROM durability_semaphore_queue_leases
|
|
176
|
+
WHERE key = ? ORDER BY created_at ASC, lease_id ASC`, key)
|
|
177
|
+
.toArray());
|
|
178
|
+
}
|
|
179
|
+
getKey(key) {
|
|
180
|
+
return queueKeyRowSchema
|
|
181
|
+
.optional()
|
|
182
|
+
.parse(this.sql
|
|
183
|
+
.exec('SELECT * FROM durability_semaphore_queue_keys WHERE key = ? LIMIT 1', key)
|
|
184
|
+
.toArray()[0]);
|
|
185
|
+
}
|
|
186
|
+
upsertKey(row) {
|
|
187
|
+
this.sql.exec(`INSERT INTO durability_semaphore_queue_keys (key, next_request_at, queued)
|
|
188
|
+
VALUES (?, ?, ?)
|
|
189
|
+
ON CONFLICT(key) DO UPDATE SET
|
|
190
|
+
next_request_at = excluded.next_request_at, queued = excluded.queued`, row.key, row.next_request_at, row.queued);
|
|
191
|
+
}
|
|
192
|
+
removeKey(key) {
|
|
193
|
+
this.sql.exec('DELETE FROM durability_semaphore_queue_keys WHERE key = ?', key);
|
|
194
|
+
}
|
|
195
|
+
listDueKeys(now) {
|
|
196
|
+
return queueKeyRowSchema.array().parse(this.sql
|
|
197
|
+
.exec(`SELECT * FROM durability_semaphore_queue_keys
|
|
198
|
+
WHERE queued > 0 AND next_request_at <= ?
|
|
199
|
+
ORDER BY next_request_at ASC`, now)
|
|
200
|
+
.toArray());
|
|
201
|
+
}
|
|
202
|
+
nextPendingAt(checksFinished) {
|
|
203
|
+
const candidates = [
|
|
204
|
+
this.sql
|
|
205
|
+
.exec(`SELECT next_request_at AS at FROM durability_semaphore_queue_keys
|
|
206
|
+
WHERE queued > 0 ORDER BY next_request_at ASC LIMIT 1`)
|
|
207
|
+
.toArray()[0]?.['at'],
|
|
208
|
+
this.sql
|
|
209
|
+
.exec(`SELECT next_attempt_at AS at FROM durability_semaphore_queue_items
|
|
210
|
+
WHERE status = 'admitted' AND (notified = 0 OR ?)
|
|
211
|
+
ORDER BY next_attempt_at ASC LIMIT 1`, checksFinished ? 1 : 0)
|
|
212
|
+
.toArray()[0]?.['at'],
|
|
213
|
+
].filter((value) => typeof value === 'number');
|
|
214
|
+
return candidates.length === 0 ? undefined : Math.min(...candidates);
|
|
215
|
+
}
|
|
216
|
+
items(query, ...bindings) {
|
|
217
|
+
return queueItemRowSchema
|
|
218
|
+
.array()
|
|
219
|
+
.parse(this.sql.exec(query, ...bindings).toArray());
|
|
220
|
+
}
|
|
221
|
+
}
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
import { type DurabilityMigrationResult } from './migrations.js';
|
|
2
|
+
import { type DurabilityRetryOptions } from './policy.js';
|
|
3
|
+
import { type SchedulerAttachment } from './scheduler.js';
|
|
4
|
+
import type { PermitGrant, PermitRequest, PermitSync, PermitSyncResult, SemaphoreBlockedReason } from './semaphore-protocol.js';
|
|
5
|
+
import { type QueueItemRow } from './semaphore-queue-store.js';
|
|
6
|
+
export type SemaphoreInput<Body> = {
|
|
7
|
+
/** Stable item ID; enqueueing a known ID again is a no-op. Defaults to random. */
|
|
8
|
+
id?: string;
|
|
9
|
+
/** Semaphore key: the name of the holder Durable Object, e.g. an account ID. */
|
|
10
|
+
key: string;
|
|
11
|
+
/** Optional sub-partition with its own ceiling at the holder. Defaults to ''. */
|
|
12
|
+
group?: string;
|
|
13
|
+
body: Body;
|
|
14
|
+
};
|
|
15
|
+
export type AdmittedItem<Body> = {
|
|
16
|
+
id: string;
|
|
17
|
+
key: string;
|
|
18
|
+
group: string;
|
|
19
|
+
body: Body;
|
|
20
|
+
enqueuedAt: number;
|
|
21
|
+
admittedAt: number;
|
|
22
|
+
/** `grant`: confirmed by the holder; `lease`: drawn locally from a lease. */
|
|
23
|
+
via: 'grant' | 'lease';
|
|
24
|
+
};
|
|
25
|
+
export type SemaphoreItemStatus = {
|
|
26
|
+
state: 'queued';
|
|
27
|
+
enqueuedAt: number;
|
|
28
|
+
blocked?: SemaphoreBlockedReason;
|
|
29
|
+
} | {
|
|
30
|
+
state: 'claiming';
|
|
31
|
+
enqueuedAt: number;
|
|
32
|
+
} | {
|
|
33
|
+
state: 'admitted';
|
|
34
|
+
enqueuedAt: number;
|
|
35
|
+
admittedAt: number;
|
|
36
|
+
};
|
|
37
|
+
/** What the queue needs from `DurabilitySemaphore.client()`. */
|
|
38
|
+
export type SemaphoreHolder = {
|
|
39
|
+
request(key: string, message: PermitRequest): Promise<PermitGrant>;
|
|
40
|
+
sync(key: string, message: PermitSync): Promise<PermitSyncResult>;
|
|
41
|
+
};
|
|
42
|
+
export type DurabilitySemaphoreQueueConfig<Body> = SchedulerAttachment & {
|
|
43
|
+
/** The holder, from `DurabilitySemaphore.client()`; caller transforms apply. */
|
|
44
|
+
server: SemaphoreHolder;
|
|
45
|
+
/** Stable identity of this client Durable Object, e.g. `ctx.id.toString()`. */
|
|
46
|
+
clientId: string;
|
|
47
|
+
/**
|
|
48
|
+
* Receives items once the holder has confirmed their permits, after the
|
|
49
|
+
* admission commits. Retried until it returns; must be idempotent on item ID.
|
|
50
|
+
*/
|
|
51
|
+
admit(items: AdmittedItem<Body>[]): unknown | Promise<unknown>;
|
|
52
|
+
/**
|
|
53
|
+
* Returns which of these admitted items are done. The queue asks on its own
|
|
54
|
+
* alarm and releases them, so a permit whose `release()` was lost (a
|
|
55
|
+
* best-effort lifecycle hook, a crash) still comes back. Without it,
|
|
56
|
+
* `release()` is the only way a permit returns.
|
|
57
|
+
*/
|
|
58
|
+
finished?(ids: string[]): string[] | Promise<string[]>;
|
|
59
|
+
/** How long an admitted item runs before `finished` is asked, and between asks. Defaults to 60 seconds. */
|
|
60
|
+
finishedCheckMs?: number;
|
|
61
|
+
/** Items per `admit()` and `finished()` call. Defaults to 100. */
|
|
62
|
+
maxAdmitBatch?: number;
|
|
63
|
+
/** Maximum duration of one `admit()` call. Defaults to 60 seconds. */
|
|
64
|
+
attemptTimeoutMs?: number;
|
|
65
|
+
/** Backoff for failed `admit()` calls and holder requests. */
|
|
66
|
+
retries?: Pick<DurabilityRetryOptions, 'delay'>;
|
|
67
|
+
onLifecycleEvent?: (event: DurabilitySemaphoreQueueEvent) => void | Promise<void>;
|
|
68
|
+
};
|
|
69
|
+
export type DurabilitySemaphoreQueueEvent = {
|
|
70
|
+
entityKind: 'semaphore_item';
|
|
71
|
+
type: 'queued' | 'released' | 'cancelled';
|
|
72
|
+
timestamp: number;
|
|
73
|
+
id: string;
|
|
74
|
+
key: string;
|
|
75
|
+
group: string;
|
|
76
|
+
} | {
|
|
77
|
+
entityKind: 'semaphore_item';
|
|
78
|
+
type: 'admitted';
|
|
79
|
+
timestamp: number;
|
|
80
|
+
id: string;
|
|
81
|
+
key: string;
|
|
82
|
+
group: string;
|
|
83
|
+
waitMs: number;
|
|
84
|
+
} | {
|
|
85
|
+
entityKind: 'semaphore_item';
|
|
86
|
+
type: 'blocked';
|
|
87
|
+
timestamp: number;
|
|
88
|
+
key: string;
|
|
89
|
+
group: string;
|
|
90
|
+
reason: SemaphoreBlockedReason;
|
|
91
|
+
count: number;
|
|
92
|
+
};
|
|
93
|
+
/**
|
|
94
|
+
* A composable DO capability for the client side of {@link DurabilitySemaphore}:
|
|
95
|
+
* queues items per semaphore key in arrival order, asks the holder for
|
|
96
|
+
* permits, and hands admitted items to the application. Claims and releases
|
|
97
|
+
* are published to the holder through an internal outbox channel as
|
|
98
|
+
* cumulative counts, so nothing is lost or double-counted across retries.
|
|
99
|
+
*/
|
|
100
|
+
export declare class DurabilitySemaphoreQueue<Body = unknown> {
|
|
101
|
+
#private;
|
|
102
|
+
constructor(config: DurabilitySemaphoreQueueConfig<Body>);
|
|
103
|
+
static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
|
|
104
|
+
alarm(info?: AlarmInvocationInfo): Promise<void>;
|
|
105
|
+
/**
|
|
106
|
+
* Durably accepts items. Each is admitted once the holder confirms a
|
|
107
|
+
* permit; items whose key already holds unclaimed permits skip the request.
|
|
108
|
+
*/
|
|
109
|
+
enqueue(items: readonly SemaphoreInput<Body>[]): Promise<{
|
|
110
|
+
queued: string[];
|
|
111
|
+
duplicates: string[];
|
|
112
|
+
}>;
|
|
113
|
+
/** The item finished: its permit returns to the holder. Idempotent. */
|
|
114
|
+
release(id: string): Promise<boolean>;
|
|
115
|
+
/** Removes a still-queued item. False once it counts against a grant. */
|
|
116
|
+
cancel(id: string): Promise<boolean>;
|
|
117
|
+
status(id: string): Promise<SemaphoreItemStatus | undefined>;
|
|
118
|
+
usage(): Promise<Record<QueueItemRow['status'], number>>;
|
|
119
|
+
}
|