durability 4.2.0 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/fanout.js CHANGED
@@ -11,10 +11,11 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
11
11
  };
12
12
  var _DurabilityFanout_instances, _DurabilityFanout_engine, _DurabilityFanout_routing, _DurabilityFanout_targets, _DurabilityFanout_policies, _DurabilityFanout_dlq, _DurabilityFanout_maxBatchSize, _DurabilityFanout_batchDelayMs, _DurabilityFanout_lifecycle, _DurabilityFanout_emit, _DurabilityFanout_running, _DurabilityFanout_pending, _DurabilityFanout_firstAttemptAt, _DurabilityFanout_runDue, _DurabilityFanout_runTarget, _DurabilityFanout_postpone, _DurabilityFanout_deliver, _DurabilityFanout_ackUnsettled, _DurabilityFanout_message, _DurabilityFanout_remove, _DurabilityFanout_removeDelivery, _DurabilityFanout_retry, _DurabilityFanout_deadLetter, _DurabilityFanout_emitTerminal, _DurabilityFanout_transaction, _DurabilityFanout_pendingCount, _DurabilityFanout_adjustPending, _DurabilityFanout_listDue, _DurabilityFanout_deadline;
13
13
  import { z } from 'zod';
14
+ import { traceFunction, traceMethods } from './dev.js';
14
15
  import { DurableRetryPolicyError, FanoutEnqueueError, FanoutSettlementError, FanoutTimeoutError, reportFailure, serializeError, } from './errors.js';
15
16
  import { createLifecycleHooks, } from './lifecycle.js';
16
17
  import { RoutingLoad } from './load.js';
17
- import { durabilityFanoutMigrations, migrate } from './migrations.js';
18
+ import { durabilityFanoutMigrations, migrateCapability } from './migrations.js';
18
19
  import { assertPositiveInteger, createPolicyResolver, methodOptionsSchema, } from './policy.js';
19
20
  import { engineFor, } from './scheduler.js';
20
21
  import { deserialize, serialize } from './serialization.js';
@@ -125,7 +126,7 @@ export class DurabilityFanout {
125
126
  });
126
127
  }
127
128
  static migrate(context, target) {
128
- return migrate(context.storage, 'fanout', durabilityFanoutMigrations, target);
129
+ return migrateCapability(context.storage, 'fanout', durabilityFanoutMigrations, target);
129
130
  }
130
131
  alarm(info) {
131
132
  return __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").alarm(info);
@@ -501,6 +502,10 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
501
502
  }
502
503
  }, _DurabilityFanout_message = function _DurabilityFanout_message(state, policy, startedAt) {
503
504
  const { row, message } = state.claim;
505
+ const identity = {
506
+ deliveryId: deliveryIdentity(row),
507
+ target: row.target_id,
508
+ };
504
509
  const settle = (outcome, action) => {
505
510
  if (state.closed || state.outcome !== undefined) {
506
511
  return Promise.reject(new FanoutSettlementError(message.id, state.outcome));
@@ -519,12 +524,11 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
519
524
  };
520
525
  return {
521
526
  id: message.id,
522
- deliveryId: deliveryIdentity(row),
523
- target: row.target_id,
527
+ ...identity,
524
528
  body: deserialize(message.payload),
525
529
  enqueuedAt: message.created_at,
526
530
  attempt: row.attempt,
527
- ack: () => settle('ack', async () => {
531
+ ack: traceFunction('DurabilityFanoutMessage.ack', () => settle('ack', async () => {
528
532
  await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_remove).call(this, row);
529
533
  __classPrivateFieldGet(this, _DurabilityFanout_emit, "f").call(this, {
530
534
  ...entity(state.claim),
@@ -534,8 +538,8 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
534
538
  durationMs: Math.max(0, Date.now() - startedAt),
535
539
  outcome: 'completed',
536
540
  });
537
- }),
538
- retry: (delayMs) => {
541
+ }), identity),
542
+ retry: traceFunction('DurabilityFanoutMessage.retry', (delayMs) => {
539
543
  if (delayMs !== undefined &&
540
544
  (!Number.isSafeInteger(delayMs) ||
541
545
  delayMs < 0 ||
@@ -543,8 +547,8 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
543
547
  return Promise.reject(new RangeError('delayMs must produce a non-negative safe-integer timestamp'));
544
548
  }
545
549
  return settle('retry', () => __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_retry).call(this, state.claim, policy, delayMs, { name: 'Retry', message: 'Retried by consumer' }, startedAt));
546
- },
547
- deadLetter: () => settle('deadLetter', () => __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_deadLetter).call(this, state.claim, 'explicit')),
550
+ }, identity),
551
+ deadLetter: traceFunction('DurabilityFanoutMessage.deadLetter', () => settle('deadLetter', () => __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_deadLetter).call(this, state.claim, 'explicit')), identity),
548
552
  };
