durability 5.0.0 → 5.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/README.md +238 -7
  2. package/dist/{durability-alarms.d.ts → alarms/index.d.ts} +23 -6
  3. package/dist/{durability-alarms.js → alarms/index.js} +96 -52
  4. package/dist/alarms/migrations.d.ts +9 -0
  5. package/dist/alarms/migrations.js +133 -0
  6. package/dist/errors.d.ts +15 -0
  7. package/dist/errors.js +24 -0
  8. package/dist/experimental.d.ts +11 -8
  9. package/dist/experimental.js +8 -5
  10. package/dist/{fanout.d.ts → fanout/index.d.ts} +13 -6
  11. package/dist/{fanout.js → fanout/index.js} +55 -49
  12. package/dist/fanout/migrations.d.ts +9 -0
  13. package/dist/fanout/migrations.js +181 -0
  14. package/dist/{stored-message.d.ts → fanout/stored-message.d.ts} +1 -1
  15. package/dist/index.d.ts +14 -9
  16. package/dist/index.js +13 -8
  17. package/dist/{log.d.ts → log/index.d.ts} +15 -3
  18. package/dist/{log.js → log/index.js} +152 -124
  19. package/dist/log/migrations.d.ts +18 -0
  20. package/dist/log/migrations.js +297 -0
  21. package/dist/{memoize.d.ts → memoize/index.d.ts} +1 -1
  22. package/dist/{memoize.js → memoize/index.js} +14 -11
  23. package/dist/memoize/migrations.d.ts +10 -0
  24. package/dist/memoize/migrations.js +21 -0
  25. package/dist/migrations.d.ts +1 -103
  26. package/dist/migrations.js +1 -570
  27. package/dist/{durability.d.ts → operations/index.d.ts} +13 -5
  28. package/dist/{durability.js → operations/index.js} +63 -46
  29. package/dist/operations/migrations.d.ts +10 -0
  30. package/dist/operations/migrations.js +150 -0
  31. package/dist/{outbox.d.ts → outbox/index.d.ts} +4 -4
  32. package/dist/{outbox.js → outbox/index.js} +18 -63
  33. package/dist/outbox/migrations.d.ts +9 -0
  34. package/dist/outbox/migrations.js +43 -0
  35. package/dist/{routing-client.js → routing/client.js} +1 -1
  36. package/dist/{routing.d.ts → routing/index.d.ts} +3 -3
  37. package/dist/{routing.js → routing/index.js} +3 -3
  38. package/dist/{load.d.ts → routing/load.d.ts} +1 -1
  39. package/dist/schedule/index.d.ts +165 -0
  40. package/dist/schedule/index.js +667 -0
  41. package/dist/schedule/migrations.d.ts +9 -0
  42. package/dist/schedule/migrations.js +118 -0
  43. package/dist/{scheduler.d.ts → scheduler/index.d.ts} +122 -22
  44. package/dist/scheduler/index.js +925 -0
  45. package/dist/{semaphore-client.d.ts → semaphore/client.d.ts} +1 -1
  46. package/dist/{semaphore-client.js → semaphore/client.js} +2 -2
  47. package/dist/{semaphore.d.ts → semaphore/index.d.ts} +10 -10
  48. package/dist/{semaphore.js → semaphore/index.js} +7 -7
  49. package/dist/{semaphore-leases.d.ts → semaphore/leases.d.ts} +17 -6
  50. package/dist/{semaphore-leases.js → semaphore/leases.js} +28 -12
  51. package/dist/semaphore/migrations.d.ts +18 -0
  52. package/dist/semaphore/migrations.js +444 -0
  53. package/dist/{semaphore-protocol.d.ts → semaphore/protocol.d.ts} +16 -8
  54. package/dist/{semaphore-protocol.js → semaphore/protocol.js} +37 -14
  55. package/dist/{semaphore-queue-store.d.ts → semaphore/queue-store.d.ts} +12 -6
  56. package/dist/{semaphore-queue-store.js → semaphore/queue-store.js} +87 -75
  57. package/dist/{semaphore-queue.d.ts → semaphore/queue.d.ts} +15 -5
  58. package/dist/{semaphore-queue.js → semaphore/queue.js} +105 -46
  59. package/dist/{semaphore-server.d.ts → semaphore/server.d.ts} +12 -4
  60. package/dist/{semaphore-server.js → semaphore/server.js} +51 -24
  61. package/dist/{semaphore-store.d.ts → semaphore/store.d.ts} +8 -3
  62. package/dist/{semaphore-store.js → semaphore/store.js} +35 -33
  63. package/dist/{client.d.ts → socket/client.d.ts} +3 -3
  64. package/dist/{client.js → socket/client.js} +4 -4
  65. package/dist/{socket.d.ts → socket/index.d.ts} +15 -4
  66. package/dist/{socket.js → socket/index.js} +66 -20
  67. package/dist/socket/migrations.d.ts +9 -0
  68. package/dist/socket/migrations.js +57 -0
  69. package/dist/{socket-protocol.d.ts → socket/protocol.d.ts} +1 -1
  70. package/dist/storage.d.ts +9 -2
  71. package/dist/storage.js +24 -11
  72. package/dist/{topology-client.d.ts → topology/client.d.ts} +2 -2
  73. package/dist/{topology-client.js → topology/client.js} +3 -3
  74. package/dist/{topology.d.ts → topology/index.d.ts} +17 -7
  75. package/dist/{topology.js → topology/index.js} +92 -58
  76. package/dist/topology/migrations.d.ts +10 -0
  77. package/dist/topology/migrations.js +138 -0
  78. package/dist/{tracker.d.ts → tracker/index.d.ts} +3 -3
  79. package/dist/{tracker.js → tracker/index.js} +2 -2
  80. package/package.json +11 -11
  81. package/dist/scheduler.js +0 -577
  82. /package/dist/{stored-message.js → fanout/stored-message.js} +0 -0
  83. /package/dist/{routing-client.d.ts → routing/client.d.ts} +0 -0
  84. /package/dist/{load.js → routing/load.js} +0 -0
  85. /package/dist/{socket-protocol.js → socket/protocol.js} +0 -0
  86. /package/dist/{topology-snapshot.d.ts → topology/snapshot.d.ts} +0 -0
  87. /package/dist/{topology-snapshot.js → topology/snapshot.js} +0 -0
  88. /package/dist/{tracked-source.d.ts → tracker/source.d.ts} +0 -0
  89. /package/dist/{tracked-source.js → tracker/source.js} +0 -0
