durability 4.1.2 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +406 -1
  2. package/dist/dev.d.ts +22 -0
  3. package/dist/dev.js +149 -0
  4. package/dist/durability-alarms.d.ts +1 -1
  5. package/dist/durability-alarms.js +6 -4
  6. package/dist/durability.d.ts +1 -1
  7. package/dist/durability.js +8 -5
  8. package/dist/durable-object-target.d.ts +12 -0
  9. package/dist/durable-object-target.js +17 -0
  10. package/dist/errors.d.ts +25 -0
  11. package/dist/errors.js +36 -0
  12. package/dist/experimental.d.ts +8 -0
  13. package/dist/experimental.js +6 -0
  14. package/dist/fanout.js +14 -9
  15. package/dist/index.d.ts +2 -1
  16. package/dist/index.js +1 -1
  17. package/dist/lifecycle.d.ts +14 -3
  18. package/dist/lifecycle.js +3 -2
  19. package/dist/log.js +26 -4
  20. package/dist/migrations.d.ts +74 -2
  21. package/dist/migrations.js +307 -36
  22. package/dist/outbox.d.ts +85 -0
  23. package/dist/outbox.js +433 -0
  24. package/dist/routing.d.ts +2 -9
  25. package/dist/routing.js +2 -14
  26. package/dist/scheduler.d.ts +14 -2
  27. package/dist/scheduler.js +38 -13
  28. package/dist/semaphore-client.d.ts +22 -0
  29. package/dist/semaphore-client.js +61 -0
  30. package/dist/semaphore-leases.d.ts +109 -0
  31. package/dist/semaphore-leases.js +272 -0
  32. package/dist/semaphore-protocol.d.ts +231 -0
  33. package/dist/semaphore-protocol.js +106 -0
  34. package/dist/semaphore-queue-store.d.ts +95 -0
  35. package/dist/semaphore-queue-store.js +248 -0
  36. package/dist/semaphore-queue.d.ts +119 -0
  37. package/dist/semaphore-queue.js +863 -0
  38. package/dist/semaphore-server.d.ts +89 -0
  39. package/dist/semaphore-server.js +518 -0
  40. package/dist/semaphore-store.d.ts +43 -0
  41. package/dist/semaphore-store.js +108 -0
  42. package/dist/semaphore.d.ts +42 -0
  43. package/dist/semaphore.js +57 -0
  44. package/dist/socket.js +19 -10
  45. package/dist/topology-client.d.ts +40 -0
  46. package/dist/topology-client.js +180 -0
  47. package/dist/topology-snapshot.d.ts +70 -0
  48. package/dist/topology-snapshot.js +48 -0
  49. package/dist/topology.d.ts +94 -0
  50. package/dist/topology.js +468 -0
  51. package/dist/tracker.js +2 -0
  52. package/package.json +6 -2