549
553
  }, _DurabilityFanout_remove = async function _DurabilityFanout_remove(row) {
550
554
  await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_transaction).call(this, (sql) => {
@@ -706,3 +710,4 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_routing = new WeakMa
706
710
  }
707
711
  }
708
712
  };
713
+ traceMethods(DurabilityFanout.prototype, 'DurabilityFanout');
package/dist/index.d.ts CHANGED
@@ -7,5 +7,6 @@ export type { MessageWrite, StoredMessage } from './stored-message.js';
7
7
  export { DurabilityScheduler, type DurabilityContext, type DurabilitySchedulerConfig, type DurabilitySchedulerOptions, type SchedulerAttachment, } from './scheduler.js';
8
8
  export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
9
9
  export type { DurabilityLifecycleEvent, LifecycleHook } from './lifecycle.js';
10
- export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, type DurabilityMigrationResult, type MigrationCapability, } from './migrations.js';
10
+ export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, migrate, type DurabilityMigrationResult, type MigrateOptions, type MigrationCapability, } from './migrations.js';
11
+ export type { DurableMigrations } from '@durability/storage';
11
12
  export type { DurabilityAlarmMethodOptions, DurabilityMethodOptions, DurabilityRetryOptions, } from './policy.js';
package/dist/index.js CHANGED
@@ -5,4 +5,4 @@ export { DurabilityLog, maxLogBytes, } from './log.js';
5
5
  export { RoutingLoad, } from './load.js';
6
6
  export { DurabilityScheduler, } from './scheduler.js';
7
7
  export { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAlarmTimeoutError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, DurableRetryPolicyError, NonRetryableError, FanoutTimeoutError, FanoutSettlementError, FanoutEnqueueError, LogAppendError, LogLeaseError, LogTruncatedError, RoutingError, } from './errors.js';
8
- export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, } from './migrations.js';
8
+ export { durabilityNamedAlarmMigrations, durabilityOperationMigrations, durabilityFanoutMigrations, durabilityLogLeaseMigrations, durabilityLogMigrations, migrate, } from './migrations.js';
package/dist/lifecycle.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { traceLifecycle } from './dev.js';
1
2
  import { reportFailure } from './errors.js';
2
3
  /** Fans one helper's lifecycle events out to every attached hook. */
3
4
  export const createLifecycleHooks = (emitter, initial) => {
@@ -13,11 +14,11 @@ export const createLifecycleHooks = (emitter, initial) => {
13
14
  add(initial);
14
15
  }
15
16
  return {
16
- emit: (event) => {
17
+ emit: traceLifecycle((event) => {
17
18
  for (const emit of emits) {
18
19
  emit(event);
19
20
  }
20
- },
21
+ }),
21
22
  add,
22
23
  };
23
24
  };
package/dist/log.js CHANGED
@@ -9,11 +9,12 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
9
9
  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
10
10
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
11
  };
