| name | kotlin-ktor |
| description | Bruk ved arbeid på Ktor-backend i no.nav.syfo: nye routes/plugins, ContentNegotiation, auth (TokenX/Azure AD, JWT-claims som NAVident), Koin DI, CallId/CallLogging/MDC, StatusPages/ApiError-feilkontrakt, paginering, input-validering, Postgres/Flyway/Kafka-oppsett, avhengigheter via version catalog — eller når noen sier /kotlin-ktor. |
Ktor — NAV-spesifikt (syfo-budstikka)
Kotlin + Ktor 3.x på Netty, pakke no.nav.syfo. Java 25, Gradle. Norsk er arbeidsspråk.
Oppstart og moduler
Repoet bruker config-basert oppstart med EngineMain, ikke embeddedServer { }. Moduler registreres i src/main/resources/application.yaml under ktor.application.modules, ikke i main.kt:
ktor:
deployment:
port: 8080
application:
modules:
- no.nav.syfo.RoutingKt.configureRouting
- no.nav.syfo.AppKt.apiModule
main.kt kaller bare io.ktor.server.netty.EngineMain.main(args). En ny Application.xxx()-modul tas i bruk ved å legge fully-qualified <Fil>Kt.<funksjon>-referansen i listen over — å bare skrive funksjonen er ikke nok.
Avhengigheter (version catalogs)
To kataloger er i bruk:
ktorLibs — alle Ktor-artefakter, pinnet via io.ktor:ktor-version-catalog i settings.gradle.kts. Bruk f.eks. implementation(ktorLibs.server.auth), ktorLibs.server.contentNegotiation. Ikke skriv Ktor-versjoner manuelt.libs — alt annet (logback, Koin, db, Kafka, osv.), definert i gradle/libs.versions.toml.
Legg nye Ktor-plugins via ktorLibs.*; legg tredjepart via libs.* med versjon i [versions]/[libraries].
Autentisering (TokenX / Azure AD)
authenticate("azureAd") {
get("/api/protected") {
val principal = call.principal<JWTPrincipal>()
val navIdent = principal?.getClaim("NAVident", String::class)
?: throw ApiErrorException.UnauthorizedException("Mangler NAVident")
}
}
- TokenX for borger-til-app (on-behalf-of sluttbruker, ID-porten-opphav). Valider
sub/pid.
- Azure AD for ansatt-flyt og maskin-til-maskin internt. NAVident-claim identifiserer saksbehandler.
- Sett opp
accessPolicy.inbound/outbound i NAIS-manifestet for hvilke apper som får kalle/kalles. Auth-valg er typisk en blind-spot — grav i det i grill-fasen.
Avhengighetsinjeksjon
Detekter eksisterende DI-mønster først. Er io.insert-koin i avhengighetene: bruk Koin (install(Koin) { modules(appModule) }, hent via by inject()). Ellers er manuell konstruktørinjeksjon i Application-modulen default — ikke dra inn et DI-rammeverk uoppfordret. (Dette repoet har ingen Koin i dag.)
Logging og sporing
install(CallId) {
header(HttpHeaders.XRequestId)
generate { UUID.randomUUID().toString() }
verify { it.isNotBlank() }
}
install(CallLogging) {
callIdMdc("x_request_id")
}
NAIS forventer strukturert (JSON) logging til stdout for innsamling. Logg aldri fnr eller særlige kategorier personopplysninger i klartekst — bruk callId/aktørreferanser i stedet.
Feilhåndtering — StatusPages + ApiError
Team-standard for strukturerte feilresponser: sealed ApiErrorException-hierarki + StatusPages-plugin som mapper til en enhetlig ApiError-payload (status, type, message, path, timestamp). Se references/error-handling.md for full implementasjon (ErrorType-enum, ApiErrorException-klasser, installStatusPages(), determineApiError(), logging).
Paginering og input-validering
Team-standard PaginatedResponse<T>-wrapper og route-validering med tidlig-retur (kast ApiErrorException.BadRequestException) på ugyldige parametre. Se references/paginering-og-validering.md.
Utgående HttpClient (kall mot nedstrøms-tjeneste)
Når backenden selv kaller en nedstrøms-tjeneste: bruk Ktor HttpClient via ktorLibs.client.*, med eksplisitt timeout/retry, Nav-Call-Id-propagering og oversettelse av nedstrøms-feil til repoets feilkontrakt. Token for kallet hentes som beskrevet i /auth-overview (TokenX OBO / Azure AD M2M) — ikke dupliser auth her. Se references/http-client.md for konkret oppsett (motor, HttpTimeout, HttpRequestRetry, callId-header, ApiErrorException-mapping; circuit breaker krever Resilience4j — ikke native i Ktor).
Persistens (Postgres / Flyway)
- Flyway-migreringer i
src/main/resources/db/migration (V<n>__<navn>.sql), kjøres ved oppstart. Migreringer er append-only — endre aldri en allerede deployet migrering.
- Bruk NAIS-provisjonert Postgres med IAM/Vault-rotert credential; ikke hardkod connection-string.
- Skjema- og lagringsvalg for personopplysninger er en arkitekturbeslutning → utløs ADR i
docs/adr/ via grill-fasen.
Kafka (hendelseskonsument/-produsent)
- Konsumenter må være idempotente og tåle replay — dedup på nøkkel/offset, ikke anta exactly-once.
- Definer eksplisitt oppførsel når downstream er nede (retry/DLQ), og bekreft
accessPolicy/topic-tilgang i NAIS.
- Logg med callId/hendelse-id, aldri rå payload med PII.
Graceful shutdown
EngineMain (Netty) installerer shutdown-hook og håndterer SIGTERM automatisk — påbegynte kall fullføres før prosessen stopper. Du trenger ikke manuell readiness-toggling i applikasjonen. På plattformsiden gir NAIS preStop-hook og rimelig terminationGracePeriodSeconds tid til å drenere. Anti-mønstre: manuell readiness=false-vipping og for lav grace-period.
Verifisering
Kvalitetsgater er deterministiske: ./gradlew test og ./gradlew build. Ktor-routes testes med testApplication { } (ktorLibs.server.testHost) — se src/test/kotlin/ServerTest.kt. Ingen «ser riktig ut»-påstand uten ferskt kommando-output + exit-kode.
