WebSocket

#Introduction

WebSockets shine in scenarios that require real-time communication. For example, they are widely used in chat applications, online multiplayer games, and real-time data dashboards.

For a mobile application, WebSockets enable seamless interaction with a backend server, allowing mobile clients to maintain a live link to the server for push notifications or updates. In mobile development, WebSockets are useful for building apps where timely delivery of message updates is critical, such as collaborative editing tools or live sports score apps.

If you are new to WebSockets, we recommend reading our WebSocket overview first.

#Server

To use WebSockets, you need to include the ktor-server-websockets dependency:

dependencies:
  - $ktor.server.websockets

Install the WebSockets plugin by passing it to the install function within your application module:

import io.ktor.server.application.*
import io.ktor.server.websocket.*
// ...
fun Application.module() {
    install(WebSockets)
    // ...
}

#Configure WebSockets

You can customize the plugin’s behavior within the install block using WebSocketOptions:

• pingPeriod: Frequency of keep-alive pings.
• timeout: Duration after which an inactive connection is closed.
• maxFrameSize: Maximum size allowed for a single frame.
• masking: Whether to enable frame masking.
• contentConverter: A converter for automated serialization and deserialization.

install(WebSockets) {
    pingPeriod = 15.seconds
    timeout = 15.seconds
    maxFrameSize = Long.MAX_VALUE
    masking = false
}

#Handle WebSockets sessions

Define a WebSocket endpoint by calling the webSocket function inside your routing block:

routing {
    webSocket("/echo") {
       // Handle a WebSocket session
    }
}