0
# Ktor HTTP Client Core
1

2
Ktor HTTP Client Core is a powerful, asynchronous HTTP client library for Kotlin multiplatform applications. It provides comprehensive HTTP client capabilities including request/response handling, client configuration, content negotiation, and an extensible plugin system. The library supports multiple platforms (JVM, JavaScript, Native) with a coroutine-based API for non-blocking HTTP operations.
3

4
## Package Information
5

6
- **Package Name**: io.ktor:ktor-client-core-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: Add `implementation("io.ktor:ktor-client-core:2.3.13")` to your build.gradle.kts
10

11
## Core Imports
12

13
```kotlin
14
import io.ktor.client.*
15
import io.ktor.client.request.*
16
import io.ktor.client.statement.*
17
import io.ktor.client.plugins.*
18
```
19

20
For engine-specific implementations:
21

22
```kotlin
23
import io.ktor.client.engine.cio.*  // CIO engine
24
import io.ktor.client.engine.apache.*  // Apache engine
25
```
26

27
## Basic Usage
28

29
```kotlin
30
import io.ktor.client.*
31
import io.ktor.client.request.*
32
import io.ktor.client.statement.*
33

34
// Create a client
35
val client = HttpClient()
36

37
// Make a simple GET request
38
val response: HttpResponse = client.get("https://api.example.com/users")
39
val body: String = response.bodyAsText()
40

41
// Make a POST request with JSON
42
val postResponse = client.post("https://api.example.com/users") {
43
    header("Content-Type", "application/json")
44
    setBody("""{"name": "John", "email": "john@example.com"}""")
45
}
46

47
// Close the client when done
48
client.close()
49
```
50

51
## Architecture
52

53
Ktor HTTP Client is built around several key components:
54

55
- **HttpClient**: The main client class that coordinates HTTP operations
56
- **HttpClientEngine**: Pluggable backend implementations (CIO, Apache, OkHttp, etc.)
57
- **Plugin System**: Extensible architecture for adding functionality like authentication, logging, caching
58
- **Pipeline Architecture**: Request and response processing pipelines for transformation and validation
59
- **Multiplatform Support**: Common API that works across JVM, JavaScript, and Native platforms
60

61
## Capabilities
62

63
### Client Creation and Configuration
64

65
Core client setup and configuration including engine selection, connection settings, and basic client lifecycle management.
66

67
```kotlin { .api }
68
class HttpClient(
69
    engine: HttpClientEngine = HttpClientEngineContainer.default,
70
    block: HttpClientConfig<*>.() -> Unit = {}
71
) : Closeable
72

73
fun HttpClient(
74
    block: HttpClientConfig<*>.() -> Unit = {}
75
): HttpClient
76

77
class HttpClientConfig<T : HttpClientEngineConfig>(
78
    val engine: HttpClientEngineFactory<T>
79
)
80
```
81

82
[Client Configuration](./client-configuration.md)
83

84
### HTTP Request Building
85

86
Comprehensive request building capabilities including HTTP methods, headers, parameters, and body content with type-safe DSL.
87

88
```kotlin { .api }
89
class HttpRequestBuilder {
90
    var method: HttpMethod
91
    val url: URLBuilder
92
    val headers: HeadersBuilder
93
    var body: OutgoingContent
94
}
95

96
suspend fun HttpClient.get(urlString: String): HttpResponse
97
suspend fun HttpClient.post(
98
    urlString: String,
99
    block: HttpRequestBuilder.() -> Unit = {}
100
): HttpResponse
101
```
102

103
[Request Building](./request-building.md)
104

105
### Response Handling
106

107
Complete response processing including content reading, status handling, and type-safe response body parsing.
108

109
```kotlin { .api }
110
abstract class HttpResponse : HttpMessage, CoroutineScope {
111
    abstract val status: HttpStatusCode
112
    abstract val version: HttpProtocolVersion
113
    abstract val requestTime: GMTDate
114
    abstract val responseTime: GMTDate
115
    abstract val call: HttpClientCall
116
}
117

118
suspend fun HttpResponse.bodyAsText(charset: Charset = Charsets.UTF_8): String
119
suspend fun HttpResponse.bodyAsBytes(): ByteArray
120
suspend fun HttpResponse.bodyAsChannel(): ByteReadChannel
121
```
122

