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/log.d.ts
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { RoutingLoad, type EnqueueResult, type LoadSnapshot } from './load.js';
|
|
3
|
+
import { type SchedulerAttachment } from './scheduler.js';
|
|
4
|
+
/**
|
|
5
|
+
* One in-flight or settled range of offsets held by a consumer. A range is
|
|
6
|
+
* redelivered under a fresh `batch_id`, so an ack from a previous holder is
|
|
7
|
+
* rejected rather than advancing a range someone else now owns.
|
|
8
|
+
*/
|
|
9
|
+
declare const logLeaseRowSchema: z.ZodObject<{
|
|
10
|
+
batch_id: z.ZodString;
|
|
11
|
+
consumer: z.ZodString;
|
|
12
|
+
first_offset: z.ZodNumber;
|
|
13
|
+
last_offset: z.ZodNumber;
|
|
14
|
+
state: z.ZodEnum<{
|
|
15
|
+
pending: "pending";
|
|
16
|
+
active: "active";
|
|
17
|
+
acked: "acked";
|
|
18
|
+
skipped: "skipped";
|
|
19
|
+
}>;
|
|
20
|
+
attempt: z.ZodNumber;
|
|
21
|
+
expires_at: z.ZodNumber;
|
|
22
|
+
created_at: z.ZodNumber;
|
|
23
|
+
}, z.core.$strip>;
|
|
24
|
+
export type LogLeaseRow = z.infer<typeof logLeaseRowSchema>;
|
|
25
|
+
export type LogBounds = {
|
|
26
|
+
/**
|
|
27
|
+
* Lowest readable offset, counting flushed segments that can be rehydrated.
|
|
28
|
+
* Equals `nextOffset` once nothing is readable.
|
|
29
|
+
*/
|
|
30
|
+
oldestOffset: number;
|
|
31
|
+
/** Lowest offset still held in the object rather than cold storage. */
|
|
32
|
+
hotOffset: number;
|
|
33
|
+
/** Offset the next appended record receives. */
|
|
34
|
+
nextOffset: number;
|
|
35
|
+
};
|
|
36
|
+
export type LogAppendInput<Body = unknown> = {
|
|
37
|
+
body: Body;
|
|
38
|
+
/**
|
|
39
|
+
* Appending the same key twice returns the first offset instead of a second
|
|
40
|
+
* record. Deduplication lasts only while the original record is retained.
|
|
41
|
+
*/
|
|
42
|
+
deduplicationKey?: string;
|
|
43
|
+
};
|
|
44
|
+
export type LogRecord<Body = unknown> = {
|
|
45
|
+
offset: number;
|
|
46
|
+
deduplicationKey: string;
|
|
47
|
+
body: Body;
|
|
48
|
+
appendedAt: number;
|
|
49
|
+
};
|
|
50
|
+
export type LogPage<Body = unknown> = {
|
|
51
|
+
records: LogRecord<Body>[];
|
|
52
|
+
/** Offset to read from next; commit this to acknowledge the page. */
|
|
53
|
+
nextOffset: number;
|
|
54
|
+
/** Records appended beyond this page. */
|
|
55
|
+
lag: number;
|
|
56
|
+
};
|
|
57
|
+
export type LogReadOptions = {
|
|
58
|
+
from: number;
|
|
59
|
+
limit?: number;
|
|
60
|
+
};
|
|
61
|
+
/** One contiguous run of records leaving the object, oldest first. */
|
|
62
|
+
export type LogSegment<Body = unknown> = {
|
|
63
|
+
firstOffset: number;
|
|
64
|
+
lastOffset: number;
|
|
65
|
+
records: LogRecord<Body>[];
|
|
66
|
+
};
|
|
67
|
+
/**
|
|
68
|
+
* Somewhere records live once they leave the object, usually R2. `write`
|
|
69
|
+
* returns a locator the log stores, and `read` hands the segment back so a
|
|
70
|
+
* lagging consumer can keep reading flushed offsets. Returning undefined from
|
|
71
|
+
* `read` means the segment is gone for good, which surfaces as truncation.
|
|
72
|
+
*/
|
|
73
|
+
export type LogColdStorage<Body = unknown> = {
|
|
74
|
+
write(segment: LogSegment<Body>): Promise<string>;
|
|
75
|
+
read(locator: string): Promise<LogRecord<Body>[] | undefined>;
|
|
76
|
+
};
|
|
77
|
+
/** A claimed range of offsets, held until acked, nacked, or expired. */
|
|
78
|
+
export type LogLease<Body = unknown> = {
|
|
79
|
+
/** Identifies this delivery. A redelivery of the same range gets a new one. */
|
|
80
|
+
batchId: string;
|
|
81
|
+
consumer: string;
|
|
82
|
+
records: LogRecord<Body>[];
|
|
83
|
+
firstOffset: number;
|
|
84
|
+
lastOffset: number;
|
|
85
|
+
/** One-based delivery attempt for this range. */
|
|
86
|
+
attempt: number;
|
|
87
|
+
expiresAt: number;
|
|
88
|
+
};
|
|
89
|
+
export type LogLeaseOptions = {
|
|
90
|
+
/** Ranges one consumer may hold at once. Defaults to 1. */
|
|
91
|
+
maxParallelism?: number;
|
|
92
|
+
/** How long a claim is held before another worker may take it. */
|
|
93
|
+
leaseMs?: number;
|
|
94
|
+
/**
|
|
95
|
+
* Attempts before a range is skipped instead of redelivered forever. Only
|
|
96
|
+
* honoured together with `onPoison`: without somewhere to send the records,
|
|
97
|
+
* blocking the consumer beats silently dropping them.
|
|
98
|
+
*/
|
|
99
|
+
maxAttempts?: number;
|
|
100
|
+
onPoison?: (lease: LogLease) => Promise<void>;
|
|
101
|
+
};
|
|
102
|
+
export type LogRetention = {
|
|
103
|
+
maxAgeMs?: number;
|
|
104
|
+
maxRecords?: number;
|
|
105
|
+
/**
|
|
106
|
+
* Payload bytes held in the object. Reaching it flushes the oldest records
|
|
107
|
+
* to cold storage, or deletes them when no cold storage is configured.
|
|
108
|
+
*/
|
|
109
|
+
maxBytes?: number;
|
|
110
|
+
};
|
|
111
|
+
export type DurabilityLogConfig<Body = unknown> = SchedulerAttachment & {
|
|
112
|
+
/** Without retention the log grows until the object's storage limit. */
|
|
113
|
+
retention?: LogRetention;
|
|
114
|
+
cold?: LogColdStorage<Body>;
|
|
115
|
+
/** Enables `lease`/`ack`/`nack`; plain `read`/`commit` needs no leases. */
|
|
116
|
+
leases?: LogLeaseOptions;
|
|
117
|
+
routing?: RoutingLoad;
|
|
118
|
+
maxBatchSize?: number;
|
|
119
|
+
};
|
|
120
|
+
/**
|
|
121
|
+
* A single object holds a hot window, not an unbounded log, so the byte
|
|
122
|
+
* budget is capped well below the platform's per-object limit.
|
|
123
|
+
*/
|
|
124
|
+
export declare const maxLogBytes = 1073741824;
|
|
125
|
+
/**
|
|
126
|
+
* A composable DO capability: an append-only record log addressed by offset,
|
|
127
|
+
* read by pulling consumers that own their cursors. Share a scheduler with
|
|
128
|
+
* operations, alarms, and fanout on the same object.
|
|
129
|
+
*
|
|
130
|
+
* Unlike fanout, records are retained rather than deleted on acknowledgement,
|
|
131
|
+
* so a consumer can rewind or a new one can start from the beginning. Records
|
|
132
|
+
* leave only through `trim`, and a consumer that falls behind retention reads a
|
|
133
|
+
* `LogTruncatedError` rather than silently skipping records.
|
|
134
|
+
*/
|
|
135
|
+
export declare class DurabilityLog<Body = unknown> {
|
|
136
|
+
#private;
|
|
137
|
+
constructor(config: DurabilityLogConfig<Body>);
|
|
138
|
+
static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): import("./migrations.js").DurabilityMigrationResult;
|
|
139
|
+
/**
|
|
140
|
+
* Appends the batch atomically. Definite input rejections return
|
|
141
|
+
* success:false; storage and commit uncertainty throws, so a caller never
|
|
142
|
+
* reads a transport failure as a definite rejection.
|
|
143
|
+
*/
|
|
144
|
+
append(records: LogAppendInput<Body> | LogAppendInput<Body>[]): Promise<EnqueueResult<number[]>>;
|
|
145
|
+
/**
|
|
146
|
+
* Reads forward from an offset. Offsets already flushed are rehydrated from
|
|
147
|
+
* cold storage, so a lagging consumer keeps reading instead of failing; only
|
|
148
|
+
* offsets below everything readable raise `LogTruncatedError`.
|
|
149
|
+
*/
|
|
150
|
+
read(options: LogReadOptions): Promise<LogPage<Body>>;
|
|
151
|
+
/** The retained window. `oldestOffset` equals `nextOffset` when empty. */
|
|
152
|
+
bounds(): Promise<LogBounds>;
|
|
153
|
+
/** Undefined until the consumer commits, so callers choose their own start. */
|
|
154
|
+
cursor(consumer: string): Promise<number | undefined>;
|
|
155
|
+
/** Records progress. Regressions are ignored, so a late commit cannot rewind. */
|
|
156
|
+
commit(consumer: string, offset: number): Promise<void>;
|
|
157
|
+
cursors(): Promise<Record<string, number>>;
|
|
158
|
+
/**
|
|
159
|
+
* Enforces retention on the oldest records: with cold storage they are
|
|
160
|
+
* flushed and stay readable through rehydration, without it they are
|
|
161
|
+
* deleted. A cold write failure propagates with the records still in the
|
|
162
|
+
* object, so configured storage cannot be skipped.
|
|
163
|
+
*
|
|
164
|
+
* Retention ignores cursors, as a log should: a consumer slower than
|
|
165
|
+
* everything readable learns through `LogTruncatedError`.
|
|
166
|
+
*/
|
|
167
|
+
trim(): Promise<number>;
|
|
168
|
+
/**
|
|
169
|
+
* Forgets flushed segments below an offset, matching whatever lifecycle rule
|
|
170
|
+
* expires them externally. Reads below the new floor then truncate.
|
|
171
|
+
*/
|
|
172
|
+
forgetColdBefore(offset: number): Promise<number>;
|
|
173
|
+
/**
|
|
174
|
+
* Claims the next unleased range for a consumer, or redelivers one whose
|
|
175
|
+
* holder nacked or let its lease expire. Returns undefined when nothing is
|
|
176
|
+
* available, either because the consumer is at `maxParallelism` or because
|
|
177
|
+
* the log has no unleased records.
|
|
178
|
+
*
|
|
179
|
+
* Two workers sharing a consumer name never receive the same offsets: the
|
|
180
|
+
* range is recorded durably before the records are returned, and a
|
|
181
|
+
* redelivery rewrites the batch id so the previous holder can no longer
|
|
182
|
+
* settle it.
|
|
183
|
+
*/
|
|
184
|
+
lease(consumer: string, limit?: number): Promise<LogLease<Body> | undefined>;
|
|
185
|
+
/**
|
|
186
|
+
* Accepts a leased range and advances the cursor over every settled range
|
|
187
|
+
* that forms an unbroken run from it, so parallel consumers commit without
|
|
188
|
+
* skipping offsets another worker is still holding.
|
|
189
|
+
*/
|
|
190
|
+
ack(consumer: string, batchId: string): Promise<void>;
|
|
191
|
+
/** Returns a leased range for redelivery under a fresh batch id. */
|
|
192
|
+
nack(consumer: string, batchId: string): Promise<void>;
|
|
193
|
+
/** In-flight and settled-but-uncommitted ranges, for operators and tests. */
|
|
194
|
+
leases(consumer: string): Promise<LogLeaseRow[]>;
|
|
195
|
+
/**
|
|
196
|
+
* Backlog is the furthest-behind committed cursor, so routing can weigh
|
|
197
|
+
* partitions by consumer lag. Without cursors there is no backlog to report.
|
|
198
|
+
*/
|
|
199
|
+
load(): Promise<LoadSnapshot>;
|
|
200
|
+
}
|
|
201
|
+
export {};
|