12
- var _DurabilityLog_instances, _DurabilityLog_engine, _DurabilityLog_routing, _DurabilityLog_retention, _DurabilityLog_cold, _DurabilityLog_leases, _DurabilityLog_maxParallelism, _DurabilityLog_leaseMs, _DurabilityLog_maxBatchSize, _DurabilityLog_encoder, _DurabilityLog_rehydrate, _DurabilityLog_record, _DurabilityLog_settle, _DurabilityLog_advance, _DurabilityLog_between, _DurabilityLog_readFrom, _DurabilityLog_requireLeases;
12
+ var _DurabilityLog_instances, _DurabilityLog_engine, _DurabilityLog_routing, _DurabilityLog_retention, _DurabilityLog_cold, _DurabilityLog_leases, _DurabilityLog_maxParallelism, _DurabilityLog_leaseMs, _DurabilityLog_maxBatchSize, _DurabilityLog_encoder, _DurabilityLog_rehydrate, _DurabilityLog_record, _DurabilityLog_settle, _DurabilityLog_dropTrimmed, _DurabilityLog_advance, _DurabilityLog_between, _DurabilityLog_readFrom, _DurabilityLog_requireLeases;
13
13
  import { z } from 'zod';
14
+ import { traceMethods } from './dev.js';
14
15
  import { LogAppendError, LogLeaseError, LogTruncatedError, reportFailure, serializeError, } from './errors.js';
15
16
  import { RoutingLoad } from './load.js';
16
- import { durabilityLogLeaseMigrations, durabilityLogMigrations, migrate, } from './migrations.js';
17
+ import { durabilityLogLeaseMigrations, durabilityLogMigrations, migrateCapability, } from './migrations.js';
17
18
  import { assertPositiveInteger } from './policy.js';
18
19
  import { engineFor, } from './scheduler.js';
19
20
  import { deserialize, serialize } from './serialization.js';
@@ -321,7 +322,7 @@ export class DurabilityLog {
321
322
  __classPrivateFieldGet(this, _DurabilityLog_engine, "f").migrateSchema('log', durabilityLogMigrations);
322
323
  }
323
324
  static migrate(context, target) {
324
- return migrate(context.storage, 'log', durabilityLogMigrations, target);
325
+ return migrateCapability(context.storage, 'log', durabilityLogMigrations, target);
325
326
  }
326
327
  /**
327
328
  * Appends the batch atomically. Definite input rejections return
@@ -518,6 +519,11 @@ export class DurabilityLog {
518
519
  const sql = __classPrivateFieldGet(this, _DurabilityLog_engine, "f").sql;
519
520
  const reclaimed = claimExpired(sql, consumer, now, crypto.randomUUID(), now + __classPrivateFieldGet(this, _DurabilityLog_leaseMs, "f"));
520
521
  if (reclaimed) {
522
+ const { oldestOffset } = readBounds(sql);
523
+ if (reclaimed.first_offset < oldestOffset) {
524
+ __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_dropTrimmed).call(this, consumer, reclaimed, oldestOffset);
525
+ throw new LogTruncatedError(reclaimed.first_offset, oldestOffset);
526
+ }
521
527
  const poisoned = leases.maxAttempts !== undefined &&
522
528
  leases.onPoison !== undefined &&
523
529
  reclaimed.attempt > leases.maxAttempts;
@@ -651,9 +657,24 @@ async function _DurabilityLog_rehydrate(from, limit, bounds) {
651
657
  // Either the batch never existed, was fenced by a redelivery, or was
652
658
  // already settled; all three are the caller holding a stale handle.
653
659
  throw new LogLeaseError(batchId);
660
+ }, _DurabilityLog_dropTrimmed = function _DurabilityLog_dropTrimmed(consumer, lease, oldestOffset) {
661
+ __classPrivateFieldGet(this, _DurabilityLog_engine, "f").transactionSync((sql) => {
662
+ if (lease.last_offset < oldestOffset) {
663
+ deleteLeases(sql, [lease.batch_id]);
664
+ }
665
+ else {
666
+ sql.exec(`UPDATE durability_log_leases
667
+ SET first_offset = ?, state = 'pending', attempt = attempt - 1,
668
+ expires_at = 0
669
+ WHERE batch_id = ?`, oldestOffset, lease.batch_id);
670
+ }
671
+ __classPrivateFieldGet(this, _DurabilityLog_instances, "m", _DurabilityLog_advance).call(this, consumer);
672
+ });
654
673
  }, _DurabilityLog_advance = function _DurabilityLog_advance(consumer) {
655
674
  const sql = __classPrivateFieldGet(this, _DurabilityLog_engine, "f").sql;
656
- const from = readCursor(sql, consumer) ?? 0;
675
+ // Offsets below the retained window are gone for everyone; a cursor
676
+ // stranded there could never meet the ranges leased after them.
677
+ const from = Math.max(readCursor(sql, consumer) ?? 0, readBounds(sql).oldestOffset);
657
678
  const candidates = leasesFrom(sql, consumer, from, __classPrivateFieldGet(this, _DurabilityLog_maxBatchSize, "f"));
658
679
  let cursor = from;
659
680
  const settled = [];
@@ -688,6 +709,7 @@ async function _DurabilityLog_between(first, last) {
688
709
  }
689
710
  return __classPrivateFieldGet(this, _DurabilityLog_leases, "f");
690
711
  };
712
+ traceMethods(DurabilityLog.prototype, 'DurabilityLog');
691
713
  const assertConsumer = (consumer) => {
692
714
  if (typeof consumer !== 'string' || consumer.length === 0) {
693
715
  throw new LogAppendError('Consumer must be a non-empty string');
@@ -82,6 +82,16 @@ export declare const durabilitySemaphoreQueueMigrations: {
82
82
  up: string;
83
83
  down: string;
84
84
  }[];
85
+ /**
86
+ * Ordered SQLite migrations for the experimental topology coordinator.
87
+ * Publication and sync ride on outbox channels. Applied automatically on
88
+ * construction.
89
+ */
90
+ export declare const durabilityTopologyMigrations: {
91
+ name: string;
92
+ up: string;
93
+ down: string;
94
+ }[];
85
95
  /** Migration names changed by one migrate call. */
