or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

application.mdconfig.mdengine.mdindex.mdplugins.mdrequest.mdresponse.mdrouting.md
tile.json

tessl/maven-io-ktor--ktor-server-core-jvm

Core server functionality for the Ktor asynchronous web framework, providing essential building blocks for HTTP servers including application lifecycle management, routing foundations, request/response handling, and plugin architecture specifically compiled for JVM targets.

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

To install, run

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

index.mddocs/

Ktor Server Core JVM

Ktor Server Core JVM provides the foundational server functionality for Ktor applications, a Kotlin-based asynchronous framework for building microservices and web applications. It contains essential server components compiled specifically for JVM targets, including application lifecycle management, routing infrastructure, request/response processing, plugin architecture, and foundational abstractions for HTTP server implementations.

Package Information

  • Package Name: io.ktor:ktor-server-core-jvm
  • Package Type: maven
  • Language: Kotlin
  • Installation: implementation("io.ktor:ktor-server-core:3.2.0")

Core Imports

import io.ktor.server.application.*
import io.ktor.server.routing.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.plugins.*
import io.ktor.server.engine.*

Basic Usage

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Application.module() {
    routing {
        get("/") {
            call.respondText("Hello, World!")
        }
        
        post("/api/users") {
            val user = call.receive<User>()
            // Process user
            call.respond(HttpStatusCode.Created, user)
        }
    }
}

Architecture

Ktor Server Core is built around several key architectural components:

  • Application Framework: Application class serves as the main container with plugin registry and lifecycle management
  • Call Processing: ApplicationCall represents the request-response cycle with pipeline-based processing
  • Plugin System: Interface-based plugins (ApplicationPlugin, RouteScopedPlugin) with installation and lifecycle management
  • Routing Engine: DSL-based URL routing with HTTP method handlers and parameter matching
  • Content Processing: Type-safe content receiving/sending with transformation pipelines
  • Server Abstraction: ApplicationEngine interface for different server implementations (Netty, Jetty, CIO)

Capabilities

Application and Lifecycle Management

Core application framework providing the main application instance, environment configuration, and plugin management system.

abstract class Application {
    abstract val environment: ApplicationEnvironment
    abstract val attributes: Attributes
    abstract val monitor: Events
    
    fun plugin(plugin: Plugin<*, *, *>): PluginInstance
}

interface ApplicationEnvironment {
    val config: ApplicationConfig
    val log: Logger
    val monitor: Events
    val developmentMode: Boolean
    val rootPath: String
    val classLoader: ClassLoader
}

suspend fun ApplicationCall.application(): Application

Application and Lifecycle

Request Processing and Content Receiving

Request handling functionality for accessing request properties, headers, parameters, and converting request content to Kotlin types.

interface ApplicationRequest {
    val call: ApplicationCall
    val pipeline: ApplicationReceivePipeline
    val queryParameters: Parameters
    val headers: Headers
    val local: RequestConnectionPoint
    val cookies: RequestCookies
    val httpMethod: HttpMethod
    val uri: String
}

suspend inline fun <reified T : Any> ApplicationCall.receive(): T
suspend inline fun <reified T : Any> ApplicationCall.receiveNullable(): T?
suspend fun ApplicationCall.receiveText(): String
suspend fun ApplicationCall.receiveParameters(): Parameters

Request Processing

Response Processing and Content Sending

Response handling functionality for setting status codes, headers, and sending various types of content back to clients.

interface ApplicationResponse {
    val call: ApplicationCall
    val pipeline: ApplicationSendPipeline
    val status: HttpStatusCode?
    val headers: ResponseHeaders
    val cookies: ResponseCookies
    val isCommitted: Boolean
    val isSent: Boolean
    
    fun status(value: HttpStatusCode)
}

suspend fun ApplicationCall.respond(message: Any)
suspend fun ApplicationCall.respond(status: HttpStatusCode, message: Any = "")
suspend fun ApplicationCall.respondText(text: String, contentType: ContentType? = null, status: HttpStatusCode? = null)
suspend fun ApplicationCall.respondBytes(bytes: ByteArray, contentType: ContentType? = null, status: HttpStatusCode? = null)
suspend fun ApplicationCall.respondRedirect(url: String, permanent: Boolean = false)

Response Processing

Routing and HTTP Method Handling

URL routing system with DSL for defining routes, handling different HTTP methods, and extracting path parameters.

class Route(
    val parent: Route?,
    val selector: RouteSelector,
    val developmentMode: Boolean = false,
    val environment: ApplicationEnvironment
) : ApplicationCallPipeline()

