Client WebSockets

Ktor supports the WebSocket protocol and allows you to create applications that require real-time data transfer from and to the server. For example, WebSockets can be used to create a chat application.

The Ktor client allows you to handle a WebSocket session for exchanging messages with the server. To learn about WebSocket support in a Ktor server, see Server WebSockets.

Add dependencies

To use WebSockets, you need to include the ktor-client-websockets artifact in the build script:

implementation "io.ktor:ktor-client-websockets:$ktor_version"

implementation("io.ktor:ktor-client-websockets:$ktor_version")

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-client-websockets</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

Install WebSockets

To install the WebSockets plugin, pass it to the install function inside a client configuration block:

val client = HttpClient(CIO) {
    install(WebSockets) {
        // Configure WebSockets
    }
}

Optionally, you can configure the plugin inside the install block by passing the required options using WebSockets.Config.

Handle a WebSockets session

API overview

To handle a client WebSocket session, call the webSocket function:

runBlocking {
    client.webSocket(method = HttpMethod.Get, host = "127.0.0.1", port = 8080, path = "/echo") {
        // Handle a WebSocket session
    }
}

Inside the webSocket block, you need to handle a WebSocket session, which is represented by the DefaultClientWebSocketSession class. Session configuration might look as follows:

Use the send function to send text content to the server.
Use the incoming and outgoing properties to access the channels for receiving and sending WebSocket frames. A frame is represented by the Frame class.
When handing a session, you can check a frame type, for example:
- Frame.Text is a text frame. For this frame type, you can read its content using Frame.Text.readText().
- Frame.Binary is a binary frame. For this type, you can read its content using Frame.Binary.readBytes().
- Frame.Close is a closing frame. You can call Frame.Close.readReason() to get a close reason for the current session.
Use the close function to send a close frame with the specified reason.

Example

The example below shows how to send a message to the echo WebSocket endpoint and how to receive a response:

fun main() {
    val client = HttpClient(CIO) {
        install(WebSockets)
    }
    runBlocking {
        client.webSocket(method = HttpMethod.Get, host = "127.0.0.1", port = 8080, path = "/echo") {
            while(true) {
                val othersMessage = incoming.receive() as? Frame.Text
                println(othersMessage?.readText())
                val myMessage = Scanner(System.`in`).next()
                if(myMessage != null) {
                    send(myMessage)
                }
            }
        }
    }
    client.close()
}

You can find the full example here: client-websockets.

Last modified: 31 August 2021