0
# HTTP Core
1

2
Essential HTTP protocol components including methods, status codes, protocol versions, and message handling interfaces.
3

4
## Capabilities
5

6
### HTTP Methods
7

8
Represents HTTP request methods with common methods pre-defined and parsing support.
9

10
```kotlin { .api }
11
/**
12
 * Represents an HTTP request method
13
 * @param value The string representation of the HTTP method
14
 */
15
class HttpMethod(val value: String) {
16
    fun component1(): String = value
17
    fun copy(value: String = this.value): HttpMethod
18
    
19
    companion object {
20
        val Get: HttpMethod
21
        val Post: HttpMethod
22
        val Put: HttpMethod
23
        val Delete: HttpMethod
24
        val Head: HttpMethod
25
        val Options: HttpMethod
26
        val Patch: HttpMethod
27
        val DefaultMethods: List<HttpMethod>
28
        
29
        /**
30
         * Parse HTTP method from string
31
         * @param method Method string (case-sensitive)
32
         * @return HttpMethod instance
33
         */
34
        fun parse(method: String): HttpMethod
35
    }
36
}
37

38
/**
39
 * Check if HTTP method supports request body
40
 */
41
val HttpMethod.supportsRequestBody: Boolean
42
```
43

44
**Usage Examples:**
45

46
```kotlin
47
import io.ktor.http.HttpMethod
48

49
// Use predefined methods
50
val getMethod = HttpMethod.Get
51
val postMethod = HttpMethod.Post
52

53
// Parse from string
54
val customMethod = HttpMethod.parse("PATCH")
55

56
// Check body support
57
val supportsBody = HttpMethod.Post.supportsRequestBody // true
58
val noBody = HttpMethod.Get.supportsRequestBody // false
59
```
60

61
### HTTP Status Codes
62

63
Represents HTTP response status codes with common codes pre-defined and utility functions.
64

65
```kotlin { .api }
66
/**
67
 * Represents an HTTP status code
68
 * @param value The numeric status code
69
 * @param description Human-readable description
70
 */
71
data class HttpStatusCode(val value: Int, val description: String) : Comparable<HttpStatusCode> {
72
    fun description(description: String): HttpStatusCode
73
    
74
    companion object {
75
        // 1xx Informational
76
        val Continue: HttpStatusCode
77
        val SwitchingProtocols: HttpStatusCode
78
        val Processing: HttpStatusCode
79
        
80
        // 2xx Success
81
        val OK: HttpStatusCode
82
        val Created: HttpStatusCode
83
        val Accepted: HttpStatusCode
84
        val NonAuthoritativeInformation: HttpStatusCode
85
        val NoContent: HttpStatusCode
86
        val ResetContent: HttpStatusCode
87
        val PartialContent: HttpStatusCode
88
        val MultiStatus: HttpStatusCode
89
        
90
        // 3xx Redirection
91
        val MultipleChoices: HttpStatusCode
92
        val MovedPermanently: HttpStatusCode
93
        val Found: HttpStatusCode
94
        val SeeOther: HttpStatusCode
95
        val NotModified: HttpStatusCode
96
        val UseProxy: HttpStatusCode
97
        val SwitchProxy: HttpStatusCode
98
        val TemporaryRedirect: HttpStatusCode
99
        val PermanentRedirect: HttpStatusCode
100
        
101
        // 4xx Client Error
102
        val BadRequest: HttpStatusCode
103
        val Unauthorized: HttpStatusCode
104
        val PaymentRequired: HttpStatusCode
105
        val Forbidden: HttpStatusCode
106
        val NotFound: HttpStatusCode
107
        val MethodNotAllowed: HttpStatusCode
108
        val NotAcceptable: HttpStatusCode
109
        val ProxyAuthenticationRequired: HttpStatusCode
110
        val RequestTimeout: HttpStatusCode
111
        val Conflict: HttpStatusCode
112
        val Gone: HttpStatusCode
113
        val LengthRequired: HttpStatusCode
114
        val PreconditionFailed: HttpStatusCode
115
        val PayloadTooLarge: HttpStatusCode
116
        val RequestURITooLong: HttpStatusCode
117
        val UnsupportedMediaType: HttpStatusCode
118
        val RequestedRangeNotSatisfiable: HttpStatusCode
119
        val ExpectationFailed: HttpStatusCode
120
        val UnprocessableEntity: HttpStatusCode
121
        val Locked: HttpStatusCode
122
        val FailedDependency: HttpStatusCode
123
        val TooEarly: HttpStatusCode
124
        val UpgradeRequired: HttpStatusCode
125
        val TooManyRequests: HttpStatusCode
126
        val RequestHeaderFieldTooLarge: HttpStatusCode
127
        
128
        // 5xx Server Error
129
        val InternalServerError: HttpStatusCode
130
        val NotImplemented: HttpStatusCode
131
        val BadGateway: HttpStatusCode
132
        val ServiceUnavailable: HttpStatusCode
133
        val GatewayTimeout: HttpStatusCode
134
        val VersionNotSupported: HttpStatusCode
135
        val VariantAlsoNegotiates: HttpStatusCode
136
        val InsufficientStorage: HttpStatusCode
137
        
138
        val allStatusCodes: List<HttpStatusCode>
139
        
140
        /**
141
         * Get status code by numeric value
142
         * @param value HTTP status code number
143
         * @return HttpStatusCode instance
144
         */
145
        fun fromValue(value: Int): HttpStatusCode
146
    }
147
}
148

149
/**
150
 * Check if status code indicates success (2xx range)
151
 */
152
fun HttpStatusCode.isSuccess(): Boolean
153
```
154

