[jlouvel]

Closes #1573. Based on #1578.

The Netty client only supported HTTP proxies. Some environments only provide a SOCKS proxy, such as SSH dynamic port forwarding (ssh -D) or some corporate networks.

Changes

• NettyClientHelper:

  • New connector parameters, each falling back to the JDK system property of the same purpose:

    Parameter	System property	Default
    socksProxyHost	socksProxyHost	none
    socksProxyPort	socksProxyPort	1080
    socksProxyUsername	java.net.socks.username	none
    socksProxyPassword	java.net.socks.password	none

  • Requests without an HTTP proxy for their scheme go through Netty's Socks5ProxyHandler, for both HTTP and HTTPS. The HTTP proxy takes precedence. Requests use origin-form targets, and the proxy resolves the host names (like socks5h). nonProxyHosts applies to the SOCKS proxy too, and HTTP/3 is not used through it, since QUIC would need UDP ASSOCIATE.

  • initConnection() now builds either a Socks5ProxyHandler or an HttpProxyHandler, and shares the setup from fix: send proxy credentials with the CONNECT request of HTTPS tunnels #1574: protocol handlers are added only once the proxy connection is established, and proxy failures are reported through the ready promise.

  • New public getters and Javadoc rows for the parameters.

• SocksProxyTestCase: a minimal SOCKS5 test proxy (RFC 1928 / RFC 1929). Tests cover HTTP with connection reuse, HTTPS with username/password, refused credentials (connector error), nonProxyHosts bypass, and the system properties.
• changes.md: entry under Enhancements.

netty-handler-proxy is already a dependency, and it brings netty-codec-socks, so no new library is needed. Only SOCKS5 is supported, not SOCKS4/4a.

Behavior change (accepted)

A JVM with the socksProxyHost system property set now sends the requests of the Restlet client through that SOCKS proxy, as java.net.Socket already does. Before, the Netty client ignored the property. As with the HTTP proxy, the loopback addresses bypass it unless nonProxyHosts says otherwise (see #1577).

Validation

ProxyTestCase (11 tests) and SocksProxyTestCase (5 tests) pass.

🤖 Generated with Claude Code

[jlouvel]

Full module verify passed at the top of the stack (#1580 branch, which includes this PR): 2,228 tests, 0 failures; JaCoCo checks met; SpotBugs 8 findings (threshold 9).

[Copilot]

🟡 Changes recommended

SOCKS-routed requests can leak HTTP proxy credentials to origin servers, and an empty SOCKS host incorrectly routes traffic to a loopback proxy instead of connecting directly.

2 open issues

• Prevent proxy credentials from reaching SOCKS-routed origins · New
• Treat an empty SOCKS proxy host as unconfigured · New

What changed in this PR

Adds SOCKS5 proxy support to the Netty HTTP client for environments such as SSH dynamic forwarding, while preserving HTTP proxy precedence.

Changes:

• Adds SOCKS configuration parameters, system-property fallbacks, authentication, and proxy-side hostname resolution.
• Applies proxy bypass rules to SOCKS and avoids HTTP/3 on SOCKS routes.
• Adds integration tests and a changelog entry.

File	Description
org.restlet/​src/​test/​java/​org/​restlet/​engine/​connector/​SocksProxyTestCase.java	Adds a test SOCKS5 proxy and coverage for routing, authentication, reuse, bypass, and system properties.
org.restlet/​src/​main/​java/​org/​restlet/​engine/​netty/​NettyClientHelper.java	Implements SOCKS5 configuration and connection handling for HTTP and HTTPS.
changes.md	Documents SOCKS5 support and configuration options.

_{Review effort: Balanced}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud