Intermediate

// build.gradle.kts: implementation("io.ktor:ktor-server-auth:3.0.3")

import io.ktor.server.application.*
import io.ktor.server.auth.*               // => Authentication plugin
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Application.configureAuthentication() {
    install(Authentication) {              // => Install authentication plugin
        basic("auth-basic") {              // => Register Basic auth with name "auth-basic"
                                            // => Name used to reference in authenticate blocks
            realm = "My Protected API"     // => Shown in browser auth dialog
                                            // => Also appears in WWW-Authenticate header
            validate { credentials ->      // => Called for every request to protected routes
                                            // => credentials.name = username
                                            // => credentials.password = password
                // Return UserIdPrincipal (success) or null (failure)
                if (credentials.name == "admin" &&
                    credentials.password == "secret123") {
                    UserIdPrincipal(credentials.name)  // => Wraps username as principal
                                                        // => Available as call.principal<UserIdPrincipal>()
                } else {
                    null                   // => null = authentication failed -> 401
                }
                // In production: check against database with bcrypt comparison
                // Never store plain-text passwords
            }
        }
    }
}

fun Application.configureRouting() {
    routing {
        // Unprotected route
        get("/public") {
            call.respondText("Public endpoint - no auth required")
        }

        // Protected route - requires "auth-basic" authentication
        authenticate("auth-basic") {       // => All routes inside are protected
            get("/admin") {
                val principal = call.principal<UserIdPrincipal>()  // => Get authenticated user
                                                                     // => Non-null inside authenticate block
                call.respondText("Hello, ${principal?.name}!")     // => "Hello, admin!"
            }
            get("/admin/stats") {
                call.respondText("Admin stats endpoint")
            }
        }
    }
}
// => GET /public              => 200 "Public endpoint - no auth required"
// => GET /admin               => 401 (no credentials)
// => GET /admin (Authorization: Basic YWRtaW46c2VjcmV0MTIz)
//    => 200 "Hello, admin!" (YWRtaW46c2VjcmV0MTIz = base64("admin:secret123"))

// build.gradle.kts:
// implementation("io.ktor:ktor-server-auth:3.0.3")
// implementation("io.ktor:ktor-server-auth-jwt:3.0.3")
// implementation("com.auth0:java-jwt:4.4.0")

import com.auth0.jwt.JWT
import com.auth0.jwt.algorithms.Algorithm
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.auth.jwt.*           // => JWT authentication support
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.http.*
import java.util.Date

// JWT configuration constants (move to application.conf in production)
private const val JWT_SECRET = "your-256-bit-secret-key-here"
private const val JWT_ISSUER = "https://myapp.com"
private const val JWT_AUDIENCE = "myapp-users"
private const val JWT_EXPIRY_MS = 86_400_000L  // => 24 hours in milliseconds

// Helper: generate a JWT token for a user
fun generateToken(userId: String, role: String): String {
    return JWT.create()
        .withIssuer(JWT_ISSUER)            // => Identifies who issued the token
        .withAudience(JWT_AUDIENCE)        // => Identifies intended recipients
        .withClaim("userId", userId)       // => Custom claim: userId
        .withClaim("role", role)           // => Custom claim: user role
        .withExpiresAt(                    // => Token expiration time
            Date(System.currentTimeMillis() + JWT_EXPIRY_MS)
        )
        .sign(Algorithm.HMAC256(JWT_SECRET))  // => Sign with HMAC-SHA256
                                               // => Signature prevents tampering
}

fun Application.configureJWT() {
    install(Authentication) {
        jwt("auth-jwt") {                  // => Register JWT auth with name "auth-jwt"
            realm = "ktor-jwt-example"
            verifier(                      // => Configure token verifier
                JWT.require(Algorithm.HMAC256(JWT_SECRET))  // => Must use same secret
                    .withIssuer(JWT_ISSUER)      // => Must match issuer claim
                    .withAudience(JWT_AUDIENCE)  // => Must match audience claim
                    .build()
            )
            validate { credential ->       // => Called after signature validation passes
                // credential.payload contains decoded claims
                val userId = credential.payload.getClaim("userId").asString()
                if (userId != null) {
                    JWTPrincipal(credential.payload)  // => Wrap payload as principal
                } else {
                    null                   // => Invalid claims -> 401
                }
            }
            challenge { defaultScheme, realm ->
                call.respond(HttpStatusCode.Unauthorized,
                    mapOf("error" to "Token is not valid or has expired"))
            }
        }
    }
}

fun Application.configureRouting() {
    routing {
        // Public: issue tokens
        post("/auth/login") {
            // In production: verify credentials against database first
            val token = generateToken("user-123", "user")
            call.respond(mapOf("token" to token))
            // => {"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}
        }

        authenticate("auth-jwt") {
            get("/profile") {
                val principal = call.principal<JWTPrincipal>()  // => Non-null here
                val userId = principal?.payload?.getClaim("userId")?.asString()
                val role = principal?.payload?.getClaim("role")?.asString()
                call.respondText("User: $userId, Role: $role")
                // => "User: user-123, Role: user"
            }
        }
    }
}
// => POST /auth/login => {"token": "eyJ..."}
// => GET /profile (Authorization: Bearer eyJ...) => "User: user-123, Role: user"
// => GET /profile (no token) => 401 {"error": "Token is not valid or has expired"}

// build.gradle.kts:
// implementation("io.ktor:ktor-server-sessions:3.0.3")
// implementation("io.ktor:ktor-server-auth:3.0.3")

import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.server.sessions.*            // => Sessions plugin
import io.ktor.http.*

// Session data class (must be serializable)
// Stored in the cookie or server-side
data class UserSession(
    val userId: String,                    // => Identifies the logged-in user
    val role: String                       // => User's role for authorization
)

