@decentnetwork/lan 0.1.138 → 0.1.139

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

@@ -17,8 +17,14 @@
 // cloning the repo (it used to live in scripts/failover-proxy.mjs).
 //
 import http from "node:http";
+import https from "node:https";
 import net from "node:net";
+import tls from "node:tls";
 import { egressConnect } from "./egress.js";
+import { HlsPrefetcher, looksLikePlaylist, looksLikeSegment, parseM3u8Variants, parseM3u8Segments } from "./hls-prefetch.js";
+import { RouteLearner } from "./route-learner.js";
+import { GeoCnClassifier } from "./geo-cn.js";
+import { MitmGateway } from "./mitm-gateway.js";
 // Built-in domain lists, so a user can reference a region by name in
 // routes.yaml without hand-listing every domain. Override by giving the
 // region its own `domains` list.
@@ -27,6 +33,7 @@ export const BUILTIN_REGION_DOMAINS = {
     china: [
         ".cn",
         ".cctv.com", ".cctvpic.com", ".cntv.cn", ".cctv.cn",
+        ".v.myalicdn.com", // CCTV live HLS rides Ali CDN video subdomains (piccpndali.v.myalicdn.com etc.)
         ".bilibili.com", ".biliapi.net", ".bilivideo.com", ".bilivideo.cn", ".hdslb.com",
         ".youku.com", ".iqiyi.com", ".iq.com", ".mgtv.com", ".hitv.com",
         ".miguvideo.com", ".cmvideo.cn", ".migu.cn",
@@ -83,6 +90,81 @@ const HEALTH_TIMEOUT_MS = 4000;
 // of transient jitter on a long-haul path (don't blackout a region on one blip).
 const DOWN_AFTER_FAILS = 3;
 const CONNECT_TIMEOUT_MS = 8000;
+// Tunnel-establishment timeout through an EXIT (vs direct). Tighter than the
+// direct timeout: on failure we fail over to the next exit in the order, and a
+// video player can't hide an 8s stall.
+const EXIT_CONNECT_TIMEOUT_MS = 4000;
+// Throughput sampling: only transfers that moved at least this many bytes
+// produce a speed sample. Below this, a transfer over a high-RTT path is all
+// TCP slow-start and latency, never reaching path capacity — measuring it
+// underestimates by ~5x and poisons the ordering. Video segments clear this;
+// API calls and redirects don't (they stay unmeasured = balanced by load).
+const SPEED_MIN_BYTES = 512 * 1024;
+// We record PEAK 1-second throughput within a transfer, not lifetime average,
+// so slow-start ramp-up doesn't drag the estimate down.
+const SPEED_WINDOW_MS = 1000;
+const SPEED_EWMA_KEEP = 0.6; // new = keep*old + (1-keep)*sample
+// Circuit breaker for an unstable exit (e.g. a friend's laptop that comes and
+// goes, or an exit whose CONNECT still answers but whose forwarding is dead).
+// A tunnel that establishes but then delivers almost nothing counts as a STALL;
+// enough consecutive stalls trip the exit OUT of the pool for a cooldown, so one
+// flaky node never stalls the whole experience.
+const STALL_IDLE_MS = 6000; // no bytes for this long on an open tunnel = stalled → tear down
+const STALL_MIN_OPEN_MS = 4000; // only a tunnel open at least this long can count as a stall
+const STALL_MIN_BYTES = 16 * 1024; // delivered less than this over that time = stall, not a short ok tunnel
+const TRIP_AFTER_STALLS = 2; // consecutive stalls before an exit is tripped out
+const TRIP_COOLDOWN_MS = 30_000; // how long a tripped exit stays excluded before it's retried
+// Measures peak short-window throughput of a byte stream. Feed it every chunk
+// length via add(); read peakBps at the end. Peak (not average) shrugs off TCP
+// slow-start on high-RTT paths, where a transfer spends its first seconds
+// ramping and a lifetime-average badly understates real capacity.
+class RateMeter {
+    total = 0;
+    #winBytes = 0;
+    #winStart = 0;
+    #peakBps = 0;
+    add(len, nowMs) {
+        this.total += len;
+        if (this.#winStart === 0) {
+            this.#winStart = nowMs;
+            this.#winBytes = len;
+            return;
+        }
+        const dt = nowMs - this.#winStart;
+        if (dt >= SPEED_WINDOW_MS) {
+            const bps = (this.#winBytes / dt) * 1000;
+            if (bps > this.#peakBps)
+                this.#peakBps = bps;
+            this.#winStart = nowMs;
+            this.#winBytes = len;
+        }
+        else {
+            this.#winBytes += len;
+        }
+    }
+    /** Peak bytes/sec, falling back to whole-transfer average if no full window
+     *  ever closed (a fast small-ish transfer that still cleared SPEED_MIN_BYTES). */
+    peakBps(totalDurMs) {
+        if (this.#peakBps > 0)
+            return this.#peakBps;
+        return totalDurMs > 0 ? (this.total / totalDurMs) * 1000 : 0;
+    }
+}
+/** 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) {
+    exit.bytesDown += meter.total;
+    if (meter.total < SPEED_MIN_BYTES)
+        return;
+    const bps = meter.peakBps(durMs);
+    if (bps <= 0)
+        return;
+    exit.speedEwma = exit.speedEwma === null ? bps : SPEED_EWMA_KEEP * exit.speedEwma + (1 - SPEED_EWMA_KEEP) * bps;
+}
+function fmtMbps(bps) {
+    return bps === null ? "?" : `${((bps * 8) / 1e6).toFixed(1)}Mbps`;
+}
 // An exit that carried a real tunnel within this window is treated as healthy
 // regardless of what the synthetic probe says (the probe adds load and flaps on
 // a busy/jittery exit; live traffic is the truth).
@@ -113,6 +195,10 @@ export function startMultiExitRouter(opts) {
         served: 0,
         lastRtt: null,
         lastSuccessMs: null,
+        speedEwma: null,
+        bytesDown: 0,
+        stalls: 0,
+        trippedUntil: 0,
     }));
     // Per-host routing decision, logged once on first sight so the user can SEE
     // why a hostname went DIRECT vs through a region (e.g. a CCTV video CDN that
@@ -122,6 +208,13 @@ export function startMultiExitRouter(opts) {
     let directTotal = 0;
     let lastPool = null;
     let stopped = false;
+    // Learned host→region routes: hosts the static table missed whose DIRECT
+    // route kept failing get auto-promoted into the fallback region (and
+    // persisted). Explicit domain lists always win over learned entries.
+    const learner = new RouteLearner(opts.learnedRoutesPath, log);
+    const fallbackRegion = opts.fallbackRegion
+        ?? regions.find((r) => opts.exits.some((e) => (e.region ?? "default") === r.name))?.name
+        ?? null;
     // ---- routing decision -----------------------------------------------------
     // Returns the region name a host should use, or "direct" for a direct
     // connection from this machine.
@@ -130,8 +223,43 @@ export function startMultiExitRouter(opts) {
             if (r.domains.length > 0 && hostMatches(host, r.domains))
                 return r.name;
         }
+        const l = learner.get(host);
+        if (l !== null && regionHasExits(l))
+            return l;
         return defaultRegion;
     }
+    // A bad DIRECT outcome for an unmatched host; learn it once it crosses the
+    // threshold so future requests route through the fallback region.
+    function noteDirectBad(host) {
+        if (!fallbackRegion || !regionHasExits(fallbackRegion))
+            return;
+        if (learner.recordDirectBad(host))
+            learner.learn(host, fallbackRegion);
+    }
+    // GeoIP layer: for a host the domain table and learner both miss, resolve it
+    // and — if its IP is China-allocated — route it through the fallback (China)
+    // region. Catches China-CDN hostnames no suffix list anticipates (Baidu
+    // bdydns, etc.). Returns the region to use (may be "direct").
+    const geoCn = new GeoCnClassifier();
+    async function resolveRegion(host) {
+        let region = routeFor(host); // static domains + persistent learned routes
+        if (region === "direct" && !isLocalDest(host) && fallbackRegion && regionHasExits(fallbackRegion)) {
+            // peek() is sync for IP literals / cached verdicts; classify() resolves.
+            const cn = geoCn.peek(host);
+            if (cn === true || (cn === null && await geoCn.classify(host))) {
+                if (!seenGeo.has(host)) {
+                    seenGeo.add(host);
+                    log(`geo ${host} → region [${fallbackRegion}] (resolved to a China IP)`);
+                }
+                region = fallbackRegion;
+            }
+        }
+        if (region !== "direct" && !regionHasExits(region))
+            region = "direct";
+        return region;
+    }
+    const seenGeo = new Set();
+    const seenMitm = new Set();
     // ---- health checks --------------------------------------------------------
     function probe(exit) {
         return new Promise((resolve) => {
@@ -194,13 +322,37 @@ export function startMultiExitRouter(opts) {
             await new Promise((r) => setTimeout(r, HEALTH_INTERVAL_MS));
         }
     }
+    // ---- circuit breaker ------------------------------------------------------
+    // A tunnel delivered healthy data → the exit is good; clear its stall streak
+    // and any trip.
+    function recordHealthy(exit) {
+        if (exit.stalls > 0 || exit.trippedUntil > 0) {
+            exit.stalls = 0;
+            exit.trippedUntil = 0;
+        }
+    }
+    // A tunnel established but stalled (delivered ~nothing) → count it; trip the
+    // exit out of the pool once it stalls repeatedly, so a flaky node stops
+    // getting traffic instead of stalling segments.
+    function recordStall(exit, why) {
+        exit.stalls++;
+        if (exit.stalls >= TRIP_AFTER_STALLS && exit.trippedUntil <= Date.now()) {
+            exit.trippedUntil = Date.now() + TRIP_COOLDOWN_MS;
+            exit.healthy = false;
+            log(`✗ ${exit.name} [${exit.region}] TRIPPED for ${TRIP_COOLDOWN_MS / 1000}s (${why}) — excluding from pool`);
+            printPool();
+        }
+    }
     // ---- exit selection (scoped to one region) --------------------------------
     function pickOrder(region) {
         const now = Date.now();
         // An exit is usable if the probe says healthy OR it carried a real tunnel
         // recently (live traffic beats a flapping probe).
         const isUp = (e) => e.healthy || (e.lastSuccessMs !== null && now - e.lastSuccessMs < RECENT_SUCCESS_MS);
-        const inRegion = exits.filter((e) => e.region === region);
+        // Exclude exits currently tripped by the circuit breaker (unstable: they
+        // established tunnels but stalled). A friend's laptop dropping off no longer
+        // gets segments routed to it. They rejoin automatically after the cooldown.
+        const inRegion = exits.filter((e) => e.region === region && e.trippedUntil <= now);
         const healthy = inRegion.filter(isUp);
         // Best-effort fallback: if NO exit currently passes health checks but the
         // region HAS exits, try them anyway instead of 503-ing the user. A single
@@ -209,12 +361,33 @@ export function startMultiExitRouter(opts) {
         // CONNECT tunnels keep working. The real forward() has its own timeout +
         // retry, so trying a "down" exit costs little and avoids blacking out the
         // whole region on a transient probe blip. Prefer healthy when we have them.
-        const pool = healthy.length > 0 ? healthy : inRegion;
-        if (pool.length === 0)
-            return [];
+        let pool = healthy.length > 0 ? healthy : inRegion;
+        // If EVERY exit in the region is tripped, fall back to the least-recently-
+        // tripped ones anyway rather than black-holing the region entirely.
+        if (pool.length === 0) {
+            const all = exits.filter((e) => e.region === region);
+            if (all.length === 0)
+                return [];
+            pool = [...all].sort((a, b) => a.trippedUntil - b.trippedUntil).slice(0, 1);
+        }
         if (mode === "failover")
             return pool; // priority order (input order)
-        return [...pool].sort((a, b) => a.active - b.active || a.served - b.served);
+        // Capacity-aware load-balance. Exits in one region differ wildly in real
+        // throughput (0.3 vs 2.6 Mbps observed), and HLS downloads segments
+        // sequentially — so a segment that lands on a slow exit stalls the player
+        // ("很卡"). Score each exit by its ESTIMATED AVAILABLE bandwidth right now:
+        //
+        //     score = measured_peak_bps / (active + 1)
+        //
+        // The fastest idle exit wins; as it fills with connections its score falls
+        // and traffic spills to the next-fastest — self-balancing in proportion to
+        // capacity, and steering every segment to whoever can deliver it soonest.
+        // Unmeasured exits assume the region's median (or a neutral default) so a
+        // new exit is tried but doesn't monopolize before it's proven.
+        const measuredVals = pool.map((e) => e.speedEwma).filter((v) => v !== null).sort((a, b) => a - b);
+        const medianBps = measuredVals.length > 0 ? measuredVals[Math.floor(measuredVals.length / 2)] : 2_000_000;
+        const score = (e) => (e.speedEwma ?? medianBps) / (e.active + 1);
+        return [...pool].sort((a, b) => score(b) - score(a) || a.served - b.served);
     }
     // Whether ANY exit is configured for a region (healthy or not). Lets us tell
     // "region has no exits at all → fall through" from "exits all down → 503".
@@ -225,15 +398,20 @@ export function startMultiExitRouter(opts) {
     function forward(exit, target, client, head, onFail) {
         const up = net.connect(exit.port, exit.host);
         let established = false;
-        const fail = (why) => { if (!established) {
-            up.destroy();
-            onFail(why);
-        }
-        else {
-            client.destroy();
-        } };
+        const fail = (why) => {
+            if (!established) {
+                // Couldn't even establish → an instability signal for the breaker, then
+                // fail over to the next exit.
+                recordStall(exit, why);
+                up.destroy();
+                onFail(why);
+            }
+            else {
+                client.destroy();
+            }
+        };
         up.once("connect", () => up.write(`CONNECT ${target} HTTP/1.1\r\nHost: ${target}\r\n\r\n`));
-        up.setTimeout(CONNECT_TIMEOUT_MS, () => fail("timeout"));
+        up.setTimeout(EXIT_CONNECT_TIMEOUT_MS, () => fail("timeout"));
         let buf = Buffer.alloc(0);
         const onData = (d) => {
             buf = Buffer.concat([buf, d]);
@@ -265,7 +443,50 @@ export function startMultiExitRouter(opts) {
                     client.write(rest);
                 client.pipe(up);
                 up.pipe(client);
-                const done = () => { exit.active = Math.max(0, exit.active - 1); };
+                // Passively measure peak download throughput (exit → client) to feed
+                // the quality-aware exit ordering.
+                const t0 = Date.now();
+                const meter = new RateMeter();
+                up.on("data", (d) => meter.add(d.length, Date.now()));
+                // Mid-tunnel stall watchdog: if the exit delivers no bytes for
+                // STALL_IDLE_MS while the tunnel is open, it's stalled — tear it down so
+                // the client retries elsewhere, and feed the circuit breaker. setTimeout
+                // re-arms on every I/O, so it only fires on genuine inactivity.
+                let stalledOut = false;
+                up.setTimeout(STALL_IDLE_MS, () => {
+                    if (meter.total >= STALL_MIN_BYTES) {
+                        up.setTimeout(0);
+                        return;
+                    } // real transfer, just slow
+                    stalledOut = true;
+                    up.destroy();
+                });
+                let closed = false;
+                const done = () => {
+                    if (closed)
+                        return;
+                    closed = true;
+                    exit.active = Math.max(0, exit.active - 1);
+                    const durMs = Date.now() - t0;
+                    sampleSpeed(exit, meter, durMs);
+                    // Circuit-breaker classification: a tunnel that stayed open a while but
+                    // delivered almost nothing is a stall (dead/flaky exit); a tunnel that
+                    // moved real data proves the exit is healthy.
+                    if (stalledOut || (durMs >= STALL_MIN_OPEN_MS && meter.total < STALL_MIN_BYTES)) {
+                        recordStall(exit, stalledOut ? "idle stall" : "no data");
+                    }
+                    else if (meter.total >= STALL_MIN_BYTES) {
+                        recordHealthy(exit);
+                    }
+                    // Log substantial tunnels (video segments) so we can see per-exit
+                    // speed even for opaque https streams the prefetcher can't touch.
+                    if (meter.total >= SPEED_MIN_BYTES && durMs > 0) {
+                        const mb = (meter.total / 1048576).toFixed(1);
+                        const mbps = ((meter.total * 8) / durMs / 1000).toFixed(1);
+                        const peak = ((meter.peakBps(durMs) * 8) / 1e6).toFixed(1);
+                        log(`  tunnel ${target} via ${exit.name} — ${mb}MB in ${(durMs / 1000).toFixed(1)}s = ${mbps}Mbps (peak ${peak})`);
+                    }
+                };
                 up.once("close", done);
                 client.once("close", () => up.destroy());
                 client.on("error", () => up.destroy());
@@ -279,12 +500,49 @@ export function startMultiExitRouter(opts) {
         up.on("error", () => fail("conn error"));
     }
     // Direct connection from THIS machine — for hosts that match no region so
-    // Google etc. aren't black-holed through a foreign exit.
+    // Google etc. aren't black-holed through a foreign exit. Unmatched hosts
+    // whose direct route fails are retried through the fallback region in the
+    // SAME request, and learned once they prove misclassified (the
+    // piccpndali.v.myalicdn.com case: a CDN host no suffix table anticipated).
     function directConnect(target, client, head) {
         const [host, portStr] = target.split(":");
+        const h = (host || "").toLowerCase();
+        const local = isLocalDest(h);
         const up = egressConnect(Number(portStr) || 443, host, opts.egressBindIp);
-        up.setTimeout(CONNECT_TIMEOUT_MS, () => up.destroy());
+        let established = false;
+        let failedOver = false;
+        // In-request fallback: the direct dial never came up → try the fallback
+        // region's exits before giving up (local destinations never fall back).
+        const failover = () => {
+            if (failedOver)
+                return;
+            failedOver = true;
+            if (local || !fallbackRegion) {
+                client.destroy();
+                return;
+            }
+            noteDirectBad(h);
+            const order = pickOrder(fallbackRegion);
+            if (order.length === 0) {
+                client.destroy();
+                return;
+            }
+            log(`  ${target}: direct failed, retrying via region [${fallbackRegion}]`);
+            let i = 0;
+            const tryNext = () => {
+                if (i >= order.length) {
+                    learner.unlearn(h);
+                    client.end("HTTP/1.1 502 All routes failed\r\n\r\n");
+                    return;
+                }
+                forward(order[i++], target, client, head, tryNext);
+            };
+            tryNext();
+        };
+        up.setTimeout(CONNECT_TIMEOUT_MS, () => { up.destroy(); if (!established)
+            failover(); });
         up.once("connect", () => {
+            established = true;
             up.setTimeout(0);
             directActive++;
             directTotal++;
@@ -293,12 +551,32 @@ export function startMultiExitRouter(opts) {
                 up.write(head);
             client.pipe(up);
             up.pipe(client);
-            const done = () => { directActive = Math.max(0, directActive - 1); };
+            // Outcome classification: a tunnel that dies almost immediately with
+            // almost nothing delivered looks like a geo-block RST, not a real
+            // exchange — two of those in a row and the host is learned into the
+            // fallback region for next time.
+            const t0 = Date.now();
+            let down = 0;
+            up.on("data", (d) => { down += d.length; });
+            let closed = false;
+            const done = () => {
+                if (closed)
+                    return;
+                closed = true;
+                directActive = Math.max(0, directActive - 1);
+                if (local)
+                    return;
+                if (RouteLearner.suspiciousClose(down, Date.now() - t0))
+                    noteDirectBad(h);
+                else
+                    learner.recordDirectGood(h);
+            };
             up.once("close", done);
             client.once("close", () => up.destroy());
         });
         client.on("error", () => up.destroy());
-        up.on("error", () => client.destroy());
+        up.on("error", () => { client.destroy(); if (!established)
+            failover(); });
     }
     // A destination is "local" when it should be dialed straight from this box on
     // the normal routing table — loopback, RFC1918, the agentnet 10.86/16 vIPs
@@ -327,25 +605,118 @@ export function startMultiExitRouter(opts) {
         }
         return false;
     }
+    // HTTP status codes that, on a DIRECT dial to an unmatched host, smell like a
+    // geo-block rather than a real answer (Forbidden / legal / some CDNs' region
+    // gate). Two of these in a row and the host is learned into the fallback
+    // region — the soft-failure counterpart to a connection RST.
+    const GEO_BLOCK_STATUS = new Set([403, 451]);
     // Plain-HTTP forwarding (the browser's proxy request for an `http://` URL,
     // which arrives as a normal request with an absolute-form URL — NOT a CONNECT
     // tunnel). Dial the origin directly from here and pipe the streams both ways.
-    function httpForwardDirect(host, port, path, req, res, headers) {
-        const bindIp = isLocalDest(host) ? undefined : opts.egressBindIp;
+    // On a hard failure OR a geo-block status for an unmatched host, retry the
+    // whole request through the fallback region and learn the host.
+    function httpForwardDirect(host, port, path, req, res, headers, body) {
+        const local = isLocalDest(host);
+        const bindIp = local ? undefined : opts.egressBindIp;
         directTotal++;
+        let done = false;
+        const target = `${host}:${port}`;
+        // Retry through the fallback region (only possible before we've streamed a
+        // response, and only for a non-local unmatched host we buffered the body of).
+        // Only safe to replay through an exit when the request carried no body we'd
+        // have already streamed away (GET/HEAD and friends), or its body was
+        // pre-buffered. Otherwise we'd resend an empty body — skip the retry.
+        const bodyless = ["GET", "HEAD", "DELETE", "OPTIONS"].includes((req.method || "GET").toUpperCase());
+        const viaFallback = (why) => {
+            if (done || local || res.headersSent || !fallbackRegion || !regionHasExits(fallbackRegion))
+                return false;
+            if (!bodyless && body === undefined)
+                return false;
+            done = true;
+            noteDirectBad(host);
+            const order = pickOrder(fallbackRegion);
+            if (order.length === 0)
+                return false;
+            log(`  ${target}: direct ${why}, retrying via region [${fallbackRegion}] (http)`);
+            httpForwardViaExitBuffered(order, 0, target, host, port, path, req.method || "GET", headers, body, res);
+            return true;
+        };
         const up = http.request({ host, port, path, method: req.method, headers, localAddress: bindIp }, (upRes) => {
-            res.writeHead(upRes.statusCode || 502, upRes.headers);
+            const code = upRes.statusCode || 502;
+            if (!local && GEO_BLOCK_STATUS.has(code) && viaFallback(`${code}`)) {
+                upRes.destroy();
+                return;
+            }
+            done = true;
+            learner.recordDirectGood(host);
+            res.writeHead(code, upRes.headers);
             upRes.pipe(res);
         });
         up.setTimeout(CONNECT_TIMEOUT_MS, () => up.destroy(new Error("upstream timeout")));
-        up.on("error", (e) => { if (!res.headersSent)
-            res.writeHead(502, { "content-type": "text/plain" }); res.end(`direct proxy error: ${e.message}\n`); });
-        req.pipe(up);
+        up.on("error", (e) => {
+            if (viaFallback(e.message))
+                return;
+            if (!res.headersSent)
+                res.writeHead(502, { "content-type": "text/plain" });
+            res.end(`direct proxy error: ${e.message}\n`);
+        });
+        if (body && body.length)
+            up.end(body);
+        else
+            req.pipe(up);
+    }
+    // Like httpForwardViaExit but re-sends a pre-buffered request body (used when
+    // the direct attempt already consumed the client stream before failing over).
+    function httpForwardViaExitBuffered(order, idx, target, host, port, path, method, headers, body, res) {
+        if (idx >= order.length) {
+            if (!res.headersSent)
+                res.writeHead(502, { "content-type": "text/plain" });
+            res.end("all exits failed\n");
+            return;
+        }
+        const exit = order[idx];
+        const tun = net.connect(exit.port, exit.host);
+        tun.setTimeout(EXIT_CONNECT_TIMEOUT_MS, () => tun.destroy());
+        tun.once("connect", () => { tun.setTimeout(0); tun.write(`CONNECT ${target} HTTP/1.1\r\nHost: ${target}\r\n\r\n`); });
+        let buf = Buffer.alloc(0);
+        const onHdr = (chunk) => {
+            buf = Buffer.concat([buf, chunk]);
+            const i = buf.indexOf("\r\n\r\n");
+            if (i === -1)
+                return;
+            tun.removeListener("data", onHdr);
+            const statusLine = buf.slice(0, i).toString("utf8").split("\r\n")[0] || "";
+            if (!/ 200/.test(statusLine)) {
+                tun.destroy();
+                httpForwardViaExitBuffered(order, idx + 1, target, host, port, path, method, headers, body, res);
+                return;
+            }
+            exit.lastSuccessMs = Date.now();
+            exit.fails = 0;
+            if (!exit.healthy)
+                exit.healthy = true;
+            exit.served++;
+            const leftover = buf.slice(i + 4);
+            if (leftover.length)
+                tun.unshift(leftover);
+            const up = http.request({ host, port, path, method, headers, createConnection: () => tun }, (upRes) => {
+                res.writeHead(upRes.statusCode || 502, upRes.headers);
+                upRes.pipe(res);
+            });
+            up.on("error", (e) => { if (!res.headersSent)
+                res.writeHead(502, { "content-type": "text/plain" }); res.end(`exit proxy error: ${e.message}\n`); });
+            if (body && body.length)
+                up.end(body);
+            else
+                up.end();
+        };
+        tun.on("data", onHdr);
+        tun.on("error", () => { tun.removeListener("data", onHdr); httpForwardViaExitBuffered(order, idx + 1, target, host, port, path, method, headers, body, res); });
     }
     // Plain-HTTP through an exit region: open a CONNECT tunnel to host:port via the
     // exit, then ride the normal http.request over that raw socket. Fails over to
     // the next exit if CONNECT is refused.
-    function httpForwardViaExit(order, idx, target, host, port, path, req, res, headers) {
+    function httpForwardViaExit(order, idx, target, host, port, path, req, res, headers, isTls = false) {
         if (idx >= order.length) {
             if (!res.headersSent)
                 res.writeHead(502, { "content-type": "text/plain" });
@@ -366,17 +737,28 @@ export function startMultiExitRouter(opts) {
             const statusLine = buf.slice(0, i).toString("utf8").split("\r\n")[0] || "";
             if (!/ 200/.test(statusLine)) {
                 tun.destroy();
-                httpForwardViaExit(order, idx + 1, target, host, port, path, req, res, headers);
+                httpForwardViaExit(order, idx + 1, target, host, port, path, req, res, headers, isTls);
                 return;
             }
             exit.lastSuccessMs = Date.now();
             exit.fails = 0;
             if (!exit.healthy)
                 exit.healthy = true;
+            exit.served++;
             const leftover = buf.slice(i + 4);
             if (leftover.length)
                 tun.unshift(leftover);
-            const up = http.request({ host, port, path, method: req.method, headers, createConnection: () => tun }, (upRes) => {
+            const t0 = Date.now();
+            // For an https origin (MITM path) run TLS over the tunnel to the CDN; for
+            // http, the raw tunnel carries plaintext.
+            const reqFn = isTls ? https.request : http.request;
+            const conn = isTls
+                ? () => tls.connect({ socket: tun, servername: host, rejectUnauthorized: false })
+                : () => tun;
+            const up = reqFn({ host, port, path, method: req.method, headers, createConnection: conn }, (upRes) => {
+                const meter = new RateMeter();
+                upRes.on("data", (d) => meter.add(d.length, Date.now()));
+                upRes.once("end", () => sampleSpeed(exit, meter, Date.now() - t0));
                 res.writeHead(upRes.statusCode || 502, upRes.headers);
                 upRes.pipe(res);
             });
@@ -385,7 +767,219 @@ export function startMultiExitRouter(opts) {
             req.pipe(up);
         };
         tun.on("data", onHdr);
-        tun.on("error", () => { tun.removeListener("data", onHdr); httpForwardViaExit(order, idx + 1, target, host, port, path, req, res, headers); });
+        tun.on("error", () => { tun.removeListener("data", onHdr); httpForwardViaExit(order, idx + 1, target, host, port, path, req, res, headers, isTls); });
+    }
+    // ---- HLS segment prefetch (plain-HTTP streams only) ------------------------
+    // Fetch one URL through the region's exit pool, buffered, with failover.
+    // Rotates the starting exit across calls so concurrent prefetches spread over
+    // the fast pool and aggregate its bandwidth.
+    let prefetchRR = 0;
+    function fetchViaRegionBuffered(u, extraHeaders, label) {
+        return new Promise((resolvep, rejectp) => {
+            const host = u.hostname.toLowerCase();
+            const isTls = u.protocol === "https:";
+            const port = Number(u.port) || (isTls ? 443 : 80);
+            // routeFor covers static + learned; also honor a cached GeoIP=China
+            // verdict (the playlist fetch just warmed it for this host) so segments
+            // on a geo-classified CDN ride the same region.
+            let region = routeFor(host);
+            if (region === "direct" && geoCn.peek(host) === true && fallbackRegion)
+                region = fallbackRegion;
+            if (region === "direct" || !regionHasExits(region)) {
+                rejectp(new Error("no region for host"));
+                return;
+            }
+            const base = pickOrder(region);
+            if (base.length === 0) {
+                rejectp(new Error("no healthy exit"));
+                return;
+            }
+            const start = prefetchRR++ % Math.min(3, base.length);
+            const order = [...base.slice(start), ...base.slice(0, start)];
+            const path = (u.pathname || "/") + (u.search || "");
+            const target = `${host}:${port}`;
+            const tail = (u.pathname || "/").split("/").pop() || path;
+            const tryIdx = (idx) => {
+                if (idx >= order.length) {
+                    rejectp(new Error("all exits failed"));
+                    return;
+                }
+                const exit = order[idx];
+                const tun = net.connect(exit.port, exit.host);
+                let moved = false;
+                const move = () => { if (!moved) {
+                    moved = true;
+                    tun.destroy();
+                    tryIdx(idx + 1);
+                } };
+                tun.setTimeout(EXIT_CONNECT_TIMEOUT_MS, move);
+                tun.once("connect", () => tun.write(`CONNECT ${target} HTTP/1.1\r\nHost: ${target}\r\n\r\n`));
+                tun.on("error", move);
+                let buf = Buffer.alloc(0);
+                const onHdr = (chunk) => {
+                    buf = Buffer.concat([buf, chunk]);
+                    const i = buf.indexOf("\r\n\r\n");
+                    if (i === -1)
+                        return;
+                    tun.removeListener("data", onHdr);
+                    const statusLine = buf.slice(0, i).toString("utf8").split("\r\n")[0] || "";
+                    if (!/ 200/.test(statusLine)) {
+                        move();
+                        return;
+                    }
+                    moved = true; // established — failover window is over
+                    tun.setTimeout(0);
+                    exit.lastSuccessMs = Date.now();
+                    exit.fails = 0;
+                    if (!exit.healthy)
+                        exit.healthy = true;
+                    exit.served++;
+                    const leftover = buf.slice(i + 4);
+                    if (leftover.length)
+                        tun.unshift(leftover);
+                    const t0 = Date.now();
+                    // For an https origin, run TLS over the exit tunnel so we speak
+                    // straight to the CDN (the exit only ever sees ciphertext). For http,
+                    // the raw tunnel socket carries plaintext HTTP directly.
+                    const reqFn = isTls ? https.request : http.request;
+                    const conn = isTls
+                        ? () => tls.connect({ socket: tun, servername: host, rejectUnauthorized: false })
+                        : () => tun;
+                    const up = reqFn({ host, port, path, method: "GET", headers: { ...extraHeaders, host: u.host }, createConnection: conn }, (upRes) => {
+                        const chunks = [];
+                        const meter = new RateMeter();
+                        upRes.on("data", (d) => { chunks.push(d); meter.add(d.length, Date.now()); });
+                        upRes.once("end", () => {
+                            const body = Buffer.concat(chunks);
+                            const durMs = Date.now() - t0;
+                            sampleSpeed(exit, meter, durMs);
+                            if (label) {
+                                const kb = (body.length / 1024).toFixed(0);
+                                const mbps = durMs > 0 ? ((body.length * 8) / durMs / 1000).toFixed(1) : "?";
+                                log(`  ${label} ${tail} via ${exit.name} — ${kb}KB in ${durMs}ms = ${mbps}Mbps`);
+                            }
+                            resolvep({ status: upRes.statusCode || 502, headers: upRes.headers, body });
+                        });
+                        upRes.once("error", (e) => rejectp(e));
+                    });
+                    up.setTimeout(30_000, () => up.destroy(new Error("prefetch timeout")));
+                    up.on("error", (e) => rejectp(e));
+                    up.end();
+                };
+                tun.on("data", onHdr);
+            };
+            tryIdx(0);
+        });
+    }
+    const hls = new HlsPrefetcher(fetchViaRegionBuffered);
+    let lastHlsHits = 0;
+    function bumpHlsStats() {
+        const s = hls.stats;
+        if (s.hits - lastHlsHits >= 20) {
+            lastHlsHits = s.hits;
+            log(`hls cache: ${s.hits} hits / ${s.misses} misses / ${s.entries} entries / ${(s.bytes / 1048576).toFixed(0)}MB`);
+        }
+    }
+    // Shared HLS-accelerated GET path, used by BOTH the plain-http proxy handler
+    // (http origin) and the MITM gateway (https origin). A cached segment is
+    // answered from memory; a playlist is fetched buffered so its segment list
+    // seeds the prefetcher (which pulls the upcoming segments in parallel across
+    // the exit pool); a cold segment is fetched buffered and cached; everything
+    // else streams through one exit.
+    function serveHlsAware(o) {
+        const { fullUrl, host, port, path, target, method, headers, req, res, order, isTls } = o;
+        const u = new URL(fullUrl);
+        const cacheable = method === "GET" && !headers["range"];
+        if (cacheable) {
+            const hit = hls.lookup(fullUrl);
+            if (hit) {
+                res.writeHead(200, {
+                    "content-type": hit.contentType ?? "application/octet-stream",
+                    "content-length": hit.body.length,
+                    "x-agentnet-cache": "hit",
+                });
+                res.end(hit.body);
+                bumpHlsStats();
+                return;
+            }
+            const isPlaylist = looksLikePlaylist(u.pathname || "");
+            const isSegment = looksLikeSegment(u.pathname || "");
+            if (isPlaylist || isSegment) {
+                const fwd = {};
+                for (const [k, v] of Object.entries(headers)) {
+                    if (typeof v === "string" && ["user-agent", "referer", "origin", "cookie", "authorization"].includes(k))
+                        fwd[k] = v;
+                }
+                fetchViaRegionBuffered(u, fwd, isPlaylist ? "playlist" : "segment")
+                    .then((r) => {
+                    const outHeaders = { ...r.headers };
+                    delete outHeaders["transfer-encoding"];
+                    outHeaders["content-length"] = r.body.length;
+                    res.writeHead(r.status, outHeaders);
+                    res.end(r.body);
+                    if (r.status === 200) {
+                        const ct = r.headers["content-type"];
+                        if (isPlaylist) {
+                            const text = r.body.toString("utf8");
+                            const variants = parseM3u8Variants(text, fullUrl);
+                            if (variants.length > 0) {
+                                const desc = variants.map((v) => `${v.resolution || "?"}@${(v.bandwidth / 1e6).toFixed(1)}Mbps`).join(", ");
+                                log(`  playlist ${host} is MASTER — variants: ${desc}`);
+                            }
+                            else {
+                                const segs = parseM3u8Segments(text, fullUrl);
+                                log(`  playlist ${host} is MEDIA — ${segs.length} segments, prefetching ahead`);
+                            }
+                            hls.onPlaylist(fullUrl, text);
+                        }
+                        else {
+                            hls.put(fullUrl, r.body, Array.isArray(ct) ? ct[0] : ct);
+                        }
+                    }
+                })
+                    .catch(() => {
+                    if (!res.headersSent)
+                        httpForwardViaExit(order, 0, target, host, port, path, req, res, headers, isTls);
+                    else
+                        res.destroy();
+                });
+                return;
+            }
+        }
+        httpForwardViaExit(order, 0, target, host, port, path, req, res, headers, isTls);
+    }
+    // ---- HLS aggregation gateway (selective HTTPS MITM) -----------------------
+    // Only enabled with hlsAccel + a configDir for the CA. We MITM a host only
+    // when it's routed to a region (China) AND its name looks like a video CDN —
+    // never generic HTTPS (banking, mail, APIs), which stays an opaque tunnel.
+    const VIDEO_HOST_RE = /(cctv|cntv|live|vod|hls|video|stream|liveplay|bdydns|myalicdn|volcfcdn|myqcloud|gslb|byteimg|volcfcdn|bilivideo|hdslb|ivideo|tvyun)/;
+    let mitm = null;
+    if (opts.hlsAccel && opts.configDir) {
+        mitm = new MitmGateway({
+            configDir: opts.configDir,
+            log,
+            onRequest: (req, res, host, port) => {
+                const path = req.url || "/";
+                const headers = { ...req.headers };
+                delete headers["proxy-connection"];
+                void resolveRegion(host).then((region) => {
+                    const order = region === "direct" ? [] : pickOrder(region);
+                    if (order.length === 0) {
+                        res.writeHead(502, { "content-type": "text/plain" });
+                        res.end("no exit for MITM host\n");
+                        return;
+                    }
+                    serveHlsAware({
+                        fullUrl: `https://${host}${port === 443 ? "" : `:${port}`}${path}`,
+                        host, port, path, target: `${host}:${port}`,
+                        method: req.method || "GET", headers, req, res, order, isTls: true,
+                    });
+                });
+            },
+        });
+    }
+    function shouldMitm(host, region) {
+        return mitm !== null && region !== "direct" && VIDEO_HOST_RE.test(host);
     }
     const server = http.createServer((req, res) => {
         // Browsers send proxy HTTP requests in absolute-form: `GET http://h:p/path`.
@@ -411,62 +1005,76 @@ export function startMultiExitRouter(opts) {
         // Forward the client's headers minus hop-by-hop proxy bits.
         const headers = { ...req.headers };
         delete headers["proxy-connection"];
-        let region = routeFor(host);
-        if (region !== "direct" && !regionHasExits(region))
-            region = "direct";
-        if (!seenHosts.has(host)) {
-            seenHosts.add(host);
-            log(`route ${host} → ${region === "direct" ? "DIRECT" : `region [${region}]`} (http)`);
-        }
-        if (region === "direct") {
-            httpForwardDirect(host, port, path, req, res, headers);
-            return;
-        }
-        const order = pickOrder(region);
-        if (order.length === 0) {
-            res.writeHead(503, { "content-type": "text/plain" });
-            res.end("no healthy exit for region\n");
-            return;
-        }
-        httpForwardViaExit(order, 0, target, host, port, path, req, res, headers);
+        void resolveRegion(host).then((region) => {
+            if (!seenHosts.has(host)) {
+                seenHosts.add(host);
+                log(`route ${host} → ${region === "direct" ? "DIRECT" : `region [${region}]`} (http)`);
+            }
+            if (region === "direct") {
+                httpForwardDirect(host, port, path, req, res, headers);
+                return;
+            }
+            const order = pickOrder(region);
+            if (order.length === 0) {
+                res.writeHead(503, { "content-type": "text/plain" });
+                res.end("no healthy exit for region\n");
+                return;
+            }
+            const fullUrl = `http://${host}${port === 80 ? "" : `:${port}`}${path}`;
+            serveHlsAware({ fullUrl, host, port, path, target, method: req.method || "GET", headers, req, res, order, isTls: false });
+        });
     });
     server.on("connect", (req, client, head) => {
         const target = req.url || "";
         const host = (target.split(":")[0] || "").toLowerCase();
         client.on("error", () => { });
-        let region = routeFor(host);
-        // If the chosen region has no exits configured, fall back to direct rather
-        // than 503 (a misconfigured default shouldn't black-hole everything).
-        if (region !== "direct" && !regionHasExits(region))
-            region = "direct";
-        if (!seenHosts.has(host)) {
-            seenHosts.add(host);
-            log(`route ${host} → ${region === "direct" ? "DIRECT" : `region [${region}]`}`);
-        }
-        if (region === "direct") {
-            directConnect(target, client, head);
-            return;
-        }
-        const order = pickOrder(region);
-        if (order.length === 0) {
-            // Region matched but every exit in it is down. Do NOT silently leak to
-            // direct — a .cn host would just fail from abroad, and the operator
-            // should see the region is down.
-            log(`  ${target}: region [${region}] has no healthy exit`);
-            client.end("HTTP/1.1 503 No healthy exit for region\r\n\r\n");
-            return;
-        }
-        let i = 0;
-        const tryNext = (why) => {
-            if (why)
-                log(`  ${target}: ${order[i - 1]?.name} failed (${why}), retrying`);
-            if (i >= order.length) {
-                client.end("HTTP/1.1 502 All exits failed\r\n\r\n");
+        void resolveRegion(host).then((region) => {
+            if (client.destroyed)
                 return;
+            if (!seenHosts.has(host)) {
+                seenHosts.add(host);
+                log(`route ${host} → ${region === "direct" ? "DIRECT" : `region [${region}]`}`);
             }
-            forward(order[i++], target, client, head, tryNext);
-        };
-        tryNext();
+            if (region === "direct") {
+                directConnect(target, client, head);
+                return;
+            }
+            // HLS aggregation: for a China video-CDN host (and only those), MITM the
+            // TLS so we can see and parallel-prefetch its segments across the pool.
+            // Everything else stays an opaque tunnel.
+            if (mitm && shouldMitm(host, region)) {
+                const cport = Number(target.split(":")[1]) || 443;
+                if (!seenMitm.has(host)) {
+                    seenMitm.add(host);
+                    log(`  ${host}: HLS-accel (MITM) enabled`);
+                }
+                try {
+                    mitm.handleConnect(host, cport, client, head);
+                    return;
+                }
+                catch { /* fall through to opaque tunnel on any MITM error */ }
+            }
+            const order = pickOrder(region);
+            if (order.length === 0) {
+                // Region matched but every exit in it is down. Do NOT silently leak to
+                // direct — a .cn host would just fail from abroad, and the operator
+                // should see the region is down.
+                log(`  ${target}: region [${region}] has no healthy exit`);
+                client.end("HTTP/1.1 503 No healthy exit for region\r\n\r\n");
+                return;
+            }
+            let i = 0;
+            const tryNext = (why) => {
+                if (why)
+                    log(`  ${target}: ${order[i - 1]?.name} failed (${why}), retrying`);
+                if (i >= order.length) {
+                    client.end("HTTP/1.1 502 All exits failed\r\n\r\n");
+                    return;
+                }
+                forward(order[i++], target, client, head, tryNext);
+            };
+            tryNext();
+        });
     });
     server.listen(listenPort, listenHost, () => {
         log(`Multi-exit router [${mode}] on http://${listenHost}:${listenPort}`);
@@ -479,11 +1087,18 @@ export function startMultiExitRouter(opts) {
         }
         log(`  default (unmatched hosts) → ${defaultRegion === "direct" ? "DIRECT" : `region [${defaultRegion}]`}`);
         log(`Point your browser's HTTPS proxy at ${listenHost}:${listenPort}`);
+        if (mitm) {
+            log(`HLS acceleration ON — selectively decrypting China video CDNs to parallel-prefetch across exits.`);
+            log(`  TRUST THIS CA ONCE so the browser accepts the local certs:`);
+            log(`    ${mitm.caCertPath}`);
+            log(`    macOS: sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${mitm.caCertPath}"`);
+            log(`    (or import it in the browser's certificate settings as a trusted root)`);
+        }
         void healthLoop();
     });
     if (mode === "loadbalance") {
         const reporter = setInterval(() => {
-            const parts = exits.filter((e) => e.healthy).map((e) => `${e.name}[${e.region}]: ${e.active} active / ${e.served} total`);
+            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("  |  ")}`);
         }, 15000);