feat: client-side UDP socket rebind for source-port rotation by hrimfaxi · Pull Request #127 · spongebob888/shadowquic

hrimfaxi · 2026-04-21T08:27:12Z

Add periodic rebind of the underlying UDP socket via quinn::Endpoint::rebind().
The QUIC connection itself is preserved across rebinds—no reconnect, no
re-authentication, and no stream interruption. Only the local source port
is changed.

Configuration (all optional):

rebind_interval / min_rebind_interval / max_rebind_interval
Accept human-readable durations such as "30s", "5m", "1h".
When configured, a background task sleeps for a random duration inside
the range, binds a new ephemeral UDP socket, and calls
endpoint.rebind() atomically.

Other changes:

Use a single dual-stack endpoint backed by an IPv6 socket with
IPV6_V6ONLY=false, transparently handling both IPv4 and IPv6 traffic.
This removes the previous v4/v6 split and avoids address-family
mismatch when DNS result ordering changes.
init_endpoint() always tries IPv6 dual-stack first, falling back to
plain IPv4 only when dual-stack is unavailable.
resolve_addrs() now tries all resolved addresses instead of only the
first one, improving dual-stack connectivity.
Abort rebind background tasks on Drop to prevent tokio task and FD
leakage.
Add parse_duration_str() and format_duration() with unit tests for
ms/s/m/h/d suffixes and fractional values.

hrimfaxi · 2026-04-21T08:29:46Z

Client example:

outbound:
    max-rebind-interval: 2m
    min-rebind-interval: 10s
    # rebind-interval: 3m

Add periodic rebind of the underlying UDP socket via quinn::Endpoint::rebind(). The QUIC connection itself is preserved across rebinds—no reconnect, no re-authentication, and no stream interruption. Only the local source port is changed. Configuration (all optional): - rebind_interval / min_rebind_interval / max_rebind_interval Accept human-readable durations such as "30s", "5m", "1h". When configured, a background task sleeps for a random duration inside the range, binds a new ephemeral UDP socket, and calls endpoint.rebind() atomically. Other changes: - Use a single dual-stack endpoint backed by an IPv6 socket with IPV6_V6ONLY=false, transparently handling both IPv4 and IPv6 traffic. This removes the previous v4/v6 split and avoids address-family mismatch when DNS result ordering changes. - init_endpoint() always tries IPv6 dual-stack first, falling back to plain IPv4 only when dual-stack is unavailable. - resolve_addrs() now tries all resolved addresses instead of only the first one, improving dual-stack connectivity. - Abort rebind background tasks on Drop to prevent tokio task and FD leakage. - Add parse_duration_str() and format_duration() with unit tests for ms/s/m/h/d suffixes and fractional values. Signed-off-by: hrimfaxi <outmatch@gmail.com>

hrimfaxi · 2026-04-21T09:58:28Z

V2:

Use a single dual-stack endpoint backed by an IPv6 socket with
IPV6_V6ONLY=false, transparently handling both IPv4 and IPv6 traffic.
This removes the previous v4/v6 split and avoids address-family
mismatch when DNS result ordering changes.

happytrudy · 2026-04-22T12:27:04Z

What is the purpose of source port switching? Can it enhance anti-blocking capabilities?

hrimfaxi · 2026-04-22T13:01:59Z

What is the purpose of source port switching? Can it enhance anti-blocking capabilities?

Source port switching is mainly a lightweight path/flow perturbation mechanism. It may improve resistance to simple 5-tuple-based blocking, but it should not be expected to significantly strengthen anti-blocking capability against more advanced DPI systems.

spongebob888 · 2026-04-22T13:24:06Z

Isn't this client-side port hopping. Server-side port hopping is abnormal for a general website. I'd rather not implement it.

Most port hopping is implemented by simple reforwarding traffic from one port to the real quic port. This exploits the passive migration feature of QUIC, but it still can be tracked by connection ID.

This implementation is better. It uses rebind which is QUIC stack aware and internally it is implemented by active migration of QUIC feature. After changing to the new port, it instantly uses a new connection ID and can't be tracked(since connection ID negotiation is encrypted ).

From the side of an observer, it sees an QUIC connection vanlished and regard this connection from new port an unknown connection. The privacy is much better

happytrudy · 2026-04-24T23:33:51Z

My understanding is that this is a feature derived from QUIC, used solely to improve privacy. It allows setting default values for configurations that are imperceptible to the user.

