rustunnel/droid-wiki/how-to-contribute/patterns-and-conventions.md

Patterns and conventions

Error handling

The project uses a layered error strategy:

• thiserror enums for domain-specific errors (TlsError, AuthError, TunnelError, HostError, Socks5Error, FrameError). These live in src/errors.rs and src/socks5.rs / src/framing.rs.
• anyhow for application-level propagation. CLI commands return anyhow::Result and main exits with process::exit(exit_code).
• All errors are designed to be actionable and fail-closed. There are no silent degradation paths to insecure modes.

Secret handling

• The Redacted wrapper in src/redact.rs must be used before logging any secret.
• Redacted::inner() and into_inner() are marked #[allow(dead_code)] to discourage use, but available for file writes.
• is_sensitive() detects PEM private key blocks. is_auth_token() detects long alphanumeric strings.
• is_connection_key() detects strings starting with rtun3..

Async patterns

• Tokio's multi-threaded runtime is used on both listener and connector sides.
• tokio::spawn is used for per-connection and per-stream tasks.
• tokio::select! with biased; prioritizes shutdown signals over new connections.
• watch::channel is used for publishing the active StreamMux to the SOCKS5 proxy (supports reconnect).
• mpsc::channel and oneshot::channel are used for stream data and CONNECT_REPLY coordination.

Constant-time comparison

Auth token comparison in src/tunnel.rs uses a manual constant-time XOR loop to prevent timing attacks:

fn constant_time_compare(a: &str, b: &str) -> bool {
    let a_bytes = a.as_bytes();
    let b_bytes = b.as_bytes();
    if a_bytes.len() != b_bytes.len() {
        return false;
    }
    let mut result: u8 = 0;
    for (x, y) in a_bytes.iter().zip(b_bytes.iter()) {
        result |= x ^ y;
    }
    result == 0
}

Frame reader partial read discipline

FrameReader in src/framing.rs never consumes bytes from the buffer until a complete frame (header + payload) is available. This prevents corruption when TCP segments arrive in arbitrary chunks.

TLS material as enum

Both ServerTlsMaterial and ClientTlsMaterial are enums with Paths and Pem variants. This lets the listener and connector accept either file paths (from CLI args) or embedded PEM strings (from connection keys).

Insecure mode

--insecure-skip-tls-verify exists for DPI/intercepted environments only. When enabled, the listener skips client certificate verification and the connector skips server certificate verification. This is logged at warn level.