0
# HTTP Client Management
1

2
Core client creation, configuration, and lifecycle management functionality for creating and managing HttpClient instances.
3

4
## Capabilities
5

6
### HttpClient Factory Functions
7

8
Creates HttpClient instances with various configuration options and engine selections.
9

10
```kotlin { .api }
11
/**
12
 * Creates an HttpClient with the default engine for the current platform
13
 * @param block Configuration block for the client
14
 * @return Configured HttpClient instance
15
 */
16
expect fun HttpClient(
17
    block: HttpClientConfig<*>.() -> Unit = {}
18
): HttpClient
19

20
/**
21
 * Creates an HttpClient with a specific engine factory
22
 * @param engineFactory The engine factory to use
23
 * @param block Configuration block for the client
24
 * @return Configured HttpClient instance
25
 */
26
fun <T : HttpClientEngineConfig> HttpClient(
27
    engineFactory: HttpClientEngineFactory<T>,
28
    block: HttpClientConfig<T>.() -> Unit = {}
29
): HttpClient
30

31
/**
32
 * Creates an HttpClient with a pre-configured engine instance
33
 * @param engine The engine instance to use
34
 * @param block Configuration block for the client
35
 * @return Configured HttpClient instance
36
 */
37
fun HttpClient(
38
    engine: HttpClientEngine,
39
    block: HttpClientConfig<*>.() -> Unit
40
): HttpClient
41
```
42

43
**Usage Examples:**
44

45
```kotlin
46
import io.ktor.client.*
47

48
// Default client with platform-specific engine
49
val client = HttpClient()
50

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

57
// Client with specific engine (example for JVM)
58
val jvmClient = HttpClient(CIO) {
59
    engine {
60
        threadsCount = 4
61
        pipelining = true
62
    }
63
}
64
```
65

66
### HttpClient Class
67

68
The main HTTP client class that manages the request/response lifecycle.
69

70
```kotlin { .api }
71
/**
72
 * Main HTTP client class providing HTTP request capabilities
73
 */
74
class HttpClient(
75
    val engine: HttpClientEngine,
76
    private val userConfig: HttpClientConfig<out HttpClientEngineConfig>
77
) : CoroutineScope, Closeable {
78
    
79
    /** Request processing pipeline */
80
    val requestPipeline: HttpRequestPipeline
81
    
82
    /** Response processing pipeline */
83
    val responsePipeline: HttpResponsePipeline
84
    
85
    /** Send pipeline for outgoing content */
86
    val sendPipeline: HttpSendPipeline
87
    
88
    /** Receive pipeline for incoming content */
89
    val receivePipeline: HttpReceivePipeline
90
    
91
    /** Client attributes for storing metadata */
92
    val attributes: Attributes
93
    
94
    /** Engine configuration */
95
    val engineConfig: HttpClientEngineConfig
96
    
97
    /** Event monitor for client events */
98
    val monitor: Events
99
    
100
    /**
101
     * Check if the client supports a specific capability
102
     * @param capability The capability to check
103
     * @return true if supported, false otherwise
104
     */
105
    fun isSupported(capability: HttpClientEngineCapability<*>): Boolean
106
    
107
    /**
108
     * Create a new client with additional configuration
109
     * @param block Configuration block to apply
110
     * @return New HttpClient instance with combined configuration
111
     */
112
    fun config(block: HttpClientConfig<*>.() -> Unit): HttpClient
113
    
114
    /**
115
     * Close the client and release resources
116
     * Must be called when the client is no longer needed
117
     */
118
    override fun close()
119
}
120
```
121

122
**Usage Examples:**
123

124
```kotlin
125
import io.ktor.client.*
126
import io.ktor.client.request.*
127

128
val client = HttpClient()
129

130
// Check engine capabilities
131
if (client.isSupported(WebSocketCapability)) {
132
    // Use WebSocket functionality
133
}
134

135
// Create derived client with additional config
136
val derivedClient = client.config {
137
    install(HttpTimeout) {
138
        requestTimeoutMillis = 5000
139
    }
140
}
141

142
// Always close clients when done
143
client.close()
144
derivedClient.close()
145
```
146

147
### HttpClientConfig Class
148

149
Configuration builder for customizing HttpClient behavior and installing plugins.
150

