feat(event): client-side SOCKS5 proxy support at the io layer

[ithewei]

What

Adds client-side proxy support at the io layer, hooked into hio_connect(), so any client built on it (TcpClient, HttpClient, ...) can connect through a proxy. The framework is protocol-tagged (proxy_protocol_e); SOCKS5 (RFC 1928 + RFC 1929 username/password auth) is the first and currently only implemented protocol.

Only the client side (dial out through a proxy) is added; the server side stays an example (examples/socks5_proxy_server.c), since a proxy server is an application, not an io capability.

Design

The socket is created for the proxy address, so hio_connect() dials the proxy directly (a single socket, no fd recreation). The proxy handshake then runs before the connection is handed to the upper layer — mirroring how SSL is done at the io layer:

create socket [proxy] -> TCP connect [proxy]
                      -> proxy handshake (SOCKS5 CONNECT to target)
                      -> (optional) TLS handshake against the target -> connect_cb

• event/hloop.h: proxy_protocol_e { NONE, SOCKS5 } + proxy_setting_t { protocol, proxy_host, proxy_port, target_host, target_port, username, password }. The setting carries the final target the proxy should CONNECT to plus optional credentials.
• event/socks5.{h,c}: internal proxy_conn_t runtime state (copied setting + fragmentation-safe read accumulator) + SOCKS5 request builders. Target is sent as ATYP=domain for hostnames, ATYP=ipv4/ipv6 for IP literals.
• event/nio.c: socks5_handshake state machine (method negotiation → [user/pass auth] → CONNECT <target>:<port> → reply), driven non-blockingly via hio_add, exactly like ssl_client_handshake (raw recv into an internal buffer; never touches io->read_cb). proxy_handshake_start() dispatches by protocol. Handshake sends use a dedicated raw send() (no upper-layer write_cb, no hssl_write on a not-yet-created SSL handle). TLS SNI falls back to proxy_setting.target_host when the socket is the proxy.
• event/hevent.{h,c}: io->proxy field, hio_set_proxy(io, setting) (copies the setting, validates the protocol), init/cleanup.
• evpp/Channel.h, evpp/TcpClient.h: setProxy(proxy_setting_t*). TcpClient::createsocket() is called with the proxy address; the normal (async-DNS) connect path resolves and dials the proxy, and the target is delivered via setProxy.

API

// C — create the socket for the PROXY, then set the target + auth:
hio_t* io = hio_create_socket(loop, proxy_host, proxy_port, HIO_TYPE_TCP, HIO_CLIENT_SIDE);
proxy_setting_t s;
memset(&s, 0, sizeof(s));
s.protocol = PROXY_PROTOCOL_SOCKS5;
strcpy(s.target_host, "target.example.com"); s.target_port = 1234;
// optional: strcpy(s.username, ...); strcpy(s.password, ...);
hio_set_proxy(io, &s);          // before hio_connect
hio_connect(io);

// C++ — createsocket(PROXY), setProxy(target):
proxy_setting_t s;
strcpy(s.target_host, "target.example.com"); s.target_port = 1234;
tcpClient.createsocket(1080, "127.0.0.1");   // proxy
tcpClient.setProxy(&s);

Scope / platform

• Protocol: SOCKS5 only (proxy_protocol_e leaves room for more).
• Auth: no-auth + username/password (RFC 1929). No GSSAPI.
• Covered by epoll / kqueue / wepoll (all use nio.c). The legacy IOCP backend (overlapio.c) is not wired — it is no longer maintained and superseded by wepoll on Windows.

Testing

• make libhv ✅, make socks5_client_test ✅.
• End-to-end against libhv's own socks5_proxy_server and a fragmenting fake proxy (2-byte replies split byte-by-byte with delay):
  • IPv4 target (ATYP=1) → echo round-trips ✅
  • hostname target (localhost, resolved by the proxy, ATYP=domain) → ✅
  • username/password auth proxy → ✅
  • fragmented method/auth replies → ✅ (no data loss; no onWriteComplete before onConnection)

