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.
- package/README.md +406 -1
- package/dist/dev.d.ts +22 -0
- package/dist/dev.js +149 -0
- package/dist/durability-alarms.d.ts +1 -1
- package/dist/durability-alarms.js +6 -4
- package/dist/durability.d.ts +1 -1
- package/dist/durability.js +8 -5
- package/dist/durable-object-target.d.ts +12 -0
- package/dist/durable-object-target.js +17 -0
- package/dist/errors.d.ts +25 -0
- package/dist/errors.js +36 -0
- package/dist/experimental.d.ts +8 -0
- package/dist/experimental.js +6 -0
- package/dist/fanout.js +14 -9
- package/dist/index.d.ts +2 -1
- package/dist/index.js +1 -1
- package/dist/lifecycle.d.ts +14 -3
- package/dist/lifecycle.js +3 -2
- package/dist/log.js +26 -4
- package/dist/migrations.d.ts +74 -2
- package/dist/migrations.js +307 -36
- package/dist/outbox.d.ts +85 -0
- package/dist/outbox.js +433 -0
- package/dist/routing.d.ts +2 -9
- package/dist/routing.js +2 -14
- package/dist/scheduler.d.ts +14 -2
- package/dist/scheduler.js +38 -13
- package/dist/semaphore-client.d.ts +22 -0
- package/dist/semaphore-client.js +61 -0
- package/dist/semaphore-leases.d.ts +109 -0
- package/dist/semaphore-leases.js +272 -0
- package/dist/semaphore-protocol.d.ts +231 -0
- package/dist/semaphore-protocol.js +106 -0
- package/dist/semaphore-queue-store.d.ts +95 -0
- package/dist/semaphore-queue-store.js +248 -0
- package/dist/semaphore-queue.d.ts +119 -0
- package/dist/semaphore-queue.js +863 -0
- package/dist/semaphore-server.d.ts +89 -0
- package/dist/semaphore-server.js +518 -0
- package/dist/semaphore-store.d.ts +43 -0
- package/dist/semaphore-store.js +108 -0
- package/dist/semaphore.d.ts +42 -0
- package/dist/semaphore.js +57 -0
- package/dist/socket.js +19 -10
- 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/tracker.js +2 -0
- package/package.json +6 -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
|
|
@@ -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 ${
|
|
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('${
|
|
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 ${
|
|
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,
|
|
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 ${
|
|
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 ${
|
|
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 ${
|
|
622
|
+
sql.exec(`DELETE FROM ${table} WHERE name = ?`, name);
|
|
396
623
|
};
|
|
397
624
|
/**
|
|
398
|
-
* Reverts migrations recorded by a newer
|
|
399
|
-
*
|
|
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,
|
|
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(
|
|
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
|
-
|
|
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
|
|
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,
|
|
440
|
-
const rolledBack = revertFutureMigrations(storage,
|
|
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 ${
|
|
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 ${
|
|
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 ${
|
|
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 ${
|
|
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
|
+
};
|
package/dist/outbox.d.ts
ADDED
|
@@ -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
|
+
}
|