durability 4.1.2 → 4.3.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.
Files changed (52) hide show
  1. package/README.md +406 -1
  2. package/dist/dev.d.ts +22 -0
  3. package/dist/dev.js +149 -0
  4. package/dist/durability-alarms.d.ts +1 -1
  5. package/dist/durability-alarms.js +6 -4
  6. package/dist/durability.d.ts +1 -1
  7. package/dist/durability.js +8 -5
  8. package/dist/durable-object-target.d.ts +12 -0
  9. package/dist/durable-object-target.js +17 -0
  10. package/dist/errors.d.ts +25 -0
  11. package/dist/errors.js +36 -0
  12. package/dist/experimental.d.ts +8 -0
  13. package/dist/experimental.js +6 -0
  14. package/dist/fanout.js +14 -9
  15. package/dist/index.d.ts +2 -1
  16. package/dist/index.js +1 -1
  17. package/dist/lifecycle.d.ts +14 -3
  18. package/dist/lifecycle.js +3 -2
  19. package/dist/log.js +26 -4
  20. package/dist/migrations.d.ts +74 -2
  21. package/dist/migrations.js +307 -36
  22. package/dist/outbox.d.ts +85 -0
  23. package/dist/outbox.js +433 -0
  24. package/dist/routing.d.ts +2 -9
  25. package/dist/routing.js +2 -14
  26. package/dist/scheduler.d.ts +14 -2
  27. package/dist/scheduler.js +38 -13
  28. package/dist/semaphore-client.d.ts +22 -0
  29. package/dist/semaphore-client.js +61 -0
  30. package/dist/semaphore-leases.d.ts +109 -0
  31. package/dist/semaphore-leases.js +272 -0
  32. package/dist/semaphore-protocol.d.ts +231 -0
  33. package/dist/semaphore-protocol.js +106 -0
  34. package/dist/semaphore-queue-store.d.ts +95 -0
  35. package/dist/semaphore-queue-store.js +248 -0
  36. package/dist/semaphore-queue.d.ts +119 -0
  37. package/dist/semaphore-queue.js +863 -0
  38. package/dist/semaphore-server.d.ts +89 -0
  39. package/dist/semaphore-server.js +518 -0
  40. package/dist/semaphore-store.d.ts +43 -0
  41. package/dist/semaphore-store.js +108 -0
  42. package/dist/semaphore.d.ts +42 -0
  43. package/dist/semaphore.js +57 -0
  44. package/dist/socket.js +19 -10
  45. package/dist/topology-client.d.ts +40 -0
  46. package/dist/topology-client.js +180 -0
  47. package/dist/topology-snapshot.d.ts +70 -0
  48. package/dist/topology-snapshot.js +48 -0
  49. package/dist/topology.d.ts +94 -0
  50. package/dist/topology.js +468 -0
  51. package/dist/tracker.js +2 -0
  52. package/package.json +6 -2
