Colitu Adaptive Connect 2.0 and Warm Spare: a technical report

#Abstract

Some networks block VPN protocols; others behave more subtly: they let the connection come up and then quietly stop the traffic a few dozen seconds later. On such a network "answers the ping" and "carries traffic" are not the same thing. This report describes the set of mechanisms the Colitu apps use against this problem, Colitu Adaptive Connect 2.0: server ranking that takes proximity and privacy into account, per-network memory kept only on the device, network hints derived from anonymous counters, a connect-time health check based on real traffic, server fallback, a warm spare kept ready inside the running connection, and a mid-session watcher that covers every transport. The evaluation was carried out on a single Android phone on a single residential Wi-Fi network in a country with active deep packet inspection (DPI), with faults injected at the server for this one client only. In the best configuration, when the main path was cut for 120 seconds, the VPN stayed on, there was no reconnect and the outage lasted about 5–10 seconds. In a 60-minute soak test with 11 faults injected on 8 servers, 98.8 % of the probes through the tunnel succeeded; when the server in use was fully cut for 101 seconds, the user saw only a stall of about 5 seconds and the VPN stayed on. Limitations and situations not yet measured are listed separately.

#1. Introduction

1. 1
   The first job of a VPN app is to connect to the right server with the right connection mode. Colitu servers offer five connection modes from four protocol families: Hysteria2 (UDP/QUIC), VLESS Reality, VLESS XHTTP, Trojan and Shadowsocks 2022 (see Technical details).
2. 2
   The classic approach ranks servers by ping and picks the fastest responder. But ping is only a hint: on some networks a server answers the ping and still carries no traffic at all.
3. 3
   There is a harder case: the connection comes up, the app says "Connected", but after a while traffic stops while the TCP connection still looks open. For the user this means the VPN is on but the internet is gone.
4. 4
   Adaptive Connect 1.x solved part of these problems, but our measurements showed two important gaps: the server list came in database-id order, and the mid-session watcher only covered Hysteria2 (see section 4).
5. 5
   The goal of Adaptive Connect 2.0 is: find a path that really works when connecting, notice a path that breaks while connected and move the user to another path, if possible without turning the VPN off, and do all this without collecting information about the user.

#3. Design

The mechanisms below were designed for the Windows, Linux, Android (including TV) and iOS apps. All mechanisms are the same in every app. The measurements in section 4 were made on one Android phone.

3.1 Server ranking

1. 1
   A location the user picked is used as is. Colitu never switches a manual choice on its own.
2. 2
   In automatic mode ("Fastest server") the order is:

1. 1
   "Recommended" in the server list always shows the server automatic mode would connect to.
2. 2
   Privacy: To order the list, the panel works out your country and your internet provider's network from the IP address of that request only. Nothing is stored. When the request comes through the VPN the panel can't know them, and the app keeps the last values it learned.

3.2 Per-network memory

1. 1
   A "network" is the connection type (Wi-Fi, mobile data, Ethernet) combined with your internet provider's network. Home Wi-Fi and mobile data are remembered separately.
2. 2
   The memory is kept only on the device:

1. 1
   Old entries are deleted; at most 200 entries are kept.
2. 2
   As a result, a mode blocked on mobile data is still tried first on home Wi-Fi.

3.3 Network hints

The memory of one device only knows that device's experience. Network hints share the experience of other devices on the same network without identifying anyone.

1. 1
   Signed network token. The panel gives the app a token containing the country and network number (ASN), signed with HMAC and valid for 48 hours.
2. 2
   Reporting. The app sends per-protocol results with this token. The request's IP address is never used for observations; while connected, that address is a VPN server anyway.
3. 3
   Anonymous hourly counters. The panel keeps only hourly counters per (country, ASN, protocol): successes, failures and the number of distinct devices. Distinct devices are counted with per-hour keyed pseudonyms that are deleted when the hour ends. The counts are kept for 7 days.
4. 4
   Thresholds. A protocol counts as "blocked on this network" when at least 5 devices tried it in the last 24 hours with a success rate below 20 %. If the network has too little data, the country level is used: at least 20 devices and below 10 % success.