151
```kotlin { .api }
152
/**
153
 * Configuration builder for HttpClient
154
 */
155
class HttpClientConfig<T : HttpClientEngineConfig> {
156
    
157
    /** Whether to follow HTTP redirects automatically */
158
    var followRedirects: Boolean = true
159
    
160
    /** Whether to use default request/response transformers */
161
    var useDefaultTransformers: Boolean = true
162
    
163
    /** Whether to expect successful responses (2xx status codes) */
164
    var expectSuccess: Boolean = false
165
    
166
    /**
167
     * Configure the HTTP engine
168
     * @param block Configuration block for the engine
169
     */
170
    fun engine(block: T.() -> Unit)
171
    
172
    /**
173
     * Install a plugin with configuration
174
     * @param plugin The plugin to install
175
     * @param configure Configuration block for the plugin
176
     */
177
    fun <TBuilder : Any, TPlugin : Any> install(
178
        plugin: HttpClientPlugin<TBuilder, TPlugin>,
179
        configure: TBuilder.() -> Unit = {}
180
    )
181
    
182
    /**
183
     * Install a plugin by key with custom installation logic
184
     * @param key String identifier for the plugin
185
     * @param block Installation logic
186
     */
187
    fun install(key: String, block: HttpClient.() -> Unit)
188
}
189
```
190

191
**Usage Examples:**
192

193
```kotlin
194
import io.ktor.client.*
195
import io.ktor.client.plugins.*
196

197
val client = HttpClient {
198
    // Basic configuration
199
    followRedirects = false
200
    expectSuccess = true
201
    useDefaultTransformers = true
202
    
203
    // Engine configuration (platform-specific)
204
    engine {
205
        threadsCount = 2
206
        pipelining = false
207
    }
208
    
209
    // Plugin installation
210
    install(HttpTimeout) {
211
        requestTimeoutMillis = 30000
212
        connectTimeoutMillis = 10000
213
    }
214
    
215
    install(UserAgent) {
216
        agent = "MyApp/1.0"
217
    }
218
}
219
```
220

221
### Plugin Access Functions
222

223
Functions for accessing installed plugins from an HttpClient instance.
224

225
```kotlin { .api }
226
/**
227
 * Get an installed plugin, returning null if not installed
228
 * @param plugin The plugin to retrieve
229
 * @return Plugin instance or null if not installed
230
 */
231
fun <B : Any, F : Any> HttpClient.pluginOrNull(
232
    plugin: HttpClientPlugin<B, F>
233
): F?
234

235
/**
236
 * Get an installed plugin, throwing an exception if not installed
237
 * @param plugin The plugin to retrieve
238
 * @return Plugin instance
239
 * @throws IllegalStateException if plugin is not installed
240
 */
241
fun <B : Any, F : Any> HttpClient.plugin(
242
    plugin: HttpClientPlugin<B, F>
243
): F
244
```
245

246
**Usage Examples:**
247

248
```kotlin
249
import io.ktor.client.*
250
import io.ktor.client.plugins.*
251

252
val client = HttpClient {
253
    install(HttpTimeout) {
254
        requestTimeoutMillis = 5000
255
    }
256
}
257

258
// Safe access to plugin
259
val timeoutPlugin = client.pluginOrNull(HttpTimeout)
260
if (timeoutPlugin != null) {
261
    // Use plugin
262
}
263

264
// Direct access (throws if not installed)
265
val timeout = client.plugin(HttpTimeout)
266
```
267

268
## Types
269

270
Client management related types:
271

272
```kotlin { .api }
273
/**
274
 * Events interface for monitoring client activities
275
 */
276
interface Events {
277
    fun <T> subscribe(definition: EventDefinition<T>, handler: (T) -> Unit)
278
    fun <T> unsubscribe(definition: EventDefinition<T>, handler: (T) -> Unit)
279
    fun <T> raise(definition: EventDefinition<T>, value: T)
280
}
281

282
/**
283
 * Event definition for type-safe event handling
284
 */
285
interface EventDefinition<T>
286

287
/**
288
 * Client monitoring events
289
 */
290
val HttpRequestCreated: EventDefinition<HttpRequestBuilder>
291
val HttpRequestIsReadyForSending: EventDefinition<HttpRequestBuilder>
292
val HttpResponseReceived: EventDefinition<HttpResponse>
293
val HttpResponseCancelled: EventDefinition<HttpResponse>
294
val HttpResponseReceiveFailed: EventDefinition<HttpResponseReceiveFail>
295

296
/**
297
 * Event data for failed response reception
298
 */
299
class HttpResponseReceiveFail(
300
    val response: HttpResponse,
301
    val cause: Throwable
302
)
303
```