fun Application.configureSessions() {
    install(Sessions) {                    // => Install sessions plugin
        cookie<UserSession>("user_session") {  // => Cookie name: "user_session"
                                                // => Type param = session data class
            cookie.path = "/"              // => Cookie valid for entire site
            cookie.maxAgeInSeconds = 86400  // => Session lasts 24 hours
            cookie.httpOnly = true         // => Prevent JS access (XSS protection)
            cookie.secure = true           // => HTTPS only
            cookie.extensions["SameSite"] = "Lax"  // => CSRF protection

            // Encrypt cookie to prevent tampering (REQUIRED for production)
            transform(SessionTransportTransformerEncrypt(
                hex("00112233445566778899aabbccddeeff"),  // => Encryption key (AES-256)
                hex("01020304050607080910111213141516")   // => Sign key (HMAC)
                // Generate with: java.security.SecureRandom().generateSeed(32)
            ))
        }
    }
}

fun Application.configureRouting() {
    routing {
        // Login endpoint: verify credentials, set session
        post("/login") {
            val params = call.receiveParameters()
            val username = params["username"] ?: return@post call.respond(HttpStatusCode.BadRequest)
            val password = params["password"] ?: return@post call.respond(HttpStatusCode.BadRequest)

            // In production: verify against database with bcrypt
            if (username == "alice" && password == "password123") {
                call.sessions.set(         // => Creates/overwrites the session cookie
                    UserSession(userId = "user-1", role = "admin")
                )
                call.respondRedirect("/dashboard")
            } else {
                call.respond(HttpStatusCode.Unauthorized)
            }
        }

        // Protected: require active session
        get("/dashboard") {
            val session = call.sessions.get<UserSession>()  // => Read session; null if not logged in
            if (session == null) {
                call.respondRedirect("/login")
                return@get
            }
            call.respondText("Welcome, ${session.userId}! Role: ${session.role}")
        }

        // Logout: clear session
        post("/logout") {
            call.sessions.clear<UserSession>()  // => Removes session cookie
            call.respondRedirect("/login")
        }
    }
}
// => POST /login username=alice&password=password123 => Sets cookie, redirects to /dashboard
// => GET /dashboard (with valid cookie) => "Welcome, user-1! Role: admin"
// => GET /dashboard (no cookie) => redirects to /login
// => POST /logout => Clears cookie, redirects to /login

// build.gradle.kts:
// implementation("io.ktor:ktor-server-auth:3.0.3")
// implementation("io.ktor:ktor-client-core:3.0.3")
// implementation("io.ktor:ktor-client-cio:3.0.3")

import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.http.*

// HttpClient for Ktor's OAuth to make token exchange calls
val httpClient = HttpClient(CIO)         // => Required by OAuth auth provider

fun Application.configureOAuth() {
    install(Authentication) {
        oauth("auth-oauth-github") {     // => Register OAuth provider
            urlProvider = { "http://localhost:8080/callback" }
                                         // => Your registered redirect URI in GitHub app
                                         // => Must match exactly what's in GitHub OAuth app settings
            providerLookup = {
                OAuthServerSettings.OAuth2ServerSettings(
                    name = "github",
                    authorizeUrl = "https://github.com/login/oauth/authorize",
                                         // => GitHub OAuth authorization URL
                    accessTokenUrl = "https://github.com/login/oauth/access_token",
                                         // => Exchange code for access token
                    requestMethod = HttpMethod.Post,
                    clientId = System.getenv("GITHUB_CLIENT_ID") ?: "your-client-id",
                    clientSecret = System.getenv("GITHUB_CLIENT_SECRET") ?: "your-secret",
                    defaultScopes = listOf("read:user", "user:email")
                                         // => Permissions to request from GitHub
                )
            }
            client = httpClient          // => HttpClient for token exchange
        }
    }
}

fun Application.configureRouting() {
    routing {
        // Clicking "Login with GitHub" redirects here first
        authenticate("auth-oauth-github") {
            get("/login/github") {
                // => Ktor intercepts this and redirects to GitHub OAuth
                // => No code needed here; plugin handles redirect
            }

            // GitHub redirects back here with ?code=... and ?state=...
            get("/callback") {
                val principal = call.principal<OAuthAccessTokenResponse.OAuth2>()
                // => principal.accessToken = GitHub access token
                // => Use this token to call GitHub API for user info
                val accessToken = principal?.accessToken
                // => In production: call https://api.github.com/user with token
                // => Get user's GitHub ID, name, email
                // => Find or create user in your database
                // => Create your app's session or JWT
                call.respondText("GitHub OAuth success! Token: ${accessToken?.take(8)}...")
            }
        }

        get("/login") {
            call.respondText(
                """<a href="/login/github">Login with GitHub</a>""",
                io.ktor.http.ContentType.Text.Html
            )
        }
    }
}
// => GET /login => page with "Login with GitHub" link
// => GET /login/github => redirected to github.com/login/oauth/authorize
// => GitHub redirects to GET /callback?code=abc&state=xyz
//    => Token exchanged; response: "GitHub OAuth success! Token: ghp_abc1..."

// build.gradle.kts:
// implementation("org.jetbrains.exposed:exposed-core:0.57.0")
// implementation("org.jetbrains.exposed:exposed-dao:0.57.0")
// implementation("org.jetbrains.exposed:exposed-jdbc:0.57.0")
// implementation("com.zaxxer:HikariCP:5.1.0")
// implementation("org.postgresql:postgresql:42.7.4")

import com.zaxxer.hikari.HikariConfig
import com.zaxxer.hikari.HikariDataSource
import io.ktor.server.application.*
import org.jetbrains.exposed.sql.*
import org.jetbrains.exposed.sql.transactions.transaction

// Table definition using Exposed DSL approach
// Object represents the "users" table schema
object Users : Table("users") {          // => Table name in database: "users"
    val id = integer("id").autoIncrement()  // => INTEGER AUTOINCREMENT column
    val name = varchar("name", 255)         // => VARCHAR(255) column
    val email = varchar("email", 255).uniqueIndex()  // => VARCHAR(255) UNIQUE
    val createdAt = long("created_at")      // => BIGINT for Unix timestamp
    override val primaryKey = PrimaryKey(id)  // => id is the primary key
}

