0
# Client Configuration
1

2
Comprehensive client setup and configuration including engine selection, connection settings, timeout configuration, and client lifecycle management.
3

4
## Capabilities
5

6
### HttpClient Creation
7

8
Create HTTP client instances with optional engine and configuration.
9

10
```kotlin { .api }
11
/**
12
 * Creates an HTTP client with the specified engine and configuration
13
 * @param engine - The HTTP client engine to use (defaults to platform-specific engine)
14
 * @param block - Configuration block for client setup
15
 */
16
class HttpClient(
17
    engine: HttpClientEngine = HttpClientEngineContainer.default,
18
    block: HttpClientConfig<*>.() -> Unit = {}
19
) : Closeable
20

21
/**
22
 * Creates an HTTP client with default engine and configuration
23
 * @param block - Configuration block for client setup
24
 */
25
fun HttpClient(
26
    block: HttpClientConfig<*>.() -> Unit = {}
27
): HttpClient
28
```
29

30
**Usage Examples:**
31

32
```kotlin
33
import io.ktor.client.*
34
import io.ktor.client.engine.cio.*
35

36
// Default client
37
val client = HttpClient()
38

39
// Client with specific engine
40
val cioClient = HttpClient(CIO) {
41
    engine {
42
        maxConnectionsCount = 1000
43
        endpoint {
44
            maxConnectionsPerRoute = 100
45
        }
46
    }
47
}
48

49
// Client with configuration
50
val configuredClient = HttpClient {
51
    expectSuccess = false
52
    followRedirects = true
53
}
54
```
55

56
### HttpClientConfig
57

58
Main configuration class for HttpClient setup.
59

60
```kotlin { .api }
61
/**
62
 * Configuration class for HttpClient
63
 * @param T - Type of the engine configuration
64
 */
65
class HttpClientConfig<T : HttpClientEngineConfig>(
66
    val engine: HttpClientEngineFactory<T>
67
) {
68
    /** Whether to follow HTTP redirects automatically */
69
    var followRedirects: Boolean = true
70
    
71
    /** Whether to validate response status codes (throws exceptions for 4xx/5xx) */
72
    var expectSuccess: Boolean = true
73
    
74
    /** Whether to use default content transformers */
75
    var useDefaultTransformers: Boolean = true
76
    
77
    /** Development mode flag for enhanced debugging */
78
    var developmentMode: Boolean = false
79
    
80
    /** Clone this configuration */
81
    fun clone(): HttpClientConfig<T>
82
    
83
    /** Merge configuration from another config */
84
    operator fun plusAssign(other: HttpClientConfig<out T>)
85
}
86
```
87

88
### Engine Configuration
89

90
Configure the underlying HTTP engine.
91

92
```kotlin { .api }
93
/**
94
 * Configure the HTTP client engine
95
 * @param block - Engine configuration block
96
 */
97
fun <T : HttpClientEngineConfig> HttpClientConfig<T>.engine(
98
    block: T.() -> Unit
99
)
100

101
/**
102
 * Base configuration for HTTP client engines
103
 */
104
open class HttpClientEngineConfig {
105
    /** Number of threads for the engine */
106
    var threadsCount: Int = 4
107
    
108
    /** Whether to enable HTTP pipelining */
109
    var pipelining: Boolean = false
110
    
111
    /** Proxy configuration */
112
    var proxy: ProxyConfig? = null
113
}
114
```
115

116
### Plugin Installation
117

118
Install and configure client plugins.
119

120
```kotlin { .api }
121
/**
122
 * Install a plugin in the HTTP client
123
 * @param plugin - The plugin to install
124
 * @param configure - Configuration block for the plugin
125
 */
126
fun <TConfig : Any, TPlugin : Any> HttpClientConfig<*>.install(
127
    plugin: HttpClientPlugin<TConfig, TPlugin>,
128
    configure: TConfig.() -> Unit = {}
129
)
130

131
/**
132
 * Install a plugin by key
133
 * @param key - The plugin key
134
 * @param block - Configuration block
135
 */
136
fun <T : Any> HttpClientConfig<*>.install(
137
    key: AttributeKey<T>,
138
    block: () -> T
139
)
140
```
141

142
**Usage Examples:**
143

144
```kotlin
145
import io.ktor.client.plugins.*
146
import io.ktor.client.plugins.contentnegotiation.*
147
import io.ktor.client.plugins.logging.*
148

149
val client = HttpClient {
150
    // Install logging plugin
151
    install(Logging) {
152
        level = LogLevel.INFO
153
        logger = Logger.DEFAULT
154
    }
155
    
156
    // Install content negotiation
157
    install(ContentNegotiation) {
158
        json()
159
    }
160
    
161
    // Install default request plugin
162
    install(DefaultRequest) {
163
        header("User-Agent", "MyApp/1.0")
164
        host = "api.example.com"
165
        port = 443
166
    }
167
}
168
```
169

170
### Proxy Configuration
171

172
Configure HTTP proxy settings.
173