fun Route.get(path: String = "", body: PipelineInterceptor<Unit, ApplicationCall>): Route
fun Route.post(path: String = "", body: PipelineInterceptor<Unit, ApplicationCall>): Route
fun Route.put(path: String = "", body: PipelineInterceptor<Unit, ApplicationCall>): Route
fun Route.delete(path: String = "", body: PipelineInterceptor<Unit, ApplicationCall>): Route
fun Route.patch(path: String = "", body: PipelineInterceptor<Unit, ApplicationCall>): Route
fun Route.head(path: String = "", body: PipelineInterceptor<Unit, ApplicationCall>): Route
fun Route.options(path: String = "", body: PipelineInterceptor<Unit, ApplicationCall>): Route

fun Route.route(path: String, build: Route.() -> Unit): Route
fun Application.routing(configuration: Routing.() -> Unit): Routing

Routing

Plugin System and Extensions

Plugin architecture for extending Ktor functionality with application-level and route-scoped plugins.

interface ApplicationPlugin<out TConfiguration : Any> {
    val key: AttributeKey<*>
    fun install(pipeline: ApplicationCallPipeline, configure: TConfiguration.() -> Unit): Any
}

interface RouteScopedPlugin<TConfiguration : Any, TPlugin : Any> {
    val key: AttributeKey<TPlugin>
    fun install(pipeline: ApplicationCallPipeline, configure: TConfiguration.() -> Unit): TPlugin
}

fun <P : Any, B : Any, F : Any> createApplicationPlugin(
    name: String,
    createConfiguration: () -> B,
    body: PluginBuilder<P>.() -> Unit
): ApplicationPlugin<B, P, F>

fun <TConfiguration : Any> Application.install(
    plugin: ApplicationPlugin<TConfiguration, *, *>,
    configure: TConfiguration.() -> Unit = {}
)

Plugins

Configuration Management

Hierarchical configuration system with type conversion and environment-specific settings.

interface ApplicationConfig {
    fun property(path: String): ApplicationConfigValue
    fun propertyOrNull(path: String): ApplicationConfigValue?
    fun config(path: String): ApplicationConfig
    fun configList(path: String): List<ApplicationConfig>
    fun keys(): Set<String>
    fun toMap(): Map<String, Any?>
}

interface ApplicationConfigValue {
    fun getString(): String
    fun getList(): List<String>
}

class MapApplicationConfig : ApplicationConfig
class MergedApplicationConfig(vararg sources: ApplicationConfig) : ApplicationConfig

Configuration

Server Engine Abstraction

Engine abstraction layer for different server implementations and environment configuration.

interface ApplicationEngine {
    val environment: ApplicationEngineEnvironment
    fun start(wait: Boolean = true): ApplicationEngine
    fun stop(gracePeriodMillis: Long, timeoutMillis: Long)
}

interface ApplicationEngineEnvironment {
    val application: Application
    val log: Logger
    val config: ApplicationConfig
    val monitor: Events
    val developmentMode: Boolean
    val connectors: List<EngineConnectorConfig>
    val modules: List<Application.() -> Unit>
}

abstract class BaseApplicationEngine(
    final override val environment: ApplicationEngineEnvironment,
    val pipeline: EnginePipeline = defaultEnginePipeline(environment)
) : ApplicationEngine

Engine

Types

interface ApplicationCall {
    val application: Application
    val request: ApplicationRequest
    val response: ApplicationResponse
    val parameters: Parameters
    val attributes: Attributes
}

interface PipelineInterceptor<TSubject : Any, TContext : Any> : 
    suspend PipelineContext<TSubject, TContext>.(TSubject) -> Unit

interface Parameters {
    operator fun get(name: String): String?
    fun getAll(name: String): List<String>?
    fun names(): Set<String>
    fun isEmpty(): Boolean
    fun contains(name: String): Boolean
    fun contains(name: String, value: String): Boolean
    fun forEach(body: (String, List<String>) -> Unit)
}

enum class HttpStatusCode(val value: Int, val description: String) {
    OK(200, "OK"),
    Created(201, "Created"),
    NotFound(404, "Not Found"),
    InternalServerError(500, "Internal Server Error")
    // ... more status codes
}

interface Attributes {
    operator fun <T : Any> get(key: AttributeKey<T>): T
    operator fun <T : Any> set(key: AttributeKey<T>, value: T)
    fun <T : Any> getOrNull(key: AttributeKey<T>): T?
    operator fun <T : Any> contains(key: AttributeKey<T>): Boolean
    fun <T : Any> remove(key: AttributeKey<T>)
    fun <T : Any> put(key: AttributeKey<T>, value: T): T?
}

data class AttributeKey<T>(val name: String)

interface Events {  
    fun <T> subscribe(definition: EventDefinition<T>, handler: (T) -> Unit)
    fun <T> unsubscribe(definition: EventDefinition<T>, handler: (T) -> Unit)
    fun <T> raise(definition: EventDefinition<T>, value: T)
}

data class EventDefinition<T>(val name: String)