0
# Ktor Server Core JVM
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: io.ktor:ktor-server-core-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: `implementation("io.ktor:ktor-server-core:3.2.0")`
10

11
## Core Imports
12

13
```kotlin
14
import io.ktor.server.application.*
15
import io.ktor.server.routing.*
16
import io.ktor.server.request.*
17
import io.ktor.server.response.*
18
import io.ktor.server.plugins.*
19
import io.ktor.server.engine.*
20
```
21

22
## Basic Usage
23

24
```kotlin
25
import io.ktor.server.application.*
26
import io.ktor.server.response.*
27
import io.ktor.server.routing.*
28

29
fun Application.module() {
30
    routing {
31
        get("/") {
32
            call.respondText("Hello, World!")
33
        }
34
        
35
        post("/api/users") {
36
            val user = call.receive<User>()
37
            // Process user
38
            call.respond(HttpStatusCode.Created, user)
39
        }
40
    }
41
}
42
```
43

44
## Architecture
45

46
Ktor Server Core is built around several key architectural components:
47

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

55
## Capabilities
56

57
### Application and Lifecycle Management
58

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

61
```kotlin { .api }
62
abstract class Application {
63
    abstract val environment: ApplicationEnvironment
64
    abstract val attributes: Attributes
65
    abstract val monitor: Events
66
    
67
    fun plugin(plugin: Plugin<*, *, *>): PluginInstance
68
}
69

70
interface ApplicationEnvironment {
71
    val config: ApplicationConfig
72
    val log: Logger
73
    val monitor: Events
74
    val developmentMode: Boolean
75
    val rootPath: String
76
    val classLoader: ClassLoader
77
}
78

79
suspend fun ApplicationCall.application(): Application
80
```
81

82
[Application and Lifecycle](./application.md)
83

84
### Request Processing and Content Receiving
85

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

88
```kotlin { .api }
89
interface ApplicationRequest {
90
    val call: ApplicationCall
91
    val pipeline: ApplicationReceivePipeline
92
    val queryParameters: Parameters
93
    val headers: Headers
94
    val local: RequestConnectionPoint
95
    val cookies: RequestCookies
96
    val httpMethod: HttpMethod
97
    val uri: String
98
}
99

100
suspend inline fun <reified T : Any> ApplicationCall.receive(): T
101
suspend inline fun <reified T : Any> ApplicationCall.receiveNullable(): T?
102
suspend fun ApplicationCall.receiveText(): String
103
suspend fun ApplicationCall.receiveParameters(): Parameters
104
```
105

106
[Request Processing](./request.md)
107

108
### Response Processing and Content Sending
109

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

112
```kotlin { .api }
113
interface ApplicationResponse {
114
    val call: ApplicationCall
115
    val pipeline: ApplicationSendPipeline
116
    val status: HttpStatusCode?
117
    val headers: ResponseHeaders
118
    val cookies: ResponseCookies
119
    val isCommitted: Boolean
120
    val isSent: Boolean
121
    
122
    fun status(value: HttpStatusCode)
123
}
124

125
suspend fun ApplicationCall.respond(message: Any)
126
suspend fun ApplicationCall.respond(status: HttpStatusCode, message: Any = "")
127
suspend fun ApplicationCall.respondText(text: String, contentType: ContentType? = null, status: HttpStatusCode? = null)
128
suspend fun ApplicationCall.respondBytes(bytes: ByteArray, contentType: ContentType? = null, status: HttpStatusCode? = null)
129
suspend fun ApplicationCall.respondRedirect(url: String, permanent: Boolean = false)
130
```
131

132
[Response Processing](./response.md)
133

134
### Routing and HTTP Method Handling
135

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

138
```kotlin { .api }
139
class Route(
140
    val parent: Route?,
141
    val selector: RouteSelector,
142
    val developmentMode: Boolean = false,
143
    val environment: ApplicationEnvironment
144
) : ApplicationCallPipeline()
145

146
fun Route.get(path: String = "", body: PipelineInterceptor<Unit, ApplicationCall>): Route
147
fun Route.post(path: String = "", body: PipelineInterceptor<Unit, ApplicationCall>): Route
148
fun Route.put(path: String = "", body: PipelineInterceptor<Unit, ApplicationCall>): Route
149
fun Route.delete(path: String = "", body: PipelineInterceptor<Unit, ApplicationCall>): Route
150
fun Route.patch(path: String = "", body: PipelineInterceptor<Unit, ApplicationCall>): Route
151
fun Route.head(path: String = "", body: PipelineInterceptor<Unit, ApplicationCall>): Route
152
fun Route.options(path: String = "", body: PipelineInterceptor<Unit, ApplicationCall>): Route
153

154
fun Route.route(path: String, build: Route.() -> Unit): Route
155
fun Application.routing(configuration: Routing.() -> Unit): Routing
156
```
157

