Feature Proposal: WebSocket Support

[o-nnerb]

Overview

Does WebSocket fit RequestDL? The handshake half does — it's an HTTP/1.1 Upgrade request that can reuse RequestDL's existing declarative BaseURL/Headers/session/TLS/proxy configuration. The connection-lifecycle half (a long-lived, bidirectional message stream) doesn't fit the existing Property/RequestTask.result() one-shot request/response model at all, and — more importantly — can't be built cleanly without duplicating infrastructure AsyncHTTPClient already owns.

Status: 🚫 blocked upstream

Same shape of gap as #191 (Network Capabilities) and the SOCKS Authentication proposal, confirmed directly rather than assumed:

• AsyncHTTPClient has zero WebSocket support today — nothing in its source references it.
• swift-nio's own NIOWebSocketClient/NIOWebSocketServer aren't reusable libraries — they're .executableTarget demo programs in swift-nio's own repo, not exposed as library products. Only the low-level NIOWebSocket frame codec is actually importable.
• The connection a WebSocket upgrade needs to reuse — pooling, TLS, proxy (including SOCKS), DNS override, bootstrap construction — is all owned internally by AsyncHTTPClient's HTTPConnectionPool+Factory.swift. A downstream package (RequestDL or otherwise) attempting this would have to open an independent NIO connection and re-implement that whole configuration surface to get parity — not "building on top of AsyncHTTPClient," duplicating it.
• HTTPClient.execute(request:delegate:)'s delegate model has no channel-hijack hook — no supported way to say "repurpose this connection's channel for something else" once a response starts.

Proposed path forward

A design doc has been drafted (living in this repo, not yet filed against the upstream project): async-http-client/WEBSOCKET-PROPOSAL.md. Summary: a new HTTPClient.executeWebSocketUpgrade(request:configuration:) async throws -> WebSocket API, reusing the exact same pooled-connection path ordinary requests already go through, swapping the channel's pipeline from HTTP/1 framing to NIOWebSocket framing after a 101 Switching Protocols response — implemented inside the same HTTPConnectionPool+Factory.swift bootstrap construction that already handles TLS/proxy/SOCKS today. Scoped to HTTP/1.1 only (not RFC 8441's HTTP/2 WebSocket, not permessage-deflate compression) for v1.

RequestDL-side plan, once it lands

Internals.Client calls the new upgrade API on the same pooled HTTPClient instance it already manages via Internals.ClientManager — no separate connection-management path needed. A new public WebSocketTask, built from existing Property types the same declarative way every other task is, wraps the result. This is a genuinely different task shape from DataTask/DownloadTask/UploadTask — an open, bidirectional message stream rather than a one-shot resolve-and-return — but RequestDL already has precedent for tasks with different result shapes (UploadTask's step-based AsyncResponse vs. DataTask's simple TaskResult).

Out of scope

• WebSocket server support — irrelevant to an HTTP client library.
• HTTP/2-based WebSocket (RFC 8441) — a different upgrade mechanism, left for later if there's real demand.
• Per-message compression (RFC 7692) — real, but not required for a functioning v1.

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

[o-nnerb]

Related option worth noting: vapor/websocket-kit

Not proposing this as the chosen path, just flagging it as prior art since it's directly relevant to the "duplicating infrastructure" concern above.

vapor/websocket-kit is a maintained, NIO-only WebSocket client library (depends only on swift-nio/swift-nio-ssl/swift-nio-extras/swift-nio-transport-services/swift-atomics — no AsyncHTTPClient). It already does the HTTP/1.1 Upgrade handshake via NIOWebSocketClientUpgrader, with its own TLS setup and HTTP CONNECT-proxy tunneling for both ws/wss, and picks NIOTransportServices automatically on Apple platforms.

It's essentially the "duplicated infrastructure" this proposal is trying to avoid writing from scratch — except already written and maintained upstream by Vapor. If RequestDL ever wanted a WebSocketTask without waiting on AsyncHTTPClient's executeWebSocketUpgrade, wrapping WebSocketClient.connect is one way to get there sooner.

Trade-offs that would need weighing, not glossed over:

• Connections wouldn't go through Internals.ClientManager's pooled HTTPClient — a second, unpooled connection path alongside the existing one.
• Its proxy support is HTTP CONNECT only — no SOCKS, so it doesn't close the gap from the SOCKS Authentication proposal.
• TLS/proxy config would need its own mapping from Property types, separate from however AsyncHTTPClient's config is mapped today.

Leaving this here as a documented alternative for whoever revisits this, not as a recommendation over the upstream executeWebSocketUpgrade path.