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
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Ordered SQLite migrations for the experimental schedule. Applied
3
+ * automatically on construction.
4
+ */
5
+ export declare const durabilityScheduleMigrations: {
6
+ name: string;
7
+ up: string;
8
+ down: string;
9
+ }[];
@@ -0,0 +1,118 @@
1
+ /**
2
+ * Ordered SQLite migrations for the experimental schedule. Applied
3
+ * automatically on construction.
4
+ */
5
+ export const durabilityScheduleMigrations = [
6
+ {
7
+ name: 'durability_0013_create_schedule',
8
+ // INTEGER PRIMARY KEY aliases the rowid, so each table is a single b-tree
9
+ // with no secondary index for per-run writes to maintain.
10
+ up: `
11
+ CREATE TABLE IF NOT EXISTS durability_schedule (
12
+ id INTEGER PRIMARY KEY CHECK (id = 1),
13
+ version INTEGER NOT NULL,
14
+ expression TEXT,
15
+ next_at INTEGER
16
+ );
17
+ CREATE TABLE IF NOT EXISTS durability_schedule_runs (
18
+ scheduled_time INTEGER PRIMARY KEY,
19
+ state TEXT NOT NULL
20
+ CHECK (state IN ('queued', 'running', 'complete', 'errored')),
21
+ next_at INTEGER NOT NULL,
22
+ attempt INTEGER NOT NULL DEFAULT 0,
23
+ error TEXT
24
+ );
25
+ `,
26
+ down: `
27
+ DROP TABLE IF EXISTS durability_schedule_runs;
28
+ DROP TABLE IF EXISTS durability_schedule;
29
+ `,
30
+ },
31
+ {
32
+ name: 'durability_0014_add_schedule_jitter',
33
+ up: `
34
+ ALTER TABLE durability_schedule ADD COLUMN jitter_ms INTEGER NOT NULL DEFAULT 0;
35
+ ALTER TABLE durability_schedule_runs ADD COLUMN due_at INTEGER;
36
+ UPDATE durability_schedule_runs SET due_at = scheduled_time;
37
+ `,
38
+ down: `
39
+ ALTER TABLE durability_schedule_runs DROP COLUMN due_at;
40
+ ALTER TABLE durability_schedule DROP COLUMN jitter_ms;
41
+ `,
42
+ },
43
+ {
44
+ name: 'durability_0018_schedule_channels',
45
+ // WITHOUT ROWID keeps each table a single b-tree under its composite key,
46
+ // so per-run writes still maintain no secondary index.
47
+ up: `
48
+ ALTER TABLE durability_schedule RENAME TO durability_schedule_before_channels;
49
+ CREATE TABLE durability_schedule (
50
+ channel TEXT NOT NULL DEFAULT 'default',
51
+ id INTEGER NOT NULL CHECK (id = 1),
52
+ version INTEGER NOT NULL,
53
+ expression TEXT,
54
+ next_at INTEGER,
55
+ jitter_ms INTEGER NOT NULL DEFAULT 0,
56
+ PRIMARY KEY (channel, id)
57
+ ) WITHOUT ROWID;
58
+ INSERT INTO durability_schedule
59
+ (channel, id, version, expression, next_at, jitter_ms)
60
+ SELECT 'default', id, version, expression, next_at, jitter_ms
61
+ FROM durability_schedule_before_channels;
62
+ DROP TABLE durability_schedule_before_channels;
63
+ ALTER TABLE durability_schedule_runs RENAME TO durability_schedule_runs_before_channels;
64
+ CREATE TABLE durability_schedule_runs (
65
+ channel TEXT NOT NULL DEFAULT 'default',
66
+ scheduled_time INTEGER NOT NULL,
67
+ state TEXT NOT NULL
68
+ CHECK (state IN ('queued', 'running', 'complete', 'errored')),
69
+ next_at INTEGER NOT NULL,
70
+ attempt INTEGER NOT NULL DEFAULT 0,
71
+ error TEXT,
72
+ due_at INTEGER,
73
+ PRIMARY KEY (channel, scheduled_time)
74
+ ) WITHOUT ROWID;
75
+ INSERT INTO durability_schedule_runs
76
+ (channel, scheduled_time, state, next_at, attempt, error, due_at)
77
+ SELECT 'default', scheduled_time, state, next_at, attempt, error, due_at
78
+ FROM durability_schedule_runs_before_channels;
79
+ DROP TABLE durability_schedule_runs_before_channels;
80
+ `,
81
+ down: `
82
+ CREATE TABLE durability_schedule_channel_guard (
83
+ channel TEXT CONSTRAINT cannot_downgrade_nondefault_channels CHECK (channel = 'default')
84
+ );
85
+ INSERT INTO durability_schedule_channel_guard
86
+ SELECT channel FROM durability_schedule
87
+ UNION SELECT channel FROM durability_schedule_runs;
88
+ DROP TABLE durability_schedule_channel_guard;
89
+ ALTER TABLE durability_schedule RENAME TO durability_schedule_with_channels;
90
+ CREATE TABLE durability_schedule (
91
+ id INTEGER PRIMARY KEY CHECK (id = 1),
92
+ version INTEGER NOT NULL,
93
+ expression TEXT,
94
+ next_at INTEGER,
95
+ jitter_ms INTEGER NOT NULL DEFAULT 0
96
+ );
97
+ INSERT INTO durability_schedule (id, version, expression, next_at, jitter_ms)
98
+ SELECT id, version, expression, next_at, jitter_ms
99
+ FROM durability_schedule_with_channels;
100
+ DROP TABLE durability_schedule_with_channels;
101
+ ALTER TABLE durability_schedule_runs RENAME TO durability_schedule_runs_with_channels;
102
+ CREATE TABLE durability_schedule_runs (
103
+ scheduled_time INTEGER PRIMARY KEY,
104
+ state TEXT NOT NULL
105
+ CHECK (state IN ('queued', 'running', 'complete', 'errored')),
106
+ next_at INTEGER NOT NULL,
107
+ attempt INTEGER NOT NULL DEFAULT 0,
108
+ error TEXT,
109
+ due_at INTEGER
110
+ );
111
+ INSERT INTO durability_schedule_runs
112
+ (scheduled_time, state, next_at, attempt, error, due_at)
113
+ SELECT scheduled_time, state, next_at, attempt, error, due_at
114
+ FROM durability_schedule_runs_with_channels;
115
+ DROP TABLE durability_schedule_runs_with_channels;
116
+ `,
117
+ },
118
+ ];
@@ -1,7 +1,8 @@
1
- import { type DurabilityLifecycleEvent, type Emit, type LifecycleEntity } from './lifecycle.js';
2
- import { type MigrationCapability } from './migrations.js';
3
- import { type AttemptPolicy } from './policy.js';
4
- import { type DurableTable } from './storage.js';
1
+ import { type SerializedError } from '../errors.js';
2
+ import { type DurabilityLifecycleEvent, type Emit, type LifecycleEntity } from '../lifecycle.js';
3
+ import { type MigrationCapability } from '../migrations.js';
4
+ import { type AttemptPolicy } from '../policy.js';
5
+ import { type DurableTable } from '../storage.js';
5
6
  import type { DurableMigrations } from '@durability/storage';
