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.
Ktor allows you to:
Configure basic WebSocket settings, such as frame size, a ping period, and so on.
Handle a WebSocket session for exchanging messages between the server and client.
Add WebSocket extensions. For example, you can use the Deflate extension or implement a custom extension.
WebSockets, you need to include the
ktor-server-websockets artifact in the build script:
To install the
WebSockets plugin to the application, pass it to the
install function in the specified module. The code snippets below show how to install
... inside the
... inside the explicitly defined
module, which is an extension function of the
Configure WebSockets settings
Optionally, you can configure the plugin by passing WebSocketOptions to the
Handle WebSockets sessions
After you installed and configured the
WebSockets plugin, you are ready to handle a WebSocket session. First, you need to define a WebSocket endpoint on a server by calling the
webSocket function inside the routing block:
For such an endpoint, a server accepts WebSocket requests to
ws://localhost:8080/echo when a default configuration is used.
webSocket block, you need to handle a WebSocket session, which is represented by the DefaultWebSocketServerSession class. Session configuration might look as follows:
sendfunction to send text content to the client.
outgoingproperties to access the channels for receiving and sending WebSocket frames. A frame is represented by the
When handling a session, you can check a frame type, for example:
Frame.Textis a text frame. For this frame type, you can read its content using
Frame.Binaryis a binary frame. For this type, you can read its content using
closefunction to send a close frame with the specified reason.
Below, we'll take a look at the examples of using this API.
Example: Handle a single session
The example below shows how to create the
echo WebSocket endpoint to handle a session with one client:
You can find the full example here: server-websockets.
Example: Handle multiple sessions
To handle multiple WebSocket sessions (for example, in a chat application), you need to store each session on a server. For example, you can define a connection with a unique name and associate it with a specified session. A sample
Connection class below shows how to do this:
Then, you can create a new connection inside the
webSocket handler when a new client connects to the WebSocket endpoint:
You can find the full example here: tutorial-websockets-server.
The WebSocket API and Ktor
The standard events from the WebSocket API map to Ktor in the following way:
onConnecthappens at the start of the block.
onMessagehappens after successfully reading a message (for example, with
incoming.receive()) or using suspended iteration with
for(frame in incoming).
onClosehappens when the
incomingchannel is closed. That would complete the suspended iteration, or throw a
ClosedReceiveChannelExceptionwhen trying to receive a message.
onErroris equivalent to other exceptions.
closeReason property is set.
In this sample, the infinite loop is only exited with an exception is risen: either a
ClosedReceiveChannelException or another exception.