Docs / examples

• examples/socks5_client_test.c (pure C, io layer), docs/cn/socks5.md, build wiring for Makefile/CMake/Bazel.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved critical and moderate issues affect backend support, address-family handling, buffer safety, API correctness, and build integration.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 4 · 2 · 1

Open (7)

• Handle unsupported SOCKS5 behavior on the IOCP backend · New
• Prevent overflow with maximum-length credentials · New
• Use the proxy address family for the socket · New
• Initialize SOCKS5 credentials safely for C callers · New
• Register the example in CMake and Bazel · New
• Select socket family from the proxy address · New
• Expose the new method on the Channel base class · New

What changed in this PR

Adds client-side SOCKS5 proxy support at the io layer, including authentication, C++ APIs, documentation, and an example.

Changes:

• Implements nonblocking SOCKS5 negotiation and CONNECT handshakes.
• Integrates proxy configuration with C and C++ clients.
• Adds public headers, build metadata, documentation, and an example.

File	Summary
Makefile.vars	Registers the SOCKS5 header.
Makefile	Adds the client example target.
examples/​socks5_client_test.cpp	Demonstrates proxied TCP connections.
evpp/​TcpClient.h	Adds proxy configuration and hostname handling.
evpp/​Channel.h	Exposes the SOCKS5 setter.
event/​socks5.h	Defines SOCKS5 configuration and helpers.
event/​socks5.c	Builds SOCKS5 protocol messages.
event/​nio.c	Implements the nonblocking handshake.
event/​hloop.h	Declares the C proxy API.
event/​hevent.h	Adds per-connection proxy state.
event/​hevent.c	Manages proxy state lifecycle.
docs/​cn/​socks5.md	Documents configuration and usage.
cmake/​vars.cmake	Registers the public header for CMake.
BUILD.bazel	Registers the public header for Bazel.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved handshake, socket-management, backend, DNS, and build-integration issues remain.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 3 · 3 · 1

Open (7)

• Resize the IO table before attaching descriptors · New
• Initialize SOCKS5 credentials safely for C callers
• Handle unsupported SOCKS5 behavior on the IOCP backend
• Avoid blocking proxy DNS resolution on the event loop · New
• Select socket family from the proxy address
• Register the example in CMake and Bazel
• Remove duplicate nested configuration code block · New

Resolved since last review (3)

• Use the proxy address family for the socket
• Prevent overflow with maximum-length credentials
• Expose the new method on the Channel base class

Previously missed (4)

In code that hasn't changed since last review

Handle partial nonblocking SOCKS5 writes

event/​nio.c:261

send() on a nonblocking socket may write fewer than n bytes or return EAGAIN; treating any short write as a handshake failure can reject valid connections under backpressure. Queue/retain the unsent bytes and resume on HV_WRITE rather than requiring one complete write.

This issue also appears in the following locations of the same file:

• line 287
• line 305

Buffer fragmented SOCKS5 method replies

event/​nio.c:268

A TCP read is not guaranteed to return both bytes of this SOCKS5 method reply. If the proxy fragments the reply, this consumes the first byte and the n < 2 check closes a valid connection instead of waiting for the remaining byte. Accumulate the fixed-length reply (and preserve partial bytes) before parsing it.

This issue also appears on line 294 of the same file.

Validate the RFC 1929 reply version

event/​nio.c:297

RFC 1929 requires the subnegotiation reply version to be 0x01, but this check validates only the status byte. A malformed or incompatible proxy returning another version with status 0 would be accepted and the client would continue parsing the stream as SOCKS5.

Preserve the original hostname for proxy resolution

event/​nio.c:619

For a raw hio_create_socket(loop, "hostname", ...) client, the original hostname is not stored in hio_t; only the synchronously resolved peer address is retained. Unless the caller separately calls hio_set_hostname, this fallback sends the resolved IP to the proxy, so the proxy does not perform the documented proxy-side hostname resolution. Preserve the original host or make that requirement explicit.