5. 5
   Never all. All offered protocols are never marked blocked.
6. 6
   Use. The server list response reports the blocked protocols. The app tries them last, unless one worked on this device on this network in the last 24 hours.

3.4 Connect-time health check and the verify path

1. 1
   A mode only counts as working when real traffic flows. The check asks common connectivity-test addresses (Cloudflare, Google, Microsoft) through the tunnel, never Colitu's own servers. It takes about 4–6 seconds per mode.
2. 2
   Before a mode is marked as not working, the app checks that the device is online at all, so a dropped Wi-Fi isn't blamed on the mode.
3. 3
   Time budget: about 8 seconds per mode (start plus traffic check), about 20 seconds per server, at most about 45 seconds for a whole connect. Usually a few seconds are enough.
4. 4
   Android shows "Connected" only after the check passes; until then it shows "Checking…".
5. 5
   Verify path. Every time the core starts, a private check input reachable only from the device is added (with a random port and random credentials). The first routing rule sends it straight to the main path. The connect-time check therefore measures the main path only; a broken main path can't hide behind the spare and is avoided on the next connect.

3.5 Server fallback

1. 1
   In automatic mode, if none of a server's modes pass the health check, the app moves to the next server in the list, up to 3 servers per connect. Meanwhile "Trying another server…" is shown.
2. 2
   The failed server stays at the back for 30 minutes on that network.
3. 3
   On Windows and Linux with the kill switch on, the automatic retry moves down the list instead of retrying the same server.
4. 4
   If every mode fails on a manually chosen server, the error offers a one-tap "Try the fastest server".

3.6 Warm spare

Topology. While connected, the app keeps a second path ready inside the running connection. Traffic passes through a balancer: while the main path is healthy, everything goes over it; if the main path stops working, new traffic moves to the spare by itself. The VPN stays on and no "reconnecting" screen appears. Because the switch happens in the connection itself and not in the app screen, it also works when the app is in the background. The spare only connects when it's used.

Choosing the spare.

Modes and servers that failed on this network are never the spare.

The prefix pitfall. In Xray, balancer and observatory selectors match tags by prefix. If the spare's tag started with the same prefix as the main path's tag, the observatory would treat the spare as the main path too. The spare's tag is therefore chosen so it shares no prefix with the main path.

DNS. Queries from Xray's DNS module have an explicit rule to the balancer.

TCP user timeout. With a spare attached, TCP paths use a 10-second TCP user timeout (the concept from RFC 5482), so dead connections close instead of hanging.

Detection time and cost.

The Windows kill switch allows the spare server too; Linux adds it to its allow-list. The spare's configuration is fetched in parallel with the connect, never delays it, and is cached. Warm spare is on by default; it can be turned off in Advanced mode and is always on in Simple mode.

3.7 Mid-session watcher and the spare-aware rule

1. 1
   In Adaptive Connect 1.x the mid-session watcher only covered Hysteria2. In 2.0 every transport is watched.
2. 2
   Cadence: every 5 seconds for the first 90 seconds, then every 30 seconds. Three misses in a row while the device is online mean the main path is considered dead.
3. 3
   Spare-aware rule. With a spare attached, the watcher checks two things separately: the main path alone, and the normal path (the one the balancer uses).

1. 1
   This rule is the fix for the bug seen in experiment 1 in section 4: the old watcher restarted the connection while the spare was carrying traffic, and broke it.
2. 2
   Android and iOS reconnect by themselves after an unexpected drop (after about 2, 5 and 15 seconds, then the error is shown) and again when the network comes back. They don't after you press disconnect, sign out, or when the plan or device is paused.

3.8 Stall marks that cannot lock a network

Wrong stall marks could leave a network with no mode to try. Two rules prevent this:

1. 1
   If the marks would leave at most one of the offered transports, they are ignored for that round.
2. 2
   Marks found during a round in which everything failed last 10 minutes. The 6-hour lifetime applies only when another transport then carried traffic on the same network, that is, when the problem really was specific to that mode.

3.9 Node online reports and load

