Architecture, Battles & Error Handling

// HTTP delegates the work instead of calculating damage.
post("/battles") {
    val request = call.receive<StartBattleRequest>()
    call.respond(battleService.start(request.attackerId, request.defenderId))
}

POST /battles → battleService.start(...)

// Route -> service -> repository -> domain
class MonsterService(private val repository: MonsterRepository) {
    fun get(id: Int): Monster? = repository.findById(id)
}

GET /monsters/1 → service → repository → Pyron

nl/monsterbattles/api/
├── Application.kt
├── common/ApiError.kt
├── config/Plugins.kt
└── features/
    ├── monsters/
    │   ├── model/Monster.kt, Stats.kt, Element.kt
    │   ├── repository/MonsterRepository.kt
    │   ├── MonsterService.kt
    │   └── MonsterRoutes.kt
    └── battles/
        ├── model/BattleResult.kt, BattleEvent.kt
        ├── dto/BattleDtos.kt
        ├── DamageCalculator.kt
        ├── BattleService.kt
        └── BattleRoutes.kt

De battle-feature gebruikt het bestaande monsterdomein, zonder eigen kopie.

// In Week 06 the existing BattleService is extended with repository injection.
class BattleService(private val repository: MonsterRepository) {
    fun start(attackerId: Int, defenderId: Int): BattleResult {
        require(attackerId > 0 && defenderId > 0 && attackerId != defenderId)
        val attacker = repository.findById(attackerId) ?: throw MonsterNotFoundException(attackerId)
        val defender = repository.findById(defenderId) ?: throw MonsterNotFoundException(defenderId)
        return fight(attacker, defender) // Week 03 simulation algorithm, preserved.
    }
    // The existing fight(attacker, defender) implementation remains in BattleService.
}

BattleService ontvangt repository via constructor.

// Dependency Inversion: unchanged interface introduced in Week 04.
interface MonsterRepository {
    fun findAll(): List<Monster>
    fun findById(id: Int): Monster?
    fun create(name: String, element: Element, stats: Stats): Monster
    fun update(id: Int, name: String, element: Element, stats: Stats): Monster?
    fun delete(id: Int): Boolean
}
// In Week 07, ExposedMonsterRepository replaces InMemoryMonsterRepository.

Service kent MonsterRepository, niet de concrete opslag.

val result = BattleService(repository).fight(pyron, aquara)
println("Winner: ${result.winnerId}")
println("Rounds: ${result.rounds} | Turns: ${result.turns}")
// pyron and aquara are the immutable base monsters from Week 02.

Winner: 1
Rounds: 7 | Turns: 13

@Serializable
data class StartBattleRequest(val attackerId: Int, val defenderId: Int)
// Request only contains IDs: HP and damage are server-owned rules.

{"attackerId":1,"defenderId":2}

@Serializable
data class BattleEventResponse(
    val turn: Int,
    val attackerId: Int,
    val defenderId: Int,
    val damage: Int,
    val defenderRemainingHp: Int
)

@Serializable
data class BattleResponse(
    val winnerId: Int,
    val rounds: Int,
    val turns: Int,
    val attackerRemainingHp: Int,
    val defenderRemainingHp: Int,
    val log: List<BattleEventResponse>
)

BattleResponse: winnerId=1, rounds=7, turns=13, log.size=13 (verwacht)

// Fragment inside fun Route.battleRoutes(useCase: BattleService)
post("/battles") {
    val request = call.receive<StartBattleRequest>()
    val result = useCase.start(request.attackerId, request.defenderId)
    call.respond(HttpStatusCode.OK, result.toResponse())
}

200 OK + BattleResponse (rounds=7, turns=13, 13 events)

fun validateIds(attackerId: Int, defenderId: Int) {
    require(attackerId > 0 && defenderId > 0) { "IDs must be positive" }
    require(attackerId != defenderId) { "Choose two different monsters" }
}
validateIds(1, 2)

Geldige IDs leveren geen fout op; ongeldige IDs geven 400.

class MonsterNotFoundException(id: Int) :
    RuntimeException("Monster $id was not found")

fun requireMonster(monster: Monster?, id: Int): Monster =
    monster ?: throw MonsterNotFoundException(id)

Missing monster → MonsterNotFoundException

require(attack >= 0) { "Attack cannot be negative" }
check(currentHp >= 0) { "HP cannot be negative" }
if (turns > 1000) error("Battle exceeded turn limit")

Bij geldige waarden: geen exception.

install(StatusPages) {
    exception<MonsterNotFoundException> { call, cause ->
        call.respond(HttpStatusCode.NotFound, ErrorResponse(cause.message ?: "Not found"))
    }
    exception<IllegalArgumentException> { call, cause ->
        call.respond(HttpStatusCode.BadRequest, ErrorResponse(cause.message ?: "Bad request"))
    }
}

404 {"message":"Monster 99 was not found"}

application.log.info("Starting battle for monster IDs {} and {}", attackerId, defenderId)
application.log.warn("Unknown monster ID: {}", missingId)

