# Overview - Vapor Docs

Skip to content


# Using WebSockets

Unlike HTTP, WebSockets allow you to communicate between client and server in an open, interactive way. You can send messages (called frames) in either text or binary format. Both the client and the server can send as many messages as they want at a time, without having to wait for responses.

Although WebSocket is its own protocol, it still uses HTTP to get setup. Every WebSocket connection will start with an HTTP request with special headers followed by an HTTP response with status `101 Switching Protocols`. After this initial handshake, the connection is a WebSocket connection.

## WebSocket

The `WebSocket` class represents a connected WebSocket client. You can use this to set callbacks for receiving data and to send data.

    let ws: WebSocket = ...
    // Send an initial message to this WebSocket
    ws.send("Hello!")

    // Set a new callback for receiving text formatted data
    ws.onText { ws, string in
        // Echo the text back, reversed.
        ws.send(string.reversed())
    }

Tip

All callbacks will receive a reference to the `WebSocket`. Use these if you need to send data to avoid creating a reference cycle.

The `WebSocket` has an `onClose` future that will be completed when the connection closes. You can use `close()` to close the connection yourself.

## Server

WebSocket servers connect to one or more WebSocket clients at a time. As mentioned previously, WebSocket connections must start via an HTTP request and response handshake. Because of this, WebSocket servers are built on top of HTTP servers using the HTTP upgrade mechanism.

    // First, create an HTTPProtocolUpgrader
    let ws = HTTPServer.webSocketUpgrader(shouldUpgrade: { req in
        // Returning nil in this closure will reject upgrade
        if req.url.path == "/deny" { return nil }
        // Return any additional headers you like, or just empty
        return [:]
    }, onUpgrade: { ws, req in
        // This closure will be called with each new WebSocket client
        ws.send("Connected")
        ws.onText { ws, string in
            ws.send(string.reversed())
        }
    })

    // Next, create your server, adding the WebSocket upgrader
    let server = try HTTPServer.start(
        ...
        upgraders: [ws],
        ...
    ).wait()
    // Run the server.
    try server.onClose.wait()

Seealso

Visit HTTP → Server for more information on setting up an HTTP server.

The WebSocket protocol upgrader consists of two callbacks.

The first callback `shouldUpgrade` receives the incoming HTTP request that is requesting upgrade. This callback decides whether or not to complete the upgrade based on the contents of the request. If `nil` is returned in this closure, the upgrade will be rejected.

The second callback `onUpgrade` is called each time a new WebSocket client connects. This is where you configure your callbacks and send any initial data.

Warning

The upgrade closures may be called on any event loop. Be careful to avoid race conditions if you must access external variables.

## Client

You can also use the WebSocket package to connect to a WebSocket server. Just like the WebSocket server used an HTTP server, the WebSocket client uses HTTP client.

    // Create a new WebSocket connected to echo.websocket.org
    let ws = try HTTPClient.webSocket(hostname: "echo.websocket.org", on: ...).wait()

    // Set a new callback for receiving text formatted data.
    ws.onText { ws, text in
        print("Server echo: \(text)")
    }

    // Send a message.
    ws.send("Hello, world!")

    // Wait for the Websocket to closre.
    try ws.onClose.wait()

Seealso

Visit HTTP → Client for more information on setting up an HTTP client.

## API Docs

Check out the API docs for more in-depth information about all of the methods.