durability 4.3.0 → 5.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,136 @@
1
+ import { z } from 'zod';
2
+ import { traceFunction } from './dev.js';
3
+ import { DurableMemoLimitError, DurableMemoSerializationError, } from './errors.js';
4
+ import { deserialize, serialize } from './serialization.js';
5
+ import { pendingGeneration, } from './storage.js';
6
+ /** The most keys one operation, alarm occurrence, or fanout delivery may memoize. */
7
+ export const maxMemosPerRecord = 1000;
8
+ /** The largest serialized memoized result, in UTF-8 bytes. */
9
+ export const maxMemoBytes = 1048576;
10
+ const memoLookupSchema = z.object({
11
+ result: z.string().nullable(),
12
+ owned: z.number().int(),
13
+ saved: z.number().int(),
14
+ });
15
+ const supersededError = (key) => new Error(`Memoized key ${JSON.stringify(key)} belongs to a superseded attempt`);
16
+ /** Memoization for one attempt; only that attempt may persist new results. */
17
+ export const createMemoize = (sql, table, ref) => {
18
+ const running = new Set();
19
+ /** Serializes, checks, and writes a callback's result, then returns its persisted form. */
20
+ const save = (key, value) => {
21
+ let serialized;
22
+ try {
23
+ serialized = serialize(value);
24
+ }
25
+ catch (error) {
26
+ throw new DurableMemoSerializationError(key, error);
27
+ }
28
+ const bytes = new TextEncoder().encode(serialized).byteLength;
29
+ if (bytes > maxMemoBytes) {
30
+ throw new DurableMemoLimitError(`Memoized result for ${JSON.stringify(key)} is ${bytes} bytes, over the ${maxMemoBytes}-byte limit`);
31
+ }
32
+ // A timed-out attempt that finishes late must not write over its successor.
33
+ const written = sql
34
+ .exec(`INSERT INTO durability_memos
35
+ (owner, key, generation_id, memo_key, result)
36
+ SELECT ?, ?, ?, ?, ?
37
+ WHERE EXISTS (
38
+ SELECT 1 FROM ${table.name}
39
+ WHERE ${pendingGeneration(table)} AND attempt = ?
40
+ )
41
+ RETURNING memo_key`, table.name, ref.key, ref.generation, key, serialized, ref.key, ref.generation, ref.attempt)
42
+ .toArray().length > 0;
43
+ if (!written) {
44
+ throw supersededError(key);
45
+ }
46
+ // Return what a replay would return, so later code sees one shape either way.
47
+ return deserialize(serialized);
48
+ };
49
+ // Everything up to the callback runs synchronously, so a concurrent call
50
+ // with the same key sees either the saved result or this key as running.
51
+ const run = async (key, callback) => {
52
+ if (typeof key !== 'string' || key === '') {
53
+ throw new TypeError('Memoize keys must be non-empty strings');
54
+ }
55
+ const lookup = memoLookupSchema.parse(sql
56
+ .exec(`SELECT
57
+ (SELECT result FROM durability_memos
58
+ WHERE owner = ? AND key = ? AND generation_id = ? AND memo_key = ?)
59
+ AS result,
60
+ EXISTS (
61
+ SELECT 1 FROM ${table.name}
62
+ WHERE ${pendingGeneration(table)} AND attempt = ?
63
+ ) AS owned,
64
+ (SELECT COUNT(*) FROM durability_memos
65
+ WHERE owner = ? AND key = ? AND generation_id = ?) AS saved`, table.name, ref.key, ref.generation, key, ref.key, ref.generation, ref.attempt, table.name, ref.key, ref.generation)
66
+ .toArray()[0]);
67
+ if (lookup.result !== null) {
68
+ return deserialize(lookup.result);
69
+ }
70
+ // A rescheduled or purged attempt must not start side effects it can never record.
71
+ if (lookup.owned === 0) {
72
+ throw supersededError(key);
73
+ }
74
+ // Waiting on the running call would deadlock a callback that memoizes its own key.
75
+ if (running.has(key)) {
76
+ throw new Error(`Memoized key ${JSON.stringify(key)} is already running; await the first call instead`);
77
+ }
78
+ // Running callbacks count too: each may save a result when it settles.
79
+ if (lookup.saved + running.size >= maxMemosPerRecord) {
80
+ throw new DurableMemoLimitError(`Memoizing ${JSON.stringify(key)} would exceed ${maxMemosPerRecord} keys`);
81
+ }
82
+ // The key stays running through serialization, so a getter that memoizes
83
+ // it again is rejected instead of running the callback a second time.
84
+ running.add(key);
85
+ try {
86
+ return save(key, await callback());
87
+ }
88
+ finally {
89
+ running.delete(key);
90
+ }
91
+ };
92
+ return (key, callback) => traceFunction('memoize', () => run(key, callback), {
93
+ owner: table.name,
94
+ key: ref.key,
95
+ attempt: ref.attempt,
96
+ memoKey: key,
97
+ })();
98
+ };
99
+ const memoKeySchema = z.object({ memo_key: z.string() });
100
+ /** Keys a record's current generation has results for, in the order they were saved. */
101
+ export const memoizedKeys = (sql, table, key, generation) => memoKeySchema
102
+ .array()
103
+ .parse(sql
104
+ .exec(`SELECT memo_key FROM durability_memos
105
+ WHERE owner = ? AND key = ? AND generation_id = ?
106
+ ORDER BY rowid`, table.name, key, generation)
107
+ .toArray())
108
+ .map((row) => row.memo_key);
109
+ /** Deletes every memoized result of a record, whichever generation wrote it. */
110
+ export const deleteMemos = (sql, table, key) => {
111
+ sql.exec('DELETE FROM durability_memos WHERE owner = ? AND key = ?', table.name, key);
112
+ };
113
+ /** Deletes memoized results whose record generation is no longer pending. */
114
+ export const deleteStaleMemos = (sql, table) => {
115
+ sql.exec(`DELETE FROM durability_memos
116
+ WHERE owner = ? AND NOT EXISTS (
117
+ SELECT 1 FROM ${table.name} AS record
118
+ WHERE record.${table.key} = durability_memos.key
119
+ AND record.generation_id = durability_memos.generation_id
120
+ AND record.status = 'pending'
121
+ )`, table.name);
122
+ };
123
+ const tableExists = (sql, name) => sql
124
+ .exec(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?`, name)
125
+ .toArray().length > 0;
126
+ /**
127
+ * Deletes the memoized results of a helper whose schema was reverted. The
128
+ * shared table stays for the other helper, but the removed records' results
129
+ * must not.
130
+ */
131
+ export const deleteMemosOfDroppedTable = (sql, table) => {
132
+ if (!tableExists(sql, 'durability_memos') || tableExists(sql, table.name)) {
133
+ return;
134
+ }
135
+ sql.exec('DELETE FROM durability_memos WHERE owner = ?', table.name);
136
+ };
@@ -19,6 +19,16 @@ export declare const durabilityNamedAlarmMigrations: {
19
19
  up: string;
20
20
  down: string;
21
21
  }[];
22
+ /**
23
+ * Ordered SQLite migrations for `durability_memos`, the memoized results that
24
+ * {@link Durability} and {@link DurabilityAlarms} share. Applied by whichever
25
+ * helper is constructed first.
26
+ */
27
+ export declare const durabilityMemoMigrations: {
28
+ name: string;
29
+ up: string;
30
+ down: string;
31
+ }[];
22
32
  /**
23
33
  * Ordered SQLite migrations for fanout manifests and deliveries. Applied
24
34
  * automatically on construction.
@@ -92,6 +102,15 @@ export declare const durabilityTopologyMigrations: {
92
102
  up: string;
93
103
  down: string;
94
104
  }[];
105
+ /**
106
+ * Ordered SQLite migrations for the experimental schedule. Applied
107
+ * automatically on construction.
108
+ */
109
+ export declare const durabilityScheduleMigrations: {
110
+ name: string;
111
+ up: string;
112
+ down: string;
113
+ }[];
95
114
  /** Migration names changed by one migrate call. */
96
115
  export type DurabilityMigrationResult = {
97
116
  /** Migrations applied in ascending order. */
@@ -99,8 +118,15 @@ export type DurabilityMigrationResult = {
99
118
  /** Migrations reverted in descending order. */
100
119
  rolledBack: string[];
101
120
  };
102
- export type MigrationCapability = 'operations' | 'namedAlarms' | 'fanout' | 'socket' | 'log' | 'logLeases' | 'outbox' | 'semaphore' | 'semaphoreQueue' | 'topology';
121
+ export type MigrationCapability = 'operations' | 'namedAlarms' | 'memos' | 'fanout' | 'socket' | 'log' | 'logLeases' | 'outbox' | 'semaphore' | 'semaphoreQueue' | 'topology' | 'schedule';
103
122
  type MigrationStorage = Pick<DurableObjectStorage, 'sql' | 'transactionSync'>;
123
+ /**
124
+ * Whether a capability's history already lists exactly these migrations with
125
+ * these `down` scripts, so construction can skip {@link migrateCapability}. Every Durable
126
+ * Object wake constructs its helpers, and each statement there is one more way
127
+ * for the wake to fail, so the common case costs one read.
128
+ */
129
+ export declare const isSchemaCurrent: (sql: SqlStorage, capability: MigrationCapability, migrations: DurableMigrations) => boolean;
104
130
  /**
105
131
  * Moves one capability's schema to a target migration, applying or reverting as
106
132
  * needed. `null` reverts every migration in the list; the shared migration
@@ -166,6 +166,27 @@ export const durabilityNamedAlarmMigrations = [
166
166
  `,
167
167
  },
