0
# Engine Configuration
1

2
Platform-specific engine abstraction providing the underlying HTTP implementation with configurable connection pooling, proxy support, and platform optimizations.
3

4
## Capabilities
5

6
### HttpClientEngine Interface
7

8
Core engine interface providing the underlying HTTP transport implementation.
9

10
```kotlin { .api }
11
/**
12
 * HTTP client engine interface for platform-specific implementations
13
 */
14
interface HttpClientEngine : CoroutineScope, Closeable {
15
    /** I/O operations dispatcher */
16
    val dispatcher: CoroutineDispatcher
17
    
18
    /** Engine configuration */
19
    val config: HttpClientEngineConfig
20
    
21
    /** Set of supported engine capabilities */
22
    val supportedCapabilities: Set<HttpClientEngineCapability<*>>
23
}
24
```
25

26
### HttpClientEngineFactory Interface
27

28
Factory interface for creating engine instances with configuration.
29

30
```kotlin { .api }
31
/**
32
 * Factory for creating HTTP client engine instances
33
 */
34
interface HttpClientEngineFactory<out T : HttpClientEngineConfig> {
35
    /**
36
     * Create engine instance with configuration
37
     */
38
    fun create(block: T.() -> Unit = {}): HttpClientEngine
39
}
40

41
/**
42
 * Create a configured engine factory
43
 */
44
fun <T : HttpClientEngineConfig> HttpClientEngineFactory<T>.config(
45
    nested: T.() -> Unit
46
): HttpClientEngineFactory<T>
47
```
48

49
**Usage Examples:**
50

51
```kotlin
52
import io.ktor.client.engine.cio.*
53

54
// Create engine with factory
55
val engine = CIO.create {
56
    maxConnectionsCount = 1000
57
    requestTimeout = 30_000
58
}
59

60
// Create configured factory
61
val configuredFactory = CIO.config {
62
    maxConnectionsCount = 500
63
    endpoint {
64
        maxConnectionsPerRoute = 100
65
    }
66
}
67

68
val client = HttpClient(configuredFactory)
69
```
70

71
### HttpClientEngineConfig Class
72

73
Base configuration class for all HTTP client engines.
74

75
```kotlin { .api }
76
/**
77
 * Base configuration for HTTP client engines
78
 */
79
open class HttpClientEngineConfig {
80
    /** Network threads count - deprecated, use engine-specific configuration */
81
    @Deprecated("Use engine-specific configuration instead")
82
    var threadsCount: Int = 4
83
    
84
    /** HTTP pipelining advice (not all engines support this) */
85
    var pipelining: Boolean = false
86
    
87
    /** Proxy configuration */
88
    var proxy: ProxyConfig? = null
89
}
90
```
91

92
**Usage Examples:**
93

94
```kotlin
95
val client = HttpClient(CIO) {
96
    engine {
97
        // Base engine configuration
98
        pipelining = true
99
        proxy = ProxyBuilder.http("http://proxy.example.com:8080")
100
        
101
        // CIO-specific configuration
102
        maxConnectionsCount = 1000
103
        requestTimeout = 30_000
104
        
105
        endpoint {
106
            maxConnectionsPerRoute = 100
107
            pipelineMaxSize = 20
108
            keepAliveTime = 5000
109
            connectTimeout = 5000
110
            connectAttempts = 5
111
        }
112
    }
113
}
114
```
115

116
### Proxy Configuration
117

118
Comprehensive proxy support for HTTP and SOCKS proxies.
119

120
```kotlin { .api }
121
/**
122
 * Proxy configuration - platform-specific implementation
123
 */
124
expect class ProxyConfig {
125
    val type: ProxyType
126
    fun resolveAddress(): NetworkAddress
127
}
128

129
/**
130
 * Proxy type enumeration
131
 */
132
enum class ProxyType {
133
    SOCKS, HTTP, UNKNOWN
134
}
135

136
/**
137
 * Proxy builder for creating proxy configurations
138
 */
139
expect object ProxyBuilder {
140
    /**
141
     * Create HTTP proxy configuration from URL
142
     */
143
    fun http(url: Url): ProxyConfig
144
    
145
    /**
146
     * Create HTTP proxy configuration from URL string
147
     */
148
    fun http(urlString: String): ProxyConfig
149
    
150
    /**
151
     * Create SOCKS proxy configuration
152
     */
153
    fun socks(host: String, port: Int): ProxyConfig
154
}
155
```
156

157
**Usage Examples:**
158

159
```kotlin
160
import io.ktor.client.engine.*
161

162
// HTTP proxy
163
val httpProxy = ProxyBuilder.http("http://proxy.example.com:8080")
164
val httpsProxy = ProxyBuilder.http("https://secure-proxy.example.com:8443")
165

166
// SOCKS proxy
167
val socksProxy = ProxyBuilder.socks("socks-proxy.example.com", 1080)
168

169
// Use proxy in client
170
val client = HttpClient(CIO) {
171
    engine {
172
        proxy = httpProxy
173
    }
174
}
175

176
// Check proxy type
177
when (httpProxy.type) {
178
    ProxyType.HTTP -> println("Using HTTP proxy")
179
    ProxyType.SOCKS -> println("Using SOCKS proxy")
180
    ProxyType.UNKNOWN -> println("Unknown proxy type")
181
}
182
```
183