Every heartbeat, servers report the number of distinct connected users (Xray's online-user statistics and Hysteria2's online interface). The panel uses complete reports only; if a core's statistics couldn't be read, the previous value is kept. As a result full servers are no longer offered and load-based distribution uses real numbers. These reports are live on all servers.

3.10 Spare health probe and parallel connect

The following two mechanisms are in all apps; both were active in the soak test in 4.3:

1. 1
   Spare health probe. The spare path is also checked about once a minute through its own check input. A dead spare is only replaced while the tunnel is idle, never during a call.
2. 2
   Parallel connect ("happy eyeballs"). The best two candidates are checked at the same time, and the first to carry traffic wins. The idea follows the Happy Eyeballs approach of RFC 8305.

#4. Evaluation

4.1 Method

An internal tool (a fault lab) was written for this: it cuts one protocol (on all listed servers) or one whole server for one client with tagged firewall rules, removes the rules with self-deleting timers, probes the client every 5 seconds for an hour and reports the outage length per fault. In the warm spare experiments in 4.2 faults were applied one at a time; in the soak test in 4.3 the tool injected faults in random order for 60 minutes.

4.2 Results

Ranking. A server in the user's own country had the lowest ping (13–15 ms) but was correctly placed after a nearby foreign server (16–17 ms). In Adaptive Connect 1.x the list came in database-id order, and a server of about 222 ms on another continent was shown as "Recommended".

Freeze observation. On this network every TCP transport to one nearby server (VLESS Reality, VLESS XHTTP, Trojan) froze about 30–50 seconds after connecting: traffic stopped while TCP stayed open. Hysteria2 kept working. The old watcher, which only covered Hysteria2, showed "Connected" with no traffic in this case. The new all-transport watcher detected the freeze and switched transport in about 1.3 seconds.

Baseline. The released version 2.7.0 on the same network ran 100 seconds without interruption on Hysteria2.

