Kotlin Ktor Patterns

1---2name: kotlin-ktor-patterns3description: Ktor server patterns including routing DSL, plugins, authentication, Koin DI, kotlinx.serialization, WebSockets, and testApplication testing.4origin: ECC5---6 7# Ktor Server Patterns8 9Comprehensive Ktor patterns for building robust, maintainable HTTP servers with Kotlin coroutines.10 11## When to Activate12 13- Building Ktor HTTP servers14- Configuring Ktor plugins (Auth, CORS, ContentNegotiation, StatusPages)15- Implementing REST APIs with Ktor16- Setting up dependency injection with Koin17- Writing Ktor integration tests with testApplication18- Working with WebSockets in Ktor19 20## Application Structure21 22### Standard Ktor Project Layout23 24```text25src/main/kotlin/26├── com/example/27│   ├── Application.kt           # Entry point, module configuration28│   ├── plugins/29│   │   ├── Routing.kt           # Route definitions30│   │   ├── Serialization.kt     # Content negotiation setup31│   │   ├── Authentication.kt    # Auth configuration32│   │   ├── StatusPages.kt       # Error handling33│   │   └── CORS.kt              # CORS configuration34│   ├── routes/35│   │   ├── UserRoutes.kt        # /users endpoints36│   │   ├── AuthRoutes.kt        # /auth endpoints37│   │   └── HealthRoutes.kt      # /health endpoints38│   ├── models/39│   │   ├── User.kt              # Domain models40│   │   └── ApiResponse.kt       # Response envelopes41│   ├── services/42│   │   ├── UserService.kt       # Business logic43│   │   └── AuthService.kt       # Auth logic44│   ├── repositories/45│   │   ├── UserRepository.kt    # Data access interface46│   │   └── ExposedUserRepository.kt47│   └── di/48│       └── AppModule.kt         # Koin modules49src/test/kotlin/50├── com/example/51│   ├── routes/52│   │   └── UserRoutesTest.kt53│   └── services/54│       └── UserServiceTest.kt55```56 57### Application Entry Point58 59```kotlin60// Application.kt61fun main() {62    embeddedServer(Netty, port = 8080, module = Application::module).start(wait = true)63}64 65fun Application.module() {66    configureSerialization()67    configureAuthentication()68    configureStatusPages()69    configureCORS()70    configureDI()71    configureRouting()72}73```74 75## Routing DSL76 77### Basic Routes78 79```kotlin80// plugins/Routing.kt81fun Application.configureRouting() {82    routing {83        userRoutes()84        authRoutes()85        healthRoutes()86    }87}88 89// routes/UserRoutes.kt90fun Route.userRoutes() {91    val userService by inject<UserService>()92 93    route("/users") {94        get {95            val users = userService.getAll()96            call.respond(users)97        }98 99        get("/{id}") {100            val id = call.parameters["id"]101                ?: return@get call.respond(HttpStatusCode.BadRequest, "Missing id")102            val user = userService.getById(id)103                ?: return@get call.respond(HttpStatusCode.NotFound)104            call.respond(user)105        }106 107        post {108            val request = call.receive<CreateUserRequest>()109            val user = userService.create(request)110            call.respond(HttpStatusCode.Created, user)111        }112 113        put("/{id}") {114            val id = call.parameters["id"]115                ?: return@put call.respond(HttpStatusCode.BadRequest, "Missing id")116            val request = call.receive<UpdateUserRequest>()117            val user = userService.update(id, request)118                ?: return@put call.respond(HttpStatusCode.NotFound)119            call.respond(user)120        }121 122        delete("/{id}") {123            val id = call.parameters["id"]124                ?: return@delete call.respond(HttpStatusCode.BadRequest, "Missing id")125            val deleted = userService.delete(id)126            if (deleted) call.respond(HttpStatusCode.NoContent)127            else call.respond(HttpStatusCode.NotFound)128        }129    }130}131```132 133### Route Organization with Authenticated Routes134 135```kotlin136fun Route.userRoutes() {137    route("/users") {138        // Public routes139        get { /* list users */ }140        get("/{id}") { /* get user */ }141 142        // Protected routes143        authenticate("jwt") {144            post { /* create user - requires auth */ }145            put("/{id}") { /* update user - requires auth */ }146            delete("/{id}") { /* delete user - requires auth */ }147        }148    }149}150```151 152## Content Negotiation & Serialization153 154### kotlinx.serialization Setup155 156```kotlin157// plugins/Serialization.kt158fun Application.configureSerialization() {159    install(ContentNegotiation) {160        json(Json {161            prettyPrint = true162            isLenient = false163            ignoreUnknownKeys = true164            encodeDefaults = true165            explicitNulls = false166        })167    }168}169```170 171### Serializable Models172 173```kotlin174@Serializable175data class UserResponse(176    val id: String,177    val name: String,178    val email: String,179    val role: Role,180    @Serializable(with = InstantSerializer::class)181    val createdAt: Instant,182)183 184@Serializable185data class CreateUserRequest(186    val name: String,187    val email: String,188    val role: Role = Role.USER,189)190 191@Serializable192data class ApiResponse<T>(193    val success: Boolean,194    val data: T? = null,195    val error: String? = null,196) {197    companion object {198        fun <T> ok(data: T): ApiResponse<T> = ApiResponse(success = true, data = data)199        fun <T> error(message: String): ApiResponse<T> = ApiResponse(success = false, error = message)200    }201}202 203@Serializable204data class PaginatedResponse<T>(205    val data: List<T>,206    val total: Long,207    val page: Int,208    val limit: Int,209)210```211 212### Custom Serializers213 214```kotlin215object InstantSerializer : KSerializer<Instant> {216    override val descriptor = PrimitiveSerialDescriptor("Instant", PrimitiveKind.STRING)217    override fun serialize(encoder: Encoder, value: Instant) =218        encoder.encodeString(value.toString())219    override fun deserialize(decoder: Decoder): Instant =220        Instant.parse(decoder.decodeString())221}222```223 224## Authentication225 226### JWT Authentication227 228```kotlin229// plugins/Authentication.kt230fun Application.configureAuthentication() {231    val jwtSecret = environment.config.property("jwt.secret").getString()232    val jwtIssuer = environment.config.property("jwt.issuer").getString()233    val jwtAudience = environment.config.property("jwt.audience").getString()234    val jwtRealm = environment.config.property("jwt.realm").getString()235 236    install(Authentication) {237        jwt("jwt") {238            realm = jwtRealm239            verifier(240                JWT.require(Algorithm.HMAC256(jwtSecret))241                    .withAudience(jwtAudience)242                    .withIssuer(jwtIssuer)243                    .build()244            )245            validate { credential ->246                if (credential.payload.audience.contains(jwtAudience)) {247                    JWTPrincipal(credential.payload)248                } else {249                    null250                }251            }252            challenge { _, _ ->253                call.respond(HttpStatusCode.Unauthorized, ApiResponse.error<Unit>("Invalid or expired token"))254            }255        }256    }257}258 259// Extracting user from JWT260fun ApplicationCall.userId(): String =261    principal<JWTPrincipal>()262        ?.payload263        ?.getClaim("userId")264        ?.asString()265        ?: throw AuthenticationException("No userId in token")266```267 268### Auth Routes269 270```kotlin271fun Route.authRoutes() {272    val authService by inject<AuthService>()273 274    route("/auth") {275        post("/login") {276            val request = call.receive<LoginRequest>()277            val token = authService.login(request.email, request.password)278                ?: return@post call.respond(279                    HttpStatusCode.Unauthorized,280                    ApiResponse.error<Unit>("Invalid credentials"),281                )282            call.respond(ApiResponse.ok(TokenResponse(token)))283        }284 285        post("/register") {286            val request = call.receive<RegisterRequest>()287            val user = authService.register(request)288            call.respond(HttpStatusCode.Created, ApiResponse.ok(user))289        }290 291        authenticate("jwt") {292            get("/me") {293                val userId = call.userId()294                val user = authService.getProfile(userId)295                call.respond(ApiResponse.ok(user))296            }297        }298    }299}300```301 302## Status Pages (Error Handling)303 304```kotlin305// plugins/StatusPages.kt306fun Application.configureStatusPages() {307    install(StatusPages) {308        exception<ContentTransformationException> { call, cause ->309            call.respond(310                HttpStatusCode.BadRequest,311                ApiResponse.error<Unit>("Invalid request body: ${cause.message}"),312            )313        }314 315        exception<IllegalArgumentException> { call, cause ->316            call.respond(317                HttpStatusCode.BadRequest,318                ApiResponse.error<Unit>(cause.message ?: "Bad request"),319            )320        }321 322        exception<AuthenticationException> { call, _ ->323            call.respond(324                HttpStatusCode.Unauthorized,325                ApiResponse.error<Unit>("Authentication required"),326            )327        }328 329        exception<AuthorizationException> { call, _ ->330            call.respond(331                HttpStatusCode.Forbidden,332                ApiResponse.error<Unit>("Access denied"),333            )334        }335 336        exception<NotFoundException> { call, cause ->337            call.respond(338                HttpStatusCode.NotFound,339                ApiResponse.error<Unit>(cause.message ?: "Resource not found"),340            )341        }342 343        exception<Throwable> { call, cause ->344            call.application.log.error("Unhandled exception", cause)345            call.respond(346                HttpStatusCode.InternalServerError,347                ApiResponse.error<Unit>("Internal server error"),348            )349        }350 351        status(HttpStatusCode.NotFound) { call, status ->352            call.respond(status, ApiResponse.error<Unit>("Route not found"))353        }354    }355}356```357 358## CORS Configuration359 360```kotlin361// plugins/CORS.kt362fun Application.configureCORS() {363    install(CORS) {364        allowHost("localhost:3000")365        allowHost("example.com", schemes = listOf("https"))366        allowHeader(HttpHeaders.ContentType)367        allowHeader(HttpHeaders.Authorization)368        allowMethod(HttpMethod.Put)369        allowMethod(HttpMethod.Delete)370        allowMethod(HttpMethod.Patch)371        allowCredentials = true372        maxAgeInSeconds = 3600373    }374}375```376 377## Koin Dependency Injection378 379### Module Definition380 381```kotlin382// di/AppModule.kt383val appModule = module {384    // Database385    single<Database> { DatabaseFactory.create(get()) }386 387    // Repositories388    single<UserRepository> { ExposedUserRepository(get()) }389    single<OrderRepository> { ExposedOrderRepository(get()) }390 391    // Services392    single { UserService(get()) }393    single { OrderService(get(), get()) }394    single { AuthService(get(), get()) }395}396 397// Application setup398fun Application.configureDI() {399    install(Koin) {400        modules(appModule)401    }402}403```404 405### Using Koin in Routes406 407```kotlin408fun Route.userRoutes() {409    val userService by inject<UserService>()410 411    route("/users") {412        get {413            val users = userService.getAll()414            call.respond(ApiResponse.ok(users))415        }416    }417}418```419 420### Koin for Testing421 422```kotlin423class UserServiceTest : FunSpec(), KoinTest {424    override fun extensions() = listOf(KoinExtension(testModule))425 426    private val testModule = module {427        single<UserRepository> { mockk() }428        single { UserService(get()) }429    }430 431    private val repository by inject<UserRepository>()432    private val service by inject<UserService>()433 434    init {435        test("getUser returns user") {436            coEvery { repository.findById("1") } returns testUser437            service.getById("1") shouldBe testUser438        }439    }440}441```442 443## Request Validation444 445```kotlin446// Validate request data in routes447fun Route.userRoutes() {448    val userService by inject<UserService>()449 450    post("/users") {451        val request = call.receive<CreateUserRequest>()452 453        // Validate454        require(request.name.isNotBlank()) { "Name is required" }455        require(request.name.length <= 100) { "Name must be 100 characters or less" }456        require(request.email.matches(Regex(".+@.+\\..+"))) { "Invalid email format" }457 458        val user = userService.create(request)459        call.respond(HttpStatusCode.Created, ApiResponse.ok(user))460    }461}462 463// Or use a validation extension464fun CreateUserRequest.validate() {465    require(name.isNotBlank()) { "Name is required" }466    require(name.length <= 100) { "Name must be 100 characters or less" }467    require(email.matches(Regex(".+@.+\\..+"))) { "Invalid email format" }468}469```470 471## WebSockets472 473```kotlin474fun Application.configureWebSockets() {475    install(WebSockets) {476        pingPeriod = 15.seconds477        timeout = 15.seconds478        maxFrameSize = 64 * 1024 // 64 KiB — increase only if your protocol requires larger frames479        masking = false // Server-to-client frames are unmasked per RFC 6455; client-to-server are always masked by Ktor480    }481}482 483fun Route.chatRoutes() {484    val connections = Collections.synchronizedSet<Connection>(LinkedHashSet())485 486    webSocket("/chat") {487        val thisConnection = Connection(this)488        connections += thisConnection489 490        try {491            send("Connected! Users online: ${connections.size}")492 493            for (frame in incoming) {494                frame as? Frame.Text ?: continue495                val text = frame.readText()496                val message = ChatMessage(thisConnection.name, text)497 498                // Snapshot under lock to avoid ConcurrentModificationException499                val snapshot = synchronized(connections) { connections.toList() }500                snapshot.forEach { conn ->501                    conn.session.send(Json.encodeToString(message))502                }503            }504        } catch (e: Exception) {505            logger.error("WebSocket error", e)506        } finally {507            connections -= thisConnection508        }509    }510}511 512data class Connection(val session: DefaultWebSocketSession) {513    val name: String = "User-${counter.getAndIncrement()}"514 515    companion object {516        private val counter = AtomicInteger(0)517    }518}519```520 521## testApplication Testing522 523### Basic Route Testing524 525```kotlin526class UserRoutesTest : FunSpec({527    test("GET /users returns list of users") {528        testApplication {529            application {530                install(Koin) { modules(testModule) }531                configureSerialization()532                configureRouting()533            }534 535            val response = client.get("/users")536 537            response.status shouldBe HttpStatusCode.OK538            val body = response.body<ApiResponse<List<UserResponse>>>()539            body.success shouldBe true540            body.data.shouldNotBeNull().shouldNotBeEmpty()541        }542    }543 544    test("POST /users creates a user") {545        testApplication {546            application {547                install(Koin) { modules(testModule) }548                configureSerialization()549                configureStatusPages()550                configureRouting()551            }552 553            val client = createClient {554                install(io.ktor.client.plugins.contentnegotiation.ContentNegotiation) {555                    json()556                }557            }558 559            val response = client.post("/users") {560                contentType(ContentType.Application.Json)561                setBody(CreateUserRequest("Alice", "alice@example.com"))562            }563 564            response.status shouldBe HttpStatusCode.Created565        }566    }567 568    test("GET /users/{id} returns 404 for unknown id") {569        testApplication {570            application {571                install(Koin) { modules(testModule) }572                configureSerialization()573                configureStatusPages()574                configureRouting()575            }576 577            val response = client.get("/users/unknown-id")578 579            response.status shouldBe HttpStatusCode.NotFound580        }581    }582})583```584 585### Testing Authenticated Routes586 587```kotlin588class AuthenticatedRoutesTest : FunSpec({589    test("protected route requires JWT") {590        testApplication {591            application {592                install(Koin) { modules(testModule) }593                configureSerialization()594                configureAuthentication()595                configureRouting()596            }597 598            val response = client.post("/users") {599                contentType(ContentType.Application.Json)600                setBody(CreateUserRequest("Alice", "alice@example.com"))601            }602 603            response.status shouldBe HttpStatusCode.Unauthorized604        }605    }606 607    test("protected route succeeds with valid JWT") {608        testApplication {609            application {610                install(Koin) { modules(testModule) }611                configureSerialization()612                configureAuthentication()613                configureRouting()614            }615 616            val token = generateTestJWT(userId = "test-user")617 618            val client = createClient {619                install(io.ktor.client.plugins.contentnegotiation.ContentNegotiation) { json() }620            }621 622            val response = client.post("/users") {623                contentType(ContentType.Application.Json)624                bearerAuth(token)625                setBody(CreateUserRequest("Alice", "alice@example.com"))626            }627 628            response.status shouldBe HttpStatusCode.Created629        }630    }631})632```633 634## Configuration635 636### application.yaml637 638```yaml639ktor:640  application:641    modules:642      - com.example.ApplicationKt.module643  deployment:644    port: 8080645 646jwt:647  secret: ${JWT_SECRET}648  issuer: "https://example.com"649  audience: "https://example.com/api"650  realm: "example"651 652database:653  url: ${DATABASE_URL}654  driver: "org.postgresql.Driver"655  maxPoolSize: 10656```657 658### Reading Config659 660```kotlin661fun Application.configureDI() {662    val dbUrl = environment.config.property("database.url").getString()663    val dbDriver = environment.config.property("database.driver").getString()664    val maxPoolSize = environment.config.property("database.maxPoolSize").getString().toInt()665 666    install(Koin) {667        modules(module {668            single { DatabaseConfig(dbUrl, dbDriver, maxPoolSize) }669            single { DatabaseFactory.create(get()) }670        })671    }672}673```674 675## Quick Reference: Ktor Patterns676 677| Pattern | Description |678|---------|-------------|679| `route("/path") { get { } }` | Route grouping with DSL |680| `call.receive<T>()` | Deserialize request body |681| `call.respond(status, body)` | Send response with status |682| `call.parameters["id"]` | Read path parameters |683| `call.request.queryParameters["q"]` | Read query parameters |684| `install(Plugin) { }` | Install and configure plugin |685| `authenticate("name") { }` | Protect routes with auth |686| `by inject<T>()` | Koin dependency injection |687| `testApplication { }` | Integration testing |688 689**Remember**: Ktor is designed around Kotlin coroutines and DSLs. Keep routes thin, push logic to services, and use Koin for dependency injection. Test with `testApplication` for full integration coverage.