184
### Engine Capabilities
185

186
System for advertising and checking engine-specific features.
187

188
```kotlin { .api }
189
/**
190
 * Interface for engine capabilities
191
 */
192
interface HttpClientEngineCapability<T>
193

194
/**
195
 * Check if client supports a capability
196
 */
197
fun HttpClient.isSupported(capability: HttpClientEngineCapability<*>): Boolean
198

199
/**
200
 * Set capability in request builder
201
 */
202
fun <T> HttpRequestBuilder.setCapability(
203
    key: HttpClientEngineCapability<T>, 
204
    capability: T
205
)
206

207
/**
208
 * Get capability from request builder
209
 */
210
fun <T> HttpRequestBuilder.getCapabilityOrNull(
211
    key: HttpClientEngineCapability<T>
212
): T?
213
```
214

215
**Usage Examples:**
216

217
```kotlin
218
// Check engine capabilities
219
val client = HttpClient(CIO)
220

221
if (client.isSupported(WebSocketCapability)) {
222
    println("WebSocket is supported")
223
}
224

225
if (client.isSupported(HttpTimeoutCapability)) {
226
    println("Timeout configuration is supported")
227
}
228

229
// Set capability in request
230
client.get("https://api.example.com/data") {
231
    setCapability(SomeEngineCapability, capabilityValue)
232
}
233
```
234

235
### Platform-Specific Engines
236

237
Overview of available engines for different platforms.
238

239
```kotlin { .api }
240
// JVM Engines
241
// CIO - Coroutine-based I/O engine (pure Kotlin)
242
// Apache - Apache HttpClient engine
243
// OkHttp - OkHttp engine
244
// Jetty - Jetty HttpClient engine
245

246
// JavaScript Engine
247
// Js - Browser fetch API or Node.js
248

249
// Native Engines  
250
// Curl - libcurl-based engine for native platforms
251
// Darwin - URLSession-based engine for iOS/macOS
252
```
253

254
**Usage Examples:**
255

256
```kotlin
257
// JVM - CIO Engine (recommended)
258
import io.ktor.client.engine.cio.*
259
val cioClient = HttpClient(CIO) {
260
    engine {
261
        maxConnectionsCount = 1000
262
        requestTimeout = 30_000
263
    }
264
}
265

266
// JVM - OkHttp Engine
267
import io.ktor.client.engine.okhttp.*
268
val okHttpClient = HttpClient(OkHttp) {
269
    engine {
270
        config {
271
            retryOnConnectionFailure(true)
272
            connectTimeout(30, TimeUnit.SECONDS)
273
        }
274
    }
275
}
276

277
// JavaScript Engine
278
import io.ktor.client.engine.js.*
279
val jsClient = HttpClient(Js) {
280
    engine {
281
        // JavaScript-specific configuration
282
    }
283
}
284

285
// Native - Darwin Engine (iOS/macOS)
286
import io.ktor.client.engine.darwin.*
287
val darwinClient = HttpClient(Darwin) {
288
    engine {
289
        configureRequest {
290
            setAllowsCellularAccess(true)
291
        }
292
    }
293
}
294
```
295

296
### Engine Configuration Examples
297

298
Detailed configuration examples for different use cases.
299

300
```kotlin { .api }
301
// Production configuration example
302
val productionClient = HttpClient(CIO) {
303
    engine {
304
        // Connection pool settings
305
        maxConnectionsCount = 1000
306
        
307
        // Timeouts
308
        requestTimeout = 30_000
309
        
310
        // Per-endpoint configuration
311
        endpoint {
312
            maxConnectionsPerRoute = 100
313
            pipelineMaxSize = 20
314
            keepAliveTime = 5000
315
            connectTimeout = 5000
316
            connectAttempts = 5
317
        }
318
        
319
        // Proxy for corporate environment
320
        proxy = ProxyBuilder.http("http://corporate-proxy.com:8080")
321
    }
322
    
323
    // Additional configuration
324
    followRedirects = true
325
    expectSuccess = false
326
}
327

328
// Development configuration example
329
val developmentClient = HttpClient(CIO) {
330
    engine {
331
        // Relaxed settings for development
332
        maxConnectionsCount = 100
333
        requestTimeout = 60_000 // Longer timeout for debugging
334
        
335
        endpoint {
336
            connectTimeout = 10_000
337
            connectAttempts = 3
338
        }
339
    }
340
    
341
    // Development mode features
342
    developmentMode = true
343
}
344

345
// High-performance configuration
346
val highPerfClient = HttpClient(CIO) {
347
    engine {
348
        // Optimized for high throughput
349
        maxConnectionsCount = 2000
350
        
351
        endpoint {
352
            maxConnectionsPerRoute = 200
353
            pipelineMaxSize = 50
354
            keepAliveTime = 10_000
355
        }
356
        
357
        // Disable pipelining for compatibility
358
        pipelining = false
359
    }
360
}
361
```