package/README.md CHANGED
@@ -205,7 +205,69 @@ export class ImageJobs extends DurableObject<Env> {
205
205
  }
206
206
  ```
207
207
 
208
- A helper configured with `context` instead of `scheduler` creates a private scheduler and accepts the scheduler options (`alarmConcurrency`, `alarmMinDelayMs`, `alarmHandoffMs`) in the same object. Two helpers on the same object must share one scheduler; otherwise each would reconcile the physical alarm against only its own records.
208
+ A Durable Object has one scheduler. A helper configured with `context` instead of `scheduler`, and any further `DurabilityScheduler` for the same object, joins it, so helpers never reconcile the physical alarm against only their own records. Scheduler options (`alarmConcurrency`, `alarmMinDelayMs`, `alarmHandoffMs`, and the experimental ones) can be set by whichever attaches; an option left out never conflicts, and a different value for one already set throws. The object's `alarm` method can delegate to the scheduler or to any helper's `alarm`: each runs the due work of every helper on the object.
209
+
210
+ This lets a library use durability without asking for a scheduler. It builds its helpers from the context it is given, and the application only forwards `alarm`:
211
+
212
+ ```ts
213
+ // In a library
214
+ export const alerts = (ctx: DurableObjectState) => {
215
+ const alarms = new DurabilityAlarms({
216
+ context: ctx,
217
+ handlers: { checkAlerts: () => runChecks(ctx) },
218
+ });
219
+ return {
220
+ start: () => alarms.checkAlerts(Date.now()),
221
+ alarm: (info?: AlarmInvocationInfo) => alarms.alarm(info),
222
+ };
223
+ };
224
+
225
+ // In the application
226
+ export class Billing extends DurableObject<Env> {
227
+ private readonly jobs = new Durability({ context: this.ctx, handlers });
228
+ private readonly alerts = alerts(this.ctx);
229
+
230
+ alarm(info?: AlarmInvocationInfo) {
231
+ return this.jobs.alarm(info); // also runs the library's alarms
232
+ }
233
+ }
234
+ ```
235
+
236
+ Install durability once per Worker, as a peer dependency of libraries that use it: a second copy reaching the same object throws instead of fighting the first over its alarm.
237
+
238
+ ### Channels
239
+
240
+ `Durability`, `DurabilityAlarms`, `DurabilityFanout`, `DurabilityOutbox`, `DurabilitySchedule`, `DurabilityLog`, `DurabilitySemaphore`, `DurabilitySemaphoreQueue`, `DurabilityTopology`, and `DurabilitySocket` accept `channel`, defaulting to `default`. Each channel of a helper kind holds one instance. Instances on different channels share the scheduler but not their records: IDs and names are scoped to a channel, and each instance's operations affect only its own state. A library should use a channel of its own, so the application can use the same helper and the same IDs without either seeing the other's work:
241
+
242
+ ```ts
243
+ // In a library
244
+ const jobs = new Durability({
245
+ context: ctx,
246
+ channel: 'durable-alerts',
247
+ handlers: { notify },
248
+ });
249
+
250
+ // In the application, on the default channel
251
+ const jobs = new Durability({ context: this.ctx, handlers: { charge } });
252
+ // Both can register { id: 'invoice-1' }; they are different calls.
253
+ ```
254
+
255
+ Attaching a second instance to a channel already in use throws `Durability for channel "durable-alerts" is already attached to this scheduler`. Due operations, alarms, fanout deliveries and outbox entries of a channel no instance attached are retained and postponed a minute, with a `durability.channel_missing` report. Custom-timed schedule and semaphore state is retained unchanged while its owner is absent; reattaching it reconciles any pending work. Data-only log and socket history remains stored. Channel identity is part of persisted keys; existing records and memoized results migrate to `default` without changing their IDs or names. Schema downgrades refuse to discard non-default-channel state. Deliberately remove that state before rolling back: draining or cancelling work may still leave counters or tombstones. `DurabilityAlarms` and `DurabilityOutbox` take the same `channel` option: an application and a library can both have an alarm called `check`, each with its own handler, policy, and lifecycle hook:
256
+
257
+ ```ts
258
+ const reminders = new DurabilityAlarms({
259
+ context: this.ctx,
260
+ handlers: { check },
261
+ });
262
+ const alerts = new DurabilityAlarms({
263
+ context: this.ctx,
264
+ channel: 'durable-alerts',
265
+ retries: { maxAttempts: 5 },
266
+ handlers: { check: () => runChecks(this.ctx) },
267
+ });
268
+ ```
269
+
270
+ Within a channel, a due alarm whose name has no handler, such as one a deploy removed, fails through that channel's instance.
209
271
 
210
272
  ## Memoize
211
273
 
@@ -375,6 +437,106 @@ const removedAlarms = await this.alarms.purgeBefore(retentionCutoff);
375
437
 
376
438
  The purge runs in one transaction. It best-effort aborts matching active handlers, but cannot force an abort-ignoring handler to stop. Operation IDs can be reused immediately; a late old generation cannot overwrite the replacement record.
377
439
 
440
+ ## Experimental options
441
+
442
+ These options, methods, and capabilities are opt-in: none takes effect unless you set, call, or construct it, so leaving them alone keeps every behavior described above. Their names and behavior may change in a minor release. Scheduler options can also be passed to a helper configured with `context`.
443
+
444
+ ```ts
445
+ const scheduler = new DurabilityScheduler({
446
+ context: this.ctx,
447
+ liveTimers: true,
448
+ });
449
+
450
+ const alarms = new DurabilityAlarms({
451
+ scheduler,
452
+ handlers: { tick: async () => this.enqueueDueRuns() },
453
+ });
454
+
455
+ await alarms.tick.cancel();
456
+ ```
457
+
458
+ ### `liveTimers` (scheduler)
459
+
460
+ `liveTimers?: boolean`. Due work starts from an in-memory timer at its exact scheduled time, however far beyond `alarmMinDelayMs`, and an alarm pass skips records that are already running instead of waiting for them, so a long handler no longer delays newly due work. The physical alarm stays armed at the usual bounded delay as the eviction fallback, and the handoff before the alarm wall-time limit is unchanged.
461
+
462
+ Gives up: every settled attempt runs one more reconciliation transaction to re-arm the timer, and timers do not survive eviction, so after one the work runs only when the physical alarm fires. Attempts interrupted by the eviction are counted as usual, so an operation with `maxAttempts: 1` fails instead of running again.
463
+
464
+ ### `cancel` (named alarm method)
465
+
466
+ `alarms.<name>.cancel(): Promise<boolean>`. This deletes the alarm's pending occurrence and its memos and reconciles the physical alarm in one transaction, then aborts the `signal` of a running attempt of it. That attempt's settlement can no longer retry it. It resolves `true` when a pending occurrence was deleted. Failed occurrences are left for `purgeBefore`.
467
+
468
+ Gives up: cancelling does not stop later scheduling. A call to the scheduling method after `cancel`, including one from the running handler before it returns, schedules a new occurrence.
469
+
470
+ ### `onAlarmRetry` (scheduler)
471
+
472
+ `onAlarmRetry?: (info: AlarmRetryInfo) => void | Promise<void>`, where `info` is `{ error: { name, message }, retryInMs, retryCount?, isRetry?, objectId? }`. It is called each time an alarm run fails and the scheduler re-arms its own fallback alarm (see [When a run cannot finish](#when-a-run-cannot-finish)), so the error can go to an external service. `retryInMs` is `alarmMinDelayMs`; `retryCount` and `isRetry` come from the platform's `AlarmInvocationInfo` when the invocation carried one, and `objectId` from the context.
473
+
474
+ The `durability.alarm.failed` report still happens. The hook is best effort: it runs after the fallback is armed, a returned promise is passed to `waitUntil`, and a throw or rejection is only reported as `durability.alarm.retry_hook_failed`, so it cannot change scheduling. It is not called when even the fallback cannot be armed, because the failure then reaches the platform.
475
+
476
+ ```ts
477
+ const scheduler = new DurabilityScheduler({
478
+ context: this.ctx,
479
+ onAlarmRetry: (info) => this.env.ERRORS.send(info),
480
+ });
481
+ ```
482
+
483
+ ### `DurabilitySchedule`
484
+
485
+ `DurabilitySchedule` is exported from `durability/experimental`. It runs one recurring schedule per channel of a Durable Object: each tick starts a run, runs overlap, every run is tracked on its own, and its outcome is reported once and then forgotten. It replaces a `DurabilityAlarms` tick that registers a `Durability` operation per run, which needs retained records to deduplicate and keeps them until purged.
486
+
487
+ ```ts
488
+ import { DurableObject } from 'cloudflare:workers';
489
+ import { DurabilityScheduler } from 'durability';
490
+ import { DurabilitySchedule } from 'durability/experimental';
491
+ import { nextCronTime } from './cron';
492
+
493
+ export class Cron extends DurableObject<Env> {
494
+ private readonly scheduler = new DurabilityScheduler({ context: this.ctx });
495
+ private readonly schedule = new DurabilitySchedule({
496
+ scheduler: this.scheduler,
497
+ // Durability ships no cron parser: return the first tick after `after`.
498
+ nextOccurrence: (expression, after) => nextCronTime(expression, after),
499
+ run: ({ scheduledTime, idempotencyKey, signal }) =>
500
+ this.env.TARGET.fire({ scheduledTime, idempotencyKey }, { signal }),
501
+ onOutcome: (run, outcome) => this.env.TARGET.report(run, outcome),
502
+ maxConcurrentRuns: 20,
503
+ runTimeoutMs: 15 * 60_000,
504
+ });
505
+
506
+ configure(expression: string, version: number) {
507
+ // Spread objects sharing an expression over the first 30 seconds.
508
+ return this.schedule.set({
509
+ expression,
510
+ version,
511
+ jitterMs: { maxMs: 30_000 },
512
+ });
513
+ }
514
+
515
+ remove(version: number) {
516
+ return this.schedule.cancel(version);
517
+ }
518
+
519
+ override alarm(info?: AlarmInvocationInfo) {
520
+ return this.scheduler.alarm(info);
521
+ }
522
+ }
523
+ ```
524
+
525
+ - **Versions.** `set({ expression, version })` stores the schedule and its next tick only when `version` is higher than the stored one, and resolves `true` when it did. A lower version is ignored. The same version changes nothing but reconciles the physical alarm, so resending it repairs a lost alarm. The expression is opaque; only `nextOccurrence(expression, after)` reads it, and it must return a safe integer after `after`, or `undefined` to stop ticking. `get()` returns `{ expression, version, jitterMs, nextAt }`, where `nextAt` is the next tick's nominal time, or `undefined` when no schedule is live.
526
+ - **Jitter.** `set({ expression, version, jitterMs })` delays every tick by one fixed offset, so many objects sharing a popular expression do not all fire at the same instant. `jitterMs` is either a non-negative integer, the offset itself, or `{ maxMs }`, which picks an offset uniformly in `[0, maxMs]` when the version is stored. It defaults to 0, and both forms are at most 2^31 - 1 ms. The offset is stored in the schedule's row, so it costs no write per run, and resending the same version keeps it; only a new version picks a new one. A tick's nominal time `scheduledTime` is what `nextOccurrence` returned, and it fires at `dueAt`, which is `scheduledTime + jitterMs`. `idempotencyKey` derives from `scheduledTime`, and the next tick is always searched from nominal times, so the offset never drifts. Keep `jitterMs` below the expression's interval; durability cannot know the interval of an opaque expression. A larger offset is allowed: every tick still fires once, in nominal order, each `jitterMs` after its nominal time, even when that is after the next tick's nominal time.
527
+ - **Cancel.** `cancel(version?)` stops future ticks and resolves `true` when a schedule was live. Runs already due or running still finish and report. With a version, the cancel is ignored when the stored version is higher, and is otherwise kept as a one-row tombstone so a delayed `set` of that version or lower cannot revive the schedule.
528
+ - **One tick, one run.** A tick inserts its run in the transaction that advances the stored next tick, so a replayed or duplicated alarm finds the cursor already moved and cannot fire the tick again; deduplication needs no finished-run records. When ticks were missed, for example while the object was down, they collapse into one run for the earliest missed time, and the next tick is the first whose `dueAt` is after now. A `nextOccurrence` that throws or returns an invalid time rolls the tick back and fails the alarm run, which is retried at `alarmMinDelayMs` and reported through `onAlarmRetry`.
529
+ - **Runs.** `run({ scheduledTime, dueAt, idempotencyKey, signal })` starts outside the alarm pass that recorded it, so a long run never delays later ticks. `idempotencyKey` is `<objectId>:<scheduledTime>`; on a named channel it ends with `:` and the JSON-encoded channel name, such as `<objectId>:<scheduledTime>:"library"`, so it never equals a default-channel key or another channel's. At most `maxConcurrentRuns` (default 10) are in flight; later runs wait durably in tick order. This limit is separate from the scheduler's `alarmConcurrency`. A run that throws, or exceeds `runTimeoutMs` (default 15 minutes, which aborts its `signal`), is `errored`. A run is attempted once and never retried. A timed-out run keeps its slot until its handler actually settles.
530
+ - **Keeping the object alive.** While runs or outcome deliveries are in flight, the alarm pass stays pending, so an alarm invocation stays open and holds the object in memory; it fires the next ticks and outcome retries itself, at their exact times. Before the wall-time limit the scheduler hands off at `alarmHandoffMs`, and the next alarm joins the same loop. A tick started by an in-memory timer is joined by the next physical alarm. Other helpers on the same scheduler still run on each alarm pass, but work of theirs that becomes due during the hold waits for it unless the scheduler uses `liveTimers`.
531
+ - **Interrupted runs.** A run still marked running when no live instance holds it, for example after the object was evicted, reset, or redeployed mid-run, is reported as `errored` with `ScheduledRunInterruptedError` on the next alarm, and is not run again. While a run or outcome delivery is in flight, the physical alarm stays on the next tick, which is its eviction fallback, so an interrupted run is reported by the next tick at the latest, or within `alarmMinDelayMs` when no tick is left.
532
+ - **Outcomes.** `onOutcome(run, outcome)` receives `{ scheduledTime, dueAt, idempotencyKey, attempt }` and `{ status: 'complete' }` or `{ status: 'errored', error: { name, message } }`. The outcome is persisted before the first delivery, so delivery is at least once with the same outcome, even across a crash. Returning acknowledges it and deletes the run's row; nothing about the run is kept afterwards. Throwing, or exceeding `outcomeTimeoutMs` (default 60 seconds), retries it with `outcomeRetries.delay(attempt)` (default jittered exponential capped at 5 minutes) up to `outcomeRetries.maxAttempts` (default 10) deliveries. After the last, the row is deleted, `durability.schedule.outcome_dead_lettered` is reported, and a `dead_lettered` lifecycle event is emitted.
533
+ - **Storage.** Two tables keyed by channel with no secondary indexes: `durability_schedule` holds one row per channel's schedule and `durability_schedule_runs` holds one small row per run from its tick until its outcome is delivered. A run writes four rows: the tick's cursor update and run insert, the outcome update, and the delete on delivery. It also arms the physical alarm once, for the next tick, and each `setAlarm()` is billed as a row written. A run that waits for a slot writes one more row, and each failed delivery one more.
534
+ - **Lifecycle events.** `onLifecycleEvent` receives `scheduled_run` events keyed by `idempotencyKey`: `due` (with `queued`), `started`, `settled` (with `outcome`, `error`, and `durationMs`), `outcome_retry`, and `dead_lettered`. Like every lifecycle hook, it is best effort.
535
+
536
+ - **Channels.** `channel` (default `default`) gives each instance its own schedule, versions, cancels, runs, outcome deliveries, and hooks, so a library can keep a schedule of its own in an object whose application has one; both may tick at the same scheduled time. One instance attaches per channel; attaching a second throws `DurabilitySchedule for channel "library" is already attached to this scheduler`. A channel whose runs hold the alarm invocation open does not delay another channel's ticks. Interrupted-run recovery only looks at the instance's own channel. The schedule and runs of a channel no instance attached, such as one a deploy removed, are kept unchanged and do not arm the alarm, with a `durability.channel_missing` report; reattaching that channel restores its alarm without requiring another application write, and its next alarm pass reports interrupted runs and fires missed ticks under the rules above. The `durability_0018_schedule_channels` migration moves an existing schedule and its runs to the default channel without changing their idempotency keys. Downgrading refuses to discard the schedules, including cancelled ones, and runs of named channels; let their outcomes deliver and remove their rows before rolling back.
537
+
538
+ Construct each channel's schedule once per object instance, as with every helper. `DurabilitySchedule.migrate(this.ctx, null)` removes its schema.
539
+
378
540
  ## Lifecycle metrics hook
379
541
 
380
542
  Each helper accepts `onLifecycleEvent`, which receives compact events for registration or scheduling, attempt start and settlement, pre-invocation attempt exhaustion, and purges:
@@ -571,6 +733,33 @@ An inbound handler is either a bare function, which receives no input or `unknow
571
733
 
