Ktor Framework Guide

Applies to: Ktor 2.x, Kotlin 1.9+, Microservices, REST APIs, WebSockets

Overview

Ktor is a lightweight, asynchronous framework built by JetBrains for Kotlin. It leverages coroutines for non-blocking I/O and provides a flexible plugin system for extensibility.

Best For: Microservices, lightweight APIs, real-time applications, Kotlin-native projects

Key Characteristics:

• Native Kotlin coroutines (non-blocking by default)

• Modular plugin architecture (install only what you use)

• Type-safe routing DSL

• Built-in test engine (testApplication )

• Multiple server engines: Netty, Jetty, CIO, Tomcat

• First-class WebSocket support

• Multiplatform HTTP client

Core Principles

• Plugins Over Middleware: Configure behavior via installable plugins, not middleware chains

• Coroutine-First: All request handling is suspending; never block the event loop

• Type-Safe DSL: Use Kotlin's type system for routing, configuration, and serialization

• Explicit Dependencies: Wire services manually or via a lightweight DI container

• HOCON Configuration: Use application.conf with environment variable overrides

Project Structure

myapp/ ├── src/main/kotlin/com/example/ │ ├── Application.kt # Entry point, module composition │ ├── plugins/ # Plugin configuration (one file per plugin) │ │ ├── Routing.kt │ │ ├── Serialization.kt │ │ ├── Security.kt │ │ ├── StatusPages.kt │ │ ├── Validation.kt │ │ └── Databases.kt │ ├── routes/ # Route definitions (Route extensions) │ │ ├── UserRoutes.kt │ │ └── AuthRoutes.kt │ ├── models/ # Data models, DTOs, table definitions │ │ ├── User.kt │ │ └── Requests.kt │ ├── services/ # Business logic layer │ │ └── UserService.kt │ ├── repositories/ # Data access layer (Exposed) │ │ └── UserRepository.kt │ └── utils/ # Utilities (JWT, hashing, etc.) │ └── JwtUtils.kt ├── src/main/resources/ │ ├── application.conf # HOCON configuration │ └── logback.xml ├── src/test/kotlin/com/example/ │ ├── ApplicationTest.kt # Integration tests with testApplication │ └── services/UserServiceTest.kt # Unit tests with MockK ├── build.gradle.kts └── gradle.properties

Conventions:

• One plugin configuration per file in plugins/

• Routes defined as Route extension functions in routes/

• Services injected via constructor parameters (no global singletons)

• models/ contains Exposed table objects, domain models, and serializable DTOs

• repositories/ wraps all database access behind suspend functions

Guardrails

Application Module

• Define a single Application.module() that composes plugins in order

• Plugin install order matters: Serialization before Routing, StatusPages early

• Use embeddedServer() for simple apps, EngineMain for HOCON-driven startup

• Never put business logic in Application.kt

