0
# WebSocket Connections
1

2
Ktor Client WebSockets provides multiple functions for establishing WebSocket connections with different usage patterns and security options.
3

4
## Connection Functions
5

6
### webSocket() - Session with Block
7

8
Establishes a WebSocket connection and executes a block with the session, automatically closing the connection afterward:
9

10
```kotlin { .api }
11
suspend fun HttpClient.webSocket(
12
    method: HttpMethod = HttpMethod.Get,
13
    host: String? = null,
14
    port: Int? = null,
15
    path: String? = null,
16
    request: HttpRequestBuilder.() -> Unit = {},
17
    block: suspend DefaultClientWebSocketSession.() -> Unit
18
)
19

20
suspend fun HttpClient.webSocket(
21
    request: HttpRequestBuilder.() -> Unit,
22
    block: suspend DefaultClientWebSocketSession.() -> Unit
23
)
24

25
suspend fun HttpClient.webSocket(
26
    urlString: String,
27
    request: HttpRequestBuilder.() -> Unit = {},
28
    block: suspend DefaultClientWebSocketSession.() -> Unit
29
)
30
```
31

32
**Usage:**
33
```kotlin
34
client.webSocket(
35
    method = HttpMethod.Get,
36
    host = "echo.websocket.org",
37
    port = 80,
38
    path = "/"
39
) {
40
    send("Hello WebSocket!")
41
    val frame = incoming.receive()
42
    println("Received: ${frame}")
43
}
44
// Connection automatically closed after block completion
45
```
46

47
**URL string variant:**
48
```kotlin
49
client.webSocket("ws://echo.websocket.org/") {
50
    send("Hello from URL!")
51
    val response = incoming.receive()
52
    println("Response: $response")
53
}
54
```
55

56
### webSocketSession() - Manual Session Management
57

58
Creates a WebSocket session that must be manually managed and closed:
59

60
```kotlin { .api }
61
suspend fun HttpClient.webSocketSession(
62
    method: HttpMethod = HttpMethod.Get,
63
    host: String? = null,
64
    port: Int? = null,
65
    path: String? = null,
66
    block: HttpRequestBuilder.() -> Unit = {}
67
): DefaultClientWebSocketSession
68

69
suspend fun HttpClient.webSocketSession(
70
    block: HttpRequestBuilder.() -> Unit
71
): DefaultClientWebSocketSession
72

73
suspend fun HttpClient.webSocketSession(
74
    urlString: String,
75
    block: HttpRequestBuilder.() -> Unit = {}
76
): DefaultClientWebSocketSession
77
```
78

79
**Usage:**
80
```kotlin
81
val session = client.webSocketSession(
82
    host = "echo.websocket.org",
83
    port = 80,
84
    path = "/"
85
)
86

87
try {
88
    session.send("Manual session message")
89
    val frame = session.incoming.receive()
90
    println("Received: $frame")
91
} finally {
92
    session.close()
93
}
94
```
95

96
### ws() - Short Alias
97

98
Convenience alias for `webSocket()` with identical functionality:
99

100
```kotlin { .api }
101
suspend fun HttpClient.ws(
102
    method: HttpMethod = HttpMethod.Get,
103
    host: String? = null,
104
    port: Int? = null,
105
    path: String? = null,
106
    request: HttpRequestBuilder.() -> Unit = {},
107
    block: suspend DefaultClientWebSocketSession.() -> Unit
108
)
109

110
suspend fun HttpClient.ws(
111
    request: HttpRequestBuilder.() -> Unit,
112
    block: suspend DefaultClientWebSocketSession.() -> Unit
113
)
114

115
suspend fun HttpClient.ws(
116
    urlString: String,
117
    request: HttpRequestBuilder.() -> Unit = {},
118
    block: suspend DefaultClientWebSocketSession.() -> Unit
119
)
120
```
121

122
**Usage:**
123
```kotlin
124
client.ws("ws://echo.websocket.org/") {
125
    send("Short alias message")
126
    val frame = incoming.receive()
127
    println("Response: $frame")
128
}
129
```
130

131
### wss() - Secure WebSocket Connections
132

133
Establishes secure WebSocket connections over TLS/SSL:
134

135
```kotlin { .api }
136
suspend fun HttpClient.wss(
137
    method: HttpMethod = HttpMethod.Get,
138
    host: String? = null,
139
    port: Int? = null,
140
    path: String? = null,
141
    request: HttpRequestBuilder.() -> Unit = {},
142
    block: suspend DefaultClientWebSocketSession.() -> Unit
143
)
144

145
suspend fun HttpClient.wss(
146
    request: HttpRequestBuilder.() -> Unit,
147
    block: suspend DefaultClientWebSocketSession.() -> Unit
148
)
149

150
suspend fun HttpClient.wss(
151
    urlString: String,
152
    request: HttpRequestBuilder.() -> Unit = {},
153
    block: suspend DefaultClientWebSocketSession.() -> Unit
154
)
155
```
156