Warm spare experiments (the main path's packets were dropped at the server for this client only):

4.3 Soak test

On 10 October 2026 a 60-minute soak test was run on the same phone and the same Wi-Fi network, with an Android build containing every 2.0 mechanism (including the spare health probe and parallel connect), in automatic mode.

1. 1
   Method. The fault lab injected 11 faults on 8 servers in random order, with 2–5 minutes between faults and each fault lasting 60–120 seconds. Two fault types were used: one protocol cut on every server for this client, and one server fully cut for this client.
2. 2
   Probe. An HTTP request through the tunnel every 5 seconds.
3. 3
   Result. 741 of 750 probes succeeded (98.8 %).

Interpretation.

1. 1
   Fault 3 is the key case: the server in use disappeared for 101 seconds; the user saw a stall of about 5 seconds and the VPN stayed on.
2. 2
   Fault 11: on this network every TCP protocol is frozen by DPI. With Hysteria2 cut everywhere no working protocol existed; traffic returned 2 seconds after the fault ended.
3. 3
   Faults on protocols and servers not in use show 0 seconds, as expected: faults elsewhere don't disturb the session.

Limits. One device, one network, one hour; the faults were injected at the server side, not by a real censorship system.

The tested mechanisms are the same in all apps (Android including TV, iOS, Windows and Linux); the measurement was made on one Android phone.

4.4 Discussion

1. 1
   Experiment 1: A warm spare alone is not enough; the watcher has to know about the spare. This experiment led to the spare-aware rule in 3.7.
2. 2
   Experiment 2: A spare on the same server is useless when the network freezes all TCP modes of that server (assumption 2). No working path existed here; the measured time is the block itself, not a delay of the mechanism.
3. 3
   Experiment 3: The "other family" rule is not right on every network. On this network the TCP family froze as a whole; picking the other family meant picking a frozen family. This experiment led to the "proven transport" rule in 3.6: a transport proven to work on this network becomes the spare on the next server.
4. 4
   Experiment 4: With a proven transport and a different server combined, cutting the main path reached the user only as a short pause.
5. 5
   Soak test: A 101-second full cut of the server in use came down to a stall of about 5 seconds; the only long outage was fault 11, when no working protocol was left.
6. 6
   Freeze observation: The gap between "Connected" and "traffic flows" is a real failure type, and watching only one transport is not enough.

4.5 Not yet measured

Switching between Wi-Fi and mobile data and measurements of iOS, Windows and Linux on real devices have not been done yet.

#5. Limitations

1. 1
   Exit rotation. This feature forces VLESS on one server and disables the warm spare. On the measured network this meant repeated freezes. This is a documented limitation.
2. 2
   Open TCP streams. During a switch to the spare, calls continue after a short glitch, and pages and messages reconnect on their own; but a large download running at that moment may restart. Truly seamless continuation of downloads is future work.
3. 3
   Single device, single network, one hour. The evaluation used one Android phone on one network, with a test of at most one hour; the faults were injected at the server side, not by a real censorship system. The results can't be generalised to other networks.
4. 4
   Stale network key. While the VPN is on, the panel can't see which network the request comes from; the app uses the last network it learned until the list is fetched again with the VPN off.
5. 5
   Online counts. Users connected through sing-box are not included in the online reports; a user connected to two servers is counted twice in the total.
6. 6
   No spare. There is no warm spare with multihop routes or on single-mode servers. sing-box can't run XHTTP.

#6. Future work: the CSL session layer

The Colitu Session Layer (CSL) is a session layer planned on top of the warm spare. The plan is a draft, and no date or result is promised.

1. 1
   What it adds. Today the warm spare moves new connections to the spare, but open downloads and calls carried over TCP can break. With CSL the app opens one session that survives even when the tunnel underneath (the carrier) changes. In the lab prototype the longest pause was 0.08–1.75 seconds, and downloads were verified to continue unbroken.
2. 2
   Its limit. A CSL session is bound to one server; the first version can't move a session to another server. CSL solves problems within the same server (switching between Wi-Fi and mobile data, a protocol being blocked, a momentary drop). If the server itself goes down, the warm spare takes over. The two don't replace each other; they work together.
3. 3
   Phases. First, real-tunnel tests (Reality, Trojan, Hysteria2) on temporary test servers with drop, blocking, network-change and load scenarios; then the server-side service, a per-server on/off flag in the panel and an emergency switch that turns all of CSL off; then Windows first, followed by Linux, Android and iOS last. The targets include a pause of no more than 2 seconds on a carrier change while a spare is ready, and at least 90 % of the speed of a direct connection.
4. 4
   UDP and calls. The first version protects TCP only; UDP (WhatsApp and Meet calls, QUIC/HTTP3) stays under the warm spare's protection as today. The next step is to carry UDP as datagrams inside the CSL session; a gap shorter than 2 seconds is expected on a carrier change. An optional "force QUIC to TCP" setting in Advanced mode is also being considered.
5. 5
   Without CSL. If the flag is off on the server, CSL doesn't answer, or it says "busy" or "refused", the client goes back to today's path within a few seconds. A session left without a carrier for more than 90 seconds is lost. A watchdog shuts down a stuck CSL client.
6. 6
   How users get it. As "Seamless session (beta)" in Advanced mode; off by default and shown only on servers with the flag on.

#7. Conclusion

The core lesson of Adaptive Connect 2.0 is that real traffic, not ping, decides whether a path works, and that this decision depends on the network. Ranking that respects proximity and privacy, network memory kept on the device, anonymous network hints and a health check that measures the main path only make it possible to find the right path. While connected, the warm spare together with a watcher that covers every transport and knows about the spare turns a cut main path into a pause of about 5–10 seconds. In the 60-minute soak test 98.8 % of the probes succeeded, and a full cut of the server in use reached the user as a stall of about 5 seconds. The evaluation is narrow; network changes and measurements on the other platforms are the next steps.

#References

1. 1
   RFC 8305, Happy Eyeballs Version 2: Better Connectivity Using Concurrency.
2. 2
   RFC 9000, QUIC: A UDP-Based Multiplexed and Secure Transport.
3. 3
   RFC 5482, TCP User Timeout Option.
4. 4
   Hysteria2 project documentation.
5. 5
   Xray-core project documentation.