0
# WebSocket Extensions
1

2
Raw WebSocket functionality specifically designed for the Ktor Client CIO engine on JVM platform. These extensions provide low-level WebSocket operations without automatic ping-pong handling, giving developers full control over the WebSocket connection lifecycle.
3

4
**Note**: These extensions are only available on the JVM platform.
5

6
## Capabilities
7

8
### Raw WebSocket Session Creation
9

10
Creates a raw `ClientWebSocketSession` without automatic ping-pong and service message handling.
11

12
```kotlin { .api }
13
/**
14
 * Creates a raw ClientWebSocketSession: no ping-pong and other service messages are used.
15
 * @param method HTTP method for the WebSocket handshake (default: HttpMethod.Get)
16
 * @param host Target host (optional, can be null)
17
 * @param port Target port (optional, can be null)
18
 * @param path URL path for the WebSocket endpoint (optional, can be null)
19
 * @param block Configuration block for the HTTP request builder
20
 * @returns ClientWebSocketSession for direct interaction
21
 */
22
suspend fun HttpClient.webSocketRawSession(
23
    method: HttpMethod = HttpMethod.Get,
24
    host: String? = null,
25
    port: Int? = null,
26
    path: String? = null,
27
    block: HttpRequestBuilder.() -> Unit = {}
28
): ClientWebSocketSession
29
```
30

31
**Usage Example:**
32

33
```kotlin
34
import io.ktor.client.*
35
import io.ktor.client.engine.cio.*
36
import io.ktor.client.plugins.websocket.cio.*
37

38
val client = HttpClient(CIO)
39

40
val session = client.webSocketRawSession(
41
    host = "echo.websocket.org",
42
    port = 443,
43
    path = "/"
44
) {
45
    // Configure the WebSocket handshake request
46
    headers {
47
        append("Authorization", "Bearer token")
48
    }
49
}
50

51
// Use the session directly
52
session.send(Frame.Text("Hello, WebSocket!"))
53
val response = session.incoming.receive()
54
session.close()
55
```
56

57
### Raw WebSocket with Block Execution
58

59
Creates and executes a raw WebSocket session with automatic session management.
60

61
```kotlin { .api }
62
/**
63
 * Creates a raw ClientWebSocketSession: no ping-pong and other service messages are used.
64
 * @param method HTTP method for the WebSocket handshake (default: HttpMethod.Get)
65
 * @param host Target host (optional, can be null)
66
 * @param port Target port (optional, can be null)
67
 * @param path URL path for the WebSocket endpoint (optional, can be null)
68
 * @param request Configuration block for the HTTP request builder
69
 * @param block Suspend block that operates on the WebSocket session
70
 */
71
suspend fun HttpClient.webSocketRaw(
72
    method: HttpMethod = HttpMethod.Get,
73
    host: String? = null,
74
    port: Int? = null,
75
    path: String? = null,
76
    request: HttpRequestBuilder.() -> Unit = {},
77
    block: suspend ClientWebSocketSession.() -> Unit
78
)
79
```
80

81
**Usage Example:**
82

83
```kotlin
84
client.webSocketRaw(
85
    host = "echo.websocket.org",
86
    port = 443,
87
    path = "/",
88
    request = {
89
        headers {
90
            append("Authorization", "Bearer token")
91
        }
92
    }
93
) {
94
    // WebSocket session operations
95
    send(Frame.Text("Hello from CIO WebSocket!"))
96
    
97
    for (frame in incoming) {
98
        when (frame) {
99
            is Frame.Text -> {
100
                val text = frame.readText()
101
                println("Received: $text")
102
                if (text == "bye") break
103
            }
104
            is Frame.Close -> break
105
            else -> continue
106
        }
107
    }
108
}
109
```
110

111
### Insecure WebSocket (ws://)
112

113
Convenience function for creating raw WebSocket connections over insecure `ws://` protocol.
114