fun Application.module() { configureSerialization() // ContentNegotiation first configureValidation() // RequestValidation before routing configureSecurity() // Authentication before protected routes configureStatusPages() // Error handling catches all configureDatabases() // Database connection pool configureRouting() // Routes last (depends on all above) }

Configuration (HOCON)

• Use application.conf with environment variable overrides via ${?ENV_VAR}

• Never hardcode secrets; always provide env var fallbacks

• Group related settings under namespaces (database , jwt , server )

• Access config via environment.config.property("path").getString()

ktor { deployment { port = 8080, port = ${?PORT} } application { modules = [ com.example.ApplicationKt.module ] } } database { url = "jdbc:postgresql://localhost:5432/myapp" url = ${?DATABASE_URL} driver = "org.postgresql.Driver" user = ${?DATABASE_USER} password = ${?DATABASE_PASSWORD} maxPoolSize = 10 } jwt { secret = ${?JWT_SECRET} issuer = "myapp" audience = "myapp-users" realm = "myapp" expirationMs = 3600000 }

Serialization

• Use kotlinx.serialization with ContentNegotiation plugin

• Configure lenient parsing and unknown key ignoring for forward compatibility

• All DTOs must be @Serializable data classes

• Separate request DTOs from response DTOs from domain models

fun Application.configureSerialization() { install(ContentNegotiation) { json(Json { prettyPrint = false // disable in production isLenient = true ignoreUnknownKeys = true encodeDefaults = true }) } }

Routing

• Define routes as Route extension functions (not inline in configureRouting )

• Group routes under versioned prefixes (/api/v1/... )

• Use authenticate("scheme") blocks to protect routes

• Parse path/query parameters with null-safe handling and validation

• Return appropriate HTTP status codes (Created , NoContent , BadRequest )

fun Route.userRoutes(userService: UserService) { route("/users") { post { val request = call.receive<CreateUserRequest>() val user = userService.createUser(request) call.respond(HttpStatusCode.Created, user) } authenticate("auth-jwt") { get { val limit = call.parameters["limit"]?.toIntOrNull() ?: 20 val offset = call.parameters["offset"]?.toLongOrNull() ?: 0 call.respond(userService.getAllUsers(limit, offset)) } get("/{id}") { val id = call.parameters["id"]?.toLongOrNull() ?: return@get call.respond(HttpStatusCode.BadRequest, "Invalid ID") call.respond(userService.getUserById(id)) } } } }

Request Validation

• Install RequestValidation plugin for declarative input validation

• Validate all request DTOs before they reach service layer

• Return structured error messages via ValidationResult.Invalid

• Handle RequestValidationException in StatusPages

fun Application.configureValidation() { install(RequestValidation) { validate<CreateUserRequest> { req -> val errors = buildList { if (!req.email.contains("@")) add("Invalid email format") if (req.password.length < 8) add("Password must be at least 8 characters") if (req.name.isBlank()) add("Name is required") } if (errors.isNotEmpty()) ValidationResult.Invalid(errors) else ValidationResult.Valid } } }

Authentication (JWT)

• Use Authentication plugin with named JWT schemes

• Validate claims in the validate block; return null to reject

• Return structured error in challenge block (not raw strings)

• Extract claims from JWTPrincipal in routes, never parse tokens manually

fun Application.configureSecurity() { val config = environment.config install(Authentication) { jwt("auth-jwt") { realm = config.property("jwt.realm").getString() verifier(JWT.require(Algorithm.HMAC256(config.property("jwt.secret").getString())) .withAudience(config.property("jwt.audience").getString()) .withIssuer(config.property("jwt.issuer").getString()) .build()) validate { credential -> val userId = credential.payload.getClaim("userId").asString() if (userId != null) JWTPrincipal(credential.payload) else null } challenge { _, _ -> call.respond(HttpStatusCode.Unauthorized, ErrorResponse(401, "UNAUTHORIZED", "Token is not valid or has expired")) } } } }

Error Handling (StatusPages)

• Install StatusPages plugin to centralize exception-to-response mapping

• Define custom exception hierarchy (sealed class or separate classes)

• Never expose internal exception details to clients

• Always include a catch-all Throwable handler that logs and returns 500

@Serializable data class ErrorResponse(val status: Int, val error: String, val message: String)

class NotFoundException(message: String) : RuntimeException(message) class ConflictException(message: String) : RuntimeException(message)

fun Application.configureStatusPages() { install(StatusPages) { exception<NotFoundException> { call, cause -> call.respond(HttpStatusCode.NotFound, ErrorResponse(404, "NOT_FOUND", cause.message ?: "Resource not found")) } exception<RequestValidationException> { call, cause -> call.respond(HttpStatusCode.BadRequest, ErrorResponse(400, "VALIDATION_ERROR", cause.reasons.joinToString("; "))) } exception<Throwable> { call, cause -> call.application.environment.log.error("Unhandled exception", cause) call.respond(HttpStatusCode.InternalServerError, ErrorResponse(500, "INTERNAL_ERROR", "An unexpected error occurred")) } } }

Database (Exposed ORM)

• Use HikariCP connection pool with newSuspendedTransaction for coroutine safety

• Define tables as object : LongIdTable("name") in models/

• Wrap all DB calls in a suspend dbQuery helper

• Separate domain models from Exposed ResultRow mapping

• Use SchemaUtils.create() for dev; prefer migrations for production

// Repository pattern with suspend functions class UserRepository { private suspend fun <T> dbQuery(block: suspend () -> T): T = newSuspendedTransaction { block() }

suspend fun findById(id: Long): User? = dbQuery {
    Users.select { Users.id eq id }.map(User::fromRow).singleOrNull()
}

suspend fun create(email: String, passwordHash: String, name: String): User = dbQuery {
    val id = Users.insertAndGetId {
        it[Users.email] = email
        it[Users.passwordHash] = passwordHash
        it[Users.name] = name
    }
    Users.select { Users.id eq id }.map(User::fromRow).single()
}

}

Service Layer

• Services receive repositories and utilities via constructor injection

• All public methods are suspend functions

• Throw domain exceptions (NotFoundException , ConflictException ), not generic ones

• Services contain business logic; repositories contain data access only

Coroutine Safety

• Never call blocking I/O without withContext(Dispatchers.IO)

• Use withTimeout for external service calls

• Handle CancellationException correctly (rethrow, never swallow)

• Use supervisorScope when child failures should not cancel siblings

Testing

Integration Tests (testApplication)

class ApplicationTest { @Test fun create user returns 201() = testApplication { application { module() } val client = createClient { install(ContentNegotiation) { json() } } val response = client.post("/api/users") { contentType(ContentType.Application.Json) setBody(CreateUserRequest("test@example.com", "password123", "Test")) } assertEquals(HttpStatusCode.Created, response.status) } }

Unit Tests (MockK)

class UserServiceTest { private val repo = mockk<UserRepository>() private val jwt = mockk<JwtUtils>() private val service = UserService(repo, jwt)

@Test
fun `createUser with existing email throws ConflictException`() = runBlocking {
    coEvery { repo.existsByEmail(any()) } returns true
    assertFailsWith<ConflictException> {
        service.createUser(CreateUserRequest("dup@test.com", "pass1234", "Dup"))
    }
}

@AfterTest fun teardown() { clearAllMocks() }

}

Testing Standards

• Use testApplication for HTTP-level integration tests

• Use MockK with coEvery /coVerify for coroutine-aware mocking

• Test names describe behavior: create user with duplicate email throws ConflictException

• Use H2 in-memory database for integration tests

• Coverage target: >80% for services, >60% overall

Commands

Development

./gradlew run # Start dev server ./gradlew run -t # Auto-reload on changes

Build

./gradlew build # Compile + test + check ./gradlew buildFatJar # Build executable fat JAR java -jar build/libs/app.jar # Run production JAR

Test

./gradlew test # Run all tests ./gradlew test --tests "*.UserServiceTest" # Specific test class ./gradlew test --tests "create user" # Tests matching pattern

Quality

./gradlew ktlintCheck # Check formatting ./gradlew ktlintFormat # Auto-fix formatting ./gradlew detekt # Static analysis

Dependencies

./gradlew dependencies # Full dependency tree ./gradlew clean # Clean build artifacts

Do's and Don'ts

Do

• Configure plugins in separate files under plugins/

• Use suspend functions for all database and external calls

• Use Route extension functions to define typed routes

• Use kotlinx.serialization for JSON (not Jackson/Gson)

• Use newSuspendedTransaction for coroutine-safe DB access

• Handle errors centrally with StatusPages

• Use application.conf with env var overrides

• Inject dependencies via constructor parameters

Don't

• Block coroutines with synchronous I/O calls

• Use global mutable state without synchronization

• Expose internal exception messages to API clients

• Hardcode configuration values in source code

• Skip request validation on any user-facing endpoint

• Mix business logic into route handlers

• Use GlobalScope for request-scoped work

• Install plugins inside route blocks

When to Use Ktor

Choose Ktor when: building lightweight microservices, Kotlin is your primary language, you need fast startup times, you want fine-grained control over dependencies, building real-time applications (WebSockets), or creating serverless functions.

Consider alternatives when: you need extensive enterprise integrations (Spring Boot), team is more familiar with Spring, project requires complex security configurations, or you need a large third-party library ecosystem.

References

For detailed patterns, examples, and advanced topics, see:

• references/patterns.md -- Database integration, WebSocket patterns, testing strategies, deployment, Ktor client

External References

• Ktor Documentation

• Ktor Server Plugins

• Exposed ORM

• kotlinx.serialization

• MockK

• HikariCP

• Kotlin Coroutines