0
# Ktor Client WebSockets
1

2
Ktor Client WebSockets provides comprehensive WebSocket client capabilities for Kotlin applications running on Linux x64 platforms. As part of the Ktor framework, it enables full-duplex, real-time communication between clients and servers over a single TCP connection with native performance optimizations.
3

4
## Package Information
5

6
- **Package Name**: ktor-client-websockets-linuxx64
7
- **Package Type**: Maven
8
- **Language**: Kotlin
9
- **Platform**: Linux x64 (Native)
10
- **Installation**: Add to your `build.gradle.kts`:
11

12
```kotlin
13
dependencies {
14
    implementation("io.ktor:ktor-client-websockets-linuxx64:3.2.0")
15
}
16
```
17

18
## Core Imports
19

20
```kotlin
21
import io.ktor.client.*
22
import io.ktor.client.plugins.websocket.*
23
import io.ktor.websocket.*
24
```
25

26
For WebSocket frames:
27

28
```kotlin
29
import io.ktor.websocket.Frame
30
import io.ktor.websocket.FrameType
31
```
32

33
## Basic Usage
34

35
```kotlin
36
import io.ktor.client.*
37
import io.ktor.client.plugins.websocket.*
38
import io.ktor.websocket.*
39
import kotlin.time.Duration.Companion.seconds
40

41
// Install WebSocket plugin
42
val client = HttpClient {
43
    install(WebSockets) {
44
        pingInterval = 30.seconds
45
        maxFrameSize = 1024 * 1024 // 1MB
46
    }
47
}
48

49
// Connect and use WebSocket
50
client.webSocket("ws://echo.websocket.org") {
51
    // Send text message
52
    send("Hello WebSocket!")
53
    
54
    // Receive messages
55
    for (frame in incoming) {
56
        when (frame) {
57
            is Frame.Text -> println("Received: ${frame.readText()}")
58
            is Frame.Binary -> println("Received binary: ${frame.data.size} bytes")
59
            is Frame.Close -> break
60
        }
61
    }
62
}
63

64
client.close()
65
```
66

67
## Architecture
68

69
Ktor WebSocket client is built around several key components:
70

71
- **Plugin System**: WebSocket functionality is provided as a client plugin that integrates with Ktor's HTTP client
72
- **Session Management**: WebSocket connections are managed through session interfaces with lifecycle control
73
- **Frame Processing**: Low-level WebSocket frame handling with support for text, binary, and control frames
74
- **Extension Support**: Pluggable WebSocket extensions system for protocol enhancements
75
- **Serialization**: Content converter integration for automatic serialization/deserialization
76
- **Coroutine Integration**: Full async/await support using Kotlin coroutines
77

78
## Capabilities
79

80
### Plugin Configuration
81

82
WebSocket plugin installation and configuration with ping intervals, frame size limits, and extension support.
83

84
```kotlin { .api }
85
class WebSockets internal constructor(
86
    val pingIntervalMillis: Long,
87
    val maxFrameSize: Long,
88
    val contentConverter: WebsocketContentConverter? = null
89
) : HttpClientPlugin<WebSockets.Config, WebSockets>
90

91
class Config {
92
    var pingIntervalMillis: Long
93
    var maxFrameSize: Long
94
    var contentConverter: WebsocketContentConverter?
95
    var pingInterval: Duration?
96
    fun extensions(block: WebSocketExtensionsConfig.() -> Unit)
97
}
98

99
fun HttpClientConfig<*>.WebSockets(config: WebSockets.Config.() -> Unit)
100
```
101

102
[Plugin Configuration](./plugin-configuration.md)
103

104
### WebSocket Connections
105

106
Core connection establishment functions for creating WebSocket sessions with various configuration options.
107

108
```kotlin { .api }
109
suspend fun HttpClient.webSocket(
110
    request: HttpRequestBuilder.() -> Unit,
111
    block: suspend DefaultClientWebSocketSession.() -> Unit
112
)
113

114
suspend fun HttpClient.webSocketSession(
115
    block: HttpRequestBuilder.() -> Unit
116
): DefaultClientWebSocketSession
117

118
suspend fun HttpClient.ws(
119
    host: String? = null,
120
    port: Int? = null, 
121
    path: String? = null,
122
    block: suspend DefaultClientWebSocketSession.() -> Unit
123
)
124

125
suspend fun HttpClient.wss(
126
    host: String? = null,
127
    port: Int? = null,
128
    path: String? = null, 
129
    block: suspend DefaultClientWebSocketSession.() -> Unit
130
)
131
```
132

133
[WebSocket Connections](./websocket-connections.md)
134

135
### Session Management
136

137
WebSocket session interfaces providing frame-level control and connection lifecycle management.
138

