0
# Application and Lifecycle Management
1

2
Core application framework providing the main application instance, environment configuration, and plugin management system for Ktor server applications.
3

4
## Capabilities
5

6
### Application Class
7

8
The main application instance that serves as the container for all server functionality, managing plugins, configuration, and lifecycle.
9

10
```kotlin { .api }
11
/**
12
 * Main application instance extending ApplicationCallPipeline
13
 */
14
class Application : ApplicationCallPipeline(), CoroutineScope {
15
    /** Application environment containing configuration and logging */
16
    val environment: ApplicationEnvironment
17
    /** Attributes for storing application-scoped data */
18
    val attributes: Attributes
19
    /** Event monitor for application lifecycle events */
20
    val monitor: Events
21
    /** Coroutine context for application scope */
22
    override val coroutineContext: CoroutineContext
23
    
24
    /** Get installed plugin instance by plugin key */
25
    fun <TPlugin : Any> plugin(plugin: Plugin<*, *, TPlugin>): TPlugin
26
    /** Get installed plugin instance or null if not installed */
27
    fun <TPlugin : Any> pluginOrNull(plugin: Plugin<*, *, TPlugin>): TPlugin?
28
    /** Access application configuration */
29
    val config: ApplicationConfig get() = environment.config
30
    /** Access application logger */
31
    val log: Logger get() = environment.log
32

33
    /** Property access to configuration with serialization */
34
    inline fun <reified T> property(path: String): T
35
    /** Safe property access that returns null if not found */
36
    inline fun <reified T> propertyOrNull(path: String): T?
37
}
38

39
/**
40
 * Server configuration containing modules and settings
41
 */
42
class ServerConfig {
43
    /** List of application modules to install */
44
    val modules: List<suspend Application.() -> Unit>
45
    /** Paths to watch for application reload */
46
    val watchPaths: List<String>
47
    /** Application's root path (prefix) */
48
    val rootPath: String
49
    /** Development mode flag */
50
    val developmentMode: Boolean
51
    /** Application environment */
52
    val environment: ApplicationEnvironment
53
}
54

55
/**
56
 * Builder for creating ServerConfig instances
57
 */
58
class ServerConfigBuilder(val environment: ApplicationEnvironment) {
59
    /** List of application modules */
60
    val modules: MutableList<suspend Application.() -> Unit>
61
    /** Paths to watch for application reload */
62
    var watchPaths: List<String>
63
    /** Application's root path (prefix) */
64
    var rootPath: String
65
    /** Development mode flag */
66
    var developmentMode: Boolean
67
    
68
    /** Add a module to the server configuration */
69
    fun module(module: suspend Application.() -> Unit)
70
    /** Build the final ServerConfig */
71
    fun build(): ServerConfig
72
}
73

74
/**
75
 * Create a server configuration
76
 */
77
fun serverConfig(
78
    environment: ApplicationEnvironment,
79
    configure: ServerConfigBuilder.() -> Unit = {}
80
): ServerConfig
81
```
82

83
### Application Environment
84

85
Provides access to application configuration, logging, development mode settings, and other environment-specific properties.
86

87
```kotlin { .api }
88
/**
89
 * Application environment providing access to configuration, classloader, and logging
90
 */
91
interface ApplicationEnvironment {
92
    /** Application configuration */
93
    val config: ApplicationConfig
94
    /** Application logger */
95
    val log: Logger
96
    /** Event monitor for lifecycle events */
97
    val monitor: Events
98
    /** Whether application is running in development mode */
99
    val developmentMode: Boolean
100
    /** Root path for the application */
101
    val rootPath: String
102
    /** Class loader for the application */
103
    val classLoader: ClassLoader
104
}
105
```
106

107
### Application Call
108

109
Represents a single HTTP request-response cycle with access to request, response, and application context.
110

111
```kotlin { .api }
112
/**
113
 * Represents a single HTTP request-response cycle
114
 */
115
interface ApplicationCall {
116
    /** The application instance handling this call */
117
    val application: Application
118
    /** The HTTP request */
119
    val request: ApplicationRequest
120
    /** The HTTP response */
121
    val response: ApplicationResponse
122
    /** URL and form parameters */
123
    val parameters: Parameters
124
    /** Call-scoped attributes for storing data */
125
    val attributes: Attributes
126
}
127

128
/** Access application from within a call context */
129
suspend fun ApplicationCall.application(): Application = application
130

131
/**
132
 * Property to access the application from within a call
133
 */
134
val ApplicationCall.application: Application
135
```
136

137
### Pipeline System
138

139
Core pipeline system for processing HTTP requests and responses through interceptor chains.
140