// Configure HikariCP connection pool
fun createHikariDataSource(
    url: String,
    driver: String = "org.postgresql.Driver"
): HikariDataSource {
    val config = HikariConfig().apply {
        jdbcUrl = url                    // => "jdbc:postgresql://localhost:5432/mydb"
        driverClassName = driver
        maximumPoolSize = 10             // => Max 10 concurrent DB connections
        minimumIdle = 2                  // => Keep 2 idle connections warm
        idleTimeout = 600_000            // => Close idle connections after 10 minutes
        connectionTimeout = 30_000       // => Fail fast if no connection in 30s
        isAutoCommit = false             // => Let Exposed manage transactions
        transactionIsolation = "TRANSACTION_REPEATABLE_READ"
    }
    return HikariDataSource(config)
}

fun Application.configureDatabase() {
    val dataSource = createHikariDataSource(
        url = environment.config
            .property("database.url")    // => Read from application.conf
            .getString()
    )

    Database.connect(dataSource)         // => Connect Exposed to HikariCP pool
                                          // => All transaction { } blocks use this connection

    // Create tables if they don't exist (use Flyway for production migrations)
    transaction {
        SchemaUtils.create(Users)        // => CREATE TABLE IF NOT EXISTS users (...)
    }
}
// => Database connected with pool of 2-10 connections
// => "users" table created if not already present

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.request.*
import io.ktor.server.routing.*
import io.ktor.http.*
import kotlinx.serialization.Serializable
import org.jetbrains.exposed.sql.*
import org.jetbrains.exposed.sql.transactions.transaction

@Serializable
data class UserDto(val id: Int, val name: String, val email: String)

@Serializable
data class CreateUserDto(val name: String, val email: String)

fun Application.configureRouting() {
    routing {
        // CREATE: INSERT INTO users
        post("/users") {
            val dto = call.receive<CreateUserDto>()

            val userId = transaction {   // => Opens a database transaction
                Users.insert {           // => INSERT INTO users (name, email, created_at)
                    it[name] = dto.name
                    it[email] = dto.email
                    it[createdAt] = System.currentTimeMillis()
                } get Users.id           // => Returns the generated id value
            }
            // => transaction {} auto-commits on success, rollbacks on exception

            call.respond(
                HttpStatusCode.Created,
                UserDto(userId, dto.name, dto.email)
            )
        }

        // READ ALL: SELECT * FROM users
        get("/users") {
            val users = transaction {
                Users.selectAll()        // => SELECT * FROM users
                    .orderBy(Users.id)   // => ORDER BY id ASC
                    .map { row ->        // => Map each ResultRow to UserDto
                        UserDto(
                            id = row[Users.id],       // => row[column] extracts typed value
                            name = row[Users.name],
                            email = row[Users.email]
                        )
                    }
            }
            call.respond(users)          // => JSON array of users
        }

        // READ ONE: SELECT WHERE id = ?
        get("/users/{id}") {
            val userId = call.parameters["id"]?.toIntOrNull()
                ?: return@get call.respond(HttpStatusCode.BadRequest)

            val user = transaction {
                Users.select { Users.id eq userId }  // => WHERE id = userId
                    .singleOrNull()      // => Returns ResultRow? (null if not found)
                    ?.let { row ->       // => Map if found
                        UserDto(row[Users.id], row[Users.name], row[Users.email])
                    }
            }

            if (user == null) {
                call.respond(HttpStatusCode.NotFound, mapOf("error" to "User not found"))
            } else {
                call.respond(user)
            }
        }

        // UPDATE: UPDATE users SET ... WHERE id = ?
        put("/users/{id}") {
            val userId = call.parameters["id"]?.toIntOrNull()
                ?: return@put call.respond(HttpStatusCode.BadRequest)
            val dto = call.receive<CreateUserDto>()

            val updated = transaction {
                Users.update({ Users.id eq userId }) {  // => UPDATE ... WHERE id = userId
                    it[name] = dto.name
                    it[email] = dto.email
                }
                // => Returns count of updated rows (0 = not found, 1 = updated)
            }

            if (updated == 0) {
                call.respond(HttpStatusCode.NotFound)
            } else {
                call.respond(UserDto(userId, dto.name, dto.email))
            }
        }

        // DELETE: DELETE FROM users WHERE id = ?
        delete("/users/{id}") {
            val userId = call.parameters["id"]?.toIntOrNull()
                ?: return@delete call.respond(HttpStatusCode.BadRequest)

            transaction {
                Users.deleteWhere { Users.id eq userId }  // => DELETE WHERE id = userId
            }
            call.respond(HttpStatusCode.NoContent)        // => 204 regardless (idempotent)
        }
    }
}
// => POST /users {"name":"Alice","email":"alice@example.com"} => 201 {"id":1,...}
// => GET  /users                                              => 200 [{"id":1,...}]
// => GET  /users/1                                            => 200 {"id":1,...}
// => PUT  /users/1 {"name":"Alice Smith","email":"..."}       => 200 {"id":1,...}
// => DELETE /users/1                                          => 204

// build.gradle.kts: implementation("io.ktor:ktor-server-websockets:3.0.3")

import io.ktor.server.application.*
import io.ktor.server.websocket.*           // => WebSocket plugin and DSL
import io.ktor.websocket.*                  // => Frame, CloseReason types
import io.ktor.server.routing.*
import kotlinx.coroutines.channels.consumeEach  // => Iterate incoming frames
import java.time.Duration

fun Application.configureWebSockets() {
    install(WebSockets) {                   // => Install WebSocket support
        pingPeriod = Duration.ofSeconds(15) // => Send ping every 15s to keep connection alive
                                             // => Detects dead connections from broken networks
        timeout = Duration.ofSeconds(15)    // => Close if no pong received within 15s
        maxFrameSize = Long.MAX_VALUE        // => Maximum frame size (use reasonable limit in prod)
        masking = false                     // => Server-to-client masking (false = standard)
    }
}

