0
# Ktor HTTP Client Core
1

2
Ktor HTTP Client Core is a multiplatform asynchronous HTTP client library written in Kotlin that provides comprehensive HTTP communication capabilities with full coroutines support. It enables developers to make HTTP requests across multiple platforms including JVM, JavaScript, Native (including tvOS ARM64), with a plugin-based architecture for extensibility.
3

4
## Package Information
5

6
- **Package Name**: io.ktor:ktor-client-core-tvosarm64
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Platforms**: JVM, JavaScript, Native (tvOS ARM64, iOS, Android, etc.)
10
- **Installation**: Add to your `build.gradle.kts` dependencies
11

12
```kotlin
13
dependencies {
14
    implementation("io.ktor:ktor-client-core-tvosarm64:3.2.0")
15
}
16
```
17

18
## Core Imports
19

20
```kotlin { .api }
21
import io.ktor.client.*
22
import io.ktor.client.request.*
23
import io.ktor.client.statement.*
24
import io.ktor.client.plugins.*
25
import io.ktor.client.engine.*
26
```
27

28
## Basic Usage
29

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

35
// Create client
36
val client = HttpClient()
37

38
// Make requests
39
val response: HttpResponse = client.get("https://api.example.com/users")
40
val text: String = response.bodyAsText()
41

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

48
// Don't forget to close the client
49
client.close()
50
```
51

52
## Architecture
53

54
Ktor HTTP Client Core is built around several key architectural components:
55

56
- **HttpClient**: Main client interface providing HTTP method convenience functions and lifecycle management
57
- **Engine Abstraction**: Pluggable HTTP engines for different platforms (CIO, OkHttp, Curl, Fetch, etc.)
58
- **Plugin System**: Extensible plugin architecture for cross-cutting concerns (authentication, caching, retries, etc.)
59
- **Pipeline Processing**: Request and response pipeline with interceptor support for transformations
60
- **Multiplatform Design**: Common API with platform-specific implementations using expect/actual declarations
61
- **Coroutine Integration**: Full async/await support with proper cancellation and context propagation
62

63
## Capabilities
64

65
### HTTP Client Core
66

67
Core HTTP client functionality including client creation, configuration, request execution, and lifecycle management. Provides convenience methods for all HTTP verbs and advanced request building.
68

69
```kotlin { .api }
70
// HttpClient factory functions
71
expect fun HttpClient(block: HttpClientConfig<*>.() -> Unit = {}): HttpClient
72

73
fun <T : HttpClientEngineConfig> HttpClient(
74
    engineFactory: HttpClientEngineFactory<T>,
75
    block: HttpClientConfig<T>.() -> Unit = {}
76
): HttpClient
77

78
fun HttpClient(
79
    engine: HttpClientEngine,
80
    block: HttpClientConfig<*>.() -> Unit
81
): HttpClient
82

83
// HttpClient class
84
class HttpClient(
85
    public val engine: HttpClientEngine,
86
    private val userConfig: HttpClientConfig<out HttpClientEngineConfig> = HttpClientConfig()
87
) : CoroutineScope, Closeable {
88
    public val attributes: Attributes
89
    public val engineConfig: HttpClientEngineConfig
90
    public val monitor: Events
91
    public val requestPipeline: HttpRequestPipeline
92
    public val responsePipeline: HttpResponsePipeline
93
    public val sendPipeline: HttpSendPipeline
94
    public val receivePipeline: HttpReceivePipeline
95
    
96
    public fun isSupported(capability: HttpClientEngineCapability<*>): Boolean
97
    public fun config(block: HttpClientConfig<*>.() -> Unit): HttpClient
98
    override fun close()
99
}
100
```
101

102
[HTTP Client Core](./http-client.md)
103

104
### Request Building
105

106
Request building API providing type-safe DSL for constructing HTTP requests with URL configuration, headers, parameters, and body content.
107

108
```kotlin { .api }
109
class HttpRequestBuilder {
110
    var method: HttpMethod
111
    val url: URLBuilder
112
    val headers: HeadersBuilder
113
    
114
    fun parameter(key: String, value: Any?)
115
    fun header(key: String, value: String)
116
    fun accept(contentType: ContentType)
117
    fun contentType(contentType: ContentType)
118
    fun userAgent(agent: String)
119
    fun setBody(body: Any)
120
}
121

122
interface HttpRequest {
123
    val call: HttpClientCall
124
    val attributes: Attributes
125
    val content: OutgoingContent
126
    val headers: Headers
127
    val method: HttpMethod
128
    val url: Url
129
}
130
```
131

132
[Request Building](./request-building.md)
133

134
### Response Handling
135

136
Response handling API for accessing response data, headers, status, and converting response bodies to various types with streaming support.
137

138
```kotlin { .api }
139
abstract class HttpResponse {
140
    abstract val call: HttpClientCall
141
    abstract val content: ByteReadChannel
142
    abstract val coroutineContext: CoroutineContext
143
    abstract val headers: Headers
144
    abstract val requestTime: GMTDate
145
    abstract val responseTime: GMTDate
146
    abstract val status: HttpStatusCode
147
    abstract val version: HttpProtocolVersion
148
}
149

