or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdcontent-types.mdcontent.mdcookies.mdheaders.mdhttp-core.mdindex.mdurls.md
tile.json

tessl/maven-io-ktor--ktor-http-js

JavaScript/WebAssembly implementation of Ktor's HTTP core library providing HTTP utilities, URL building, request/response handling, and HTTP method definitions for multiplatform Kotlin applications targeting JavaScript environments

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.ktor/ktor-http-js@3.2.x

To install, run

npx @tessl/cli install tessl/maven-io-ktor--ktor-http-js@3.2.0

index.mddocs/

Ktor HTTP JS

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.

Package Information

  • Package Name: ktor-http-js
  • Package Type: maven (Kotlin Multiplatform)
  • Language: Kotlin
  • Installation:
    implementation("io.ktor:ktor-http-js:3.2.0")

Core Imports

import io.ktor.http.*
import io.ktor.http.content.*
import io.ktor.http.auth.*

For specific functionality:

import io.ktor.http.HttpMethod
import io.ktor.http.HttpStatusCode
import io.ktor.http.ContentType
import io.ktor.http.Url
import io.ktor.http.Headers
import io.ktor.http.Parameters

Basic Usage

import io.ktor.http.*

// Create HTTP method and status
val method = HttpMethod.Get
val status = HttpStatusCode.OK

// Build URLs
val url = Url("https://api.example.com/users")
val builtUrl = buildUrl {
    protocol = URLProtocol.HTTPS
    host = "api.example.com"
    path("v1", "users")
    parameters.append("format", "json")
}

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

// Manage headers
val headers = headersOf(
    HttpHeaders.Accept to "application/json",
    HttpHeaders.UserAgent to "MyApp/1.0"
)

// Parse and encode URLs
val encodedPath = encodeURLPath("/api/v1/users")
val decodedQuery = decodeURLQueryComponent("q=hello%20world")

Architecture

Ktor HTTP JS is built around several key components:

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

Capabilities

HTTP Core Operations

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

class HttpMethod(val value: String) {
    companion object {
        val Get: HttpMethod
        val Post: HttpMethod  
        val Put: HttpMethod
        val Delete: HttpMethod
        val Head: HttpMethod
        val Options: HttpMethod
        val Patch: HttpMethod
        fun parse(method: String): HttpMethod
    }
}

data class HttpStatusCode(val value: Int, val description: String) : Comparable<HttpStatusCode> {
    companion object {
        val OK: HttpStatusCode
        val NotFound: HttpStatusCode
        val InternalServerError: HttpStatusCode
        fun fromValue(value: Int): HttpStatusCode
    }
}

val HttpStatusCode.isSuccess: Boolean

HTTP Core

Headers Management

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

interface Headers : StringValues {
    companion object {
        val Empty: Headers
        fun build(builder: HeadersBuilder.() -> Unit): Headers
    }
}

class HeadersBuilder : StringValuesBuilderImpl() {
    fun append(name: String, value: String)
    fun set(name: String, value: String)
    fun remove(name: String)
    fun build(): Headers
}

object HttpHeaders {
    val Accept: String
    val ContentType: String
    val Authorization: String
    val UserAgent: String
    // ... all standard HTTP headers
    fun checkHeaderName(name: String)
    fun checkHeaderValue(value: String)
}

Headers Management

Content Types

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

class ContentType(
    val contentType: String, 
    val contentSubtype: String, 
    val parameters: List<HeaderValueParam>
) : HeaderValueWithParameters {
    fun match(contentType: ContentType): Boolean
    fun withParameter(name: String, value: String): ContentType
    fun withCharset(charset: Charset): ContentType
    
    companion object {
        val Any: ContentType
        fun parse(value: String): ContentType
    }
    
    object Application {
        val Json: ContentType
        val OctetStream: ContentType
        val FormUrlEncoded: ContentType
        val Xml: ContentType
    }
    
    object Text {
        val Plain: ContentType
        val Html: ContentType
        val CSS: ContentType
        val JavaScript: ContentType
    }
}

Content Types

