0
# Plugin Configuration
1

2
WebSocket plugin installation and configuration with comprehensive control over connection behavior, frame processing, and extension support.
3

4
## Capabilities
5

6
### WebSocket Plugin Installation
7

8
Install the WebSocket plugin with configuration options for ping intervals, frame sizes, and content converters.
9

10
```kotlin { .api }
11
/**
12
 * Install WebSocket plugin with configuration
13
 * @param config Configuration block for WebSocket settings
14
 */
15
fun HttpClientConfig<*>.WebSockets(config: WebSockets.Config.() -> Unit)
16
```
17

18
**Usage Examples:**
19

20
```kotlin
21
val client = HttpClient {
22
    install(WebSockets) {
23
        pingInterval = 30.seconds
24
        maxFrameSize = 1024 * 1024 // 1MB
25
        contentConverter = GsonWebsocketContentConverter()
26
    }
27
}
28
```
29

30
### WebSocket Plugin Class
31

32
Main plugin class containing configuration and implementation logic.
33

34
```kotlin { .api }
35
/**
36
 * Client WebSocket plugin providing WebSocket support for Ktor HTTP client
37
 * @param pingIntervalMillis Interval between ping messages in milliseconds
38
 * @param maxFrameSize Maximum size of a single WebSocket frame
39
 * @param contentConverter Optional converter for serialization/deserialization
40
 */
41
class WebSockets internal constructor(
42
    val pingIntervalMillis: Long,
43
    val maxFrameSize: Long,
44
    private val extensionsConfig: WebSocketExtensionsConfig,
45
    val contentConverter: WebsocketContentConverter? = null
46
) : HttpClientPlugin<WebSockets.Config, WebSockets> {
47
    
48
    constructor(
49
        pingIntervalMillis: Long = PINGER_DISABLED,
50
        maxFrameSize: Long = Int.MAX_VALUE.toLong()
51
    )
52
    
53
    constructor()
54
    
55
    companion object Plugin : HttpClientPlugin<Config, WebSockets> {
56
        override val key: AttributeKey<WebSockets>
57
        override fun prepare(block: Config.() -> Unit): WebSockets
58
        override fun install(plugin: WebSockets, scope: HttpClient)
59
    }
60
}
61
```
62

63
### WebSocket Configuration
64

65
Configuration class for customizing WebSocket behavior.
66

67
```kotlin { .api }
68
/**
69
 * Configuration class for WebSocket plugin
70
 */
71
@KtorDsl
72
class Config {
73
    /** Interval of sending ping frames in milliseconds. Use PINGER_DISABLED to disable ping */
74
    var pingIntervalMillis: Long
75
    
76
    /** Maximum frame size in bytes */
77
    var maxFrameSize: Long
78
    
79
    /** Content converter for serialization/deserialization */
80
    var contentConverter: WebsocketContentConverter?
81
    
82
    /** Ping interval as Duration. Use null to disable ping */
83
    var pingInterval: Duration?
84
    
85
    /**
86
     * Configure WebSocket extensions
87
     * @param block Configuration block for extensions
88
     */
89
    fun extensions(block: WebSocketExtensionsConfig.() -> Unit)
90
}
91
```
92

93
**Usage Examples:**
94

95
```kotlin
96
install(WebSockets) {
97
    // Set ping interval using Duration
98
    pingInterval = 45.seconds
99
    
100
    // Set maximum frame size (1MB)
101
    maxFrameSize = 1024 * 1024
102
    
103
    // Install content converter
104
    contentConverter = KotlinxSerializationWebsocketContentConverter()
105
    
106
    // Configure extensions
107
    extensions {
108
        install(WebSocketDeflateExtension) {
109
            compressionLevel = Deflater.DEFAULT_COMPRESSION
110
        }
111
    }
112
}
113
```
114

115
### Duration-based Constructor
116

117
Alternative constructor using Kotlin Duration API for more convenient configuration.
118

119
```kotlin { .api }
120
/**
121
 * Create WebSocket plugin with Duration-based ping interval
122
 * @param pingInterval Interval between ping messages, null to disable
123
 * @param maxFrameSize Maximum size of a single WebSocket frame
124
 */
125
fun WebSockets(
126
    pingInterval: Duration?,
127
    maxFrameSize: Long = Int.MAX_VALUE.toLong()
128
): WebSockets
129
```
130

131
**Usage Examples:**
132

133
```kotlin
134
val client = HttpClient {
135
    install(WebSockets(
136
        pingInterval = 30.seconds,
137
        maxFrameSize = 512 * 1024
138
    ))
139
}
140
```
141

142
### Extension Properties
143

144
Convenient extension properties for working with Duration-based configuration.
145

146
```kotlin { .api }
147
/**
148
 * Get ping interval as Duration, null if disabled 
149
 */
150
val WebSockets.pingInterval: Duration?
151

152
/**
153
 * Set/get ping interval as Duration for configuration
154
 */
155
var WebSockets.Config.pingInterval: Duration?
156
```
157

158
### WebSocket Capabilities
159

160
Engine capability markers for WebSocket support detection.
161

162
```kotlin { .api }
163
/**
164
 * Indicates if a client engine supports WebSockets
165
 */
166
data object WebSocketCapability : HttpClientEngineCapability<Unit>
167

168
/**
169
 * Indicates if a client engine supports extensions for WebSocket plugin
170
 */
171
data object WebSocketExtensionsCapability : HttpClientEngineCapability<Unit>
172
```
173

174
### Constants
175

176
```kotlin { .api }
177
/** Constant indicating disabled ping (0L) */
178
const val PINGER_DISABLED: Long = 0L
179
```
180

181
## Configuration Examples
182

183
### Basic Configuration
184

185
```kotlin
186
val client = HttpClient {
187
    install(WebSockets)
188
}
189
```
190

191
### Advanced Configuration
192

193
```kotlin
194
val client = HttpClient {
195
    install(WebSockets) {
196
        // Enable ping every 30 seconds
197
        pingInterval = 30.seconds
198
        
199
        // Set 1MB frame size limit
200
        maxFrameSize = 1024 * 1024
201
        
202
        // Add JSON serialization support
203
        contentConverter = GsonWebsocketContentConverter()
204
        
205
        // Configure compression extension
206
        extensions {
207
            install(WebSocketDeflateExtension) {
208
                compressionLevel = Deflater.BEST_COMPRESSION
209
                serverNoContextTakeover = false
210
                clientNoContextTakeover = false
211
            }
212
        }
213
    }
214
}
215
```
216

217
### Milliseconds-based Configuration
218

219
```kotlin
220
val client = HttpClient {
221
    install(WebSockets) {
222
        // 45 second ping interval
223
        pingIntervalMillis = 45000
224
        
225
        // 512KB frame size limit  
226
        maxFrameSize = 512 * 1024
227
    }
228
}
229
```