157
**Usage:**
158
```kotlin
159
client.wss(
160
    host = "secure.websocket.example.com",
161
    port = 443,
162
    path = "/secure-endpoint"
163
) {
164
    send("Secure message")
165
    val frame = incoming.receive()
166
    println("Secure response: $frame")
167
}
168
```
169

170
**URL string variant:**
171
```kotlin
172
client.wss("wss://secure.websocket.example.com/api/v1/socket") {
173
    send("Secure connection established")
174
    val response = incoming.receive()
175
    println("Secure response: $response")
176
}
177
```
178

179
## Request Configuration
180

181
All connection functions accept a request configuration block for customizing the WebSocket handshake:
182

183
### Headers
184

185
```kotlin
186
client.webSocket("ws://example.com/") {
187
    headers {
188
        append("Authorization", "Bearer $token")
189
        append("X-Custom-Header", "value")
190
    }
191
}
192
```
193

194
### URL Parameters
195

196
```kotlin
197
client.webSocket(
198
    host = "api.example.com",
199
    path = "/socket"
200
) {
201
    url {
202
        parameters.append("token", authToken)
203
        parameters.append("room", roomId)
204
    }
205
}
206
```
207

208
### Protocol and Port Override
209

210
```kotlin
211
client.webSocket("ws://example.com:8080/socket") {
212
    url {
213
        protocol = URLProtocol.WSS // Override to secure
214
        port = 443 // Override port
215
    }
216
}
217
```
218

219
## Connection Examples
220

221
### Basic Text Communication
222

223
```kotlin
224
client.webSocket("ws://echo.websocket.org/") {
225
    // Send text frame
226
    send("Hello WebSocket!")
227
    
228
    // Receive and process frames
229
    for (frame in incoming) {
230
        when (frame) {
231
            is Frame.Text -> {
232
                val text = frame.readText()
233
                println("Received text: $text")
234
                if (text == "exit") break
235
            }
236
            is Frame.Close -> {
237
                println("Connection closed: ${frame.readReason()}")
238
                break
239
            }
240
            else -> println("Received frame: $frame")
241
        }
242
    }
243
}
244
```
245

246
### Binary Data Transfer
247

248
```kotlin
249
client.webSocket("ws://example.com/binary") {
250
    // Send binary frame
251
    val data = "Binary data".toByteArray()
252
    send(Frame.Binary(true, data))
253
    
254
    // Receive binary frame
255
    val frame = incoming.receive()
256
    if (frame is Frame.Binary) {
257
        val receivedData = frame.data
258
        println("Received ${receivedData.size} bytes")
259
    }
260
}
261
```
262

263
### Authentication with Headers
264

265
```kotlin
266
client.webSocket("ws://secure.example.com/socket") {
267
    headers {
268
        append("Authorization", "Bearer $jwt")
269
        append("X-API-Key", apiKey)
270
    }
271
} {
272
    send("Authenticated connection established")
273
    
274
    for (frame in incoming) {
275
        when (frame) {
276
            is Frame.Text -> {
277
                handleMessage(frame.readText())
278
            }
279
            is Frame.Close -> break
280
            else -> { /* Handle other frame types */ }
281
        }
282
    }
283
}
284
```
285

286
### Connection with Custom Timeout
287

288
```kotlin
289
withTimeout(30.seconds) {
290
    client.webSocket("ws://example.com/socket") {
291
        timeout {
292
            requestTimeoutMillis = 15_000
293
            connectTimeoutMillis = 10_000
294
        }
295
    } {
296
        // WebSocket operations
297
        send("Message with timeout")
298
        val response = incoming.receive()
299
        println("Response: $response")
300
    }
301
}
302
```
303

304
## Error Handling
305

306
WebSocket connections can fail during handshake or operation:
307

308
```kotlin
309
try {
310
    client.webSocket("ws://unreliable.example.com/") {
311
        send("Test message")
312
        val frame = incoming.receive()
313
        println("Success: $frame")
314
    }
315
} catch (e: WebSocketException) {
316
    println("WebSocket error: ${e.message}")
317
} catch (e: ConnectTimeoutException) {
318
    println("Connection timeout: ${e.message}")
319
} catch (e: IOException) {
320
    println("Network error: ${e.message}")
321
}
322
```
323

324
## Connection Lifecycle
325

326
1. **Handshake**: HTTP upgrade request sent to server
327
2. **Protocol Switch**: HTTP connection upgraded to WebSocket
328
3. **Session Active**: Bidirectional frame communication
329
4. **Ping/Pong**: Automatic heartbeat (if configured)
330
5. **Close Handshake**: Graceful connection termination
331
6. **Cleanup**: Resources automatically released