[Copilot]

Copilot review overview

🟡 Changes recommended

The SOCKS5 handshake write path has a critical runtime issue, with additional protocol, target-host, and build/documentation problems unresolved.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 4 · 3 · 1

Open (8)

• Use raw handshake writes before starting TLS · New
• Resize the IO table before attaching descriptors
• Initialize SOCKS5 credentials safely for C callers
• Handle unsupported SOCKS5 behavior on the IOCP backend
• Avoid blocking proxy DNS resolution on the event loop
• Select socket family from the proxy address
• Register the example in CMake and Bazel
• Remove duplicate nested configuration code block

Previously missed (1)

In code that hasn't changed since last review

Preserve proxy target hostname separately from SNI

event/​nio.c:655

io->hostname is the SNI field, not a guaranteed copy of the original connect target. In particular, hio_create_socket() resolves a hostname and stores only the resulting peer address, so a generic C client using hio_create_socket(loop, "name", ...) still performs local DNS and this fallback sends the resolved IP instead of an ATYP=domain request; a caller that sets a custom SNI can also make the proxy connect to the wrong host. Preserve the target hostname separately (or add an explicit target-host API) rather than reusing the SNI field.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved handshake, write-safety, hostname, descriptor, and documentation/example issues remain.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 4 · 4

Open (8)

• Prevent application writes during SOCKS5 negotiation · New
• Resize the IO table before attaching descriptors
• Initialize SOCKS5 credentials safely for C callers
• Handle unsupported SOCKS5 behavior on the IOCP backend
• Example fails to preserve hostname for SOCKS5 requests · New
• Avoid blocking proxy DNS resolution on the event loop
• Select socket family from the proxy address
• Register the example in CMake and Bazel

Resolved since last review (2)

• Use raw handshake writes before starting TLS
• Remove duplicate nested configuration code block

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved critical and moderate issues remain in hostname handling, handshake writes, socket preservation, and protocol validation.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 5 · 3

Open (8)

• Reject overlong hostnames instead of silently truncating · New
• Prevent application writes during SOCKS5 negotiation
• Resize the IO table before attaching descriptors
• Initialize SOCKS5 credentials safely for C callers
• Handle unsupported SOCKS5 behavior on the IOCP backend
• Avoid blocking proxy DNS resolution on the event loop
• Select socket family from the proxy address
• Register the example in CMake and Bazel

Resolved since last review (1)

• Example fails to preserve hostname for SOCKS5 requests

Previously missed (2)

In code that hasn't changed since last review

Handle partial and blocked nonblocking handshake writes

event/​nio.c:285

A nonblocking send() is allowed to return a short count (or EAGAIN), even for these small messages. Treating any result other than len as fatal can send a partial method/auth/CONNECT request and close otherwise valid connections under a constrained send buffer or transient backpressure. Track the unsent handshake bytes and resume on HV_WRITE, or use an equivalent nonblocking write path that preserves handshake ordering.

This issue also appears on line 327 of the same file.

SOCKS5 uses resolved address instead of original hostname

event/​nio.c:674

When the caller uses the low-level API as documented (hio_create_socket(loop, "example.com", ...) followed by hio_set_socks5), hio_create_socket has already resolved the name and does not populate io->hostname. This fallback therefore sends the resolved numeric address instead of the original domain, so the proxy does not perform the promised proxy-side DNS resolution. Preserve the original host for SOCKS5 or explicitly require hio_set_hostname before hio_connect and update the public API documentation to match.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Unresolved moderate issues remain in transport support, handshake robustness, backend behavior, and socket handling.

Review effort: Lite
Findings: 5 · 3

Open (8)

• Reject overlong hostnames instead of silently truncating
• Prevent application writes during SOCKS5 negotiation
• Resize the IO table before attaching descriptors
• Initialize SOCKS5 credentials safely for C callers
• Handle unsupported SOCKS5 behavior on the IOCP backend
• Avoid blocking proxy DNS resolution on the event loop
• Select socket family from the proxy address
• Register the example in CMake and Bazel

