durability 5.2.1 → 5.4.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 +42 -18
- package/dist/alarms/index.d.ts +1 -1
- package/dist/alarms/index.js +6 -3
- package/dist/dev.d.ts +7 -3
- package/dist/dev.js +17 -11
- package/dist/durable-object-target.js +8 -4
- package/dist/errors.d.ts +13 -7
- package/dist/errors.js +34 -32
- package/dist/fanout/index.d.ts +1 -1
- package/dist/fanout/index.js +15 -26
- package/dist/lifecycle.d.ts +1 -0
- package/dist/lifecycle.js +2 -2
- package/dist/log/index.js +5 -2
- package/dist/memoize/index.js +6 -1
- package/dist/migrations.js +37 -37
- package/dist/operations/index.js +8 -4
- package/dist/outbox/index.d.ts +1 -1
- package/dist/outbox/index.js +7 -17
- package/dist/policy.d.ts +1 -1
- package/dist/policy.js +2 -1
- package/dist/predicates.d.ts +9 -0
- package/dist/predicates.js +10 -0
- package/dist/routing/client.js +3 -4
- package/dist/routing/index.d.ts +1 -1
- package/dist/routing/index.js +14 -10
- package/dist/schedule/index.d.ts +15 -3
- package/dist/schedule/index.js +55 -36
- package/dist/scheduler/index.d.ts +35 -14
- package/dist/scheduler/index.js +78 -74
- package/dist/semaphore/client.js +2 -1
- package/dist/semaphore/index.d.ts +1 -1
- package/dist/semaphore/index.js +10 -5
- package/dist/semaphore/leases.d.ts +3 -2
- package/dist/semaphore/leases.js +3 -2
- package/dist/semaphore/queue-store.js +2 -1
- package/dist/semaphore/queue.d.ts +1 -1
- package/dist/semaphore/queue.js +36 -37
- package/dist/semaphore/server.js +50 -32
- package/dist/serialization.d.ts +3 -2
- package/dist/serialization.js +16 -13
- package/dist/shared-timer.d.ts +27 -0
- package/dist/shared-timer.js +191 -0
- package/dist/socket/client.d.ts +21 -7
- package/dist/socket/client.js +37 -27
- package/dist/socket/index.d.ts +20 -13
- package/dist/socket/index.js +40 -18
- package/dist/socket/protocol.d.ts +37 -17
- package/dist/socket/protocol.js +30 -36
- package/dist/topology/client.js +36 -19
- package/dist/topology/index.d.ts +3 -3
- package/dist/topology/index.js +40 -49
- package/dist/topology/snapshot.d.ts +6 -5
- package/dist/topology/snapshot.js +5 -2
- package/dist/tracker/index.js +18 -7
- package/dist/tracker/source.d.ts +6 -2
- package/package.json +2 -2
package/dist/scheduler/index.js
CHANGED
|
@@ -4,7 +4,9 @@ import { DurableRetryPolicyError, isErrorInstance, isNonRetryable, reportFailure
|
|
|
4
4
|
import { createEmitter, } from '../lifecycle.js';
|
|
5
5
|
import { isSchemaCurrent, migrateCapability, } from '../migrations.js';
|
|
6
6
|
import { assertPositiveInteger } from '../policy.js';
|
|
7
|
+
import { isFunction, isNonEmptyString } from '../predicates.js';
|
|
7
8
|
import { deleteMemos, deleteStaleMemos } from '../memoize/index.js';
|
|
9
|
+
import { SharedTimer } from '../shared-timer.js';
|
|
8
10
|
import { channelBindings, channelClause, claimAttempt, exhaustAttempts, tableOwner, updateAttempt, } from '../storage.js';
|
|
9
11
|
const minAlarmDelayMs = 1000;
|
|
10
12
|
const failedRunRetryMs = 1000;
|
|
@@ -17,9 +19,6 @@ const schedulerOptionKeys = [
|
|
|
17
19
|
'onAlarmRetry',
|
|
18
20
|
];
|
|
19
21
|
const maxAlarmDelayMs = 15000;
|
|
20
|
-
// setTimeout treats delays past this as zero, so anything further out can only
|
|
21
|
-
// be served by the physical alarm fallback.
|
|
22
|
-
const maxTimerMs = 2 ** 31 - 1;
|
|
23
22
|
const pendingHeadRowSchema = v.object({
|
|
24
23
|
pk: v.string(),
|
|
25
24
|
channel: v.optional(v.string()),
|
|
@@ -36,18 +35,18 @@ const channelRowSchema = v.object({ channel: v.string() });
|
|
|
36
35
|
const activeKey = (channel, key) => JSON.stringify([channel ?? null, key]);
|
|
37
36
|
/** Rejects a channel name a helper would otherwise store rows under. */
|
|
38
37
|
export const assertChannel = (helper, channel) => {
|
|
39
|
-
if (
|
|
38
|
+
if (!isNonEmptyString(channel)) {
|
|
40
39
|
throw new TypeError(`${helper} channel must be a non-empty string`);
|
|
41
40
|
}
|
|
42
41
|
return channel;
|
|
43
42
|
};
|
|
44
|
-
const decideRetry = (spec, attempt,
|
|
45
|
-
const terminal = isNonRetryable(
|
|
43
|
+
const decideRetry = (spec, attempt, cause) => {
|
|
44
|
+
const terminal = isNonRetryable(cause) ||
|
|
46
45
|
attempt >= spec.policy.maxAttempts ||
|
|
47
|
-
spec.isTerminal(
|
|
46
|
+
spec.isTerminal(cause);
|
|
48
47
|
if (terminal) {
|
|
49
48
|
const timestamp = Date.now();
|
|
50
|
-
return { error, terminal, timestamp, nextAttemptAt: timestamp };
|
|
49
|
+
return { error: cause, terminal, timestamp, nextAttemptAt: timestamp };
|
|
51
50
|
}
|
|
52
51
|
try {
|
|
53
52
|
const rawDelay = spec.policy.delay(attempt);
|
|
@@ -61,7 +60,7 @@ const decideRetry = (spec, attempt, error) => {
|
|
|
61
60
|
throw new DurableRetryPolicyError(spec.label);
|
|
62
61
|
}
|
|
63
62
|
return {
|
|
64
|
-
error,
|
|
63
|
+
error: cause,
|
|
65
64
|
terminal: false,
|
|
66
65
|
timestamp,
|
|
67
66
|
nextAttemptAt: timestamp + delay,
|
|
@@ -85,6 +84,8 @@ const decideRetry = (spec, attempt, error) => {
|
|
|
85
84
|
*/
|
|
86
85
|
export class Engine {
|
|
87
86
|
constructor(context, options) {
|
|
87
|
+
/** Holds the timeouts of every helper on the object behind one native timer. */
|
|
88
|
+
this.timer = new SharedTimer();
|
|
88
89
|
this.alarmConcurrency = defaultAlarmConcurrency;
|
|
89
90
|
this.alarmMinDelayMs = 15000;
|
|
90
91
|
this.alarmHandoffMs = 14 * 60000;
|
|
@@ -137,8 +138,7 @@ export class Engine {
|
|
|
137
138
|
const alarmConcurrency = merged.alarmConcurrency ?? defaultAlarmConcurrency;
|
|
138
139
|
const alarmMinDelayMs = merged.alarmMinDelayMs ?? 15000;
|
|
139
140
|
const alarmHandoffMs = merged.alarmHandoffMs ?? 14 * 60000;
|
|
140
|
-
if (merged.onAlarmRetry !== undefined &&
|
|
141
|
-
typeof merged.onAlarmRetry !== 'function') {
|
|
141
|
+
if (merged.onAlarmRetry !== undefined && !isFunction(merged.onAlarmRetry)) {
|
|
142
142
|
throw new TypeError('onAlarmRetry must be a function');
|
|
143
143
|
}
|
|
144
144
|
assertPositiveInteger('alarmConcurrency', alarmConcurrency);
|
|
@@ -206,7 +206,7 @@ export class Engine {
|
|
|
206
206
|
if (participant.nextPendingAt !== undefined) {
|
|
207
207
|
// Missing custom channels are dormant. Defer until construction finishes,
|
|
208
208
|
// then restore their alarm without requiring a new application write.
|
|
209
|
-
const onError = (
|
|
209
|
+
const onError = (cause) => reportFailure('durability.channel_resume_failed', { table: table.name, channel }, cause);
|
|
210
210
|
const resumed = Promise.resolve()
|
|
211
211
|
.then(() => {
|
|
212
212
|
if (participant.nextPendingAt?.(this.sql) !== undefined) {
|
|
@@ -214,11 +214,11 @@ export class Engine {
|
|
|
214
214
|
}
|
|
215
215
|
return undefined;
|
|
216
216
|
})
|
|
217
|
-
.catch(async (
|
|
217
|
+
.catch(async (cause) => {
|
|
218
218
|
if (await this.armFallbackAlarm()) {
|
|
219
219
|
this.retryFailedRun();
|
|
220
220
|
}
|
|
221
|
-
onError(
|
|
221
|
+
onError(cause);
|
|
222
222
|
});
|
|
223
223
|
this.waitUntil(resumed, onError);
|
|
224
224
|
}
|
|
@@ -284,7 +284,7 @@ export class Engine {
|
|
|
284
284
|
* `DurableObjectState` applications pass at runtime carries it.
|
|
285
285
|
*/
|
|
286
286
|
objectId() {
|
|
287
|
-
const id =
|
|
287
|
+
const id = 'id' in this.context ? this.context.id : undefined;
|
|
288
288
|
return id === undefined || id === null ? undefined : String(id);
|
|
289
289
|
}
|
|
290
290
|
emitter(hook) {
|
|
@@ -428,7 +428,7 @@ export class Engine {
|
|
|
428
428
|
return;
|
|
429
429
|
}
|
|
430
430
|
if (this.earlyAlarm) {
|
|
431
|
-
|
|
431
|
+
this.earlyAlarm.cancel();
|
|
432
432
|
this.earlyAlarm = undefined;
|
|
433
433
|
}
|
|
434
434
|
if (timestamp === undefined) {
|
|
@@ -437,25 +437,21 @@ export class Engine {
|
|
|
437
437
|
const delay = timestamp - Date.now();
|
|
438
438
|
// Without liveTimers the in-memory timer only covers the sub-min-delay
|
|
439
439
|
// window; the physical alarm handles everything beyond it. With liveTimers
|
|
440
|
-
// it fires at the exact due time no matter how far out
|
|
441
|
-
// timer's range where only the physical fallback can serve it.
|
|
440
|
+
// it fires at the exact due time no matter how far out.
|
|
442
441
|
if (!this.liveTimers && delay >= this.alarmMinDelayMs) {
|
|
443
442
|
return;
|
|
444
443
|
}
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
}
|
|
448
|
-
const timer = setTimeout(() => {
|
|
449
|
-
if (this.earlyAlarm?.timer !== timer) {
|
|
444
|
+
const cancel = this.timer.schedule(() => {
|
|
445
|
+
if (this.earlyAlarm?.cancel !== cancel) {
|
|
450
446
|
return;
|
|
451
447
|
}
|
|
452
448
|
this.earlyAlarm = undefined;
|
|
453
449
|
trace('scheduler.early_alarm', { scheduledTime: timestamp });
|
|
454
|
-
const onError = (
|
|
450
|
+
const onError = (cause) => reportFailure('durability.background_execution.failed', { scheduledTime: timestamp }, cause);
|
|
455
451
|
const execution = this.alarm().catch(onError);
|
|
456
452
|
this.waitUntil(execution, onError);
|
|
457
|
-
},
|
|
458
|
-
this.earlyAlarm = { timestamp,
|
|
453
|
+
}, delay);
|
|
454
|
+
this.earlyAlarm = { timestamp, cancel };
|
|
459
455
|
}
|
|
460
456
|
/** Coalesces refreshes without dropping requests arriving after the pending-work read. */
|
|
461
457
|
scheduleNextAlarm() {
|
|
@@ -594,7 +590,7 @@ export class Engine {
|
|
|
594
590
|
throw error;
|
|
595
591
|
}
|
|
596
592
|
reportFailure('durability.alarm.failed', { retryInMs: this.alarmMinDelayMs }, error);
|
|
597
|
-
this.notifyAlarmRetry(error, info);
|
|
593
|
+
this.notifyAlarmRetry(serializeError(error), info);
|
|
598
594
|
this.retryFailedRun();
|
|
599
595
|
}
|
|
600
596
|
}
|
|
@@ -609,24 +605,24 @@ export class Engine {
|
|
|
609
605
|
const delay = Math.min(failedRunRetryMs * 2 ** (this.failedRuns - 1), this.alarmMinDelayMs);
|
|
610
606
|
this.scheduleEarlyAlarm(Date.now() + delay);
|
|
611
607
|
}
|
|
612
|
-
notifyAlarmRetry(
|
|
608
|
+
notifyAlarmRetry(error, invocation) {
|
|
613
609
|
const hook = this.onAlarmRetry;
|
|
614
610
|
if (!hook) {
|
|
615
611
|
return;
|
|
616
612
|
}
|
|
617
613
|
const objectId = this.objectId();
|
|
618
614
|
const info = {
|
|
619
|
-
error
|
|
615
|
+
error,
|
|
620
616
|
retryInMs: this.alarmMinDelayMs,
|
|
621
|
-
...(invocation === undefined
|
|
622
|
-
? {}
|
|
623
|
-
: {
|
|
624
|
-
retryCount: invocation.retryCount,
|
|
625
|
-
isRetry: invocation.isRetry,
|
|
626
|
-
}),
|
|
627
|
-
...(objectId === undefined ? {} : { objectId }),
|
|
628
617
|
};
|
|
629
|
-
|
|
618
|
+
if (invocation !== undefined) {
|
|
619
|
+
info.retryCount = invocation.retryCount;
|
|
620
|
+
info.isRetry = invocation.isRetry;
|
|
621
|
+
}
|
|
622
|
+
if (objectId !== undefined) {
|
|
623
|
+
info.objectId = objectId;
|
|
624
|
+
}
|
|
625
|
+
const report = (cause) => reportFailure('durability.alarm.retry_hook_failed', { retryInMs: info.retryInMs }, cause);
|
|
630
626
|
try {
|
|
631
627
|
const result = hook(info);
|
|
632
628
|
if (result !== undefined) {
|
|
@@ -647,20 +643,18 @@ export class Engine {
|
|
|
647
643
|
void execution.catch(() => undefined);
|
|
648
644
|
const handoff = Symbol('alarm handoff');
|
|
649
645
|
const remaining = this.alarmHandoffMs - (Date.now() - startedAt);
|
|
650
|
-
let
|
|
646
|
+
let cancelTimeout;
|
|
651
647
|
let result;
|
|
652
648
|
try {
|
|
653
649
|
result = await Promise.race([
|
|
654
650
|
execution,
|
|
655
651
|
new Promise((resolve) => {
|
|
656
|
-
|
|
652
|
+
cancelTimeout = this.timer.schedule(() => resolve(handoff), remaining);
|
|
657
653
|
}),
|
|
658
654
|
]);
|
|
659
655
|
}
|
|
660
656
|
finally {
|
|
661
|
-
|
|
662
|
-
clearTimeout(timeout);
|
|
663
|
-
}
|
|
657
|
+
cancelTimeout?.();
|
|
664
658
|
}
|
|
665
659
|
if (result === handoff) {
|
|
666
660
|
await this.armForHandoff(Date.now());
|
|
@@ -690,7 +684,10 @@ export class Engine {
|
|
|
690
684
|
/**
|
|
691
685
|
* Registers the execution in its active map synchronously, then claims and
|
|
692
686
|
* runs one attempt in the background. The returned promise settles when the
|
|
693
|
-
* attempt's outcome has been persisted
|
|
687
|
+
* attempt's outcome has been persisted. The key leaves the active map and
|
|
688
|
+
* its permit is released then too, whether or not a timed-out handler has
|
|
689
|
+
* settled: nothing can stop a handler, and one that never settles would
|
|
690
|
+
* otherwise keep its retry from ever starting.
|
|
694
691
|
*/
|
|
695
692
|
startExecution(spec, eagerPermit) {
|
|
696
693
|
const { key, row, policy } = spec;
|
|
@@ -706,15 +703,6 @@ export class Engine {
|
|
|
706
703
|
spec.active.set(key, activeExecution);
|
|
707
704
|
this.trackActive(spec.table.name, activeKey(spec.table.channel, key));
|
|
708
705
|
let releasePermit = eagerPermit;
|
|
709
|
-
let handlerStarted = false;
|
|
710
|
-
let handlerSettled = false;
|
|
711
|
-
let policySettled = false;
|
|
712
|
-
const releaseIfSettled = () => {
|
|
713
|
-
if (policySettled && (!handlerStarted || handlerSettled)) {
|
|
714
|
-
releasePermit?.();
|
|
715
|
-
settleActive();
|
|
716
|
-
}
|
|
717
|
-
};
|
|
718
706
|
const execution = (async () => {
|
|
719
707
|
releasePermit ?? (releasePermit = await this.acquirePermit());
|
|
720
708
|
const attempt = claimAttempt(this.sql, spec.table, key, row.generation_id, policy.maxAttempts);
|
|
@@ -731,18 +719,13 @@ export class Engine {
|
|
|
731
719
|
});
|
|
732
720
|
const controller = new AbortController();
|
|
733
721
|
activeExecution.controller = controller;
|
|
734
|
-
let
|
|
722
|
+
let cancelTimeout;
|
|
735
723
|
try {
|
|
736
|
-
handlerStarted = true;
|
|
737
724
|
const handlerResult = Promise.resolve().then(() => spec.invoke(attempt, controller.signal));
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
handlerSettled = true;
|
|
741
|
-
releaseIfSettled();
|
|
742
|
-
})
|
|
743
|
-
.catch(() => undefined);
|
|
725
|
+
// After a timeout nothing awaits the handler, which may still reject.
|
|
726
|
+
void handlerResult.catch(() => undefined);
|
|
744
727
|
const timeoutResult = new Promise((_resolve, reject) => {
|
|
745
|
-
|
|
728
|
+
cancelTimeout = this.timer.schedule(() => {
|
|
746
729
|
const error = spec.timeoutError();
|
|
747
730
|
controller.abort(error);
|
|
748
731
|
reject(error);
|
|
@@ -759,28 +742,29 @@ export class Engine {
|
|
|
759
742
|
});
|
|
760
743
|
if (timestamp !== undefined) {
|
|
761
744
|
this.notify(spec.table, key, row);
|
|
762
|
-
|
|
745
|
+
const completed = {
|
|
763
746
|
...spec.entity,
|
|
764
747
|
type: 'attempt_settled',
|
|
765
748
|
timestamp,
|
|
766
749
|
attempt,
|
|
767
750
|
durationMs: Math.max(0, timestamp - startedAt),
|
|
768
751
|
outcome: 'completed',
|
|
769
|
-
|
|
770
|
-
|
|
752
|
+
};
|
|
753
|
+
if (spec.includeResult) {
|
|
754
|
+
completed.result = result;
|
|
755
|
+
}
|
|
756
|
+
spec.emit(completed);
|
|
771
757
|
}
|
|
772
758
|
}
|
|
773
759
|
catch (caught) {
|
|
774
760
|
await this.settleFailure(spec, attempt, startedAt, caught);
|
|
775
761
|
}
|
|
776
762
|
finally {
|
|
777
|
-
|
|
778
|
-
clearTimeout(timeout);
|
|
779
|
-
}
|
|
763
|
+
cancelTimeout?.();
|
|
780
764
|
}
|
|
781
765
|
})().finally(() => {
|
|
782
|
-
|
|
783
|
-
|
|
766
|
+
releasePermit?.();
|
|
767
|
+
settleActive();
|
|
784
768
|
});
|
|
785
769
|
void settled.finally(() => {
|
|
786
770
|
if (spec.active.get(key) === activeExecution) {
|
|
@@ -816,9 +800,9 @@ export class Engine {
|
|
|
816
800
|
error: exhausted,
|
|
817
801
|
});
|
|
818
802
|
}
|
|
819
|
-
async settleFailure(spec, attempt, startedAt,
|
|
803
|
+
async settleFailure(spec, attempt, startedAt, cause) {
|
|
820
804
|
const { key, row } = spec;
|
|
821
|
-
const decision = decideRetry(spec, attempt,
|
|
805
|
+
const decision = decideRetry(spec, attempt, cause);
|
|
822
806
|
const serializedError = serializeError(decision.error);
|
|
823
807
|
const updated = await this.transaction((sql) => {
|
|
824
808
|
const owned = updateAttempt(sql, spec.table, { key, generation: row.generation_id, attempt }, 'status = ?, next_attempt_at = ?, last_error = ?, last_error_name = ?', decision.terminal ? 'failed' : 'pending', decision.nextAttemptAt, serializedError.message, serializedError.name);
|
|
@@ -854,10 +838,11 @@ const engines = new WeakMap();
|
|
|
854
838
|
// Every copy of this package in an isolate shares the registry, so a second
|
|
855
839
|
// copy reaching the same object is caught instead of fighting over its alarm.
|
|
856
840
|
const installation = Symbol('durability installation');
|
|
857
|
-
const globalRegistry = globalThis;
|
|
858
841
|
const registryKey = Symbol.for('durability.object-schedulers');
|
|
859
|
-
|
|
860
|
-
|
|
842
|
+
// SAFETY: registryKey is this package's registered symbol, and every copy
|
|
843
|
+
// stores only a WeakMap<object, ObjectScheduler> under it on globalThis.
|
|
844
|
+
const globalRegistry = globalThis;
|
|
845
|
+
const objectSchedulers = (globalRegistry[registryKey] ?? (globalRegistry[registryKey] = new WeakMap()));
|
|
861
846
|
/** The one engine behind every scheduler and helper of a Durable Object. */
|
|
862
847
|
const engineForObject = (config) => {
|
|
863
848
|
const { context } = config;
|
|
@@ -870,6 +855,8 @@ const engineForObject = (config) => {
|
|
|
870
855
|
if (existing.installation !== installation) {
|
|
871
856
|
throw new Error('Another copy of durability is already attached to this Durable Object; install durability once, for example as a peer dependency');
|
|
872
857
|
}
|
|
858
|
+
// SAFETY: the installation matches, so this copy of the module created the
|
|
859
|
+
// entry above with `new Engine`.
|
|
873
860
|
const engine = existing.engine;
|
|
874
861
|
engine.attach(context, config);
|
|
875
862
|
return engine;
|
|
@@ -911,6 +898,23 @@ export class DurabilityScheduler {
|
|
|
911
898
|
alarm(info) {
|
|
912
899
|
return engineFor({ scheduler: this }).alarm(info);
|
|
913
900
|
}
|
|
901
|
+
/**
|
|
902
|
+
* Runs `callback` once after `delayMs`, like the global `setTimeout`, and
|
|
903
|
+
* returns a function that cancels it. The timeout shares one native timer
|
|
904
|
+
* with every helper on the object, so any number of them can be pending
|
|
905
|
+
* without reaching the runtime's limit of 10,000 native timers.
|
|
906
|
+
*
|
|
907
|
+
* The timeout exists only in memory and an eviction drops it; schedule work
|
|
908
|
+
* that must survive one with `DurabilityAlarms`. Callbacks due at the same
|
|
909
|
+
* time run one after another in the same task, and one that throws is
|
|
910
|
+
* reported as `durability.timer.callback_failed` instead of being thrown.
|
|
911
|
+
*/
|
|
912
|
+
setTimeout(callback, delayMs) {
|
|
913
|
+
if (!isFunction(callback)) {
|
|
914
|
+
throw new TypeError('callback must be a function');
|
|
915
|
+
}
|
|
916
|
+
return engineFor({ scheduler: this }).timer.schedule(callback, delayMs);
|
|
917
|
+
}
|
|
914
918
|
}
|
|
915
919
|
traceMethods(DurabilityScheduler.prototype, 'DurabilityScheduler');
|
|
916
920
|
/** Resolves the engine a helper attaches to: the object's one scheduler. */
|
package/dist/semaphore/client.js
CHANGED
|
@@ -12,6 +12,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
|
|
|
12
12
|
var _SemaphoreClient_instances, _SemaphoreClient_config, _SemaphoreClient_nextRequestAt, _SemaphoreClient_address;
|
|
13
13
|
import * as v from 'valibot';
|
|
14
14
|
import { SemaphoreProtocolError } from '../errors.js';
|
|
15
|
+
import { isNonEmptyString } from '../predicates.js';
|
|
15
16
|
import { permitGrantSchema, permitSyncResultSchema, } from './protocol.js';
|
|
16
17
|
/**
|
|
17
18
|
* Transport-independent protocol core. Validates responses and remembers each
|
|
@@ -54,7 +55,7 @@ export class SemaphoreClient {
|
|
|
54
55
|
}
|
|
55
56
|
}
|
|
56
57
|
_SemaphoreClient_config = new WeakMap(), _SemaphoreClient_nextRequestAt = new WeakMap(), _SemaphoreClient_instances = new WeakSet(), _SemaphoreClient_address = function _SemaphoreClient_address(key) {
|
|
57
|
-
if (
|
|
58
|
+
if (!isNonEmptyString(key)) {
|
|
58
59
|
throw new SemaphoreProtocolError('Semaphore keys must be non-empty strings');
|
|
59
60
|
}
|
|
60
61
|
const locationHint = __classPrivateFieldGet(this, _SemaphoreClient_config, "f").locationHint?.(key);
|
|
@@ -20,7 +20,7 @@ export type SemaphoreSession = {
|
|
|
20
20
|
request(key: string, message: PermitRequest): Promise<PermitGrant>;
|
|
21
21
|
sync(key: string, message: PermitSync): Promise<PermitSyncResult>;
|
|
22
22
|
setContext(context: TransformContext): {
|
|
23
|
-
invoke(method: string, args: unknown[]): Promise<
|
|
23
|
+
invoke(method: string, args: unknown[]): Promise<PermitGrant | PermitSyncResult>;
|
|
24
24
|
};
|
|
25
25
|
};
|
|
26
26
|
export type DurabilitySemaphoreClientConfig<Target extends Rpc.DurableObjectBranded> = DurableObjectTarget<Target> & {
|
package/dist/semaphore/index.js
CHANGED
|
@@ -24,7 +24,7 @@ export class DurabilitySemaphore extends DurabilitySemaphoreServer {
|
|
|
24
24
|
* Caller transforms such as `timeout` apply; transform context is not used.
|
|
25
25
|
*/
|
|
26
26
|
static client(config) {
|
|
27
|
-
const
|
|
27
|
+
const clientConfig = {
|
|
28
28
|
invoke: (address, message) => {
|
|
29
29
|
const namespace = resolveNamespace(config, (text) => new SemaphoreProtocolError(text));
|
|
30
30
|
const stub = namespace.getByName(address.key, address.locationHint === undefined
|
|
@@ -32,20 +32,25 @@ export class DurabilitySemaphore extends DurabilitySemaphoreServer {
|
|
|
32
32
|
: { locationHint: address.locationHint });
|
|
33
33
|
return config.invoke(stub, message);
|
|
34
34
|
},
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
}
|
|
35
|
+
};
|
|
36
|
+
if (config.locationHint !== undefined) {
|
|
37
|
+
clientConfig.locationHint = config.locationHint;
|
|
38
|
+
}
|
|
39
|
+
const client = new SemaphoreClient(clientConfig);
|
|
39
40
|
const session = {
|
|
40
41
|
request: (key, message) => client.request(key, message),
|
|
41
42
|
sync: (key, message) => client.sync(key, message),
|
|
42
43
|
setContext: () => ({
|
|
43
44
|
invoke: (method, args) => {
|
|
45
|
+
// SAFETY: the transform stub forwards the arguments of a typed
|
|
46
|
+
// SemaphoreSession call, so args are [key, message] for `method`.
|
|
44
47
|
const key = args[0];
|
|
45
48
|
if (method === 'request') {
|
|
49
|
+
// SAFETY: see `key`; `request` takes a PermitRequest.
|
|
46
50
|
return client.request(key, args[1]);
|
|
47
51
|
}
|
|
48
52
|
if (method === 'sync') {
|
|
53
|
+
// SAFETY: see `key`; `sync` takes a PermitSync.
|
|
49
54
|
return client.sync(key, args[1]);
|
|
50
55
|
}
|
|
51
56
|
throw new SemaphoreProtocolError(`Unknown semaphore method "${method}"`);
|
|
@@ -67,12 +67,13 @@ type GroupPolicy = {
|
|
|
67
67
|
blocked?: SemaphoreBlockedReason;
|
|
68
68
|
};
|
|
69
69
|
export declare const resolveLeasePolicy: (options: SemaphoreLeaseOptions) => LeasePolicy;
|
|
70
|
-
|
|
71
|
-
export declare const budgets: (provisioning: SemaphoreProvisioning, limit: number) => {
|
|
70
|
+
type PermitBudget = {
|
|
72
71
|
grants: number;
|
|
73
72
|
leases: number;
|
|
74
73
|
shared: boolean;
|
|
75
74
|
};
|
|
75
|
+
/** Permits grants may use, and permits leases may hold, for one limit. */
|
|
76
|
+
export declare const budgets: (provisioning: SemaphoreProvisioning, limit: number) => PermitBudget;
|
|
76
77
|
export declare const leaseFootprint: (lease: LeaseRow) => number;
|
|
77
78
|
export declare const leaseEligible: (policy: LeasePolicy, group: GroupPolicy) => boolean;
|
|
78
79
|
export type LeaseReportOutcome = {
|
package/dist/semaphore/leases.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { assertPositiveInteger } from '../policy.js';
|
|
2
|
+
import { isNumber } from '../predicates.js';
|
|
2
3
|
/** Map key for a client identity; JSON keeps raw IDs and channels unambiguous. */
|
|
3
4
|
export const clientKey = (clientId, clientChannel) => JSON.stringify([clientId, clientChannel]);
|
|
4
5
|
export const ownedBy = (row, client) => row.client_id === client.clientId &&
|
|
@@ -30,14 +31,14 @@ export const resolveLeasePolicy = (options) => {
|
|
|
30
31
|
? policy.provisioning.extra
|
|
31
32
|
: undefined;
|
|
32
33
|
if (amount !== undefined) {
|
|
33
|
-
const value =
|
|
34
|
+
const value = isNumber(amount) ? amount : amount.ratio;
|
|
34
35
|
if (!Number.isFinite(value) || value < 0) {
|
|
35
36
|
throw new RangeError('lease provisioning amounts must be non-negative');
|
|
36
37
|
}
|
|
37
38
|
}
|
|
38
39
|
return policy;
|
|
39
40
|
};
|
|
40
|
-
const scaled = (amount, limit) =>
|
|
41
|
+
const scaled = (amount, limit) => isNumber(amount) ? amount : Math.floor(limit * amount.ratio);
|
|
41
42
|
/** Permits grants may use, and permits leases may hold, for one limit. */
|
|
42
43
|
export const budgets = (provisioning, limit) => {
|
|
43
44
|
if (provisioning.mode === 'over') {
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import * as v from 'valibot';
|
|
2
|
+
import { isNumber } from '../predicates.js';
|
|
2
3
|
export const queueItemRowSchema = v.object({
|
|
3
4
|
id: v.string(),
|
|
4
5
|
key: v.string(),
|
|
@@ -250,7 +251,7 @@ export class QueueStore {
|
|
|
250
251
|
WHERE channel = ? AND confirmed = 0
|
|
251
252
|
)`, this.channel, this.channel, unnotified ? 1 : 0, notified ? 1 : 0, this.channel)
|
|
252
253
|
.toArray()[0]?.['at'];
|
|
253
|
-
return
|
|
254
|
+
return isNumber(at) ? at : undefined;
|
|
254
255
|
}
|
|
255
256
|
items(query, ...bindings) {
|
|
256
257
|
return v.parse(v.array(queueItemRowSchema), this.sql.exec(query, ...bindings).toArray());
|
|
@@ -58,7 +58,7 @@ export type DurabilitySemaphoreQueueConfig<Body> = SchedulerAttachment & {
|
|
|
58
58
|
* Receives items once the holder has confirmed their permits, after the
|
|
59
59
|
* admission commits. Retried until it returns; must be idempotent on item ID.
|
|
60
60
|
*/
|
|
61
|
-
admit(items: AdmittedItem<Body>[]):
|
|
61
|
+
admit(items: AdmittedItem<Body>[]): void | Promise<void>;
|
|
62
62
|
/**
|
|
63
63
|
* Returns which of these admitted items are done. The queue asks on its own
|
|
64
64
|
* alarm and releases them, so a permit whose `release()` was lost (a
|
package/dist/semaphore/queue.js
CHANGED
|
@@ -16,6 +16,7 @@ import { durabilitySemaphoreQueueMigrations } from './migrations.js';
|
|
|
16
16
|
import { migrateCapability, } from '../migrations.js';
|
|
17
17
|
import { DurabilityOutbox, stageWithin, } from '../outbox/index.js';
|
|
18
18
|
import { assertPositiveInteger, } from '../policy.js';
|
|
19
|
+
import { isFunction, isNonEmptyString, isString } from '../predicates.js';
|
|
19
20
|
import { DurabilityScheduler, assertChannel, defaultChannel, engineFor, } from '../scheduler/index.js';
|
|
20
21
|
import { deserialize, serialize } from '../serialization.js';
|
|
21
22
|
import { QueueStore, } from './queue-store.js';
|
|
@@ -38,6 +39,7 @@ const maxReportRetryMs = 5000;
|
|
|
38
39
|
const demandScanLimit = 200;
|
|
39
40
|
const maxDelayMs = 2 ** 31 - 1;
|
|
40
41
|
const pairKey = (key, second) => JSON.stringify([key, second]);
|
|
42
|
+
// SAFETY: callers pass only outbox keys this queue staged, all built by pairKey.
|
|
41
43
|
const parsePairKey = (value) => JSON.parse(value);
|
|
42
44
|
const grantReport = (grant) => ({
|
|
43
45
|
grantId: grant.grant_id,
|
|
@@ -46,12 +48,17 @@ const grantReport = (grant) => ({
|
|
|
46
48
|
});
|
|
47
49
|
// A lease stops drawing by moving its expiry to now, whoever retired it.
|
|
48
50
|
const retiredLocally = (lease, now) => lease.expires_at <= now;
|
|
49
|
-
const leaseReport = (lease) =>
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
}
|
|
51
|
+
const leaseReport = (lease) => {
|
|
52
|
+
const report = {
|
|
53
|
+
leaseId: lease.lease_id,
|
|
54
|
+
drawn: lease.drawn,
|
|
55
|
+
released: lease.released,
|
|
56
|
+
};
|
|
57
|
+
if (retiredLocally(lease, Date.now())) {
|
|
58
|
+
report.retired = true;
|
|
59
|
+
}
|
|
60
|
+
return report;
|
|
61
|
+
};
|
|
55
62
|
/**
|
|
56
63
|
* The holder sweeps a lease at its expiry by its own clock; stopping local
|
|
57
64
|
* draws this long before it bounds the window a skewed clock could open.
|
|
@@ -94,10 +101,10 @@ export class DurabilitySemaphoreQueue {
|
|
|
94
101
|
_DurabilitySemaphoreQueue_notifying.set(this, void 0);
|
|
95
102
|
_DurabilitySemaphoreQueue_checking.set(this, void 0);
|
|
96
103
|
const channel = assertChannel('Semaphore queue', config.channel ?? defaultChannel);
|
|
97
|
-
if (
|
|
104
|
+
if (!isNonEmptyString(config.clientId)) {
|
|
98
105
|
throw new TypeError('clientId must be a non-empty string');
|
|
99
106
|
}
|
|
100
|
-
if (
|
|
107
|
+
if (!isFunction(config.admit)) {
|
|
101
108
|
throw new TypeError('Semaphore queue requires an admit function');
|
|
102
109
|
}
|
|
103
110
|
__classPrivateFieldSet(this, _DurabilitySemaphoreQueue_server, config.server, "f");
|
|
@@ -109,8 +116,7 @@ export class DurabilitySemaphoreQueue {
|
|
|
109
116
|
clientChannel: channel,
|
|
110
117
|
}, "f");
|
|
111
118
|
__classPrivateFieldSet(this, _DurabilitySemaphoreQueue_admit, config.admit, "f");
|
|
112
|
-
if (config.finished !== undefined &&
|
|
113
|
-
typeof config.finished !== 'function') {
|
|
119
|
+
if (config.finished !== undefined && !isFunction(config.finished)) {
|
|
114
120
|
throw new TypeError('finished must be a function');
|
|
115
121
|
}
|
|
116
122
|
__classPrivateFieldSet(this, _DurabilitySemaphoreQueue_finished, config.finished, "f");
|
|
@@ -177,11 +183,9 @@ export class DurabilitySemaphoreQueue {
|
|
|
177
183
|
async enqueue(items) {
|
|
178
184
|
const rows = items.map((item) => {
|
|
179
185
|
const id = item.id ?? crypto.randomUUID();
|
|
180
|
-
if (
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
item.key.length === 0 ||
|
|
184
|
-
(item.group !== undefined && typeof item.group !== 'string')) {
|
|
186
|
+
if (!isNonEmptyString(id) ||
|
|
187
|
+
!isNonEmptyString(item.key) ||
|
|
188
|
+
(item.group !== undefined && !isString(item.group))) {
|
|
185
189
|
throw new TypeError('Semaphore items need a non-empty id, a semaphore key, and a string group');
|
|
186
190
|
}
|
|
187
191
|
const now = Date.now();
|
|
@@ -686,12 +690,15 @@ async function _DurabilitySemaphoreQueue_renewLeases(now) {
|
|
|
686
690
|
}, _DurabilitySemaphoreQueue_stageReport = function _DurabilitySemaphoreQueue_stageReport(grant) {
|
|
687
691
|
stageWithin(__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_outbox, "f"), __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_engine, "f").sql, pairKey(grant.key, `grant:${grant.grant_id}`), { kind: 'grant', claimed: grant.claimed, released: grant.released });
|
|
688
692
|
}, _DurabilitySemaphoreQueue_stageLeaseReport = function _DurabilitySemaphoreQueue_stageLeaseReport(lease) {
|
|
689
|
-
|
|
693
|
+
const report = {
|
|
690
694
|
kind: 'lease',
|
|
691
695
|
drawn: lease.drawn,
|
|
692
696
|
released: lease.released,
|
|
693
|
-
|
|
694
|
-
|
|
697
|
+
};
|
|
698
|
+
if (retiredLocally(lease, Date.now())) {
|
|
699
|
+
report.retired = true;
|
|
700
|
+
}
|
|
701
|
+
stageWithin(__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_outbox, "f"), __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_engine, "f").sql, pairKey(lease.key, `lease:${lease.lease_id}`), report);
|
|
695
702
|
}, _DurabilitySemaphoreQueue_publishReports =
|
|
696
703
|
/** Outbox sink: one `sync` per key; a failed key keeps its entries pending. */
|
|
697
704
|
async function _DurabilitySemaphoreQueue_publishReports(entries) {
|
|
@@ -713,12 +720,15 @@ async function _DurabilitySemaphoreQueue_publishReports(entries) {
|
|
|
713
720
|
});
|
|
714
721
|
}
|
|
715
722
|
else {
|
|
716
|
-
|
|
723
|
+
const report = {
|
|
717
724
|
leaseId: id,
|
|
718
725
|
drawn: entry.value.drawn,
|
|
719
726
|
released: entry.value.released,
|
|
720
|
-
|
|
721
|
-
|
|
727
|
+
};
|
|
728
|
+
if (entry.value.retired) {
|
|
729
|
+
report.retired = true;
|
|
730
|
+
}
|
|
731
|
+
leases.push(report);
|
|
722
732
|
}
|
|
723
733
|
}
|
|
724
734
|
let synced;
|
|
@@ -754,7 +764,7 @@ async function _DurabilitySemaphoreQueue_publishReports(entries) {
|
|
|
754
764
|
__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_instances, "m", _DurabilitySemaphoreQueue_refreshKey).call(this, key);
|
|
755
765
|
});
|
|
756
766
|
}));
|
|
757
|
-
const onError = (
|
|
767
|
+
const onError = (cause) => reportFailure('durability.semaphore_queue.notify_failed', {}, cause);
|
|
758
768
|
__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_engine, "f").waitUntil(__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_instances, "m", _DurabilitySemaphoreQueue_notify).call(this).catch(onError), onError);
|
|
759
769
|
}, _DurabilitySemaphoreQueue_releaseFinished =
|
|
760
770
|
/** Releases admitted items `finished` reports done, one check at a time. */
|
|
@@ -843,6 +853,8 @@ async function _DurabilitySemaphoreQueue_notify() {
|
|
|
843
853
|
id: row.id,
|
|
844
854
|
key: row.key,
|
|
845
855
|
group: row.grp,
|
|
856
|
+
// SAFETY: enqueue is the only writer of item payloads, each
|
|
857
|
+
// serialized from a Body.
|
|
846
858
|
body: deserialize(row.payload),
|
|
847
859
|
enqueuedAt: row.created_at,
|
|
848
860
|
admittedAt: row.admitted_at ?? row.created_at,
|
|
@@ -903,20 +915,7 @@ async function _DurabilitySemaphoreQueue_notify() {
|
|
|
903
915
|
reportFailure('durability.semaphore_queue.retry_policy_failed', {}, error);
|
|
904
916
|
}
|
|
905
917
|
return 60000;
|
|
906
|
-
}, _DurabilitySemaphoreQueue_deadline =
|
|
907
|
-
|
|
908
|
-
try {
|
|
909
|
-
return await Promise.race([
|
|
910
|
-
Promise.resolve().then(run),
|
|
911
|
-
new Promise((_resolve, reject) => {
|
|
912
|
-
timer = setTimeout(() => reject(new Error(`Semaphore ${what} timed out after ${__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_attemptTimeoutMs, "f")}ms`)), __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_attemptTimeoutMs, "f"));
|
|
913
|
-
}),
|
|
914
|
-
]);
|
|
915
|
-
}
|
|
916
|
-
finally {
|
|
917
|
-
if (timer !== undefined) {
|
|
918
|
-
clearTimeout(timer);
|
|
919
|
-
}
|
|
920
|
-
}
|
|
918
|
+
}, _DurabilitySemaphoreQueue_deadline = function _DurabilitySemaphoreQueue_deadline(what, run) {
|
|
919
|
+
return __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_engine, "f").timer.withTimeout(Promise.resolve().then(run), __classPrivateFieldGet(this, _DurabilitySemaphoreQueue_attemptTimeoutMs, "f"), () => new Error(`Semaphore ${what} timed out after ${__classPrivateFieldGet(this, _DurabilitySemaphoreQueue_attemptTimeoutMs, "f")}ms`));
|
|
921
920
|
};
|
|
922
921
|
traceMethods(DurabilitySemaphoreQueue.prototype, 'DurabilitySemaphoreQueue');
|