150
class HttpStatement(
151
    private val builder: HttpRequestBuilder,
152
    private val client: HttpClient
153
) {
154
    suspend fun execute(): HttpResponse
155
    suspend fun <T> execute(block: suspend HttpResponse.() -> T): T
156
}
157

158
// Response extension functions
159
suspend fun HttpResponse.bodyAsText(): String
160
suspend fun HttpResponse.bodyAsBytes(): ByteArray
161
fun HttpResponse.bodyAsChannel(): ByteReadChannel
162
```
163

164
[Response Handling](./response-handling.md)
165

166
### Engine Configuration
167

168
HTTP engine abstraction layer allowing pluggable HTTP implementations across platforms with configuration for connection management, proxies, and platform-specific settings.
169

170
```kotlin { .api }
171
interface HttpClientEngine : CoroutineScope, Closeable {
172
    val config: HttpClientEngineConfig
173
    val dispatcher: CoroutineDispatcher
174
    suspend fun execute(data: HttpRequestData): HttpResponseData
175
}
176

177
interface HttpClientEngineFactory<T : HttpClientEngineConfig> {
178
    fun create(block: T.() -> Unit = {}): HttpClientEngine
179
}
180

181
open class HttpClientEngineConfig {
182
    var threadsCount: Int = 4
183
    var pipelining: Boolean = false
184
    var proxy: ProxyConfig? = null
185
}
186

187
interface HttpClientEngineCapability<T>
188
```
189

190
[Engine Configuration](./engine-configuration.md)
191

192
### Plugin System
193

194
Extensible plugin architecture for adding cross-cutting functionality like authentication, caching, retries, logging, and custom request/response processing.
195

196
```kotlin { .api }
197
interface HttpClientPlugin<TConfig : Any, TPlugin : Any> {
198
    val key: AttributeKey<TPlugin>
199
    fun prepare(block: TConfig.() -> Unit = {}): TPlugin
200
    fun install(plugin: TPlugin, scope: HttpClient)
201
}
202

203
// Plugin installation
204
fun <T : HttpClientEngineConfig> HttpClientConfig<T>.install(
205
    plugin: HttpClientPlugin<*, *>,
206
    configure: Any.() -> Unit = {}
207
)
208
```
209

210
[Plugin System](./plugin-system.md)
211

212
### Built-in Plugins
213

214
Collection of built-in plugins for common HTTP client functionality including redirects, retries, timeouts, user agent, default requests, response validation, and plain text handling.
215

216
```kotlin { .api }
217
object HttpRedirect : HttpClientPlugin<HttpRedirect.Config, HttpRedirect>
218
object HttpRequestRetry : HttpClientPlugin<HttpRequestRetry.Config, HttpRequestRetry>
219
object HttpTimeout : HttpClientPlugin<HttpTimeout.Config, HttpTimeout>
220
object UserAgent : HttpClientPlugin<UserAgent.Config, UserAgent>
221
object DefaultRequest : HttpClientPlugin<DefaultRequest.Config, DefaultRequest>
222
object HttpCallValidator : HttpClientPlugin<HttpCallValidator.Config, HttpCallValidator>
223
object HttpPlainText : HttpClientPlugin<HttpPlainText.Config, HttpPlainText>
224
object HttpSend : HttpClientPlugin<HttpSend.Config, HttpSend>
225
object DataConversion : HttpClientPlugin<DataConversion.Config, DataConversion>
226
object BodyProgress : HttpClientPlugin<BodyProgress.Config, BodyProgress>
227
```
228

229
[Built-in Plugins](./builtin-plugins.md)
230

231
### Cookies Support
232

233
Cookie management functionality with configurable storage backends for automatic cookie handling across requests with support for custom storage implementations.
234

235
```kotlin { .api }
236
object HttpCookies : HttpClientPlugin<HttpCookies.Config, HttpCookies>
237

238
interface CookiesStorage {
239
    suspend fun get(requestUrl: Url): List<Cookie>
240
    suspend fun addCookie(requestUrl: Url, cookie: Cookie)
241
    fun close()
242
}
243

244
class AcceptAllCookiesStorage : CookiesStorage
245
class ConstantCookiesStorage(cookies: List<Cookie>) : CookiesStorage
246
```
247

248
[Cookies Support](./cookies.md)
249

250
### Caching
251

252
HTTP response caching functionality with configurable storage backends and cache control header support for improving performance and reducing network requests.
253

254
```kotlin { .api }
255
object HttpCache : HttpClientPlugin<HttpCache.Config, HttpCache>
256