Previously missed (1)

In code that hasn't changed since last review

Handle partial nonblocking SOCKS5 handshake writes

event/​nio.c:285

Because this is a nonblocking socket, send() is allowed to return EAGAIN or fewer than len bytes even for these small messages. Treating any short write as fatal can abort valid connections (especially with a full send buffer or maximum-length credentials); retain the unwritten bytes and resume the handshake on HV_WRITE without replacing its read callback.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved moderate issues affect backend support, protocol validation, nonblocking writes, hostname bounds, and IO-array safety.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 5 · 3 · 1

Open (9)

• Reject overlong hostnames instead of silently truncating
• Prevent application writes during SOCKS5 negotiation
• Resize the IO table before attaching descriptors
• Initialize SOCKS5 credentials safely for C callers
• Handle unsupported SOCKS5 behavior on the IOCP backend
• Avoid blocking proxy DNS resolution on the event loop
• Select socket family from the proxy address
• Register the example in CMake and Bazel
• Document domain and numeric SOCKS5 target encoding · New

Previously missed (3)

In code that hasn't changed since last review

SOCKS5 settings ignored by legacy EVENT_IOCP backend

event/​hevent.c:508

This setter succeeds on every backend, but overlapio.c's hio_connect() never consumes io->socks5; builds selecting the legacy EVENT_IOCP backend therefore silently connect without the requested proxy (and hostname targets may use the placeholder address). Since WITH_WEPOLL=OFF still permits this backend, reject the feature there or propagate an unsupported-backend error instead of returning success.

Handle partial and interrupted nonblocking handshake sends

event/​nio.c:285

send() on this nonblocking socket may return a short count, EAGAIN, or EINTR; treating every result other than exactly len as fatal can abort otherwise valid proxy connections under backpressure or a signal. Keep the unsent handshake bytes and resume on HV_WRITE (without invoking the upper-layer write callback) before advancing the handshake state.

Validate SOCKS5 authentication reply version

event/​nio.c:329

RFC 1929 replies include a version byte, but this branch only checks the status and accepts a malformed response with any buf[0]. Validate buf[0] == SOCKS5_AUTH_VERSION as well before proceeding to CONNECT.

[Copilot]

Copilot review overview

🟡 Changes recommended

Critical connection-routing and IOCP issues, plus additional handshake, SNI, API, and HTTP integration problems remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 7 · 3 · 2

Open (12)

• IOCP exposes raw proxy connections without SOCKS5 handshake · New
• Numeric targets reuse a pre-created direct connection · New
• Failed proxy lookup can reuse the target address · New
• Reject overlong hostnames instead of silently truncating
• Prevent application writes during SOCKS5 negotiation
• Initialize SOCKS5 credentials safely for C callers
• Handle unsupported SOCKS5 behavior on the IOCP backend
• Proxy connections omit TLS SNI for target hosts · New
• Avoid blocking proxy DNS resolution on the event loop
• Register the example in CMake and Bazel
• Implemented proxy API does not match the promised public API · New
• Document domain and numeric SOCKS5 target encoding

Resolved since last review (2)

• Resize the IO table before attaching descriptors
• Select socket family from the proxy address

[Copilot]

Copilot review overview

🔵 Needs a closer look

Resolve the public API mismatch, unsupported IOCP path, handshake timeout/validation issues, and nonblocking short-write handling.

Review effort: Lite
Findings: 4 · 2 · 1

Open (7)

• IOCP exposes raw proxy connections without SOCKS5 handshake
• Prevent application writes during SOCKS5 negotiation
• Initialize SOCKS5 credentials safely for C callers
• Handle unsupported SOCKS5 behavior on the IOCP backend
• Proxy connections omit TLS SNI for target hosts
• Register the example in CMake and Bazel
• Implemented proxy API does not match the promised public API

