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.
- package/README.md +406 -1
- package/dist/dev.d.ts +22 -0
- package/dist/dev.js +149 -0
- package/dist/durability-alarms.d.ts +1 -1
- package/dist/durability-alarms.js +6 -4
- package/dist/durability.d.ts +1 -1
- package/dist/durability.js +8 -5
- package/dist/durable-object-target.d.ts +12 -0
- package/dist/durable-object-target.js +17 -0
- package/dist/errors.d.ts +25 -0
- package/dist/errors.js +36 -0
- package/dist/experimental.d.ts +8 -0
- package/dist/experimental.js +6 -0
- package/dist/fanout.js +14 -9
- package/dist/index.d.ts +2 -1
- package/dist/index.js +1 -1
- package/dist/lifecycle.d.ts +14 -3
- package/dist/lifecycle.js +3 -2
- package/dist/log.js +26 -4
- package/dist/migrations.d.ts +74 -2
- package/dist/migrations.js +307 -36
- package/dist/outbox.d.ts +85 -0
- package/dist/outbox.js +433 -0
- package/dist/routing.d.ts +2 -9
- package/dist/routing.js +2 -14
- package/dist/scheduler.d.ts +14 -2
- package/dist/scheduler.js +38 -13
- 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 +272 -0
- package/dist/semaphore-protocol.d.ts +231 -0
- package/dist/semaphore-protocol.js +106 -0
- package/dist/semaphore-queue-store.d.ts +95 -0
- package/dist/semaphore-queue-store.js +248 -0
- package/dist/semaphore-queue.d.ts +119 -0
- package/dist/semaphore-queue.js +863 -0
- package/dist/semaphore-server.d.ts +89 -0
- package/dist/semaphore-server.js +518 -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/dist/socket.js +19 -10
- package/dist/topology-client.d.ts +40 -0
- package/dist/topology-client.js +180 -0
- package/dist/topology-snapshot.d.ts +70 -0
- package/dist/topology-snapshot.js +48 -0
- package/dist/topology.d.ts +94 -0
- package/dist/topology.js +468 -0
- package/dist/tracker.js +2 -0
- package/package.json +6 -2
|
@@ -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
|
+
}
|