Balancer: pick outbounds by real client-side throughput, not only by probe RTT

[markov12]

Problem

Current balancer strategies (leastPing, leastLoad, random, roundRobin) and observatory / burstObservatory judge an outbound only by the RTT of a tiny probe request (e.g. generate_204). This misses the most common real-world failure: partial degradation. The path to a server shrinks to ~1 Mbit/s (ISP shaping, congested uplink, UDP loss), the 204 still arrives in 100–300 ms, the outbound is "alive and fast", and the user sits on it with frozen video.

Real case (our service, Sep 2026): a user on a leastPing balancer watched short videos; the selected server kept answering probes every minute, but throughput collapsed. The balancer never switched. Diagnosis showed UDP buffer drops on the server (~1–5%) — RTT looked fine, bandwidth did not.

A second issue: leastPing sends every client to the geographically closest server, which is often the one with the weakest channel (in our case 14–84 Mbit/s vs 250 Mbit/s on another location). Nearest ≠ fastest.

Related: #3186, #3299, #5908, sing-box#4397 (same idea for URLTest, no response yet).

Proposal

Add an optional throughput probe to the observatory and use it in the balancer.

1. burstObservatory.pingConfig (or a sibling throughputConfig):

   "throughputConfig": {
     "destination": "https://<per-outbound URL>/probe-1m",
     "size": "1MB",
     "interval": "5m",
     "onlyTop": 3,
     "minMbps": 5
   }

   • Downloads a small object through each outbound and records Mbit/s.
   • Runs rarely and only for the top-N candidates by RTT → a few MB per hour, acceptable on mobile.
   • The goal is a threshold ("is it enough for video?"), not a precise speed test, so 0.5–1 MB is enough to tell 1 Mbit/s from normal.
   • Destination may be per-outbound (served by the server itself), so the measured path is exactly client → server.

2. Passive signal for the active outbound: Xray already counts bytes per outbound. If throughput on the active outbound drops sharply while there is demand (open connections waiting for data), trigger an immediate re-probe of the candidates instead of waiting for the next interval.

3. Strategy (new option on leastLoad, or a new bestThroughput strategy):

   • filter: alive, RTT < maxRTT, failure rate < tolerance (existing);
   • filter: measured throughput ≥ minMbps;
   • rank among the rest (optionally by server-reported headroom, see below);
   • pick randomly among near-equal candidates, so clients do not all land on one server.

4. Optional server hint (backward compatible): if the probe response contains a header like X-Headroom-Mbps: 480, use it as a ranking weight. Absolute free bandwidth, not percent: a 200 Mbit/s server with 100 free is worse than a 1 Gbit/s server with 500 free. Servers that send nothing are treated as unknown/neutral — everything works as today.

5. Optional: on switch, close existing connections through the degraded outbound (like sing-box interrupt_exist_connections), otherwise they stay stuck until connIdle.

Compatibility

All options are opt-in; with no new fields behaviour is unchanged. No protocol changes, works with any outbound type.

We can implement it and test on our servers if the direction is acceptable. Which shape do maintainers prefer: extend leastLoad or a separate strategy?

[saspol]

You can easily replace observatory / burstObservatory with your own type of testing. Just use Claude Code/Codex, it takes just few minutes.