0
# Ktor Client CIO Engine
1

2
Ktor Client CIO Engine is a coroutine-based asynchronous HTTP client engine for Ktor that provides efficient I/O operations using Kotlin coroutines and native socket operations. It supports HTTP/1.1, WebSocket connections, Server-Sent Events, and TLS/SSL encryption with connection pooling and keep-alive functionality.
3

4
## Package Information
5

6
- **Package Name**: io.ktor:ktor-client-cio-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: `implementation("io.ktor:ktor-client-cio-jvm:3.2.0")`
10

11
## Core Imports
12

13
```kotlin
14
import io.ktor.client.*
15
import io.ktor.client.engine.cio.*
16
import io.ktor.network.tls.*
17
```
18

19
## Basic Usage
20

21
```kotlin
22
import io.ktor.client.*
23
import io.ktor.client.engine.cio.*
24
import io.ktor.client.request.*
25

26
// Create a client with CIO engine
27
val client = HttpClient(CIO)
28

29
// Make requests
30
val response = client.get("https://api.example.com/data")
31

32
// Configure the engine
33
val configuredClient = HttpClient(CIO) {
34
    engine {
35
        maxConnectionsCount = 1000
36
        requestTimeout = 15000
37
        endpoint {
38
            maxConnectionsPerRoute = 100
39
            connectTimeout = 5000
40
            keepAliveTime = 5000
41
        }
42
        https {
43
            // TLS configuration
44
        }
45
    }
46
}
47
```
48

49
## Architecture
50

51
The Ktor Client CIO Engine is built around several key components:
52

53
- **CIO Engine Factory**: Main entry point (`CIO` object) for creating engine instances
54
- **Configuration System**: `CIOEngineConfig` and `EndpointConfig` for comprehensive engine setup
55
- **Connection Management**: Efficient connection pooling, keep-alive, and HTTP pipelining
56
- **Protocol Support**: HTTP/1.1, WebSocket, Server-Sent Events, and Unix domain sockets
57
- **Platform Support**: Cross-platform with JVM, JavaScript (Node.js), and native platforms
58

59
## Capabilities
60

61
### Engine Configuration
62

63
Core engine configuration for connection management, timeouts, and performance tuning.
64

65
```kotlin { .api }
66
data object CIO : HttpClientEngineFactory<CIOEngineConfig> {
67
    override fun create(block: CIOEngineConfig.() -> Unit): HttpClientEngine
68
}
69

70
val supportedCapabilities: Set<HttpClientEngineCapability<out Any>> = setOf(
71
    HttpTimeoutCapability,
72
    WebSocketCapability,
73
    WebSocketExtensionsCapability,
74
    SSECapability,
75
    UnixSocketCapability
76
)
77
```
78

79
### Engine Settings
80

81
Primary configuration class for the CIO engine providing control over connections, timeouts, and HTTPS settings.
82

83
```kotlin { .api }
84
class CIOEngineConfig : HttpClientEngineConfig() {
85
    val endpoint: EndpointConfig
86
    val https: TLSConfigBuilder
87
    var maxConnectionsCount: Int
88
    var requestTimeout: Long
89
    
90
    fun https(block: TLSConfigBuilder.() -> Unit): TLSConfigBuilder
91
}
92

93
fun CIOEngineConfig.endpoint(block: EndpointConfig.() -> Unit): EndpointConfig
94
```
95

96
### Connection Configuration
97

98
Detailed endpoint configuration for connection behavior, timeouts, and performance optimization.
99

100
```kotlin { .api }
101
class EndpointConfig {
102
    var maxConnectionsPerRoute: Int
103
    var keepAliveTime: Long
104
    var pipelineMaxSize: Int
105
    var connectTimeout: Long
106
    var socketTimeout: Long
107
    var connectAttempts: Int
108
    
109
    @Deprecated("Half closed TCP connection is not supported by all servers, use it at your own risk.")
110
    var allowHalfClose: Boolean
111
}
112
```
113

114
### WebSocket Extensions (JVM)
115

116
Raw WebSocket functionality for low-level WebSocket operations without automatic ping-pong handling.
117

118
```kotlin { .api }
119
suspend fun HttpClient.webSocketRawSession(
120
    method: HttpMethod = HttpMethod.Get,
121
    host: String? = null,
122
    port: Int? = null,
123
    path: String? = null,
124
    block: HttpRequestBuilder.() -> Unit = {}
125
): ClientWebSocketSession
126

127
suspend fun HttpClient.webSocketRaw(
128
    method: HttpMethod = HttpMethod.Get,
129
    host: String? = null,
130
    port: Int? = null,
131
    path: String? = null,
132
    request: HttpRequestBuilder.() -> Unit = {},
133
    block: suspend ClientWebSocketSession.() -> Unit
134
)
135
```
136