6
7
  /** The Durable Object state durability needs: storage plus optional `waitUntil`. */
7
8
  export type DurabilityContext = Pick<DurableObjectState, 'storage'> & Partial<Pick<DurableObjectState, 'waitUntil'>>;
@@ -13,14 +14,42 @@ export type DurabilitySchedulerOptions = {
13
14
  alarmMinDelayMs?: number;
14
15
  /** Time before a running alarm hands unfinished work to a new alarm. Defaults to 14 minutes. */
15
16
  alarmHandoffMs?: number;
17
+ /**
18
+ * Experimental. Start due work from in-memory timers at its exact scheduled
19
+ * time, independent of `alarmMinDelayMs`, and let newly due work run without
20
+ * waiting behind long-running handlers. The physical alarm stays armed as the
21
+ * eviction fallback. Off by default.
22
+ */
23
+ liveTimers?: boolean;
24
+ /**
25
+ * Called each time an alarm run fails and the scheduler re-arms its own
26
+ * fallback alarm instead of letting the platform retry, for example to send
27
+ * the error to an external service. Best effort: it runs after the fallback is
28
+ * armed, a returned promise is passed to `waitUntil`, and a throw or rejection
29
+ * is only logged, so it never changes scheduling.
30
+ */
31
+ onAlarmRetry?: (info: AlarmRetryInfo) => void | Promise<void>;
32
+ };
33
+ /** Details of a failed alarm run passed to `onAlarmRetry`. */
34
+ export type AlarmRetryInfo = {
35
+ error: SerializedError;
36
+ /** Delay until the re-armed fallback alarm fires. */
37
+ retryInMs: number;
38
+ /** The platform's retry count for this alarm invocation, when it provided one. */
39
+ retryCount?: number;
40
+ /** Whether the platform marked this invocation as a retry, when it provided one. */
41
+ isRetry?: boolean;
42
+ /** The owning Durable Object's ID, when the context carries one. */
43
+ objectId?: string;
16
44
  };
