@decentnetwork/lan 0.1.190 → 0.1.192

package/dist/proxy/multi-exit-router.d.ts

@@ -49,6 +49,19 @@ export interface MultiExitRouterOptions {
     log?: (msg: string) => void;
 }
 export declare const BUILTIN_REGION_DOMAINS: Record<string, string[]>;
+export declare function isUsefulRecoverySample(peakBps: number, averageBps: number, minBps?: number): boolean;
+interface HlsExitScore {
+    speedEwma: number | null;
+    flooredAtMs: number | null;
+}
+/** Choose exits safe for a foreground HLS fetch. Once any proven-fast exit is
+ * available, unproven/redeeming exits cannot borrow its score and displace it.
+ * With no proven exit, unproven exits remain the startup/failover path; if every
+ * exit is degraded, keep the original pool as a last resort. Exported for the
+ * policy regression tests. */
+export declare function selectHlsPrimaryPool<T extends HlsExitScore>(pool: T[]): T[];
+/** Dynamic prefetch concurrency follows only the foreground-safe pool. */
+export declare function countHlsDeliveryExits<T extends HlsExitScore>(pool: T[]): number;
 /**
  * Start the multi-exit router. Returns a stop() that closes the listener.
  * Runs until stopped (the CLI command keeps the process alive).
@@ -56,3 +69,4 @@ export declare const BUILTIN_REGION_DOMAINS: Record<string, string[]>;
 export declare function startMultiExitRouter(opts: MultiExitRouterOptions): {
     stop: () => void;
 };
+export {};

package/dist/proxy/multi-exit-router.js

@@ -149,6 +149,16 @@ const NEVER_LEARN = /(^|\.)(google|gstatic|googleapis|googleusercontent|ggpht|gv
 // (≈0.5 Mbit/s) keeps every usable exit in and sits safely ABOVE the 40 KB/s
 // deprioritize floor so a floored exit still drops out.
 const NEAR_DEAD_EXIT_BPS = 60_000;
+// Foreground HLS needs a materially stronger exit than ordinary browsing.
+// CCTV's 720p variant is 1.8 Mbit/s; an exit below ~1.2 Mbit/s cannot deliver
+// one four-second segment quickly enough to be useful even with a small live
+// buffer. Keep such exits available for last-resort failover, but do not count
+// them as HLS delivery capacity or let a slow redemption probe re-enable them.
+// This is bytes/sec (150 KB/s = 1.2 Mbit/s).
+const HLS_DELIVERY_BPS = 150_000;
+export function isUsefulRecoverySample(peakBps, averageBps, minBps = HLS_DELIVERY_BPS) {
+    return peakBps >= minBps && averageBps >= minBps;
+}
 // A buffered segment fetch is given a deadline sized to deliver its body at
 // roughly this bitrate; an exit that can't keep up is abandoned and the next is
 // tried. Live HLS needs each ~4s segment in a few seconds, so this is set near
@@ -206,6 +216,10 @@ class RateMeter {
  *  segments — but KEEP it in the pool (last-resort failover, small requests). */
 const FLOOR_BPS = 40_000;
 const REDEMPTION_MS = 90_000;
