0
# Ktor HTTP JVM
1

2
Ktor HTTP JVM provides JVM-specific HTTP utilities and extensions for the Ktor asynchronous framework. It includes comprehensive HTTP protocol support with URL manipulation, file content type detection, HTTP message property handling optimized for JVM platforms, and content handling classes for various JVM-specific content types. The package serves as the JVM-specific implementation layer for Ktor's cross-platform HTTP functionality, bridging common HTTP abstractions with JVM-specific APIs and optimizations.
3

4
## Package Information
5

6
- **Package Name**: io.ktor:ktor-http-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: Add to your `build.gradle.kts`:
10
  ```kotlin
11
  implementation("io.ktor:ktor-http-jvm:3.2.0")
12
  ```
13

14
## Core Imports
15

16
```kotlin
17
import io.ktor.http.*
18
import io.ktor.http.content.*
19
```
20

21
For specific functionality:
22
```kotlin
23
import io.ktor.http.HttpMethod
24
import io.ktor.http.HttpStatusCode
25
import io.ktor.http.ContentType
26
import io.ktor.http.Url
27
import io.ktor.http.URLBuilder
28
import io.ktor.http.Headers
29
import io.ktor.http.Parameters
30
import io.ktor.http.Cookie
31
```
32

33
## Basic Usage
34

35
```kotlin
36
import io.ktor.http.*
37

38
// Create HTTP methods
39
val method = HttpMethod.Get
40
val customMethod = HttpMethod("PATCH")
41

42
// Work with status codes
43
val status = HttpStatusCode.OK
44
val customStatus = HttpStatusCode(418, "I'm a teapot")
45

46
// Build URLs
47
val url = URLBuilder("https://api.example.com")
48
    .appendPathSegments("users", "123")
49
    .parameters.append("include", "profile")
50
    .build()
51

52
// Handle content types
53
val contentType = ContentType.Application.Json
54
val textType = ContentType.Text.Plain.withCharset(Charsets.UTF_8)
55

56
// JVM-specific: File content type detection
57
val fileType = ContentType.defaultForFile(File("image.png"))
58
```
59

60
## Architecture
61

62
Ktor HTTP JVM is structured around several key components:
63

64
- **Core HTTP Types**: `HttpMethod`, `HttpStatusCode`, `HttpProtocolVersion` for fundamental HTTP concepts
65
- **URL Handling**: `Url`, `URLBuilder`, `URLProtocol` with JVM interoperability via `java.net.URI/URL`
66
- **Content System**: `ContentType` hierarchy with JVM-specific file type detection
67
- **Headers & Parameters**: `Headers`, `Parameters` with type-safe builders
68
- **Content Handling**: `OutgoingContent` hierarchy with JVM-specific implementations like `OutputStreamContent`
69
- **Authentication**: `HttpAuthHeader` system supporting Basic, Bearer, Digest authentication
70
- **Serialization**: Built-in kotlinx.serialization support for URLs, cookies, and other HTTP types
71

72
## Capabilities
73

74
### HTTP Core Types
75

76
Fundamental HTTP protocol types including methods, status codes, and protocol versions with comprehensive predefined constants.
77

78
```kotlin { .api }
79
data class HttpMethod(val value: String) {
80
    companion object {
81
        val Get: HttpMethod
82
        val Post: HttpMethod
83
        val Put: HttpMethod
84
        val Patch: HttpMethod
85
        val Delete: HttpMethod
86
        val Head: HttpMethod
87
        val Options: HttpMethod
88
        fun parse(method: String): HttpMethod
89
    }
90
}
91

92
data class HttpStatusCode(val value: Int, val description: String) : Comparable<HttpStatusCode> {
93
    companion object {
94
        val OK: HttpStatusCode
95
        val Created: HttpStatusCode
96
        val BadRequest: HttpStatusCode
97
        val NotFound: HttpStatusCode
98
        val InternalServerError: HttpStatusCode
99
        fun fromValue(value: Int): HttpStatusCode
100
    }
101
}
102
```
103

