0
# HTTP Client Configuration
1

2
Comprehensive configuration options for HttpClient including engines, timeouts, redirects, and plugin installation.
3

4
## Capabilities
5

6
### HttpClient Factory Functions
7

8
Create HttpClient instances with various configuration options.
9

10
```kotlin { .api }
11
/**
12
 * Creates an HttpClient with default engine using service loader
13
 * @param block Configuration block for client settings
14
 * @returns Configured HttpClient instance
15
 */
16
fun HttpClient(block: HttpClientConfig<*>.() -> Unit = {}): HttpClient
17

18
/**
19
 * Creates an HttpClient with specified engine factory
20
 * @param engineFactory Factory for creating the HTTP engine
21
 * @param block Configuration block for engine-specific settings
22
 * @returns Configured HttpClient instance
23
 */
24
fun <T : HttpClientEngineConfig> HttpClient(
25
    engineFactory: HttpClientEngineFactory<T>,
26
    block: HttpClientConfig<T>.() -> Unit = {}
27
): HttpClient
28

29
/**
30
 * Creates an HttpClient with pre-configured engine instance
31
 * @param engine Pre-configured HTTP engine
32
 * @param block Configuration block for client settings
33
 * @returns Configured HttpClient instance
34
 */
35
fun HttpClient(
36
    engine: HttpClientEngine,
37
    block: HttpClientConfig<*>.() -> Unit
38
): HttpClient
39
```
40

41
**Usage Examples:**
42

43
```kotlin
44
// Basic client with default settings
45
val client = HttpClient()
46

47
// Client with configuration
48
val configuredClient = HttpClient {
49
    expectSuccess = true
50
    followRedirects = false
51
    
52
    install(HttpTimeout) {
53
        requestTimeoutMillis = 30000
54
        connectTimeoutMillis = 10000
55
    }
56
}
57

58
// Client with specific engine (requires engine dependency)
59
val engineClient = HttpClient(SomeEngine) {
60
    engine {
61
        // Engine-specific configuration
62
        threadsCount = 4
63
        pipelining = true
64
    }
65
}
66
```
67

68
### HttpClientConfig Class
69

70
Main configuration class for HttpClient with global settings and plugin management.
71

72
```kotlin { .api }
73
/**
74
 * Configuration class for HttpClient with settings and plugin management
75
 */
76
class HttpClientConfig<T : HttpClientEngineConfig> {
77
    /** Whether to follow HTTP redirects automatically (default: true) */
78
    var followRedirects: Boolean
79
    
80
    /** Whether to use default body transformers (default: true) */
81
    var useDefaultTransformers: Boolean
82
    
83
    /** Whether to throw exceptions for non-successful HTTP status codes (default: false) */
84
    var expectSuccess: Boolean
85
    
86
    /**
87
     * Configure engine-specific settings
88
     * @param block Configuration block for the engine
89
     */
90
    fun engine(block: T.() -> Unit)
91
    
92
    /**
93
     * Install a plugin with optional configuration
94
     * @param plugin The plugin to install
95
     * @param configure Configuration block for the plugin
96
     */
97
    fun <TBuilder : Any, TPlugin : Any> install(
98
        plugin: HttpClientPlugin<TBuilder, TPlugin>,
99
        configure: TBuilder.() -> Unit = {}
100
    )
101
    
102
    /**
103
     * Install a custom interceptor with a unique key
104
     * @param key Unique identifier for the interceptor
105
     * @param block Interceptor implementation
106
     */
107
    fun install(key: String, block: HttpClient.() -> Unit)
108
    
109
    /**
110
     * Create a copy of this configuration
111
     * @returns Cloned configuration
112
     */
113
    fun clone(): HttpClientConfig<T>
114
}
115
```
116

117
### Engine Configuration
118

119
Base configuration for HTTP client engines.
120