+// Redemption probes are intentionally serialized and spaced out. A degraded
+// exit is tested with a duplicate background segment while the player's normal
+// fetch remains on proven exits, so recovery discovery cannot stall playback.
+const REDEMPTION_PROBE_GAP_MS = 15_000;
 function floorExit(exit) {
     exit.speedEwma = exit.speedEwma === null ? FLOOR_BPS : Math.min(exit.speedEwma, FLOOR_BPS);
     exit.flooredAtMs = Date.now();
@@ -213,15 +227,53 @@ function floorExit(exit) {
 /** Feed one tunnel's rate meter into the exit's speed EWMA (peak-window based).
  *  Only transfers past SPEED_MIN_BYTES count — smaller ones never reveal path
  *  capacity on a high-RTT link. */
-function sampleSpeed(exit, meter, durMs) {
+function sampleSpeed(exit, meter, durMs, recoveryMinBps = NEAR_DEAD_EXIT_BPS) {
     exit.bytesDown += meter.total;
     if (meter.total < SPEED_MIN_BYTES)
         return;
     const bps = meter.peakBps(durMs);
     if (bps <= 0)
         return;
+    if (exit.flooredAtMs !== null) {
+        // FLOOR_BPS is a penalty, not a real historical sample. A qualifying probe
+        // replaces it with the fresh measurement instead of blending the floor into
+        // the result. Only a useful-speed transfer proves recovery; a completed but
+        // still-too-slow probe remains floored for another redemption interval.
+        // Peak-window speed is useful for ranking paths, but HLS redemption must
+        // also prove whole-segment average throughput. A probe observed at a 0.9
+        // Mbit/s peak but only 0.6 Mbit/s average caused six-way prefetch/hedge
+        // congestion when it rejoined a 1.8 Mbit/s stream.
+        const averageBps = durMs > 0 ? (meter.total / durMs) * 1000 : 0;
+        if (isUsefulRecoverySample(bps, averageBps, recoveryMinBps)) {
+            exit.speedEwma = bps;
+            exit.flooredAtMs = null;
+        }
+        else {
+            exit.speedEwma = FLOOR_BPS;
+            exit.flooredAtMs = Date.now();
+        }
+        return;
+    }
     exit.speedEwma = exit.speedEwma === null ? bps : SPEED_EWMA_KEEP * exit.speedEwma + (1 - SPEED_EWMA_KEEP) * bps;
-    exit.flooredAtMs = null; // a real qualifying transfer is proof of recovery
+}
+/** Choose exits safe for a foreground HLS fetch. Once any proven-fast exit is
+ * available, unproven/redeeming exits cannot borrow its score and displace it.
+ * With no proven exit, unproven exits remain the startup/failover path; if every
+ * exit is degraded, keep the original pool as a last resort. Exported for the
+ * policy regression tests. */
+export function selectHlsPrimaryPool(pool) {
+    const proven = pool.filter((e) => e.flooredAtMs === null && e.speedEwma !== null && e.speedEwma >= HLS_DELIVERY_BPS);
+    if (proven.length > 0)
+        return proven;
+    const unproven = pool.filter((e) => e.flooredAtMs === null && e.speedEwma === null);
+    return unproven.length > 0 ? unproven : pool;
+}
+/** Dynamic prefetch concurrency follows only the foreground-safe pool. */
+export function countHlsDeliveryExits(pool) {
+    // Two adjacent live segments in flight keep the buffer moving without the
+    // runaway 6-8 request fan-out seen when every marginal exit increased both
+    // prefetch concurrency and whole-segment hedging.
+    return Math.min(2, Math.max(1, selectHlsPrimaryPool(pool).length));
 }
 function fmtMbps(bps) {
     return bps === null ? "?" : `${((bps * 8) / 1e6).toFixed(1)}Mbps`;
@@ -1042,7 +1094,41 @@ export function startMultiExitRouter(opts) {
     }
     // ---- HLS segment prefetch (plain-HTTP streams only) ------------------------
     // Fetch one URL through the region's exit pool, buffered, with failover.
-    function fetchViaRegionBuffered(u, extraHeaders, label, signal, exitHint) {
+    let redemptionProbeInFlight = false;
+    let lastRedemptionProbeMs = 0;
+    function maybeStartRedemptionProbe(u, extraHeaders, region) {
+        const now = Date.now();
+        if (redemptionProbeInFlight || now - lastRedemptionProbeMs < REDEMPTION_PROBE_GAP_MS)
+            return;
+        const candidate = exits
+            .filter((e) => e.region === region && e.flooredAtMs !== null &&
+            now - e.flooredAtMs >= REDEMPTION_MS && e.trippedUntil <= now &&
+            (e.healthy || (e.lastSuccessMs !== null && now - e.lastSuccessMs < RECENT_SUCCESS_MS)))
+            .sort((a, b) => (a.flooredAtMs ?? now) - (b.flooredAtMs ?? now))[0];
+        if (!candidate)
+            return;
+        redemptionProbeInFlight = true;
+        lastRedemptionProbeMs = now;
+        // Re-arm before dispatch so a failed/short probe cannot be started again by
+        // every concurrent playlist refresh.
+        candidate.flooredAtMs = now;
+        log(`  redemption-probe ${candidate.name}: isolated background segment test`);
+        void fetchViaRegionBuffered(u, extraHeaders, "redemption-probe", undefined, undefined, candidate)
+            .then(() => {
+            if (candidate.flooredAtMs === null) {
+                log(`  redemption-probe ${candidate.name}: RECOVERED at ${fmtMbps(candidate.speedEwma)}`);
+            }
+            else {
+                log(`  redemption-probe ${candidate.name}: still degraded — keeping it off foreground HLS`);
+            }
+        })
+            .catch((e) => {
+            floorExit(candidate);
+            log(`  redemption-probe ${candidate.name}: failed (${e.message}) — keeping it off foreground HLS`);
+        })
+            .finally(() => { redemptionProbeInFlight = false; });
+    }
+    function fetchViaRegionBuffered(u, extraHeaders, label, signal, exitHint, forcedExit) {
         return new Promise((resolvep, rejectp) => {
             let settled = false;
             let curReq = null;
@@ -1077,7 +1163,9 @@ export function startMultiExitRouter(opts) {
                 reject(new Error("no region for host"));
                 return;
             }
-            const base0 = pickOrder(region);
+            if (!forcedExit && label === "prefetch")
+                maybeStartRedemptionProbe(u, extraHeaders, region);
+            const base0 = forcedExit ? [forcedExit] : pickOrder(region);
             if (base0.length === 0) {
                 reject(new Error("no healthy exit"));
                 return;
@@ -1092,7 +1180,10 @@ export function startMultiExitRouter(opts) {
             // moderately-slow ones (0.4–0.6 Mbps) that we WANT for aggregation. A
             // single (non-striped) fetch instead skips near-dead exits and rotates.
             let order;
-            if (exitHint !== undefined) {
+            if (forcedExit) {
+                order = base0;
+            }
+            else if (exitHint !== undefined) {
                 // Striped range: use pickOrder's live LOAD-AWARE order directly (base0 is
                 // sorted by speed/(active+1), least-loaded-fastest first). Because each
                 // buffered fetch now increments exit.active at connect time, concurrent
@@ -1110,8 +1201,7 @@ export function startMultiExitRouter(opts) {
                 // splitting one exit's bandwidth N ways (observed: 3 segments all on
                 // 1.15 at ~1Mbps each while 1.16 sat idle). A blind RR rotation kept
                 // colliding because it ignored who was actually busy.
-                const fast = base0.filter((e) => e.speedEwma === null || e.speedEwma >= NEAR_DEAD_EXIT_BPS);
-                order = fast.length > 0 ? fast : base0;
+                order = selectHlsPrimaryPool(base0);
             }
             const path = (u.pathname || "/") + (u.search || "");
             const tail = (u.pathname || "/").split("/").pop() || path;
@@ -1123,7 +1213,8 @@ export function startMultiExitRouter(opts) {
                     // bad luck; a fresh retry usually succeeds. Loop the whole exit order a
                     // few rounds before giving up, so the player almost never sees a hard
                     // failure (which trips its error watchdog → error.html → black screen).
-                    if (round + 1 < MAX_FETCH_ROUNDS) {
+                    const maxRounds = forcedExit ? 1 : MAX_FETCH_ROUNDS;
+                    if (round + 1 < maxRounds) {
                         const t = setTimeout(() => tryIdx(0, round + 1), 150);
                         t.unref?.();
                         return;
@@ -1201,7 +1292,7 @@ export function startMultiExitRouter(opts) {
                             nextExit(`empty ${status}`);
                             return;
                         }
-                        sampleSpeed(exit, meter, durMs);
+                        sampleSpeed(exit, meter, durMs, HLS_DELIVERY_BPS);
                         if (label) {
                             const kb = (body.length / 1024).toFixed(0);
                             const mbps = durMs > 0 ? ((body.length * 8) / durMs / 1000).toFixed(1) : "?";
@@ -1268,10 +1359,9 @@ export function startMultiExitRouter(opts) {
         if (!fallbackRegion)
             return 1;
         const now = Date.now();
-        const n = exits.filter((e) => e.region === fallbackRegion && e.trippedUntil <= now &&
-            (e.healthy || (e.lastSuccessMs !== null && now - e.lastSuccessMs < RECENT_SUCCESS_MS)) &&
-            (e.speedEwma === null || e.speedEwma >= NEAR_DEAD_EXIT_BPS)).length;
-        return Math.max(1, n);
+        const eligible = exits.filter((e) => e.region === fallbackRegion && e.trippedUntil <= now &&
+            (e.healthy || (e.lastSuccessMs !== null && now - e.lastSuccessMs < RECENT_SUCCESS_MS)));
+        return countHlsDeliveryExits(eligible);
     };
     const usableChinaExits = () => Math.min(AGG, deliveringChinaExits());
     // Prefetch parallelism = the number of exits ACTUALLY delivering right now
@@ -1565,17 +1655,6 @@ export function startMultiExitRouter(opts) {
     });
     if (mode === "loadbalance") {
         const reporter = setInterval(() => {
-            // Redemption: lift an expired speed-floor back to "unproven" so the exit
-            // gets a fresh segment chance (only segments can re-prove it; without
-            // this a floor is a permanent exclusion, which we never want).
-            const rnow = Date.now();
-            for (const e of exits) {
-                if (e.flooredAtMs !== null && rnow - e.flooredAtMs > REDEMPTION_MS) {
-                    e.flooredAtMs = null;
-                    e.speedEwma = null;
-                    log(`${e.name}: floor lifted after ${Math.round(REDEMPTION_MS / 1000)}s — giving it another chance`);
-                }
-            }
             const parts = exits.filter((e) => e.healthy).map((e) => `${e.name}[${e.region}]: ${e.active} active / ${e.served} total / ${fmtMbps(e.speedEwma)}`);
             parts.push(`direct: ${directActive} active / ${directTotal} total`);
             log(`load — ${parts.join("  |  ")}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/lan",
-  "version": "0.1.190",
+  "version": "0.1.192",
   "description": "Private virtual LAN for self-hosted services and AI agents, built on Elastos Carrier. NAT-traversal, name service, ACL, all over a peer-to-peer mesh — no public IP required.",
   "type": "module",
   "main": "./dist/index.js",