0
# Ktor HTTP JS
1

2
Ktor HTTP JS is the JavaScript/WebAssembly implementation of Ktor's HTTP core library. It provides multiplatform Kotlin implementations for HTTP operations in browser and Node.js environments, enabling HTTP clients and servers to run in JavaScript runtime environments with full HTTP protocol support.
3

4
## Package Information
5

6
- **Package Name**: ktor-http-js
7
- **Package Type**: maven (Kotlin Multiplatform)
8
- **Language**: Kotlin
9
- **Installation**: 
10
  ```kotlin
11
  implementation("io.ktor:ktor-http-js:3.2.0")
12
  ```
13

14
## Core Imports
15

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

22
For specific functionality:
23

24
```kotlin
25
import io.ktor.http.HttpMethod
26
import io.ktor.http.HttpStatusCode
27
import io.ktor.http.ContentType
28
import io.ktor.http.Url
29
import io.ktor.http.Headers
30
import io.ktor.http.Parameters
31
```
32

33
## Basic Usage
34

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

38
// Create HTTP method and status
39
val method = HttpMethod.Get
40
val status = HttpStatusCode.OK
41

42
// Build URLs
43
val url = Url("https://api.example.com/users")
44
val builtUrl = buildUrl {
45
    protocol = URLProtocol.HTTPS
46
    host = "api.example.com"
47
    path("v1", "users")
48
    parameters.append("format", "json")
49
}
50

51
// Handle content types
52
val contentType = ContentType.Application.Json
53
val textContent = TextContent("Hello World", ContentType.Text.Plain)
54

55
// Manage headers
56
val headers = headersOf(
57
    HttpHeaders.Accept to "application/json",
58
    HttpHeaders.UserAgent to "MyApp/1.0"
59
)
60

61
// Parse and encode URLs
62
val encodedPath = encodeURLPath("/api/v1/users")
63
val decodedQuery = decodeURLQueryComponent("q=hello%20world")
64
```
65

66
## Architecture 
67

68
Ktor HTTP JS is built around several key components:
69

70
- **HTTP Core**: Methods, status codes, protocol versions, and message interfaces
71
- **Headers System**: Immutable headers with builder pattern and standard header constants
72
- **Content Types**: MIME type system with pre-defined types and parameter handling
73
- **URL System**: Immutable URLs with builder pattern and encoding/decoding utilities
74
- **Content Framework**: Outgoing content types for different data sources and formats
75
- **Authentication**: HTTP authentication header parsing and challenge generation
76
- **Platform Integration**: JavaScript-specific optimizations for browser and Node.js environments
77

78
## Capabilities
79

80
### HTTP Core Operations
81

82
Essential HTTP protocol components including methods, status codes, protocol versions, and message handling interfaces.
83

84
```kotlin { .api }
85
class HttpMethod(val value: String) {
86
    companion object {
87
        val Get: HttpMethod
88
        val Post: HttpMethod  
89
        val Put: HttpMethod
90
        val Delete: HttpMethod
91
        val Head: HttpMethod
92
        val Options: HttpMethod
93
        val Patch: HttpMethod
94
        fun parse(method: String): HttpMethod
95
    }
96
}
97

98
data class HttpStatusCode(val value: Int, val description: String) : Comparable<HttpStatusCode> {
99
    companion object {
100
        val OK: HttpStatusCode
101
        val NotFound: HttpStatusCode
102
        val InternalServerError: HttpStatusCode
103
        fun fromValue(value: Int): HttpStatusCode
104
    }
105
}
106

107
val HttpStatusCode.isSuccess: Boolean
108
```
109

110
[HTTP Core](./http-core.md)
111

112
### Headers Management
113

114
Comprehensive header management with immutable collections, builder patterns, and standard HTTP header constants.
115

116
```kotlin { .api }
117
interface Headers : StringValues {
118
    companion object {
119
        val Empty: Headers
120
        fun build(builder: HeadersBuilder.() -> Unit): Headers
121
    }
122
}
123

124
class HeadersBuilder : StringValuesBuilderImpl() {
125
    fun append(name: String, value: String)
126
    fun set(name: String, value: String)
127
    fun remove(name: String)
128
    fun build(): Headers
129
}
130

131
object HttpHeaders {
132
    val Accept: String
133
    val ContentType: String
134
    val Authorization: String
135
    val UserAgent: String
136
    // ... all standard HTTP headers
137
    fun checkHeaderName(name: String)
138
    fun checkHeaderValue(value: String)
139
}
140
```
141

142
[Headers Management](./headers.md)
143

144
### Content Types
145

146
MIME content type system with pre-defined types, parameter handling, and charset support.
147

148
```kotlin { .api }
149
class ContentType(
150
    val contentType: String, 
151
    val contentSubtype: String, 
152
    val parameters: List<HeaderValueParam>
153
) : HeaderValueWithParameters {
154
    fun match(contentType: ContentType): Boolean
155
    fun withParameter(name: String, value: String): ContentType
156
    fun withCharset(charset: Charset): ContentType
157
    
158
    companion object {
159
        val Any: ContentType
160
        fun parse(value: String): ContentType
161
    }
162
    
163
    object Application {
164
        val Json: ContentType
165
        val OctetStream: ContentType
166
        val FormUrlEncoded: ContentType
167
        val Xml: ContentType
168
    }
169
    
170
    object Text {
171
        val Plain: ContentType
172
        val Html: ContentType
173
        val CSS: ContentType
174
        val JavaScript: ContentType
175
    }
176
}
177
```
178

179
[Content Types](./content-types.md)
180

181
### URL Building and Parsing
182

183
URL construction, parsing, and manipulation with immutable URLs and builder patterns.
184

185
```kotlin { .api }
186
class Url {
187
    val protocol: URLProtocol
188
    val host: String
189
    val port: Int
190
    val encodedPath: String
191
    val parameters: Parameters
192
    val fragment: String?
193
    
194
    companion object {
195
        operator fun invoke(urlString: String): Url
196
    }
197
}
198

