or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdcontent-handling.mdcontent-types.mdcookie-management.mdheaders-parameters.mdhttp-core-types.mdindex.mdmessage-properties.mdmultipart-data.mdurl-encoding.mdurl-handling.md
tile.json

tessl/maven-io-ktor--ktor-http-jvm

JVM-specific HTTP utilities and extensions for the Ktor framework providing URL utilities, file content type detection, HTTP message properties, and content handling for JVM platforms

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

To install, run

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

index.mddocs/

Ktor HTTP JVM

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.

Package Information

  • Package Name: io.ktor:ktor-http-jvm
  • Package Type: maven
  • Language: Kotlin
  • Installation: Add to your build.gradle.kts: 
    implementation("io.ktor:ktor-http-jvm:3.2.0")

Core Imports

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

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.URLBuilder
import io.ktor.http.Headers
import io.ktor.http.Parameters
import io.ktor.http.Cookie

Basic Usage

import io.ktor.http.*

// Create HTTP methods
val method = HttpMethod.Get
val customMethod = HttpMethod("PATCH")

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

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

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

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

Architecture

Ktor HTTP JVM is structured around several key components:

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

Capabilities

HTTP Core Types

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

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

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

HTTP Core Types

URL Handling and Building

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

class Url : Serializable {
    val protocol: URLProtocol
    val host: String
    val port: Int
    val encodedPath: String
    val parameters: Parameters
    val fragment: String?
    fun toURI(): URI
}

class URLBuilder {
    var protocol: URLProtocol
    var host: String
    var port: Int
    var pathSegments: MutableList<String>
    var parameters: ParametersBuilder
    fun takeFrom(uri: URI): URLBuilder
    fun takeFrom(url: URL): URLBuilder
    fun build(): Url
}

URL Handling

Content Types and File Detection

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

class ContentType private constructor(
    val contentType: String,
    val contentSubtype: String,
    parameters: List<HeaderValueParam> = emptyList()
) : HeaderValueWithParameters {
    fun withParameter(name: String, value: String): ContentType
    fun withCharset(charset: Charset): ContentType
    
    object Application {
        val Json: ContentType
        val FormUrlEncoded: ContentType
        val OctetStream: ContentType
    }
    
    object Text {
        val Plain: ContentType
        val Html: ContentType
        val CSS: ContentType
    }
    
    companion object {
        fun defaultForFile(file: File): ContentType
        fun defaultForPath(path: Path): ContentType
        fun defaultForFileExtension(extension: String): ContentType
    }
}

Content Types

Headers and Parameters

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

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

class HeadersBuilder : StringValuesBuilderImpl {
    fun build(): Headers
}

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

Headers and Parameters

HTTP Content Handling

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

abstract class OutgoingContent {
    open val contentType: ContentType?
    open val contentLength: Long?
    open val status: HttpStatusCode?
    
    abstract class WriteChannelContent : OutgoingContent()
    abstract class ReadChannelContent : OutgoingContent()
    abstract class ByteArrayContent : OutgoingContent()
}

class OutputStreamContent(
    private val body: suspend OutputStream.() -> Unit,
    override val contentType: ContentType,
    override val status: HttpStatusCode? = null,
    override val contentLength: Long? = null
) : OutgoingContent.WriteChannelContent()

class WriterContent(
    private val body: suspend Writer.() -> Unit,
    override val contentType: ContentType,
    override val status: HttpStatusCode? = null,
    override val contentLength: Long? = null
) : OutgoingContent.WriteChannelContent()

Content Handling

Authentication Headers

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

abstract class HttpAuthHeader {
    val authScheme: String
    abstract fun render(): String
    
    class Single(authScheme: String, val blob: String) : HttpAuthHeader
    class Parameterized(
        authScheme: String,
        val parameters: List<HeaderValueParam>
    ) : HttpAuthHeader
    
    companion object {
        fun basicAuthChallenge(realm: String, charset: Charset = Charsets.UTF_8): Parameterized
        fun bearerAuthChallenge(realm: String? = null, scope: String? = null): HttpAuthHeader
        fun parseAuthorizationHeader(headerValue: String): HttpAuthHeader?
    }
}

Authentication

Cookie Management

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

data class Cookie(
    val name: String,
    val value: String,
    val encoding: CookieEncoding = CookieEncoding.RAW,
    val maxAgeInt: 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()
) : Serializable

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

Cookie Management

URL Encoding and Form Data

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

// URL encoding functions
fun encodeURLParameter(value: String, spaceToPlus: Boolean = false): String
fun encodeURLPath(value: String, alreadyEncoded: Boolean = false): String  
fun encodeURLQueryComponent(value: String, encodeFull: Boolean = true, spaceToPlus: Boolean = true, charset: Charset = Charsets.UTF_8): String
fun decodeURLPart(value: String, start: Int = 0, end: Int = value.length, charset: Charset = Charsets.UTF_8): String

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

URL Encoding

HTTP Message Properties

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

// Common properties
fun HttpMessage.contentType(): ContentType?
fun HttpMessage.contentLength(): Long?
fun HttpMessage.charset(): Charset?
fun HttpMessage.etag(): String?
fun HttpMessage.cacheControl(): List<CacheControl>

// JVM-specific Date properties  
fun HttpMessage.date(): Date?
fun HttpMessage.lastModified(): Date?
fun HttpMessage.expires(): Date?
fun HttpMessageBuilder.ifModifiedSince(date: Date)

Message Properties

Multipart Data Handling

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

interface MultiPartData {
    suspend fun readPart(): PartData?
}

abstract class PartData {
    val headers: Headers
    val contentDisposition: ContentDisposition?
    val contentType: ContentType?
    val name: String?
}

class PartData.FileItem(
    provider: () -> InputStream,
    dispose: () -> Unit,
    headers: Headers
) : PartData {
    val originalFileName: String?
    val streamProvider: () -> InputStream // JVM-specific
}

Multipart Data