121
```kotlin { .api }
122
/**
123
 * Base configuration class for HTTP client engines
124
 */
125
open class HttpClientEngineConfig {
126
    /** Connection timeout in milliseconds */
127
    var connectTimeout: Long
128
    
129
    /** Socket timeout in milliseconds */
130
    var socketTimeout: Long
131
    
132
    /** Request timeout in milliseconds */
133
    var requestTimeout: Long
134
    
135
    /** Number of threads in the engine thread pool */
136
    var threadsCount: Int
137
    
138
    /** Whether to enable HTTP pipelining */
139
    var pipelining: Boolean
140
    
141
    /** Proxy configuration */
142
    var proxy: ProxyConfig?
143
}
144

145
/**
146
 * Proxy configuration for HTTP requests
147
 */
148
sealed class ProxyConfig {
149
    data class HttpProxy(
150
        val address: SocketAddress,
151
        val credentials: Credentials?
152
    ) : ProxyConfig()
153
    
154
    data class SocksProxy(
155
        val address: SocketAddress,
156
        val credentials: Credentials?
157
    ) : ProxyConfig()
158
}
159

160
/**
161
 * Proxy builder utilities
162
 */
163
object ProxyBuilder {
164
    /**
165
     * Create HTTP proxy configuration
166
     * @param url Proxy URL (e.g., "http://proxy.example.com:8080")
167
     * @returns HttpProxy configuration
168
     */
169
    fun http(url: String): ProxyConfig.HttpProxy
170
    
171
    /**
172
     * Create SOCKS proxy configuration
173
     * @param host Proxy host
174
     * @param port Proxy port
175
     * @returns SocksProxy configuration
176
     */
177
    fun socks(host: String, port: Int): ProxyConfig.SocksProxy
178
}
179
```
180

181
**Usage Examples:**
182

183
```kotlin
184
val client = HttpClient {
185
    // Basic configuration
186
    followRedirects = true
187
    expectSuccess = false
188
    useDefaultTransformers = true
189
    
190
    // Engine configuration
191
    engine {
192
        connectTimeout = 10000
193
        socketTimeout = 15000
194
        threadsCount = 4
195
        pipelining = true
196
        proxy = ProxyBuilder.http("http://proxy.example.com:8080")
197
    }
198
    
199
    // Install plugins
200
    install(HttpTimeout) {
201
        requestTimeoutMillis = 30000
202
        connectTimeoutMillis = 10000
203
        socketTimeoutMillis = 15000
204
    }
205
    
206
    install(HttpRedirect) {
207
        checkHttpMethod = true
208
        allowHttpsDowngrade = false
209
        maxJumps = 20
210
    }
211
}
212
```
213

214
### Client Configuration Methods
215

216
Additional methods for runtime configuration and client management.
217

218
```kotlin { .api }
219
/**
220
 * Create a new client by copying this client's configuration
221
 * @param block Additional configuration to apply
222
 * @returns New HttpClient instance
223
 */
224
fun HttpClient.config(block: HttpClientConfig<*>.() -> Unit): HttpClient
225

226
/**
227
 * Check if the client supports a specific engine capability
228
 * @param capability The capability to check
229
 * @returns True if supported, false otherwise
230
 */
231
fun HttpClient.isSupported(capability: HttpClientEngineCapability<*>): Boolean
232

233
/**
234
 * Close the client and release resources
235
 */
236
fun HttpClient.close()
237
```
238

239
**Usage Examples:**
240

241
```kotlin
242
val originalClient = HttpClient()
243

244
// Create a new client with additional configuration
245
val enhancedClient = originalClient.config {
246
    install(HttpCookies) {
247
        storage = AcceptAllCookiesStorage()
248
    }
249
}
250

251
// Check engine capabilities
252
val supportsWebSockets = client.isSupported(WebSocketCapability)
253

254
// Always close clients when done
255
client.close()
256
```
257

258
### Default Request Configuration
259

260
Configure default parameters applied to all requests.
261

262
```kotlin { .api }
263
/**
264
 * Configure default request parameters
265
 */
266
fun HttpClientConfig<*>.defaultRequest(block: HttpRequestBuilder.() -> Unit)
267
```
268

269
**Usage Examples:**
270

271
```kotlin
272
val client = HttpClient {
273
    defaultRequest {
274
        url("https://api.example.com/")
275
        header("User-Agent", "MyApp/1.0")
276
        header("Accept", "application/json")
277
        
278
        // Default timeout for all requests
279
        timeout {
280
            requestTimeoutMillis = 30000
281
        }
282
    }
283
}
284

285
// Now all requests will include the default configuration
286
val response = client.get("users") // Requests https://api.example.com/users
287
```
288

289
## Types
290

291
### Configuration Types
292

293
```kotlin { .api }
294
/**
295
 * Credentials for proxy authentication
296
 */
297
data class Credentials(
298
    val username: String,
299
    val password: String
300
)
301

302
/**
303
 * Socket address for proxy configuration
304
 */
305
data class SocketAddress(
306
    val hostname: String,
307
    val port: Int
308
)
309

310
/**
311
 * Engine capability marker interface
312
 */
313
interface HttpClientEngineCapability<T>
314

315
/**
316
 * Engine factory interface
317
 */
318
interface HttpClientEngineFactory<T : HttpClientEngineConfig> {
319
    fun create(block: T.() -> Unit = {}): HttpClientEngine
320
}
321
```