104
[HTTP Core Types](./http-core-types.md)
105

106
### URL Handling and Building
107

108
Comprehensive URL manipulation with JVM integration for `java.net.URI` and `java.net.URL` interoperability.
109

110
```kotlin { .api }
111
class Url : Serializable {
112
    val protocol: URLProtocol
113
    val host: String
114
    val port: Int
115
    val encodedPath: String
116
    val parameters: Parameters
117
    val fragment: String?
118
    fun toURI(): URI
119
}
120

121
class URLBuilder {
122
    var protocol: URLProtocol
123
    var host: String
124
    var port: Int
125
    var pathSegments: MutableList<String>
126
    var parameters: ParametersBuilder
127
    fun takeFrom(uri: URI): URLBuilder
128
    fun takeFrom(url: URL): URLBuilder
129
    fun build(): Url
130
}
131
```
132

133
[URL Handling](./url-handling.md)
134

135
### Content Types and File Detection
136

137
Content-Type header handling with JVM-specific file extension detection and MIME type mapping.
138

139
```kotlin { .api }
140
class ContentType private constructor(
141
    val contentType: String,
142
    val contentSubtype: String,
143
    parameters: List<HeaderValueParam> = emptyList()
144
) : HeaderValueWithParameters {
145
    fun withParameter(name: String, value: String): ContentType
146
    fun withCharset(charset: Charset): ContentType
147
    
148
    object Application {
149
        val Json: ContentType
150
        val FormUrlEncoded: ContentType
151
        val OctetStream: ContentType
152
    }
153
    
154
    object Text {
155
        val Plain: ContentType
156
        val Html: ContentType
157
        val CSS: ContentType
158
    }
159
    
160
    companion object {
161
        fun defaultForFile(file: File): ContentType
162
        fun defaultForPath(path: Path): ContentType
163
        fun defaultForFileExtension(extension: String): ContentType
164
    }
165
}
166
```
167

168
[Content Types](./content-types.md)
169

170
### Headers and Parameters
171

172
HTTP header and URL parameter handling with type-safe builders and validation.
173

174
```kotlin { .api }
175
interface Headers : StringValues {
176
    companion object {
177
        fun build(builder: HeadersBuilder.() -> Unit): Headers
178
        val Empty: Headers
179
    }
180
}
181

182
class HeadersBuilder : StringValuesBuilderImpl {
183
    fun build(): Headers
184
}
185

186
interface Parameters : StringValues {
187
    companion object {
188
        fun build(builder: ParametersBuilder.() -> Unit): Parameters
189
        val Empty: Parameters
190
    }
191
}
192
```
193

194
[Headers and Parameters](./headers-parameters.md)
195

196
### HTTP Content Handling
197

198
Outgoing content system with JVM-specific implementations for streams, writers, and file content.
199

200
```kotlin { .api }
201
abstract class OutgoingContent {
202
    open val contentType: ContentType?
203
    open val contentLength: Long?
204
    open val status: HttpStatusCode?
205
    
206
    abstract class WriteChannelContent : OutgoingContent()
207
    abstract class ReadChannelContent : OutgoingContent()
208
    abstract class ByteArrayContent : OutgoingContent()
209
}
210

211
class OutputStreamContent(
212
    private val body: suspend OutputStream.() -> Unit,
213
    override val contentType: ContentType,
214
    override val status: HttpStatusCode? = null,
215
    override val contentLength: Long? = null
216
) : OutgoingContent.WriteChannelContent()
217

218
class WriterContent(
219
    private val body: suspend Writer.() -> Unit,
220
    override val contentType: ContentType,
221
    override val status: HttpStatusCode? = null,
222
    override val contentLength: Long? = null
223
) : OutgoingContent.WriteChannelContent()
224
```
225

226
[Content Handling](./content-handling.md)
227

228
### Authentication Headers
229

230
HTTP authentication header parsing and generation supporting Basic, Bearer, Digest, and custom schemes.
231