17
45
  /** Configuration for a scheduler shared by several helpers. */
18
46
  export type DurabilitySchedulerConfig = DurabilitySchedulerOptions & {
19
47
  context: DurabilityContext;
20
48
  };
21
49
  /**
22
- * How a helper attaches to a scheduler: an existing shared one, or a private
23
- * one created from the Durable Object context with the given scheduler options.
50
+ * How a helper attaches to the object's scheduler: through a
51
+ * {@link DurabilityScheduler}, or from the Durable Object context, which joins
52
+ * the scheduler already there or creates it with the given options.
24
53
  */
25
54
  export type SchedulerAttachment = {
26
55
  scheduler: DurabilityScheduler;
@@ -34,7 +63,30 @@ export type Participant = {
34
63
  runDue(now: number, info: AlarmInvocationInfo | undefined): Promise<void>;
35
64
  /** Earliest due time, for tables without `status` and `next_attempt_at` columns. */
36
65
  nextPendingAt?(sql: SqlStorage): number | undefined;
66
+ /** Earliest work not already executing; active work still keeps its physical fallback. */
67
+ nextTimerAt?(sql: SqlStorage): number | undefined;
68
+ /**
69
+ * True while the participant runs its own due work from an alarm invocation
70
+ * it keeps open. The in-memory timer then ignores its pending time, which only
71
+ * arms the physical alarm as the eviction fallback.
72
+ */
73
+ holding?(): boolean;
74
+ };
75
+ /** The channel every helper uses when it is not given one. */
76
+ export declare const defaultChannel = "default";
77
+ /**
78
+ * One helper instance's share of a table that several instances partition by
79
+ * a `channel` column. Each runs only its own channel's due rows.
80
+ */
81
+ export type ChannelParticipant = Participant & {
82
+ channel: string;
83
+ /** How errors name the helper, such as `An outbox`. */
84
+ helper: string;
85
+ /** Other tables carrying this capability's channel identity, such as its configuration. */
86
+ channelTables?: readonly string[];
37
87
  };
88
+ /** Rejects a channel name a helper would otherwise store rows under. */
89
+ export declare const assertChannel: (helper: string, channel: unknown) => string;
38
90
  /**
39
91
  * Called after a record may have settled. Successful completions pass the
40
92
  * executed row because some tables delete it on success; other changes pass
@@ -80,20 +132,50 @@ export type ExecutionSpec = {
80
132
  */
81
133
  export declare class Engine {
82
134
  readonly sql: SqlStorage;
83
- private readonly context;
135
+ private context;
84
136
  private readonly storage;
85
- private readonly alarmConcurrency;
86
- private readonly alarmMinDelayMs;
87
- private readonly alarmHandoffMs;
137
+ private alarmConcurrency;
138
+ private alarmMinDelayMs;
139
+ private alarmHandoffMs;
140
+ liveTimers: boolean;
141
+ private onAlarmRetry;
142
+ private explicitOptions;
88
143
  private readonly participants;
144
+ private readonly channelsByTable;
145
+ private readonly claimedChannels;
146
+ private readonly reportedMissingChannels;
89
147
  private readonly migrated;
90
148
  private availablePermits;
91
149
  private readonly permitWaiters;
92
150
  private alarmRefresh;
151
+ private alarmRefreshRequested;
152
+ private failedRuns;
93
153
  private earlyAlarm;
94
154
  private readonly watchers;
155
+ private readonly activeByTable;
95
156
  constructor(context: DurabilityContext, options: DurabilitySchedulerOptions);
157
+ /**
158
+ * Joins one more helper or scheduler handle to this object's scheduler. The
159
+ * first context that can `waitUntil` is kept, so a bare `{ storage }` context
160
+ * attached first does not hide it from the rest.
161
+ */
162
+ attach(context: DurabilityContext, options: DurabilitySchedulerOptions): void;
163
+ private configure;
96
164
  register(participant: Participant): void;
165
+ /** Reserves an instance identity, including for helpers that do not schedule work. */
166
+ claimChannel(kind: string, channel: string, helper: string): void;
167
+ /**
168
+ * Attaches one channel of a table several helper instances share. The first
169
+ * attachment registers the table; each run then runs every attached
170
+ * channel's due rows and retains the rows of channels nothing attached.
171
+ */
172
+ registerChannel(participant: ChannelParticipant): void;
173
+ /**
174
+ * Due rows of a channel no instance attached, such as one a deploy removed
175
+ * or a library not yet constructed, would keep the alarm awake forever. They
176
+ * are kept and looked at again later, since their owner may return.
177
+ */
178
+ private postponeUnattachedChannels;
97
179
  waitUntil(promise: Promise<unknown>, onError: (error: unknown) => void): void;
98
180
  /**
99
181
  * The owning Durable Object's ID. The public context type omits it, but the
@@ -113,10 +195,22 @@ export declare class Engine {
113
195
  * transaction, then publishes the in-memory timer only after commit.
114
196
  */
115
197
  transaction<T>(write: (sql: SqlStorage) => T): Promise<T>;
116
- /** Returns the earliest pending time and maintains its bounded physical fallback. */
198
+ private trackActive;
199
+ private releaseActive;
200
+ /**
201
+ * The earliest pending time for one participant: `physical` arms the physical
202
+ * alarm (eviction fallback) and includes active work; `timer` drives the
203
+ * in-memory timer and skips work that is already executing
204
+ * so a still-due active row cannot re-fire a zero-delay timer in a loop.
205
+ */
206
+ private pendingTimes;
207
+ /**
208
+ * Arms the physical alarm from the earliest pending time (the eviction
209
+ * fallback) and returns the earliest time the in-memory timer should fire.
210
+ */
117
211
  private reconcile;
118
212
  private scheduleEarlyAlarm;
119
- /** Coalesces concurrent refresh requests into one reconciliation transaction. */
213
+ /** Coalesces refreshes without dropping requests arriving after the pending-work read. */
120
214
  scheduleNextAlarm(): Promise<void>;
121
215
  /**
122
216
  * Aborts matching active handlers, then deletes one kind's records created
@@ -137,6 +231,14 @@ export declare class Engine {
137
231
  * because the platform drops an alarm after a few failed deliveries.
138
232
  */
139
233
  alarm(info?: AlarmInvocationInfo): Promise<void>;
234
+ /**
235
+ * A transient storage fault would otherwise leave all due work to the
236
+ * fallback alarm, up to `alarmMinDelayMs` away: longer than a holder's
237
+ * grant window, for one. The in-memory timer retries sooner, backing off to
238
+ * that fallback while runs keep failing.
239
+ */
240
+ private retryFailedRun;
241
+ private notifyAlarmRetry;
140
242
  /**
141
243
  * Runs every participant's due work, hands off to a fresh alarm if the
142
244
  * invocation approaches its wall-time limit, and re-arms the physical alarm.
@@ -155,13 +257,14 @@ export declare class Engine {
155
257
  private settleFailure;
156
258
  }
157
259
  /**
158
- * Owns the Durable Object's physical alarm, storage, and concurrency
159
- * pool so {@link Durability} and {@link DurabilityAlarms} can share them.
260
+ * Owns the Durable Object's physical alarm, storage, and concurrency pool so
261
+ * every durability helper on the object shares them.
160
262
  *
161
- * Construct one per Durable Object when using both helpers, pass it to each,
162
- * and delegate the object's `alarm` method to {@link DurabilityScheduler.alarm}.
163
- * A helper constructed directly from the Durable Object context creates a
164
- * private scheduler instead.
263
+ * A Durable Object has one scheduler. Constructing another for the same
264
+ * object, or a helper from the object's context, joins it; scheduler options
265
+ * merge, and a different value for an option already set throws. Delegate the
266
+ * object's `alarm` method to {@link DurabilityScheduler.alarm} or to any
267
+ * helper's `alarm`: each runs the due work of every helper on the object.
165
268
  *
166
269
  * @example
167
270
  * ```ts
@@ -187,8 +290,5 @@ export declare class DurabilityScheduler {
187
290
  /** Runs due work for every attached helper and re-arms the physical alarm. */
188
291
  alarm(info?: AlarmInvocationInfo): Promise<void>;
189
292
  }
190
- /**
191
- * Resolves the engine a helper should attach to: the shared one behind a
192
- * scheduler, or a private one built from the Durable Object context.
193
- */
293
+ /** Resolves the engine a helper attaches to: the object's one scheduler. */
194
294
  export declare const engineFor: (attachment: SchedulerAttachment) => Engine;