fun Application.configureRouting() {
    routing {
        // Basic echo WebSocket
        webSocket("/ws/echo") {             // => WebSocket route; suspends for connection lifetime
            // 'this' is DefaultWebSocketServerSession
            send("Connected to echo server!")  // => Send text frame to client

            incoming.consumeEach { frame ->    // => Iterate frames until connection closes
                when (frame) {
                    is Frame.Text -> {         // => Text frame received
                        val text = frame.readText()  // => "hello" (string content)
                        send("Echo: $text")    // => Send echo back
                        // => send() is a suspend function; waits for buffer space
                    }
                    is Frame.Close -> {        // => Client sent close frame
                        val reason = frame.readReason()
                        close(CloseReason(CloseReason.Codes.NORMAL, "Client closed"))
                        return@consumeEach     // => Exit the consume loop
                    }
                    else -> {} // => Binary, Ping, Pong frames: ignore in this example
                }
            }
            // => After consumeEach exits, connection is closed
        }

        // Chat room: broadcast to all connected clients
        val connections = mutableSetOf<DefaultWebSocketServerSession>()

        webSocket("/ws/chat") {
            connections.add(this)           // => Track this connection
            try {
                incoming.consumeEach { frame ->
                    if (frame is Frame.Text) {
                        val message = frame.readText()
                        // Broadcast to all other connections
                        connections.forEach { conn ->
                            if (conn !== this) {  // => Don't echo back to sender
                                conn.send(message)  // => Broadcast to each connection
                            }
                        }
                    }
                }
            } finally {
                connections.remove(this)    // => Clean up on disconnect (always)
            }
        }
    }
}
// WebSocket client connects to ws://localhost:8080/ws/echo
// Client sends: "hello"
// Server responds: "Echo: hello"
// Client sends: "world"
// Server responds: "Echo: world"

import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.auth.jwt.*
import io.ktor.server.websocket.*
import io.ktor.websocket.*
import io.ktor.server.routing.*
import kotlinx.coroutines.channels.consumeEach
import java.util.concurrent.ConcurrentHashMap

// Per-connection state
data class ConnectedUser(
    val userId: String,
    val session: DefaultWebSocketServerSession
)

// Thread-safe map of all connected users
val activeConnections = ConcurrentHashMap<String, ConnectedUser>()
                                           // => Key: userId, Value: ConnectedUser

fun Application.configureRouting() {
    routing {
        authenticate("auth-jwt") {         // => Require JWT before WebSocket upgrade
            webSocket("/ws/notifications") {
                // Principal available after JWT validation
                val principal = call.principal<JWTPrincipal>()
                val userId = principal?.payload?.getClaim("userId")?.asString()
                    ?: return@webSocket close(
                        CloseReason(CloseReason.Codes.VIOLATED_POLICY, "No user ID")
                    )

                // Register this connection
                val connection = ConnectedUser(userId, this)
                activeConnections[userId] = connection  // => Store for server-push later
                                                         // => ConcurrentHashMap is thread-safe

                try {
                    send("Connected! User: $userId")   // => Confirm connection to client

                    incoming.consumeEach { frame ->
                        if (frame is Frame.Text) {
                            val msg = frame.readText()
                            // Echo back with userId prefix
                            send("[$userId] $msg")
                        }
                    }
                } finally {
                    activeConnections.remove(userId)    // => Always remove on disconnect
                                                         // => Prevents memory leaks
                }
            }
        }

        // Server-side push: send notification to specific user
        // Called from other parts of the application (e.g., after a database event)
        post("/notify/{userId}") {
            val targetUserId = call.parameters["userId"] ?: return@post
            val message = call.receiveText()
            val connection = activeConnections[targetUserId]

            if (connection != null) {
                connection.session.send(message)  // => Push to connected WebSocket client
                call.respondText("Sent to $targetUserId")
            } else {
                call.respondText("User not connected",
                    status = io.ktor.http.HttpStatusCode.NotFound)
            }
        }
    }
}
// => WebSocket /ws/notifications (with JWT) => registers connection for user-123
// => POST /notify/user-123 body="New order!" => pushes to user-123's WebSocket

// build.gradle.kts (test dependencies):
// testImplementation("io.ktor:ktor-server-test-host:3.0.3")
// testImplementation("io.ktor:ktor-client-content-negotiation:3.0.3")
// testImplementation("org.jetbrains.kotlin:kotlin-test:2.1.0")

import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*
import io.ktor.http.*
import io.ktor.server.testing.*            // => testApplication, ApplicationTestBuilder
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive

class UserApiTest {

    // testApplication creates an in-memory Ktor server using real modules
    @Test
    fun `GET users returns list`() = testApplication {
        application {                       // => Apply your real module functions
            configureContentNegotiation()   // => Same function used in production
            configureRouting()              // => Same routes as production
        }

        // client is a pre-configured HttpClient pointing to the test server
        val response = client.get("/users") {
            header(HttpHeaders.Accept, ContentType.Application.Json.toString())
        }

        assertEquals(HttpStatusCode.OK, response.status)
        // => response.status is HttpStatusCode.OK (200)

        val body = response.bodyAsText()    // => Read response body as String
        // Assert body contains expected content
        assert(body.contains("[")) { "Expected JSON array, got: $body" }
    }

    @Test
    fun `POST users creates user and returns 201`() = testApplication {
        application {
            configureContentNegotiation()
            configureRouting()
        }

        // Configure test client with JSON support
        val jsonClient = createClient {     // => Create client with plugins
            install(ContentNegotiation) {   // => Auto-serialize/deserialize JSON
                json()
            }
        }

        val response = jsonClient.post("/users") {
            contentType(ContentType.Application.Json)
            setBody(mapOf("name" to "Bob", "email" to "bob@example.com"))
            // => setBody() serializes the map to JSON using the ContentNegotiation plugin
        }

        assertEquals(HttpStatusCode.Created, response.status)  // => 201 Created
        val responseBody = response.bodyAsText()
        assert(responseBody.contains("Bob")) { "Expected 'Bob' in response: $responseBody" }
    }