139
```kotlin { .api }
140
interface ClientWebSocketSession : WebSocketSession {
141
    val call: HttpClientCall
142
}
143

144
class DefaultClientWebSocketSession(
145
    override val call: HttpClientCall,
146
    delegate: DefaultWebSocketSession
147
) : ClientWebSocketSession, DefaultWebSocketSession
148

149
interface WebSocketSession : CoroutineScope {
150
    var masking: Boolean
151
    var maxFrameSize: Long
152
    val incoming: ReceiveChannel<Frame>
153
    val outgoing: SendChannel<Frame>
154
    val extensions: List<WebSocketExtension<*>>
155
}
156
```
157

158
[Session Management](./session-management.md)
159

160
### Frame Operations
161

162
Low-level WebSocket frame handling for text, binary, and control frame processing.
163

164
```kotlin { .api }
165
sealed class Frame {
166
    val fin: Boolean
167
    val frameType: FrameType
168
    val data: ByteArray
169
    val rsv1: Boolean
170
    val rsv2: Boolean  
171
    val rsv3: Boolean
172
    
173
    class Text(text: String) : Frame
174
    class Binary(fin: Boolean, data: ByteArray) : Frame
175
    class Close : Frame
176
    class Ping(data: ByteArray) : Frame
177
    class Pong(data: ByteArray) : Frame
178
}
179

180
enum class FrameType(val controlFrame: Boolean, val opcode: Int) {
181
    TEXT, BINARY, CLOSE, PING, PONG
182
}
183

184
fun Frame.Text.readText(): String
185
fun Frame.readBytes(): ByteArray
186
fun Frame.Close.readReason(): CloseReason?
187
```
188

189
[Frame Operations](./frame-operations.md)
190

191
### Serialization Support
192

193
Content converter integration for automatic serialization/deserialization of objects to/from WebSocket frames.
194

195
```kotlin { .api }
196
suspend fun DefaultClientWebSocketSession.sendSerialized(data: Any?, typeInfo: TypeInfo)
197
suspend inline fun <reified T> DefaultClientWebSocketSession.sendSerialized(data: T)
198

199
suspend fun <T> DefaultClientWebSocketSession.receiveDeserialized(typeInfo: TypeInfo): T  
200
suspend inline fun <reified T> DefaultClientWebSocketSession.receiveDeserialized(): T
201

202
val DefaultClientWebSocketSession.converter: WebsocketContentConverter?
203
```
204

205
[Serialization Support](./serialization-support.md)
206

207
## Types
208

209
### WebSocket Configuration Types
210

211
```kotlin { .api }
212
interface WebsocketContentConverter {
213
    suspend fun serialize(
214
        charset: Charset,
215
        typeInfo: TypeInfo,
216
        value: Any?
217
    ): Frame
218
    
219
    suspend fun deserialize(
220
        charset: Charset,
221
        typeInfo: TypeInfo,
222
        content: Frame
223
    ): Any?
224
}
225

226
data object WebSocketCapability : HttpClientEngineCapability<Unit>
227
data object WebSocketExtensionsCapability : HttpClientEngineCapability<Unit>
228
```
229

230
### WebSocket Constants
231

232
```kotlin { .api }
233
/** Constant indicating that WebSocket pinger is disabled */
234
const val PINGER_DISABLED: Long = 0
235
```
236

237
### Exception Types
238

239
```kotlin { .api }
240
class WebSocketException(message: String, cause: Throwable?) : IllegalStateException
241

242
class ProtocolViolationException(message: String) : Exception
243

244
class FrameTooBigException(message: String) : Exception
245
```
246

247
### Extension Types
248

249
```kotlin { .api }
250
interface WebSocketExtension<ConfigType : Any> {
251
    val protocols: List<WebSocketExtensionHeader>
252
    fun clientNegotiation(extensions: List<WebSocketExtensionHeader>): Boolean
253
}
254

255
interface WebSocketExtensionFactory<ConfigType : Any, ExtensionType : WebSocketExtension<ConfigType>>
256

257
class WebSocketExtensionsConfig {
258
    fun <Config : Any, Extension : WebSocketExtension<Config>> install(
259
        extension: WebSocketExtensionFactory<Config, Extension>,
260
        configure: Config.() -> Unit = {}
261
    )
262
}
263

264
class WebSocketExtensionHeader(val name: String, val parameters: List<String>)
265

266
/** Parse WebSocket extension headers from HTTP header value */
267
fun parseWebSocketExtensions(value: String): List<WebSocketExtensionHeader>
268
```
269

270
## Error Handling
271

272
WebSocket operations can throw several types of exceptions:
273

274
- **WebSocketException**: General WebSocket protocol errors, handshake failures, or connection issues
275
- **ProtocolViolationException**: WebSocket protocol compliance violations
276
- **FrameTooBigException**: Frame size exceeds configured maximum
277
- **ClosedReceiveChannelException**: Channel closed while receiving
278
- **WebsocketConverterNotFoundException**: No content converter available for serialization
279
- **WebsocketDeserializeException**: Deserialization failed for received frame