durability 5.3.0 → 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 +23 -14
- 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 -13
- 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/operations/index.js +8 -4
- package/dist/outbox/index.d.ts +1 -1
- package/dist/outbox/index.js +7 -4
- 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 +2 -2
- package/dist/schedule/index.js +16 -12
- package/dist/scheduler/index.d.ts +16 -13
- package/dist/scheduler/index.js +39 -33
- 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 +34 -22
- package/dist/semaphore/server.js +31 -22
- package/dist/serialization.d.ts +3 -2
- package/dist/serialization.js +16 -13
- package/dist/socket/client.d.ts +21 -7
- package/dist/socket/client.js +12 -5
- 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 +9 -6
- package/dist/topology/index.d.ts +3 -3
- package/dist/topology/index.js +38 -33
- package/dist/topology/snapshot.d.ts +6 -5
- package/dist/topology/snapshot.js +5 -2
- package/dist/tracker/index.js +10 -2
- package/dist/tracker/source.d.ts +6 -2
- package/package.json +2 -2
package/dist/scheduler/index.js
CHANGED
|
@@ -4,6 +4,7 @@ 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';
|
|
8
9
|
import { SharedTimer } from '../shared-timer.js';
|
|
9
10
|
import { channelBindings, channelClause, claimAttempt, exhaustAttempts, tableOwner, updateAttempt, } from '../storage.js';
|
|
@@ -34,18 +35,18 @@ const channelRowSchema = v.object({ channel: v.string() });
|
|
|
34
35
|
const activeKey = (channel, key) => JSON.stringify([channel ?? null, key]);
|
|
35
36
|
/** Rejects a channel name a helper would otherwise store rows under. */
|
|
36
37
|
export const assertChannel = (helper, channel) => {
|
|
37
|
-
if (
|
|
38
|
+
if (!isNonEmptyString(channel)) {
|
|
38
39
|
throw new TypeError(`${helper} channel must be a non-empty string`);
|
|
39
40
|
}
|
|
40
41
|
return channel;
|
|
41
42
|
};
|
|
42
|
-
const decideRetry = (spec, attempt,
|
|
43
|
-
const terminal = isNonRetryable(
|
|
43
|
+
const decideRetry = (spec, attempt, cause) => {
|
|
44
|
+
const terminal = isNonRetryable(cause) ||
|
|
44
45
|
attempt >= spec.policy.maxAttempts ||
|
|
45
|
-
spec.isTerminal(
|
|
46
|
+
spec.isTerminal(cause);
|
|
46
47
|
if (terminal) {
|
|
47
48
|
const timestamp = Date.now();
|
|
48
|
-
return { error, terminal, timestamp, nextAttemptAt: timestamp };
|
|
49
|
+
return { error: cause, terminal, timestamp, nextAttemptAt: timestamp };
|
|
49
50
|
}
|
|
50
51
|
try {
|
|
51
52
|
const rawDelay = spec.policy.delay(attempt);
|
|
@@ -59,7 +60,7 @@ const decideRetry = (spec, attempt, error) => {
|
|
|
59
60
|
throw new DurableRetryPolicyError(spec.label);
|
|
60
61
|
}
|
|
61
62
|
return {
|
|
62
|
-
error,
|
|
63
|
+
error: cause,
|
|
63
64
|
terminal: false,
|
|
64
65
|
timestamp,
|
|
65
66
|
nextAttemptAt: timestamp + delay,
|
|
@@ -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) {
|
|
@@ -447,7 +447,7 @@ export class Engine {
|
|
|
447
447
|
}
|
|
448
448
|
this.earlyAlarm = undefined;
|
|
449
449
|
trace('scheduler.early_alarm', { scheduledTime: timestamp });
|
|
450
|
-
const onError = (
|
|
450
|
+
const onError = (cause) => reportFailure('durability.background_execution.failed', { scheduledTime: timestamp }, cause);
|
|
451
451
|
const execution = this.alarm().catch(onError);
|
|
452
452
|
this.waitUntil(execution, onError);
|
|
453
453
|
}, delay);
|
|
@@ -590,7 +590,7 @@ export class Engine {
|
|
|
590
590
|
throw error;
|
|
591
591
|
}
|
|
592
592
|
reportFailure('durability.alarm.failed', { retryInMs: this.alarmMinDelayMs }, error);
|
|
593
|
-
this.notifyAlarmRetry(error, info);
|
|
593
|
+
this.notifyAlarmRetry(serializeError(error), info);
|
|
594
594
|
this.retryFailedRun();
|
|
595
595
|
}
|
|
596
596
|
}
|
|
@@ -605,24 +605,24 @@ export class Engine {
|
|
|
605
605
|
const delay = Math.min(failedRunRetryMs * 2 ** (this.failedRuns - 1), this.alarmMinDelayMs);
|
|
606
606
|
this.scheduleEarlyAlarm(Date.now() + delay);
|
|
607
607
|
}
|
|
608
|
-
notifyAlarmRetry(
|
|
608
|
+
notifyAlarmRetry(error, invocation) {
|
|
609
609
|
const hook = this.onAlarmRetry;
|
|
610
610
|
if (!hook) {
|
|
611
611
|
return;
|
|
612
612
|
}
|
|
613
613
|
const objectId = this.objectId();
|
|
614
614
|
const info = {
|
|
615
|
-
error
|
|
615
|
+
error,
|
|
616
616
|
retryInMs: this.alarmMinDelayMs,
|
|
617
|
-
...(invocation === undefined
|
|
618
|
-
? {}
|
|
619
|
-
: {
|
|
620
|
-
retryCount: invocation.retryCount,
|
|
621
|
-
isRetry: invocation.isRetry,
|
|
622
|
-
}),
|
|
623
|
-
...(objectId === undefined ? {} : { objectId }),
|
|
624
617
|
};
|
|
625
|
-
|
|
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);
|
|
626
626
|
try {
|
|
627
627
|
const result = hook(info);
|
|
628
628
|
if (result !== undefined) {
|
|
@@ -742,15 +742,18 @@ export class Engine {
|
|
|
742
742
|
});
|
|
743
743
|
if (timestamp !== undefined) {
|
|
744
744
|
this.notify(spec.table, key, row);
|
|
745
|
-
|
|
745
|
+
const completed = {
|
|
746
746
|
...spec.entity,
|
|
747
747
|
type: 'attempt_settled',
|
|
748
748
|
timestamp,
|
|
749
749
|
attempt,
|
|
750
750
|
durationMs: Math.max(0, timestamp - startedAt),
|
|
751
751
|
outcome: 'completed',
|
|
752
|
-
|
|
753
|
-
|
|
752
|
+
};
|
|
753
|
+
if (spec.includeResult) {
|
|
754
|
+
completed.result = result;
|
|
755
|
+
}
|
|
756
|
+
spec.emit(completed);
|
|
754
757
|
}
|
|
755
758
|
}
|
|
756
759
|
catch (caught) {
|
|
@@ -797,9 +800,9 @@ export class Engine {
|
|
|
797
800
|
error: exhausted,
|
|
798
801
|
});
|
|
799
802
|
}
|
|
800
|
-
async settleFailure(spec, attempt, startedAt,
|
|
803
|
+
async settleFailure(spec, attempt, startedAt, cause) {
|
|
801
804
|
const { key, row } = spec;
|
|
802
|
-
const decision = decideRetry(spec, attempt,
|
|
805
|
+
const decision = decideRetry(spec, attempt, cause);
|
|
803
806
|
const serializedError = serializeError(decision.error);
|
|
804
807
|
const updated = await this.transaction((sql) => {
|
|
805
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);
|
|
@@ -835,10 +838,11 @@ const engines = new WeakMap();
|
|
|
835
838
|
// Every copy of this package in an isolate shares the registry, so a second
|
|
836
839
|
// copy reaching the same object is caught instead of fighting over its alarm.
|
|
837
840
|
const installation = Symbol('durability installation');
|
|
838
|
-
const globalRegistry = globalThis;
|
|
839
841
|
const registryKey = Symbol.for('durability.object-schedulers');
|
|
840
|
-
|
|
841
|
-
|
|
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()));
|
|
842
846
|
/** The one engine behind every scheduler and helper of a Durable Object. */
|
|
843
847
|
const engineForObject = (config) => {
|
|
844
848
|
const { context } = config;
|
|
@@ -851,6 +855,8 @@ const engineForObject = (config) => {
|
|
|
851
855
|
if (existing.installation !== installation) {
|
|
852
856
|
throw new Error('Another copy of durability is already attached to this Durable Object; install durability once, for example as a peer dependency');
|
|
853
857
|
}
|
|
858
|
+
// SAFETY: the installation matches, so this copy of the module created the
|
|
859
|
+
// entry above with `new Engine`.
|
|
854
860
|
const engine = existing.engine;
|
|
855
861
|
engine.attach(context, config);
|
|
856
862
|
return engine;
|
|
@@ -904,7 +910,7 @@ export class DurabilityScheduler {
|
|
|
904
910
|
* reported as `durability.timer.callback_failed` instead of being thrown.
|
|
905
911
|
*/
|
|
906
912
|
setTimeout(callback, delayMs) {
|
|
907
|
-
if (
|
|
913
|
+
if (!isFunction(callback)) {
|
|
908
914
|
throw new TypeError('callback must be a function');
|
|
909
915
|
}
|
|
910
916
|
return engineFor({ scheduler: this }).timer.schedule(callback, delayMs);
|
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,
|
package/dist/semaphore/server.js
CHANGED
|
@@ -16,6 +16,7 @@ import { SemaphoreProtocolError, reportFailure } from '../errors.js';
|
|
|
16
16
|
import { durabilitySemaphoreMigrations } from './migrations.js';
|
|
17
17
|
import { migrateCapability, } from '../migrations.js';
|
|
18
18
|
import { assertPositiveInteger } from '../policy.js';
|
|
19
|
+
import { isFunction, isNumber } from '../predicates.js';
|
|
19
20
|
import { allocateLeases, applyLeaseReports, budgets, clientKey, leaseFootprint, ownedBy, resolveLeasePolicy, } from './leases.js';
|
|
20
21
|
import { assertChannel, defaultChannel, engineFor, } from '../scheduler/index.js';
|
|
21
22
|
import { semaphoreRequestSchema, } from './protocol.js';
|
|
@@ -37,12 +38,15 @@ const clientOf = (message) => ({
|
|
|
37
38
|
* Echoes the protocol identity so the client can verify which queue was counted.
|
|
38
39
|
* Version 1 retains the response shape older clients expect.
|
|
39
40
|
*/
|
|
40
|
-
const acknowledgement = (message) =>
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
41
|
+
const acknowledgement = (message) => {
|
|
42
|
+
const echo = {
|
|
43
|
+
v: message.v,
|
|
44
|
+
};
|
|
45
|
+
if (message.clientChannel !== undefined) {
|
|
46
|
+
echo.clientChannel = message.clientChannel;
|
|
47
|
+
}
|
|
48
|
+
return echo;
|
|
49
|
+
};
|
|
46
50
|
/** Permits left queued per (group, reason) across one round's allocations. */
|
|
47
51
|
const blockedCounts = (allocations) => {
|
|
48
52
|
const counts = new Map();
|
|
@@ -59,6 +63,7 @@ const blockedCounts = (allocations) => {
|
|
|
59
63
|
}
|
|
60
64
|
}
|
|
61
65
|
return [...counts].map(([key, count]) => {
|
|
66
|
+
// SAFETY: every key was built above by JSON.stringify([group, reason]).
|
|
62
67
|
const [group, reason] = JSON.parse(key);
|
|
63
68
|
return [group, reason, count];
|
|
64
69
|
});
|
|
@@ -93,9 +98,8 @@ export class DurabilitySemaphoreServer {
|
|
|
93
98
|
_DurabilitySemaphoreServer_contended.set(this, false);
|
|
94
99
|
const channel = assertChannel('Semaphore', config.channel ?? defaultChannel);
|
|
95
100
|
const limit = config.limit;
|
|
96
|
-
__classPrivateFieldSet(this, _DurabilitySemaphoreServer_limit,
|
|
97
|
-
if (
|
|
98
|
-
(!Number.isSafeInteger(limit) || limit < 0)) {
|
|
101
|
+
__classPrivateFieldSet(this, _DurabilitySemaphoreServer_limit, isFunction(limit) ? limit : () => limit, "f");
|
|
102
|
+
if (isNumber(limit) && (!Number.isSafeInteger(limit) || limit < 0)) {
|
|
99
103
|
throw new RangeError('limit must be a non-negative safe integer');
|
|
100
104
|
}
|
|
101
105
|
__classPrivateFieldSet(this, _DurabilitySemaphoreServer_groupLimit, config.groupLimit, "f");
|
|
@@ -206,7 +210,7 @@ _DurabilitySemaphoreServer_engine = new WeakMap(), _DurabilitySemaphoreServer_st
|
|
|
206
210
|
__classPrivateFieldSet(this, _DurabilitySemaphoreServer_roundScheduled, true, "f");
|
|
207
211
|
__classPrivateFieldGet(this, _DurabilitySemaphoreServer_engine, "f").timer.schedule(() => {
|
|
208
212
|
__classPrivateFieldSet(this, _DurabilitySemaphoreServer_roundScheduled, false, "f");
|
|
209
|
-
const onError = (
|
|
213
|
+
const onError = (cause) => reportFailure('durability.semaphore.round_failed', {}, cause);
|
|
210
214
|
__classPrivateFieldSet(this, _DurabilitySemaphoreServer_round, __classPrivateFieldGet(this, _DurabilitySemaphoreServer_instances, "m", _DurabilitySemaphoreServer_runRound).call(this)
|
|
211
215
|
.catch(onError)
|
|
212
216
|
.finally(() => {
|
|
@@ -247,15 +251,19 @@ _DurabilitySemaphoreServer_engine = new WeakMap(), _DurabilitySemaphoreServer_st
|
|
|
247
251
|
__classPrivateFieldSet(this, _DurabilitySemaphoreServer_contended, round.contended, "f");
|
|
248
252
|
for (const [entry, allocation] of round.allocations) {
|
|
249
253
|
const { leases, ...rest } = allocation;
|
|
250
|
-
|
|
254
|
+
const grant = {
|
|
251
255
|
type: 'grant',
|
|
252
256
|
...acknowledgement(entry.request),
|
|
253
257
|
...rest,
|
|
254
258
|
nextRequestAt,
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
+
};
|
|
260
|
+
if (entry.request.leases !== undefined) {
|
|
261
|
+
grant.leases = leases;
|
|
262
|
+
if (round.contended) {
|
|
263
|
+
grant.contended = true;
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
entry.resolve(grant);
|
|
259
267
|
}
|
|
260
268
|
for (const event of [...round.reclaimed, ...round.leaseEvents]) {
|
|
261
269
|
__classPrivateFieldGet(this, _DurabilitySemaphoreServer_emit, "f").call(this, event);
|
|
@@ -451,17 +459,18 @@ _DurabilitySemaphoreServer_engine = new WeakMap(), _DurabilitySemaphoreServer_st
|
|
|
451
459
|
: undefined;
|
|
452
460
|
return { grantResults, leaseEchoes: leaseOutcome?.echoes };
|
|
453
461
|
});
|
|
454
|
-
|
|
462
|
+
const synced = {
|
|
455
463
|
type: 'synced',
|
|
456
464
|
...acknowledgement(message),
|
|
457
465
|
grantResults: result.grantResults,
|
|
458
|
-
...(result.leaseEchoes === undefined
|
|
459
|
-
? {}
|
|
460
|
-
: {
|
|
461
|
-
leases: result.leaseEchoes,
|
|
462
|
-
...(__classPrivateFieldGet(this, _DurabilitySemaphoreServer_contended, "f") ? { contended: true } : {}),
|
|
463
|
-
}),
|
|
464
466
|
};
|
|
467
|
+
if (result.leaseEchoes !== undefined) {
|
|
468
|
+
synced.leases = result.leaseEchoes;
|
|
469
|
+
if (__classPrivateFieldGet(this, _DurabilitySemaphoreServer_contended, "f")) {
|
|
470
|
+
synced.contended = true;
|
|
471
|
+
}
|
|
472
|
+
}
|
|
473
|
+
return synced;
|
|
465
474
|
}, _DurabilitySemaphoreServer_applyReports = function _DurabilitySemaphoreServer_applyReports(store, client, reports, now) {
|
|
466
475
|
const results = [];
|
|
467
476
|
for (const report of reports) {
|
package/dist/serialization.d.ts
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
import * as v from 'valibot';
|
|
2
|
-
export type Json = string | number | boolean | null | Json[] |
|
|
2
|
+
export type Json = string | number | boolean | null | Json[] | JsonObject;
|
|
3
|
+
export type JsonObject = {
|
|
3
4
|
[key: string]: Json;
|
|
4
5
|
};
|
|
5
6
|
export declare const jsonSchema: v.CustomSchema<Json, v.ErrorMessage<v.CustomIssue> | undefined>;
|
|
6
7
|
export declare const serialize: (value: unknown) => string;
|
|
7
|
-
export declare const deserialize: (value: string) =>
|
|
8
|
+
export declare const deserialize: (value: string) => Json | undefined;
|
|
8
9
|
/**
|
|
9
10
|
* The stored form with object keys sorted at every depth, so two payloads
|
|
10
11
|
* compare equal when they carry the same data regardless of key order.
|
package/dist/serialization.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import * as v from 'valibot';
|
|
2
|
+
import { isJsonObject } from './predicates.js';
|
|
2
3
|
const isPlainObject = (value) => {
|
|
3
4
|
if (value === null || typeof value !== 'object') {
|
|
4
5
|
return false;
|
|
@@ -33,27 +34,28 @@ const storedValueSchema = v.variant('kind', [
|
|
|
33
34
|
v.object({ kind: v.literal('undefined') }),
|
|
34
35
|
]);
|
|
35
36
|
/**
|
|
36
|
-
*
|
|
37
|
-
* `undefined` array elements become `null`.
|
|
38
|
-
* although they are routine in values such
|
|
39
|
-
* returned nothing.
|
|
37
|
+
* Parses a value into what `JSON.stringify` would produce: `undefined`
|
|
38
|
+
* properties are dropped and `undefined` array elements become `null`.
|
|
39
|
+
* `jsonSchema` rejects both as given, although they are routine in values such
|
|
40
|
+
* as lifecycle events whose handler returned nothing.
|
|
40
41
|
*/
|
|
41
|
-
const
|
|
42
|
+
const toJson = (value) => {
|
|
42
43
|
if (Array.isArray(value)) {
|
|
43
|
-
|
|
44
|
+
// `map` keeps the holes of a sparse array, which are not JSON.
|
|
45
|
+
return v.parse(jsonSchema, value.map((item) => (item === undefined ? null : toJson(item))));
|
|
44
46
|
}
|
|
45
47
|
// Only plain objects are rewritten; anything else must fail validation as is.
|
|
46
48
|
if (!isPlainObject(value)) {
|
|
47
|
-
return value;
|
|
49
|
+
return v.parse(jsonSchema, value);
|
|
48
50
|
}
|
|
49
51
|
return Object.fromEntries(Object.entries(value)
|
|
50
52
|
.filter(([, item]) => item !== undefined)
|
|
51
|
-
.map(([key, item]) => [key,
|
|
53
|
+
.map(([key, item]) => [key, toJson(item)]));
|
|
52
54
|
};
|
|
53
55
|
// Wrapping preserves a successful `undefined` result, which bare JSON cannot represent.
|
|
54
56
|
export const serialize = (value) => JSON.stringify(value === undefined
|
|
55
57
|
? { kind: 'undefined' }
|
|
56
|
-
: { kind: 'value', value:
|
|
58
|
+
: { kind: 'value', value: toJson(value) });
|
|
57
59
|
export const deserialize = (value) => {
|
|
58
60
|
const stored = v.parse(storedValueSchema, JSON.parse(value));
|
|
59
61
|
return stored.kind === 'undefined' ? undefined : stored.value;
|
|
@@ -62,10 +64,10 @@ const canonicalize = (value) => {
|
|
|
62
64
|
if (Array.isArray(value)) {
|
|
63
65
|
return value.map(canonicalize);
|
|
64
66
|
}
|
|
65
|
-
if (value
|
|
66
|
-
return Object.fromEntries(Object.
|
|
67
|
-
.sort()
|
|
68
|
-
.map((key) => [key, canonicalize(
|
|
67
|
+
if (isJsonObject(value)) {
|
|
68
|
+
return Object.fromEntries(Object.entries(value)
|
|
69
|
+
.sort(([left], [right]) => (left < right ? -1 : 1))
|
|
70
|
+
.map(([key, item]) => [key, canonicalize(item)]));
|
|
69
71
|
}
|
|
70
72
|
return value;
|
|
71
73
|
};
|
|
@@ -73,4 +75,5 @@ const canonicalize = (value) => {
|
|
|
73
75
|
* The stored form with object keys sorted at every depth, so two payloads
|
|
74
76
|
* compare equal when they carry the same data regardless of key order.
|
|
75
77
|
*/
|
|
78
|
+
// SAFETY: JSON.parse yields only JSON values.
|
|
76
79
|
export const canonical = (stored) => JSON.stringify(canonicalize(JSON.parse(stored)));
|