WebSocketUpgrader

public final class WebSocketUpgrader : HTTPProtocolUpgrader

A HTTPProtocolUpgrader that knows how to do the WebSocket upgrade dance.

Users may frequently want to offer multiple websocket endpoints on the same port. For this reason, this WebSocketUpgrader only knows how to do the required parts of the upgrade and to complete the handshake. Users are expected to provide a callback that examines the HTTP headers (including the path) and determines whether this is a websocket upgrade request that is acceptable to them.

This upgrader assumes that the HTTPServerUpgradeHandler will appropriately mutate the pipeline to remove the HTTP ChannelHandlers.

  • RFC 6455 specs this as the required entry in the Upgrade header.

    Declaration

    Swift

    public let supportedProtocol: String
  • We deliberately do not actually set any required headers here, because the websocket spec annoyingly does not actually force the client to send these in the Upgrade header, which NIO requires. We check for these manually.

    Declaration

    Swift

    public let requiredUpgradeHeaders: [String]
  • Create a new WebSocketUpgrader.

    Declaration

    Swift

    public convenience init(automaticErrorHandling: Bool = true, shouldUpgrade: @escaping (HTTPRequestHead) -> HTTPHeaders?,
                upgradePipelineHandler: @escaping (Channel, HTTPRequestHead) -> EventLoopFuture<Void>)

    Parameters

    automaticErrorHandling

    Whether the pipeline should automatically handle protocol errors by sending error responses and closing the connection. Defaults to true, may be set to false if the user wishes to handle their own errors.

    shouldUpgrade

    A callback that determines whether the websocket request should be upgraded. This callback is responsible for creating a HTTPHeaders object with any headers that it needs on the response except for the Upgrade, Connection, and Sec-WebSocket-Accept headers, which this upgrader will handle. Should return nil if the upgrade should be refused.

    upgradePipelineHandler

    A function that will be called once the upgrade response is flushed, and that is expected to mutate the Channel appropriately to handle the websocket protocol. This only needs to add the user handlers: the WebSocketFrameEncoder and WebSocketFrameDecoder will have been added to the pipeline automatically.

  • Create a new WebSocketUpgrader.

    Declaration

    Swift

    public init(maxFrameSize: Int, automaticErrorHandling: Bool = true, shouldUpgrade: @escaping (HTTPRequestHead) -> HTTPHeaders?,
                upgradePipelineHandler: @escaping (Channel, HTTPRequestHead) -> EventLoopFuture<Void>)

    Parameters

    maxFrameSize

    The maximum frame size the decoder is willing to tolerate from the remote peer. WebSockets in principle allows frame sizes up to 2**64 bytes, but this is an objectively unreasonable maximum value (on AMD64 systems it is not possible to even. Users may set this to any value up to UInt32.max.

    automaticErrorHandling

    Whether the pipeline should automatically handle protocol errors by sending error responses and closing the connection. Defaults to true, may be set to false if the user wishes to handle their own errors.

    shouldUpgrade

    A callback that determines whether the websocket request should be upgraded. This callback is responsible for creating a HTTPHeaders object with any headers that it needs on the response except for the Upgrade, Connection, and Sec-WebSocket-Accept headers, which this upgrader will handle. Should return nil if the upgrade should be refused.

    upgradePipelineHandler

    A function that will be called once the upgrade response is flushed, and that is expected to mutate the Channel appropriately to handle the websocket protocol. This only needs to add the user handlers: the WebSocketFrameEncoder and WebSocketFrameDecoder will have been added to the pipeline automatically.

  • Declaration

    Swift

    public func buildUpgradeResponse(upgradeRequest: HTTPRequestHead, initialResponseHeaders: HTTPHeaders) throws -> HTTPHeaders
  • Declaration

    Swift

    public func upgrade(ctx: ChannelHandlerContext, upgradeRequest: HTTPRequestHead) -> EventLoopFuture<Void>