Skip to content
Browse files

Add a WebSocket Client example. As Per issue #465 (#1064)


To provide an example of the usage of the WebSocket client upgrade functionality.
To satisfy issue #465


Added a ‘WebSocketClient’ example with a readme and a target in the package file.


There is now a WebSocket client example to assist with the creation of a WebSocket client.
  • Loading branch information...
tigerpixel authored and weissi committed Jul 26, 2019
1 parent 96d9e44 commit fa2a1fd168316e7a9aff22cced32df9709a78b59
Showing with 243 additions and 2 deletions.
  1. +4 −2 Package.swift
  2. +11 −0 Sources/NIOWebSocketClient/
  3. +228 −0 Sources/NIOWebSocketClient/main.swift
@@ -51,6 +51,8 @@ var targets: [PackageDescription.Target] = [
dependencies: ["NIO", "NIOHTTP1", "CNIOSHA1"]),
.target(name: "NIOWebSocketServer",
dependencies: ["NIO", "NIOHTTP1", "NIOWebSocket"]),
.target(name: "NIOWebSocketClient",
dependencies: ["NIO", "NIOHTTP1", "NIOWebSocket"]),
.target(name: "NIOPerformanceTester",
dependencies: ["NIO", "NIOHTTP1", "NIOFoundationCompat"]),
.target(name: "NIOMulticastChat",
@@ -84,8 +86,8 @@ let package = Package(
.executable(name: "NIOChatClient", targets: ["NIOChatClient"]),
.executable(name: "NIOHTTP1Server", targets: ["NIOHTTP1Server"]),
.executable(name: "NIOHTTP1Client", targets: ["NIOHTTP1Client"]),
.executable(name: "NIOWebSocketServer",
targets: ["NIOWebSocketServer"]),
.executable(name: "NIOWebSocketServer", targets: ["NIOWebSocketServer"]),
.executable(name: "NIOWebSocketClient", targets: ["NIOWebSocketClient"]),
.executable(name: "NIOPerformanceTester",
targets: ["NIOPerformanceTester"]),
.executable(name: "NIOMulticastChat", targets: ["NIOMulticastChat"]),
@@ -0,0 +1,11 @@
# NIOWebSocketClient

This sample application provides a simple WebSocket client. First it performs an upgrade from a HTTP connection. Once upgraded, it sends a 'ping' frame, with a body, to the server. It then checks that the body matches in the returning 'pong' frame. It also prints out any text frame received from the server. Invoke it using one of the following syntaxes:

swift run NIOWebSocketClient # Connects to a server on ::1, port 8888.
swift run NIOWebSocketClient 9899 # Connects to a server on ::1, port 9899
swift run NIOWebSocketClient /path/to/unix/socket # Connects to a server using the given UNIX socket
swift run NIOWebSocketClient 9899 # Connects to a server on

@@ -0,0 +1,228 @@
// This source file is part of the SwiftNIO open source project
// Copyright (c) 2017-2019 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
// SPDX-License-Identifier: Apache-2.0
import NIO
import NIOHTTP1
import NIOWebSocket

print("Establishing connection.")

// The HTTP handler to be used to initiate the request.
// This initial request will be adapted by the WebSocket upgrader to contain the upgrade header parameters.
// Channel read will only be called if the upgrade fails.
private final class HTTPInitialRequestHandler: ChannelInboundHandler, RemovableChannelHandler {
public typealias InboundIn = HTTPClientResponsePart
public typealias OutboundOut = HTTPClientRequestPart

public func channelActive(context: ChannelHandlerContext) {
print("Client connected to \(context.remoteAddress!)")

// We are connected. It's time to send the message to the server to initialize the upgrade dance.
var headers = HTTPHeaders()
headers.add(name: "Content-Type", value: "text/plain; charset=utf-8")
headers.add(name: "Content-Length", value: "\(0)")

let requestHead = HTTPRequestHead(version: HTTPVersion(major: 1, minor: 1),
method: .GET,
uri: "/",
headers: headers)

context.write(self.wrapOutboundOut(.head(requestHead)), promise: nil)

let emptyBuffer = 0)
let body = HTTPClientRequestPart.body(.byteBuffer(emptyBuffer))
context.write(self.wrapOutboundOut(body), promise: nil)

context.writeAndFlush(self.wrapOutboundOut(.end(nil)), promise: nil)

public func channelRead(context: ChannelHandlerContext, data: NIOAny) {

let clientResponse = self.unwrapInboundIn(data)

print("Upgrade failed")

switch clientResponse {
case .head(let responseHead):
print("Received status: \(responseHead.status)")
case .body(var byteBuffer):
if let string = byteBuffer.readString(length: byteBuffer.readableBytes) {
print("Received: '\(string)' back from the server.")
} else {
print("Received the line back from the server.")
case .end:
print("Closing channel.")
context.close(promise: nil)

public func handlerRemoved(context: ChannelHandlerContext) {
print("HTTP handler removed.")

public func errorCaught(context: ChannelHandlerContext, error: Error) {
print("error: ", error)

// As we are not really interested getting notified on success or failure
// we just pass nil as promise to reduce allocations.
context.close(promise: nil)

// The web socket handler to be used once the upgrade has occurred.
// One added, it sends a ping-pong round trip with "Hello World" data.
// It also listens for any text frames from the server and prints them.
private final class WebSocketPingPongHandler: ChannelInboundHandler {
typealias InboundIn = WebSocketFrame
typealias OutboundOut = WebSocketFrame

let testFrameData: String = "Hello World"

// This is being hit, channel active won't be called as it is already added.
public func handlerAdded(context: ChannelHandlerContext) {
print("WebSocket handler added.")
self.pingTestFrameData(context: context)

public func handlerRemoved(context: ChannelHandlerContext) {
print("WebSocket handler removed.")

public func channelRead(context: ChannelHandlerContext, data: NIOAny) {
let frame = self.unwrapInboundIn(data)

switch frame.opcode {
case .pong:
self.pong(context: context, frame: frame)
case .text:
var data = frame.unmaskedData
let text = data.readString(length: data.readableBytes) ?? ""
print("Websocket: Received \(text)")
case .connectionClose:
self.receivedClose(context: context, frame: frame)
case .binary, .continuation, .ping:
// We ignore these frames.
// Unknown frames are errors.
self.closeOnError(context: context)

public func channelReadComplete(context: ChannelHandlerContext) {

private func receivedClose(context: ChannelHandlerContext, frame: WebSocketFrame) {
// Handle a received close frame. We're just going to close.
print("Received Close instruction from server")
context.close(promise: nil)

private func pingTestFrameData(context: ChannelHandlerContext) {
var buffer = self.testFrameData.utf8.count)
let frame = WebSocketFrame(fin: true, opcode: .ping, data: buffer)
context.write(self.wrapOutboundOut(frame), promise: nil)

private func pong(context: ChannelHandlerContext, frame: WebSocketFrame) {
var frameData =
if let frameDataString = frameData.readString(length: self.testFrameData.count) {
print("Websocket: Received: \(frameDataString)")

private func closeOnError(context: ChannelHandlerContext) {
// We have hit an error, we want to close. We do that by sending a close frame and then
// shutting down the write side of the connection. The server will respond with a close of its own.
var data = 2)
data.write(webSocketErrorCode: .protocolError)
let frame = WebSocketFrame(fin: true, opcode: .connectionClose, data: data)
context.write(self.wrapOutboundOut(frame)).whenComplete { (_: Result<Void, Error>) in
context.close(mode: .output, promise: nil)

let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
let bootstrap = ClientBootstrap(group: group)
.channelOption(ChannelOptions.socket(SocketOptionLevel(SOL_SOCKET), SO_REUSEADDR), value: 1)
.channelInitializer { channel in

let httpHandler = HTTPInitialRequestHandler()

let websocketUpgrader = NIOWebClientSocketUpgrader(requestKey: "OfS0wDaT5NoxF2gqm7Zj2YtetzM=",
upgradePipelineHandler: { (channel: Channel, _: HTTPResponseHead) in

let config: NIOHTTPClientUpgradeConfiguration = (
upgraders: [ websocketUpgrader ],
completionHandler: { _ in
channel.pipeline.removeHandler(httpHandler, promise: nil)

return channel.pipeline.addHTTPClientHandlers(withClientUpgrade: config).flatMap {
defer {
try! group.syncShutdownGracefully()

// First argument is the program path
let arguments = CommandLine.arguments
let arg1 = arguments.dropFirst().first
let arg2 = arguments.dropFirst(2).first

let defaultHost = "::1"
let defaultPort: Int = 8888

enum ConnectTo {
case ip(host: String, port: Int)
case unixDomainSocket(path: String)

let connectTarget: ConnectTo
switch (arg1, arg1.flatMap(Int.init), arg2.flatMap(Int.init)) {
case (.some(let h), _ , .some(let p)):
/* we got two arguments, let's interpret that as host and port */
connectTarget = .ip(host: h, port: p)
case (.some(let portString), .none, _):
/* couldn't parse as number, expecting unix domain socket path */
connectTarget = .unixDomainSocket(path: portString)
case (_, .some(let p), _):
/* only one argument --> port */
connectTarget = .ip(host: defaultHost, port: p)
connectTarget = .ip(host: defaultHost, port: defaultPort)

let channel = try { () -> Channel in
switch connectTarget {
case .ip(let host, let port):
return try bootstrap.connect(host: host, port: port).wait()
case .unixDomainSocket(let path):
return try bootstrap.connect(unixDomainSocketPath: path).wait()

// Will be closed after we echo-ed back to the server.
try channel.closeFuture.wait()

print("Client closed")

0 comments on commit fa2a1fd

Please sign in to comment.
You can’t perform that action at this time.