572
734
  Every outbound event is persisted to `durability_socket_events` with a sequence number before it is pushed. A reconnecting client subscribes from the last sequence it saw: events still within `retention` (default 1000) are replayed in order, otherwise the client is told to resync and should rebuild its state from an inbound snapshot call. Payloads must be JSON. Keep-alive pings are answered by the runtime through `setWebSocketAutoResponse`, so idle connections never wake the object. Frames over 1 MiB are rejected; malformed frames close the connection with code `4002`.
573
735
 
736
+ ### Socket channels
737
+
738
+ Like the other helpers, `DurabilitySocket` takes a `channel` option, `default` unless given one, and each channel holds one socket per object. A library can bring its own socket into an object that already has one, even with the same method and event names:
739
+
740
+ ```ts
741
+ readonly librarySocket = new DurabilitySocket({
742
+ context: this.ctx,
743
+ channel: 'durable-alerts',
744
+ inbound: { list: () => this.alerts.list() },
745
+ outbound: { updated: event<Alert>() },
746
+ });
747
+
748
+ fetch(request: Request) {
749
+ // Which socket accepts an upgrade is up to the application.
750
+ return new URL(request.url).pathname.endsWith('/alerts')
751
+ ? this.librarySocket.fetch(request)
752
+ : this.socket.fetch(request);
753
+ }
754
+
755
+ webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
756
+ // Any socket routes a frame to the socket of the connection's channel.
757
+ return this.socket.webSocketMessage(ws, message);
758
+ }
759
+ ```
760
+
761
+ A connection belongs to the channel of the socket whose `fetch` accepted it; the channel is stored in its WebSocket attachment next to its metadata and subscriptions, so it survives hibernation. Its calls and subscriptions run only that socket's handlers, whichever socket the object's `webSocketMessage` delegates to, and an outbound method pushes only to its own channel's subscribers. Each channel numbers, retains, and replays its events independently, so one channel's traffic never trims another's history or makes its clients resync. Connections accepted before channels existed belong to `default`. A frame from a connection whose channel no socket attached, such as one a deploy removed, closes it with code `1011` and a `durability.socket.channel_missing` report; it never reaches another channel, and the channel's events are kept for when its socket attaches again. Attaching a second socket to a channel already in use throws. Events use the composite primary key `(channel, seq)`; existing events move to `default` with their sequence numbers. A schema downgrade refuses to discard non-default-channel events: revert those channels' sockets and delete their events first. The wire protocol and browser client are unchanged; point a client at the endpoint the application routes to that channel.
762
+
574
763
  The browser client derives every method and event type from the socket:
