Ktor Server skill for Codex

Done well means: the app is split into extension-function modules that tests can install individually, request and response bodies are @Serializable data classes, every error path goes through StatusPages to one JSON shape, blocking I/O never runs on the event loop, and each route has a testApplication test.

Before changing anything

1. Read AGENTS.md, build.gradle.kts (Ktor version, engine artifact such as ktor-server-netty or ktor-server-cio, serialization plugin) and the main entry.
2. Find the config source: application.yaml / application.conf with EngineMain, or code-only embeddedServer(...). Keep whichever the project uses.
3. Baseline: ./gradlew build. Gradle downloads need network; offline, rely on the local Gradle cache or ask before enabling network.

Structure

fun main(args: Array<String>) = io.ktor.server.netty.EngineMain.main(args)

// application.yaml: ktor.application.modules lists these
fun Application.module() {
    configureSerialization()
    configureMonitoring()
    configureErrors()
    configureSecurity()
    configureRouting(OrderService(Database.connect(environment.config)))
}

ktor:
  deployment:
    port: "$PORT:8080"
  application:
    modules:
      - com.acme.ApplicationKt.module
jwt:
  issuer: "https://auth.acme.dev/"
  audience: "orders-api"
  secret: "$JWT_SECRET"

"$ENV:default" reads an environment variable with a fallback. Read values with environment.config.property("jwt.issuer").getString(). Never commit secrets in config.

Pass dependencies into routing functions (constructor-style) or use a DI container (Koin, or the Ktor DI plugin in 3.2+). Avoid top-level singletons that tests cannot replace.

Plugins

fun Application.configureSerialization() {
    install(ContentNegotiation) {
        json(Json { ignoreUnknownKeys = true; explicitNulls = false })
    }
}

fun Application.configureMonitoring() {
    install(CallId) { retrieveFromHeader(HttpHeaders.XRequestId); generate { UUID.randomUUID().toString() } }
    install(CallLogging) { callIdMdc("call-id"); filter { it.request.path().startsWith("/api") } }
}

fun Application.configureErrors() {
    install(StatusPages) {
        exception<RequestValidationException> { call, e ->
            call.respond(HttpStatusCode.UnprocessableEntity, ApiError("validation_failed", e.reasons))
        }
        exception<BadRequestException> { call, e ->
            call.respond(HttpStatusCode.BadRequest, ApiError("bad_request", listOfNotNull(e.message)))
        }
        exception<NotFoundException> { call, _ ->
            call.respond(HttpStatusCode.NotFound, ApiError("not_found"))
        }
        exception<Throwable> { call, e ->
            call.application.log.error("Unhandled", e)
            call.respond(HttpStatusCode.InternalServerError, ApiError("internal"))
        }
    }
    install(RequestValidation) {
        validate<CreateOrder> { o ->
            if (o.quantity !in 1..100) ValidationResult.Invalid("quantity must be 1..100")
            else ValidationResult.Valid
        }
    }
}

@Serializable
data class ApiError(val code: String, val details: List<String> = emptyList())

Plugin	Why
ContentNegotiation + json()	Without it call.receive<T>() fails with 415 and respond(obj) fails
StatusPages	Single error shape; keeps try/catch out of routes
RequestValidation	Declarative checks on received bodies; throws RequestValidationException
CallId + CallLogging	Request IDs in MDC for every log line
Authentication	JWT, sessions, OAuth; wrap protected routes in authenticate {}
CORS, DefaultHeaders, Compression	Only when needed; CORS allow-list explicit hosts

Routing

fun Application.configureRouting(orders: OrderService) {
    routing {
        get("/healthz") { call.respond(HttpStatusCode.NoContent) }
        route("/api/orders") {
            authenticate("auth-jwt") {
                get("/{id}") {
                    val id = call.parameters.getOrFail<Long>("id")   // 400 if missing or not a Long
                    val order = orders.find(id) ?: throw NotFoundException()
                    call.respond(order)
                }
                post {
                    val userId = call.principal<JWTPrincipal>()!!.subject!!
                    val req = call.receive<CreateOrder>()
                    call.respond(HttpStatusCode.Created, orders.create(userId, req))
                }
            }
        }
    }
}

• call.receive reads the body once. A second receive fails unless the DoubleReceive plugin is installed; receive once and pass the object along.
• For many routes with typed parameters, the Resources plugin (@Resource classes and get<Orders.Id> { res -> }) gives compile-checked paths and URL building.

JWT authentication

fun Application.configureSecurity() {
    val cfg = environment.config
    val issuer = cfg.property("jwt.issuer").getString()
    val audience = cfg.property("jwt.audience").getString()
    install(Authentication) {
        jwt("auth-jwt") {
            realm = "orders-api"
            verifier(
                JWT.require(Algorithm.HMAC256(cfg.property("jwt.secret").getString()))
                    .withIssuer(issuer).withAudience(audience).build()
            )
            validate { cred -> if (cred.payload.subject != null) JWTPrincipal(cred.payload) else null }
            challenge { _, _ -> call.respond(HttpStatusCode.Unauthorized, ApiError("unauthorized")) }
        }
    }
}

For tokens from an identity provider, verify with its JWKS (jwt { verifier(jwkProvider, issuer) }) rather than a shared secret.

Coroutines and blocking work

Ktor handlers run on a small event-loop pool. JDBC, file I/O and CPU-heavy work must leave it:

suspend fun <T> dbQuery(block: () -> T): T = withContext(Dispatchers.IO) { transaction { block() } }

With Exposed, newSuspendedTransaction(Dispatchers.IO) { ... } does the same. Use a coroutine-native client (Ktor client, R2DBC, the Lettuce coroutine API) where one exists. Never call runBlocking inside a route.

Testing

class OrderRoutesTest {
    @Test
    fun `unknown order returns 404`() = testApplication {
        environment { config = MapApplicationConfig("jwt.issuer" to "t", "jwt.audience" to "t", "jwt.secret" to "s") }
        application {
            configureSerialization(); configureErrors(); configureSecurity()
            configureRouting(FakeOrderService())
        }
        val client = createClient { install(ClientContentNegotiation) { json() } }
        val res = client.get("/api/orders/999") { bearerAuth(testToken("s")) }
        assertEquals(HttpStatusCode.NotFound, res.status)
    }
}

Import the client plugin with an alias (io.ktor.client.plugins.contentnegotiation.ContentNegotiation as ClientContentNegotiation) to avoid clashing with the server plugin. Installing modules piecemeal is why modules should take their dependencies as parameters.

Build and run

./gradlew test
./gradlew buildFatJar          # io.ktor.plugin; output in build/libs/*-all.jar
./gradlew run                  # local dev

The Ktor Gradle plugin also offers buildImage / publishImageToLocalRegistry through Jib; publishing an image to a remote registry is outward-facing, so confirm with the user.

Checklist

• Modules are extension functions taking dependencies as parameters
• Bodies are @Serializable; ContentNegotiation configured once
• StatusPages maps validation, bad request, not found, and fallback 500
• Protected routes inside authenticate; config secrets from environment
• Blocking calls on Dispatchers.IO
• ./gradlew build green with a testApplication test per route

Gotchas

• Forgetting the kotlin("plugin.serialization") Gradle plugin compiles fine but fails at runtime with “Serializer for class … is not found”.
• call.respond(someMap) with mixed value types cannot be serialized; use a data class.
• Route order matters only within the same specificity; a literal segment beats a parameter.
• Upgrading from Ktor 2: package and API changes (for example engine and config APIs, kotlinx.io based I/O); follow the official migration guide rather than guessing.