durability 4.2.0 → 5.0.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/README.md +340 -12
- package/dist/dev.d.ts +22 -0
- package/dist/dev.js +149 -0
- package/dist/durability-alarms.d.ts +16 -3
- package/dist/durability-alarms.js +21 -7
- package/dist/durability.d.ts +31 -6
- package/dist/durability.js +42 -16
- package/dist/errors.d.ts +31 -0
- package/dist/errors.js +45 -0
- package/dist/experimental.d.ts +5 -0
- package/dist/experimental.js +3 -0
- package/dist/fanout.d.ts +6 -0
- package/dist/fanout.js +20 -9
- package/dist/index.d.ts +4 -2
- package/dist/index.js +3 -2
- package/dist/lifecycle.d.ts +6 -1
- package/dist/lifecycle.js +3 -2
- package/dist/log.js +61 -16
- package/dist/memoize.d.ts +34 -0
- package/dist/memoize.js +136 -0
- package/dist/migrations.d.ts +64 -2
- package/dist/migrations.js +179 -34
- package/dist/outbox.d.ts +13 -0
- package/dist/outbox.js +78 -30
- package/dist/scheduler.d.ts +9 -0
- package/dist/scheduler.js +53 -11
- package/dist/semaphore-leases.js +15 -9
- package/dist/semaphore-queue-store.d.ts +12 -2
- package/dist/semaphore-queue-store.js +32 -5
- package/dist/semaphore-queue.js +109 -43
- package/dist/semaphore-server.js +7 -9
- package/dist/socket.js +19 -10
- package/dist/storage.d.ts +1 -0
- package/dist/storage.js +1 -1
- package/dist/topology-client.d.ts +40 -0
- package/dist/topology-client.js +180 -0
- package/dist/topology-snapshot.d.ts +70 -0
- package/dist/topology-snapshot.js +48 -0
- package/dist/topology.d.ts +94 -0
- package/dist/topology.js +468 -0
- package/dist/tracked-source.d.ts +2 -0
- package/dist/tracker.js +2 -0
- package/package.json +3 -2
package/dist/migrations.js
CHANGED
|
@@ -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
|
|
@@ -165,6 +166,27 @@ export const durabilityNamedAlarmMigrations = [
|
|
|
165
166
|
`,
|
|
166
167
|
},
|
|
167
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
|
+
];
|
|
168
190
|
/**
|
|
169
191
|
* Ordered SQLite migrations for fanout manifests and deliveries. Applied
|
|
170
192
|
* automatically on construction.
|
|
@@ -496,6 +518,57 @@ export const durabilitySemaphoreQueueMigrations = [
|
|
|
496
518
|
ALTER TABLE durability_semaphore_queue_items DROP COLUMN lease_id;
|
|
497
519
|
`,
|
|
498
520
|
},
|
|
521
|
+
{
|
|
522
|
+
name: 'durability_0011_renew_semaphore_queue_leases',
|
|
523
|
+
up: `
|
|
524
|
+
ALTER TABLE durability_semaphore_queue_leases ADD COLUMN renew_at INTEGER NOT NULL DEFAULT 0;
|
|
525
|
+
ALTER TABLE durability_semaphore_queue_leases ADD COLUMN renew_ms INTEGER NOT NULL DEFAULT 30000;
|
|
526
|
+
ALTER TABLE durability_semaphore_queue_leases ADD COLUMN confirmed INTEGER NOT NULL DEFAULT 0;
|
|
527
|
+
`,
|
|
528
|
+
down: `
|
|
529
|
+
ALTER TABLE durability_semaphore_queue_leases DROP COLUMN confirmed;
|
|
530
|
+
ALTER TABLE durability_semaphore_queue_leases DROP COLUMN renew_ms;
|
|
531
|
+
ALTER TABLE durability_semaphore_queue_leases DROP COLUMN renew_at;
|
|
532
|
+
`,
|
|
533
|
+
},
|
|
534
|
+
];
|
|
535
|
+
/**
|
|
536
|
+
* Ordered SQLite migrations for the experimental topology coordinator.
|
|
537
|
+
* Publication and sync ride on outbox channels. Applied automatically on
|
|
538
|
+
* construction.
|
|
539
|
+
*/
|
|
540
|
+
export const durabilityTopologyMigrations = [
|
|
541
|
+
{
|
|
542
|
+
name: 'durability_0011_create_topology',
|
|
543
|
+
up: `
|
|
544
|
+
CREATE TABLE IF NOT EXISTS durability_topology_groups (
|
|
545
|
+
group_id TEXT PRIMARY KEY,
|
|
546
|
+
version INTEGER NOT NULL,
|
|
547
|
+
members TEXT NOT NULL,
|
|
548
|
+
deleted INTEGER NOT NULL CHECK (deleted IN (0, 1)),
|
|
549
|
+
updated_at INTEGER NOT NULL
|
|
550
|
+
);
|
|
551
|
+
CREATE TABLE IF NOT EXISTS durability_topology_states (
|
|
552
|
+
group_id TEXT NOT NULL,
|
|
553
|
+
channel TEXT NOT NULL,
|
|
554
|
+
value TEXT NOT NULL,
|
|
555
|
+
PRIMARY KEY (group_id, channel)
|
|
556
|
+
);
|
|
557
|
+
CREATE TABLE IF NOT EXISTS durability_topology_writes (
|
|
558
|
+
id TEXT PRIMARY KEY,
|
|
559
|
+
group_id TEXT NOT NULL,
|
|
560
|
+
land_by INTEGER NOT NULL
|
|
561
|
+
);
|
|
562
|
+
CREATE INDEX IF NOT EXISTS durability_topology_writes_group_idx
|
|
563
|
+
ON durability_topology_writes (group_id, land_by);
|
|
564
|
+
`,
|
|
565
|
+
down: `
|
|
566
|
+
DROP INDEX IF EXISTS durability_topology_writes_group_idx;
|
|
567
|
+
DROP TABLE IF EXISTS durability_topology_writes;
|
|
568
|
+
DROP TABLE IF EXISTS durability_topology_states;
|
|
569
|
+
DROP TABLE IF EXISTS durability_topology_groups;
|
|
570
|
+
`,
|
|
571
|
+
},
|
|
499
572
|
];
|
|
500
573
|
/**
|
|
501
574
|
* Newer library versions may leave migrations this one does not know about.
|
|
@@ -521,22 +594,22 @@ const legacyHalves = [
|
|
|
521
594
|
'durability_0004_calls_generation_and_created_at',
|
|
522
595
|
'durability_0004_alarms_generation_and_created_at',
|
|
523
596
|
];
|
|
524
|
-
const ensureHistoryTable = (sql) => {
|
|
597
|
+
const ensureHistoryTable = (sql, table) => {
|
|
525
598
|
// The base shape matches the table earlier versions created through workers-qb.
|
|
526
599
|
sql.exec(`
|
|
527
|
-
CREATE TABLE IF NOT EXISTS ${
|
|
600
|
+
CREATE TABLE IF NOT EXISTS ${table} (
|
|
528
601
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
529
602
|
name TEXT UNIQUE,
|
|
530
603
|
applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
|
|
531
604
|
)
|
|
532
605
|
`);
|
|
533
606
|
const columns = new Set(sql
|
|
534
|
-
.exec(`SELECT name FROM pragma_table_info('${
|
|
607
|
+
.exec(`SELECT name FROM pragma_table_info('${table}')`)
|
|
535
608
|
.toArray()
|
|
536
609
|
.map((row) => row['name']));
|
|
537
610
|
for (const column of ['capability', 'down']) {
|
|
538
611
|
if (!columns.has(column)) {
|
|
539
|
-
sql.exec(`ALTER TABLE ${
|
|
612
|
+
sql.exec(`ALTER TABLE ${table} ADD COLUMN ${column} TEXT`);
|
|
540
613
|
}
|
|
541
614
|
}
|
|
542
615
|
};
|
|
@@ -551,54 +624,74 @@ const translateLegacyHistory = (sql) => {
|
|
|
551
624
|
sql.exec(`INSERT OR IGNORE INTO ${migrationTableName} (name) VALUES (?)`, name);
|
|
552
625
|
}
|
|
553
626
|
};
|
|
554
|
-
const readHistory = (sql,
|
|
627
|
+
const readHistory = (sql, scope, migrations) => {
|
|
555
628
|
// Rows written before capabilities were tracked are claimed by the list that names them.
|
|
556
629
|
for (const { name } of migrations) {
|
|
557
|
-
sql.exec(`UPDATE ${
|
|
558
|
-
WHERE name = ? AND capability IS NULL`, capability, name);
|
|
630
|
+
sql.exec(`UPDATE ${scope.table} SET capability = ?
|
|
631
|
+
WHERE name = ? AND capability IS NULL`, scope.capability, name);
|
|
559
632
|
}
|
|
560
633
|
return historyRowSchema.array().parse(sql
|
|
561
|
-
.exec(`SELECT id, name, capability, down FROM ${
|
|
562
|
-
WHERE capability = ? ORDER BY id`, capability)
|
|
634
|
+
.exec(`SELECT id, name, capability, down FROM ${scope.table}
|
|
635
|
+
WHERE capability = ? ORDER BY id`, scope.capability)
|
|
563
636
|
.toArray());
|
|
564
637
|
};
|
|
565
|
-
const runDown = (sql, name, down) => {
|
|
638
|
+
const runDown = (sql, table, name, down) => {
|
|
566
639
|
if (down === null) {
|
|
567
640
|
throw new Error(`Migration "${name}" has no stored down script`);
|
|
568
641
|
}
|
|
569
642
|
sql.exec(down);
|
|
570
|
-
sql.exec(`DELETE FROM ${
|
|
643
|
+
sql.exec(`DELETE FROM ${table} WHERE name = ?`, name);
|
|
571
644
|
};
|
|
572
645
|
/**
|
|
573
|
-
* Reverts migrations recorded by a newer
|
|
574
|
-
*
|
|
646
|
+
* Reverts migrations recorded by a newer version, newest first, using the down
|
|
647
|
+
* scripts it stored. Refuses when the schema is further ahead than
|
|
575
648
|
* {@link maxFutureMigrations}.
|
|
576
649
|
*/
|
|
577
|
-
const revertFutureMigrations = (storage,
|
|
650
|
+
const revertFutureMigrations = (storage, scope, history, known) => {
|
|
578
651
|
const future = history.filter(({ name }) => !known.has(name)).reverse();
|
|
579
652
|
if (future.length === 0) {
|
|
580
653
|
return [];
|
|
581
654
|
}
|
|
582
655
|
if (future.length > maxFutureMigrations) {
|
|
583
|
-
throw new Error(
|
|
656
|
+
throw new Error(`${scope.label} schema is ${future.length} migrations ahead of this version; refusing to revert more than ${maxFutureMigrations}`);
|
|
584
657
|
}
|
|
585
658
|
storage.transactionSync(() => {
|
|
586
659
|
for (const row of future) {
|
|
587
|
-
runDown(storage.sql, row.name, row.down);
|
|
660
|
+
runDown(storage.sql, scope.table, row.name, row.down);
|
|
588
661
|
}
|
|
589
662
|
});
|
|
590
663
|
return future.map(({ name }) => name);
|
|
591
664
|
};
|
|
665
|
+
const currentRowSchema = z.object({
|
|
666
|
+
name: z.string(),
|
|
667
|
+
down: z.string().nullable(),
|
|
668
|
+
});
|
|
592
669
|
/**
|
|
593
|
-
*
|
|
594
|
-
*
|
|
595
|
-
*
|
|
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.
|
|
670
|
+
* Whether a capability's history already lists exactly these migrations with
|
|
671
|
+
* these `down` scripts, so construction can skip {@link migrateCapability}. Every Durable
|
|
672
|
+
* Object wake constructs its helpers, and each statement there is one more way
|
|
673
|
+
* for the wake to fail, so the common case costs one read.
|
|
600
674
|
*/
|
|
601
|
-
export const
|
|
675
|
+
export const isSchemaCurrent = (sql, capability, migrations) => {
|
|
676
|
+
let rows;
|
|
677
|
+
try {
|
|
678
|
+
rows = currentRowSchema
|
|
679
|
+
.array()
|
|
680
|
+
.parse(sql
|
|
681
|
+
.exec(`SELECT name, down FROM ${migrationTableName} WHERE capability = ?`, capability)
|
|
682
|
+
.toArray());
|
|
683
|
+
}
|
|
684
|
+
catch {
|
|
685
|
+
// A first construction has no history table, and an older one lacks the
|
|
686
|
+
// capability column; migrateCapability() creates both, and retries any other failure.
|
|
687
|
+
return false;
|
|
688
|
+
}
|
|
689
|
+
const known = new Map(migrations.map(({ name, down }) => [name, down]));
|
|
690
|
+
return (rows.length === known.size &&
|
|
691
|
+
rows.every((row) => known.get(row.name) === row.down));
|
|
692
|
+
};
|
|
693
|
+
const migrateScope = (storage, scope, migrations, target) => {
|
|
694
|
+
storage = traceStorage(storage);
|
|
602
695
|
const resolvedTarget = target === undefined
|
|
603
696
|
? (migrations[migrations.length - 1]?.name ?? null)
|
|
604
697
|
: target;
|
|
@@ -606,13 +699,15 @@ export const migrate = (storage, capability, migrations, target) => {
|
|
|
606
699
|
? -1
|
|
607
700
|
: migrations.findIndex((migration) => migration.name === resolvedTarget);
|
|
608
701
|
if (resolvedTarget !== null && targetIndex === -1) {
|
|
609
|
-
throw new Error(`Unknown
|
|
702
|
+
throw new Error(`Unknown ${scope.label} migration target "${resolvedTarget}"`);
|
|
703
|
+
}
|
|
704
|
+
ensureHistoryTable(storage.sql, scope.table);
|
|
705
|
+
if (scope.table === migrationTableName) {
|
|
706
|
+
translateLegacyHistory(storage.sql);
|
|
610
707
|
}
|
|
611
|
-
ensureHistoryTable(storage.sql);
|
|
612
|
-
translateLegacyHistory(storage.sql);
|
|
613
708
|
const known = new Set(migrations.map(({ name }) => name));
|
|
614
|
-
const history = readHistory(storage.sql,
|
|
615
|
-
const rolledBack = revertFutureMigrations(storage,
|
|
709
|
+
const history = readHistory(storage.sql, scope, migrations);
|
|
710
|
+
const rolledBack = revertFutureMigrations(storage, scope, history, known);
|
|
616
711
|
const applied = new Map(history
|
|
617
712
|
.filter(({ name }) => known.has(name))
|
|
618
713
|
.map((row) => [row.name, row]));
|
|
@@ -628,27 +723,77 @@ export const migrate = (storage, capability, migrations, target) => {
|
|
|
628
723
|
.filter(({ name, down }) => applied.get(name)?.down !== down);
|
|
629
724
|
storage.transactionSync(() => {
|
|
630
725
|
for (const migration of toRevert) {
|
|
631
|
-
runDown(storage.sql, migration.name, migration.down);
|
|
726
|
+
runDown(storage.sql, scope.table, migration.name, migration.down);
|
|
632
727
|
}
|
|
633
728
|
for (const migration of toApply) {
|
|
634
729
|
storage.sql.exec(migration.up);
|
|
635
|
-
storage.sql.exec(`INSERT INTO ${
|
|
730
|
+
storage.sql.exec(`INSERT INTO ${scope.table} (name, capability, down) VALUES (?, ?, ?)`, migration.name, scope.capability, migration.down);
|
|
636
731
|
}
|
|
637
732
|
// Keep stored down scripts current so a downgrade runs the latest revert logic.
|
|
638
733
|
for (const migration of toRefresh) {
|
|
639
|
-
storage.sql.exec(`UPDATE ${
|
|
734
|
+
storage.sql.exec(`UPDATE ${scope.table} SET down = ? WHERE name = ?`, migration.down, migration.name);
|
|
640
735
|
}
|
|
641
736
|
});
|
|
642
737
|
const remaining = z
|
|
643
738
|
.object({ count: z.number().int() })
|
|
644
739
|
.parse(storage.sql
|
|
645
|
-
.exec(`SELECT COUNT(*) AS count FROM ${
|
|
740
|
+
.exec(`SELECT COUNT(*) AS count FROM ${scope.table}`)
|
|
646
741
|
.toArray()[0]).count;
|
|
647
742
|
if (remaining === 0) {
|
|
648
|
-
storage.sql.exec(`DROP TABLE IF EXISTS ${
|
|
743
|
+
storage.sql.exec(`DROP TABLE IF EXISTS ${scope.table}`);
|
|
649
744
|
}
|
|
650
745
|
return {
|
|
651
746
|
applied: toApply.map(({ name }) => name),
|
|
652
747
|
rolledBack: [...rolledBack, ...toRevert.map(({ name }) => name)],
|
|
653
748
|
};
|
|
654
749
|
};
|
|
750
|
+
/**
|
|
751
|
+
* Moves one capability's schema to a target migration, applying or reverting as
|
|
752
|
+
* needed. `null` reverts every migration in the list; the shared migration
|
|
753
|
+
* table is dropped once no durability history remains.
|
|
754
|
+
*
|
|
755
|
+
* Each migration's `down` is stored alongside its history row so a later
|
|
756
|
+
* downgrade of the library can still revert it. Batches of migrations apply or
|
|
757
|
+
* revert atomically.
|
|
758
|
+
*/
|
|
759
|
+
export const migrateCapability = (storage, capability, migrations, target) => migrateScope(storage, {
|
|
760
|
+
table: migrationTableName,
|
|
761
|
+
capability,
|
|
762
|
+
label: `Durability ${capability}`,
|
|
763
|
+
}, migrations, target);
|
|
764
|
+
const sqlIdentifier = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
765
|
+
/**
|
|
766
|
+
* Moves an application's own schema to a target migration, with the same
|
|
767
|
+
* guarantees durability gives its tables: each batch applies or reverts in one
|
|
768
|
+
* synchronous transaction, every history row stores its `down` script, and a
|
|
769
|
+
* Durable Object running older code reverts up to two migrations it does not
|
|
770
|
+
* know before refusing.
|
|
771
|
+
*
|
|
772
|
+
* The history lives in its own table, apart from `durability_migrations`, and
|
|
773
|
+
* is dropped once no migration remains applied.
|
|
774
|
+
*
|
|
775
|
+
* @example
|
|
776
|
+
* ```ts
|
|
777
|
+
* constructor(ctx: DurableObjectState, env: Env) {
|
|
778
|
+
* super(ctx, env);
|
|
779
|
+
* migrate(ctx.storage, [
|
|
780
|
+
* {
|
|
781
|
+
* name: '0001_create_jobs',
|
|
782
|
+
* up: 'CREATE TABLE jobs (id TEXT PRIMARY KEY);',
|
|
783
|
+
* down: 'DROP TABLE jobs;',
|
|
784
|
+
* },
|
|
785
|
+
* ]);
|
|
786
|
+
* }
|
|
787
|
+
* ```
|
|
788
|
+
*/
|
|
789
|
+
export const migrate = (storage, migrations, options = {}) => {
|
|
790
|
+
const table = options.table ?? 'schema_migrations';
|
|
791
|
+
if (!sqlIdentifier.test(table) || table === migrationTableName) {
|
|
792
|
+
throw new Error(`Invalid schema migration table "${table}"`);
|
|
793
|
+
}
|
|
794
|
+
return migrateScope(storage, {
|
|
795
|
+
table,
|
|
796
|
+
capability: 'schema',
|
|
797
|
+
label: `"${table}"`,
|
|
798
|
+
}, migrations, options.target);
|
|
799
|
+
};
|
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;
|
package/dist/outbox.js
CHANGED
|
@@ -9,9 +9,10 @@ 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 _DurabilityOutbox_instances, _DurabilityOutbox_engine, _DurabilityOutbox_channel, _DurabilityOutbox_publish, _DurabilityOutbox_maxBatchSize, _DurabilityOutbox_batchDelayMs, _DurabilityOutbox_attemptTimeoutMs, _DurabilityOutbox_delay, _DurabilityOutbox_emit, _DurabilityOutbox_running, _DurabilityOutbox_stageIn, _DurabilityOutbox_emitRegistered, _DurabilityOutbox_attach, _DurabilityOutbox_firstAttemptAt, _DurabilityOutbox_runDue, _DurabilityOutbox_runBatch, _DurabilityOutbox_publishBatch, _DurabilityOutbox_retryDelay, _DurabilityOutbox_deadline;
|
|
12
|
+
var _DurabilityOutbox_instances, _DurabilityOutbox_engine, _DurabilityOutbox_channel, _DurabilityOutbox_publish, _DurabilityOutbox_maxBatchSize, _DurabilityOutbox_batchDelayMs, _DurabilityOutbox_attemptTimeoutMs, _DurabilityOutbox_delay, _DurabilityOutbox_emit, _DurabilityOutbox_running, _DurabilityOutbox_stageIn, _DurabilityOutbox_emitRegistered, _DurabilityOutbox_attach, _DurabilityOutbox_firstAttemptAt, _DurabilityOutbox_runDue, _DurabilityOutbox_publishNow, _DurabilityOutbox_exclusive, _DurabilityOutbox_runBatch, _DurabilityOutbox_publishBatch, _DurabilityOutbox_retryDelay, _DurabilityOutbox_deadline;
|
|
13
|
+
import { traceLifecycle, traceMethods } from './dev.js';
|
|
13
14
|
import { OutboxTimeoutError, reportFailure, serializeError, } from './errors.js';
|
|
14
|
-
import { durabilityOutboxMigrations,
|
|
15
|
+
import { durabilityOutboxMigrations, migrateCapability, } from './migrations.js';
|
|
15
16
|
import { assertPositiveInteger, } from './policy.js';
|
|
16
17
|
import { engineFor, } from './scheduler.js';
|
|
17
18
|
import { deserialize, serialize } from './serialization.js';
|
|
@@ -35,11 +36,12 @@ const outboxRowSchema = z.object({
|
|
|
35
36
|
});
|
|
36
37
|
const versionRowSchema = z.object({ version: z.number().int().positive() });
|
|
37
38
|
const channelRowSchema = z.object({ channel: z.string() });
|
|
38
|
-
const listDueForChannel = (sql, channel, now, limit) => outboxRowSchema.array().parse(sql
|
|
39
|
+
const listDueForChannel = (sql, channel, now, limit, key) => outboxRowSchema.array().parse(sql
|
|
39
40
|
.exec(`SELECT * FROM durability_outbox
|
|
40
41
|
WHERE channel = ? AND status = 'pending' AND next_attempt_at <= ?
|
|
42
|
+
AND (? IS NULL OR entry_key = ?)
|
|
41
43
|
ORDER BY next_attempt_at ASC, version ASC
|
|
42
|
-
LIMIT ?`, channel, now, limit)
|
|
44
|
+
LIMIT ?`, channel, now, key ?? null, key ?? null, limit)
|
|
43
45
|
.toArray());
|
|
44
46
|
/** Allocates a version from a durable counter that survives row deletion. */
|
|
45
47
|
const nextVersion = (sql) => {
|
|
@@ -60,6 +62,19 @@ const nextVersion = (sql) => {
|
|
|
60
62
|
* the class's static block.
|
|
61
63
|
*/
|
|
62
64
|
export let stageWithin;
|
|
65
|
+
/**
|
|
66
|
+
* Package-internal: drops a key's pending version inside a held transaction.
|
|
67
|
+
* An in-flight publication of it still completes, but its acknowledgement and
|
|
68
|
+
* retry both miss.
|
|
69
|
+
*/
|
|
70
|
+
export let discardWithin;
|
|
71
|
+
/**
|
|
72
|
+
* Package-internal: publishes a key's pending version now, even one waiting
|
|
73
|
+
* out a retry delay or batch window, serialized with the channel's other
|
|
74
|
+
* publish runs, and reports whether nothing is left pending for it. Takes no
|
|
75
|
+
* scheduler permit, so a caller holding the last one cannot deadlock.
|
|
76
|
+
*/
|
|
77
|
+
export let publishNow;
|
|
63
78
|
const infrastructureRetryMs = 60000;
|
|
64
79
|
// setTimeout overflows past 2^31 - 1 ms, and it keeps every derived timestamp
|
|
65
80
|
// far inside the safe-integer range the storage indexes accept.
|
|
@@ -117,6 +132,7 @@ export class DurabilityOutbox {
|
|
|
117
132
|
_DurabilityOutbox_attemptTimeoutMs.set(this, void 0);
|
|
118
133
|
_DurabilityOutbox_delay.set(this, void 0);
|
|
119
134
|
_DurabilityOutbox_emit.set(this, void 0);
|
|
135
|
+
/** The channel's one publish run, never one still waiting for a permit. */
|
|
120
136
|
_DurabilityOutbox_running.set(this, void 0);
|
|
121
137
|
__classPrivateFieldSet(this, _DurabilityOutbox_channel, config.channel ?? 'default', "f");
|
|
122
138
|
if (typeof __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f") !== 'string' || __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f").length === 0) {
|
|
@@ -142,12 +158,12 @@ export class DurabilityOutbox {
|
|
|
142
158
|
__classPrivateFieldSet(this, _DurabilityOutbox_delay, config.retries?.delay ?? ((attempt) => jitter(exponential(attempt))), "f");
|
|
143
159
|
__classPrivateFieldSet(this, _DurabilityOutbox_publish, config.publish, "f");
|
|
144
160
|
__classPrivateFieldSet(this, _DurabilityOutbox_engine, engineFor(config), "f");
|
|
145
|
-
__classPrivateFieldSet(this, _DurabilityOutbox_emit, __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").emitter(config.onLifecycleEvent), "f");
|
|
161
|
+
__classPrivateFieldSet(this, _DurabilityOutbox_emit, traceLifecycle(__classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").emitter(config.onLifecycleEvent)), "f");
|
|
146
162
|
__classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").migrateSchema('outbox', durabilityOutboxMigrations);
|
|
147
163
|
__classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_attach).call(this);
|
|
148
164
|
}
|
|
149
165
|
static migrate(context, target) {
|
|
150
|
-
return
|
|
166
|
+
return migrateCapability(context.storage, 'outbox', durabilityOutboxMigrations, target);
|
|
151
167
|
}
|
|
152
168
|
alarm(info) {
|
|
153
169
|
return __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").alarm(info);
|
|
@@ -222,42 +238,69 @@ _DurabilityOutbox_engine = new WeakMap(), _DurabilityOutbox_channel = new WeakMa
|
|
|
222
238
|
return createdAt;
|
|
223
239
|
}
|
|
224
240
|
return Math.ceil(createdAt / __classPrivateFieldGet(this, _DurabilityOutbox_batchDelayMs, "f")) * __classPrivateFieldGet(this, _DurabilityOutbox_batchDelayMs, "f");
|
|
225
|
-
}, _DurabilityOutbox_runDue = function _DurabilityOutbox_runDue() {
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
}
|
|
229
|
-
return __classPrivateFieldGet(this, _DurabilityOutbox_running, "f");
|
|
230
|
-
}, _DurabilityOutbox_runBatch = async function _DurabilityOutbox_runBatch() {
|
|
241
|
+
}, _DurabilityOutbox_runDue = async function _DurabilityOutbox_runDue() {
|
|
242
|
+
if (__classPrivateFieldGet(this, _DurabilityOutbox_running, "f")) {
|
|
243
|
+
return __classPrivateFieldGet(this, _DurabilityOutbox_running, "f");
|
|
244
|
+
}
|
|
231
245
|
// Every transaction reconciles the alarm; one per idle run keeps re-arming
|
|
232
246
|
// it while anything else on the scheduler is due, such as a running operation.
|
|
233
247
|
if (listDueForChannel(__classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").sql, __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"), Date.now(), 1)
|
|
234
248
|
.length === 0) {
|
|
235
|
-
return;
|
|
249
|
+
return undefined;
|
|
236
250
|
}
|
|
251
|
+
// The permit is taken before claiming the channel, so nothing that holds
|
|
252
|
+
// the channel ever waits for a permit.
|
|
237
253
|
const release = await __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").acquirePermit();
|
|
238
254
|
try {
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
const deadline = Date.now() + __classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f");
|
|
242
|
-
const claimed = [];
|
|
243
|
-
for (const row of due) {
|
|
244
|
-
const attempt = claimAttempt(sql, outboxTable, row.id, row.generation_id, Number.MAX_SAFE_INTEGER);
|
|
245
|
-
if (attempt === undefined) {
|
|
246
|
-
continue;
|
|
247
|
-
}
|
|
248
|
-
// A crash mid-publication leaves the claim due again at the deadline.
|
|
249
|
-
updateAttempt(sql, outboxTable, { key: row.id, generation: row.generation_id, attempt }, 'next_attempt_at = ?', deadline);
|
|
250
|
-
claimed.push({ ...row, attempt });
|
|
251
|
-
}
|
|
252
|
-
return claimed;
|
|
253
|
-
});
|
|
254
|
-
if (claims.length > 0) {
|
|
255
|
-
await __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_publishBatch).call(this, claims);
|
|
255
|
+
if (__classPrivateFieldGet(this, _DurabilityOutbox_running, "f")) {
|
|
256
|
+
return await __classPrivateFieldGet(this, _DurabilityOutbox_running, "f");
|
|
256
257
|
}
|
|
258
|
+
return await __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_exclusive).call(this, () => __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_runBatch).call(this));
|
|
257
259
|
}
|
|
258
260
|
finally {
|
|
259
261
|
release();
|
|
260
262
|
}
|
|
263
|
+
}, _DurabilityOutbox_publishNow = async function _DurabilityOutbox_publishNow(key) {
|
|
264
|
+
const pending = () => __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").sql
|
|
265
|
+
.exec('SELECT 1 FROM durability_outbox WHERE id = ?', rowId(__classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"), key))
|
|
266
|
+
.toArray().length > 0;
|
|
267
|
+
while (__classPrivateFieldGet(this, _DurabilityOutbox_running, "f")) {
|
|
268
|
+
// eslint-disable-next-line no-await-in-loop
|
|
269
|
+
await __classPrivateFieldGet(this, _DurabilityOutbox_running, "f").catch(() => undefined);
|
|
270
|
+
}
|
|
271
|
+
if (!pending()) {
|
|
272
|
+
return true;
|
|
273
|
+
}
|
|
274
|
+
await __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_exclusive).call(this, () => __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_runBatch).call(this, key));
|
|
275
|
+
return !pending();
|
|
276
|
+
}, _DurabilityOutbox_exclusive = function _DurabilityOutbox_exclusive(run) {
|
|
277
|
+
const running = run().finally(() => {
|
|
278
|
+
if (__classPrivateFieldGet(this, _DurabilityOutbox_running, "f") === running) {
|
|
279
|
+
__classPrivateFieldSet(this, _DurabilityOutbox_running, undefined, "f");
|
|
280
|
+
}
|
|
281
|
+
});
|
|
282
|
+
__classPrivateFieldSet(this, _DurabilityOutbox_running, running, "f");
|
|
283
|
+
return running;
|
|
284
|
+
}, _DurabilityOutbox_runBatch = async function _DurabilityOutbox_runBatch(key) {
|
|
285
|
+
const claims = await __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").transaction((sql) => {
|
|
286
|
+
// No run is in flight here, so a key's future attempt time is only a delay to skip.
|
|
287
|
+
const due = listDueForChannel(sql, __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f"), key === undefined ? Date.now() : Number.MAX_SAFE_INTEGER, __classPrivateFieldGet(this, _DurabilityOutbox_maxBatchSize, "f"), key);
|
|
288
|
+
const deadline = Date.now() + __classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f");
|
|
289
|
+
const claimed = [];
|
|
290
|
+
for (const row of due) {
|
|
291
|
+
const attempt = claimAttempt(sql, outboxTable, row.id, row.generation_id, Number.MAX_SAFE_INTEGER);
|
|
292
|
+
if (attempt === undefined) {
|
|
293
|
+
continue;
|
|
294
|
+
}
|
|
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
|
+
claimed.push({ ...row, attempt });
|
|
298
|
+
}
|
|
299
|
+
return claimed;
|
|
300
|
+
});
|
|
301
|
+
if (claims.length > 0) {
|
|
302
|
+
await __classPrivateFieldGet(this, _DurabilityOutbox_instances, "m", _DurabilityOutbox_publishBatch).call(this, claims);
|
|
303
|
+
}
|
|
261
304
|
}, _DurabilityOutbox_publishBatch = async function _DurabilityOutbox_publishBatch(claims) {
|
|
262
305
|
const startedAt = Date.now();
|
|
263
306
|
const retries = new Map();
|
|
@@ -382,4 +425,9 @@ _DurabilityOutbox_engine = new WeakMap(), _DurabilityOutbox_channel = new WeakMa
|
|
|
382
425
|
__classPrivateFieldGet(outbox, _DurabilityOutbox_instances, "m", _DurabilityOutbox_emitRegistered).call(outbox, row);
|
|
383
426
|
return row.version;
|
|
384
427
|
};
|
|
428
|
+
discardWithin = (outbox, sql, key) => {
|
|
429
|
+
sql.exec('DELETE FROM durability_outbox WHERE id = ?', rowId(__classPrivateFieldGet(outbox, _DurabilityOutbox_channel, "f"), key));
|
|
430
|
+
};
|
|
431
|
+
publishNow = (outbox, key) => __classPrivateFieldGet(outbox, _DurabilityOutbox_instances, "m", _DurabilityOutbox_publishNow).call(outbox, key);
|
|
385
432
|
})();
|
|
433
|
+
traceMethods(DurabilityOutbox.prototype, 'DurabilityOutbox');
|
package/dist/scheduler.d.ts
CHANGED
|
@@ -60,6 +60,8 @@ export type ExecutionSpec = {
|
|
|
60
60
|
active: Map<string, ActiveExecution>;
|
|
61
61
|
policy: AttemptPolicy;
|
|
62
62
|
emit: Emit;
|
|
63
|
+
/** When true, the completed event carries the handler result; omitted by default to keep results out of telemetry. */
|
|
64
|
+
includeResult?: boolean;
|
|
63
65
|
exhaustedError: () => Error;
|
|
64
66
|
timeoutError: () => Error;
|
|
65
67
|
invoke: (attempt: number, signal: AbortSignal) => unknown;
|
|
@@ -79,10 +81,12 @@ export type ExecutionSpec = {
|
|
|
79
81
|
export declare class Engine {
|
|
80
82
|
readonly sql: SqlStorage;
|
|
81
83
|
private readonly context;
|
|
84
|
+
private readonly storage;
|
|
82
85
|
private readonly alarmConcurrency;
|
|
83
86
|
private readonly alarmMinDelayMs;
|
|
84
87
|
private readonly alarmHandoffMs;
|
|
85
88
|
private readonly participants;
|
|
89
|
+
private readonly migrated;
|
|
86
90
|
private availablePermits;
|
|
87
91
|
private readonly permitWaiters;
|
|
88
92
|
private alarmRefresh;
|
|
@@ -91,6 +95,11 @@ export declare class Engine {
|
|
|
91
95
|
constructor(context: DurabilityContext, options: DurabilitySchedulerOptions);
|
|
92
96
|
register(participant: Participant): void;
|
|
93
97
|
waitUntil(promise: Promise<unknown>, onError: (error: unknown) => void): void;
|
|
98
|
+
/**
|
|
99
|
+
* The owning Durable Object's ID. The public context type omits it, but the
|
|
100
|
+
* `DurableObjectState` applications pass at runtime carries it.
|
|
101
|
+
*/
|
|
102
|
+
objectId(): string | undefined;
|
|
94
103
|
emitter<Event extends {
|
|
95
104
|
entityKind: string;
|
|
96
105
|
type: string;
|