durability 4.2.0 → 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 +203 -2
- 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/errors.d.ts +17 -0
- package/dist/errors.js +22 -0
- package/dist/experimental.d.ts +5 -0
- package/dist/experimental.js +3 -0
- package/dist/fanout.js +14 -9
- package/dist/index.d.ts +2 -1
- package/dist/index.js +1 -1
- package/dist/lifecycle.js +3 -2
- package/dist/log.js +26 -4
- package/dist/migrations.d.ts +47 -2
- package/dist/migrations.js +132 -36
- package/dist/outbox.d.ts +13 -0
- package/dist/outbox.js +78 -30
- package/dist/scheduler.d.ts +7 -0
- package/dist/scheduler.js +26 -7
- package/dist/semaphore-leases.js +15 -9
- package/dist/semaphore-queue-store.d.ts +12 -2
- package/dist/semaphore-queue-store.js +32 -5
- package/dist/semaphore-queue.js +109 -43
- package/dist/semaphore-server.js +7 -9
- 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 +2 -2
package/README.md
CHANGED
|
@@ -7,6 +7,7 @@ Composable capabilities for application-owned Cloudflare Durable Objects:
|
|
|
7
7
|
- **`DurabilityFanout`** — durable batch acceptance and independent delivery to static consumer or storage targets.
|
|
8
8
|
- **`DurabilityOutbox`** _(experimental, `durability/experimental`)_ — keyed latest-state publication: stage the newest value for a key with the state it describes, and it is republished until acknowledged.
|
|
9
9
|
- **`DurabilitySemaphore`** _(experimental, `durability/experimental/semaphore`)_ — one concurrency limit shared by many client Durable Objects, allocated in arrival-ordered rounds with cumulative claim/release accounting.
|
|
10
|
+
- **`DurabilityTopology`** _(experimental, `durability/experimental`)_ — membership of shard groups held by one coordinator, published to a read store and pushed to every member as the latest value of each state channel, with a read-only cached client.
|
|
10
11
|
- **`DurabilityRouting`** — a DO-side load observer and client-side shard selector (`durability/routing`), supporting location hints and caller transforms.
|
|
11
12
|
- **`DurabilitySocket`** — typed WebSocket RPC and replayable event push from a Durable Object to browsers (`durability/socket`), with a dependency-free browser client (`durability/client`).
|
|
12
13
|
- **`DurabilityTracker`** _(experimental, `durability/experimental`)_ — lists work across capabilities and custom sources, as RPC handles that can be waited on or as plain records.
|
|
@@ -194,6 +195,32 @@ Passing a name moves that capability's schema to exactly that version. Each batc
|
|
|
194
195
|
|
|
195
196
|
Every history row stores its migration's `down` script. If a Durable Object later runs an older `durability` version, that version reverts the migrations it does not recognize using the stored scripts, so downgrades are safe without code changes. To guard against deploying a very old version by mistake, at most two unknown migrations are reverted; beyond that, construction throws. The `durability_migrations` table is dropped once no durability history remains.
|
|
196
197
|
|
|
198
|
+
### Application schemas
|
|
199
|
+
|
|
200
|
+
`migrate` gives an application's own tables the same guarantees. Its history lives in a separate table (`schema_migrations` unless `table` is set), so it never mixes with durability's:
|
|
201
|
+
|
|
202
|
+
```ts
|
|
203
|
+
import { DurableObject } from 'cloudflare:workers';
|
|
204
|
+
import { migrate, type DurableMigrations } from 'durability';
|
|
205
|
+
|
|
206
|
+
const migrations: DurableMigrations = [
|
|
207
|
+
{
|
|
208
|
+
name: '0001_create_jobs',
|
|
209
|
+
up: 'CREATE TABLE jobs (id TEXT PRIMARY KEY);',
|
|
210
|
+
down: 'DROP TABLE jobs;',
|
|
211
|
+
},
|
|
212
|
+
];
|
|
213
|
+
|
|
214
|
+
export class Jobs extends DurableObject {
|
|
215
|
+
constructor(ctx: DurableObjectState, env: Env) {
|
|
216
|
+
super(ctx, env);
|
|
217
|
+
migrate(ctx.storage, migrations);
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Pass `target` to move to a named migration, or `null` to revert every migration and drop the history table.
|
|
223
|
+
|
|
197
224
|
## Retries, timeouts, and terminal failures
|
|
198
225
|
|
|
199
226
|
Attempts use exponential backoff with equal jitter, stop after five attempts, and time out after five minutes by default. The retry `delay` function fully controls scheduling and can be overridden globally or per method on either helper:
|
|
@@ -268,6 +295,39 @@ const detach = durability.lifecycle((event) => {
|
|
|
268
295
|
});
|
|
269
296
|
```
|
|
270
297
|
|
|
298
|
+
## Dev mode tracing
|
|
299
|
+
|
|
300
|
+
Define `__DURABILITY_DEV__` as `true` at build time to log every operation the package performs. Each entry is a structured `console.debug` object whose `event` starts with `durability.dev.`:
|
|
301
|
+
|
|
302
|
+
| `event` | Logged for |
|
|
303
|
+
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
304
|
+
| `durability.dev.call` | Each public method call on every helper, including the experimental outbox and semaphores, generated operation, alarm, and socket outbound methods, and fanout `ack`, `retry`, and `deadLetter`, with its arguments. |
|
|
305
|
+
| `durability.dev.call.return` / `.call.throw` | The call's result or serialized error, linked to the call by `call`. |
|
|
306
|
+
| `durability.dev.storage` | Each storage method: transactions and alarm reads and writes, including those inside `transaction`. |
|
|
307
|
+
| `durability.dev.storage.return` / `.storage.throw` | The storage call's result or serialized error, linked by `call`. |
|
|
308
|
+
| `durability.dev.sql` | Each SQL statement, whitespace-compacted, with its bindings. |
|
|
309
|
+
| `durability.dev.lifecycle` | Every lifecycle event, whether or not a hook is attached. |
|
|
310
|
+
| `durability.dev.scheduler.early_alarm` | An in-memory timer that runs due work before the physical alarm. |
|
|
311
|
+
| `durability.dev.socket.send` / `.socket.close` | Each frame sent to a browser socket, and each socket closed for a protocol error. |
|
|
312
|
+
|
|
313
|
+
Every entry carries `seq`, a process-wide counter that orders entries across interleaved async work, and `at`, the `Date.now()` reading when it was logged. A deterministic simulation that controls time, randomness, and scheduling gets a replayable transcript by collecting the entries in order, for example with `vi.spyOn(console, 'debug')`.
|
|
314
|
+
|
|
315
|
+
Set the flag with the bundler's `define`:
|
|
316
|
+
|
|
317
|
+
```jsonc
|
|
318
|
+
// wrangler.jsonc
|
|
319
|
+
{ "define": { "__DURABILITY_DEV__": "true" } }
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
```ts
|
|
323
|
+
// vite.config.ts or vitest.config.ts
|
|
324
|
+
export default defineConfig({
|
|
325
|
+
define: { __DURABILITY_DEV__: 'true' },
|
|
326
|
+
});
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
Leave it undefined or define it as `false` in production. With `false`, the bundler drops the tracing code entirely; left undefined, each traced call costs one branch. Tracing logs payloads, results, and SQL bindings verbatim, so never enable it where those contain secrets. In this repository, `DURABILITY_DEV=1 pnpm --filter durability test` runs the test suite in dev mode.
|
|
330
|
+
|
|
271
331
|
## Browser sockets
|
|
272
332
|
|
|
273
333
|
`DurabilitySocket` lets browsers call a Durable Object and receive events from it over one hibernatable WebSocket. `inbound` handlers become callable methods on the client; `outbound` events become methods on the socket that push to every subscribed connection. Nothing outside `inbound` is reachable, and no result is broadcast unless an outbound method sends it.
|
|
@@ -591,7 +651,7 @@ new DurabilitySemaphore({
|
|
|
591
651
|
- **`under`** — a reserve inside the limit is kept for leases; grants may use at most `limit - reserve`. Still never exceeds the limit, and leases have guaranteed headroom. The reserve never takes the last permit: with a reserve at or above the limit (including after lowering the limit), grants keep one, so groups excluded from leases and clients without lease support still make progress.
|
|
592
652
|
- **`over`** — leases come from a separate budget above the limit (the original gatekeeper behaviour); the effective ceiling is `limit + extra`.
|
|
593
653
|
|
|
594
|
-
Leases are issued only to clients that report `leases` (the queue always does), to groups without their own limit unless `limitedGroups: 'withinGroupLimit'`, and only to a client that holds no undrawn permits for that group. Each round shares the remaining lease budget equally among candidates, oldest demand first, up to `permitsPerLease`; with fewer permits left than candidates, the oldest get one each. When a round leaves demand unserved, the holder marks its replies `contended`, and each client returns the undrawn permits of leases in groups where it has nothing queued, so an idle lease cannot keep other clients waiting. A client that stops talking to the holder keeps its lease until `ttlMs`. Reports (`drawn`, `released` high-water marks) heartbeat a lease;
|
|
654
|
+
Leases are issued only to clients that report `leases` (the queue always does), to groups without their own limit unless `limitedGroups: 'withinGroupLimit'`, and only to a client that holds no undrawn permits for that group. Each round shares the remaining lease budget equally among candidates, oldest demand first, up to `permitsPerLease`; with fewer permits left than candidates, the oldest get one each. When a round leaves demand unserved, the holder marks its replies `contended`, and each client returns the undrawn permits of leases in groups where it has nothing queued, so an idle lease cannot keep other clients waiting. A client that stops talking to the holder keeps its lease until `ttlMs`. Reports (`drawn`, `released` high-water marks) heartbeat a lease, and the queue reports a lease with permits in use at half its lifetime even when nothing else is happening, so long-running work keeps its permits counted; a lease unreported for `ttlMs` is retired rather than forgotten: its client may be cut off from the holder with work still running, so, like a claimed grant permit, its footprint stays counted until the client reports what it drew and released. The queue keeps reporting a stopped lease until the holder settles it. A report for a lease the holder never knew is answered retired and its live footprint charged against that round. On the client, a drawn permit is one-shot: releasing the item returns footprint to the holder but never makes the permit drawable again. Lowering a group's eligibility, or the limit, retires leases on the next round. A retired lease stops drawing at once but stays counted in full until its client confirms how much it drew, since it may have drawn after its last report.
|
|
595
655
|
|
|
596
656
|
### Queueing work in a client Durable Object
|
|
597
657
|
|
|
@@ -876,6 +936,147 @@ export class Account extends DurableObject<Env> {
|
|
|
876
936
|
|
|
877
937
|
`DurabilityOutbox.migrate(this.ctx, null)` removes the outbox schema.
|
|
878
938
|
|
|
939
|
+
## Shard topology (experimental)
|
|
940
|
+
|
|
941
|
+
`DurabilityTopology` is for work spread over several Durable Objects (shards) whose membership changes over time, where something else needs to reach them: a router picking a shard for a write, a reader querying every shard, or a coordinator pushing configuration to all of them. It lives in `durability/experimental`, so pin an exact version.
|
|
942
|
+
|
|
943
|
+
One coordinator Durable Object holds each group. It is the only thing that can change or publish that group. Readers never call it: they read the snapshot it published.
|
|
944
|
+
|
|
945
|
+
```ts
|
|
946
|
+
import {
|
|
947
|
+
DurabilityTopology,
|
|
948
|
+
type TopologyStateUpdate,
|
|
949
|
+
} from 'durability/experimental';
|
|
950
|
+
|
|
951
|
+
export class Coordinator extends DurableObject<Env> {
|
|
952
|
+
private readonly scheduler = new DurabilityScheduler({ context: this.ctx });
|
|
953
|
+
private readonly topology = new DurabilityTopology({
|
|
954
|
+
scheduler: this.scheduler,
|
|
955
|
+
publish: {
|
|
956
|
+
write: (snapshot, encoded) =>
|
|
957
|
+
this.env.TOPOLOGY.put(`topology/${snapshot.group}`, encoded),
|
|
958
|
+
delete: (group) => this.env.TOPOLOGY.delete(`topology/${group}`),
|
|
959
|
+
},
|
|
960
|
+
states: {
|
|
961
|
+
limits: {
|
|
962
|
+
deliver: (member, update: TopologyStateUpdate<Limits>) =>
|
|
963
|
+
this.env.SHARDS.getByName(member.id).applyLimits(update),
|
|
964
|
+
},
|
|
965
|
+
},
|
|
966
|
+
});
|
|
967
|
+
|
|
968
|
+
createTenant(tenant: string, limits: Limits) {
|
|
969
|
+
return this.topology.update(tenant, () => ({
|
|
970
|
+
members: [0, 1, 2].map((n) => ({
|
|
971
|
+
id: `${tenant}-${n}`,
|
|
972
|
+
state: 'active' as const,
|
|
973
|
+
})),
|
|
974
|
+
states: { limits },
|
|
975
|
+
}));
|
|
976
|
+
}
|
|
977
|
+
|
|
978
|
+
retireShard(tenant: string, shard: string) {
|
|
979
|
+
return this.topology.update(tenant, ({ members }) => ({
|
|
980
|
+
members: [
|
|
981
|
+
...members.map((m) =>
|
|
982
|
+
m.id === shard ? { ...m, state: 'draining' as const } : m
|
|
983
|
+
),
|
|
984
|
+
{ id: `${tenant}-${members.length}`, state: 'active' },
|
|
985
|
+
],
|
|
986
|
+
}));
|
|
987
|
+
}
|
|
988
|
+
|
|
989
|
+
deleteTenant(tenant: string) {
|
|
990
|
+
return this.topology.delete(tenant);
|
|
991
|
+
}
|
|
992
|
+
|
|
993
|
+
alarm(info?: AlarmInvocationInfo) {
|
|
994
|
+
return this.scheduler.alarm(info);
|
|
995
|
+
}
|
|
996
|
+
}
|
|
997
|
+
```
|
|
998
|
+
|
|
999
|
+
The coordinator has three methods:
|
|
1000
|
+
|
|
1001
|
+
- `update(group, next)` runs `next(current)` inside one storage transaction and commits its draft, staging publication and deliveries in the same transaction. `current` holds the members and the current state values. The draft can set `members`, `states`, or both, and `next` must return synchronously, so nothing interleaves between reading and writing. Membership changes bump the group's `version`; unchanged drafts do not. After the commit, one publish is attempted: `published: false` means the snapshot is not yet final in the store, because the write failed or an older write may still land over it. The change is committed either way, and the outbox keeps going until it is. An empty member list is rejected; use `delete`.
|
|
1002
|
+
- `delete(group)` drops the members and state values, cancels pending syncs, and asks the publisher to delete the snapshot. Versions keep counting, so a recreated group is newer than anything a reader cached.
|
|
1003
|
+
- `snapshot(group)` reads the group inside the coordinator. It is not a lookup path for other Workers.
|
|
1004
|
+
|
|
1005
|
+
An `active` member is in the write set and the read set. A `draining` member is only in the read set: it receives no new work but still holds data, so queries must still reach it. Members leave the read set only when a draft omits them.
|
|
1006
|
+
|
|
1007
|
+
### When to use it
|
|
1008
|
+
|
|
1009
|
+
Topology is for when something needs the list of shards. A shard that only does work when a caller reaches it, and only talks to a coordinator whose name it can derive, does not need one: create it on demand.
|
|
1010
|
+
|
|
1011
|
+
| Need | Use |
|
|
1012
|
+
| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
1013
|
+
| A shard does work when a caller sends it something | Nothing: address it by name, for example with `DurabilityRouting` |
|
|
1014
|
+
| A shard asks a central object for something it needs, such as permits or capacity | `DurabilitySemaphore`: shards pull, and the holder learns about them from their requests |
|
|
1015
|
+
| A caller must pick among a group's current shards | Topology membership |
|
|
1016
|
+
| A reader must reach every shard that may hold data | Topology membership, including `draining` members |
|
|
1017
|
+
| Every shard must hold the same data before any caller reaches it, such as schedules it runs by itself or configuration it enforces | A topology state channel |
|
|
1018
|
+
|
|
1019
|
+
A state channel sends one value to every member in its role. Values that differ per shard, or that must be accounted for in both directions (granted, used, returned), do not fit it; that is the semaphore's model.
|
|
1020
|
+
|
|
1021
|
+
A shard created on demand can still join its group, so readers can find it later: its first request can call the coordinator, which adds it with one `update`. Only do this when a reader needs it.
|
|
1022
|
+
|
|
1023
|
+
### Publishing
|
|
1024
|
+
|
|
1025
|
+
`publish.write` receives the snapshot and an `encoded` string. Store `encoded` as is; it is the only format the client reads, and no encoder is exported, so only the coordinator can produce one. It carries the coordinator's Durable Object ID, because versions only compare within one coordinator: if a group moves to another coordinator, its versions start over, and readers accept the new snapshot. Publication runs on a `DurabilityOutbox` channel (`durability.topology`) keyed by group, so it shares the outbox's guarantees: only the newest snapshot of a group is pending, publish calls for the channel run one at a time, and attempts never stop (`retries.delay` controls backoff). The outbox expects sinks to keep the highest version, which a plain `KV.put` cannot, so the topology closes that gap itself, durably:
|
|
1026
|
+
|
|
1027
|
+
- Every write is recorded in storage before it starts and forgotten once it settles.
|
|
1028
|
+
- A record that outlives its write, because the write timed out or the object was evicted mid-write, means an older snapshot may still land. A newer write is then not acknowledged until that record's landing deadline has passed, and is written again at that point.
|
|
1029
|
+
- An abandoned write that settles while the object is still running restages the latest snapshot immediately.
|
|
1030
|
+
|
|
1031
|
+
The landing deadline is the write's start plus `attemptTimeoutMs` plus five minutes. A write that lands later than that can still overwrite a newer snapshot until the next change; only a sink that keeps the highest version avoids that bound. `attemptTimeoutMs` bounds one write.
|
|
1032
|
+
|
|
1033
|
+
### State channels
|
|
1034
|
+
|
|
1035
|
+
Each entry in `states` is a channel whose latest value every member converges to. `members: 'write'` (the default) reaches active members; `'read'` reaches draining members too. Setting a value delivers it to every member in the role. A member that enters the role receives the current value in the same transaction that added it, so a new shard never starts with an old value. A member that leaves the role has its pending delivery discarded; one already in flight may still arrive. Each channel is its own outbox channel (`durability.topology.<name>`) keyed by group and member, so every member is retried independently; `attemptTimeoutMs` bounds one delivery, and a member that hangs holds up the rest of its batch only until then. Setting a channel to the value it already has delivers nothing.
|
|
1036
|
+
|
|
1037
|
+
Only the latest value is delivered, and a timed-out delivery may still arrive after a newer one. `version` is the outbox version, which only increases. Apply an update only when it is newer than the last one applied, in the same transaction:
|
|
1038
|
+
|
|
1039
|
+
```ts
|
|
1040
|
+
applyLimits(update: TopologyStateUpdate<Limits>) {
|
|
1041
|
+
this.ctx.storage.transactionSync(() => {
|
|
1042
|
+
const applied = this.ctx.storage.kv.get<number>('limits:version') ?? 0;
|
|
1043
|
+
if (update.version <= applied) {
|
|
1044
|
+
return;
|
|
1045
|
+
}
|
|
1046
|
+
this.ctx.storage.kv.put('limits', update.value);
|
|
1047
|
+
this.ctx.storage.kv.put('limits:version', update.version);
|
|
1048
|
+
});
|
|
1049
|
+
}
|
|
1050
|
+
```
|
|
1051
|
+
|
|
1052
|
+
`onLifecycleEvent` receives the outbox events of those channels: `channel` names the publication or state channel, and `id` is the group, or `[group, member]` as JSON for a delivery.
|
|
1053
|
+
|
|
1054
|
+
### Reading
|
|
1055
|
+
|
|
1056
|
+
Stateless Workers read through a client. It has one method:
|
|
1057
|
+
|
|
1058
|
+
```ts
|
|
1059
|
+
const topology = DurabilityTopology.client({
|
|
1060
|
+
read: (tenant) => env.TOPOLOGY.get(`topology/${tenant}`),
|
|
1061
|
+
});
|
|
1062
|
+
|
|
1063
|
+
const { members } = await topology.get(tenant);
|
|
1064
|
+
const writable = members.filter((member) => member.state === 'active');
|
|
1065
|
+
const shard = writable[Math.floor(Math.random() * writable.length)];
|
|
1066
|
+
```
|
|
1067
|
+
|
|
1068
|
+
Routing, querying every member, and resolving stubs are ordinary code over `members`.
|
|
1069
|
+
|
|
1070
|
+
The client caches each group in the isolate for `ttlMs` (default 30 seconds, jittered by ±20%), shares one read between concurrent callers, and never replaces a snapshot with an older version from the same coordinator. A missing or failed read is remembered for `negativeTtlMs` (default 5 seconds). Reads time out after `readTimeoutMs` (default 1 second).
|
|
1071
|
+
|
|
1072
|
+
When the published copy is missing, invalid, slow, or the read throws, `get` throws `TopologyUnavailableError` with a `reason`. Every fallback is opt-in, and they run in this order:
|
|
1073
|
+
|
|
1074
|
+
1. `staleIfErrorMs` serves this isolate's last good snapshot for that long after it expired. It never applies to a missing group.
|
|
1075
|
+
2. `seed(group)` derives members locally, without I/O.
|
|
1076
|
+
3. `fallback(group, reason)` is application code and is not cached.
|
|
1077
|
+
|
|
1078
|
+
The client never contacts the coordinator. Wiring `fallback` to it moves every reader onto one Durable Object at the moment the read store is struggling, so prefer failing or serving stale. `onFallback` reports each fallback and its source.
|
|
1079
|
+
|
|
879
1080
|
## Retained log
|
|
880
1081
|
|
|
881
1082
|
Fanout deletes a record once every target settles it, which is what a work queue wants. A log wants the opposite: records are **retained** so a consumer can rewind, a new consumer can start from the beginning, and several consumers can read the same history at different speeds. `DurabilityLog` is that second shape, and it attaches to the same scheduler.
|
|
@@ -962,7 +1163,7 @@ type LogColdStorage<Body> = {
|
|
|
962
1163
|
|
|
963
1164
|
External storage expires on its own schedule, so mirror a lifecycle rule with `forgetColdBefore(offset)` to drop stale index entries. Returning `undefined` from `read` is also honoured: a segment the index outlived surfaces as truncation rather than a silent gap.
|
|
964
1165
|
|
|
965
|
-
Retention still **ignores cursors**, exactly as a log should: a consumer slower than everything readable loses records. It learns loudly rather than silently skipping, because reading below the oldest readable offset throws `LogTruncatedError` carrying `requestedOffset` and `oldestOffset`. Compare `bounds()` against a cursor to detect the risk before it happens.
|
|
1166
|
+
Retention still **ignores cursors**, exactly as a log should: a consumer slower than everything readable loses records. It learns loudly rather than silently skipping, because reading below the oldest readable offset throws `LogTruncatedError` carrying `requestedOffset` and `oldestOffset`. Leased consumers learn the same way: when a range awaiting redelivery (nacked or expired) was trimmed, `lease()` throws `LogTruncatedError` once, drops the trimmed offsets from the range, and the next call carries on from what is still retained. A leased consumer's cursor moves past offsets trimmed before anyone leased them. Compare `bounds()` against a cursor to detect the risk before it happens.
|
|
966
1167
|
|
|
967
1168
|
### Leases for parallel consumers
|
|
968
1169
|
|
package/dist/dev.d.ts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Logs one dev-mode trace entry and returns its sequence number. The sequence
|
|
3
|
+
* is process-wide and monotonic so interleaved async work can be reordered
|
|
4
|
+
* and correlated when replaying a simulation.
|
|
5
|
+
*/
|
|
6
|
+
export declare const trace: (operation: string, details?: Record<string, unknown>) => number;
|
|
7
|
+
/**
|
|
8
|
+
* Wraps a public function so dev mode logs its arguments and outcome. `details`
|
|
9
|
+
* identifies the receiver when the arguments alone do not.
|
|
10
|
+
*/
|
|
11
|
+
export declare const traceFunction: <Args extends unknown[], Result>(method: string, fn: (...args: Args) => Result, details?: Record<string, unknown>) => ((...args: Args) => Result);
|
|
12
|
+
/** Wraps every method on a class prototype with {@link traceFunction}. */
|
|
13
|
+
export declare const traceMethods: (prototype: object, owner: string) => void;
|
|
14
|
+
/** Logs each lifecycle event before `emit` hands it to the consumer's hooks. */
|
|
15
|
+
export declare const traceLifecycle: <Event extends Record<string, unknown>>(emit: (event: Event) => void) => ((event: Event) => void);
|
|
16
|
+
/**
|
|
17
|
+
* In dev mode, returns a view of Durable Object storage that logs every SQL
|
|
18
|
+
* statement, transaction, and alarm read or write. Outside dev mode, returns
|
|
19
|
+
* the storage unchanged. Idempotent, so helpers sharing one storage log each
|
|
20
|
+
* call once.
|
|
21
|
+
*/
|
|
22
|
+
export declare const traceStorage: <Storage extends object>(storage: Storage) => Storage;
|
package/dist/dev.js
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
import { serializeError } from './errors.js';
|
|
2
|
+
/**
|
|
3
|
+
* True only when the build defines `__DURABILITY_DEV__` as `true`. Bundlers
|
|
4
|
+
* fold the check to a constant, so production builds pay one branch per
|
|
5
|
+
* traced call and log nothing.
|
|
6
|
+
*/
|
|
7
|
+
const devMode = typeof __DURABILITY_DEV__ === 'boolean' && __DURABILITY_DEV__;
|
|
8
|
+
let sequence = 0;
|
|
9
|
+
/**
|
|
10
|
+
* Logs one dev-mode trace entry and returns its sequence number. The sequence
|
|
11
|
+
* is process-wide and monotonic so interleaved async work can be reordered
|
|
12
|
+
* and correlated when replaying a simulation.
|
|
13
|
+
*/
|
|
14
|
+
export const trace = (operation, details = {}) => {
|
|
15
|
+
if (!devMode) {
|
|
16
|
+
return 0;
|
|
17
|
+
}
|
|
18
|
+
sequence += 1;
|
|
19
|
+
// Tracing is best-effort: a logger that throws must not change the operation.
|
|
20
|
+
try {
|
|
21
|
+
console.debug({
|
|
22
|
+
event: `durability.dev.${operation}`,
|
|
23
|
+
seq: sequence,
|
|
24
|
+
at: Date.now(),
|
|
25
|
+
...details,
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
catch {
|
|
29
|
+
// Keep the sequence number so later entries still order correctly.
|
|
30
|
+
}
|
|
31
|
+
return sequence;
|
|
32
|
+
};
|
|
33
|
+
const traceCall = (operation, details, run) => {
|
|
34
|
+
const call = trace(operation, details);
|
|
35
|
+
let result;
|
|
36
|
+
try {
|
|
37
|
+
result = run();
|
|
38
|
+
}
|
|
39
|
+
catch (error) {
|
|
40
|
+
trace(`${operation}.throw`, { call, error: serializeError(error) });
|
|
41
|
+
throw error;
|
|
42
|
+
}
|
|
43
|
+
if (!(result instanceof Promise)) {
|
|
44
|
+
trace(`${operation}.return`, { call, result });
|
|
45
|
+
return result;
|
|
46
|
+
}
|
|
47
|
+
// Observes the promise without changing what the caller sees.
|
|
48
|
+
void result.then((value) => trace(`${operation}.return`, { call, result: value }), (error) => trace(`${operation}.throw`, { call, error: serializeError(error) }));
|
|
49
|
+
return result;
|
|
50
|
+
};
|
|
51
|
+
const loggableArgs = (args) => args.filter((arg) => typeof arg !== 'function');
|
|
52
|
+
/**
|
|
53
|
+
* Wraps a public function so dev mode logs its arguments and outcome. `details`
|
|
54
|
+
* identifies the receiver when the arguments alone do not.
|
|
55
|
+
*/
|
|
56
|
+
export const traceFunction = (method, fn, details = {}) => {
|
|
57
|
+
if (!devMode) {
|
|
58
|
+
return fn;
|
|
59
|
+
}
|
|
60
|
+
return function (...args) {
|
|
61
|
+
return traceCall('call', { method, ...details, args: loggableArgs(args) }, () => fn.apply(this, args));
|
|
62
|
+
};
|
|
63
|
+
};
|
|
64
|
+
/** Wraps every method on a class prototype with {@link traceFunction}. */
|
|
65
|
+
export const traceMethods = (prototype, owner) => {
|
|
66
|
+
if (!devMode) {
|
|
67
|
+
return;
|
|
68
|
+
}
|
|
69
|
+
for (const name of Object.getOwnPropertyNames(prototype)) {
|
|
70
|
+
const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
|
|
71
|
+
if (name === 'constructor' || typeof descriptor?.value !== 'function') {
|
|
72
|
+
continue;
|
|
73
|
+
}
|
|
74
|
+
Object.defineProperty(prototype, name, {
|
|
75
|
+
...descriptor,
|
|
76
|
+
value: traceFunction(`${owner}.${name}`, descriptor.value),
|
|
77
|
+
});
|
|
78
|
+
}
|
|
79
|
+
};
|
|
80
|
+
/** Logs each lifecycle event before `emit` hands it to the consumer's hooks. */
|
|
81
|
+
export const traceLifecycle = (emit) => {
|
|
82
|
+
if (!devMode) {
|
|
83
|
+
return emit;
|
|
84
|
+
}
|
|
85
|
+
return (event) => {
|
|
86
|
+
trace('lifecycle', event);
|
|
87
|
+
emit(event);
|
|
88
|
+
};
|
|
89
|
+
};
|
|
90
|
+
const compactQuery = (query) => query.replace(/\s+/g, ' ').trim();
|
|
91
|
+
const traceSql = (sql) => new Proxy(sql, {
|
|
92
|
+
get(target, key) {
|
|
93
|
+
const value = Reflect.get(target, key);
|
|
94
|
+
if (key === 'exec') {
|
|
95
|
+
return (query, ...bindings) => {
|
|
96
|
+
trace('sql', { query: compactQuery(query), bindings });
|
|
97
|
+
return target.exec(query, ...bindings);
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
return typeof value === 'function' ? value.bind(target) : value;
|
|
101
|
+
},
|
|
102
|
+
});
|
|
103
|
+
const proxyStorage = (storage, scope) => {
|
|
104
|
+
let sql;
|
|
105
|
+
return new Proxy(storage, {
|
|
106
|
+
get(target, key) {
|
|
107
|
+
const value = Reflect.get(target, key);
|
|
108
|
+
if (key === 'sql' && value !== undefined) {
|
|
109
|
+
sql ?? (sql = traceSql(value));
|
|
110
|
+
return sql;
|
|
111
|
+
}
|
|
112
|
+
if (typeof value !== 'function') {
|
|
113
|
+
return value;
|
|
114
|
+
}
|
|
115
|
+
const method = `${scope}.${String(key)}`;
|
|
116
|
+
return (...args) => {
|
|
117
|
+
// Alarm writes inside `transaction` go through the transaction object.
|
|
118
|
+
const forwarded = key === 'transaction' && typeof args[0] === 'function'
|
|
119
|
+
? [
|
|
120
|
+
(transaction) => args[0](proxyStorage(transaction, 'transaction')),
|
|
121
|
+
...args.slice(1),
|
|
122
|
+
]
|
|
123
|
+
: args;
|
|
124
|
+
return traceCall('storage', { method, args: loggableArgs(args) }, () => Reflect.apply(value, target, forwarded));
|
|
125
|
+
};
|
|
126
|
+
},
|
|
127
|
+
});
|
|
128
|
+
};
|
|
129
|
+
const tracedStorage = new WeakMap();
|
|
130
|
+
const storageProxies = new WeakSet();
|
|
131
|
+
/**
|
|
132
|
+
* In dev mode, returns a view of Durable Object storage that logs every SQL
|
|
133
|
+
* statement, transaction, and alarm read or write. Outside dev mode, returns
|
|
134
|
+
* the storage unchanged. Idempotent, so helpers sharing one storage log each
|
|
135
|
+
* call once.
|
|
136
|
+
*/
|
|
137
|
+
export const traceStorage = (storage) => {
|
|
138
|
+
if (!devMode || storageProxies.has(storage)) {
|
|
139
|
+
return storage;
|
|
140
|
+
}
|
|
141
|
+
const existing = tracedStorage.get(storage);
|
|
142
|
+
if (existing) {
|
|
143
|
+
return existing;
|
|
144
|
+
}
|
|
145
|
+
const traced = proxyStorage(storage, 'storage');
|
|
146
|
+
tracedStorage.set(storage, traced);
|
|
147
|
+
storageProxies.add(traced);
|
|
148
|
+
return traced;
|
|
149
|
+
};
|
|
@@ -50,7 +50,7 @@ export type DurableNamedAlarm = (scheduledTime: number) => Promise<void>;
|
|
|
50
50
|
declare class DurabilityAlarmsCore<Names extends string> {
|
|
51
51
|
#private;
|
|
52
52
|
constructor(config: DurabilityAlarmsConfig<Names>);
|
|
53
|
-
/** Applies or reverts the `durability_alarms` schema; see {@link
|
|
53
|
+
/** Applies or reverts the `durability_alarms` schema; see {@link migrateCapability}. */
|
|
54
54
|
static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
|
|
55
55
|
/** Runs due named alarms and re-arms the physical alarm. */
|
|
56
56
|
alarm(info?: AlarmInvocationInfo): Promise<void>;
|
|
@@ -11,9 +11,10 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
|
|
|
11
11
|
};
|
|
12
12
|
var _DurabilityAlarmsCore_instances, _DurabilityAlarmsCore_engine, _DurabilityAlarmsCore_handlers, _DurabilityAlarmsCore_policy, _DurabilityAlarmsCore_lifecycle, _DurabilityAlarmsCore_emit, _DurabilityAlarmsCore_active, _DurabilityAlarmsCore_trackedSource, _DurabilityAlarmsCore_runDue, _DurabilityAlarmsCore_schedule, _DurabilityAlarmsCore_execute;
|
|
13
13
|
import { z } from 'zod';
|
|
14
|
+
import { traceFunction, traceMethods } from './dev.js';
|
|
14
15
|
import { DurableAlarmTimeoutError, DurableAttemptsExhaustedError, isErrorInstance, NonRetryableError, } from './errors.js';
|
|
15
16
|
import { createLifecycleHooks, } from './lifecycle.js';
|
|
16
|
-
import { durabilityNamedAlarmMigrations,
|
|
17
|
+
import { durabilityNamedAlarmMigrations, migrateCapability, } from './migrations.js';
|
|
17
18
|
import { alarmMethodOptionsSchema, createPolicyResolver, } from './policy.js';
|
|
18
19
|
import { engineFor, } from './scheduler.js';
|
|
19
20
|
import { deleteAttempt, listCreated } from './storage.js';
|
|
@@ -83,7 +84,7 @@ class DurabilityAlarmsCore {
|
|
|
83
84
|
throw new Error(`"${name}" is reserved by DurabilityAlarms`);
|
|
84
85
|
}
|
|
85
86
|
Object.defineProperty(this, name, {
|
|
86
|
-
value: (scheduledTime) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_schedule).call(this, name, scheduledTime),
|
|
87
|
+
value: traceFunction(`DurabilityAlarms.${name}`, (scheduledTime) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_schedule).call(this, name, scheduledTime)),
|
|
87
88
|
enumerable: true,
|
|
88
89
|
});
|
|
89
90
|
}
|
|
@@ -94,9 +95,9 @@ class DurabilityAlarmsCore {
|
|
|
94
95
|
});
|
|
95
96
|
registerTrackedSource(this, __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_trackedSource).call(this));
|
|
96
97
|
}
|
|
97
|
-
/** Applies or reverts the `durability_alarms` schema; see {@link
|
|
98
|
+
/** Applies or reverts the `durability_alarms` schema; see {@link migrateCapability}. */
|
|
98
99
|
static migrate(context, target) {
|
|
99
|
-
return
|
|
100
|
+
return migrateCapability(context.storage, 'namedAlarms', durabilityNamedAlarmMigrations, target);
|
|
100
101
|
}
|
|
101
102
|
/** Runs due named alarms and re-arms the physical alarm. */
|
|
102
103
|
alarm(info) {
|
|
@@ -259,6 +260,7 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
|
|
|
259
260
|
isTerminal: (error) => isErrorInstance(error, DurableAlarmTimeoutError) && !retryTimeouts,
|
|
260
261
|
});
|
|
261
262
|
};
|
|
263
|
+
traceMethods(DurabilityAlarmsCore.prototype, 'DurabilityAlarms');
|
|
262
264
|
// See Durability: members derived from the handler names cannot be declared on
|
|
263
265
|
// the class, so the constructor is typed separately.
|
|
264
266
|
export const DurabilityAlarms = DurabilityAlarmsCore;
|
package/dist/durability.d.ts
CHANGED
|
@@ -133,7 +133,7 @@ export type DurabilityConfig<Handlers extends HandlerMap = HandlerMap> = Durabil
|
|
|
133
133
|
declare class DurabilityCore<Handlers extends HandlerMap> {
|
|
134
134
|
#private;
|
|
135
135
|
constructor(config: DurabilityConfig<Handlers>);
|
|
136
|
-
/** Applies or reverts the `durability_calls` schema; see {@link
|
|
136
|
+
/** Applies or reverts the `durability_calls` schema; see {@link migrateCapability}. */
|
|
137
137
|
static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
|
|
138
138
|
/** Processes due operations and re-arms the physical alarm. */
|
|
139
139
|
alarm(info?: AlarmInvocationInfo): Promise<void>;
|
package/dist/durability.js
CHANGED
|
@@ -11,9 +11,10 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
|
|
|
11
11
|
};
|
|
12
12
|
var _DurabilityCore_instances, _DurabilityCore_engine, _DurabilityCore_handlers, _DurabilityCore_policy, _DurabilityCore_lifecycle, _DurabilityCore_emit, _DurabilityCore_active, _DurabilityCore_executionStarts, _DurabilityCore_trackedSource, _DurabilityCore_runDue, _DurabilityCore_getResult, _DurabilityCore_run, _DurabilityCore_execute, _DurabilityCore_start;
|
|
13
13
|
import { z } from 'zod';
|
|
14
|
+
import { traceFunction, traceMethods } from './dev.js';
|
|
14
15
|
import { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, isErrorInstance, NonRetryableError, reportFailure, } from './errors.js';
|
|
15
16
|
import { createLifecycleHooks, } from './lifecycle.js';
|
|
16
|
-
import { durabilityOperationMigrations,
|
|
17
|
+
import { durabilityOperationMigrations, migrateCapability, } from './migrations.js';
|
|
17
18
|
import { createPolicyResolver, methodOptionsSchema, } from './policy.js';
|
|
18
19
|
import { engineFor, } from './scheduler.js';
|
|
19
20
|
import { canonical, deserialize, serialize } from './serialization.js';
|
|
@@ -100,8 +101,9 @@ class DurabilityCore {
|
|
|
100
101
|
if (reserved.has(operation)) {
|
|
101
102
|
throw new Error(`"${operation}" is reserved by Durability`);
|
|
102
103
|
}
|
|
103
|
-
const method = (input) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_run).call(this, { ...input, operation })
|
|
104
|
-
|
|
104
|
+
const method = Object.assign(traceFunction(`Durability.${operation}`, (input) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_run).call(this, { ...input, operation })), {
|
|
105
|
+
getResult: traceFunction(`Durability.${operation}.getResult`, (idempotencyKey) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_getResult).call(this, operation, idempotencyKey)),
|
|
106
|
+
});
|
|
105
107
|
Object.defineProperty(this, operation, {
|
|
106
108
|
value: method,
|
|
107
109
|
enumerable: true,
|
|
@@ -114,9 +116,9 @@ class DurabilityCore {
|
|
|
114
116
|
});
|
|
115
117
|
registerTrackedSource(this, __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_trackedSource).call(this));
|
|
116
118
|
}
|
|
117
|
-
/** Applies or reverts the `durability_calls` schema; see {@link
|
|
119
|
+
/** Applies or reverts the `durability_calls` schema; see {@link migrateCapability}. */
|
|
118
120
|
static migrate(context, target) {
|
|
119
|
-
return
|
|
121
|
+
return migrateCapability(context.storage, 'operations', durabilityOperationMigrations, target);
|
|
120
122
|
}
|
|
121
123
|
/** Processes due operations and re-arms the physical alarm. */
|
|
122
124
|
alarm(info) {
|
|
@@ -317,6 +319,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
|
|
|
317
319
|
isTerminal: (error) => isErrorInstance(error, DurableResultSerializationError),
|
|
318
320
|
}, eagerPermit);
|
|
319
321
|
};
|
|
322
|
+
traceMethods(DurabilityCore.prototype, 'Durability');
|
|
320
323
|
// TypeScript cannot declare class members derived from a generic handler map,
|
|
321
324
|
// so the constructor is typed separately; the constructor installs and reserves
|
|
322
325
|
// every operation method at runtime.
|
package/dist/errors.d.ts
CHANGED
|
@@ -115,3 +115,20 @@ export declare const isErrorInstance: (error: unknown, constructor: new (...args
|
|
|
115
115
|
/** Recognizes this package's NonRetryableError and same-named errors from other packages. */
|
|
116
116
|
export declare const isNonRetryable: (error: unknown) => boolean;
|
|
117
117
|
export declare const reportFailure: (event: string, details: Record<string, unknown>, error: unknown) => void;
|
|
118
|
+
/** A definite rejection of a topology change or configuration. */
|
|
119
|
+
export declare class TopologyError extends Error {
|
|
120
|
+
constructor(message: string);
|
|
121
|
+
}
|
|
122
|
+
/** Why a topology client could not use the published snapshot. */
|
|
123
|
+
export type TopologyFallbackReason = 'missing' | 'invalid' | 'timeout' | 'error';
|
|
124
|
+
/**
|
|
125
|
+
* Thrown by a topology client when the published snapshot is unusable and no
|
|
126
|
+
* configured fallback produced one. The client never asks the coordinator.
|
|
127
|
+
*/
|
|
128
|
+
export declare class TopologyUnavailableError extends Error {
|
|
129
|
+
readonly group: string;
|
|
130
|
+
readonly reason: TopologyFallbackReason;
|
|
131
|
+
constructor(group: string, reason: TopologyFallbackReason, options?: {
|
|
132
|
+
cause?: unknown;
|
|
133
|
+
});
|
|
134
|
+
}
|
package/dist/errors.js
CHANGED
|
@@ -234,3 +234,25 @@ export const reportFailure = (event, details, error) => {
|
|
|
234
234
|
return;
|
|
235
235
|
}
|
|
236
236
|
};
|
|
237
|
+
/** A definite rejection of a topology change or configuration. */
|
|
238
|
+
export class TopologyError extends Error {
|
|
239
|
+
constructor(message) {
|
|
240
|
+
super(message);
|
|
241
|
+
this.name = 'TopologyError';
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
/**
|
|
245
|
+
* Thrown by a topology client when the published snapshot is unusable and no
|
|
246
|
+
* configured fallback produced one. The client never asks the coordinator.
|
|
247
|
+
*/
|
|
248
|
+
export class TopologyUnavailableError extends Error {
|
|
249
|
+
constructor(group, reason, options) {
|
|
250
|
+
super(`Topology for group "${group}" is unavailable: ${reason}`);
|
|
251
|
+
this.group = group;
|
|
252
|
+
this.reason = reason;
|
|
253
|
+
this.name = 'TopologyUnavailableError';
|
|
254
|
+
if (options?.cause !== undefined) {
|
|
255
|
+
Object.defineProperty(this, 'cause', { value: options.cause });
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
}
|
package/dist/experimental.d.ts
CHANGED
|
@@ -9,3 +9,8 @@ export type { TrackedEntry, TrackedPage, TrackedQuery, TrackedRecord, TrackedRes
|
|
|
9
9
|
export { DurabilityOutbox, type DurabilityOutboxConfig, type DurabilityOutboxEvent, type OutboxEntry, } from './outbox.js';
|
|
10
10
|
export { OutboxTimeoutError } from './errors.js';
|
|
11
11
|
export { durabilityOutboxMigrations } from './migrations.js';
|
|
12
|
+
export { DurabilityTopology, type DurabilityTopologyConfig, type DurabilityTopologyEvent, type TopologyChannel, type TopologyCurrent, type TopologyDraft, type TopologyPublisher, type TopologyRetryOptions, type TopologyRole, type TopologyStateUpdate, } from './topology.js';
|
|
13
|
+
export type { TopologyClient, TopologyClientConfig, TopologySource, TopologyView, } from './topology-client.js';
|
|
14
|
+
export type { TopologyMember, TopologyMemberInput, TopologyMemberState, TopologySnapshot, } from './topology-snapshot.js';
|
|
15
|
+
export { TopologyError, TopologyUnavailableError, type TopologyFallbackReason, } from './errors.js';
|
|
16
|
+
export { durabilityTopologyMigrations } from './migrations.js';
|
package/dist/experimental.js
CHANGED
|
@@ -8,3 +8,6 @@ export { DurabilityTracker, } from './tracker.js';
|
|
|
8
8
|
export { DurabilityOutbox, } from './outbox.js';
|
|
9
9
|
export { OutboxTimeoutError } from './errors.js';
|
|
10
10
|
export { durabilityOutboxMigrations } from './migrations.js';
|
|
11
|
+
export { DurabilityTopology, } from './topology.js';
|
|
12
|
+
export { TopologyError, TopologyUnavailableError, } from './errors.js';
|
|
13
|
+
export { durabilityTopologyMigrations } from './migrations.js';
|