115
```kotlin { .api }
116
/**
117
 * Creates a raw ClientWebSocketSession: no ping-pong and other service messages are used.
118
 * @param method HTTP method for the WebSocket handshake (default: HttpMethod.Get)
119
 * @param host Target host (optional, can be null)
120
 * @param port Target port (optional, can be null)
121
 * @param path URL path for the WebSocket endpoint (optional, can be null)
122
 * @param request Configuration block for the HTTP request builder
123
 * @param block Suspend block that operates on the WebSocket session
124
 */
125
suspend fun HttpClient.wsRaw(
126
    method: HttpMethod = HttpMethod.Get,
127
    host: String? = null,
128
    port: Int? = null,
129
    path: String? = null,
130
    request: HttpRequestBuilder.() -> Unit = {},
131
    block: suspend ClientWebSocketSession.() -> Unit
132
)
133
```
134

135
**Usage Example:**
136

137
```kotlin
138
client.wsRaw(
139
    host = "localhost",
140
    port = 8080,
141
    path = "/websocket"
142
) {
143
    send(Frame.Text("Testing insecure WebSocket"))
144
    val response = incoming.receive()
145
    println("Response: ${(response as Frame.Text).readText()}")
146
}
147
```
148

149
### Secure WebSocket (wss://)
150

151
Convenience function for creating raw WebSocket connections over secure `wss://` protocol.
152

153
```kotlin { .api }
154
/**
155
 * Create secure raw ClientWebSocketSession: no ping-pong and other service messages are used.
156
 * @param method HTTP method for the WebSocket handshake (default: HttpMethod.Get)
157
 * @param host Target host (optional, can be null)
158
 * @param port Target port (optional, can be null)
159
 * @param path URL path for the WebSocket endpoint (optional, can be null)
160
 * @param request Configuration block for the HTTP request builder
161
 * @param block Suspend block that operates on the WebSocket session
162
 */
163
suspend fun HttpClient.wssRaw(
164
    method: HttpMethod = HttpMethod.Get,
165
    host: String? = null,
166
    port: Int? = null,
167
    path: String? = null,
168
    request: HttpRequestBuilder.() -> Unit = {},
169
    block: suspend ClientWebSocketSession.() -> Unit
170
)
171
```
172

173
**Usage Example:**
174

175
```kotlin
176
client.wssRaw(
177
    host = "secure.websocket.org",
178
    port = 443,
179
    path = "/secure-chat"
180
) {
181
    send(Frame.Text("Secure WebSocket message"))
182
    
183
    while (true) {
184
        val frame = incoming.receive()
185
        when (frame) {
186
            is Frame.Text -> {
187
                println("Secure message: ${frame.readText()}")
188
            }
189
            is Frame.Close -> {
190
                println("Connection closed")
191
                break
192
            }
193
            else -> continue
194
        }
195
    }
196
}
197
```
198

199
## Integration Notes
200

201
### Raw vs Standard WebSocket
202

203
These raw WebSocket extensions differ from Ktor's standard WebSocket plugin in several key ways:
204

205
- **No automatic ping-pong**: You must handle ping/pong frames manually if needed
206
- **No automatic close handling**: Connection lifecycle is entirely under your control
207
- **Direct frame access**: All WebSocket frames are exposed without filtering
208
- **Manual session management**: You're responsible for proper session cleanup
209

210
### Error Handling
211

212
When using raw WebSocket extensions, handle exceptions appropriately:
213

214
```kotlin
215
try {
216
    client.webSocketRaw(host = "example.com") {
217
        // WebSocket operations
218
    }
219
} catch (e: Exception) {
220
    // Handle connection errors, protocol violations, etc.
221
    println("WebSocket error: ${e.message}")
222
}
223
```
224

225
### Platform Limitations
226

227
These WebSocket extensions are **JVM-only**. For other platforms, use Ktor's standard WebSocket plugin or platform-specific WebSocket implementations.
228

229
## Types
230

231
### Import Dependencies
232

233
```kotlin
234
import io.ktor.client.*
235
import io.ktor.client.plugins.websocket.cio.*
236
import io.ktor.http.*
237
import io.ktor.client.request.*
238
import io.ktor.websocket.*
239
```
240

241
All WebSocket extension functions are available in the `io.ktor.client.plugins.websocket.cio` package and require the Ktor Client CIO engine to function properly.