141
```kotlin { .api }
142
/**
143
 * Main pipeline for processing application calls
144
 */
145
open class ApplicationCallPipeline : Pipeline<Unit, ApplicationCall> {
146
    companion object {
147
        /** Setup phase for call processing */
148
        val Setup: PipelinePhase = PipelinePhase("Setup")
149
        /** Monitoring phase for call processing */
150
        val Monitoring: PipelinePhase = PipelinePhase("Monitoring")
151
        /** Plugins phase for call processing */
152
        val Plugins: PipelinePhase = PipelinePhase("Plugins")
153
        /** Call processing phase */
154
        val Call: PipelinePhase = PipelinePhase("Call")
155
        /** Fallback phase for unhandled calls */
156
        val Fallback: PipelinePhase = PipelinePhase("Fallback")
157
    }
158
    
159
    /** Install a plugin into this pipeline */
160
    fun <TConfiguration : Any, TPlugin : Any> install(
161
        plugin: BaseApplicationPlugin<*, TConfiguration, TPlugin>,
162
        configure: TConfiguration.() -> Unit = {}
163
    ): TPlugin
164
    
165
    /** Get installed plugin instance */
166
    fun <TPlugin : Any> plugin(plugin: Plugin<*, *, TPlugin>): TPlugin
167
    
168
    /** Get installed plugin instance or null if not installed */
169
    fun <TPlugin : Any> pluginOrNull(plugin: Plugin<*, *, TPlugin>): TPlugin?
170
}
171

172
/**
173
 * Pipeline for processing incoming content
174
 */
175
class ApplicationReceivePipeline : Pipeline<ApplicationReceiveRequest, ApplicationCall> {
176
    companion object {
177
        /** Before transformation phase */
178
        val Before: PipelinePhase = PipelinePhase("Before")
179
        /** Transformation phase */
180
        val Transform: PipelinePhase = PipelinePhase("Transform")
181
        /** After transformation phase */
182
        val After: PipelinePhase = PipelinePhase("After")
183
    }
184
}
185

186
/**
187
 * Pipeline for processing outgoing content
188
 */
189
class ApplicationSendPipeline : Pipeline<Any, ApplicationCall> {
190
    companion object {
191
        /** Before transformation phase */
192
        val Before: PipelinePhase = PipelinePhase("Before")
193
        /** Transform phase */
194
        val Transform: PipelinePhase = PipelinePhase("Transform")
195
        /** Render phase */
196
        val Render: PipelinePhase = PipelinePhase("Render")
197
        /** Content encoding phase */
198
        val ContentEncoding: PipelinePhase = PipelinePhase("ContentEncoding")
199
        /** Transfer encoding phase */ 
200
        val TransferEncoding: PipelinePhase = PipelinePhase("TransferEncoding")
201
        /** After phase */
202
        val After: PipelinePhase = PipelinePhase("After")
203
    }
204
}
205

206
/**
207
 * Pipeline for processing call responses
208
 */
209
class ApplicationResponsePipeline : Pipeline<Any, ApplicationCall> {
210
    companion object {
211
        /** Transform phase */
212
        val Transform: PipelinePhase = PipelinePhase("Transform")
213
        /** Render phase */
214
        val Render: PipelinePhase = PipelinePhase("Render")
215
        /** Content encoding phase */
216
        val ContentEncoding: PipelinePhase = PipelinePhase("ContentEncoding")
217
        /** After phase */
218
        val After: PipelinePhase = PipelinePhase("After")
219
    }
220
}
221

222
/**
223
 * Pipeline context for interceptors
224
 */
225
interface PipelineContext<TSubject : Any, TContext : Any> {
226
    /** Current pipeline subject */
227
    val subject: TSubject
228
    /** Pipeline execution context */
229
    val context: TContext
230
    /** Proceed to next interceptor */
231
    suspend fun proceed(): TSubject
232
    /** Proceed with modified subject */
233
    suspend fun proceedWith(subject: TSubject): TSubject
234
    /** Finish pipeline execution */
235
    fun finish()
236
}
237

238
/**
239
 * Type alias for pipeline interceptor function
240
 */
241
typealias PipelineInterceptor<TSubject, TContext> = 
242
    suspend PipelineContext<TSubject, TContext>.(TSubject) -> Unit
243
```
244

245
### Hook System
246

247
Event-driven extension points for cross-cutting concerns and application lifecycle management.
248

249
```kotlin { .api }
250
/**
251
 * Hook definition for event-driven extensions
252
 */
253
class Hook<T : Function<Unit>> {
254
    /** Install hook handler */
255
    fun install(handler: T)
256
    /** Uninstall hook handler */
257
    fun uninstall(handler: T)
258
}
259

260
/**
261
 * Application call hooks for lifecycle events
262
 */
263
object ApplicationCallHooks {
264
    /** Called when application call starts */
265
    val CallStart: Hook<(ApplicationCall) -> Unit>
266
    /** Called when application call completes */
267
    val CallFinished: Hook<(ApplicationCall) -> Unit>
268
    /** Called when application call fails */
269
    val CallFailed: Hook<(ApplicationCall, Throwable) -> Unit>
270
}
271

272
/** Install hook handler */
273
fun <T : Function<Unit>> Application.hook(hook: Hook<T>, handler: T)
274
```
275

276
### Application Module
277

278
Function type for configuring application modules and defining server behavior.
279

280
```kotlin { .api }
281
/**
282
 * Application module function type for configuration
283
 */
284
typealias ApplicationModule = Application.() -> Unit
285

286
/**
287
 * Configure application with module function
288
 */
289
fun Application.module(body: Application.() -> Unit) = body()
290
```
291

292
**Usage Examples:**
293

294
```kotlin
295
import io.ktor.server.application.*
296
import io.ktor.server.response.*
297
import io.ktor.server.routing.*
298

299
// Basic application module
300
fun Application.myModule() {
301
    routing {
302
        get("/health") {
303
            call.respondText("OK")
304
        }
305
    }
306
}
307

308
// Access application properties
309
fun Application.configExample() {
310
    val dbUrl = config.property("database.url").getString()
311
    val isDev = environment.developmentMode
312
    
313
    log.info("Starting application in ${if (isDev) "development" else "production"} mode")
314
    log.info("Database URL: $dbUrl")
315
}
316

317
// Hook installation
318
fun Application.hookExample() {
319
    hook(ApplicationCallHooks.CallStart) { call ->
320
        log.info("Processing ${call.request.httpMethod.value} ${call.request.uri}")
321
    }
322
    
323
    hook(ApplicationCallHooks.CallFinished) { call ->
324
        log.info("Completed ${call.request.uri} with status ${call.response.status()}")
325
    }
326
}
327
```