@@ -0,0 +1,231 @@
1
+ import { z } from 'zod';
2
+ /** Bounds one message's work so a client cannot monopolize the holder. */
3
+ export declare const maxDemandEntries = 100;
4
+ export declare const maxGrantReports = 200;
5
+ /** Cumulative counts for one grant. Replaying a report can never free capacity twice. */
6
+ export declare const grantReportSchema: z.ZodObject<{
7
+ grantId: z.ZodString;
8
+ claimed: z.ZodNumber;
9
+ released: z.ZodNumber;
10
+ }, z.core.$strip>;
11
+ export type GrantReport = z.infer<typeof grantReportSchema>;
12
+ /** Cumulative counts for one lease the client holds. */
13
+ export declare const leaseReportSchema: z.ZodObject<{
14
+ leaseId: z.ZodString;
15
+ drawn: z.ZodNumber;
16
+ released: z.ZodNumber;
17
+ retired: z.ZodOptional<z.ZodBoolean>;
18
+ }, z.core.$strip>;
19
+ export type LeaseReport = z.infer<typeof leaseReportSchema>;
20
+ export declare const leaseGrantSchema: z.ZodObject<{
21
+ leaseId: z.ZodString;
22
+ group: z.ZodString;
23
+ permits: z.ZodNumber;
24
+ expiresAt: z.ZodNumber;
25
+ }, z.core.$strip>;
26
+ export type LeaseGrant = z.infer<typeof leaseGrantSchema>;
27
+ export declare const permitRequestSchema: z.ZodObject<{
28
+ type: z.ZodLiteral<"request">;
29
+ v: z.ZodLiteral<1>;
30
+ clientId: z.ZodString;
31
+ demand: z.ZodArray<z.ZodObject<{
32
+ group: z.ZodString;
33
+ count: z.ZodNumber;
34
+ oldestAt: z.ZodNumber;
35
+ }, z.core.$strip>>;
36
+ grants: z.ZodArray<z.ZodObject<{
37
+ grantId: z.ZodString;
38
+ claimed: z.ZodNumber;
39
+ released: z.ZodNumber;
40
+ }, z.core.$strip>>;
41
+ leases: z.ZodOptional<z.ZodArray<z.ZodObject<{
42
+ leaseId: z.ZodString;
43
+ drawn: z.ZodNumber;
44
+ released: z.ZodNumber;
45
+ retired: z.ZodOptional<z.ZodBoolean>;
46
+ }, z.core.$strip>>>;
47
+ }, z.core.$strip>;
48
+ export type PermitRequest = z.infer<typeof permitRequestSchema>;
49
+ export declare const permitSyncSchema: z.ZodObject<{
50
+ type: z.ZodLiteral<"sync">;
51
+ v: z.ZodLiteral<1>;
52
+ clientId: z.ZodString;
53
+ grants: z.ZodArray<z.ZodObject<{
54
+ grantId: z.ZodString;
55
+ claimed: z.ZodNumber;
56
+ released: z.ZodNumber;
57
+ }, z.core.$strip>>;
58
+ leases: z.ZodOptional<z.ZodArray<z.ZodObject<{
59
+ leaseId: z.ZodString;
60
+ drawn: z.ZodNumber;
61
+ released: z.ZodNumber;
62
+ retired: z.ZodOptional<z.ZodBoolean>;
63
+ }, z.core.$strip>>>;
64
+ }, z.core.$strip>;
65
+ export type PermitSync = z.infer<typeof permitSyncSchema>;
66
+ export declare const semaphoreRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
67
+ type: z.ZodLiteral<"request">;
68
+ v: z.ZodLiteral<1>;
69
+ clientId: z.ZodString;
70
+ demand: z.ZodArray<z.ZodObject<{
71
+ group: z.ZodString;
72
+ count: z.ZodNumber;
73
+ oldestAt: z.ZodNumber;
74
+ }, z.core.$strip>>;
75
+ grants: z.ZodArray<z.ZodObject<{
76
+ grantId: z.ZodString;
77
+ claimed: z.ZodNumber;
78
+ released: z.ZodNumber;
79
+ }, z.core.$strip>>;
80
+ leases: z.ZodOptional<z.ZodArray<z.ZodObject<{
81
+ leaseId: z.ZodString;
82
+ drawn: z.ZodNumber;
83
+ released: z.ZodNumber;
84
+ retired: z.ZodOptional<z.ZodBoolean>;
85
+ }, z.core.$strip>>>;
86
+ }, z.core.$strip>, z.ZodObject<{
87
+ type: z.ZodLiteral<"sync">;
88
+ v: z.ZodLiteral<1>;
89
+ clientId: z.ZodString;
90
+ grants: z.ZodArray<z.ZodObject<{
91
+ grantId: z.ZodString;
92
+ claimed: z.ZodNumber;
93
+ released: z.ZodNumber;
94
+ }, z.core.$strip>>;
95
+ leases: z.ZodOptional<z.ZodArray<z.ZodObject<{
96
+ leaseId: z.ZodString;
97
+ drawn: z.ZodNumber;
98
+ released: z.ZodNumber;
99
+ retired: z.ZodOptional<z.ZodBoolean>;
100
+ }, z.core.$strip>>>;
101
+ }, z.core.$strip>], "type">;
102
+ export type SemaphoreRequest = z.infer<typeof semaphoreRequestSchema>;
103
+ export declare const semaphoreBlockedReasonSchema: z.ZodEnum<{
104
+ limit: "limit";
105
+ group_limit: "group_limit";
106
+ limit_resolution_error: "limit_resolution_error";
107
+ not_permitted: "not_permitted";
108
+ }>;
109
+ export type SemaphoreBlockedReason = z.infer<typeof semaphoreBlockedReasonSchema>;
110
+ export declare const grantResultSchema: z.ZodObject<{
111
+ grantId: z.ZodString;
112
+ claimed: z.ZodNumber;
113
+ status: z.ZodEnum<{
114
+ not_found: "not_found";
115
+ ok: "ok";
116
+ expired: "expired";
117
+ }>;
118
+ }, z.core.$strip>;
119
+ export type GrantResult = z.infer<typeof grantResultSchema>;
120
+ export declare const permitGrantSchema: z.ZodObject<{
121
+ type: z.ZodLiteral<"grant">;
122
+ v: z.ZodLiteral<1>;
123
+ grants: z.ZodArray<z.ZodObject<{
124
+ grantId: z.ZodString;
125
+ group: z.ZodString;
126
+ permits: z.ZodNumber;
127
+ }, z.core.$strip>>;
128
+ blocked: z.ZodArray<z.ZodObject<{
129
+ group: z.ZodString;
130
+ reason: z.ZodEnum<{
131
+ limit: "limit";
132
+ group_limit: "group_limit";
133
+ limit_resolution_error: "limit_resolution_error";
134
+ not_permitted: "not_permitted";
135
+ }>;
136
+ }, z.core.$strip>>;
137
+ nextRequestAt: z.ZodNumber;
138
+ grantResults: z.ZodArray<z.ZodObject<{
139
+ grantId: z.ZodString;
140
+ claimed: z.ZodNumber;
141
+ status: z.ZodEnum<{
142
+ not_found: "not_found";
143
+ ok: "ok";
144
+ expired: "expired";
145
+ }>;
146
+ }, z.core.$strip>>;
147
+ leases: z.ZodOptional<z.ZodArray<z.ZodObject<{
148
+ leaseId: z.ZodString;
149
+ group: z.ZodString;
150
+ permits: z.ZodNumber;
151
+ expiresAt: z.ZodNumber;
152
+ }, z.core.$strip>>>;
153
+ contended: z.ZodOptional<z.ZodBoolean>;
154
+ }, z.core.$strip>;
155
+ export type PermitGrant = z.infer<typeof permitGrantSchema>;
156
+ export declare const permitSyncResultSchema: z.ZodObject<{
157
+ type: z.ZodLiteral<"synced">;
158
+ v: z.ZodLiteral<1>;
159
+ grantResults: z.ZodArray<z.ZodObject<{
160
+ grantId: z.ZodString;
161
+ claimed: z.ZodNumber;
162
+ status: z.ZodEnum<{
163
+ not_found: "not_found";
164
+ ok: "ok";
165
+ expired: "expired";
166
+ }>;
167
+ }, z.core.$strip>>;
168
+ leases: z.ZodOptional<z.ZodArray<z.ZodObject<{
169
+ leaseId: z.ZodString;
170
+ group: z.ZodString;
171
+ permits: z.ZodNumber;
172
+ expiresAt: z.ZodNumber;
173
+ }, z.core.$strip>>>;
174
+ contended: z.ZodOptional<z.ZodBoolean>;
175
+ }, z.core.$strip>;
176
+ export type PermitSyncResult = z.infer<typeof permitSyncResultSchema>;
177
+ export declare const semaphoreResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
178
+ type: z.ZodLiteral<"grant">;
179
+ v: z.ZodLiteral<1>;
180
+ grants: z.ZodArray<z.ZodObject<{
181
+ grantId: z.ZodString;
182
+ group: z.ZodString;
183
+ permits: z.ZodNumber;
184
+ }, z.core.$strip>>;
185
+ blocked: z.ZodArray<z.ZodObject<{
186
+ group: z.ZodString;
187
+ reason: z.ZodEnum<{
188
+ limit: "limit";
189
+ group_limit: "group_limit";
190
+ limit_resolution_error: "limit_resolution_error";
191
+ not_permitted: "not_permitted";
192
+ }>;
193
+ }, z.core.$strip>>;
194
+ nextRequestAt: z.ZodNumber;
195
+ grantResults: z.ZodArray<z.ZodObject<{
196
+ grantId: z.ZodString;
197
+ claimed: z.ZodNumber;
198
+ status: z.ZodEnum<{
199
+ not_found: "not_found";
200
+ ok: "ok";
201
+ expired: "expired";
202
+ }>;
203
+ }, z.core.$strip>>;
204
+ leases: z.ZodOptional<z.ZodArray<z.ZodObject<{
205
+ leaseId: z.ZodString;
206
+ group: z.ZodString;
207
+ permits: z.ZodNumber;
208
+ expiresAt: z.ZodNumber;
209
+ }, z.core.$strip>>>;
210
+ contended: z.ZodOptional<z.ZodBoolean>;
211
+ }, z.core.$strip>, z.ZodObject<{
212
+ type: z.ZodLiteral<"synced">;
213
+ v: z.ZodLiteral<1>;
214
+ grantResults: z.ZodArray<z.ZodObject<{
215
+ grantId: z.ZodString;
216
+ claimed: z.ZodNumber;
217
+ status: z.ZodEnum<{
218
+ not_found: "not_found";
219
+ ok: "ok";
220
+ expired: "expired";
221
+ }>;
222
+ }, z.core.$strip>>;
223
+ leases: z.ZodOptional<z.ZodArray<z.ZodObject<{
224
+ leaseId: z.ZodString;
225
+ group: z.ZodString;
226
+ permits: z.ZodNumber;
227
+ expiresAt: z.ZodNumber;
228
+ }, z.core.$strip>>>;
229
+ contended: z.ZodOptional<z.ZodBoolean>;
230
+ }, z.core.$strip>], "type">;
231
+ export type SemaphoreResponse = z.infer<typeof semaphoreResponseSchema>;
@@ -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,95 @@
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
+ renew_at: z.ZodNumber;
49
+ renew_ms: z.ZodNumber;
50
+ confirmed: z.ZodNumber;
51
+ }, z.core.$strip>;
52
+ export type QueueLeaseRow = z.infer<typeof queueLeaseRowSchema>;
53
+ /**
54
+ * A semaphore client's queue: items, the grants it holds per key, and per-key
55
+ * request pacing. Due work is a key whose request time has passed with items
56
+ * queued, an admitted item whose `admit()` notification is outstanding, or a
57
+ * lease the holder must hear about again.
58
+ */
59
+ export declare class QueueStore {
60
+ private readonly sql;
61
+ constructor(sql: SqlStorage);
62
+ getItem(id: string): QueueItemRow | undefined;
63
+ insertItem(row: QueueItemRow): boolean;
64
+ updateItem(row: QueueItemRow): void;
65
+ removeItem(id: string): void;
66
+ listItems(key: string, status: QueueItemRow['status'], limit: number): QueueItemRow[];
67
+ listItemsByGrant(grantId: string): QueueItemRow[];
68
+ /** Notified items whose `finished` check is due; `next_attempt_at` holds the check time. */
69
+ listCheckDue(now: number, limit: number): QueueItemRow[];
70
+ listUnnotified(now: number, limit: number): QueueItemRow[];
71
+ countItems(): Record<QueueItemRow['status'], number>;
72
+ getGrant(grantId: string): QueueGrantRow | undefined;
73
+ insertGrant(row: QueueGrantRow): boolean;
74
+ updateGrant(row: QueueGrantRow): void;
75
+ removeGrant(grantId: string): void;
76
+ listGrants(key: string): QueueGrantRow[];
77
+ getLease(leaseId: string): QueueLeaseRow | undefined;
78
+ insertLease(row: QueueLeaseRow): boolean;
79
+ updateLease(row: QueueLeaseRow): void;
80
+ /**
81
+ * Leases the holder must hear about again: those with permits in use, and
82
+ * stopped ones it has not settled. Both stay counted at the holder until
83
+ * reported, so a lost report must be repeated.
84
+ */
85
+ listRenewalsDue(now: number, limit: number): QueueLeaseRow[];
86
+ /** Drops settled leases that stopped drawing before `before`. */
87
+ removeSpentLeases(before: number): void;
88
+ listLeases(key: string): QueueLeaseRow[];
89
+ getKey(key: string): QueueKeyRow | undefined;
90
+ upsertKey(row: QueueKeyRow): void;
91
+ removeKey(key: string): void;
92
+ listDueKeys(now: number): QueueKeyRow[];
93
+ nextPendingAt(checksFinished: boolean): number | undefined;
94
+ private items;
95
+ }
@@ -0,0 +1,248 @@
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
+ /** When to report the lease again while it has permits in use, so the holder keeps it. */
49
+ renew_at: z.number().int().nonnegative(),
50
+ /** Half the lease's lifetime at the holder, from its last refresh. */
51
+ renew_ms: z.number().int().positive(),
52
+ /** 1 once the holder has settled the stopped lease; until then it is reported again. */
53
+ confirmed: z.number().int().min(0).max(1),
54
+ });
55
+ const queueItemColumns = queueItemRowSchema.keyof().options;
56
+ const queueGrantColumns = queueGrantRowSchema.keyof().options;
57
+ const queueLeaseColumns = queueLeaseRowSchema.keyof().options;
58
+ const statusCountSchema = z.object({
59
+ status: queueItemRowSchema.shape.status,
60
+ count: z.number().int().nonnegative(),
61
+ });
62
+ /**
63
+ * A semaphore client's queue: items, the grants it holds per key, and per-key
64
+ * request pacing. Due work is a key whose request time has passed with items
65
+ * queued, an admitted item whose `admit()` notification is outstanding, or a
66
+ * lease the holder must hear about again.
67
+ */
68
+ export class QueueStore {
69
+ constructor(sql) {
70
+ this.sql = sql;
71
+ }
72
+ getItem(id) {
73
+ return this.items('SELECT * FROM durability_semaphore_queue_items WHERE id = ? LIMIT 1', id)[0];
74
+ }
75
+ insertItem(row) {
76
+ return (this.sql
77
+ .exec(`INSERT INTO durability_semaphore_queue_items (${queueItemColumns.join(', ')})
78
+ VALUES (${queueItemColumns.map(() => '?').join(', ')})
79
+ ON CONFLICT(id) DO NOTHING
80
+ RETURNING id`, ...queueItemColumns.map((column) => row[column]))
81
+ .toArray().length > 0);
82
+ }
83
+ updateItem(row) {
84
+ this.sql.exec(`UPDATE durability_semaphore_queue_items
85
+ SET status = ?, grant_id = ?, lease_id = ?, admitted_at = ?, notified = ?,
86
+ attempt = ?, next_attempt_at = ?
87
+ WHERE id = ?`, row.status, row.grant_id, row.lease_id, row.admitted_at, row.notified, row.attempt, row.next_attempt_at, row.id);
88
+ }
89
+ removeItem(id) {
90
+ this.sql.exec('DELETE FROM durability_semaphore_queue_items WHERE id = ?', id);
91
+ }
92
+ listItems(key, status, limit) {
93
+ return this.items(`SELECT * FROM durability_semaphore_queue_items
94
+ WHERE key = ? AND status = ?
95
+ ORDER BY created_at ASC, id ASC
96
+ LIMIT ?`, key, status, limit);
97
+ }
98
+ listItemsByGrant(grantId) {
99
+ return this.items(`SELECT * FROM durability_semaphore_queue_items
100
+ WHERE grant_id = ?
101
+ ORDER BY created_at ASC, id ASC`, grantId);
102
+ }
103
+ /** Notified items whose `finished` check is due; `next_attempt_at` holds the check time. */
104
+ listCheckDue(now, limit) {
105
+ return this.items(`SELECT * FROM durability_semaphore_queue_items
106
+ WHERE status = 'admitted' AND notified = 1 AND next_attempt_at <= ?
107
+ ORDER BY next_attempt_at ASC
108
+ LIMIT ?`, now, limit);
109
+ }
110
+ listUnnotified(now, limit) {
111
+ return this.items(`SELECT * FROM durability_semaphore_queue_items
112
+ WHERE status = 'admitted' AND notified = 0 AND next_attempt_at <= ?
113
+ ORDER BY next_attempt_at ASC
114
+ LIMIT ?`, now, limit);
115
+ }
116
+ countItems() {
117
+ const counts = { queued: 0, claiming: 0, admitted: 0 };
118
+ for (const row of statusCountSchema.array().parse(this.sql
119
+ .exec(`SELECT status, COUNT(*) AS count FROM durability_semaphore_queue_items
120
+ GROUP BY status`)
121
+ .toArray())) {
122
+ counts[row.status] = row.count;
123
+ }
124
+ return counts;
125
+ }
126
+ getGrant(grantId) {
127
+ return queueGrantRowSchema
128
+ .optional()
129
+ .parse(this.sql
130
+ .exec('SELECT * FROM durability_semaphore_queue_grants WHERE grant_id = ? LIMIT 1', grantId)
131
+ .toArray()[0]);
132
+ }
133
+ insertGrant(row) {
134
+ return (this.sql
135
+ .exec(`INSERT INTO durability_semaphore_queue_grants (${queueGrantColumns.join(', ')})
136
+ VALUES (${queueGrantColumns.map(() => '?').join(', ')})
137
+ ON CONFLICT(grant_id) DO NOTHING
138
+ RETURNING grant_id`, ...queueGrantColumns.map((column) => row[column]))
139
+ .toArray().length > 0);
140
+ }
141
+ updateGrant(row) {
142
+ this.sql.exec(`UPDATE durability_semaphore_queue_grants
143
+ SET permits = ?, claimed = ?, confirmed = ?, admitted = ?, released = ?
144
+ WHERE grant_id = ?`, row.permits, row.claimed, row.confirmed, row.admitted, row.released, row.grant_id);
145
+ }
146
+ removeGrant(grantId) {
147
+ this.sql.exec('DELETE FROM durability_semaphore_queue_grants WHERE grant_id = ?', grantId);
148
+ }
149
+ listGrants(key) {
150
+ return queueGrantRowSchema.array().parse(this.sql
151
+ .exec(`SELECT * FROM durability_semaphore_queue_grants
152
+ WHERE key = ? ORDER BY created_at ASC, grant_id ASC`, key)
153
+ .toArray());
154
+ }
155
+ getLease(leaseId) {
156
+ return queueLeaseRowSchema
157
+ .optional()
158
+ .parse(this.sql
159
+ .exec('SELECT * FROM durability_semaphore_queue_leases WHERE lease_id = ? LIMIT 1', leaseId)
160
+ .toArray()[0]);
161
+ }
162
+ insertLease(row) {
163
+ return (this.sql
164
+ .exec(`INSERT INTO durability_semaphore_queue_leases (${queueLeaseColumns.join(', ')})
165
+ VALUES (${queueLeaseColumns.map(() => '?').join(', ')})
166
+ ON CONFLICT(lease_id) DO NOTHING
167
+ RETURNING lease_id`, ...queueLeaseColumns.map((column) => row[column]))
168
+ .toArray().length > 0);
169
+ }
170
+ updateLease(row) {
171
+ this.sql.exec(`UPDATE durability_semaphore_queue_leases
172
+ SET permits = ?, drawn = ?, released = ?, expires_at = ?,
173
+ renew_at = ?, renew_ms = ?, confirmed = ?
174
+ WHERE lease_id = ?`, row.permits, row.drawn, row.released, row.expires_at, row.renew_at, row.renew_ms, row.confirmed, row.lease_id);
175
+ }
176
+ /**
177
+ * Leases the holder must hear about again: those with permits in use, and
178
+ * stopped ones it has not settled. Both stay counted at the holder until
179
+ * reported, so a lost report must be repeated.
180
+ */
181
+ listRenewalsDue(now, limit) {
182
+ return queueLeaseRowSchema.array().parse(this.sql
183
+ .exec(`SELECT * FROM durability_semaphore_queue_leases
184
+ WHERE confirmed = 0 AND renew_at <= ?
185
+ AND (released < drawn OR expires_at <= ?)
186
+ ORDER BY renew_at ASC LIMIT ?`, now, now, limit)
187
+ .toArray());
188
+ }
189
+ /** Drops settled leases that stopped drawing before `before`. */
190
+ removeSpentLeases(before) {
191
+ this.sql.exec(`DELETE FROM durability_semaphore_queue_leases
192
+ WHERE confirmed = 1 AND expires_at < ? AND released >= drawn`, before);
193
+ }
194
+ listLeases(key) {
195
+ return queueLeaseRowSchema.array().parse(this.sql
196
+ .exec(`SELECT * FROM durability_semaphore_queue_leases
197
+ WHERE key = ? ORDER BY created_at ASC, lease_id ASC`, key)
198
+ .toArray());
199
+ }
200
+ getKey(key) {
201
+ return queueKeyRowSchema
202
+ .optional()
203
+ .parse(this.sql
204
+ .exec('SELECT * FROM durability_semaphore_queue_keys WHERE key = ? LIMIT 1', key)
205
+ .toArray()[0]);
206
+ }
207
+ upsertKey(row) {
208
+ this.sql.exec(`INSERT INTO durability_semaphore_queue_keys (key, next_request_at, queued)
209
+ VALUES (?, ?, ?)
210
+ ON CONFLICT(key) DO UPDATE SET
211
+ next_request_at = excluded.next_request_at, queued = excluded.queued`, row.key, row.next_request_at, row.queued);
212
+ }
213
+ removeKey(key) {
214
+ this.sql.exec('DELETE FROM durability_semaphore_queue_keys WHERE key = ?', key);
215
+ }
216
+ listDueKeys(now) {
217
+ return queueKeyRowSchema.array().parse(this.sql
218
+ .exec(`SELECT * FROM durability_semaphore_queue_keys
219
+ WHERE queued > 0 AND next_request_at <= ?
220
+ ORDER BY next_request_at ASC`, now)
221
+ .toArray());
222
+ }
223
+ nextPendingAt(checksFinished) {
224
+ const candidates = [
225
+ this.sql
226
+ .exec(`SELECT next_request_at AS at FROM durability_semaphore_queue_keys
227
+ WHERE queued > 0 ORDER BY next_request_at ASC LIMIT 1`)
228
+ .toArray()[0]?.['at'],
229
+ this.sql
230
+ .exec(`SELECT next_attempt_at AS at FROM durability_semaphore_queue_items
231
+ WHERE status = 'admitted' AND (notified = 0 OR ?)
232
+ ORDER BY next_attempt_at ASC LIMIT 1`, checksFinished ? 1 : 0)
233
+ .toArray()[0]?.['at'],
234
+ // An idle lease is due when it stops at its expiry, not before.
235
+ this.sql
236
+ .exec(`SELECT MIN(CASE WHEN released < drawn THEN renew_at
237
+ ELSE MAX(renew_at, expires_at) END) AS at
238
+ FROM durability_semaphore_queue_leases WHERE confirmed = 0`)
239
+ .toArray()[0]?.['at'],
240
+ ].filter((value) => typeof value === 'number');
241
+ return candidates.length === 0 ? undefined : Math.min(...candidates);
242
+ }
243
+ items(query, ...bindings) {
244
+ return queueItemRowSchema
245
+ .array()
246
+ .parse(this.sql.exec(query, ...bindings).toArray());
247
+ }
248
+ }