257
interface HttpCacheStorage {
258
    suspend fun find(url: Url, vary: Map<String, String>): HttpCacheEntry?
259
    suspend fun findAll(url: Url): Set<HttpCacheEntry>
260
    suspend fun store(url: Url, data: HttpCacheEntry)
261
}
262

263
class UnlimitedCacheStorage : HttpCacheStorage
264
object DisabledCacheStorage : HttpCacheStorage
265
```
266

267
[Caching](./caching.md)
268

269
### WebSocket Support
270

271
WebSocket client functionality for establishing and managing WebSocket connections with session management, ping/pong handling, and message serialization.
272

273
```kotlin { .api }
274
object WebSockets : HttpClientPlugin<WebSockets.Config, WebSockets>
275

276
interface ClientWebSocketSession : WebSocketSession {
277
    val call: HttpClientCall
278
}
279

280
// WebSocket extension functions  
281
suspend fun HttpClient.webSocket(
282
    method: HttpMethod = HttpMethod.Get,
283
    host: String? = null,
284
    port: Int? = null,
285
    path: String? = null,
286
    request: HttpRequestBuilder.() -> Unit = {},
287
    block: suspend ClientWebSocketSession.() -> Unit
288
)
289

290
suspend fun HttpClient.webSocketSession(
291
    method: HttpMethod = HttpMethod.Get,
292
    host: String? = null,
293
    port: Int? = null,
294
    path: String? = null,
295
    request: HttpRequestBuilder.() -> Unit = {}
296
): ClientWebSocketSession
297
```
298

299
[WebSocket Support](./websockets.md)
300

301
### Form Handling
302

303
Form data construction and submission utilities with support for URL-encoded forms, multipart forms, and file uploads using type-safe DSL builders.
304

305
```kotlin { .api }
306
class FormDataContent(formData: List<Pair<String, String>>) : OutgoingContent
307
class MultiPartFormDataContent(
308
    parts: List<PartData>,
309
    boundary: String = generateBoundary(),
310
    contentType: ContentType = ContentType.MultiPart.FormData.withParameter("boundary", boundary)
311
) : OutgoingContent
312

313
class FormBuilder {
314
    fun append(key: String, value: String)
315
    fun append(
316
        key: String,
317
        filename: String,
318
        contentType: ContentType? = null,
319
        size: Long? = null,
320
        block: suspend ByteWriteChannel.() -> Unit
321
    )
322
    fun appendInput(
323
        key: String,
324
        headers: Headers = Headers.Empty,
325
        size: Long? = null,
326
        block: suspend ByteWriteChannel.() -> Unit
327
    )
328
}
329

330
// Form submission functions
331
suspend fun HttpClient.submitForm(
332
    url: String,
333
    formParameters: Parameters = Parameters.Empty,
334
    encodeInQuery: Boolean = false,
335
    block: HttpRequestBuilder.() -> Unit = {}
336
): HttpResponse
337

338
suspend fun HttpClient.submitFormWithBinaryData(
339
    url: String,
340
    formData: List<PartData>,
341
    block: HttpRequestBuilder.() -> Unit = {}
342
): HttpResponse
343
```
344

345
[Form Handling](./forms.md)
346

347
### Response Observation
348

349
Response observation functionality for monitoring and intercepting HTTP responses for logging, metrics collection, and custom processing.
350

351
```kotlin { .api }
352
object ResponseObserver : HttpClientPlugin<ResponseObserver.Config, ResponseObserver>
353

354
class ResponseObserver {
355
    class Config {
356
        internal val responseHandlers = mutableListOf<suspend (HttpResponse) -> Unit>()
357
        
358
        fun onResponse(block: suspend (response: HttpResponse) -> Unit)
359
    }
360
}
361
```
362

363
[Response Observation](./response-observation.md)
364

365
### Utilities and Extensions
366

367
Utility classes and extension functions for common HTTP client operations including content handling, exception utilities, coroutine integration, and platform-specific helpers.
368

369
```kotlin { .api }
370
// Exception types
371
class ConnectTimeoutException(message: String, cause: Throwable? = null) : Exception(message, cause)
372
class SocketTimeoutException(message: String, cause: Throwable? = null) : Exception(message, cause)
373
class SaveBodyAbandonedReadException : Exception()
374

375
// Content utilities
376
class ClientUpgradeContent : OutgoingContent
377

378
// Client events
379
object HttpRequestCreated : EventDefinition<HttpRequestBuilder>()
380
object HttpRequestIsReadyForSending : EventDefinition<HttpRequest>()
381
object HttpResponseReceived : EventDefinition<HttpResponseContainer>()
382
object HttpResponseCancelled : EventDefinition<HttpResponseContainer>()
383
```
384

385
[Utilities and Extensions](./utilities.md)