socks-to-http-proxy

An executable to convert SOCKS5 proxy into HTTP proxy

About

sthp purpose is to create HTTP proxy on top of the Socks 5 Proxy

How it works

It uses hyper library HTTP proxy example and adds functionality to connect via Socks5

Compiling

Follow these instructions to compile

1. Ensure you have current version of cargo and Rust installed
2. Clone the project $ git clone https://github.com/KaranGauswami/socks-to-http-proxy.git && cd socks-to-http-proxy
3. Build the project $ cargo build --release
4. Once complete, the binary will be located at target/release/sthp

Usage

sthp -p 8080 -s 127.0.0.1:1080

This will create proxy server on 8080 and use localhost:1080 as a Socks5 Proxy

See "Advanced Usage Examples" below for authentication and domain whitelist configurations.

Advanced Usage Examples

• Require HTTP proxy auth and allow only example.com (apex + subdomains):

sthp -p 8080 -s 127.0.0.1:1080 \
  --http-basic user:pass --no-httpauth=0 \
  --allowed-domains .example.com

• Allow multiple domains (exact apex and subdomains):

sthp -p 8080 -s 127.0.0.1:1080 \
  --http-basic user:pass --no-httpauth=0 \
  --allowed-domains example.com,*.test.org

• Higher throughput (allow HTTP/1.1 keep-alive). Use with monitoring:

sthp -p 8080 -s 127.0.0.1:1080 --force-close=false

• Limit per-IP connections (e.g., 300):

sthp -p 8080 -s 127.0.0.1:1080 --conn-per-ip 300

• Auth + whitelist + per-IP limit:

sthp -p 8080 -s 127.0.0.1:1080 \
  --http-basic user:pass --no-httpauth=0 \
  --allowed-domains .example.com \
  --conn-per-ip 300

• Keep-alive + per-IP cap (throughput with guardrails):

sthp -p 8080 -s 127.0.0.1:1080 --force-close=false --conn-per-ip 300

• High-throughput with auth + whitelist + per-IP cap (keep-alive):

sthp -p 8080 -s 127.0.0.1:1080 \
  --force-close=false \
  --http-basic user:pass --no-httpauth=0 \
  --allowed-domains .example.com \
  --conn-per-ip 300

Options

There are a few options for using sthp.

Usage: sthp [OPTIONS]

Options:
  -p, --port <PORT>                        port where Http proxy should listen [default: 8080]
      --listen-ip <LISTEN_IP>              [default: 0.0.0.0]
  -u, --username <USERNAME>                Socks5 username
  -P, --password <PASSWORD>                Socks5 password
      --http-basic <USER:PASSWD>           HTTP Basic Auth
      --no-httpauth <1/0>                  Ignore HTTP Basic Auth, [default: 1]
  -s, --socks-address <SOCKS_ADDRESS>      Socks5 proxy address [default: 127.0.0.1:1080]
      --allowed-domains <ALLOWED_DOMAINS>  Comma-separated list of allowed domains (supports exact, *.domain, .domain, or *)
      --idle-timeout <IDLE_TIMEOUT>        Idle timeout in seconds for tunnel connections [default: 540]
      --force-close <FORCE_CLOSE>          Force 'Connection: close' on forwarded HTTP requests [default: true]
                                           Set to false to allow HTTP/1.1 keep-alive for higher throughput
      --conn-per-ip <CONN_PER_IP>          Maximum connections per client IP [default: 500]

  -h, --help                               Print help information
  -V, --version                            Print version information

Performance & Stability Recommendations

• Default for production: keep --force-close=true (historical default; now configurable). This forces Connection: close on forwarded HTTP requests and helps prevent lingering sockets/CLOSE_WAIT buildup. It slightly reduces throughput for large non-CONNECT HTTP transfers but yields more predictable resource usage.

• When to consider --force-close=false: in trusted, well-behaved upstream environments where you want higher throughput via HTTP/1.1 keep-alive. Monitor connection counts and memory closely; revert to true if you observe resource pressure.

• Pair with --conn-per-ip to bound per-client impact during spikes; start with 500 and tune based on upstream capacity and concurrency patterns.

• CONNECT (HTTPS tunneling) is unaffected by --force-close and will remain stable with the existing idle timeout.

• Keep the idle timeout (--idle-timeout, default 540s) aligned with your operational requirements. Lower it to reclaim idle tunnels more aggressively in resource-constrained environments.

Examples

• Production (recommended):

sthp -p 8080 -s 127.0.0.1:1080 --force-close=true

• Higher throughput experiment (only if you can tolerate longer-lived HTTP/1.1 connections):

sthp -p 8080 -s 127.0.0.1:1080 --force-close=false

HTTP Proxy Authentication

• Configure credentials with --http-basic <USER:PASSWD>.
• Control whether authentication is enforced with --no-httpauth <1/0> (default: 1, meaning HTTP auth is ignored/disabled). Set to 0 to require authentication.
• Behavior when authentication is required (--no-httpauth=0):
  • Missing or incorrect Proxy-Authorization header results in 407 Proxy Authentication Required and includes Proxy-Authenticate: Basic realm="proxy".

Examples

• Require authentication:

sthp -p 8080 -s 127.0.0.1:1080 --http-basic user:pass --no-httpauth=0