158
[Routing](./routing.md)
159

160
### Plugin System and Extensions
161

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

164
```kotlin { .api }
165
interface ApplicationPlugin<out TConfiguration : Any> {
166
    val key: AttributeKey<*>
167
    fun install(pipeline: ApplicationCallPipeline, configure: TConfiguration.() -> Unit): Any
168
}
169

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

175
fun <P : Any, B : Any, F : Any> createApplicationPlugin(
176
    name: String,
177
    createConfiguration: () -> B,
178
    body: PluginBuilder<P>.() -> Unit
179
): ApplicationPlugin<B, P, F>
180

181
fun <TConfiguration : Any> Application.install(
182
    plugin: ApplicationPlugin<TConfiguration, *, *>,
183
    configure: TConfiguration.() -> Unit = {}
184
)
185
```
186

187
[Plugins](./plugins.md)
188

189
### Configuration Management
190

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

193
```kotlin { .api }
194
interface ApplicationConfig {
195
    fun property(path: String): ApplicationConfigValue
196
    fun propertyOrNull(path: String): ApplicationConfigValue?
197
    fun config(path: String): ApplicationConfig
198
    fun configList(path: String): List<ApplicationConfig>
199
    fun keys(): Set<String>
200
    fun toMap(): Map<String, Any?>
201
}
202

203
interface ApplicationConfigValue {
204
    fun getString(): String
205
    fun getList(): List<String>
206
}
207

208
class MapApplicationConfig : ApplicationConfig
209
class MergedApplicationConfig(vararg sources: ApplicationConfig) : ApplicationConfig
210
```
211

212
[Configuration](./config.md)
213

214
### Server Engine Abstraction
215

216
Engine abstraction layer for different server implementations and environment configuration.
217

218
```kotlin { .api }
219
interface ApplicationEngine {
220
    val environment: ApplicationEngineEnvironment
221
    fun start(wait: Boolean = true): ApplicationEngine
222
    fun stop(gracePeriodMillis: Long, timeoutMillis: Long)
223
}
224

225
interface ApplicationEngineEnvironment {
226
    val application: Application
227
    val log: Logger
228
    val config: ApplicationConfig
229
    val monitor: Events
230
    val developmentMode: Boolean
231
    val connectors: List<EngineConnectorConfig>
232
    val modules: List<Application.() -> Unit>
233
}
234

235
abstract class BaseApplicationEngine(
236
    final override val environment: ApplicationEngineEnvironment,
237
    val pipeline: EnginePipeline = defaultEnginePipeline(environment)
238
) : ApplicationEngine
239
```
240

241
[Engine](./engine.md)
242

243
## Types
244

245
```kotlin { .api }
246
interface ApplicationCall {
247
    val application: Application
248
    val request: ApplicationRequest
249
    val response: ApplicationResponse
250
    val parameters: Parameters
251
    val attributes: Attributes
252
}
253

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

257
interface Parameters {
258
    operator fun get(name: String): String?
259
    fun getAll(name: String): List<String>?
260
    fun names(): Set<String>
261
    fun isEmpty(): Boolean
262
    fun contains(name: String): Boolean
263
    fun contains(name: String, value: String): Boolean
264
    fun forEach(body: (String, List<String>) -> Unit)
265
}
266

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

275
interface Attributes {
276
    operator fun <T : Any> get(key: AttributeKey<T>): T
277
    operator fun <T : Any> set(key: AttributeKey<T>, value: T)
278
    fun <T : Any> getOrNull(key: AttributeKey<T>): T?
279
    operator fun <T : Any> contains(key: AttributeKey<T>): Boolean
280
    fun <T : Any> remove(key: AttributeKey<T>)
281
    fun <T : Any> put(key: AttributeKey<T>, value: T): T?
282
}
283

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

286
interface Events {  
287
    fun <T> subscribe(definition: EventDefinition<T>, handler: (T) -> Unit)
288
    fun <T> unsubscribe(definition: EventDefinition<T>, handler: (T) -> Unit)
289
    fun <T> raise(definition: EventDefinition<T>, value: T)
290
}
291

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