168
168
  ];
169
+ /**
170
+ * Ordered SQLite migrations for `durability_memos`, the memoized results that
171
+ * {@link Durability} and {@link DurabilityAlarms} share. Applied by whichever
172
+ * helper is constructed first.
173
+ */
174
+ export const durabilityMemoMigrations = [
175
+ {
176
+ name: 'durability_0012_create_memos',
177
+ up: `
178
+ CREATE TABLE IF NOT EXISTS durability_memos (
179
+ owner TEXT NOT NULL,
180
+ key TEXT NOT NULL,
181
+ generation_id TEXT NOT NULL,
182
+ memo_key TEXT NOT NULL,
183
+ result TEXT NOT NULL,
184
+ PRIMARY KEY (owner, key, generation_id, memo_key)
185
+ );
186
+ `,
187
+ down: 'DROP TABLE IF EXISTS durability_memos;',
188
+ },
189
+ ];
169
190
  /**
170
191
  * Ordered SQLite migrations for fanout manifests and deliveries. Applied
171
192
  * automatically on construction.
@@ -549,6 +570,49 @@ export const durabilityTopologyMigrations = [
549
570
  `,
550
571
  },
551
572
  ];
573
+ /**
574
+ * Ordered SQLite migrations for the experimental schedule. Applied
575
+ * automatically on construction.
576
+ */
577
+ export const durabilityScheduleMigrations = [
578
+ {
579
+ name: 'durability_0013_create_schedule',
580
+ // INTEGER PRIMARY KEY aliases the rowid, so each table is a single b-tree
581
+ // with no secondary index for per-run writes to maintain.
582
+ up: `
583
+ CREATE TABLE IF NOT EXISTS durability_schedule (
584
+ id INTEGER PRIMARY KEY CHECK (id = 1),
585
+ version INTEGER NOT NULL,
586
+ expression TEXT,
587
+ next_at INTEGER
588
+ );
589
+ CREATE TABLE IF NOT EXISTS durability_schedule_runs (
590
+ scheduled_time INTEGER PRIMARY KEY,
591
+ state TEXT NOT NULL
592
+ CHECK (state IN ('queued', 'running', 'complete', 'errored')),
593
+ next_at INTEGER NOT NULL,
594
+ attempt INTEGER NOT NULL DEFAULT 0,
595
+ error TEXT
596
+ );
597
+ `,
598
+ down: `
599
+ DROP TABLE IF EXISTS durability_schedule_runs;
600
+ DROP TABLE IF EXISTS durability_schedule;
601
+ `,
602
+ },
603
+ {
604
+ name: 'durability_0014_add_schedule_jitter',
605
+ up: `
606
+ ALTER TABLE durability_schedule ADD COLUMN jitter_ms INTEGER NOT NULL DEFAULT 0;
607
+ ALTER TABLE durability_schedule_runs ADD COLUMN due_at INTEGER;
608
+ UPDATE durability_schedule_runs SET due_at = scheduled_time;
609
+ `,
610
+ down: `
611
+ ALTER TABLE durability_schedule_runs DROP COLUMN due_at;
612
+ ALTER TABLE durability_schedule DROP COLUMN jitter_ms;
613
+ `,
614
+ },
615
+ ];
552
616
  /**
553
617
  * Newer library versions may leave migrations this one does not know about.
554
618
  * On downgrade their stored `down` scripts are run, but only this many, so an
@@ -641,6 +705,34 @@ const revertFutureMigrations = (storage, scope, history, known) => {
641
705
  });
642
706
  return future.map(({ name }) => name);
643
707
  };
708
+ const currentRowSchema = z.object({
709
+ name: z.string(),
710
+ down: z.string().nullable(),
711
+ });
712
+ /**
713
+ * Whether a capability's history already lists exactly these migrations with
714
+ * these `down` scripts, so construction can skip {@link migrateCapability}. Every Durable
715
+ * Object wake constructs its helpers, and each statement there is one more way
716
+ * for the wake to fail, so the common case costs one read.
717
+ */
718
+ export const isSchemaCurrent = (sql, capability, migrations) => {
719
+ let rows;
720
+ try {
721
+ rows = currentRowSchema
722
+ .array()
723
+ .parse(sql
724
+ .exec(`SELECT name, down FROM ${migrationTableName} WHERE capability = ?`, capability)
725
+ .toArray());
726
+ }
727
+ catch {
728
+ // A first construction has no history table, and an older one lacks the
729
+ // capability column; migrateCapability() creates both, and retries any other failure.
730
+ return false;
731
+ }
732
+ const known = new Map(migrations.map(({ name, down }) => [name, down]));
733
+ return (rows.length === known.size &&
734
+ rows.every((row) => known.get(row.name) === row.down));
735
+ };
644
736
  const migrateScope = (storage, scope, migrations, target) => {
645
737
  storage = traceStorage(storage);
646
738
  const resolvedTarget = target === undefined
@@ -671,7 +763,7 @@ const migrateScope = (storage, scope, migrations, target) => {
671
763
  .filter(({ name }) => !applied.has(name));
672
764
  const toRefresh = migrations
673
765
  .slice(0, targetIndex + 1)
674
- .filter(({ name, down }) => applied.get(name)?.down !== down);
766
+ .filter(({ name, down }) => applied.has(name) && applied.get(name)?.down !== down);
675
767
  storage.transactionSync(() => {
676
768
  for (const migration of toRevert) {
677
769
  runDown(storage.sql, scope.table, migration.name, migration.down);
package/dist/outbox.js CHANGED
@@ -288,12 +288,11 @@ _DurabilityOutbox_engine = new WeakMap(), _DurabilityOutbox_channel = new WeakMa
288
288
  const deadline = Date.now() + __classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f");
289
289
  const claimed = [];
290
290
  for (const row of due) {
291
- const attempt = claimAttempt(sql, outboxTable, row.id, row.generation_id, Number.MAX_SAFE_INTEGER);
291
+ // A crash mid-publication leaves the claim due again at the deadline.
292
+ const attempt = claimAttempt(sql, outboxTable, row.id, row.generation_id, Number.MAX_SAFE_INTEGER, deadline);
292
293
  if (attempt === undefined) {
293
294
  continue;
294
295
  }
295
- // A crash mid-publication leaves the claim due again at the deadline.
296
- updateAttempt(sql, outboxTable, { key: row.id, generation: row.generation_id, attempt }, 'next_attempt_at = ?', deadline);
297
296
  claimed.push({ ...row, attempt });
298
297
  }
299
298
  return claimed;
@@ -0,0 +1,157 @@
1
+ import { type SerializedError } from './errors.js';
2
+ import { type DurabilityMigrationResult } from './migrations.js';
3
+ import { type DurabilityRetryOptions } from './policy.js';
4
+ import { type SchedulerAttachment } from './scheduler.js';
5
+ /** A schedule as passed to {@link DurabilitySchedule.set}. */
6
+ export type ScheduleDefinition = {
7
+ /** Opaque to durability: only `nextOccurrence` interprets it. */
8
+ expression: string;
9
+ /**
10
+ * Orders updates: `set` stores only a version higher than the stored one,
11
+ * and the same version only re-arms a lost alarm.
12
+ */
13
+ version: number;
14
+ /**
15
+ * Delays every tick by one fixed offset after its nominal time, to spread
16
+ * objects that share an expression. A number is the offset; `{ maxMs }`
17
+ * picks one uniformly in `[0, maxMs]` when the version is stored, so
18
+ * resending that version keeps it. Defaults to 0, at most 2^31 - 1. Keep
19
+ * it below the expression's interval.
20
+ */
21
+ jitterMs?: number | {
22
+ maxMs: number;
23
+ };
24
+ };
25
+ /** The stored schedule returned by {@link DurabilitySchedule.get}. */
26
+ export type ScheduleState = {
27
+ expression: string;
28
+ version: number;
29
+ /** The stored offset, including one picked from `{ maxMs }`. */
30
+ jitterMs: number;
31
+ /**
32
+ * The next tick's nominal time, or `undefined` once `nextOccurrence`
33
+ * returned none. It fires at `nextAt + jitterMs`.
34
+ */
35
+ nextAt: number | undefined;
36
+ };
37
+ /** One tick's run. */
38
+ export type ScheduledRun = {
39
+ /** The tick's nominal time, as `nextOccurrence` returned it. */
40
+ scheduledTime: number;
41
+ /**
42
+ * When the tick fired: `scheduledTime` plus the schedule's `jitterMs`. A run
43
+ * that waited for a slot starts later.
44
+ */
45
+ dueAt: number;
46
+ /**
47
+ * `<objectId>:<scheduledTime>`, or the bare scheduled time when the context
48
+ * has no object ID. A tick fires at most once, so the key is unique per run.
49
+ */
50
+ idempotencyKey: string;
51
+ };
52
+ /** What `run` receives. */
53
+ export type ScheduledRunContext = ScheduledRun & {
54
+ /** Aborted when the run exceeds `runTimeoutMs`. */
55
+ signal: AbortSignal;
56
+ };
57
+ /** What a run ended with, as passed to `onOutcome`. */
58
+ export type ScheduledRunOutcome = {
59
+ status: 'complete';
60
+ } | {
61
+ status: 'errored';
62
+ error: SerializedError;
63
+ };
64
+ /** The run an `onOutcome` call reports. */
65
+ export type ScheduledOutcomeDelivery = ScheduledRun & {
66
+ /** One-based delivery attempt of this outcome. */
67
+ attempt: number;
68
+ };
69
+ type ScheduledRunEntity = {
70
+ entityKind: 'scheduled_run';
71
+ /** The run's idempotency key. */
72
+ id: string;
73
+ scheduledTime: number;
74
+ timestamp: number;
75
+ };
76
+ /** Best-effort lifecycle signal for one scheduled run. */
77
+ export type DurabilityScheduleEvent = ScheduledRunEntity & ({
78
+ /** A tick recorded the run; `queued` when no run slot was free. */
79
+ type: 'due';
80
+ queued: boolean;
81
+ } | {
82
+ type: 'started';
83
+ } | {
84
+ /**
85
+ * The outcome was recorded. An interrupted run has no `durationMs` and
86
+ * a `ScheduledRunInterruptedError`.
87
+ */
88
+ type: 'settled';
89
+ outcome: ScheduledRunOutcome['status'];
90
+ error?: SerializedError;
91
+ durationMs?: number;
92
+ } | {
93
+ type: 'outcome_retry';
94
+ attempt: number;
95
+ error: SerializedError;
96
+ nextAttemptAt: number;
97
+ } | {
98
+ /** `onOutcome` failed `maxAttempts` times; the run's row is deleted. */
99
+ type: 'dead_lettered';
100
+ attempt: number;
101
+ error: SerializedError;
102
+ });
103
+ export type DurabilityScheduleConfig = SchedulerAttachment & {
104
+ /**
105
+ * Returns the first tick strictly after `after`, or `undefined` for none.
106
+ * Must be synchronous and deterministic; durability ships no cron parser.
107
+ */
108
+ nextOccurrence(expression: string, after: number): number | undefined;
109
+ /** The work of one tick. Throwing or timing out makes the run `errored`. */
110
+ run(run: ScheduledRunContext): unknown;
111
+ /**
112
+ * Receives each run's outcome at least once. Returning acknowledges it and
113
+ * deletes the run's row; throwing retries it with `outcomeRetries`.
114
+ */
115
+ onOutcome(run: ScheduledOutcomeDelivery, outcome: ScheduledRunOutcome): unknown;
116
+ /** Runs in flight at once; later runs wait durably in order. Defaults to 10. */
117
+ maxConcurrentRuns?: number;
118
+ /** Maximum duration of one run. Defaults to 15 minutes. */
119
+ runTimeoutMs?: number;
120
+ /** Maximum duration of one `onOutcome` call. Defaults to 60 seconds. */
121
+ outcomeTimeoutMs?: number;
122
+ /** `onOutcome` retries. `maxAttempts` defaults to 10, counting the first. */
123
+ outcomeRetries?: DurabilityRetryOptions;
124
+ onLifecycleEvent?: (event: DurabilityScheduleEvent) => void | Promise<void>;
125
+ };
126
+ /**
127
+ * Experimental. One recurring schedule per Durable Object whose ticks start
128
+ * individually tracked, overlapping runs and report each run's outcome once,
129
+ * keeping a run's row only until its outcome is delivered.
130
+ *
131
+ * A tick inserts its run in the transaction that advances the stored next
132
+ * tick, so a tick fires at most once without retaining finished runs. Missed
133
+ * ticks collapse into one run for the earliest missed time.
134
+ */
135
+ export declare class DurabilitySchedule {
136
+ #private;
137
+ constructor(config: DurabilityScheduleConfig);
138
+ static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
139
+ alarm(info?: AlarmInvocationInfo): Promise<void>;
140
+ /** The stored schedule, or `undefined` when none is set or it was cancelled. */
141
+ get(): ScheduleState | undefined;
142
+ /**
143
+ * Stores the schedule and its next tick when `version` is higher than the
144
+ * stored one, and resolves `true` when it did. A lower version is ignored; the
145
+ * same version changes nothing, keeping its stored jitter, but re-arms the
146
+ * alarm if it was lost.
147
+ */
148
+ set(definition: ScheduleDefinition): Promise<boolean>;
149
+ /**
150
+ * Stops future ticks and resolves `true` when a schedule was live. Runs
151
+ * already due or running still finish and report. With `version`, the
152
+ * cancellation is ignored when the stored version is higher, and is
153
+ * otherwise recorded so a later `set` of that version or lower is ignored.
154
+ */
155
+ cancel(version?: number): Promise<boolean>;
156
+ }
157
+ export {};