[fix][client] Fix SOCKS5 HTTP proxy being silently bypassed (#25575)

[hanmz]

Motivation

PR #25575 added SOCKS5 proxy support for PulsarAdmin and PulsarClient HTTP paths. However, the proxy is silently bypassed at runtime — requests succeed with HTTP 200 but go directly to the target host without ever touching the SOCKS5 proxy.

Root cause: async-http-client 2.x's setProxyServer(ProxyType.SOCKS_V5) is broken. ChannelManager#getBootstrap composes two ChannelInitializers — the regular HTTP bootstrap handler and a SOCKS wrapper — by calling the inner handler's handlerAdded before its own initChannel. The inner handlerAdded triggers ChannelInitializer#initChannel, which removes the shared ChannelHandlerContext in its finally block. The outer initChannel (the one that would call addFirst(SOCKS_HANDLER, socksProxyHandler)) then never executes. Net effect: the SOCKS handler is never installed, and traffic goes direct.

Verified empirically against AHC 2.16.1 (used by master) with JDK 17: a local SOCKS5 server with password auth receives zero bytes while the HTTP request returns 200.

Both AsyncHttpConnector (PulsarAdmin) and HttpClient (PulsarClient) are affected.

Modifications

1. New Socks5ProxyChannelConfigurer (pulsar-client): Installs Socks5ProxyHandler directly on the Netty pipeline via setHttpAdditionalChannelInitializer, matching the approach already used by PulsarChannelInitializer#initSocks5IfConfig for binary protocol connections.

2. Handler naming: Registers the handler under the name "socks" (matching AHC's ChannelManager.SOCKS_HANDLER constant) instead of Socks5ProxyHandler.protocol() which returns "socks5" and would cause NoSuchElementException on any addAfter(SOCKS_HANDLER, ...) lookup.

3. HTTPS-over-SOCKS5 fix: Adds Socks5HandshakeAwaitHandler that defers the channel's connect promise until ProxyHandler.connectFuture() completes. Without this, AHC inserts its SslHandler on connect-promise completion (which Netty fires at TCP-connect-to-proxy time, before the SOCKS5 handshake finishes), placing TLS ahead of the proxy handler. The ClientHello then races ahead of the SOCKS5 negotiation, causing a handshake timeout.

4. Both call sites fixed: Replace broken setProxyServer calls in AsyncHttpConnector and HttpClient with the shared Socks5ProxyChannelConfigurer.

5. Test overhaul: Replace mock-only verify(builder).setProxyServer(...) tests with end-to-end tests using a real Netty SOCKS5 server (password auth, CONNECT verification, origin-server hit confirmation). Add testConfigureSocks5_pipelineIsHttpsSafe regression test that locks in the handler name and handshake barrier requirements.

6. Gradle dependency: Add explicit netty-handler-proxy, netty-codec-socks, netty-transport to pulsar-client-admin/build.gradle.kts (previously only available transitively).

Verifying this change

End-to-end verification matrix (all scenarios tested with real AHC 2.16.1):

Scenario	Before (master)	After
HTTP + SOCKS5 (AsyncHttpConnector)	❌ proxy silently bypassed	✅
HTTPS + SOCKS5 (AsyncHttpConnector)	❌ proxy silently bypassed	✅
HTTP + SOCKS5 (HttpClient)	❌ proxy silently bypassed	✅
HTTPS + SOCKS5 (HttpClient)	❌ proxy silently bypassed	✅
HTTP + SOCKS5 (anonymous, no auth)	❌ proxy silently bypassed	✅
HTTPS + SOCKS5 (anonymous, no auth)	❌ proxy silently bypassed	✅

./gradlew :pulsar-client-admin:test --tests '*AsyncHttpConnectorSocks5Test*'

Does this pull request potentially affect one of the following parts?

• Dependencies (add or upgrade a dependency)
• The public API
• The schema
• The default values of configurations
• The threading model
• The binary protocol
• The REST endpoints
• The admin CLI options
• The metrics
• Anything that affects deployment

Documentation

• doc-required
• doc-not-needed
• doc
• doc-complete

[lhotari]

Thanks for investigating the SOCKS5 behavior and adding a live proxy test. The workaround introduces an unresolved-proxy-address regression, and its rationale needs to be checked against the AHC version currently used by this branch.

CI also fails in PulsarAdminBuilderImplTest.testSocks5ProxyAddressIsConfiguredOnHttpClient, which still expects an AHC ProxyServer; please reconcile that test with the chosen approach. Failing job.

[lhotari]

[BUG] Resolve the proxy address before passing it to Netty

A caller can supply InetSocketAddress.createUnresolved("localhost", port) through either client builder. This passes that address unchanged to Socks5ProxyHandler, whose connect calls ctx.connect(proxyAddress, ...) directly; it does not resolve the proxy hostname. NIO connections therefore fail with UnresolvedAddressException. The existing AHC ProxyServer path resolves the proxy asynchronously before constructing the handler. Please preserve that resolution and cover an unresolved proxy address in the live test.

[lhotari]

[INTENT MISMATCH] Check the workaround against the current AHC version

This branch uses AHC 3.0.13, rather than the 2.16.1 cited in the description:

pulsar/gradle/libs.versions.toml

Lines 84 to 88 in 066d687

	vertx = "4.5.32"
	# Networking / HTTP
	asynchttpclient = "3.0.13"
	conscrypt = "2.6.2"
	okhttp3 = "5.5.0"

In 3.0.13, configureSocksBootstrap adds the HTTP initializer as a separate pipeline entry, avoiding the shared-context bug described here, and TLS is inserted after the SOCKS handler when ProxyServer is configured. Could you first run the live regression test with the existing setProxyServer wiring and add an actual HTTPS roundtrip? The current HTTPS test only checks handler presence/order. If the existing wiring passes, we can keep the regression coverage without adding this workaround and handshake barrier.