Repository navigation
Proposal: optional Hysteria 2 transport support — macOS/iOS prototype and benchmarks #2946
OskarEichler
started this conversation in
Ideas
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Hi,
Alongside the TCP relay work we’ve been discussing, we’ve built working macOS and iOS prototypes that add Hysteria 2 as an optional Outline transport.
The results are promising: our installed Mac client reduced a browsing workload by approximately 30% and improved download throughput by approximately 20%. Separate server-to-server experiments showed substantially larger gains for suitable parallel workloads.
On a personal note, we’ve also been using the Hysteria build day to day for the past few days. It has felt noticeably faster and has been reliable in our everyday use. That is a personal observation, separate from the controlled measurements below and not a long-term stability claim.
I’d appreciate your thoughts on whether this would fit upstream and where you would prefer the integration boundary.
Implementation
The integration preserves existing Shadowsocks connections and access keys. Hysteria runs as an additional service alongside the existing Outline server, so ordinary Outline clients continue connecting as before.
The client currently provides:
The installed Mac and iOS clients use one persistent Hysteria session. The four-session pool described below was a separate experiment.
1. Installed Mac VPN: real browsing and downloads
Both transport configurations used the same client and Singapore exit server. We ran six rounds with all six connection orders, equal 20-second warmups and disposable browser profiles. Downloaded files were verified by SHA-256.
Values are medians; MB/s means decimal megabytes per second.
The primed browser-cache case slightly favored Outline: 0.290 s versus 0.342 s. The advantage therefore depended on the workload.
An earlier separate browser-proxy prototype, rather than the installed system-wide VPN, also showed:
Those earlier tests used three rotated rounds. Four sessions did not consistently outperform one on the Mac, which is why the installed client currently uses one persistent session.
2. Server-to-server: sustained throughput and controlled HTTP workloads
These tests ran entirely between our existing cloud instances, excluding the Mac, Wi-Fi and local access network.
In the quiet rerun, each sustained test received the same 32 MiB warmup, then ran four concurrent downloads for 45 seconds. The primary throughput metric covered seconds 15–45, with three trials and rotating configuration order.
On Frankfurt → Singapore, median sustained aggregate throughput was:
For this route and workload, four-session Hysteria achieved 4.19× Outline’s throughput and 1.59× WireGuard’s.
The controlled page workload also showed a substantial connection-setup benefit. For a fresh HTTP/2 page with HTML plus 48 assets across 13 application connections, Frankfurt → Singapore completion time fell from 4.818 seconds with Outline to 1.690 seconds with four-session Hysteria plus Fast Open, approximately 65% shorter.
Across the three tested directions, adding Fast Open to the four-session pool reduced fresh multi-origin HTTP/2 completion time by 24–32% compared with the same pool without Fast Open.
These results have important boundaries:
3. Physical iPhone: browsing and downloads
We also tested the installed prototype against official Outline using the same phone, Wi-Fi and Singapore exit server.
Medians from two passes per mode, each containing three workload cycles:
The prototype also contains local TCP/relay changes, so these figures compare complete clients rather than isolating Hysteria alone. Concurrent requests may share connections through HTTP multiplexing.
For all these experiments, results describe the tested implementations, routes and workloads. They do not establish a universal protocol ranking. We can provide sanitized measurement scripts and results.
Suggested upstream structure
I suggest separating the contribution into:
outline-sdkor in a separate adapter package, depending on your dependency policy.The existing TCP relay fixes would remain independent contributions. Multi-session pooling could also remain a follow-up, after the basic transport integration is reviewed.
Scope and remaining work
Hysteria introduces a substantial QUIC dependency and requires UDP reachability. Fast Open defers destination connection confirmation, so its error semantics need explicit handling. Our prototype includes a small Hysteria-core adaptation for TCP half-close support; we would aim to resolve that upstream rather than maintain a permanently vendored core.
Runtime validation currently covers macOS and iOS. Broader platform coverage, restrictive-network behavior, roaming and prolonged background operation need further validation. I’d propose introducing this as an optional experimental transport.
Would you be open to this direction? In particular, would you prefer the reusable adapter in
outline-sdk, withinoutline-apps, or in a separate package implementing the SDK interfaces?Once we agree on that boundary, we can prepare a focused contribution.
All reactions