Feature Proposal: Proxy CONNECT Headers

[o-nnerb]

Overview

async-http-client merged connectHeaders support for HTTP proxies in PR #912, released in 1.36.0 — already the version this package pins (Package.swift: from: "1.30.2", Package.resolved currently locked to 1.36.0), so nothing upstream is blocking this. HTTPClient.Configuration.Proxy now carries a connectHeaders: HTTPHeaders property: extra headers sent only on the CONNECT request used to establish the tunnel through an HTTP proxy (e.g. X-Proxy-Token for caller attribution), never on the actual request the tunnel then carries. host and proxy-authorization stay reserved — upstream always sets/overrides those two regardless of what's passed — and duplicate values under the same name are preserved on the wire. SOCKS proxies have no CONNECT phase, so the option doesn't apply there; upstream's own .socksServer(host:port:) factory has no connectHeaders parameter at all.

RequestDL's Proxy property (Properties/Sources/Session/Proxy/Proxy.swift) has no way to reach this today — Internals.Proxy.build() (Internals/Sources/Session/Proxy/Internals.Proxy.swift) only ever calls .server(host:port:), .server(host:port:authorization:), or .socksServer(host:port:), none of which touch connectHeaders.

API

Add connectHeaders as a trailing, defaulted parameter to the existing authorization initializer — the one already implicitly HTTP-only (it hardcodes connectionProtocol = .http, same constraint connectHeaders needs):

public init(
    host: String,
    port: Int,
    authorization: Authorization,
    connectHeaders: HTTPHeaders = [:]
)

Plus a second, auth-less overload for the "headers without proxy credentials" case:

public init(
    host: String,
    port: Int,
    connectHeaders: HTTPHeaders
)

Both source-compatible additions — no existing call site changes shape. Uses RequestDL's own public HTTPHeaders (Tasks/Sources/Raw Task/Upload/Models/HTTPHeaders.swift): already ExpressibleByDictionaryLiteral, already preserves repeated values under the same name (matches the upstream test asserting X-Proxy-Token added twice), already has build() -> NIOHTTP1.HTTPHeaders.

DataTask {
    BaseURL("example.com")
    Proxy(
        host: "proxy.example.com",
        port: 8080,
        connectHeaders: ["X-Proxy-Token": "abc123"]
    )
}

The existing init(host:port:connection:) (the one that accepts .socks) stays untouched — connectHeaders is deliberately only reachable from the HTTP-only initializers, mirroring upstream's own split between .server(...) and .socksServer(...).

Wiring

• Internals.Proxy gains a connectHeaders: RequestDL.HTTPHeaders field (default [:]), read only by the .http branch of build():

  case .http:
      return .server(
          host: host,
          port: port,
          authorization: authorization?.build(),
          connectHeaders: connectHeaders.build()
      )

• Proxy.Node / Proxy._makeProperty thread connectHeaders straight through, same shape authorization already has.

Out of scope (v1)

• No SOCKS connectHeaders — no CONNECT phase to attach them to; upstream doesn't offer it either.
• No host/proxy-authorization override validation on RequestDL's side — upstream already silently drops those two reserved names itself (HTTP1ProxyConnectHandler.reservedConnectHeaders), so duplicating the check here would just be dead code.
• No SystemProxy integration — SystemProxy.swift resolves proxy settings from the OS and has no per-proxy custom-header source to draw from; unaffected by this proposal.

Milestone: 4.1.0

[o-nnerb]

Implementado em #281 — Proxy(host:port:authorization:connectHeaders:) com connectHeaders como Property, mesmo padrão do Form. PR aberto, revisão ainda em andamento, mas a implementação já reflete a proposta. Fechando como resolvido.