kmp-networking

KMP Networking with Ktor

Configure Ktor client for cross-platform networking with platform-optimized engines.

TLS/certificate pinning (MITM hardening) is a separate concern applied per engine — see kmp-tls-pinning (OkHttp CertificatePinner on Android + Darwin handleChallenge on iOS via expect/actual).

Dependencies

// build.gradle.kts (shared module)
plugins {
    kotlin("multiplatform")
    kotlin("plugin.serialization")
}

val ktor = "3.5.2"   // current 3.x — verify latest at ktor.io/docs/releases

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("io.ktor:ktor-client-core:$ktor")
                implementation("io.ktor:ktor-client-content-negotiation:$ktor")
                implementation("io.ktor:ktor-serialization-kotlinx-json:$ktor")
                implementation("io.ktor:ktor-client-logging:$ktor")
                implementation("io.ktor:ktor-client-auth:$ktor")            // bearer-token Auth plugin
                implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.11.0")
            }
        }
        val androidMain by getting {
            dependencies {
                implementation("io.ktor:ktor-client-okhttp:$ktor")
            }
        }
        val iosMain by getting {
            dependencies {
                implementation("io.ktor:ktor-client-darwin:$ktor")
            }
        }
    }
}

HttpClient Factory

// commonMain/kotlin/network/HttpClientFactory.kt
object HttpClientFactory {
    fun create(
        platform: Platform,
        isDebug: Boolean = false
    ): HttpClient {
        return HttpClient(platformEngine()) {      // engine factory chosen per platform (expect/actual)
            install(HttpTimeout) {                 // cross-platform timeouts (no engine-specific config needed)
                requestTimeoutMillis = 30_000
                connectTimeoutMillis = 30_000
            }
            install(ContentNegotiation) {
                json(Json {
                    ignoreUnknownKeys = true
                    isLenient = true
                    encodeDefaults = false
                })
            }

            if (isDebug) {
                install(Logging) {
                    level = LogLevel.INFO
                    sanitizeHeader { it == HttpHeaders.Authorization }   // never log tokens
                    logger = object : Logger {
                        override fun log(message: String) {
                            println("Ktor: $message")
                        }
                    }
                }
            }

            install(Auth) {
                bearer {
                    loadTokens {
                        // From secure storage; return null when signed out
                        accessTokenStorage.get()?.let { access ->
                            BearerTokens(access, refreshTokenStorage.get())
                        }
                    }
                    // Runs once on 401; concurrent 401s wait for it, then retry with the new token
                    refreshTokens {  // this: RefreshTokensParams (client, oldTokens, response)
                        val refresh = oldTokens?.refreshToken ?: return@refreshTokens null
                        val new: TokenResponse = client.post("auth/refresh") {
                            markAsRefreshTokenRequest()   // excludes this call from auth retry — prevents refresh loops
                            contentType(ContentType.Application.Json)  // required: ContentNegotiation skips bodies with no Content-Type
                            setBody(RefreshRequest(refresh))
                        }.body()
                        accessTokenStorage.save(new.accessToken)
                        refreshTokenStorage.save(new.refreshToken)
                        BearerTokens(new.accessToken, new.refreshToken)
                    }
                }
            }

            defaultRequest {
                url {
                    protocol = URLProtocol.HTTPS
                    host = "api.example.com"
                }
                header("X-API-Version", "1.0")
                header("X-Platform", platform.name)
            }

            expectSuccess = true
            HttpResponseValidator {
                handleResponseExceptionWithRequest { exception, request ->
                    when (exception) {
                        is ClientRequestException -> {              // 4xx only
                            when (exception.response.status.value) {
                                401 -> throw UnauthorizedException()
                                403 -> throw ForbiddenException()
                                404 -> throw NotFoundException()
                            }
                        }
                        is ServerResponseException -> throw ServerException()   // 5xx
                    }
                }
            }

            install(ResponseObserver) {
                onResponse { response ->
                    // Track response times, errors
                }
            }
        }
    }

}

// commonMain — the engine factory is provided per platform via expect/actual:
expect fun platformEngine(): HttpClientEngineFactory<*>