• Client usage with curl:

curl -x http://127.0.0.1:8080 --proxy-user user:pass http://example.com/
# or explicitly set header
curl -x http://127.0.0.1:8080 -H "Proxy-Authorization: Basic $(printf 'user:pass' | base64)" http://example.com/

Allowed Domains (Whitelist)

Use --allowed-domains with a comma-separated list. Supported patterns:

• example.com — exact match of the apex only
• *.example.com — any subdomain of example.com (a.example.com, a.b.example.com), not the apex
• .example.com — apex and any subdomain (example.com, a.example.com)
• * — allow all domains

Note: The whitelist is applied to both normal HTTP requests and CONNECT tunnels. Matching is based on the request Host only.

Examples

# Allow only example.com and its subdomains
sthp -p 8080 -s 127.0.0.1:1080 --allowed-domains .example.com

# Allow multiple domains
sthp -p 8080 -s 127.0.0.1:1080 --allowed-domains example.com,*.test.org

# Allow all (not recommended unless you trust the environment)
sthp -p 8080 -s 127.0.0.1:1080 --allowed-domains "*"

Connection Management

• --force-close (default: true): Forces Connection: close on forwarded HTTP (non-CONNECT) requests. This has been the historical default; the flag simply makes it configurable. It favors stability and resource predictability over maximum throughput.
• --idle-timeout (default: 540s): Applies to CONNECT tunnels. The idle timer resets on traffic; when no bytes flow in either direction for the timeout window, the tunnel is closed.
• --conn-per-ip (default: 500): Enforces a per-client IP cap. New connections beyond the cap are immediately closed on accept.

Recommendations:

• Keep --force-close=true in production unless you have measured benefits and sufficient headroom to allow keep-alive.
• Tune --idle-timeout according to workload (shorter for highly ephemeral tunnels, longer for long-lived ones).
• Adjust --conn-per-ip to reflect your multi-tenant policy and upstream capacity.

Log Level Control

sthp uses structured logging with different levels to help you monitor and debug the proxy. By default, it runs at warn level for optimal performance in production environments.

Log Levels

• error: Only critical errors that may cause service interruption
• warn: Warnings including connection errors, timeouts, and important status changes (default)
• info: General information including service startup, high connection counts, and large file transfers
• debug: Detailed debugging information including all connections and data transfers

Usage Examples

Default (warn level) - Recommended for production:

sthp -p 8080 -s 127.0.0.1:1080

Enable debug logging for troubleshooting:

RUST_LOG=sthp=debug sthp -p 8080 -s 127.0.0.1:1080

Show only errors:

RUST_LOG=sthp=error sthp -p 8080 -s 127.0.0.1:1080

Enable info level logging:

RUST_LOG=sthp=info sthp -p 8080 -s 127.0.0.1:1080

Advanced logging configuration:

# Enable debug for sthp but warn for other crates
RUST_LOG=sthp=debug,warn sthp -p 8080 -s 127.0.0.1:1080

# Log to file
RUST_LOG=sthp=info sthp -p 8080 -s 127.0.0.1:1080 > proxy.log 2>&1

Performance Impact

• warn/error: Minimal performance impact, recommended for production
• info: Slight performance impact, good for monitoring
• debug: Noticeable performance impact, use only for troubleshooting

What Gets Logged at Each Level

Error Level:

• Service startup failures
• Critical connection limits reached
• Severe system errors

Warn Level (Default):

• Connection errors and timeouts
• SOCKS5 authentication failures
• Domain access violations
• I/O errors during data transfer

Info Level:

• Service startup information
• Connection count warnings
• Large file transfer completions (>10MB)
• System status updates

Debug Level:

• Individual connection details
• Request/response timing
• Detailed error traces
• Connection lifecycle events

Troubleshooting

• Getting 407 Proxy Authentication Required:
  • If you configured credentials, ensure --no-httpauth=0 and the client sends Proxy-Authorization: Basic <base64(user:pass)>.
  • With curl: curl -x http://127.0.0.1:8080 --proxy-user user:pass http://example.com/
• Request blocked or 403 due to domain whitelist:
  • Verify --allowed-domains patterns. Use .example.com for apex+subdomains, *.example.com for subdomains only, example.com for apex only, or * to allow all.
  • Matching is based on the HTTP Host (for CONNECT, the target host).
• Connection closes immediately on accept:
  • Per-IP limit reached. Increase --conn-per-ip or reduce client concurrency. See warn logs for IP counts.
• Long-lived or stuck connections consuming resources:
  • Prefer --force-close=true (default) for non-CONNECT requests. For CONNECT tunnels, tune --idle-timeout.
• Bind error / port already in use:
  • Choose a different port with -p <PORT> or adjust --listen-ip.
• Need more details to diagnose:
  • Temporarily increase log verbosity:
    • Unix-like: RUST_LOG=sthp=debug sthp -p 8080 -s 127.0.0.1:1080
    • Windows PowerShell: $env:RUST_LOG="sthp=debug"; sthp -p 8080 -s 127.0.0.1:1080
  • Lower overhead alternative: sthp=info
  • Save to file: RUST_LOG=sthp=info sthp -p 8080 -s 127.0.0.1:1080 > proxy.log 2>&1