86
96
  export type DurabilityMigrationResult = {
87
97
  /** Migrations applied in ascending order. */
@@ -89,7 +99,7 @@ export type DurabilityMigrationResult = {
89
99
  /** Migrations reverted in descending order. */
90
100
  rolledBack: string[];
91
101
  };
92
- export type MigrationCapability = 'operations' | 'namedAlarms' | 'fanout' | 'socket' | 'log' | 'logLeases' | 'outbox' | 'semaphore' | 'semaphoreQueue';
102
+ export type MigrationCapability = 'operations' | 'namedAlarms' | 'fanout' | 'socket' | 'log' | 'logLeases' | 'outbox' | 'semaphore' | 'semaphoreQueue' | 'topology';
93
103
  type MigrationStorage = Pick<DurableObjectStorage, 'sql' | 'transactionSync'>;
94
104
  /**
95
105
  * Moves one capability's schema to a target migration, applying or reverting as
@@ -100,5 +110,40 @@ type MigrationStorage = Pick<DurableObjectStorage, 'sql' | 'transactionSync'>;
100
110
  * downgrade of the library can still revert it. Batches of migrations apply or
101
111
  * revert atomically.
102
112
  */
103
- export declare const migrate: (storage: MigrationStorage, capability: MigrationCapability, migrations: DurableMigrations, target: string | null | undefined) => DurabilityMigrationResult;
113
+ export declare const migrateCapability: (storage: MigrationStorage, capability: MigrationCapability, migrations: DurableMigrations, target: string | null | undefined) => DurabilityMigrationResult;
114
+ /** Options for {@link migrate}. */
115
+ export type MigrateOptions = {
116
+ /** History table for these migrations. Defaults to `schema_migrations`. */
117
+ table?: string;
118
+ /**
119
+ * Migration to move the schema to. Defaults to the last one; `null` reverts
120
+ * every migration.
121
+ */
122
+ target?: string | null;
123
+ };
124
+ /**
125
+ * Moves an application's own schema to a target migration, with the same
126
+ * guarantees durability gives its tables: each batch applies or reverts in one
127
+ * synchronous transaction, every history row stores its `down` script, and a
128
+ * Durable Object running older code reverts up to two migrations it does not
129
+ * know before refusing.
130
+ *
131
+ * The history lives in its own table, apart from `durability_migrations`, and
132
+ * is dropped once no migration remains applied.
133
+ *
134
+ * @example
135
+ * ```ts
136
+ * constructor(ctx: DurableObjectState, env: Env) {
137
+ * super(ctx, env);
138
+ * migrate(ctx.storage, [
139
+ * {
140
+ * name: '0001_create_jobs',
141
+ * up: 'CREATE TABLE jobs (id TEXT PRIMARY KEY);',
142
+ * down: 'DROP TABLE jobs;',
143
+ * },
144
+ * ]);
145
+ * }
146
+ * ```
147
+ */
148
+ export declare const migrate: (storage: MigrationStorage, migrations: DurableMigrations, options?: MigrateOptions) => DurabilityMigrationResult;
104
149
  export {};
@@ -1,4 +1,5 @@
1
1
  import { z } from 'zod';
2
+ import { traceStorage } from './dev.js';
2
3
  export const migrationTableName = 'durability_migrations';
3
4
  /**
4
5
  * Ordered SQLite migrations for the `durability_calls` table owned by
@@ -496,6 +497,57 @@ export const durabilitySemaphoreQueueMigrations = [
496
497
  ALTER TABLE durability_semaphore_queue_items DROP COLUMN lease_id;
497
498
  `,
498
499
  },
500
+ {
501
+ name: 'durability_0011_renew_semaphore_queue_leases',
502
+ up: `
503
+ ALTER TABLE durability_semaphore_queue_leases ADD COLUMN renew_at INTEGER NOT NULL DEFAULT 0;
504
+ ALTER TABLE durability_semaphore_queue_leases ADD COLUMN renew_ms INTEGER NOT NULL DEFAULT 30000;
505
+ ALTER TABLE durability_semaphore_queue_leases ADD COLUMN confirmed INTEGER NOT NULL DEFAULT 0;
506
+ `,
507
+ down: `
508
+ ALTER TABLE durability_semaphore_queue_leases DROP COLUMN confirmed;
509
+ ALTER TABLE durability_semaphore_queue_leases DROP COLUMN renew_ms;
510
+ ALTER TABLE durability_semaphore_queue_leases DROP COLUMN renew_at;
511
+ `,
512
+ },
513
+ ];
514
+ /**
515
+ * Ordered SQLite migrations for the experimental topology coordinator.
516
+ * Publication and sync ride on outbox channels. Applied automatically on
517
+ * construction.
518
+ */
519
+ export const durabilityTopologyMigrations = [
520
+ {
521
+ name: 'durability_0011_create_topology',
522
+ up: `
523
+ CREATE TABLE IF NOT EXISTS durability_topology_groups (
524
+ group_id TEXT PRIMARY KEY,
525
+ version INTEGER NOT NULL,
526
+ members TEXT NOT NULL,
527
+ deleted INTEGER NOT NULL CHECK (deleted IN (0, 1)),
528
+ updated_at INTEGER NOT NULL
529
+ );
530
+ CREATE TABLE IF NOT EXISTS durability_topology_states (
531
+ group_id TEXT NOT NULL,
532
+ channel TEXT NOT NULL,
533
+ value TEXT NOT NULL,
534
+ PRIMARY KEY (group_id, channel)
535
+ );
536
+ CREATE TABLE IF NOT EXISTS durability_topology_writes (
537
+ id TEXT PRIMARY KEY,
538
+ group_id TEXT NOT NULL,
539
+ land_by INTEGER NOT NULL
540
+ );
541
+ CREATE INDEX IF NOT EXISTS durability_topology_writes_group_idx
542
+ ON durability_topology_writes (group_id, land_by);
543
+ `,
544
+ down: `
545
+ DROP INDEX IF EXISTS durability_topology_writes_group_idx;
546
+ DROP TABLE IF EXISTS durability_topology_writes;
547
+ DROP TABLE IF EXISTS durability_topology_states;
548
+ DROP TABLE IF EXISTS durability_topology_groups;
549
+ `,
550
+ },
499
551
  ];
500
552
  /**
501
553
  * Newer library versions may leave migrations this one does not know about.
@@ -521,22 +573,22 @@ const legacyHalves = [
521
573
  'durability_0004_calls_generation_and_created_at',
522
574
  'durability_0004_alarms_generation_and_created_at',
523
575
  ];
524
- const ensureHistoryTable = (sql) => {
576
+ const ensureHistoryTable = (sql, table) => {
525
577
  // The base shape matches the table earlier versions created through workers-qb.
526
578
  sql.exec(`
527
- CREATE TABLE IF NOT EXISTS ${migrationTableName} (
579
+ CREATE TABLE IF NOT EXISTS ${table} (
528
580
  id INTEGER PRIMARY KEY AUTOINCREMENT,
529
581
  name TEXT UNIQUE,
530
582
  applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
531
583
  )
532
584
  `);
533
585
  const columns = new Set(sql
534
- .exec(`SELECT name FROM pragma_table_info('${migrationTableName}')`)
586
+ .exec(`SELECT name FROM pragma_table_info('${table}')`)
535
587
  .toArray()
536
588
  .map((row) => row['name']));
537
589
  for (const column of ['capability', 'down']) {
538
590
  if (!columns.has(column)) {
539
- sql.exec(`ALTER TABLE ${migrationTableName} ADD COLUMN ${column} TEXT`);
591
+ sql.exec(`ALTER TABLE ${table} ADD COLUMN ${column} TEXT`);
540
592
  }
541
593
  }
542
594
  };
@@ -551,54 +603,46 @@ const translateLegacyHistory = (sql) => {
551
603
  sql.exec(`INSERT OR IGNORE INTO ${migrationTableName} (name) VALUES (?)`, name);
552
604
  }
553
605
  };
554
- const readHistory = (sql, capability, migrations) => {
606
+ const readHistory = (sql, scope, migrations) => {
555
607
  // Rows written before capabilities were tracked are claimed by the list that names them.
556
608
  for (const { name } of migrations) {
557
- sql.exec(`UPDATE ${migrationTableName} SET capability = ?
558
- WHERE name = ? AND capability IS NULL`, capability, name);
609
+ sql.exec(`UPDATE ${scope.table} SET capability = ?
610
+ WHERE name = ? AND capability IS NULL`, scope.capability, name);
559
611
  }
560
612
  return historyRowSchema.array().parse(sql
561
- .exec(`SELECT id, name, capability, down FROM ${migrationTableName}
562
- WHERE capability = ? ORDER BY id`, capability)
613
+ .exec(`SELECT id, name, capability, down FROM ${scope.table}
614
+ WHERE capability = ? ORDER BY id`, scope.capability)
563
615
  .toArray());
564
616
  };
565
- const runDown = (sql, name, down) => {
617
+ const runDown = (sql, table, name, down) => {
566
618
  if (down === null) {
567
619
  throw new Error(`Migration "${name}" has no stored down script`);
568
620
  }
569
621
  sql.exec(down);
570
- sql.exec(`DELETE FROM ${migrationTableName} WHERE name = ?`, name);
622
+ sql.exec(`DELETE FROM ${table} WHERE name = ?`, name);
571
623
  };
572
624
  /**
573
- * Reverts migrations recorded by a newer library version, newest first, using
574
- * the down scripts it stored. Refuses when the schema is further ahead than
625
+ * Reverts migrations recorded by a newer version, newest first, using the down
626
+ * scripts it stored. Refuses when the schema is further ahead than
575
627
  * {@link maxFutureMigrations}.
576
628
  */
577
- const revertFutureMigrations = (storage, capability, history, known) => {
629
+ const revertFutureMigrations = (storage, scope, history, known) => {
578
630
  const future = history.filter(({ name }) => !known.has(name)).reverse();
579
631
  if (future.length === 0) {
580
632
  return [];
581
633
  }
582
634
  if (future.length > maxFutureMigrations) {
583
- throw new Error(`Durability ${capability} schema is ${future.length} migrations ahead of this version; refusing to revert more than ${maxFutureMigrations}`);
635
+ throw new Error(`${scope.label} schema is ${future.length} migrations ahead of this version; refusing to revert more than ${maxFutureMigrations}`);
584
636
  }
585
637
  storage.transactionSync(() => {
586
638
  for (const row of future) {
587
- runDown(storage.sql, row.name, row.down);
639
+ runDown(storage.sql, scope.table, row.name, row.down);
588
640
  }
589
641
  });
590
642
  return future.map(({ name }) => name);
591
643
  };
592
- /**
593
- * Moves one capability's schema to a target migration, applying or reverting as
594
- * needed. `null` reverts every migration in the list; the shared migration
595
- * table is dropped once no durability history remains.
596
- *
597
- * Each migration's `down` is stored alongside its history row so a later
598
- * downgrade of the library can still revert it. Batches of migrations apply or
599
- * revert atomically.
600
- */
601
- export const migrate = (storage, capability, migrations, target) => {
644
+ const migrateScope = (storage, scope, migrations, target) => {
645
+ storage = traceStorage(storage);
602
646
  const resolvedTarget = target === undefined
603
647
  ? (migrations[migrations.length - 1]?.name ?? null)
604
648
  : target;
@@ -606,13 +650,15 @@ export const migrate = (storage, capability, migrations, target) => {
606
650
  ? -1
607
651
  : migrations.findIndex((migration) => migration.name === resolvedTarget);
608
652
  if (resolvedTarget !== null && targetIndex === -1) {
609
- throw new Error(`Unknown durability migration target "${resolvedTarget}"`);
653
+ throw new Error(`Unknown ${scope.label} migration target "${resolvedTarget}"`);
654
+ }
655
+ ensureHistoryTable(storage.sql, scope.table);
656
+ if (scope.table === migrationTableName) {
657
+ translateLegacyHistory(storage.sql);
610
658
  }
611
- ensureHistoryTable(storage.sql);
612
- translateLegacyHistory(storage.sql);
613
659
  const known = new Set(migrations.map(({ name }) => name));
614
- const history = readHistory(storage.sql, capability, migrations);
615
- const rolledBack = revertFutureMigrations(storage, capability, history, known);
660
+ const history = readHistory(storage.sql, scope, migrations);
661
+ const rolledBack = revertFutureMigrations(storage, scope, history, known);
616
662
  const applied = new Map(history
617
663
  .filter(({ name }) => known.has(name))
618
664
  .map((row) => [row.name, row]));
@@ -628,27 +674,77 @@ export const migrate = (storage, capability, migrations, target) => {
628
674
  .filter(({ name, down }) => applied.get(name)?.down !== down);
629
675
  storage.transactionSync(() => {
630
676
  for (const migration of toRevert) {
631
- runDown(storage.sql, migration.name, migration.down);
677
+ runDown(storage.sql, scope.table, migration.name, migration.down);
632
678
  }
633
679
  for (const migration of toApply) {
634
680
  storage.sql.exec(migration.up);
635
- storage.sql.exec(`INSERT INTO ${migrationTableName} (name, capability, down) VALUES (?, ?, ?)`, migration.name, capability, migration.down);
681
+ storage.sql.exec(`INSERT INTO ${scope.table} (name, capability, down) VALUES (?, ?, ?)`, migration.name, scope.capability, migration.down);
636
682
  }
637
683
  // Keep stored down scripts current so a downgrade runs the latest revert logic.
638
684
  for (const migration of toRefresh) {
639
- storage.sql.exec(`UPDATE ${migrationTableName} SET down = ? WHERE name = ?`, migration.down, migration.name);
685
+ storage.sql.exec(`UPDATE ${scope.table} SET down = ? WHERE name = ?`, migration.down, migration.name);
640
686
  }
641
687
  });
642
688
  const remaining = z
643
689
  .object({ count: z.number().int() })
644
690
  .parse(storage.sql
645
- .exec(`SELECT COUNT(*) AS count FROM ${migrationTableName}`)
691
+ .exec(`SELECT COUNT(*) AS count FROM ${scope.table}`)
646
692
  .toArray()[0]).count;
647
693
  if (remaining === 0) {
648
- storage.sql.exec(`DROP TABLE IF EXISTS ${migrationTableName}`);
694
+ storage.sql.exec(`DROP TABLE IF EXISTS ${scope.table}`);
649
695
  }
650
696
  return {
651
697
  applied: toApply.map(({ name }) => name),
652
698
  rolledBack: [...rolledBack, ...toRevert.map(({ name }) => name)],
653
699
  };
654
700
  };
701
+ /**
702
+ * Moves one capability's schema to a target migration, applying or reverting as
703
+ * needed. `null` reverts every migration in the list; the shared migration
704
+ * table is dropped once no durability history remains.
705
+ *
706
+ * Each migration's `down` is stored alongside its history row so a later
707
+ * downgrade of the library can still revert it. Batches of migrations apply or
708
+ * revert atomically.
709
+ */
710
+ export const migrateCapability = (storage, capability, migrations, target) => migrateScope(storage, {
711
+ table: migrationTableName,
712
+ capability,
713
+ label: `Durability ${capability}`,
714
+ }, migrations, target);
715
+ const sqlIdentifier = /^[A-Za-z_][A-Za-z0-9_]*$/;
716
+ /**
717
+ * Moves an application's own schema to a target migration, with the same
718
+ * guarantees durability gives its tables: each batch applies or reverts in one
719
+ * synchronous transaction, every history row stores its `down` script, and a
720
+ * Durable Object running older code reverts up to two migrations it does not
721
+ * know before refusing.
722
+ *
723
+ * The history lives in its own table, apart from `durability_migrations`, and
724
+ * is dropped once no migration remains applied.
725
+ *
726
+ * @example
727
+ * ```ts
728
+ * constructor(ctx: DurableObjectState, env: Env) {
729
+ * super(ctx, env);
730
+ * migrate(ctx.storage, [
731
+ * {
732
+ * name: '0001_create_jobs',
733
+ * up: 'CREATE TABLE jobs (id TEXT PRIMARY KEY);',
734
+ * down: 'DROP TABLE jobs;',
735
+ * },
736
+ * ]);
737
+ * }
738
+ * ```
739
+ */
740
+ export const migrate = (storage, migrations, options = {}) => {
741
+ const table = options.table ?? 'schema_migrations';
742
+ if (!sqlIdentifier.test(table) || table === migrationTableName) {
743
+ throw new Error(`Invalid schema migration table "${table}"`);
744
+ }
745
+ return migrateScope(storage, {
746
+ table,
747
+ capability: 'schema',
748
+ label: `"${table}"`,
749
+ }, migrations, options.target);
750
+ };
package/dist/outbox.d.ts CHANGED
@@ -52,6 +52,19 @@ export type DurabilityOutboxEvent = Extract<DurabilityLifecycleEvent, {
52
52
  * the class's static block.
53
53
  */
54
54
  export declare let stageWithin: <Value>(outbox: DurabilityOutbox<Value>, sql: SqlStorage, key: string, value: Value) => number;
55
+ /**
56
+ * Package-internal: drops a key's pending version inside a held transaction.
57
+ * An in-flight publication of it still completes, but its acknowledgement and
58
+ * retry both miss.
59
+ */
60
+ export declare let discardWithin: (outbox: DurabilityOutbox<never>, sql: SqlStorage, key: string) => void;
61
+ /**
62
+ * Package-internal: publishes a key's pending version now, even one waiting
63
+ * out a retry delay or batch window, serialized with the channel's other
64
+ * publish runs, and reports whether nothing is left pending for it. Takes no
65
+ * scheduler permit, so a caller holding the last one cannot deadlock.
66
+ */
67
+ export declare let publishNow: (outbox: DurabilityOutbox<never>, key: string) => Promise<boolean>;
55
68
  /**
56
69
  * A composable DO capability: keyed latest-state publication. Stage the
57
70
  * newest value for a key in the same transaction as the state it describes;