137
[WebSocket Extensions](./websocket-extensions.md)
138

139
### Exception Handling
140

141
Engine-specific exceptions for connection and timeout scenarios.
142

143
```kotlin { .api }
144
class FailToConnectException : Exception("Connect timed out or retry attempts exceeded")
145
```
146

147
### Server-Sent Events Support
148

149
Support for Server-Sent Events (SSE) connections through the SSECapability.
150

151
### Unix Domain Socket Support
152

153
Support for Unix domain socket connections through the UnixSocketCapability.
154

155
### Proxy Support
156

157
Support for HTTP proxy connections. SOCKS proxies are not currently supported.
158

159
## Types
160

161
### Engine Factory
162

163
```kotlin { .api }
164
data object CIO : HttpClientEngineFactory<CIOEngineConfig> {
165
    override fun create(block: CIOEngineConfig.() -> Unit): HttpClientEngine
166
}
167
```
168

169
### Configuration Classes
170

171
```kotlin { .api }
172
class CIOEngineConfig : HttpClientEngineConfig() {
173
    /** Access to endpoint settings */
174
    val endpoint: EndpointConfig
175
    
176
    /** HTTPS/TLS configuration */
177
    val https: TLSConfigBuilder
178
    
179
    /** Maximum number of connections for requests (default: 1000) */
180
    var maxConnectionsCount: Int
181
    
182
    /** Request timeout in milliseconds (default: 15000) */
183
    var requestTimeout: Long
184
    
185
    /** Configure HTTPS settings */
186
    fun https(block: TLSConfigBuilder.() -> Unit): TLSConfigBuilder
187
}
188

189
class EndpointConfig {
190
    /** Maximum connections per host (default: 100) */
191
    var maxConnectionsPerRoute: Int
192
    
193
    /** Connection keep-alive time in milliseconds (default: 5000) */
194
    var keepAliveTime: Long
195
    
196
    /** Maximum requests for HTTP pipelining (default: 20) */
197
    var pipelineMaxSize: Int
198
    
199
    /** Connection establishment timeout in milliseconds (default: 5000) */
200
    var connectTimeout: Long
201
    
202
    /** Socket inactivity timeout in milliseconds (default: INFINITE_TIMEOUT_MS) */
203
    var socketTimeout: Long
204
    
205
    /** Maximum connection retry attempts (default: 1) */
206
    var connectAttempts: Int
207
    
208
    /** Allow half-closed TCP connections (default: false, deprecated) */
209
    @Deprecated("Half closed TCP connection is not supported by all servers, use it at your own risk.")
210
    var allowHalfClose: Boolean
211
}
212
```
213

214
### Engine Container (JVM)
215

216
```kotlin { .api }
217
class CIOEngineContainer : HttpClientEngineContainer {
218
    override val factory: HttpClientEngineFactory<*>
219
    override fun toString(): String
220
}
221
```
222

223
### TLS Configuration
224

225
```kotlin { .api }
226
class TLSConfigBuilder {
227
    /** List of client certificate chains with private keys */
228
    val certificates: MutableList<CertificateAndKey>
229
    
230
    /** SecureRandom to use in encryption */
231
    var random: SecureRandom?
232
    
233
    /** Custom X509TrustManager to verify server authority */
234
    var trustManager: TrustManager?
235
    
236
    /** List of allowed CipherSuites */
237
    var cipherSuites: List<CipherSuite>
238
    
239
    /** Custom server name for TLS server name extension */
240
    var serverName: String?
241
    
242
    /** Create TLSConfig */
243
    fun build(): TLSConfig
244
}
245

246
/** Append config from another builder */
247
fun TLSConfigBuilder.takeFrom(other: TLSConfigBuilder)
248

249
/** Add client certificate chain to use */
250
fun TLSConfigBuilder.addCertificateChain(chain: Array<X509Certificate>, key: PrivateKey)
251

252
/** Add client certificates from KeyStore */
253
fun TLSConfigBuilder.addKeyStore(store: KeyStore, password: CharArray?, alias: String? = null)
254
```
255

256
### Extension Functions
257

258
```kotlin { .api }
259
/** Configure endpoint settings */
260
fun CIOEngineConfig.endpoint(block: EndpointConfig.() -> Unit): EndpointConfig
261
```