174
```kotlin { .api }
175
/**
176
 * Proxy configuration for HTTP client
177
 */
178
class ProxyConfig(
179
    val url: Url
180
) {
181
    constructor(host: String, port: Int) : this(URLBuilder().apply {
182
        this.host = host
183
        this.port = port
184
    }.build())
185
}
186

187
/**
188
 * Types of proxy configurations
189
 */
190
enum class ProxyType {
191
    HTTP, HTTPS, SOCKS
192
}
193
```
194

195
**Usage Examples:**
196

197
```kotlin
198
val client = HttpClient(CIO) {
199
    engine {
200
        proxy = ProxyConfig("proxy.example.com", 8080)
201
    }
202
}
203
```
204

205
### Client Lifecycle
206

207
Manage client lifecycle and resources.
208

209
```kotlin { .api }
210
/**
211
 * Close the HTTP client and release resources
212
 */
213
suspend fun HttpClient.close()
214

215
/**
216
 * Check if the client is closed
217
 */
218
val HttpClient.isClosed: Boolean
219
```
220

221
**Usage Examples:**
222

223
```kotlin
224
val client = HttpClient()
225

226
try {
227
    // Use client for requests
228
    val response = client.get("https://api.example.com")
229
} finally {
230
    // Always close the client
231
    client.close()
232
}
233

234
// Or use with try-with-resources pattern
235
HttpClient().use { client ->
236
    val response = client.get("https://api.example.com")
237
    // Client automatically closed
238
}
239
```
240

241
### Default Request Configuration
242

243
Set default parameters for all requests.
244

245
```kotlin { .api }
246
/**
247
 * Default request configuration plugin
248
 */
249
object DefaultRequest : HttpClientPlugin<DefaultRequest.Config, DefaultRequest>
250

251
/**
252
 * Configuration for default request parameters
253
 */
254
class DefaultRequest.Config {
255
    /** Default host */
256
    var host: String? = null
257
    
258
    /** Default port */
259
    var port: Int? = null
260
    
261
    /** Default headers */
262
    val headers: HeadersBuilder = HeadersBuilder()
263
    
264
    /** Default URL parameters */
265
    val url: URLBuilder = URLBuilder()
266
}
267
```
268

269
### Advanced Configuration
270

271
Advanced client configuration options and utilities.
272

273
```kotlin { .api }
274
/**
275
 * Configure client with engine factory
276
 */
277
fun <T : HttpClientEngineConfig> HttpClient(
278
    engineFactory: HttpClientEngineFactory<T>,
279
    block: HttpClientConfig<T>.() -> Unit = {}
280
): HttpClient
281

282
/**
283
 * Access client configuration after creation
284
 */
285
fun <T : HttpClientEngineConfig> HttpClient.config(
286
    block: HttpClientConfig<T>.() -> Unit
287
): HttpClient
288

289
/**
290
 * Check if client supports a specific capability
291
 */
292
fun HttpClient.isSupported(capability: HttpClientEngineCapability<*>): Boolean
293

294
/**
295
 * Access client attributes
296
 */
297
val HttpClient.attributes: Attributes
298

299
/**
300
 * Access client monitor for events
301
 */
302
val HttpClient.monitor: Events
303

304
/**
305
 * Access client's engine configuration
306
 */
307
val HttpClient.engineConfig: HttpClientEngineConfig
308

309
/**
310
 * Access client request pipeline
311
 */
312
val HttpClient.requestPipeline: HttpRequestPipeline
313

314
/**
315
 * Access client response pipeline
316
 */
317
val HttpClient.responsePipeline: HttpResponsePipeline
318

319
/**
320
 * Access client send pipeline
321
 */
322
val HttpClient.sendPipeline: HttpSendPipeline
323

324
/**
325
 * Access client receive pipeline
326
 */
327
val HttpClient.receivePipeline: HttpReceivePipeline
328
```
329

330
**Usage Examples:**
331

332
```kotlin
333
val client = HttpClient(CIO) {
334
    expectSuccess = false
335
    followRedirects = false
336
}
337

338
// Check capabilities
339
if (client.isSupported(HttpTimeout)) {
340
    println("Client supports timeout configuration")
341
}
342

343
// Access client attributes
344
client.attributes.put(MyCustomKey, "custom-value")
345

346
// Access pipelines for custom interceptors
347
client.requestPipeline.intercept(HttpRequestPipeline.Before) {
348
    // Custom request processing
349
}
350
```
351

352
## Types
353

354
```kotlin { .api }
355
// Engine factory and configuration types
356
interface HttpClientEngineFactory<T : HttpClientEngineConfig> {
357
    fun create(block: T.() -> Unit = {}): HttpClientEngine
358
}
359

360
// Pipeline types
361
class HttpRequestPipeline : Pipeline<Any, HttpRequestBuilder>
362
class HttpResponsePipeline : Pipeline<HttpResponseContainer, HttpClientCall>
363
class HttpSendPipeline : Pipeline<Any, HttpRequestBuilder>
364
class HttpReceivePipeline : Pipeline<HttpResponseContainer, HttpClientCall>
365

366
// Configuration types
367
class HttpClientEngineContainer {
368
    companion object {
369
        val default: HttpClientEngine
370
    }
371
}
372

373
// Client lifecycle types
374
interface Closeable {
375
    fun close()
376
}
377
```