Using WebSockets

Vapor includes convenience methods for working with the lower level WebSocket client and server.

Server

Vapor's WebSocket server includes the ability to route incoming requests just like its HTTP server.

When Vapor's main HTTP Server boots it will attempt to create a WebSocketServer. If one is registered, it will be added as an HTTP upgrade handler to the server.

So to create a WebSocket server, all you need to do is register one in configure.swift.

// Create a new NIO websocket server
let wss = NIOWebSocketServer.default()

// Add WebSocket upgrade support to GET /echo
wss.get("echo") { ws, req in
    // Add a new on text callback
    ws.onText { ws, text in
        // Simply echo any received text
        ws.send(text)
    }
}

// Register our server
services.register(wss, as: WebSocketServer.self)

That's it. Next time you boot your server, you will be able to perform a WebSocket upgrade at GET /echo. You can test this using a simple command line tool called wsta available for macOS and Linux.

$ wsta ws://localhost:8080/echo
Connected to ws://localhost:8080/echo
hello, world!
hello, world!

Parameters

Like Vapor's HTTP router, you can also use routing parameters with your WebSocket server.

// Add WebSocket upgrade support to GET /chat/:name
wss.get("chat", String.parameter) { ws, req in
    let name = try req.parameters.next(String.self)
    ws.send("Welcome, \(name)!")

    // ...
}

Now let's test this new route:

$ wsta ws://localhost:8080/chat/Vapor
Connected to ws://localhost:8080/chat/Vapor
Welcome, Vapor!

Client

Vapor also supports connecting to WebSocket servers as a client. The easiest way to connect to a WebSocket server is through the webSocket(...) method on Client.

For this example, we will assume our application connects to a WebSocket server in boot.swift

// connect to echo.websocket.org
let done = try app.client().webSocket("ws://echo.websocket.org").flatMap { ws -> Future<Void> in
    // setup an on text callback that will print the echo
    ws.onText { ws, text in
        print("rec: \(text)")
        // close the websocket connection after we recv the echo
        ws.close()
    }

    // when the websocket first connects, send message
    ws.send("hello, world!")

    // return a future that will complete when the websocket closes
    return ws.onClose
}

print(done) // Future<Void>

// wait for the websocket to close
try done.wait()