    @Test
    fun `GET users with invalid ID returns 400`() = testApplication {
        application {
            configureStatusPages()
            configureRouting()
        }

        val response = client.get("/users/not-a-number")
        assertEquals(HttpStatusCode.BadRequest, response.status)  // => 400
    }
}
// => All tests run without starting a real HTTP server
// => No ports opened; tests are fast and isolated
// => Same module functions as production: tests exercise real configuration

import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import io.ktor.server.testing.*
import kotlin.test.Test
import kotlin.test.assertEquals
import java.util.Base64

class AuthTest {

    private fun ApplicationTestBuilder.setupApp() {
        application {
            configureAuthentication()    // => Install Basic auth
            configureRouting()           // => Install routes including protected ones
        }
    }

    @Test
    fun `protected endpoint rejects unauthenticated request`() = testApplication {
        setupApp()
        val response = client.get("/admin")  // => No Authorization header
        assertEquals(HttpStatusCode.Unauthorized, response.status)
        // => 401 Unauthorized expected
    }

    @Test
    fun `protected endpoint accepts valid credentials`() = testApplication {
        setupApp()

        // Build Basic auth header: "Basic base64(username:password)"
        val credentials = Base64.getEncoder()
            .encodeToString("admin:secret123".toByteArray())
        val response = client.get("/admin") {
            header(HttpHeaders.Authorization, "Basic $credentials")
        }

        assertEquals(HttpStatusCode.OK, response.status)
        assert(response.bodyAsText().contains("Hello, admin!"))
    }

    @Test
    fun `protected endpoint rejects wrong password`() = testApplication {
        setupApp()

        val credentials = Base64.getEncoder()
            .encodeToString("admin:wrongpassword".toByteArray())
        val response = client.get("/admin") {
            header(HttpHeaders.Authorization, "Basic $credentials")
        }

        assertEquals(HttpStatusCode.Unauthorized, response.status)
        // => 401: wrong password rejected
    }

    @Test
    fun `JWT endpoint accepts valid token`() = testApplication {
        application {
            configureJWT()
            configureRouting()
        }

        // First: get a token
        val loginResponse = client.post("/auth/login")
        assertEquals(HttpStatusCode.OK, loginResponse.status)
        val responseText = loginResponse.bodyAsText()
        // Extract token from JSON (simplified; use proper JSON parsing in real tests)
        val token = responseText.substringAfter("\"token\":\"").substringBefore("\"")

        // Then: use the token
        val profileResponse = client.get("/profile") {
            header(HttpHeaders.Authorization, "Bearer $token")
        }
        assertEquals(HttpStatusCode.OK, profileResponse.status)
    }
}
// => All tests pass without network I/O
// => Authentication logic tested end-to-end including header parsing and validation

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.http.*
import io.ktor.util.*

// Step 1: Define the plugin configuration class
class RequestIdConfig {
    var headerName: String = "X-Request-ID"  // => Default header name
    var generator: () -> String = {           // => Default ID generator
        java.util.UUID.randomUUID().toString()
    }
}

// Step 2: Define the plugin using createApplicationPlugin
val RequestIdPlugin = createApplicationPlugin(
    name = "RequestIdPlugin",               // => Plugin identifier (must be unique)
    createConfiguration = ::RequestIdConfig // => Configuration factory
) {
    // pluginConfig is the RequestIdConfig instance configured by the caller
    val headerName = pluginConfig.headerName
    val generator = pluginConfig.generator

    // Step 3: Install pipeline interception
    onCall { call ->                        // => Runs for EVERY request before routing
        // Read existing request ID from client, or generate a new one
        val requestId = call.request.headers[headerName]
            ?: generator()                  // => Generate if client didn't provide one
                                             // => Client-provided IDs enable end-to-end tracing

        // Store in call attributes for access in handlers
        call.attributes.put(RequestIdKey, requestId)
                                             // => AttributeKey provides typed storage on call

        // Add to response headers so clients see the same ID
        call.response.headers.append(headerName, requestId)
    }
}

// AttributeKey for type-safe access from handlers
val RequestIdKey = AttributeKey<String>("RequestId")

// Step 4: Use the plugin
fun Application.configurePlugins() {
    install(RequestIdPlugin) {              // => Install with default config
        headerName = "X-Request-ID"         // => Customize configuration
        generator = { "ktor-${System.nanoTime()}" }  // => Custom generator
    }
}

fun Application.configureRouting() {
    routing {
        get("/demo") {
            val requestId = call.attributes[RequestIdKey]  // => Read from attributes
                                                            // => "ktor-1234567890" or client-provided
            call.respondText("Request ID: $requestId")
        }
    }
}
// => GET /demo (no X-Request-ID header)
//    Response header: X-Request-ID: ktor-1234567890
//    Body: "Request ID: ktor-1234567890"
// => GET /demo (X-Request-ID: my-trace-id)
//    Response header: X-Request-ID: my-trace-id
//    Body: "Request ID: my-trace-id"

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.http.*
import io.ktor.util.*

// Route-scoped plugin configuration
class RateLimitConfig {
    var requestsPerMinute: Int = 60         // => Configurable rate limit
    var keyExtractor: (ApplicationCall) -> String = { call ->
        call.request.origin.remoteHost      // => Default: rate limit by IP
    }
}