123
[Response Handling](./response-handling.md)
124

125
### HTTP Client Call
126

127
Request-response pair management with call lifecycle and typed body receiving capabilities.
128

129
```kotlin { .api }
130
class HttpClientCall(
131
    val client: HttpClient,
132
    val request: HttpRequest,
133
    val response: HttpResponse
134
) : CoroutineScope {
135
    val attributes: Attributes
136
    
137
    suspend fun <T> body(): T
138
    suspend fun body(info: TypeInfo): Any
139
    suspend fun bodyNullable(info: TypeInfo): Any?
140
}
141

142
// Extension functions for response body handling
143
suspend fun <T> HttpResponse.body(): T
144
suspend fun <T> HttpResponse.body(typeInfo: TypeInfo): T
145
```
146

147
### Plugin System
148

149
Extensible plugin architecture for adding cross-cutting concerns like authentication, logging, caching, and content negotiation.
150

151
```kotlin { .api }
152
interface HttpClientPlugin<out TConfig : Any, TPlugin : Any> {
153
    val key: AttributeKey<TPlugin>
154
    fun prepare(block: TConfig.() -> Unit): TPlugin
155
    fun install(plugin: TPlugin, scope: HttpClient)
156
}
157

158
fun <TConfig : Any, TPlugin : Any> createClientPlugin(
159
    name: String,
160
    createConfiguration: () -> TConfig,
161
    body: ClientPluginBuilder<TConfig>.() -> TPlugin
162
): HttpClientPlugin<TConfig, TPlugin>
163
```
164

165
[Plugin System](./plugin-system.md)
166

167
### WebSocket Support
168

169
Full WebSocket client implementation with session management, message handling, and connection lifecycle.
170

171
```kotlin { .api }
172
object WebSockets : HttpClientPlugin<WebSockets.Config, WebSockets>
173

174
interface ClientWebSocketSession : WebSocketSession {
175
    val call: HttpClientCall
176
}
177

178
suspend fun HttpClient.webSocket(
179
    urlString: String,
180
    block: suspend ClientWebSocketSession.() -> Unit
181
)
182
```
183

184
[WebSocket Support](./websocket-support.md)
185

186
### HTTP Statement
187

188
Prepared statement functionality for reusable HTTP requests with lazy execution and type-safe response handling.
189

190
```kotlin { .api }
191
class HttpStatement(
192
    val builder: HttpRequestBuilder,
193
    val client: HttpClient
194
) {
195
    suspend fun execute(): HttpResponse
196
    suspend fun <T> execute(block: suspend (HttpResponse) -> T): T
197
    suspend fun <T> body(): T
198
    suspend fun <T, R> body(block: suspend (T) -> R): R
199
}
200
```
201

202
[HTTP Statement](./http-statement.md)
203

204
### Content Handling
205

206
Advanced content processing including form data, multipart uploads, progress monitoring, and content transformation.
207

208
```kotlin { .api }
209
sealed class OutgoingContent {
210
    class ByteArrayContent(val bytes: ByteArray) : OutgoingContent()
211
    class ReadChannelContent(val readFrom: ByteReadChannel) : OutgoingContent()
212
    class WriteChannelContent(
213
        val body: suspend ByteWriteChannel.() -> Unit
214
    ) : OutgoingContent()
215
}
216

217
class FormDataContent(val formData: Parameters) : OutgoingContent()
218
class MultiPartFormDataContent(val parts: List<PartData>) : OutgoingContent()
219
```
220

221
[Content Handling](./content-handling.md)
222

223
### HTTP Timeout
224

225
Timeout configuration plugin for request, connection, and socket timeouts with per-request customization.
226

227
```kotlin { .api }
228
object HttpTimeout : HttpClientPlugin<HttpTimeoutCapabilityConfiguration, HttpTimeout> {
229
    const val INFINITE_TIMEOUT_MS: Long
230
}
231

232
class HttpTimeoutCapabilityConfiguration {
233
    var requestTimeoutMillis: Long?
234
    var connectTimeoutMillis: Long?
235
    var socketTimeoutMillis: Long?
236
}
237

238
// Extension function for request-specific timeout
239
fun HttpRequestBuilder.timeout(block: HttpTimeoutCapabilityConfiguration.() -> Unit)
240
```
241

242
### Events and Monitoring
243

