0
# Plugin Configuration
1

2
WebSocket plugin installation and configuration for Ktor HTTP client, providing control over connection behavior, frame processing, and content serialization.
3

4
## Capabilities
5

6
### WebSockets Plugin Installation
7

8
Install the WebSocket plugin with configuration options for ping intervals, frame size limits, and content conversion.
9

10
```kotlin { .api }
11
/**
12
 * Install WebSockets plugin using configuration block
13
 */
14
fun HttpClientConfig<*>.WebSockets(config: WebSockets.Config.() -> Unit)
15

16
/**
17
 * Main WebSocket plugin class
18
 */
19
class WebSockets internal constructor(
20
    val pingIntervalMillis: Long,
21
    val maxFrameSize: Long,
22
    private val extensionsConfig: WebSocketExtensionsConfig,
23
    val contentConverter: WebsocketContentConverter? = null
24
)
25

26
/**
27
 * Public constructors for WebSockets plugin
28
 */
29
constructor(
30
    pingIntervalMillis: Long = PINGER_DISABLED,
31
    maxFrameSize: Long = Int.MAX_VALUE.toLong()
32
)
33

34
constructor()
35
```
36

37
**Usage Examples:**
38

39
```kotlin
40
import io.ktor.client.*
41
import io.ktor.client.plugins.websocket.*
42

43
// Basic installation with default settings
44
val client = HttpClient {
45
    install(WebSockets)
46
}
47

48
// Installation with custom configuration
49
val client = HttpClient {
50
    install(WebSockets) {
51
        pingIntervalMillis = 30_000  // 30 seconds
52
        maxFrameSize = 1024 * 1024   // 1MB
53
    }
54
}
55
```
56

57
### Configuration Class
58

59
Configuration builder for WebSocket plugin settings.
60

61
```kotlin { .api }
62
/**
63
 * WebSockets plugin configuration
64
 */
65
@KtorDsl
66
class Config {
67
    /**
68
     * Sets interval of sending ping frames. Use PINGER_DISABLED to disable ping.
69
     */
70
    var pingIntervalMillis: Long = PINGER_DISABLED
71
    
72
    /**
73
     * Sets maximum frame size in bytes
74
     */
75
    var maxFrameSize: Long = Int.MAX_VALUE.toLong()
76
    
77
    /**
78
     * A converter for serialization/deserialization
79
     */
80
    var contentConverter: WebsocketContentConverter? = null
81
    
82
    /**
83
     * Configure WebSocket extensions
84
     */
85
    fun extensions(block: WebSocketExtensionsConfig.() -> Unit)
86
}
87
```
88

89
**Usage Examples:**
90

91
```kotlin
92
// Configure ping and frame size
93
val client = HttpClient {
94
    install(WebSockets) {
95
        pingIntervalMillis = 20_000
96
        maxFrameSize = 2 * 1024 * 1024  // 2MB
97
    }
98
}
99

100
// Configure with content converter
101
val client = HttpClient {
102
    install(WebSockets) {
103
        contentConverter = JsonWebsocketContentConverter()
104
        pingIntervalMillis = 15_000
105
    }
106
}
107
```
108

109
### Duration-based Configuration
110

111
Alternative constructor and configuration using Kotlin Duration API for more readable time specifications.
112

113
```kotlin { .api }
114
/**
115
 * Creates WebSocket plugin with Duration-based ping interval
116
 */
117
fun WebSockets(
118
    pingInterval: Duration?,
119
    maxFrameSize: Long = Int.MAX_VALUE.toLong()
120
): WebSockets
121

122
/**
123
 * Extension property for getting ping interval as Duration
124
 */
125
val WebSockets.pingInterval: Duration?
126

127
/**
128
 * Extension property for configuring ping interval using Duration
129
 */
130
var WebSockets.Config.pingInterval: Duration?
131
```
132

133
**Usage Examples:**
134

135
```kotlin
136
import kotlin.time.Duration.Companion.seconds
137
import kotlin.time.Duration.Companion.minutes
138

139
// Using Duration API in configuration
140
val client = HttpClient {
141
    install(WebSockets) {
142
        pingInterval = 30.seconds
143
        maxFrameSize = 1024 * 1024
144
    }
145
}
146

147
// Direct constructor with Duration
148
val plugin = WebSockets(
149
    pingInterval = 1.minutes,
150
    maxFrameSize = 512 * 1024
151
)
152
```
153

154
### Plugin Companion Object
155

156
Plugin installation companion implementing HttpClientPlugin interface.
157

158
```kotlin { .api }
159
/**
160
 * WebSockets plugin companion object
161
 */
162
companion object Plugin : HttpClientPlugin<Config, WebSockets> {
163
    override val key: AttributeKey<WebSockets>
164
    
165
    /**
166
     * Prepare plugin instance from configuration
167
     */
168
    override fun prepare(block: Config.() -> Unit): WebSockets
169
    
170
    /**
171
     * Install plugin in HTTP client
172
     */
173
    override fun install(plugin: WebSockets, scope: HttpClient)
174
}
175
```
176

177
### Engine Capabilities
178

179
Capability objects indicating WebSocket support in HTTP client engines.
180

181
```kotlin { .api }
182
/**
183
 * Indicates if a client engine supports WebSockets
184
 */
185
data object WebSocketCapability : HttpClientEngineCapability<Unit>
186

187
/**
188
 * Indicates if a client engine supports extensions for WebSocket plugin
189
 */
190
data object WebSocketExtensionsCapability : HttpClientEngineCapability<Unit>
191
```
192

193
### Exception Types
194

195
Exception class for WebSocket-related errors.
196

197
```kotlin { .api }
198
/**
199
 * Exception thrown during WebSocket operations
200
 */
201
class WebSocketException(message: String, cause: Throwable?) : IllegalStateException {
202
    constructor(message: String) : this(message, cause = null)
203
}
204
```
205

206
## Constants
207

208
```kotlin { .api }
209
/**
210
 * Constant value used to disable ping functionality (value: 0)
211
 */
212
const val PINGER_DISABLED: Long = 0
213
```