INFO Starting battle for monster IDs 1 and 2

ktor:
  application:
    modules:
      - nl.monsterbattles.api.ApplicationKt.module
  deployment:
    port: 8080

Server luistert op poort 8080.

// Test with the same repository interface; provide a fake implementation.
val repository: MonsterRepository = FakeMonsterRepository()
val service = BattleService(repository)
val result = service.start(1, 2)
check(result.winnerId == 1 && result.rounds == 7 && result.turns == 13)

BattleService gebruikt testdata zonder database.

Client -> BattleRoutes : POST /battles
BattleRoutes -> BattleService : start(1, 2)
BattleService -> MonsterRepository : findById(1), findById(2)
MonsterRepository --> BattleService : Pyron, Aquara
BattleService -> DamageCalculator : calculate(...)
DamageCalculator --> BattleService : damage
BattleService --> BattleRoutes : BattleResult
BattleRoutes --> Client : 200 OK + BattleResponse
alt invalid input: StatusPages => 400
alt unknown monster: StatusPages => 404

Client ontvangt winnaar en battlelog.

suspend fun loadMonster(id: Int): Monster? = repository.findById(id)
get("/monsters/{id}") {
    val id = call.parameters["id"]?.toIntOrNull() ?: return@get call.respond(HttpStatusCode.BadRequest)
    call.respond(service.loadMonster(id) ?: return@get call.respond(HttpStatusCode.NotFound))
}

GET /monsters/1 → 200 OK + Monster JSON

// Blocking calls need an appropriate dispatcher if used from suspend code.
suspend fun readLegacyData(): String = withContext(Dispatchers.IO) {
    blockingFileRead()
}

Coroutine kan wachten zonder de Ktor-eventloop te blokkeren.

install(Authentication) {
    bearer("auth-bearer") {
        authenticate { credential ->
            if (isValidDemoToken(credential.token)) UserIdPrincipal("demo") else null
        }
    }
}

Zonder geldig token → 401 Unauthorized

val user = call.principal<UserIdPrincipal>()
if (user?.name != "admin") {
    return@get call.respond(HttpStatusCode.Forbidden)
}
// Continue with admin-only operation.

Geauthenticeerde gebruiker zonder rechten → 403 Forbidden

install(Authentication) {
    jwt("auth-jwt") {
        realm = "monsterbattles"
        verifier(jwtVerifier) // Validates signature and expected claims.
        validate { credential ->
            credential.payload.subject?.let { JWTPrincipal(credential.payload) }
        }
    }
}

Geldig JWT → request gaat door; ongeldig JWT → 401

GET /admin/monsters HTTP/1.1
Host: localhost:8080
Authorization: Bearer eyJhbGciOi...

200 OK bij geldig token, anders 401 Unauthorized

routing {
    get("/monsters") { call.respond(monsterService.list()) }
    authenticate("auth-jwt") {
        delete("/admin/monsters/{id}") { /* Authorization + delete */ }
    }
}

GET /monsters publiek; DELETE /admin/... token vereist.

enum class Permission { READ_MONSTER, DELETE_MONSTER }
fun permissions(role: String): Set<Permission> = when (role) {
    "ADMIN" -> Permission.entries.toSet()
    else -> setOf(Permission.READ_MONSTER)
}
println(Permission.DELETE_MONSTER in permissions("VIEWER"))

false

post("/admin/uploads") {
    val multipart = call.receiveMultipart()
    multipart.forEachPart { part ->
        when (part) {
            is PartData.FileItem -> {
                // Validate size/type; stream to a safe server-generated path.
            }
            else -> Unit
        }
        part.dispose()
    }
    call.respond(HttpStatusCode.Created)
}

POST multipart upload → 201 Created

// Conceptual validation, after a bounded read/stream.
require(uploadedBytes.size <= MAX_IMAGE_BYTES)
require(detectImageFormat(uploadedBytes) in setOf("png", "jpeg"))
val safeName = "${java.util.UUID.randomUUID()}.png"
// Re-encode verified image; persist in configured uploads directory.

Ongeldige afbeelding → 400; geldige afbeelding → opgeslagen.

routing {
    staticResources("/assets", "public")
    // Resources from src/main/resources/public are served under /assets.
}

GET /assets/pyron.png → 200 OK (als resource bestaat).

@Test
fun `unknown monster returns 404`() = testApplication {
    application { module() }
    val response = client.post("/battles") {
        contentType(ContentType.Application.Json)
        setBody("""{"attackerId":1,"defenderId":999}""")
    }
    assertEquals(HttpStatusCode.NotFound, response.status)
}

Test passed: 404 Not Found

Client -> BattleRoutes -> BattleService.start(ids)
BattleService -> MonsterRepository.findById(ids)
BattleService -> BattleService.fight(monsters) [Week 03 algorithm]
BattleService -> DamageCalculator.calculate(...)
BattleService -> BattleResult -> BattleResponse -> Client

200: complete battle; 400: invalid request; 404: missing monster.