575
764
 
576
765
  ```ts
@@ -756,6 +945,9 @@ const grant = await limits.with(timeout, 5_000).request(accountId, {
756
945
 
757
946
  `usage()` reports the limit, outstanding permits, lease footprint, and per-group usage. `DurabilitySemaphore.migrate(this.ctx, null)` removes the schema.
758
947
 
948
+ - **Pools.** One object can hold several limits: give each `DurabilitySemaphore` its own `channel` (default `default`) and expose each through its own RPC method, then build one `DurabilitySemaphore.client()` per method. Each pool sees only its own limit, groups, rounds, grants, leases, and lease provisioning; a report sent to the wrong pool is answered `not_found` and frees nothing. Attaching a second semaphore to a channel in use throws. Grants and leases of a pool no instance attached are kept, untouched, until it attaches again.
949
+ - **Client identity.** The holder counts a client as its `clientId` together with the optional `clientChannel` of the queue that sent the message, `default` when omitted. Two queues on one object may share a `clientId` and a pool: neither can claim, release, or settle the other's grants or leases, and each receives only its own lease updates. Default clients keep protocol version 1 and its original response shape. Named queues use version 2 with `clientChannel`; the holder echoes both the version and channel. Old holders reject version 2 before allocating permits, even if they previously understood channels and were downgraded while idle.
950
+
759
951
  ### Leases
760
952
 
761
953
  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:
@@ -778,7 +970,7 @@ new DurabilitySemaphore({
778
970
  - **`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.