// createRouteScopedPlugin creates plugin applied only to specific route groups
val RateLimitPlugin = createRouteScopedPlugin(
    name = "RateLimitPlugin",
    createConfiguration = ::RateLimitConfig
) {
    val limit = pluginConfig.requestsPerMinute
    val keyExtractor = pluginConfig.keyExtractor

    // In-memory store (use Redis in production for multi-instance support)
    val requestCounts = mutableMapOf<String, Pair<Long, Int>>()
                                            // => Key -> (windowStart, count)

    onCall { call ->                        // => Runs for requests in this route scope
        val key = keyExtractor(call)        // => Extract rate limit key (e.g., IP)
        val now = System.currentTimeMillis()
        val windowMs = 60_000L              // => 1 minute window

        val (windowStart, count) = requestCounts[key] ?: (now to 0)

        if (now - windowStart > windowMs) {
            // New window: reset counter
            requestCounts[key] = now to 1  // => Reset to 1 for this request
        } else if (count >= limit) {
            // Over limit: reject
            call.response.headers.append(
                "Retry-After", "60"         // => Tell client when to retry
            )
            call.respond(
                HttpStatusCode.TooManyRequests,  // => HTTP 429
                mapOf("error" to "Rate limit exceeded. Limit: $limit/min")
            )
            return@onCall                   // => Short-circuit: don't proceed to handler
        } else {
            requestCounts[key] = windowStart to (count + 1)
        }
    }
}

fun Application.configureRouting() {
    routing {
        // Apply rate limiting only to public API endpoints
        route("/api/public") {
            install(RateLimitPlugin) {      // => Route-scoped installation
                requestsPerMinute = 30      // => Stricter limit for public endpoints
            }
            get("/data") {
                call.respondText("Public data")
            }
        }

        // Internal endpoints: no rate limiting
        route("/api/internal") {
            get("/admin") {
                call.respondText("Admin only, no rate limit")
            }
        }
    }
}
// => GET /api/public/data (30th request in window) => 200 "Public data"
// => GET /api/public/data (31st request in window) => 429 {"error":"Rate limit exceeded..."}
// => GET /api/internal/admin => 200 "Admin only, no rate limit" (no limit applied)

// src/main/resources/application.conf
// ktor {
//   deployment {
//     port = 8080
//     port = ${?PORT}            # Override with PORT env var if set
//     environment = development
//     environment = ${?APP_ENV}  # Override with APP_ENV env var
//   }
//   application {
//     modules = [ com.example.ApplicationKt.module ]
//   }
// }
//
// database {
//   url = "jdbc:postgresql://localhost:5432/mydb"
//   url = ${?DATABASE_URL}       # Override in production
//   maxPoolSize = 10
// }
//
// jwt {
//   secret = "dev-secret-change-in-production"
//   secret = ${?JWT_SECRET}      # Always override in production
//   issuer = "http://localhost:8080"
//   audience = "myapp"
// }
//
// features {
//   newDashboard = false
//   newDashboard = ${?FEATURE_NEW_DASHBOARD}  # Toggle via env var
// }

import io.ktor.server.application.*
import io.ktor.server.config.*              // => ApplicationConfig

fun Application.readConfiguration() {
    // Read configuration properties with full type safety
    val port = environment.config
        .property("ktor.deployment.port")  // => Throws if missing (required)
        .getString().toInt()               // => "8080" converted to 8080
                                            // => => 8080 or value of PORT env var

    val dbUrl = environment.config
        .property("database.url")
        .getString()                       // => "jdbc:postgresql://..." or DATABASE_URL value

    val maxPoolSize = environment.config
        .propertyOrNull("database.maxPoolSize")  // => propertyOrNull = optional
        ?.getString()?.toIntOrNull() ?: 10        // => Default 10 if not configured

    val jwtSecret = environment.config
        .property("jwt.secret")
        .getString()                       // => "dev-secret..." or JWT_SECRET env value

    val newDashboardEnabled = environment.config
        .propertyOrNull("features.newDashboard")
        ?.getString()?.toBoolean() ?: false  // => false unless FEATURE_NEW_DASHBOARD=true

    // Log configuration at startup (never log secrets)
    log.info("Starting on port $port, env=${environment.config
        .propertyOrNull("ktor.deployment.environment")
        ?.getString() ?: "unknown"}")
    log.info("DB pool size: $maxPoolSize, Feature/newDashboard: $newDashboardEnabled")
}
// => application.conf with PORT=9090 env var:
//    port = 9090 (env var overrides default 8080)
// => With JWT_SECRET env var:
//    jwtSecret = value from env (production secret, not hardcoded)
// => With DATABASE_URL env var:
//    dbUrl = PostgreSQL URL from hosting provider

// build.gradle.kts: implementation("io.ktor:ktor-server-partial-content:3.0.3")
// (multipart is part of ktor-server-core)

import io.ktor.http.content.*             // => PartData, streamProvider
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.http.*
import io.ktor.utils.io.core.*            // => readBytes
import java.io.File

fun Application.configureRouting() {
    routing {
        // File upload endpoint
        post("/upload") {
            val contentType = call.request.contentType()
            if (!contentType.match(ContentType.MultiPart.FormData)) {
                call.respond(HttpStatusCode.BadRequest, "Expected multipart/form-data")
                return@post
            }

            val multipart = call.receiveMultipart()  // => Get multipart reader
            var fileName: String? = null
            var fileSize = 0L
            var description: String? = null

            // Process each part of the multipart body
            multipart.forEachPart { part ->          // => Iterates each part
                when (part) {
                    is PartData.FileItem -> {         // => File upload part
                        fileName = part.originalFileName ?: "upload"
                        val uploadDir = File("uploads").also { it.mkdirs() }
                        val file = File(uploadDir, fileName!!)

                        // Stream to disk without loading into memory
                        part.streamProvider().use { input ->  // => InputStream of file data
                            file.outputStream().buffered().use { output ->
                                val bytes = input.readBytes()
                                output.write(bytes)
                                fileSize = bytes.size.toLong()
                                // => In production: use chunked copying for large files
                                // => input.copyTo(output) for memory-efficient streaming
                            }
                        }
                    }
                    is PartData.FormItem -> {         // => Regular form field
                        if (part.name == "description") {
                            description = part.value  // => Form field value as String
                        }
                    }
                    else -> {}                        // => BinaryChannelItem, BinaryItem: skip
                }
                part.dispose()                        // => Always dispose after reading
                                                       // => Releases underlying resources
            }

            if (fileName == null) {
                call.respond(HttpStatusCode.BadRequest, "No file uploaded")
                return@post
            }

            call.respond(
                HttpStatusCode.Created,
                mapOf(
                    "fileName" to fileName,
                    "size" to fileSize,
                    "description" to description
                )
            )
        }
    }
}
// => POST /upload (multipart with file "photo.jpg" + description field)
//    => 201 {"fileName":"photo.jpg","size":102400,"description":"My photo"}
//    => File saved to uploads/photo.jpg

