Feature Proposal: SOCKS5 Proxy Authentication

[o-nnerb]

Overview

RequestDL's Proxy property already supports SOCKS5 (Proxy(host:port:connection:.socks)), but its documentation carries a warning: "SOCKS currently not available with authorization." This proposal tracks closing that gap — letting Proxy accept connection: .socks together with authorization:, the same way it already can for HTTP proxies.

Status: 🚫 blocked upstream, two packages deep

This isn't a RequestDL implementation gap — it's inherited, and traced to two independent upstream limitations:

1. swift-nio-extras's NIOSOCKS module never implemented RFC 1929. AuthenticationMethod already models the .usernamePassword (0x02) method identifier as a constant, but ClientStateMachine hard-stops with precondition(method == .noneRequired, "No authentication mechanism is supported. Use .noneRequired only.") — the identifier is recognized, nothing acts on it.
2. async-http-client's HTTPClient.Configuration.Proxy has no slot for SOCKS credentials. Its .socks case carries no auth payload at all, and the authorization setter has a literal precondition(self.type == .http(...), "SOCKS authorization support is not yet implemented.") — this is the exact source of RequestDL's own warning.

Proposed path forward

Two upstream proposals have been drafted (living in this repo, not yet filed against the upstream projects):

• NIOSOCKS: add the RFC 1929 sub-negotiation (new message pair mirroring the existing ClientGreeting/SelectedAuthenticationMethod pattern, a new client-state-machine state entered only when the server selects .usernamePassword), replacing the current hard-stop with real handling.
• async-http-client: give HTTPClient.Configuration.Proxy's .socks case a credentials payload (a new SOCKSAuthorization type, deliberately separate from HTTPClient.Authorization since a SOCKS5 sub-negotiation isn't an HTTP header), a source-compatible socksServer(host:port:authorization:) overload, and wiring through the existing SOCKSEventsHandler/connection-pool bootstrap.

The async-http-client piece is blocked on the NIOSOCKS piece landing first — there's nothing to call into otherwise.

RequestDL-side plan, once both land

Proxy (Properties/Sources/Session/Proxy/Proxy.swift) gets a third initializer (or the existing ones relaxed) accepting connection: .socks + authorization: together, and the "SOCKS currently not available with authorization" doc warning gets removed. Internals.Proxy.Authorization gains a SOCKS-specific case — just username/password, not the existing .basic/.basicRawCredentials/.bearer HTTP-auth-header shapes, which don't apply to a SOCKS sub-negotiation.

Out of scope

• GSSAPI (RFC 1961) — more complex, not commonly needed; username/password covers the typical case.
• SOCKS4/SOCKS4a — both upstream packages are SOCKS5-only today; unchanged by this proposal.

Milestone: TBD — depends on external project timelines outside this repo's control.