rustunnel/droid-wiki/features/reconnect-and-shutdown.md

Reconnect and shutdown

The connector is designed to recover from tunnel interruptions without dropping the SOCKS5 proxy.

Purpose

Lab networks and development environments are unstable. The connector should tolerate listener restarts, network hiccups, and temporary failures without requiring manual intervention.

Reconnect behavior

run_reconnect_loop in src/tunnel.rs continuously attempts to maintain a tunnel:

1. Connect to the target address via TCP.
2. Perform TLS handshake and server certificate verification.
3. Send the HTTP auth request and wait for 200 OK.
4. On success, create a StreamMux, publish it via the watch::channel, and run the framing loop.
5. When the tunnel drops (framing task ends), log the disconnection and retry.

Backoff

• Initial delay: 1 second
• Exponential doubling up to a maximum of 30 seconds
• Auth failures are terminal (the loop exits rather than retrying with a bad token)

SOCKS5 proxy during reconnect

The SOCKS5 proxy stays bound. If a client connects while the tunnel is down, the proxy sees mux_receiver is None and rejects the connection with a warning log. Once the reconnect loop succeeds, new SOCKS5 requests work immediately.

Shutdown

Both listener and connector handle graceful shutdown:

• Unix: SIGINT or SIGTERM triggers shutdown via tokio::signal::unix.
• Windows: Ctrl+C or Ctrl+Break triggers shutdown via tokio::signal::ctrl_c.

Listener shutdown

1. The shutdown signal breaks the tokio::select! in run_listener.
2. The TCP listener is dropped, releasing the bind port.
3. The SOCKS5 proxy task (if any) is aborted.
4. Active framing sessions end when their streams close.

Connector shutdown

1. The shutdown signal breaks the tokio::select! in run_socks5_proxy.
2. The SOCKS5 listener is dropped.
3. The reconnect loop handle is aborted.
4. Existing SOCKS5 connections receive EOF when their streams close.

E2E tests e2e_graceful_shutdown_listener and e2e_graceful_shutdown_connector verify that ports are released within 3 seconds of abort.

Key source files

File	Purpose
src/tunnel.rs	run_reconnect_loop, run_socks5_proxy, run_listener, shutdown handling
src/signal.rs	Cross-platform shutdown signal future