// build.gradle.kts:
// implementation("io.insert-koin:koin-ktor:3.5.6")
// implementation("io.insert-koin:koin-logger-slf4j:3.5.6")

import io.insert.koin.ktor.ext.*          // => inject(), get() extension functions
import io.insert.koin.ktor.plugin.*       // => Koin plugin
import io.insert.koin.core.module.dsl.*   // => singleOf, factoryOf DSL
import io.insert.koin.dsl.*               // => module {}
import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

// Domain classes (no Koin annotations required)
interface UserRepository {
    fun findById(id: Int): String?
}

class InMemoryUserRepository : UserRepository {
    private val users = mapOf(1 to "Alice", 2 to "Bob")

    override fun findById(id: Int): String? = users[id]
                                           // => Returns name or null
}

class UserService(
    private val repository: UserRepository  // => Injected by Koin
) {
    fun getUser(id: Int): String =
        repository.findById(id) ?: throw NoSuchElementException("User $id not found")
}

// Koin module: defines how to create each dependency
val appModule = module {
    // single: created once, reused for all injections (singleton)
    single<UserRepository> { InMemoryUserRepository() }
                                           // => Binds UserRepository interface to implementation
                                           // => Swap implementation here for testing

    // factory: new instance for each injection
    single { UserService(get()) }          // => get() resolves UserRepository from above
                                           // => Koin wires UserRepository -> UserService
}

fun Application.configureKoin() {
    install(Koin) {                        // => Install Koin plugin
        slf4jLogger()                      // => Koin logs via SLF4J
        modules(appModule)                 // => Register dependency module(s)
    }
}

fun Application.configureRouting() {
    routing {
        get("/users/{id}") {
            val userService: UserService = call.application.koin.get()
                                           // => Resolve UserService from Koin container
                                           // => Alternative: inject() at module level
            val id = call.parameters["id"]?.toIntOrNull()
                ?: return@get call.respondText("Invalid ID",
                    status = io.ktor.http.HttpStatusCode.BadRequest)

            try {
                val name = userService.getUser(id)
                call.respondText("User: $name")  // => "User: Alice"
            } catch (e: NoSuchElementException) {
                call.respondText("Not found",
                    status = io.ktor.http.HttpStatusCode.NotFound)
            }
        }
    }
}
// => GET /users/1 => "User: Alice"
// => GET /users/3 => 404 "Not found"

import io.insert.koin.core.*
import io.insert.koin.dsl.*
import io.ktor.server.testing.*
import kotlin.test.*

// Test double: in-memory implementation for tests
class FakeUserRepository : UserRepository {
    val users = mutableMapOf<Int, String>() // => Mutable for test setup

    override fun findById(id: Int): String? = users[id]
}

class UserServiceTest {

    @Test
    fun `getUser returns user when found`() = testApplication {
        // Override production module with test module
        val fakeRepo = FakeUserRepository().apply {
            users[1] = "TestUser"           // => Pre-populate test data
        }

        application {
            install(Koin) {
                modules(module {
                    // Override: bind interface to test implementation
                    single<UserRepository> { fakeRepo }  // => Test fake, not real DB
                    single { UserService(get()) }
                })
            }
            configureRouting()
        }

        val response = client.get("/users/1")
        assertEquals(io.ktor.http.HttpStatusCode.OK, response.status)
        assert(response.bodyAsText().contains("TestUser"))
    }

    @Test
    fun `getUser returns 404 when not found`() = testApplication {
        application {
            install(Koin) {
                modules(module {
                    single<UserRepository> { FakeUserRepository() }  // => Empty repo
                    single { UserService(get()) }
                })
            }
            configureRouting()
        }

        val response = client.get("/users/999")
        assertEquals(io.ktor.http.HttpStatusCode.NotFound, response.status)
    }
}
// => Tests run without database connection
// => FakeUserRepository provides controlled, predictable test data
// => Same route handlers tested as in production (no mock of routes themselves)

// build.gradle.kts: implementation("io.ktor:ktor-server-resources:3.0.3")

import io.ktor.resources.*                  // => Resource annotation
import io.ktor.server.application.*
import io.ktor.server.resources.*           // => handle, get, post extensions
import io.ktor.server.response.*
import io.ktor.server.routing.*
import kotlinx.serialization.Serializable

// Resource classes represent URL structure
@Serializable
@Resource("/users")                         // => Maps to /users
class Users {

    @Serializable
    @Resource("{id}")                       // => Maps to /users/{id}
    class ById(val parent: Users = Users(), val id: Int)
                                             // => id is type-safe Int (not String)
                                             // => parent references parent resource

    @Serializable
    @Resource("search")                     // => Maps to /users/search
    class Search(
        val parent: Users = Users(),
        val name: String? = null,           // => Query parameter: /users/search?name=Alice
        val page: Int = 1
    )
}