@@ -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
@@ -322,6 +323,232 @@ export const durabilityLogLeaseMigrations = [
322
323
  `,
323
324
  },
324
325
  ];
326
+ /**
327
+ * Ordered SQLite migrations for outbox channels. Applied automatically on
328
+ * construction.
329
+ */
330
+ export const durabilityOutboxMigrations = [
331
+ {
332
+ name: 'durability_0006_create_outbox',
333
+ up: `
334
+ CREATE TABLE IF NOT EXISTS durability_outbox (
335
+ id TEXT PRIMARY KEY,
336
+ channel TEXT NOT NULL,
337
+ entry_key TEXT NOT NULL,
338
+ version INTEGER NOT NULL,
339
+ payload TEXT NOT NULL,
340
+ status TEXT NOT NULL CHECK (status IN ('pending')),
341
+ attempt INTEGER NOT NULL DEFAULT 0,
342
+ next_attempt_at INTEGER NOT NULL,
343
+ last_error TEXT,
344
+ last_error_name TEXT,
345
+ created_at INTEGER NOT NULL,
346
+ generation_id TEXT NOT NULL
347
+ );
348
+ CREATE INDEX IF NOT EXISTS durability_outbox_due_idx
349
+ ON durability_outbox (channel, status, next_attempt_at, version);
350
+ CREATE INDEX IF NOT EXISTS durability_outbox_pending_idx
351
+ ON durability_outbox (status, next_attempt_at);
352
+ CREATE INDEX IF NOT EXISTS durability_outbox_created_idx
353
+ ON durability_outbox (created_at);
354
+ CREATE TABLE IF NOT EXISTS durability_outbox_seq (
355
+ id INTEGER PRIMARY KEY CHECK (id = 1),
356
+ next_version INTEGER NOT NULL
357
+ );
358
+ INSERT OR IGNORE INTO durability_outbox_seq (id, next_version) VALUES (1, 1);
359
+ `,
360
+ down: `
361
+ DROP INDEX IF EXISTS durability_outbox_due_idx;
362
+ DROP INDEX IF EXISTS durability_outbox_pending_idx;
363
+ DROP INDEX IF EXISTS durability_outbox_created_idx;
364
+ DROP TABLE IF EXISTS durability_outbox;
365
+ DROP TABLE IF EXISTS durability_outbox_seq;
366
+ `,
367
+ },
368
+ ];
369
+ /**
370
+ * Ordered SQLite migrations for semaphore grants. Applied automatically on
371
+ * construction.
372
+ */
373
+ export const durabilitySemaphoreMigrations = [
374
+ {
375
+ name: 'durability_0007_create_semaphore',
376
+ up: `
377
+ CREATE TABLE IF NOT EXISTS durability_semaphore_grants (
378
+ grant_id TEXT PRIMARY KEY,
379
+ client_id TEXT NOT NULL,
380
+ grp TEXT NOT NULL,
381
+ permits INTEGER NOT NULL,
382
+ claimed INTEGER NOT NULL DEFAULT 0,
383
+ released INTEGER NOT NULL DEFAULT 0,
384
+ created_at INTEGER NOT NULL,
385
+ expires_at INTEGER NOT NULL
386
+ );
387
+ CREATE INDEX IF NOT EXISTS durability_semaphore_grants_expires_idx
388
+ ON durability_semaphore_grants (expires_at) WHERE claimed < permits;
389
+ `,
390
+ down: `
391
+ DROP INDEX IF EXISTS durability_semaphore_grants_expires_idx;
392
+ DROP TABLE IF EXISTS durability_semaphore_grants;
393
+ `,
394
+ },
395
+ {
396
+ name: 'durability_0009_create_semaphore_leases',
397
+ up: `
398
+ CREATE TABLE IF NOT EXISTS durability_semaphore_leases (
399
+ lease_id TEXT PRIMARY KEY,
400
+ client_id TEXT NOT NULL,
401
+ grp TEXT NOT NULL,
402
+ permits INTEGER NOT NULL,
403
+ released INTEGER NOT NULL DEFAULT 0,
404
+ created_at INTEGER NOT NULL,
405
+ expires_at INTEGER NOT NULL,
406
+ retired INTEGER NOT NULL DEFAULT 0
407
+ );
408
+ CREATE INDEX IF NOT EXISTS durability_semaphore_leases_expires_idx
409
+ ON durability_semaphore_leases (expires_at);
410
+ `,
411
+ down: `
412
+ DROP INDEX IF EXISTS durability_semaphore_leases_expires_idx;
413
+ DROP TABLE IF EXISTS durability_semaphore_leases;
414
+ `,
415
+ },
416
+ ];
417
+ /**
418
+ * Ordered SQLite migrations for a semaphore client's queue. Applied
419
+ * automatically on construction.
420
+ */
421
+ export const durabilitySemaphoreQueueMigrations = [
422
+ {
423
+ name: 'durability_0008_create_semaphore_queue',
424
+ up: `
425
+ CREATE TABLE IF NOT EXISTS durability_semaphore_queue_items (
426
+ id TEXT PRIMARY KEY,
427
+ key TEXT NOT NULL,
428
+ grp TEXT NOT NULL,
429
+ payload TEXT NOT NULL,
430
+ status TEXT NOT NULL CHECK (status IN ('queued', 'claiming', 'admitted')),
431
+ grant_id TEXT,
432
+ created_at INTEGER NOT NULL,
433
+ admitted_at INTEGER,
434
+ notified INTEGER NOT NULL DEFAULT 0,
435
+ attempt INTEGER NOT NULL DEFAULT 0,
436
+ next_attempt_at INTEGER NOT NULL
437
+ );
438
+ CREATE INDEX IF NOT EXISTS durability_semaphore_queue_items_key_idx
439
+ ON durability_semaphore_queue_items (key, status, created_at, id);
440
+ CREATE INDEX IF NOT EXISTS durability_semaphore_queue_items_grant_idx
441
+ ON durability_semaphore_queue_items (grant_id, created_at, id);
442
+ CREATE INDEX IF NOT EXISTS durability_semaphore_queue_items_notify_idx
443
+ ON durability_semaphore_queue_items (next_attempt_at)
444
+ WHERE status = 'admitted' AND notified = 0;
445
+ CREATE TABLE IF NOT EXISTS durability_semaphore_queue_grants (
446
+ grant_id TEXT PRIMARY KEY,
447
+ key TEXT NOT NULL,
448
+ grp TEXT NOT NULL,
449
+ permits INTEGER NOT NULL,
450
+ claimed INTEGER NOT NULL DEFAULT 0,
451
+ confirmed INTEGER NOT NULL DEFAULT 0,
452
+ admitted INTEGER NOT NULL DEFAULT 0,
453
+ released INTEGER NOT NULL DEFAULT 0,
454
+ created_at INTEGER NOT NULL
455
+ );
456
+ CREATE INDEX IF NOT EXISTS durability_semaphore_queue_grants_key_idx
457
+ ON durability_semaphore_queue_grants (key, created_at);
458
+ CREATE TABLE IF NOT EXISTS durability_semaphore_queue_keys (
459
+ key TEXT PRIMARY KEY,
460
+ next_request_at INTEGER NOT NULL,
461
+ queued INTEGER NOT NULL
462
+ );
463
+ CREATE INDEX IF NOT EXISTS durability_semaphore_queue_keys_due_idx
464
+ ON durability_semaphore_queue_keys (next_request_at) WHERE queued > 0;
465
+ `,
466
+ down: `
467
+ DROP INDEX IF EXISTS durability_semaphore_queue_keys_due_idx;
468
+ DROP TABLE IF EXISTS durability_semaphore_queue_keys;
469
+ DROP INDEX IF EXISTS durability_semaphore_queue_grants_key_idx;
470
+ DROP TABLE IF EXISTS durability_semaphore_queue_grants;
471
+ DROP INDEX IF EXISTS durability_semaphore_queue_items_notify_idx;
472
+ DROP INDEX IF EXISTS durability_semaphore_queue_items_grant_idx;
473
+ DROP INDEX IF EXISTS durability_semaphore_queue_items_key_idx;
474
+ DROP TABLE IF EXISTS durability_semaphore_queue_items;
475
+ `,
476
+ },
477
+ {
478
+ name: 'durability_0010_add_semaphore_queue_leases',
479
+ up: `
480
+ ALTER TABLE durability_semaphore_queue_items ADD COLUMN lease_id TEXT;
481
+ CREATE TABLE IF NOT EXISTS durability_semaphore_queue_leases (
482
+ lease_id TEXT PRIMARY KEY,
483
+ key TEXT NOT NULL,
484
+ grp TEXT NOT NULL,
485
+ permits INTEGER NOT NULL,
486
+ drawn INTEGER NOT NULL DEFAULT 0,
487
+ released INTEGER NOT NULL DEFAULT 0,
488
+ created_at INTEGER NOT NULL,
489
+ expires_at INTEGER NOT NULL
490
+ );
491
+ CREATE INDEX IF NOT EXISTS durability_semaphore_queue_leases_key_idx
492
+ ON durability_semaphore_queue_leases (key, created_at);
493
+ `,
494
+ down: `
495
+ DROP INDEX IF EXISTS durability_semaphore_queue_leases_key_idx;
496
+ DROP TABLE IF EXISTS durability_semaphore_queue_leases;
497
+ ALTER TABLE durability_semaphore_queue_items DROP COLUMN lease_id;
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
+ },
551
+ ];
325
552
  /**
326
553
  * Newer library versions may leave migrations this one does not know about.
327
554
  * On downgrade their stored `down` scripts are run, but only this many, so an
@@ -346,22 +573,22 @@ const legacyHalves = [
346
573
  'durability_0004_calls_generation_and_created_at',
347
574
  'durability_0004_alarms_generation_and_created_at',
348
575
  ];
349
- const ensureHistoryTable = (sql) => {
576
+ const ensureHistoryTable = (sql, table) => {
350
577
  // The base shape matches the table earlier versions created through workers-qb.
351
578
  sql.exec(`
352
- CREATE TABLE IF NOT EXISTS ${migrationTableName} (
579
+ CREATE TABLE IF NOT EXISTS ${table} (
353
580
  id INTEGER PRIMARY KEY AUTOINCREMENT,
354
581
  name TEXT UNIQUE,
355
582
  applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
356
583
  )
357
584
  `);
358
585
  const columns = new Set(sql
359
- .exec(`SELECT name FROM pragma_table_info('${migrationTableName}')`)
586
+ .exec(`SELECT name FROM pragma_table_info('${table}')`)
360
587
  .toArray()
361
588
  .map((row) => row['name']));
362
589
  for (const column of ['capability', 'down']) {
363
590
  if (!columns.has(column)) {
364
- sql.exec(`ALTER TABLE ${migrationTableName} ADD COLUMN ${column} TEXT`);
591
+ sql.exec(`ALTER TABLE ${table} ADD COLUMN ${column} TEXT`);
365
592
  }
366
593
  }
367
594
  };
@@ -376,54 +603,46 @@ const translateLegacyHistory = (sql) => {
376
603
  sql.exec(`INSERT OR IGNORE INTO ${migrationTableName} (name) VALUES (?)`, name);
377
604
  }
378
605
  };
379
- const readHistory = (sql, capability, migrations) => {
606
+ const readHistory = (sql, scope, migrations) => {
380
607
  // Rows written before capabilities were tracked are claimed by the list that names them.
381
608
  for (const { name } of migrations) {
382
- sql.exec(`UPDATE ${migrationTableName} SET capability = ?
383
- 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);
384
611
  }
385
612
  return historyRowSchema.array().parse(sql
386
- .exec(`SELECT id, name, capability, down FROM ${migrationTableName}
387
- WHERE capability = ? ORDER BY id`, capability)
613
+ .exec(`SELECT id, name, capability, down FROM ${scope.table}
614
+ WHERE capability = ? ORDER BY id`, scope.capability)
388
615
  .toArray());
389
616
  };
390
- const runDown = (sql, name, down) => {
617
+ const runDown = (sql, table, name, down) => {
391
618
  if (down === null) {
392
619
  throw new Error(`Migration "${name}" has no stored down script`);
393
620
  }
394
621
  sql.exec(down);
395
- sql.exec(`DELETE FROM ${migrationTableName} WHERE name = ?`, name);
622
+ sql.exec(`DELETE FROM ${table} WHERE name = ?`, name);
396
623
  };
397
624
  /**
398
- * Reverts migrations recorded by a newer library version, newest first, using
399
- * 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
400
627
  * {@link maxFutureMigrations}.
401
628
  */
