0
# Plugin Configuration
1

2
The WebSockets plugin provides configuration options for ping intervals, frame size limits, content conversion, and WebSocket extensions.
3

4
## Installation
5

6
Install the WebSockets plugin in your HttpClient configuration:
7

8
```kotlin
9
import io.ktor.client.*
10
import io.ktor.client.engine.cio.*
11
import io.ktor.client.plugins.websocket.*
12

13
val client = HttpClient(CIO) {
14
    install(WebSockets) {
15
        // Configure plugin options
16
        pingInterval = 20_000 // 20 seconds
17
        maxFrameSize = 1024 * 1024 // 1MB
18
        contentConverter = MyWebSocketConverter()
19
    }
20
}
21
```
22

23
## Configuration Options
24

25
### Ping Interval
26

27
Controls the automatic ping frame interval for connection keep-alive:
28

29
```kotlin { .api }
30
var WebSockets.Config.pingInterval: Long
31
```
32

33
- **Default**: `-1L` (disabled)
34
- **Units**: Milliseconds
35
- **Description**: Interval between automatic ping frames. Set to `-1L` to disable automatic pings.
36

37
**Usage:**
38
```kotlin
39
install(WebSockets) {
40
    pingInterval = 30_000 // Send ping every 30 seconds
41
    // or
42
    pingInterval = -1L // Disable automatic pings
43
}
44
```
45

46
### Maximum Frame Size
47

48
Sets the maximum allowed size for incoming WebSocket frames:
49

50
```kotlin { .api }
51
var WebSockets.Config.maxFrameSize: Long
52
```
53

54
- **Default**: `Int.MAX_VALUE.toLong()`
55
- **Units**: Bytes
56
- **Description**: Maximum size of a single WebSocket frame. Connections will be closed if this limit is exceeded.
57

58
**Usage:**
59
```kotlin
60
install(WebSockets) {
61
    maxFrameSize = 512 * 1024 // 512KB limit
62
    // or
63
    maxFrameSize = Long.MAX_VALUE // No practical limit
64
}
65
```
66

67
### Content Converter
68

69
Configures automatic serialization/deserialization for WebSocket messages:
70

71
```kotlin { .api }
72
var WebSockets.Config.contentConverter: WebsocketContentConverter?
73
```
74

75
- **Default**: `null`
76
- **Description**: Content converter for automatic serialization of objects sent via `sendSerialized()` and deserialization via `receiveDeserialized()`.
77

78
**Usage:**
79
```kotlin
80
import io.ktor.serialization.kotlinx.*
81
import kotlinx.serialization.json.*
82

83
install(WebSockets) {
84
    contentConverter = KotlinxWebsocketSerializationConverter(Json)
85
}
86
```
87

88
### WebSocket Extensions
89

90
Configure WebSocket protocol extensions:
91

92
```kotlin { .api }
93
fun WebSockets.Config.extensions(block: WebSocketExtensionsConfig.() -> Unit)
94
```
95

96
**Usage:**
97
```kotlin
98
install(WebSockets) {
99
    extensions {
100
        // Configure extensions like compression, etc.
101
        // Note: Extension availability depends on the client engine
102
    }
103
}
104
```
105

106
## Complete Configuration Example
107

108
```kotlin
109
import io.ktor.client.*
110
import io.ktor.client.engine.cio.*
111
import io.ktor.client.plugins.websocket.*
112
import io.ktor.serialization.kotlinx.*
113
import kotlinx.serialization.json.*
114

115
val client = HttpClient(CIO) {
116
    install(WebSockets) {
117
        // Send ping every 20 seconds
118
        pingInterval = 20_000
119
        
120
        // Limit frames to 1MB
121
        maxFrameSize = 1024 * 1024
122
        
123
        // Enable JSON serialization
124
        contentConverter = KotlinxWebsocketSerializationConverter(Json {
125
            prettyPrint = true
126
            isLenient = true
127
        })
128
        
129
        // Configure extensions (if supported by engine)
130
        extensions {
131
            // Extension configuration would go here
132
        }
133
    }
134
}
135
```
136

137
## Engine Compatibility
138

139
Not all client engines support all WebSocket features:
140

141
- **CIO Engine**: Full WebSocket support including extensions
142
- **JavaScript Engine**: Basic WebSocket support, no ping-pong control, no extensions
143
- **Native Engines**: WebSocket support varies by platform
144

145
Check engine capabilities:
146

147
```kotlin { .api }
148
object WebSocketCapability : HttpClientEngineCapability<Unit>
149
object WebSocketExtensionsCapability : HttpClientEngineCapability<Unit>
150
```
151

152
**Usage:**
153
```kotlin
154
val hasWebSocketSupport = client.engine.supportedCapabilities.contains(WebSocketCapability)
155
val hasExtensionsSupport = client.engine.supportedCapabilities.contains(WebSocketExtensionsCapability)
156
```
157

158
## Error Handling
159

160
Configuration errors and WebSocket-specific exceptions:
161

162
```kotlin { .api }
163
class WebSocketException(message: String, cause: Throwable?) : IllegalStateException
164
```
165

166
Common configuration issues:
167
- Invalid ping interval values
168
- Frame size limits that are too small
169
- Missing content converter when using serialization functions
170
- Engine incompatibility with requested features