232
```kotlin { .api }
233
abstract class HttpAuthHeader {
234
    val authScheme: String
235
    abstract fun render(): String
236
    
237
    class Single(authScheme: String, val blob: String) : HttpAuthHeader
238
    class Parameterized(
239
        authScheme: String,
240
        val parameters: List<HeaderValueParam>
241
    ) : HttpAuthHeader
242
    
243
    companion object {
244
        fun basicAuthChallenge(realm: String, charset: Charset = Charsets.UTF_8): Parameterized
245
        fun bearerAuthChallenge(realm: String? = null, scope: String? = null): HttpAuthHeader
246
        fun parseAuthorizationHeader(headerValue: String): HttpAuthHeader?
247
    }
248
}
249
```
250

251
[Authentication](./authentication.md)
252

253
### Cookie Management
254

255
HTTP cookie creation, parsing, and rendering with encoding support and security options.
256

257
```kotlin { .api }
258
data class Cookie(
259
    val name: String,
260
    val value: String,
261
    val encoding: CookieEncoding = CookieEncoding.RAW,
262
    val maxAgeInt: Int? = null,
263
    val expires: GMTDate? = null,
264
    val domain: String? = null,
265
    val path: String? = null,
266
    val secure: Boolean = false,
267
    val httpOnly: Boolean = false,
268
    val extensions: Map<String, String> = emptyMap()
269
) : Serializable
270

271
enum class CookieEncoding {
272
    RAW, DQUOTES, BASE64_ENCODING, URI_ENCODING
273
}
274
```
275

276
[Cookie Management](./cookie-management.md)
277

278
### URL Encoding and Form Data
279

280
URL encoding utilities and form data handling for query parameters and request bodies.
281

282
```kotlin { .api }
283
// URL encoding functions
284
fun encodeURLParameter(value: String, spaceToPlus: Boolean = false): String
285
fun encodeURLPath(value: String, alreadyEncoded: Boolean = false): String  
286
fun encodeURLQueryComponent(value: String, encodeFull: Boolean = true, spaceToPlus: Boolean = true, charset: Charset = Charsets.UTF_8): String
287
fun decodeURLPart(value: String, start: Int = 0, end: Int = value.length, charset: Charset = Charsets.UTF_8): String
288

289
// Form URL encoding
290
fun formUrlEncode(parameters: Parameters): String
291
fun formUrlEncode(parameters: List<Pair<String, String>>): String
292
fun parseUrlEncodedParameters(data: String, charset: Charset = Charsets.UTF_8, limit: Int = 1000): Parameters
293
```
294

295
[URL Encoding](./url-encoding.md)
296

297
### HTTP Message Properties
298

299
HTTP message property extraction and manipulation with JVM-specific Date support.
300

301
```kotlin { .api }
302
// Common properties
303
fun HttpMessage.contentType(): ContentType?
304
fun HttpMessage.contentLength(): Long?
305
fun HttpMessage.charset(): Charset?
306
fun HttpMessage.etag(): String?
307
fun HttpMessage.cacheControl(): List<CacheControl>
308

309
// JVM-specific Date properties  
310
fun HttpMessage.date(): Date?
311
fun HttpMessage.lastModified(): Date?
312
fun HttpMessage.expires(): Date?
313
fun HttpMessageBuilder.ifModifiedSince(date: Date)
314
```
315

316
[Message Properties](./message-properties.md)
317

318
### Multipart Data Handling
319

320
Multipart form data processing with support for file uploads and form fields.
321

322
```kotlin { .api }
323
interface MultiPartData {
324
    suspend fun readPart(): PartData?
325
}
326

327
abstract class PartData {
328
    val headers: Headers
329
    val contentDisposition: ContentDisposition?
330
    val contentType: ContentType?
331
    val name: String?
332
}
333

334
class PartData.FileItem(
335
    provider: () -> InputStream,
336
    dispose: () -> Unit,
337
    headers: Headers
338
) : PartData {
339
    val originalFileName: String?
340
    val streamProvider: () -> InputStream // JVM-specific
341
}
342
```
343

344
[Multipart Data](./multipart-data.md)