fun Application.configureRouting() {
    install(Resources)                      // => Install Resources plugin

    routing {
        get<Users> {                        // => GET /users (type-safe)
            call.respondText("All users")
        }

        get<Users.ById> { params ->         // => GET /users/{id}
                                             // => params.id is Int (already parsed)
            call.respondText("User ${params.id}")  // => "User 42"
        }

        get<Users.Search> { params ->       // => GET /users/search?name=Alice&page=2
            call.respondText(
                "Search: name=${params.name}, page=${params.page}"
            )
        }

        post<Users> {                       // => POST /users
            call.respond(io.ktor.http.HttpStatusCode.Created)
        }
    }
}

// Type-safe URL generation (no string concatenation)
fun generateUserUrl(userId: Int): String {
    return href(Users.ById(id = userId))   // => "/users/42" - compile-time safe
                                            // => Changing Users.ById structure causes compile error
    // => String "/api/users/$userId" would silently diverge from route definition
}
// => GET /users         => "All users"
// => GET /users/42      => "User 42" (42 is Int, not String)
// => GET /users/search?name=Alice&page=2 => "Search: name=Alice, page=2"
// => href(Users.ById(id=42)) => "/users/42"

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.http.*
import kotlinx.serialization.Serializable

@Serializable
data class UserV1(val id: Int, val name: String)

@Serializable
data class UserV2(val id: Int, val firstName: String, val lastName: String, val email: String)

fun Application.configureRouting() {
    routing {
        // Strategy 1: URL path versioning (most visible, easiest to test)
        route("/api/v1") {
            get("/users/{id}") {
                val id = call.parameters["id"]?.toIntOrNull() ?: return@get
                call.respond(UserV1(id, "Alice Smith"))
                // => {"id":1,"name":"Alice Smith"}
            }
        }
        route("/api/v2") {
            get("/users/{id}") {
                val id = call.parameters["id"]?.toIntOrNull() ?: return@get
                call.respond(UserV2(id, "Alice", "Smith", "alice@example.com"))
                // => {"id":1,"firstName":"Alice","lastName":"Smith","email":"alice@example.com"}
            }
        }

        // Strategy 2: Header versioning (cleaner URLs, harder to test in browser)
        get("/api/users/{id}") {
            val version = call.request.headers["Accept-Version"] ?: "v1"
                                          // => "v2" or "v1" from request header
            val id = call.parameters["id"]?.toIntOrNull() ?: return@get

            when (version) {
                "v2" -> call.respond(UserV2(id, "Alice", "Smith", "alice@example.com"))
                else -> call.respond(UserV1(id, "Alice Smith"))  // => Default to v1
            }
        }

        // Strategy 3: Query parameter versioning (easiest to add, clutters URLs)
        get("/api/users") {
            val version = call.request.queryParameters["version"] ?: "1"
            when (version) {
                "2" -> call.respondText("UserV2 list format")
                else -> call.respondText("UserV1 list format")
            }
        }
    }
}
// URL versioning:
// => GET /api/v1/users/1 => {"id":1,"name":"Alice Smith"}
// => GET /api/v2/users/1 => {"id":1,"firstName":"Alice","lastName":"Smith","email":"..."}
// Header versioning:
// => GET /api/users/1 Accept-Version: v2 => {"id":1,"firstName":"Alice",...}
// => GET /api/users/1 (no header)        => {"id":1,"name":"Alice Smith"}

import io.ktor.server.application.*
import io.ktor.server.plugins.statuspages.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.http.*
import kotlinx.serialization.Serializable

// RFC 7807 Problem Details format for structured error responses
@Serializable
data class ProblemDetail(
    val type: String,         // => URI identifying the error type
    val title: String,        // => Human-readable summary (stable, not instance-specific)
    val status: Int,          // => HTTP status code
    val detail: String,       // => Instance-specific human-readable explanation
    val instance: String? = null  // => URI of the specific occurrence (e.g., request ID)
)

// Domain-specific exceptions
class ResourceNotFoundException(val resourceType: String, val id: String)
    : RuntimeException("$resourceType with id=$id not found")

class BusinessRuleViolationException(val rule: String, override val message: String)
    : RuntimeException(message)

fun Application.configureErrorHandling() {
    install(StatusPages) {
        exception<ResourceNotFoundException> { call, cause ->
            call.respond(
                HttpStatusCode.NotFound,
                ProblemDetail(
                    type = "https://myapi.com/problems/not-found",
                    title = "Resource Not Found",
                    status = 404,
                    detail = "${cause.resourceType} '${cause.id}' does not exist",
                    instance = call.request.uri
                )
            )
        }

        exception<BusinessRuleViolationException> { call, cause ->
            call.respond(
                HttpStatusCode.UnprocessableEntity,
                ProblemDetail(
                    type = "https://myapi.com/problems/${cause.rule}",
                    title = "Business Rule Violation",
                    status = 422,
                    detail = cause.message ?: "Business rule violated"
                )
            )
        }

        exception<Throwable> { call, cause ->
            call.application.environment.log.error("Unhandled exception on ${call.request.uri}", cause)
            call.respond(
                HttpStatusCode.InternalServerError,
                ProblemDetail(
                    type = "https://myapi.com/problems/internal-error",
                    title = "Internal Server Error",
                    status = 500,
                    detail = "An unexpected error occurred. Please try again later."
                    // => Never include cause.message: may expose internal paths, SQL, secrets
                )
            )
        }
    }
}

fun Application.configureRouting() {
    routing {
        get("/orders/{id}") {
            val id = call.parameters["id"] ?: throw ResourceNotFoundException("Order", "null")
            if (id.length > 20) throw BusinessRuleViolationException(
                "order-id-too-long", "Order ID must not exceed 20 characters"
            )
            call.respondText("Order $id")
        }
    }
}
// => GET /orders/NONEXISTENT
//    => 404 {"type":"...not-found","title":"Resource Not Found","status":404,"detail":"Order 'NONEXISTENT' does not exist","instance":"/orders/NONEXISTENT"}
// => GET /orders/TOOLONGIDTHATEXCEEDSLIMIT
//    => 422 {"type":"...order-id-too-long","title":"Business Rule Violation",...}