WebSocket support to the HTTP server

[mob-connection]

Opening this issue to discuss adding WebSocket support to HTTP Server, and what the best API shape for it should be: a method on RequestContext to opt into the upgrade, a dedicated handler type, reusing the existing upgrade path, or something else — and whether the handler gets raw WebSocketFrames or a higher-level message API.

[0xTim]

Big +1 to this, it's a big missing piece for the library. The main challenges are creating the API that works for all the use cases (people using it directly, being used from libraries) and not exposing NIO types on the API, both of which are achievable. For some inspiration there's swift-websocket which is what Hummingbird uses in this package, or Vapor's wrapper https://github.com/vapor/websocket-kit. I don't think we need to expose such a complex API as Hummingbird/Vapor, it should be a similar level to the rest of the HTTP server APIs

[FranzBusch]

@aryan-25 is currently looking at Connect-UDP and has some ideas how to model connection upgrade. @aryan-25 would be great if you can share your thoughts on how web socket upgrades could be modeled

[mob-connection]

Introduction

This proposal adds server-side WebSocket support to NIOHTTPServer. It accepts the Upgrade handshake over HTTP/1.1 (for both ws:// and, under TLS, wss://) and then exchanges WebSocket messages through a message-oriented, structured-concurrency API built on top of swift-nio's NIOWebSocket.

Motivation

NIOHTTPServer handles HTTP/1.1, HTTP/2, HTTP/3 request/response traffic but has no way to serve WebSocket connections. WebSocket is the de-facto standard for bidirectional, low-latency communication (chat, live updates, streaming telemetry, collaborative editing).

Today users who need WebSocket must either adopt another framework (vapor/websocket-kit, hummingbird-websocket) or hand-assemble the upgrade and framing on a raw NIO channel — for example, manually detecting the Upgrade: websocket header, computing Sec-WebSocket-Accept, mutating the pipeline, and driving WebSocketFrame encode/decode plus ping/pong/close bookkeeping. Both undermine the goal of using a single, first-party HTTP server.

NIOWebSocket already provides the low-level primitives (frame codecs, NIOTypedWebSocketServerUpgrader, NIOWebSocketFrameAggregator). The missing piece is an integration that fits NIOHTTPServer's existing configuration and structured-concurrency model.

Proposed solution

WebSocket support is opt-in via a new webSocket field on NIOHTTPServerConfiguration. Its primary decision closure, shouldUpgrade, inspects a request and returns a WebSocketUpgrade—the response headers plus the handler that will drive the upgraded session—or nil to decline. The returned WebSocketUpgrade is retained by the runtime during the handshake and its handler is invoked once the upgrade completes. Shared settings (frame-size limits) live alongside it in the configuration.

Because the decision closure receives the request and returns the handler, routing lives in user code: the server intentionally provides no built-in router. A switch on request.path is enough to serve multiple independent WebSocket endpoints, and higher-level frameworks remain free to build richer routing abstractions on top.

var configuration = try NIOHTTPServerConfiguration(
    bindTarget: .hostAndPort(host: "127.0.0.1", port: 8080),
    supportedHTTPVersions: [.http1_1],
    transportSecurity: .plaintext
)

configuration.webSocket = .init(
    shouldUpgrade: { request in
        switch request.path {
        case "/echo":
            return WebSocketUpgrade { inbound, outbound, context in
                for try await message in inbound {
                    try await outbound.write(message)   // echo text/binary
                }
            }
        case "/clock":
            return WebSocketUpgrade { inbound, outbound, context in
                // a different endpoint, its own handler
            }
        default:
            return nil                                   // decline → regular HTTP
        }
    }
)

let server = NIOHTTPServer(logger: logger, configuration: configuration)
try await server.serve { _, _, _, responseSender in
    // Non-WebSocket requests (and declined upgrades) are served here as usual.
}

Compared with the workarounds, the handshake, fragment reassembly, and control-frame handling (ping/pong/close) are all handled by the server; user code sees only reassembled text/binary messages and writes messages back. This is cleaner (no raw-frame bookkeeping), safer (server frames are never masked, close is idempotent), and consistent with the rest of the server's structured-concurrency API.

Detailed design

Public API

extension NIOHTTPServerConfiguration {
    /// Enables WebSocket upgrades on HTTP/1.1 connections when set.
    public struct WebSocket: Sendable {
        /// Maximum size, in bytes, of a single incoming frame. Default: 1 << 14.
        public var maxFrameSize: Int
        /// Maximum number of fragments reassembled into one message. Default: 16.
        public var maxAccumulatedFrameCount: Int
        /// Maximum reassembled message size, in bytes. Default: 1 << 20.
        public var maxAccumulatedFrameSize: Int

        /// Decides whether a request is upgraded and, if so, which handler drives the
        /// session. Return a `WebSocketUpgrade` to accept (routing to the matched
        /// endpoint), or `nil` to decline — the request then falls through to the
        /// normal request handler.
        public var shouldUpgrade: @Sendable (HTTPRequest) async throws -> WebSocketUpgrade?

        public init(
            maxFrameSize: Int = 1 << 14,
            maxAccumulatedFrameCount: Int = 16,
            maxAccumulatedFrameSize: Int = 1 << 20,
            shouldUpgrade: @escaping @Sendable (HTTPRequest) async throws -> WebSocketUpgrade?
        )
    }

    /// WebSocket configuration. Default `nil` — no upgrades offered.
    public var webSocket: WebSocket?
}

/// Accepts a WebSocket upgrade: the response headers plus the session handler. Returned per request
/// from `shouldUpgrade`, so routing (and hence multiple endpoints) is expressed in user code.
public struct WebSocketUpgrade: Sendable {
    public var additionalResponseHeaders: HTTPFields   // e.g. a negotiated Sec-WebSocket-Protocol

    /// Drives the upgraded session. When it returns or throws, the server sends a close frame
    /// (if none was sent) and tears down the connection.
    public var onUpgrade: @Sendable (
        _ inbound: WebSocketInboundStream,
        _ outbound: WebSocketOutboundWriter,
        _ context: NIOHTTPServer.WebSocketContext
    ) async throws -> Void

    public init(
        additionalResponseHeaders: HTTPFields = [:],
        onUpgrade: @escaping @Sendable (
            WebSocketInboundStream, WebSocketOutboundWriter, NIOHTTPServer.WebSocketContext
        ) async throws -> Void
    )
}

/// A fully-reassembled inbound data message. Control frames are never delivered here.
public enum WebSocketMessage: Sendable, Equatable {
    case text(String)
    case binary([UInt8])
}

/// Inbound messages. Fragments are reassembled; `ping`→`pong` and `close` echo are
/// handled while iterating, so only text/binary messages are yielded.
public struct WebSocketInboundStream: AsyncSequence, Sendable {
    public typealias Element = WebSocketMessage
}

/// Writes messages and control frames. Never masks outbound frames.
public struct WebSocketOutboundWriter: Sendable {
    public func write(_ message: WebSocketMessage) async throws
    public func write(text: String) async throws
    public func write(binary: [UInt8]) async throws
    public func ping(_ payload: [UInt8]) async throws
    public func pong(_ payload: [UInt8]) async throws
    /// Idempotent: only the first close on a connection is written.
    public func close(code: WebSocketCloseCode, reason: String?) async throws
}

/// Close status code.
public struct WebSocketCloseCode: Sendable, Hashable {
    public let code: UInt16
    public static let normalClosure: Self
    public static let goingAway: Self
    public static let protocolError: Self
    public static let unacceptableData: Self
    public static let dataInconsistentWithMessage: Self
    public static let policyViolation: Self
    public static let messageTooLarge: Self
    public static let unexpectedServerError: Self
    public static func code(_ value: UInt16) -> Self
}

extension NIOHTTPServer {
    /// Connection-scoped context handed to a WebSocket handler after upgrade.
    public struct WebSocketContext: Sendable {
        public let request: HTTPRequest
        public let logger: Logger
        public let remoteAddress: NIOHTTPServer.SocketAddress?
        public let localAddress: NIOHTTPServer.SocketAddress?
    }
}

The public surface deliberately exposes no NIOWebSocket or NIOCore types (no WebSocketFrame, no ByteBuffer): messages are String/[UInt8] and close codes are a dedicated type. This matches the module's existing style ([UInt8]/UniqueArray rather than ByteBuffer) and keeps NIOWebSocket an internal implementation detail (the package builds with InternalImportsByDefault).

Behavior

• Inbound — WebSocketInboundStream yields only text and binary messages. Fragmented data frames are reassembled by NIOWebSocketFrameAggregator before delivery. Control frames are handled transparently while iterating: ping is answered with a matching pong, pong is ignored, and a close frame is echoed back and ends the sequence.
• Outbound — the writer never masks frames. close is idempotent, so it is safe for both user code and the runtime to request a close.
• Teardown — when onUpgrade returns or throws, the runtime sends a close frame if the closing handshake has not already been started, then tears the connection down.

Implementation

The HTTP/1.1 pipeline is configured through configureUpgradableHTTPServerPipeline with a NIOTypedWebSocketServerUpgrader. Because an upgrade replaces the channel's inbound/outbound element types (HTTP parts become WebSocket frames), the outcome of an HTTP/1.1 connection is modeled internally as a union:

enum HTTP1ConnectionChannel: Sendable {
    case http(NIOAsyncChannel<HTTPRequestPart, HTTPResponsePart>)
    case webSocket(NIOAsyncChannel<WebSocketFrame, WebSocketFrame>, HTTPRequest, WebSocketSessionHandler)
}

Both the plaintext and secure (ALPN → http/1.1) serving paths thread this value and dispatch on it: .http runs the existing connection/request loop unchanged; .webSocket runs a session driver that invokes the chosen handler. The upgrader's shouldUpgrade callback bridges NIO's event-loop HTTPRequestHead to HTTPRequest (via NIOHTTPTypesHTTP1) so user code sees swift-http-types, calls the configuration's shouldUpgrade, and — on acceptance — stashes the returned WebSocketUpgrade's handler in a per-connection box that the upgrade-pipeline callback reads back into the .webSocket case (both callbacks run on the same event loop). This allows each upgraded connection to carry the handler selected for its matched route. When configuration.webSocket == nil, the upgrade handler is not added to the pipeline, leaving the existing HTTP/1.1 path byte-for-byte unchanged.

WebSocket upgrades are performed over HTTP/1.1 only; connections negotiated as HTTP/2 are never upgraded (WebSocket over HTTP/2, HTTP/3, is a future direction).

Maturity Justification

Proposed at Sandbox. The feature is new, ships within an early-stage package, and parts of its public API shape are still open for community feedback (e.g. whether to add a raw-frame escape hatch alongside the message-oriented API). It has comprehensive end-to-end test coverage, with a real server and NIO WebSocket client exercising successful upgrades, text and binary message exchange, the close handshake, rejected-upgrade fall-through, and the unchanged existing test suite. However, it has not yet seen production use. Sandbox reflects that state while signalling the intended direction.

Alternatives considered

• A single fixed shouldUpgrade (returning headers) plus a single onUpgrade, both in the configuration. This was the first shape. It cannot serve more than one endpoint: there is one handler for the whole server. Replacing it with a decision closure that returns the per-request WebSocketUpgrade (headers + handler) keeps configuration as the single entry point while letting routing live in user code — the change adopted here.
• Initiating the upgrade from the request handler (e.g. responseSender.upgradeToWebSocket { … }). The most router-friendly ergonomics, but it requires performing the upgrade after the request handler runs — swapping the pipeline and re-wrapping an already-active NIOAsyncChannel as WebSocket frames. That works against NIO's typed-upgrade model (which decides upgrades during pipeline configuration) and complicates channel ownership after the request handler has already begun executing. The decision-returns-handler shape gets the same routing flexibility while keeping the upgrade at handshake time.
• Exposing a raw WebSocketFrame API instead of WebSocketMessage. More flexible, but leaks NIOWebSocket/ByteBuffer into the public API and pushes fragment reassembly and control-frame handling onto users. A raw-frame escape hatch could be added later.

[adam-fowler]

API Pattern looked pretty good. It is not dissimilar to HB 🤣 .

• Regarding WebSocketMessage I've found sometimes when writing Strings to a WebSocket my source was binary eg a Valkey GET call and I had to do an unnecessary conversion to String which was then converted back to binary buffer on actual write. Is it worthwhile looking into allowing for WebSocketMessage.text holding binary data but adding a static func text(_ string: String) -> Self?

• Any thoughts on serving WebSockets over H2?

This isn't really relevant to the API discussion but we also need to support upgrade requests on connections that have been used to serve other HTTP content. Safari started doing this a while back. I had to write a hack to get around it as currently there is no support for this. The hack was if I receive an upgrade request on a connection that had already served HTTP content I returned a re-direct to the same endpoint and closed the connection.

[FranzBusch]

var configuration = try NIOHTTPServerConfiguration(
bindTarget: .hostAndPort(host: "127.0.0.1", port: 8080),
supportedHTTPVersions: [.http1_1],
transportSecurity: .plaintext
)

configuration.webSocket = .init(
shouldUpgrade: { request in
switch request.path {
case "/echo":
return WebSocketUpgrade { inbound, outbound, context in
for try await message in inbound {
try await outbound.write(message) // echo text/binary
}
}
case "/clock":
return WebSocketUpgrade { inbound, outbound, context in
// a different endpoint, its own handler
}
default:
return nil // decline → regular HTTP
}
}
)

let server = NIOHTTPServer(logger: logger, configuration: configuration)
try await server.serve { _, _, _, responseSender in
// Non-WebSocket requests (and declined upgrades) are served here as usual.
}

@aryan-25 is exploring another approach that doesn't entirely disconnect the upgrade path from the normal request handling path. Instead of making this a configuration option we are thinking something along the lines of:

func requestHandler(request: HTTPRequest, requestReader: Reader, responseSender: HTTPResponseSender) async throws {
    try validateUpgradeRequest(request)
    
    // consumes the requestReader and the responseSender 
    try await responseSender.acceptWebsocketUpgrade(requestReader) { websocketReader, websocketWriter in
      // In here you can now handle the web socket request however you like with all the context of the original http request still available. Nicely structured with the rest of the request handling.
    }
}

[aryan-25]

@gjcairo and I have started exploring how to support Upgrade/CONNECT requests. In the interim, we are introducing a minimal API to support HTTP Datagrams in PR #106. The current shape is just enough to read and write raw bytes from the unreliable datagram stream when they are available (the unreliable datagram reader and writer are vended from Reader and Writer in a with-style method).

This shape is experimental and behind an UnstableHTTPDatagrams trait (off by default). We expect to iterate on it and make it more general purpose to better support other Upgrade/CONNECT tokens like WebSockets for example.