happytrudy · 2026-04-24T23:40:23Z

The previous implementation involved the client periodically or randomly hopping to connect to the server port, primarily to combat QoS and enhance anti-blocking capabilities, supporting random hopping within a specified time period. However, re-establishing the connection using QUIC resulted in frequent interruptions, with the client logging a timeout. To achieve seamless switching to the new port, the design of HY2 was referenced, handling the dual-connection mode at the UDP layer. This inevitably led to a significant amount of code being written.

spongebob888 · 2026-04-26T03:18:08Z

+            format_duration(hi)
+        );
+
+        let bind_addr = "[::]:0";


it may fail if it's a ipv4-only device

spongebob888 · 2026-04-26T03:18:52Z

+            format_duration(hi)
+        );
+
+        let bind_addr = "[::]:0";


Similarly, ipv4 only device may have problem

Hardcoding "[::]:0" causes rebind failures on IPv4-only hosts. This patch tracks the address family from `init_endpoint` and ensures the background rebind task uses the correct socket type (IPv4 or IPv6) to maintain compatibility across different network environments Signed-off-by: hrimfaxi <outmatch@gmail.com>

hrimfaxi · 2026-04-26T08:03:00Z

use matching address family for QUIC rebind task

Copilot

Pull request overview

Implements client-side UDP socket rebinding to rotate the local source port while keeping existing QUIC connections alive, and adds configuration support for human-readable duration intervals.

Changes:

Add a background task that periodically binds a new UDP socket and calls Endpoint::rebind() to rotate the source port.
Move toward a single dual-stack endpoint approach and try all resolved target addresses when connecting.
Add parse_duration_str / format_duration utilities plus serde deserialization support and unit tests.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
shadowquic/tests/parse_duration.rs	Adds integration tests for duration string parsing.
shadowquic/src/sunnyquic/outbound.rs	Adds rebind background task, multi-address connect attempts, and Drop abort logic.
shadowquic/src/shadowquic/outbound.rs	Adds rebind background task, multi-address connect attempts, and Drop abort logic.
shadowquic/src/sunnyquic/iroh_wrapper/wrapper.rs	Makes Endpoint clonable to support sharing into the rebind task.
shadowquic/src/shadowquic/quinn_wrapper/wrapper.rs	Makes Endpoint clonable to support sharing into the rebind task.
shadowquic/src/config/sunnyquic.rs	Adds `rebind_interval`/min/max config fields with duration deserialization.
shadowquic/src/config/shadowquic.rs	Adds duration parse/format helpers and a custom serde deserializer for duration-ms fields.
shadowquic/Cargo.toml	Adds `rand` dependency for randomized rebind scheduling.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-26T09:48:30Z

+    impl<'de> serde::de::Visitor<'de> for OptDurationMs {
+        type Value = Option<u32>;
+        fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+            f.write_str("integer or duration string like 30s, 500ms")
+        }


deserialize_duration_ms's Visitor only implements visit_u64, visit_str, and visit_none. Some deserializers provide strings via visit_string (and integers via visit_u32/visit_i64), which would currently reject otherwise-valid config values. Add visit_string (delegate to parse_duration_str), and consider visit_u32/visit_i64 to accept integer durations consistently and reject negatives cleanly (similar to deserialize_bps).

Copilot · 2026-04-26T09:48:31Z

+                let interval_ms = {
+                    let mut rng = rand::rng();
+                    rng.random_range(lo..=hi) as u64
+                };


The rebind loop uses rand::rng() and rng.random_range(lo..=hi). These APIs don't match the standard rand Rng API (thread_rng() + gen_range), so this is likely a compile error. Use the supported RNG constructor and range method for the rand version in this workspace.

Copilot · 2026-04-26T09:48:31Z