155
**Usage Examples:**
156

157
```kotlin
158
import io.ktor.http.HttpStatusCode
159
import io.ktor.http.isSuccess
160

161
// Use predefined status codes
162
val okStatus = HttpStatusCode.OK
163
val notFoundStatus = HttpStatusCode.NotFound
164

165
// Create custom status
166
val customStatus = HttpStatusCode(299, "Custom Success")
167

168
// Get by value
169
val status = HttpStatusCode.fromValue(404) // NotFound
170

171
// Check success
172
val isOk = HttpStatusCode.OK.isSuccess // true
173
val isError = HttpStatusCode.InternalServerError.isSuccess // false
174

175
// Compare status codes
176
val comparison = HttpStatusCode.OK < HttpStatusCode.NotFound // true
177
```
178

179
### HTTP Protocol Versions
180

181
Represents HTTP protocol versions with common versions pre-defined.
182

183
```kotlin { .api }
184
/**
185
 * Represents HTTP protocol version
186
 * @param name Protocol name (e.g., "HTTP")  
187
 * @param major Major version number
188
 * @param minor Minor version number
189
 */
190
data class HttpProtocolVersion(val name: String, val major: Int, val minor: Int) {
191
    companion object {
192
        val HTTP_1_0: HttpProtocolVersion
193
        val HTTP_1_1: HttpProtocolVersion
194
        val HTTP_2_0: HttpProtocolVersion
195
        val SPDY_3: HttpProtocolVersion
196
        val QUIC: HttpProtocolVersion
197
        
198
        /**
199
         * Get or create protocol version
200
         * @param name Protocol name
201
         * @param major Major version
202
         * @param minor Minor version
203
         * @return HttpProtocolVersion instance
204
         */
205
        fun fromValue(name: String, major: Int, minor: Int): HttpProtocolVersion
206
        
207
        /**
208
         * Parse protocol version from string
209
         * @param value Protocol version string (e.g., "HTTP/1.1")
210
         * @return HttpProtocolVersion instance
211
         */
212
        fun parse(value: CharSequence): HttpProtocolVersion
213
    }
214
}
215
```
216

217
**Usage Examples:**
218

