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
```