402
- const revertFutureMigrations = (storage, capability, history, known) => {
629
+ const revertFutureMigrations = (storage, scope, history, known) => {
403
630
  const future = history.filter(({ name }) => !known.has(name)).reverse();
404
631
  if (future.length === 0) {
405
632
  return [];
406
633
  }
407
634
  if (future.length > maxFutureMigrations) {
408
- 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}`);
409
636
  }
410
637
  storage.transactionSync(() => {
411
638
  for (const row of future) {
412
- runDown(storage.sql, row.name, row.down);
639
+ runDown(storage.sql, scope.table, row.name, row.down);
413
640
  }
414
641
  });
415
642
  return future.map(({ name }) => name);
416
643
  };
417
- /**
418
- * Moves one capability's schema to a target migration, applying or reverting as
419
- * needed. `null` reverts every migration in the list; the shared migration
420
- * table is dropped once no durability history remains.
421
- *
422
- * Each migration's `down` is stored alongside its history row so a later
423
- * downgrade of the library can still revert it. Batches of migrations apply or
424
- * revert atomically.
425
- */
426
- export const migrate = (storage, capability, migrations, target) => {
644
+ const migrateScope = (storage, scope, migrations, target) => {
645
+ storage = traceStorage(storage);
427
646
  const resolvedTarget = target === undefined
428
647
  ? (migrations[migrations.length - 1]?.name ?? null)
429
648
  : target;
@@ -431,13 +650,15 @@ export const migrate = (storage, capability, migrations, target) => {
431
650
  ? -1
432
651
  : migrations.findIndex((migration) => migration.name === resolvedTarget);
433
652
  if (resolvedTarget !== null && targetIndex === -1) {
434
- 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);
435
658
  }
436
- ensureHistoryTable(storage.sql);
437
- translateLegacyHistory(storage.sql);
438
659
  const known = new Set(migrations.map(({ name }) => name));
439
- const history = readHistory(storage.sql, capability, migrations);
440
- const rolledBack = revertFutureMigrations(storage, capability, history, known);
660
+ const history = readHistory(storage.sql, scope, migrations);
661
+ const rolledBack = revertFutureMigrations(storage, scope, history, known);
441
662
  const applied = new Map(history
442
663
  .filter(({ name }) => known.has(name))
443
664
  .map((row) => [row.name, row]));
@@ -453,27 +674,77 @@ export const migrate = (storage, capability, migrations, target) => {
453
674
  .filter(({ name, down }) => applied.get(name)?.down !== down);
454
675
  storage.transactionSync(() => {
455
676
  for (const migration of toRevert) {
456
- runDown(storage.sql, migration.name, migration.down);
677
+ runDown(storage.sql, scope.table, migration.name, migration.down);
457
678
  }
458
679
  for (const migration of toApply) {
459
680
  storage.sql.exec(migration.up);
460
- 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);
461
682
  }
462
683
  // Keep stored down scripts current so a downgrade runs the latest revert logic.
463
684
  for (const migration of toRefresh) {
464
- 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);
465
686
  }
466
687
  });
467
688
  const remaining = z
468
689
  .object({ count: z.number().int() })
469
690
  .parse(storage.sql
470
- .exec(`SELECT COUNT(*) AS count FROM ${migrationTableName}`)
691
+ .exec(`SELECT COUNT(*) AS count FROM ${scope.table}`)
471
692
  .toArray()[0]).count;
472
693
  if (remaining === 0) {
473
- storage.sql.exec(`DROP TABLE IF EXISTS ${migrationTableName}`);
694
+ storage.sql.exec(`DROP TABLE IF EXISTS ${scope.table}`);
474
695
  }
475
696
  return {
476
697
  applied: toApply.map(({ name }) => name),
477
698
  rolledBack: [...rolledBack, ...toRevert.map(({ name }) => name)],
478
699
  };
479
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
+ };
@@ -0,0 +1,85 @@
1
+ import type { DurabilityLifecycleEvent, LifecycleHook } from './lifecycle.js';
2
+ import { type DurabilityMigrationResult } from './migrations.js';
3
+ import { type DurabilityRetryOptions } from './policy.js';
4
+ import { type SchedulerAttachment } from './scheduler.js';
5
+ /** The newest staged version of one key, handed to `publish`. */
6
+ export type OutboxEntry<Value> = {
7
+ key: string;
8
+ /** Monotonic across the whole Durable Object; newer stages are larger. */
9
+ version: number;
10
+ value: Value;
11
+ /** One-based publication attempt for this version. */
12
+ attempt: number;
13
+ stagedAt: number;
14
+ /**
15
+ * Keeps this entry pending instead of acknowledging it when `publish`
16
+ * returns. Only callable while `publish` is running.
17
+ */
18
+ retry(delayMs?: number): void;
19
+ };
20
+ export type DurabilityOutboxConfig<Value> = SchedulerAttachment & {
21
+ /**
22
+ * Stable channel ID. Outboxes on one scheduler share storage, partitioned by
23
+ * channel, and each owns its own `publish`. Defaults to `default`.
24
+ */
25
+ channel?: string;
26
+ /**
27
+ * Publishes a batch of the newest pending versions. Returning acknowledges
28
+ * every entry not marked with `retry()`; throwing retries the whole batch.
29
+ * Sinks must be idempotent on `(key, version)` and keep the highest version.
30
+ */
31
+ publish(entries: OutboxEntry<Value>[]): unknown | Promise<unknown>;
32
+ /** Defaults to 50. */
33
+ maxBatchSize?: number;
34
+ /**
35
+ * Rounds first publication up to the next multiple of this delay so stages
36
+ * within one window share a batch. Defaults to 0.
37
+ */
38
+ batchDelayMs?: number;
39
+ /** Maximum duration of one `publish` call. Defaults to 60 seconds. */
40
+ attemptTimeoutMs?: number;
41
+ /** Publication is retried until acknowledged; only the delay is configurable. */
42
+ retries?: Pick<DurabilityRetryOptions, 'delay'>;
43
+ onLifecycleEvent?: LifecycleHook;
44
+ };
45
+ /** A lifecycle event for one of this outbox's entries. */
46
+ export type DurabilityOutboxEvent = Extract<DurabilityLifecycleEvent, {
47
+ entityKind: 'outbox_entry';
48
+ }>;
49
+ /**
50
+ * Package-internal: stages inside a transaction another helper already holds,
51
+ * so its reports commit atomically with that helper's own rows. Assigned by
52
+ * the class's static block.
53
+ */
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>;
68
+ /**
69
+ * A composable DO capability: keyed latest-state publication. Stage the
70
+ * newest value for a key in the same transaction as the state it describes;
71
+ * the outbox republishes the newest version until `publish` acknowledges it.
72
+ * Superseded versions are coalesced and may never be published.
73
+ */
74
+ export declare class DurabilityOutbox<Value = unknown> {
75
+ #private;
76
+ constructor(config: DurabilityOutboxConfig<Value>);
77
+ static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
78
+ alarm(info?: AlarmInvocationInfo): Promise<void>;
79
+ /**
80
+ * Durably stages the newest value for `key` and returns its version. On a
81
+ * SQLite-backed object, staging inside `ctx.storage.transaction()` commits
82
+ * atomically with the application's own writes in that transaction.
83
+ */
84
+ stage(key: string, value: Value): Promise<number>;
85
+ }