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
package/README.md
CHANGED
|
@@ -5,6 +5,9 @@ Composable capabilities for application-owned Cloudflare Durable Objects:
|
|
|
5
5
|
- **`Durability`** — effectively-once operations with retries, idempotency, and result lookup.
|
|
6
6
|
- **`DurabilityAlarms`** — named logical alarms with retries and stable idempotency keys.
|
|
7
7
|
- **`DurabilityFanout`** — durable batch acceptance and independent delivery to static consumer or storage targets.
|
|
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
|
+
- **`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.
|
|
8
11
|
- **`DurabilityRouting`** — a DO-side load observer and client-side shard selector (`durability/routing`), supporting location hints and caller transforms.
|
|
9
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`).
|
|
10
13
|
- **`DurabilityTracker`** _(experimental, `durability/experimental`)_ — lists work across capabilities and custom sources, as RPC handles that can be waited on or as plain records.
|
|
@@ -192,6 +195,32 @@ Passing a name moves that capability's schema to exactly that version. Each batc
|
|
|
192
195
|
|
|
193
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.
|
|
194
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
|
+
|
|
195
224
|
## Retries, timeouts, and terminal failures
|
|
196
225
|
|
|
197
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:
|
|
@@ -266,6 +295,39 @@ const detach = durability.lifecycle((event) => {
|
|
|
266
295
|
});
|
|
267
296
|
```
|
|
268
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
|
+
|
|
269
331
|
## Browser sockets
|
|
270
332
|
|
|
271
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.
|
|
@@ -511,6 +573,149 @@ new DurabilityTracker({ sources: { jobs: this.durability, approvals } });
|
|
|
511
573
|
|
|
512
574
|
New members of `TrackedSource` are always optional, so a custom source keeps compiling across releases.
|
|
513
575
|
|
|
576
|
+
## Semaphore (experimental)
|
|
577
|
+
|
|
578
|
+
Everything under `durability/experimental/semaphore` may change or be removed in a minor release; pin an exact version when depending on it. It is a separate entry point from `durability/experimental` because its client resolves Durable Object namespaces through `cloudflare:workers`.
|
|
579
|
+
|
|
580
|
+
`DurabilitySemaphore` holds one concurrency limit — say, an account's maximum running jobs — inside an application-owned Durable Object, and hands permits to many client Durable Objects that queue work. Requests arriving within a round are allocated together in arrival order, so the oldest queued work across all clients is admitted first. Groups (a workflow, a tenant) may carry their own ceiling under the shared limit.
|
|
581
|
+
|
|
582
|
+
```ts
|
|
583
|
+
import { DurableObject } from 'cloudflare:workers';
|
|
584
|
+
import { timeout } from '@durability/transforms';
|
|
585
|
+
import { DurabilityScheduler } from 'durability';
|
|
586
|
+
import {
|
|
587
|
+
DurabilitySemaphore,
|
|
588
|
+
type SemaphoreRequest,
|
|
589
|
+
} from 'durability/experimental/semaphore';
|
|
590
|
+
|
|
591
|
+
/** One instance per account; the account id is the semaphore key. */
|
|
592
|
+
export class AccountLimit extends DurableObject<Env> {
|
|
593
|
+
private readonly scheduler = new DurabilityScheduler({ context: this.ctx });
|
|
594
|
+
private readonly semaphore = new DurabilitySemaphore({
|
|
595
|
+
scheduler: this.scheduler,
|
|
596
|
+
limit: () => this.env.ACCOUNT_CONCURRENCY,
|
|
597
|
+
groupLimit: (workflowId) => this.workflowLimits.get(workflowId),
|
|
598
|
+
});
|
|
599
|
+
|
|
600
|
+
permits(message: SemaphoreRequest) {
|
|
601
|
+
return this.semaphore.handle(message);
|
|
602
|
+
}
|
|
603
|
+
|
|
604
|
+
override alarm(info?: AlarmInvocationInfo) {
|
|
605
|
+
return this.scheduler.alarm(info);
|
|
606
|
+
}
|
|
607
|
+
}
|
|
608
|
+
|
|
609
|
+
export const limits = DurabilitySemaphore.client({
|
|
610
|
+
target: AccountLimit, // Vite injects exportName
|
|
611
|
+
invoke: (stub, message) => stub.permits(message),
|
|
612
|
+
});
|
|
613
|
+
|
|
614
|
+
// From a client Durable Object:
|
|
615
|
+
const grant = await limits.with(timeout, 5_000).request(accountId, {
|
|
616
|
+
type: 'request',
|
|
617
|
+
v: 1,
|
|
618
|
+
clientId: this.ctx.id.toString(),
|
|
619
|
+
demand: [{ group: workflowId, count: queued, oldestAt: oldestEnqueuedAt }],
|
|
620
|
+
grants: [{ grantId, claimed: 3, released: 1 }], // cumulative reports
|
|
621
|
+
});
|
|
622
|
+
```
|
|
623
|
+
|
|
624
|
+
- **Rounds.** `handle()` holds a request for up to `roundWaitMs` (default 1 second) so concurrent requests are allocated together, and runs rounds no closer than `roundPeriodMs` (default 2 seconds). The response's `nextRequestAt` tells the client when it may ask again.
|
|
625
|
+
- **Grants and reports.** Each `(client, group)` that receives permits gets a grant. Clients report `claimed` (permits actually used) and `released` (claimed permits returned) per grant as cumulative high-water marks, piggybacked on requests or sent with a `sync` message. Counts only move forward and are clamped to the grant, so lost, repeated, or reordered reports can never free capacity twice. Permits a client never claims within `grantTimeoutMs` (default 10 seconds) are reclaimed; a later claim is answered with the clamped count and `status: 'expired'`.
|
|
626
|
+
- **Blocked attribution.** Demand that stays queued is explained per group: `group_limit`, `limit`, `not_permitted` (`canGrant` returned false), or `limit_resolution_error` (`groupLimit` threw; the group fails closed).
|
|
627
|
+
- **Limits are live.** `limit` and `groupLimit` are resolved once per round. Lowering a limit never evicts running work; it stops new admissions until usage is below the new ceiling.
|
|
628
|
+
- **Client side.** `DurabilitySemaphore.client()` has the same shape as `DurabilityRouting.client()`: the Vite plugin injects `exportName`, `namespace` is the escape hatch, and caller transforms such as `timeout` compose. The underlying `SemaphoreClient` is transport-independent and remembers each key's `nextRequestAt`.
|
|
629
|
+
|
|
630
|
+
`usage()` reports the limit, outstanding permits, lease footprint, and per-group usage. `DurabilitySemaphore.migrate(this.ctx, null)` removes the schema.
|
|
631
|
+
|
|
632
|
+
### Leases
|
|
633
|
+
|
|
634
|
+
Rounds cost a round trip per batch of admissions. For bursty arrivals, the holder can hand each `(client, group)` with queued demand a **lease**: a block of permits the client may draw locally, one per item, with no round trip. Where that capacity comes from is the `provisioning` mode:
|
|
635
|
+
|
|
636
|
+
```ts
|
|
637
|
+
new DurabilitySemaphore({
|
|
638
|
+
scheduler,
|
|
639
|
+
limit: 100,
|
|
640
|
+
leases: {
|
|
641
|
+
provisioning: { mode: 'strict' }, // leases share the limit with grants
|
|
642
|
+
// provisioning: { mode: 'under', reserve: 20 }, // 20 of the 100 kept for leases; grants get 80
|
|
643
|
+
// provisioning: { mode: 'over', extra: { ratio: 0.5 } }, // 50 more above the limit, for leases only
|
|
644
|
+
permitsPerLease: 64,
|
|
645
|
+
ttlMs: 30 * 60_000,
|
|
646
|
+
},
|
|
647
|
+
});
|
|
648
|
+
```
|
|
649
|
+
|
|
650
|
+
- **`strict`** — "always below": grants are allocated first, then leases from whatever is left; a live lease's footprint (permits not yet released) is reserved from the same pool. Total never exceeds the limit.
|
|
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.
|
|
652
|
+
- **`over`** — leases come from a separate budget above the limit (the original gatekeeper behaviour); the effective ceiling is `limit + extra`.
|
|
653
|
+
|
|
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.
|
|
655
|
+
|
|
656
|
+
### Queueing work in a client Durable Object
|
|
657
|
+
|
|
658
|
+
`DurabilitySemaphoreQueue` is the client half: it queues items per semaphore key in arrival order, drives the protocol above against the holder, and hands items to the application once a permit is confirmed. Claims and releases are published through an internal `DurabilityOutbox` channel as cumulative counts, so a crash or lost response never loses or double-counts a permit.
|
|
659
|
+
|
|
660
|
+
```ts
|
|
661
|
+
import { DurableObject } from 'cloudflare:workers';
|
|
662
|
+
import { timeout } from '@durability/transforms';
|
|
663
|
+
import { Durability, DurabilityScheduler } from 'durability';
|
|
664
|
+
import { DurabilitySemaphoreQueue } from 'durability/experimental/semaphore';
|
|
665
|
+
|
|
666
|
+
/** Many shards, each queueing jobs for many accounts. */
|
|
667
|
+
export class JobShard extends DurableObject<Env> {
|
|
668
|
+
private readonly scheduler = new DurabilityScheduler({ context: this.ctx });
|
|
669
|
+
private readonly jobs = new Durability({
|
|
670
|
+
scheduler: this.scheduler,
|
|
671
|
+
handlers: { run: (job: Job) => runJob(this.env, job) },
|
|
672
|
+
// Return the permit as soon as the operation reaches a terminal state.
|
|
673
|
+
onLifecycleEvent: (event) => {
|
|
674
|
+
if (
|
|
675
|
+
event.type === 'terminal' ||
|
|
676
|
+
(event.type === 'attempt_settled' && event.outcome === 'completed')
|
|
677
|
+
) {
|
|
678
|
+
return this.permits.release(event.id).then(() => undefined);
|
|
679
|
+
}
|
|
680
|
+
},
|
|
681
|
+
});
|
|
682
|
+
private readonly permits = new DurabilitySemaphoreQueue<Job>({
|
|
683
|
+
scheduler: this.scheduler,
|
|
684
|
+
clientId: this.ctx.id.toString(),
|
|
685
|
+
server: limits.with(timeout, 5_000),
|
|
686
|
+
admit: (items) =>
|
|
687
|
+
Promise.all(
|
|
688
|
+
items.map((item) => this.jobs.run({ id: item.id, payload: item.body }))
|
|
689
|
+
),
|
|
690
|
+
// The hook above is best-effort; this check returns any permit it missed.
|
|
691
|
+
finished: async (ids) => {
|
|
692
|
+
const results = await Promise.all(
|
|
693
|
+
ids.map((id) => this.jobs.run.getResult(id))
|
|
694
|
+
);
|
|
695
|
+
return ids.filter((_, index) => results[index]!.status !== 'pending');
|
|
696
|
+
},
|
|
697
|
+
});
|
|
698
|
+
|
|
699
|
+
submit(job: Job) {
|
|
700
|
+
return this.permits.enqueue([
|
|
701
|
+
{ id: job.id, key: job.accountId, group: job.workflowId, body: job },
|
|
702
|
+
]);
|
|
703
|
+
}
|
|
704
|
+
|
|
705
|
+
override alarm(info?: AlarmInvocationInfo) {
|
|
706
|
+
return this.scheduler.alarm(info);
|
|
707
|
+
}
|
|
708
|
+
}
|
|
709
|
+
```
|
|
710
|
+
|
|
711
|
+
- **States.** An item is `queued` until permits arrive, `claiming` while the holder confirms the claim, and `admitted` once `admit()` has been handed the item. Items drawn from a lease skip `claiming` and are admitted at once; `AdmittedItem.via` says which path admitted an item. `admit()` runs after the admission commits and is retried under `retries.delay` until it returns, so it must be idempotent on item ID. `release(id)` returns the permit; `cancel(id)` removes an item that is still `queued`.
|
|
712
|
+
- **Releasing.** Call `release(id)` when the work ends, and pass `finished(ids)` so a release that never happens — a lifecycle hook is best-effort, a crash can come between the work ending and the call — does not hold the permit forever. The queue asks `finished` about each admitted item `finishedCheckMs` (default 60 seconds) after `admit()` returned, and again at that interval, releasing the ones it reports done. Without `finished`, a lost `release()` leaks the permit until the item is released by hand.
|
|
713
|
+
- **Requests.** Each key is asked at most once per `nextRequestAt`, with demand aggregated per group from the oldest queued items. A failed request, or one unanswered after `attemptTimeoutMs`, is retried with backoff. Items whose key already holds unclaimed permits — a grant sized for demand that was cancelled, say — are admitted without a request.
|
|
714
|
+
- **Blocked attribution.** `status(id)` on a queued item carries the holder's most recent reason for that key and group (`limit`, `group_limit`, …); `blocked` lifecycle events report counts per group. Attribution is in-memory and best-effort.
|
|
715
|
+
- **Composition.** The queue shares the scheduler with everything else in the object and creates its own outbox channel (`durability.semaphore-queue`) on it; one queue per scheduler. Pass `DurabilitySemaphore.client()` as `server` — caller transforms apply to every request and sync.
|
|
716
|
+
|
|
717
|
+
`DurabilitySemaphoreQueue.migrate(this.ctx, null)` removes the queue schema. See the typechecked [account concurrency composition](../../examples/account-concurrency).
|
|
718
|
+
|
|
514
719
|
## Routing and fanout
|
|
515
720
|
|
|
516
721
|
A queue is a composition, not another exported abstraction. An application owns its DO class and attaches the capabilities it needs:
|
|
@@ -672,6 +877,206 @@ Routing uses the actual `@durability/transforms` runtime. For example, `routing.
|
|
|
672
877
|
|
|
673
878
|
Loopback namespaces need the application DO declared in Wrangler migrations (or the platform's supported class configuration), but no redundant DO binding block is needed. Consumer transport is explicitly wired by the application, such as a service binding or loopback entrypoint. See the typechecked [email queue composition](../../examples/email-queue).
|
|
674
879
|
|
|
880
|
+
## Outbox (experimental)
|
|
881
|
+
|
|
882
|
+
`DurabilityOutbox` is exported from `durability/experimental` and may change in a minor release; pin an exact version when depending on it.
|
|
883
|
+
|
|
884
|
+
`DurabilityOutbox` publishes the newest state of a key to something outside the object — a KV namespace, another Durable Object, an API — and keeps retrying until the sink accepts it. Use it when consumers need the latest value, not every change: restaging a key before it is published replaces the pending version, so superseded versions may never be sent. For message delivery where every message matters, use `DurabilityFanout`.
|
|
885
|
+
|
|
886
|
+
```ts
|
|
887
|
+
import { DurableObject } from 'cloudflare:workers';
|
|
888
|
+
import { DurabilityScheduler } from 'durability';
|
|
889
|
+
import { DurabilityOutbox } from 'durability/experimental';
|
|
890
|
+
|
|
891
|
+
type Topology = { workflowId: string; steps: string[] };
|
|
892
|
+
|
|
893
|
+
export class Account extends DurableObject<Env> {
|
|
894
|
+
private readonly scheduler = new DurabilityScheduler({ context: this.ctx });
|
|
895
|
+
private readonly topology = new DurabilityOutbox<Topology>({
|
|
896
|
+
scheduler: this.scheduler,
|
|
897
|
+
channel: 'topology',
|
|
898
|
+
// The sink keeps the highest version it has seen per key, so a slow
|
|
899
|
+
// publication of an older version can never overwrite a newer one.
|
|
900
|
+
publish: async (entries) => {
|
|
901
|
+
const results = await this.env.TOPOLOGY_INDEX.replace(
|
|
902
|
+
entries.map(({ key, version, value }) => ({ key, version, value }))
|
|
903
|
+
);
|
|
904
|
+
// Returning acknowledges every entry not marked for retry.
|
|
905
|
+
for (const [index, result] of results.entries()) {
|
|
906
|
+
if (!result.ok) {
|
|
907
|
+
entries[index]!.retry();
|
|
908
|
+
}
|
|
909
|
+
}
|
|
910
|
+
},
|
|
911
|
+
});
|
|
912
|
+
|
|
913
|
+
async saveTopology(topology: Topology) {
|
|
914
|
+
await this.ctx.storage.transaction(async () => {
|
|
915
|
+
this.ctx.storage.sql.exec(
|
|
916
|
+
'INSERT OR REPLACE INTO topologies (id, body) VALUES (?, ?)',
|
|
917
|
+
topology.workflowId,
|
|
918
|
+
JSON.stringify(topology)
|
|
919
|
+
);
|
|
920
|
+
await this.topology.stage(topology.workflowId, topology);
|
|
921
|
+
});
|
|
922
|
+
}
|
|
923
|
+
|
|
924
|
+
override alarm(info?: AlarmInvocationInfo) {
|
|
925
|
+
return this.scheduler.alarm(info);
|
|
926
|
+
}
|
|
927
|
+
}
|
|
928
|
+
```
|
|
929
|
+
|
|
930
|
+
- **Atomic with application state.** `stage()` inside `ctx.storage.transaction()` commits or rolls back with the application's writes.
|
|
931
|
+
- **Versions.** Every `stage()` returns a version that is monotonic across the whole object, including after acknowledged entries are deleted. Sinks must be idempotent on `(key, version)` and keep the highest version they have seen: a slow publication of an older version can land after a newer one. A plain `KV.put` cannot do this; compare versions in a Durable Object, a transactional store, or a conditional write.
|
|
932
|
+
- **Acknowledgement.** `publish` returning acknowledges every entry not marked with `entry.retry(delayMs?)`; throwing or exceeding `attemptTimeoutMs` (default 60 seconds) retries the whole batch. Acknowledging a version deletes the entry only if it is still the newest, so an in-flight publication can never discard a later stage.
|
|
933
|
+
- **Retries never give up.** Dropping the newest state would leave the sink stale forever, so there is no attempt limit or dead-letter queue; `retries.delay(attempt)` controls backoff (default: jittered exponential capped at 5 minutes).
|
|
934
|
+
- **Channels.** Several outboxes share one scheduler and one set of tables, partitioned by `channel` (default `default`); each owns its own `publish`, and the same key in different channels is independent. Attaching two outboxes with the same channel to one scheduler throws. Entries of a channel no outbox attaches are retained and postponed, as fanout does for a removed target.
|
|
935
|
+
- **Batching.** `maxBatchSize` (default 50) bounds one `publish` call. `batchDelayMs` rounds first publication up to the next multiple of the delay, so stages within one window coalesce into a batch; a stage landing exactly on a boundary is due immediately.
|
|
936
|
+
|
|
937
|
+
`DurabilityOutbox.migrate(this.ctx, null)` removes the outbox schema.
|
|
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
|
+
|
|
675
1080
|
## Retained log
|
|
676
1081
|
|
|
677
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.
|
|
@@ -758,7 +1163,7 @@ type LogColdStorage<Body> = {
|
|
|
758
1163
|
|
|
759
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.
|
|
760
1165
|
|
|
761
|
-
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.
|
|
762
1167
|
|
|
763
1168
|
### Leases for parallel consumers
|
|
764
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>;
|