244
Client lifecycle events and monitoring hooks for observing request/response processing.
245

246
```kotlin { .api }
247
object ClientEvents {
248
    val HttpRequestCreated: EventDefinition<HttpRequestBuilder>
249
    val HttpRequestIsReadyForSending: EventDefinition<HttpRequestBuilder>
250
    val HttpResponseReceived: EventDefinition<HttpResponse>
251
    val HttpResponseReceiveFailed: EventDefinition<HttpResponseReceiveFail>
252
    val HttpResponseCancelled: EventDefinition<HttpResponse>
253
}
254

255
data class HttpResponseReceiveFail(
256
    val request: HttpRequest,
257
    val cause: Throwable
258
)
259
```
260

261
[Events and Monitoring](./events-monitoring.md)
262

263
### Engine Architecture
264

265
Client engine abstraction allowing different HTTP implementations with engine-specific configuration and capabilities.
266

267
```kotlin { .api }
268
interface HttpClientEngine : CoroutineScope, Closeable {
269
    val config: HttpClientEngineConfig
270
    val dispatcher: CoroutineDispatcher
271
    val supportedCapabilities: Set<HttpClientEngineCapability<*>>
272
    
273
    suspend fun execute(data: HttpRequestData): HttpResponseData
274
}
275

276
interface HttpClientEngineFactory<T : HttpClientEngineConfig> {
277
    fun create(block: T.() -> Unit = {}): HttpClientEngine
278
}
279
```
280

281
[Engine Architecture](./engine-architecture.md)
282

283
## Types
284

285
```kotlin { .api }
286
// Core client types
287
interface HttpRequest : HttpMessage, CoroutineScope {
288
    val call: HttpClientCall
289
    val method: HttpMethod
290
    val url: Url
291
    val attributes: Attributes
292
    val content: OutgoingContent
293
}
294

295
data class HttpRequestData(
296
    val url: Url,
297
    val method: HttpMethod,
298
    val headers: Headers,
299
    val body: OutgoingContent,
300
    val executionContext: Job,
301
    val attributes: Attributes
302
) {
303
    fun <T> getCapabilityOrNull(key: HttpClientEngineCapability<T>): T?
304
}
305

306
data class HttpResponseData(
307
    val statusCode: HttpStatusCode,
308
    val requestTime: GMTDate,
309
    val headers: Headers,
310
    val version: HttpProtocolVersion,
311
    val body: Any,
312
    val callContext: CoroutineContext
313
) {
314
    val responseTime: GMTDate
315
}
316

317
// Configuration types
318
open class HttpClientEngineConfig {
319
    var threadsCount: Int = 4
320
    var pipelining: Boolean = false
321
    var proxy: ProxyConfig? = null
322
}
323

324
// Base interfaces
325
interface HttpMessage {
326
    val headers: Headers
327
    val call: HttpClientCall
328
}
329

330
interface HttpClientEngineCapability<T>
331

332
// Plugin types
333
class AttributeKey<T>(val name: String)
334
data class Attributes(private val map: ConcurrentMap<AttributeKey<*>, Any>) {
335
    fun <T> get(key: AttributeKey<T>): T
336
    fun <T> getOrNull(key: AttributeKey<T>): T?
337
    fun <T> put(key: AttributeKey<T>, value: T)
338
    fun <T> remove(key: AttributeKey<T>): T?
339
    fun <T> computeIfAbsent(key: AttributeKey<T>, block: () -> T): T
340
    operator fun <T> contains(key: AttributeKey<T>): Boolean
341
}
342

343
// Exception types
344
class DoubleReceiveException(call: HttpClientCall) : IllegalStateException()
345
class NoTransformationFoundException(from: TypeInfo, to: TypeInfo) : UnsupportedOperationException()
346
class ReceivePipelineException(
347
    request: HttpRequest,
348
    info: TypeInfo,
349
    cause: Throwable
350
) : IllegalStateException()
351

352
// Timeout exception types
353
class HttpRequestTimeoutException(
354
    request: HttpRequestBuilder,
355
    timeoutMillis: Long
356
) : IOException()
357

358
class ConnectTimeoutException(
359
    request: HttpRequestData,
360
    timeoutMillis: Long
361
) : IOException()
362

363
class SocketTimeoutException(
364
    request: HttpRequestData
365
) : IOException()
366
```