779
971
  - **`over`** — leases come from a separate budget above the limit (the original gatekeeper behaviour); the effective ceiling is `limit + extra`.
780
972
 
781
- 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.
973
+ Leases are issued only to clients that report `leases` (both default and named queues do), 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.
782
974
 
783
975
  ### Queueing work in a client Durable Object
784
976
 
@@ -839,9 +1031,10 @@ export class JobShard extends DurableObject<Env> {
839
1031
  - **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.
840
1032
  - **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.
841
1033
  - **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.
842
- - **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.
1034
+ - **Composition.** The queue shares the scheduler with everything else in the object and creates its own outbox channel on it: `durability.semaphore-queue` for the default queue, and the JSON tuple `["durability.semaphore-queue","<channel>"]` for a named one. Pass `DurabilitySemaphore.client()` as `server` — caller transforms apply to every request and sync.
1035
+ - **Channels.** Several queues share one object through `channel` (default `default`); each channel holds one queue. Items, grants, keys, and leases are scoped to the queue, so two queues may use the same item IDs and keys. A named queue sends version-2 messages with `clientChannel`, so queues sharing a `clientId` stay apart at the holder; which holder pool a key reaches is still decided by `server`. Old version-1 holders reject these messages before allocating grants or leases. The queue checks the response version and channel before applying it: incompatible peers leave its items queued and its reports pending for retry. Upgrade holders before giving queues a channel. The default queue's wire format and outbox channel are unchanged. Records of a queue channel no instance attached are kept, untouched, until it attaches again.
843
1036
 
844
- `DurabilitySemaphoreQueue.migrate(this.ctx, null)` removes the queue schema. See the typechecked [account concurrency composition](../../examples/account-concurrency).
1037
+ `DurabilitySemaphoreQueue.migrate(this.ctx, null)` removes the queue schema. Upgrading moves existing grants, leases, items, keys, and pending reports to the default pool, client channel, and queue without changing their IDs; a schema downgrade refuses to run while any pool, client channel, or queue other than `default` has records. See the typechecked [account concurrency composition](../../examples/account-concurrency).
845
1038
 
846
1039
  ## Routing and fanout
847
1040
 
@@ -903,6 +1096,8 @@ const result = await routing.push([{ id: 'job:42', body: job }], {
903
1096
 
904
1097
  The application chooses the RPC method via `invoke`; routing does not know about messages or fanout. A single push selects one shard for the entire input. Static fanout target IDs identify independent delivery obligations; each accepted message snapshots its recipients. Targets added later do not receive old work, and a removed target's work remains durable with an error and backoff until that ID is restored. Target callbacks/storage references are fixed at capability construction.
905
1098
 
1099
+ Several fanouts share one scheduler and one set of tables, partitioned by `channel` (default `default`), so a library can attach its own fanout beside the application's. Target IDs, message IDs, and deduplication keys are independent in each channel, and each instance delivers, settles, memoizes, and counts `pendingDeliveries` only for its own channel, with its own targets, policies, `dlq`, and lifecycle hooks. Attaching two fanouts with the same channel to one scheduler throws. Deliveries of a channel no fanout attaches are retained and postponed, with a `durability.channel_missing` report, until that channel's fanout attaches again.
1100
+
906
1101
  ### Acceptance, not completion
907
1102
 
908
1103
  `fanout.enqueue` accepts a message or batch and returns:
@@ -1178,6 +1373,24 @@ applyLimits(update: TopologyStateUpdate<Limits>) {
1178
1373
 
1179
1374
  `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.
1180
1375
 
1376
+ ### Instance channels
1377
+
1378
+ A `channel` option, `default` unless given one, lets several topologies share one coordinator and scheduler, for example an application's and a library's. Each channel holds one instance, with its own groups, state values, versions, publisher, and `deliver` callbacks: the same group and state names in two channels are unrelated groups, and deleting or updating one leaves the other alone. Constructing a second topology on a channel already in use throws `DurabilityTopology for channel "library" is already attached to this scheduler`, with or without a publisher.
1379
+
1380
+ ```ts
1381
+ private readonly libraryTopology = new DurabilityTopology({
1382
+ scheduler: this.scheduler,
1383
+ channel: 'library',
1384
+ publish: {
1385
+ write: (snapshot, encoded) =>
1386
+ this.env.TOPOLOGY.put(`library/${snapshot.group}`, encoded),
1387
+ delete: (group) => this.env.TOPOLOGY.delete(`library/${group}`),
1388
+ },
1389
+ });
1390
+ ```
1391
+
1392
+ Snapshots do not name the instance channel, and both instances record the same coordinator, so instances sharing one read store must publish under different keys, as above. The default instance keeps the outbox channels `durability.topology` and `durability.topology.<state>`; any other instance uses `["durability.topology", <channel>, "publication"]` and `["durability.topology", <channel>, "state", <state>]` as JSON, so no two instances or states can share an outbox channel, whatever their names contain. Pending publications and deliveries of an instance no longer constructed are kept and postponed, never handed to another instance. Groups, states, and write records are keyed by `owner_channel` plus their existing keys; existing rows migrate to `default` unchanged. A schema downgrade refuses to drop rows of other instance channels, including the tombstones `delete` leaves behind: delete those rows explicitly before rolling back.
1393
+
1181
1394
  ### Reading
1182
1395
 
1183
1396
  Stateless Workers read through a client. It has one method:
@@ -1223,8 +1436,8 @@ export class Partition extends DurableObject<Env> {
1223
1436
  // Flushed records stay readable: `write` returns a locator the log keeps,
1224
1437
  // and `read` hands the segment back when a consumer asks for it.
1225
1438
  cold: {
1226
- write: async ({ records, firstOffset }) => {
1227
- const locator = `segment/${this.ctx.id}/${firstOffset}`;
1439
+ write: async ({ channel = 'default', records, firstOffset }) => {
1440
+ const locator = `segment/${this.ctx.id}/${encodeURIComponent(channel)}/${firstOffset}`;
1228
1441
  await this.env.COLD.put(locator, JSON.stringify(records), {
1229
1442
  onlyIf: { etagDoesNotMatch: '*' },
1230
1443
  });
@@ -1284,7 +1497,7 @@ type LogColdStorage<Body> = {
1284
1497
  };
1285
1498
  ```
1286
1499
 
1287
- `write` receives one contiguous run of records, oldest first, and returns a locator — any string identifying where the segment went. The log stores that locator in a durable segment index **before** deleting the records, so a crash in between leaves a written, readable segment rather than records pointing nowhere. A failed write propagates with the records still in the object, so configured storage cannot be skipped, and writes are at-least-once, so key segments by first offset and refuse to overwrite.
1500
+ `write` receives one contiguous run of records, oldest first, with the log's `channel`, and returns a locator — any string identifying where the segment went. The log stores that locator in a durable segment index **before** deleting the records, so a crash in between leaves a written, readable segment rather than records pointing nowhere. A failed write propagates with the records still in the object, so configured storage cannot be skipped, and writes are at-least-once, so key segments by first offset and refuse to overwrite.
1288
1501
 
1289
1502
  `read` is what makes a flush **rehydratable**. A consumer reading a flushed offset gets its records back transparently, so falling behind the hot window is no longer fatal; `bounds()` reports `oldestOffset` (oldest readable, including flushed segments) alongside `hotOffset` (lowest offset still in the object). Cold reads cost a round trip and open input gates, so they serve only consumers that fell behind — never the hot path.
1290
1503
 
@@ -1318,6 +1531,24 @@ A range that keeps failing would be redelivered forever. `maxAttempts` bounds th
1318
1531
 
1319
1532
  Leases are opt-in. Without the `leases` option no lease tables are created, `read`/`commit` behave exactly as before, and the lease methods throw.
1320
1533
 
1534
+ ### Channels
1535
+
1536
+ A log attaches to a channel, `default` unless given one, and each channel holds one `DurabilityLog` per scheduler; a second instance on a channel in use throws `DurabilityLog for channel "events" is already attached to this scheduler`. Channels share the object but nothing else: each counts its own offsets from 0, and deduplication keys, consumer cursors, retention, byte budgets, cold segments, leases, batch ids, and `load()` are all scoped to the channel. A library can keep a log next to the application's, using the same keys and consumer names, and a `trim()` or lease on one never touches the other:
1537
+
1538
+ ```ts
1539
+ const events = new DurabilityLog<Event>({ scheduler, cold });
1540
+ const audit = new DurabilityLog<AuditEntry>({
1541
+ scheduler,
1542
+ channel: 'audit',
1543
+ retention: { maxRecords: 10_000 },
1544
+ cold,
1545
+ });
1546
+ ```
1547
+
1548
+ Because two channels both flush a segment starting at offset 0, cold storage shared between them must include `segment.channel ?? 'default'` in the location it writes to, as in the example above; otherwise one channel's segment overwrites or refuses the other's. The stored locator stays opaque and is read back only by the channel that wrote it, so locators written before channels existed keep working on `default`.
1549
+
1550
+ Records use composite keys such as `(channel, offset)` and `(channel, consumer)`; existing records, cursors, segments, leases, and allocations migrate to `default` unchanged. A log whose channel no instance attaches keeps its data and runs nothing, since a log schedules no work of its own. A schema downgrade refuses to discard a non-default channel's records, cursors, segments, offset counter, leases, or allocations.
1551
+
1321
1552
  ### What it is not
1322
1553
 
1323
1554
  There is no per-record retry, timeout, or dead letter here: a log tracks positions, not attempts. When a single record must be retried independently of its neighbours, that is fanout's job, and the two compose on one object.
@@ -1,8 +1,8 @@
1
- import { type DurabilityLifecycleEvent, type LifecycleHook } from './lifecycle.js';
2
- import { type DurabilityMigrationResult } from './migrations.js';
3
- import { type DurabilityAlarmMethodOptions, type ExecutionPolicyOptions } from './policy.js';
4
- import { type SchedulerAttachment } from './scheduler.js';
5
- import { type DurableMemoize } from './memoize.js';
1
+ import { type DurabilityLifecycleEvent, type LifecycleHook } from '../lifecycle.js';
2
+ import { type DurabilityMigrationResult } from '../migrations.js';
3
+ import { type DurabilityAlarmMethodOptions, type ExecutionPolicyOptions } from '../policy.js';
4
+ import { type SchedulerAttachment } from '../scheduler/index.js';
5
+ import { type DurableMemoize } from '../memoize/index.js';
6
6
  /** Information passed to a named alarm handler for one execution attempt. */
7
7
  export type DurableAlarmInfo = {
8
8
  /** Configured name of the logical alarm. */
@@ -51,6 +51,14 @@ export type DurabilityAlarmsOptions<Names extends string = string> = ExecutionPo
51
51
  export type DurabilityAlarmsConfig<Names extends string = string> = DurabilityAlarmsOptions<Names> & SchedulerAttachment & {
52
52
  /** Alarm handlers keyed by the scheduling method names they become. */
53
53
  handlers: Record<Names, DurableAlarmHandler>;
54
+ /**
55
+ * Stable channel ID. Instances on one scheduler share storage,
56
+ * partitioned by channel; alarm names are unique within a channel, and
57
+ * each instance runs, lists and purges only its own. A library should
58
+ * use its own channel so its alarms never meet the application's.
59
+ * Defaults to `default`.
60
+ */
61
+ channel?: string;
54
62
  };
55
63
  /** A lifecycle event for one of this instance's named alarms. */
56
64
  export type DurabilityAlarmEvent = Extract<DurabilityLifecycleEvent, {
@@ -59,7 +67,16 @@ export type DurabilityAlarmEvent = Extract<DurabilityLifecycleEvent, {
59
67
  type: 'purged';
60
68
  }>;
61
69
  /** Schedules (or replaces) the named alarm's pending occurrence. */
62
- export type DurableNamedAlarm = (scheduledTime: number) => Promise<void>;
70
+ export type DurableNamedAlarm = ((scheduledTime: number) => Promise<void>) & {
71
+ /**
72
+ * Experimental. Deletes the alarm's pending occurrence and reconciles the
73
+ * physical alarm, then aborts a running attempt of it. That attempt can no
74
+ * longer retry when it settles, but calling the scheduling method again,
75
+ * including from that handler, schedules a new occurrence. Resolves whether
76
+ * a pending occurrence was deleted.
77
+ */
78
+ cancel: () => Promise<boolean>;
79
+ };
63
80
  declare class DurabilityAlarmsCore<Names extends string> {
64
81
  #private;
65
82
  constructor(config: DurabilityAlarmsConfig<Names>);