URL Building and Parsing

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

class Url {
    val protocol: URLProtocol
    val host: String
    val port: Int
    val encodedPath: String
    val parameters: Parameters
    val fragment: String?
    
    companion object {
        operator fun invoke(urlString: String): Url
    }
}

class URLBuilder {
    var protocol: URLProtocol
    var host: String
    var port: Int
    val pathSegments: MutableList<String>
    val parameters: ParametersBuilder
    var fragment: String?
    
    fun build(): Url
    fun buildString(): String
    fun takeFrom(url: String): URLBuilder
}

fun buildUrl(block: URLBuilder.() -> Unit): Url

URL Building

Content Framework

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

abstract class OutgoingContent {
    open val contentType: ContentType?
    open val contentLength: Long?
    open val status: HttpStatusCode?
    open val headers: Headers?
}

abstract class OutgoingContent.ByteArrayContent : OutgoingContent() {
    abstract fun bytes(): ByteArray
}

class TextContent(
    val text: String,
    override val contentType: ContentType,
    override val status: HttpStatusCode? = null
) : OutgoingContent.ByteArrayContent

abstract class OutgoingContent.WriteChannelContent : OutgoingContent() {
    abstract suspend fun writeTo(channel: ByteWriteChannel)
}

Content Framework

Authentication

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

abstract class HttpAuthHeader(val authScheme: String) {
    abstract fun render(): String
    abstract fun render(encoding: HeaderValueEncoding): String
    
    companion object {
        fun basicAuthChallenge(realm: String, charset: Charset): HttpAuthHeader.Parameterized
        fun digestAuthChallenge(realm: String, nonce: String): HttpAuthHeader.Parameterized
        fun bearerAuthChallenge(realm: String? = null, scope: String? = null): HttpAuthHeader
    }
}

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

class HttpAuthHeader.Parameterized(
    authScheme: String, 
    val parameters: List<HeaderValueParam>
) : HttpAuthHeader(authScheme) {
    fun parameter(name: String): String?
    fun withParameter(name: String, value: String): HttpAuthHeader.Parameterized
}

fun parseAuthorizationHeader(headerValue: String): HttpAuthHeader?

Authentication

Cookie Management

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

data class Cookie(
    val name: String,
    val value: String,
    val encoding: CookieEncoding = CookieEncoding.RAW,
    val maxAge: Int? = null,
    val expires: GMTDate? = null,
    val domain: String? = null,
    val path: String? = null,
    val secure: Boolean = false,
    val httpOnly: Boolean = false,
    val extensions: Map<String, String?> = emptyMap()
)

enum class CookieEncoding {
    RAW, DQUOTES, URI_ENCODING, BASE64_ENCODING
}

fun parseServerSetCookieHeader(value: String): Cookie
fun parseClientCookiesHeader(value: String): Map<String, String>
fun renderSetCookieHeader(cookie: Cookie): String

Cookie Management

Types

Core types used across the HTTP library:

interface StringValues {
    val caseInsensitiveName: Boolean
    fun get(name: String): String?
    fun getAll(name: String): List<String>?
    fun contains(name: String): Boolean
    fun contains(name: String, value: String): Boolean
    fun isEmpty(): Boolean
    val entries: Set<Map.Entry<String, List<String>>>
    fun forEach(body: (String, List<String>) -> Unit)
}

interface Parameters : StringValues {
    companion object {
        val Empty: Parameters
        fun build(builder: ParametersBuilder.() -> Unit): Parameters
    }
}

data class HeaderValueParam(
    val name: String,
    val value: String,
    val escapeValue: Boolean = false
)

abstract class HeaderValueWithParameters(
    protected val content: String,
    val parameters: List<HeaderValueParam>
) {
    fun parameter(name: String): String?
}

data class URLProtocol(val name: String, val defaultPort: Int) {
    companion object {
        val HTTP: URLProtocol
        val HTTPS: URLProtocol  
        val WS: URLProtocol
        val WSS: URLProtocol
        fun createOrDefault(name: String): URLProtocol
    }
}