kotlin-ktor-patterns

What it does

Describes a collection of Ktor server patterns for building HTTP servers with Kotlin coroutines. It outlines a standard project structure, including entry point, wiring for serialization, authentication, status pages, CORS, DI with Koin, routing, and tests. It provides concrete Kotlin code snippets that show how to configure routing, content negotiation, authentication, status pages, CORS, DI, Koin usage in routes, request validation, and WebSockets. It also demonstrates test patterns using testApplication for route testing and Koin-based test modules. The patterns cover REST endpoints for users and authentication flows, including JWT-based security, protected routes, and error handling via ApiResponse envelopes. The content includes example models, serializers, and utility components (InstantSerializer, ApiResponse, PaginatedResponse) and shows how to wire DI into routes and tests.

How it works

• Application entry point is shown with embeddedServer(Netty, port = 8080) and module wiring that calls configureSerialization(), configureAuthentication(), configureStatusPages(), configureCORS(), configureDI(), and configureRouting().
• Routing DSL demonstrates how to define routes for /users, /auth, and /health with public and protected sections, including JWT-based authentication for protected endpoints.
• Content negotiation uses kotlinx.serialization, with a configured Json instance enabling prettyPrint, ignoreUnknownKeys, encodeDefaults, and explicitNulls settings. Serializable data classes for UserResponse, CreateUserRequest, ApiResponse, and PaginatedResponse are defined, along with a custom InstantSerializer.
• Authentication shows JWT setup, token validation, and a helper to extract userId from the JWT payload; authentication routes include /login, /register, and /me for authenticated users.
• StatusPages provides centralized error handling for common exceptions and 404 routing with ApiResponse wrappers.
• CORS configuration demonstrates allowed hosts, headers, methods, and credentials.
• Koin DI illustrates a module with Database, repositories, and services, plus application setup and usage in routes via inject<...>(). It also shows testing with a Koin test module and KoinTest integration in UserServiceTest.
• Request validation examples show in-route validation and a separate validate() extension for CreateUserRequest.
• WebSockets example configures WebSockets and defines a chat route that broadcasts messages to connected clients.
• testApplication Testing section provides patterns for testing routes with testApplication, including setup with Koin modules, serialization, status pages, and routing, plus usage of a client for POST/GET requests and assertions on response data via ApiResponse and UserResponse types.

When to use it

• When building Ktor HTTP servers and configuring Ktor plugins (Auth, CORS, ContentNegotiation, StatusPages)
• When implementing REST APIs with Ktor
• When setting up dependency injection with Koin
• When writing Ktor integration tests with testApplication
• When working with WebSockets in Ktor

What it can touch

• Files and packages under the standard Ktor project layout as shown (src/main/kotlin/com/example/...). Accesses through DI with Koin, including services, repositories, and modules. Routes reference UserService, AuthService, and related models. The provided code uses kotlin and Ktor APIs such as embeddedServer, Netty, ContentNegotiation, JWT Authentication, StatusPages, CORS, WebSockets, and testApplication tooling. Tools listed: codex, copilot, cursor.

Caveats

• The patterns assume a certain project layout and dependencies (Koin, kotlinx.serialization, JWT, WebSockets) and rely on a properties-based configuration for JWT (jwt.secret, jwt.issuer, jwt.audience, jwt.realm).
• The provided snippets are illustrative and show configuration and usage; actual integration may require additional boilerplate or environment setup not described here.