199
class URLBuilder {
200
    var protocol: URLProtocol
201
    var host: String
202
    var port: Int
203
    val pathSegments: MutableList<String>
204
    val parameters: ParametersBuilder
205
    var fragment: String?
206
    
207
    fun build(): Url
208
    fun buildString(): String
209
    fun takeFrom(url: String): URLBuilder
210
}
211

212
fun buildUrl(block: URLBuilder.() -> Unit): Url
213
```
214

215
[URL Building](./urls.md)
216

217
### Content Framework
218

219
Outgoing content types for representing different data sources and formats in HTTP responses.
220

221
```kotlin { .api }
222
abstract class OutgoingContent {
223
    open val contentType: ContentType?
224
    open val contentLength: Long?
225
    open val status: HttpStatusCode?
226
    open val headers: Headers?
227
}
228

229
abstract class OutgoingContent.ByteArrayContent : OutgoingContent() {
230
    abstract fun bytes(): ByteArray
231
}
232

233
class TextContent(
234
    val text: String,
235
    override val contentType: ContentType,
236
    override val status: HttpStatusCode? = null
237
) : OutgoingContent.ByteArrayContent
238

239
abstract class OutgoingContent.WriteChannelContent : OutgoingContent() {
240
    abstract suspend fun writeTo(channel: ByteWriteChannel)
241
}
242
```
243

244
[Content Framework](./content.md)
245

246
### Authentication
247

248
HTTP authentication header parsing, challenge generation, and authentication scheme support.
249

250
```kotlin { .api }
251
abstract class HttpAuthHeader(val authScheme: String) {
252
    abstract fun render(): String
253
    abstract fun render(encoding: HeaderValueEncoding): String
254
    
255
    companion object {
256
        fun basicAuthChallenge(realm: String, charset: Charset): HttpAuthHeader.Parameterized
257
        fun digestAuthChallenge(realm: String, nonce: String): HttpAuthHeader.Parameterized
258
        fun bearerAuthChallenge(realm: String? = null, scope: String? = null): HttpAuthHeader
259
    }
260
}
261

262
class HttpAuthHeader.Single(authScheme: String, val blob: String) : HttpAuthHeader(authScheme)
263

264
class HttpAuthHeader.Parameterized(
265
    authScheme: String, 
266
    val parameters: List<HeaderValueParam>
267
) : HttpAuthHeader(authScheme) {
268
    fun parameter(name: String): String?
269
    fun withParameter(name: String, value: String): HttpAuthHeader.Parameterized
270
}
271

272
fun parseAuthorizationHeader(headerValue: String): HttpAuthHeader?
273
```
274

275
[Authentication](./authentication.md)
276

277
### Cookie Management
278

279
HTTP cookie handling with encoding options, parsing utilities, and header rendering.
280

281
```kotlin { .api }
282
data class Cookie(
283
    val name: String,
284
    val value: String,
285
    val encoding: CookieEncoding = CookieEncoding.RAW,
286
    val maxAge: Int? = null,
287
    val expires: GMTDate? = null,
288
    val domain: String? = null,
289
    val path: String? = null,
290
    val secure: Boolean = false,
291
    val httpOnly: Boolean = false,
292
    val extensions: Map<String, String?> = emptyMap()
293
)
294

295
enum class CookieEncoding {
296
    RAW, DQUOTES, URI_ENCODING, BASE64_ENCODING
297
}
298

299
fun parseServerSetCookieHeader(value: String): Cookie
300
fun parseClientCookiesHeader(value: String): Map<String, String>
301
fun renderSetCookieHeader(cookie: Cookie): String
302
```
303

304
[Cookie Management](./cookies.md)
305

306
## Types
307

308
Core types used across the HTTP library:
309

310
```kotlin { .api }
311
interface StringValues {
312
    val caseInsensitiveName: Boolean
313
    fun get(name: String): String?
314
    fun getAll(name: String): List<String>?
315
    fun contains(name: String): Boolean
316
    fun contains(name: String, value: String): Boolean
317
    fun isEmpty(): Boolean
318
    val entries: Set<Map.Entry<String, List<String>>>
319
    fun forEach(body: (String, List<String>) -> Unit)
320
}
321

322
interface Parameters : StringValues {
323
    companion object {
324
        val Empty: Parameters
325
        fun build(builder: ParametersBuilder.() -> Unit): Parameters
326
    }
327
}
328

329
data class HeaderValueParam(
330
    val name: String,
331
    val value: String,
332
    val escapeValue: Boolean = false
333
)
334

335
abstract class HeaderValueWithParameters(
336
    protected val content: String,
337
    val parameters: List<HeaderValueParam>
338
) {
339
    fun parameter(name: String): String?
340
}
341

342
data class URLProtocol(val name: String, val defaultPort: Int) {
343
    companion object {
344
        val HTTP: URLProtocol
345
        val HTTPS: URLProtocol  
346
        val WS: URLProtocol
347
        val WSS: URLProtocol
348
        fun createOrDefault(name: String): URLProtocol
349
    }
350
}
351
```