[lhoward]

A server answering CONNECT (RFC 9110 §9.3.6), or switching to a protocol other than WebSocket, needs the connection itself once the response head has been written. HTTPResponse.Payload offers a body or a WebSocket handler, and there is no other way to reach the socket.

This adds a payload for that:

• HTTPResponse(tunnel:) creates a response whose payload is .tunnel(any HTTPTunnelHandler).
• Once the head is written, HTTPTunnelHandler is called with the bytes the client sends and the AsyncSocket, for writing and for socket options. The bytes are the connection's buffered stream, so anything the client sent along with its request comes first.
• The connection closes when the handler returns.
• The head carries Date but neither Content-Length nor Transfer-Encoding, since a 2xx answer to CONNECT must not have them.

Our use is the ATDECC Proxy Protocol (IEEE 1722.1-2021 Annex C), which tunnels ATDECC messages over an HTTP CONNECT connection on the same port as its WebSocket variant. We'd rather serve both from one FlyingFox server than parse HTTP ourselves.

Adding a case to Payload breaks exhaustive switches over it outside the package, so this probably wants a minor version bump. HTTPEncoderTests had one, which is updated.

The handler is given the AsyncSocket itself, a wider surface than WSHandler exposes. That's deliberate: a tunnel needs socket options (send buffer, keepalive, TCP_USER_TIMEOUT) and write timeouts that only the socket can provide. If you'd rather wrap it in a narrower type, I'm happy to do that.

Tests: a new HTTPConnectionTests case checks that bytes sent with a CONNECT request reach the handler first, and that what the handler writes reaches the client. On Linux (Swift 6.4) the full suite runs 314 tests. The only failures are HTTPDecoderTests' standardizedPath and naughtyPath_IsParsed, which fail the same way on main without this change.

Happy to rename or reshape it if you'd prefer a different API.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SGwDLWKAC1NJDijG6Ss6YH

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.78%. Comparing base (e8332f9) to head (bfe01b2).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #254      +/-   ##
==========================================
+ Coverage   93.76%   93.78%   +0.02%     
==========================================
  Files          72       72              
  Lines        3866     3880      +14     
==========================================
+ Hits         3625     3639      +14     
  Misses        241      241              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[swhitty]

Thanks for this — the tunnel abstraction is great. Handing the connection over once the response head is written is the right primitive, and I'd like to move the WebSocket handler onto it in the future (an upgrade is really a tunnel with a frame codec on top).

One change I'd like before merging: rather than passing the raw AsyncSocket to the handler, could we wrap it in a small type with a minimal interface? Something like:

public struct HTTPTunnel: Sendable {
    public var bytes: some AsyncBufferedSequence<UInt8>
    public func write(_ data: Data) async throws
    public func setValue<O: SocketOption>(_ value: O.Value, for option: O) throws
}

public protocol HTTPTunnelHandler: Sendable {
    func handleTunnel(_ tunnel: HTTPTunnel) async throws
}

• The raw socket offers a second read path (socket.bytes, read(...)) that bypasses the connection's buffer, so bytes already buffered past the request can be skipped or reordered.
• If a handler calls socket.close(), the fd can be reused by the next accepted connection before HTTPServer removes and closes its own (connections are keyed by fd), so the server could close the wrong client. The connection should own closing.
• A client disconnect could simply end bytes, as HTTPRequestSequence does, rather than throw SocketError.disconnected into every handler.
• A struct can grow later (e.g. shutdownWrite(), a stop signal, the originating request) without breaking conformers.

You keep socket options through setValue(_:for:) and backpressure through the awaited write.

🤖 Claude helped with this review

[swhitty]

CONNECT targets are authority-form (host:port, RFC 9110 §9.3.6), so could this send CONNECT example:17221 HTTP/1.1 rather than CONNECT /? The test only checks the method and the bytes, so it should still pass.

The decoder currently mangles authority-form targets into request.path (e.g. example.com:443 becomes "443"). I'll follow up separately with some parsing improvements there; until then a wildcard CONNECT route matches, and the authority can be read from request.target.