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/README.md +203 -2
- 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/errors.d.ts +17 -0
- package/dist/errors.js +22 -0
- package/dist/experimental.d.ts +5 -0
- package/dist/experimental.js +3 -0
- package/dist/fanout.js +14 -9
- package/dist/index.d.ts +2 -1
- package/dist/index.js +1 -1
- package/dist/lifecycle.js +3 -2
- package/dist/log.js +26 -4
- package/dist/migrations.d.ts +47 -2
- package/dist/migrations.js +132 -36
- package/dist/outbox.d.ts +13 -0
- package/dist/outbox.js +78 -30
- package/dist/scheduler.d.ts +7 -0
- package/dist/scheduler.js +26 -7
- 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/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 +2 -2
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,
|
|
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
|
|
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
|
-
|
|
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,
|
|
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
|
|
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
|
-
|
|
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');
|
package/dist/migrations.d.ts
CHANGED
|
@@ -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
|
|
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 {};
|
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
|
|
@@ -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 ${
|
|
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('${
|
|
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 ${
|
|
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,
|
|
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 ${
|
|
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 ${
|
|
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 ${
|
|
622
|
+
sql.exec(`DELETE FROM ${table} WHERE name = ?`, name);
|
|
571
623
|
};
|
|
572
624
|
/**
|
|
573
|
-
* Reverts migrations recorded by a newer
|
|
574
|
-
*
|
|
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,
|
|
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(
|
|
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
|
-
|
|
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
|
|
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,
|
|
615
|
-
const rolledBack = revertFutureMigrations(storage,
|
|
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 ${
|
|
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 ${
|
|
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 ${
|
|
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 ${
|
|
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;
|