WebSockets

WebSockets allow for two-way communication between a client and server. Unlike HTTP, which has a request and response pattern, WebSocket peers can send an arbitrary number of messages in either direction. Vapor's WebSocket API allows you to create both clients and servers that handle messages asynchronously.

Server

WebSocket endpoints can be added to your existing Vapor application using the Routing API. Use the webSocket method like you would use get or post.

app.webSocket("echo") { req, ws in
    // Connected WebSocket.
    print(ws)
}

WebSocket routes can be grouped and protected by middleware like normal routes.

In addition to accepting the incoming HTTP request, WebSocket handlers accept the newly established WebSocket connection. See below for more information on using this WebSocket to send and read messages.

Client

To connect to a remote WebSocket endpoint, use WebSocket.connect.

WebSocket.connect(to: "ws://echo.websocket.org", on: eventLoop) { ws in
    // Connected WebSocket.
    print(ws)
}

The connect method returns a future that completes when the connection is established. Once connected, the supplied closure will be called with the newly connected WebSocket. See below for more information on using this WebSocket to send and read messages.

Messages

The WebSocket class has methods for sending and receiving messages as well as listening for events like closure. WebSockets can transmit data via two protocols: text and binary. Text messages are interpreted as UTF-8 strings while binary data is interpreted as an array of bytes.

Sending

Messages can be sent using the WebSocket's send method.

ws.send("Hello, world")

Passing a String to this method results in a text message being sent. Binary messages can be sent by passing a [UInt8].

ws.send([1, 2, 3])

Message sending is asynchronous. You can supply an EventLoopPromise to the send method to be notified when the message has finished sending or failed to send.

let promise = eventLoop.makePromise(of: Void.self)
ws.send(..., promise: promise)
promise.futureResult.whenComplete { result in
    // Succeeded or failed to send.
}

If using async/await you can use await to wait for the asynchronous operation to complete

try await ws.send(...)

Receiving

Incoming messages are handled via the onText and onBinary callbacks.

ws.onText { ws, text in
    // String received by this WebSocket.
    print(text)
}

ws.onBinary { ws, binary in
    // [UInt8] received by this WebSocket.
    print(binary)
}

The WebSocket itself is supplied as the first parameter to these callbacks to prevent reference cycles. Use this reference to take action on the WebSocket after receiving data. For example, to send a reply:

// Echoes received messages.
ws.onText { ws, text in
    ws.send(text)
}

Closing

To close a WebSocket, call the close method.

ws.close()

This method returns a future that will be completed when the WebSocket has closed. Like send, you may also pass a promise to this method.

ws.close(promise: nil)

Or await on it if using async/await:

try await ws.close()

To be notified when the peer closes the connection, use onClose. This future will be completed when either the client or server closes the WebSocket.

ws.onClose.whenComplete { result in
    // Succeeded or failed to close.
}

The closeCode property is set when the WebSocket closes. This can be used to determine why the peer closed the connection.

Ping / Pong

Ping and pong messages are sent automatically by the client and server to keep WebSocket connections alive. Your application can listen for these events using the onPing and onPong callbacks.

ws.onPing { ws in 
    // Ping was received.
}

ws.onPong { ws in
    // Pong was received.
}