Resolved since last review (5)

• Failed proxy lookup can reuse the target address
• Numeric targets reuse a pre-created direct connection
• Reject overlong hostnames instead of silently truncating
• Avoid blocking proxy DNS resolution on the event loop
• Document domain and numeric SOCKS5 target encoding

Previously missed (3)

In code that hasn't changed since last review

Nonblocking proxy writes mishandle short sends

event/​nio.c:290

send() on this nonblocking socket is allowed to return a short count or EAGAIN, especially for the up-to-513-byte username/password request. Treating every result other than exactly len as fatal can reject valid connections under a small send buffer or transient backpressure; retain the unsent bytes and resume on writability instead.

Missing timeout for asynchronous SOCKS handshake

event/​nio.c:439

When the underlying nonblocking connect() returns 0, hio_connect() schedules nio_connect_async() without creating the connect timer. This branch then starts an asynchronous SOCKS handshake, so a proxy that accepts TCP but never replies leaves the connection open indefinitely despite connect_timeout; start/retain a timeout for the proxy handshake on this path.

TcpClient SOCKS5 API name and type mismatch

evpp/​TcpClient.h:375

The PR API specifies TcpClient::setSocks5Proxy(socks5_setting_t*), but this change exposes setProxy(proxy_setting_t*) instead. Code using the promised method/type will not compile, and the docs/examples now describe a different API; please keep the public name and setting type consistent across the implementation, headers, and description.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Unresolved API inconsistencies, IOCP bypass, handshake handling and validation defects, and a hanging example block approval.

Review effort: Lite
Findings: 4 · 2 · 1

Open (7)

• IOCP exposes raw proxy connections without SOCKS5 handshake
• Prevent application writes during SOCKS5 negotiation
• Initialize SOCKS5 credentials safely for C callers
• Handle unsupported SOCKS5 behavior on the IOCP backend
• Proxy connections omit TLS SNI for target hosts
• Register the example in CMake and Bazel
• Implemented proxy API does not match the promised public API

Previously missed (1)

In code that hasn't changed since last review

Nonblocking SOCKS5 handshake mishandles partial writes

event/​nio.c:294

This uses a raw send() on a nonblocking socket and treats any short write or EAGAIN as a fatal SOCKS5 failure. Nonblocking TCP sends are allowed to write only part of the request (the username/password request can be over 500 bytes), so valid proxy connections can fail under buffer pressure; retain the unwritten handshake bytes and resume on HV_WRITE instead of closing.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Unresolved proxy-handshake, unsupported-backend, API, and validation issues remain.

Review effort: Lite
Findings: 4 · 2 · 1

Open (7)

• IOCP exposes raw proxy connections without SOCKS5 handshake
• Prevent application writes during SOCKS5 negotiation
• Initialize SOCKS5 credentials safely for C callers
• Handle unsupported SOCKS5 behavior on the IOCP backend
• Proxy connections omit TLS SNI for target hosts
• Register the example in CMake and Bazel
• Implemented proxy API does not match the promised public API

Previously missed (2)

In code that hasn't changed since last review

Proxy handshake mishandles partial and interrupted sends

event/​nio.c:295

send() on a nonblocking stream may return a short count, EAGAIN, or EINTR; treating every result other than exactly len as fatal can close an otherwise valid proxy connection during method/auth/CONNECT negotiation under backpressure. Preserve the unsent suffix and wait for HV_WRITE (or otherwise complete the raw send) before advancing the handshake.

TcpClient ignores unsupported proxy configuration failures

evpp/​TcpClient.h:260

TcpClient::setProxy accepts any protocol, but SocketChannel::setProxy/hio_set_proxy can reject it (for example PROXY_PROTOCOL_NONE), and this return value is ignored. The client then proceeds to connect to remote_host—which is the proxy address—and invokes onConnection as if the target tunnel were established. Propagate or handle the failure before starting the connection.