+                sleep(Duration::from_millis(interval_ms)).await;
+
+                match tokio::net::UdpSocket::bind(bind_addr).await {
+                    Ok(tokio_socket) => match tokio_socket.into_std() {
+                        Ok(std_socket) => {


When rebinding with an IPv6 bind address, the code uses tokio::net::UdpSocket::bind("[::]:0"), but this does not ensure IPV6_V6ONLY=false. The endpoint init path explicitly sets only_v6(false) for dual-stack; after a rebind, IPv4 traffic may stop working on platforms where v6 sockets default to v6-only. Create/configure the rebind socket the same way as endpoint initialization (e.g., via socket2 + set_only_v6(false)).

Copilot · 2026-04-26T09:48:31Z

+                let (end, is_ipv6) = match self.init_endpoint(true).await {
+                    Ok(end) => (end, true),
+                    Err(_) => {
+                        let end = self
+                            .init_endpoint(false)
+                            .await
+                            .expect("error during initialize quic endpoint");
+                        (end, false)


This endpoint initialization calls init_endpoint(true) first. In the endpoint implementation, ipv6=true means “try dual-stack, else IPv6-only”, not “else IPv4-only”, so on hosts without dual-stack you can end up with an IPv6-only endpoint and fail to connect to IPv4-only servers/DNS results. If the intended fallback is IPv4, consider calling init_endpoint(false) (which still attempts dual-stack first) or making the fallback explicitly IPv4-only.

Suggested change

let (end, is_ipv6) = match self.init_endpoint(true).await {

Ok(end) => (end, true),

Err(_) => {

let end = self

.init_endpoint(false)

.await

.expect("error during initialize quic endpoint");

(end, false)

let (end, is_ipv6) = match self.init_endpoint(false).await {

Ok(end) => (end, false),

Err(_) => {

let end = self

.init_endpoint(true)

.await

.expect("error during initialize quic endpoint");

(end, true)

Copilot · 2026-04-26T09:48:31Z

+                sleep(Duration::from_millis(interval_ms)).await;
+
+                match tokio::net::UdpSocket::bind(bind_addr).await {
+                    Ok(tokio_socket) => match tokio_socket.into_std() {
+                        Ok(std_socket) => {


When rebinding with an IPv6 bind address, the code uses tokio::net::UdpSocket::bind("[::]:0"), but this does not ensure IPV6_V6ONLY=false. The endpoint init path explicitly sets only_v6(false) for dual-stack; after a rebind, IPv4 traffic may stop working on platforms where v6 sockets default to v6-only. Create/configure the rebind socket the same way as endpoint initialization (e.g., via socket2 + set_only_v6(false)).

Copilot · 2026-04-26T09:48:32Z

 console-subscriber = { version = "0.5.0", optional = true }
 serde-saphyr = "0.0.18"
 ring = "0.17.14"
+rand = "0.9.2"


rand is declared under [dependencies], but it is already present under [dev-dependencies] in this Cargo.toml. Unless you specifically need different features/versions for dev vs prod, keep a single declaration to avoid accidental version skew (move it to [dependencies] only and remove the dev-dependency entry, or vice versa).

Copilot · 2026-04-26T09:48:32Z

+                let (end, is_ipv6) = match self.init_endpoint(true).await {
+                    Ok(end) => (end, true),
+                    Err(_) => {
+                        let end = self.init_endpoint(false).await.expect("...");
+                        (end, false)


This endpoint initialization calls init_endpoint(true) first. In the endpoint implementation, ipv6=true means “try dual-stack, else IPv6-only”, not “else IPv4-only”, so on hosts without dual-stack you can end up with an IPv6-only endpoint and fail to connect to IPv4-only servers/DNS results. If the intended fallback is IPv4, consider calling init_endpoint(false) (which still attempts dual-stack first) or making the fallback explicitly IPv4-only.

Suggested change

let (end, is_ipv6) = match self.init_endpoint(true).await {

Ok(end) => (end, true),

Err(_) => {

let end = self.init_endpoint(false).await.expect("...");

(end, false)

let (end, is_ipv6) = match self.init_endpoint(false).await {

Ok(end) => (end, false),

Err(_) => {

let end = self.init_endpoint(true).await.expect("...");

(end, true)

Copilot · 2026-04-26T09:48:32Z

+        let (min_ms, max_ms) = rebind_interval?;
+        let (lo, hi) = if min_ms <= max_ms {
+            (min_ms, max_ms)
+        } else {
+            (max_ms, min_ms)


If lo is configured as 0 while hi is > 0, the random interval can be 0, causing an immediate wakeup and potentially a tight rebind loop. Consider clamping lo to 1 when hi > 0, or explicitly rejecting a 0 minimum interval.

Copilot · 2026-04-26T09:48:32Z

+        let (min_ms, max_ms) = rebind_interval?;
+        let (lo, hi) = if min_ms <= max_ms {
+            (min_ms, max_ms)
+        } else {
+            (max_ms, min_ms)


If lo is configured as 0 while hi is > 0, the random interval can be 0, causing an immediate wakeup and potentially a tight rebind loop. Consider clamping lo to 1 when hi > 0, or explicitly rejecting a 0 minimum interval.

Copilot · 2026-04-26T09:48:33Z

+                    let mut rng = rand::rng();
+                    rng.random_range(lo..=hi) as u64


The rebind loop uses rand::rng() and rng.random_range(lo..=hi). These APIs don't exist in the commonly-used rand Rng API (e.g., thread_rng() + gen_range), so this is likely a compile error or at least inconsistent with the rest of the ecosystem. Switch to the supported RNG constructor and range method for your chosen rand version.

Suggested change

let mut rng = rand::rng();

rng.random_range(lo..=hi) as u64

let mut rng = rand::thread_rng();

rand::Rng::gen_range(&mut rng, lo..=hi) as u64

- Consolidate duplicated QUIC socket rebinding implementations into a shared abstraction - Replace per-client rebind task spawning logic with a single reusable implementation - Introduce unified configuration handling for rebind intervals (min/max/default) - Move rebind task lifecycle management into RAII-based automatic cleanup - Remove manual rebind task management from both ShadowQuic and SunnyQuic clients - Simplify endpoint initialization by delegating rebinding responsibility to the shared implementation - Ensure consistent socket rebinding behavior across both QUIC stacks - Reduce code duplication and improve maintainability of endpoint management logic Signed-off-by: hrimfaxi <outmatch@gmail.com>

hrimfaxi · 2026-04-27T04:21:55Z

unify endpoint socket rebind logic across shadowquic and sunnyquic

Consolidate duplicated QUIC socket rebinding implementations into a shared abstraction
Replace per-client rebind task spawning logic with a single reusable implementation
Introduce unified configuration handling for rebind intervals (min/max/default)
Move rebind task lifecycle management into RAII-based automatic cleanup
Remove manual rebind task management from both ShadowQuic and SunnyQuic clients
Simplify endpoint initialization by delegating rebinding responsibility to the shared implementation
Ensure consistent socket rebinding behavior across both QUIC stacks
Reduce code duplication and improve maintainability of endpoint management logic

Move Rebindable, RebindConfig, and RebindEndpoint from duplicated per-wrapper modules into a single crate-level rebind module. - Delete shadowquic/src/sunnyquic/iroh_wrapper/rebind_endpoint.rs - Rename shadowquic/src/shadowquic/quinn_wrapper/rebind_endpoint.rs to shadowquic/src/rebind.rs - Update imports in outbound.rs and wrapper.rs files - Add `pub mod rebind` to lib.rs This eliminates the copy-paste duplication between quinn_wrapper and iroh_wrapper, making the rebind logic truly shared and maintainable in one place. Signed-off-by: hrimfaxi <outmatch@gmail.com>

spongebob888 · 2026-05-14T15:23:18Z

This is a big change and need some refactor work to contain protect socket on android and fw_mark in the future or any other user-defined socket options for other tools like clash-rs. I will consider refactor this

hrimfaxi force-pushed the rebind_port branch 3 times, most recently from e57d543 to cd800c6 Compare April 21, 2026 09:42

hrimfaxi force-pushed the rebind_port branch from cd800c6 to 025b2b9 Compare April 21, 2026 09:56

spongebob888 requested changes Apr 26, 2026

View reviewed changes

spongebob888 requested a review from Copilot April 26, 2026 09:42

Copilot started reviewing on behalf of spongebob888 April 26, 2026 09:43 View session

Copilot AI reviewed Apr 26, 2026

View reviewed changes

spongebob888 requested changes Apr 26, 2026

View reviewed changes

Comment thread shadowquic/src/shadowquic/outbound.rs Outdated

Conversation

hrimfaxi commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hrimfaxi commented Apr 21, 2026

Uh oh!

hrimfaxi commented Apr 21, 2026

Uh oh!

happytrudy commented Apr 22, 2026

Uh oh!

hrimfaxi commented Apr 22, 2026

Uh oh!

spongebob888 commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

happytrudy commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

happytrudy commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

spongebob888 Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

spongebob888 Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

hrimfaxi commented Apr 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hrimfaxi commented Apr 27, 2026

Uh oh!

spongebob888 commented May 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hrimfaxi commented Apr 21, 2026 •

edited

Loading

spongebob888 commented Apr 22, 2026 •

edited

Loading

happytrudy commented Apr 24, 2026 •

edited

Loading

happytrudy commented Apr 24, 2026 •

edited

Loading