@econ-v1/domain 7.6.157 → 7.6.159
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/dist/index.d.ts
CHANGED
|
@@ -288,4 +288,5 @@ export { safeOpenPath, parsePushPayload, derivePushDeviceStatus, isPushTag } fro
|
|
|
288
288
|
export { classifyOrigin, routeOrder } from "./network/route-order.js";
|
|
289
289
|
export { ROUTE_SPEED_TIERS, speedTier } from "./network/route-speed.js";
|
|
290
290
|
export { formatNodeLabel, shortNodeId } from "./services/node-label.js";
|
|
291
|
+
export { DEFAULT_ROUTE_SELECTION_POLICY, ROUTE_SELECTION_DEFAULTS } from "./network/route-selection.js";
|
|
291
292
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/** @import { RouteDecision, RouteSelectionInput, RouteSelectionRung, TransportRungName } from '@econ-v1/ports' */
|
|
2
|
+
/** All thresholds for the default strategy (ADR-218 Amendment 12). */
|
|
3
|
+
export const ROUTE_SELECTION_DEFAULTS: Readonly<{
|
|
4
|
+
rank: Readonly<{
|
|
5
|
+
lan: 0;
|
|
6
|
+
wan: 1;
|
|
7
|
+
punch: 2;
|
|
8
|
+
relay: 3;
|
|
9
|
+
}>;
|
|
10
|
+
promotionSuccesses: 2;
|
|
11
|
+
promotionStabilityMs: 10000;
|
|
12
|
+
speedRatio: 0.7;
|
|
13
|
+
speedMinDeltaMs: 50;
|
|
14
|
+
speedStabilityMs: 10000;
|
|
15
|
+
measurementMaxAgeMs: 60000;
|
|
16
|
+
dropThreshold: 3;
|
|
17
|
+
dropWindowMs: 300000;
|
|
18
|
+
unstableCooldownMs: 300000;
|
|
19
|
+
}>;
|
|
20
|
+
/** @type {Readonly<import('@econ-v1/ports').RouteSelectionPolicy> & { decide: (input: RouteSelectionInput) => RouteDecision }} */
|
|
21
|
+
export const DEFAULT_ROUTE_SELECTION_POLICY: Readonly<import("@econ-v1/ports").RouteSelectionPolicy> & {
|
|
22
|
+
decide: (input: RouteSelectionInput) => RouteDecision;
|
|
23
|
+
};
|
|
24
|
+
import type { RouteSelectionInput } from '@econ-v1/ports';
|
|
25
|
+
import type { RouteDecision } from '@econ-v1/ports';
|
|
26
|
+
//# sourceMappingURL=route-selection.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"route-selection.d.ts","sourceRoot":"","sources":["../../src/network/route-selection.js"],"names":[],"mappings":"AAEA,kHAAkH;AAElH,sEAAsE;AACtE;;;;;;;;;;;;;;;;GAWG;AA0FH,kIAAkI;AAClI,6CADW,QAAQ,CAAC,OAAO,gBAAgB,EAAE,oBAAoB,CAAC,GAAG;IAAE,MAAM,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,aAAa,CAAA;CAAE,CACpC;yCAzGK,gBAAgB;mCAAhB,gBAAgB"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@econ-v1/domain",
|
|
3
|
-
"version": "7.6.
|
|
3
|
+
"version": "7.6.159",
|
|
4
4
|
"description": "Platform-neutral domain contracts and errors for Node clients",
|
|
5
5
|
"license": "MIT OR Apache-2.0",
|
|
6
6
|
"author": "Node contributors",
|
|
@@ -57,6 +57,6 @@
|
|
|
57
57
|
"access": "public"
|
|
58
58
|
},
|
|
59
59
|
"dependencies": {
|
|
60
|
-
"@econ-v1/ports": "7.6.
|
|
60
|
+
"@econ-v1/ports": "7.6.159"
|
|
61
61
|
}
|
|
62
62
|
}
|
package/src/index.js
CHANGED
|
@@ -595,3 +595,5 @@ export { classifyOrigin, routeOrder } from "./network/route-order.js";
|
|
|
595
595
|
export { ROUTE_SPEED_TIERS, speedTier } from "./network/route-speed.js";
|
|
596
596
|
|
|
597
597
|
export { formatNodeLabel, shortNodeId } from "./services/node-label.js";
|
|
598
|
+
|
|
599
|
+
export { DEFAULT_ROUTE_SELECTION_POLICY, ROUTE_SELECTION_DEFAULTS } from "./network/route-selection.js";
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
|
|
3
|
+
/** @import { RouteDecision, RouteSelectionInput, RouteSelectionRung, TransportRungName } from '@econ-v1/ports' */
|
|
4
|
+
|
|
5
|
+
/** All thresholds for the default strategy (ADR-218 Amendment 12). */
|
|
6
|
+
export const ROUTE_SELECTION_DEFAULTS = Object.freeze({
|
|
7
|
+
rank: Object.freeze({ lan: 0, wan: 1, punch: 2, relay: 3 }),
|
|
8
|
+
promotionSuccesses: 2,
|
|
9
|
+
promotionStabilityMs: 10_000,
|
|
10
|
+
speedRatio: 0.7,
|
|
11
|
+
speedMinDeltaMs: 50,
|
|
12
|
+
speedStabilityMs: 10_000,
|
|
13
|
+
measurementMaxAgeMs: 60_000,
|
|
14
|
+
dropThreshold: 3,
|
|
15
|
+
dropWindowMs: 300_000,
|
|
16
|
+
unstableCooldownMs: 300_000,
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
/** @type {readonly TransportRungName[]} */
|
|
20
|
+
const RUNGS = Object.freeze(['lan', 'wan', 'punch', 'relay']);
|
|
21
|
+
/** @type {RouteDecision} */
|
|
22
|
+
const STAY = Object.freeze({ kind: 'stay' });
|
|
23
|
+
|
|
24
|
+
/** @param {RouteSelectionRung} rung @param {number} now */
|
|
25
|
+
function fresh(rung, now) {
|
|
26
|
+
const checked = Date.parse(rung.checkedAt ?? '');
|
|
27
|
+
const expires = Date.parse(rung.expiresAt ?? '');
|
|
28
|
+
return Number.isFinite(checked) && checked <= now && now - checked <= ROUTE_SELECTION_DEFAULTS.measurementMaxAgeMs
|
|
29
|
+
&& Number.isFinite(expires) && expires > now;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** @param {RouteSelectionInput} input @param {TransportRungName} name */
|
|
33
|
+
function working(input, name) {
|
|
34
|
+
const rung = input.rungs[name];
|
|
35
|
+
if (rung.status === 'active' && input.active === name) return true;
|
|
36
|
+
return rung.status === 'ok' && (input.active === name || fresh(rung, input.now));
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** A cooldown starts on each drop that completes a recent threshold episode.
|
|
40
|
+
* Keeping the whole window plus cooldown avoids shortening it when the first
|
|
41
|
+
* drop ages out. Future timestamps never count.
|
|
42
|
+
* @param {RouteSelectionRung} rung @param {number} now
|
|
43
|
+
*/
|
|
44
|
+
function unstable(rung, now) {
|
|
45
|
+
const drops = rung.drops.filter(at => Number.isFinite(at) && at <= now).slice().sort((a, b) => a - b);
|
|
46
|
+
for (let index = drops.length - 1; index >= ROUTE_SELECTION_DEFAULTS.dropThreshold - 1; index -= 1) {
|
|
47
|
+
const at = drops[index];
|
|
48
|
+
const first = drops[index - ROUTE_SELECTION_DEFAULTS.dropThreshold + 1];
|
|
49
|
+
if (at !== undefined && first !== undefined && now - at < ROUTE_SELECTION_DEFAULTS.unstableCooldownMs
|
|
50
|
+
&& at - first < ROUTE_SELECTION_DEFAULTS.dropWindowMs) return true;
|
|
51
|
+
}
|
|
52
|
+
return false;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** @param {RouteSelectionRung} rung @param {number} now */
|
|
56
|
+
function measured(rung, now) {
|
|
57
|
+
return fresh(rung, now) && rung.rttMs !== undefined && Number.isFinite(rung.rttMs) && rung.rttMs >= 0;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** Selects deterministically without mutating the snapshot or doing I/O.
|
|
61
|
+
* Rank breaks ties; a sustained materially faster route may beat that order.
|
|
62
|
+
* @param {RouteSelectionInput} input @returns {RouteDecision}
|
|
63
|
+
*/
|
|
64
|
+
function decide(input) {
|
|
65
|
+
const { active, now } = input;
|
|
66
|
+
const activeWorks = active !== undefined && working(input, active);
|
|
67
|
+
// Owner intent wins while working, even over automatic reliability heuristics.
|
|
68
|
+
if (input.pinned !== undefined && working(input, input.pinned)) {
|
|
69
|
+
return input.pinned === active ? STAY : { kind: 'switch', to: input.pinned, reason: { code: active !== undefined && !activeWorks ? 'failed' : 'pinned' } };
|
|
70
|
+
}
|
|
71
|
+
const eligible = RUNGS.filter(name => working(input, name) && !unstable(input.rungs[name], now));
|
|
72
|
+
const alternatives = eligible.filter(name => name !== active);
|
|
73
|
+
const best = alternatives[0];
|
|
74
|
+
if (best === undefined) return STAY;
|
|
75
|
+
if (!activeWorks || active === undefined) return { kind: 'switch', to: best, reason: { code: 'failed' } };
|
|
76
|
+
const current = input.rungs[active];
|
|
77
|
+
if (unstable(current, now)) {
|
|
78
|
+
return { kind: 'switch', to: best, reason: { code: 'unstable', drops: current.drops.filter(at => at <= now && now - at < ROUTE_SELECTION_DEFAULTS.dropWindowMs).length } };
|
|
79
|
+
}
|
|
80
|
+
// Test speed before rank so telemetry can explain a clear improvement.
|
|
81
|
+
const faster = alternatives.filter(name => {
|
|
82
|
+
const candidate = input.rungs[name];
|
|
83
|
+
return measured(candidate, now) && measured(current, now)
|
|
84
|
+
&& candidate.speedStableSinceMs !== undefined && candidate.speedStableSinceMs <= now
|
|
85
|
+
&& now - candidate.speedStableSinceMs >= ROUTE_SELECTION_DEFAULTS.speedStabilityMs
|
|
86
|
+
&& candidate.rttMs !== undefined && current.rttMs !== undefined
|
|
87
|
+
&& candidate.rttMs <= current.rttMs * ROUTE_SELECTION_DEFAULTS.speedRatio
|
|
88
|
+
&& current.rttMs - candidate.rttMs >= ROUTE_SELECTION_DEFAULTS.speedMinDeltaMs;
|
|
89
|
+
}).sort((a, b) => (input.rungs[a].rttMs ?? Infinity) - (input.rungs[b].rttMs ?? Infinity)
|
|
90
|
+
|| ROUTE_SELECTION_DEFAULTS.rank[a] - ROUTE_SELECTION_DEFAULTS.rank[b])[0];
|
|
91
|
+
if (faster !== undefined) return { kind: 'switch', to: faster, reason: { code: 'faster', fromMs: /** @type {number} */ (current.rttMs), toMs: /** @type {number} */ (input.rungs[faster].rttMs) } };
|
|
92
|
+
const higher = alternatives.find(name => {
|
|
93
|
+
const candidate = input.rungs[name];
|
|
94
|
+
// Do not undo a speed-driven switch merely because the slower route ranks higher.
|
|
95
|
+
const materiallySlower = measured(current, now) && measured(candidate, now)
|
|
96
|
+
&& current.rttMs !== undefined && candidate.rttMs !== undefined
|
|
97
|
+
&& current.rttMs <= candidate.rttMs * ROUTE_SELECTION_DEFAULTS.speedRatio
|
|
98
|
+
&& candidate.rttMs - current.rttMs >= ROUTE_SELECTION_DEFAULTS.speedMinDeltaMs;
|
|
99
|
+
return !materiallySlower && ROUTE_SELECTION_DEFAULTS.rank[name] < ROUTE_SELECTION_DEFAULTS.rank[active]
|
|
100
|
+
&& candidate.okStreak >= ROUTE_SELECTION_DEFAULTS.promotionSuccesses
|
|
101
|
+
&& candidate.stableSinceMs !== undefined && candidate.stableSinceMs <= now
|
|
102
|
+
&& now - candidate.stableSinceMs >= ROUTE_SELECTION_DEFAULTS.promotionStabilityMs;
|
|
103
|
+
});
|
|
104
|
+
return higher === undefined ? STAY : { kind: 'switch', to: higher, reason: { code: 'higher-rank' } };
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/** @type {Readonly<import('@econ-v1/ports').RouteSelectionPolicy> & { decide: (input: RouteSelectionInput) => RouteDecision }} */
|
|
108
|
+
export const DEFAULT_ROUTE_SELECTION_POLICY = Object.freeze({ id: 'default-v1', decide });
|