219
```kotlin
220
import io.ktor.http.HttpProtocolVersion
221

222
// Use predefined versions
223
val http11 = HttpProtocolVersion.HTTP_1_1
224
val http2 = HttpProtocolVersion.HTTP_2_0
225

226
// Create custom version
227
val customVersion = HttpProtocolVersion.fromValue("CUSTOM", 1, 0)
228

229
// Parse from string
230
val parsed = HttpProtocolVersion.parse("HTTP/1.1")
231
```
232

233
### HTTP Message Interfaces
234

235
Base interfaces for HTTP messages with headers support.
236

237
```kotlin { .api }
238
/**
239
 * Base interface for HTTP messages
240
 */
241
interface HttpMessage {
242
    val headers: Headers
243
}
244

245
/**
246
 * Builder interface for HTTP messages
247
 */
248
interface HttpMessageBuilder {
249
    val headers: HeadersBuilder
250
}
251
```
252

253
### HTTP Message Properties
254

255
Extension functions for accessing common HTTP message properties.
256

257
```kotlin { .api }
258
/**
259
 * Get content type from HTTP message
260
 */
261
fun HttpMessage.contentType(): ContentType?
262
fun HttpMessageBuilder.contentType(): ContentType?
263

264
/**
265
 * Set content type on HTTP message builder
266
 */
267
fun HttpMessageBuilder.contentType(contentType: ContentType)
268

269
/**
270
 * Get content length from HTTP message
271
 */
272
fun HttpMessage.contentLength(): Long?
273
fun HttpMessageBuilder.contentLength(): Long?
274

275
/**
276
 * Get charset from HTTP message
277
 */
278
fun HttpMessage.charset(): Charset?
279
fun HttpMessageBuilder.charset(): Charset?
280

281
/**
282
 * Get cache control directives from HTTP message
283
 */
284
fun HttpMessage.cacheControl(): List<CacheControl>
285

286
/**
287
 * Get ETag from HTTP message
288
 */
289
fun HttpMessage.etag(): String?
290
fun HttpMessageBuilder.etag(): String?
291

292
/**
293
 * Get Vary header values from HTTP message
294
 */
295
fun HttpMessage.vary(): List<String>
296
fun HttpMessageBuilder.vary(): List<String>
297

298
/**
299
 * Get Set-Cookie headers from HTTP message
300
 */
301
fun HttpMessage.setCookie(): List<Cookie>
302

303
/**
304
 * Get cookies from HTTP message builder
305
 */
306
fun HttpMessageBuilder.cookies(): List<Cookie>
307

308
/**
309
 * Set various message properties
310
 */
311
fun HttpMessageBuilder.ifNoneMatch(etag: String)
312
fun HttpMessageBuilder.maxAge(seconds: Int)
313
fun HttpMessageBuilder.userAgent(userAgent: String)
314
```
315

316
**Usage Examples:**
317

318
```kotlin
319
import io.ktor.http.*
320

321
// Working with HTTP messages
322
fun processMessage(message: HttpMessage) {
323
    val contentType = message.contentType()
324
    val contentLength = message.contentLength()
325
    val charset = message.charset()
326
    val etag = message.etag()
327
}
328

329
// Building HTTP messages
330
fun buildMessage(builder: HttpMessageBuilder) {
331
    builder.contentType(ContentType.Application.Json)
332
    builder.userAgent("MyApp/1.0")
333
    builder.maxAge(3600)
334
}
335
```
336

337
### Request Connection Point
338

339
Interface representing connection details for HTTP requests.
340

341
```kotlin { .api }
342
/**
343
 * Represents connection point information for HTTP requests
344
 */
345
interface RequestConnectionPoint {
346
    val scheme: String
347
    val version: String
348
    val uri: String
349
    val method: HttpMethod
350
    val host: String
351
    val port: Int
352
    val localAddress: String
353
    val localHost: String
354
    val localPort: Int
355
    val remoteAddress: String
356
    val remoteHost: String
357
    val remotePort: Int
358
    val serverHost: String
359
    val serverPort: Int
360
}
361
```
362

363
This interface is typically implemented by HTTP server frameworks to provide connection metadata.