kmp-networking
Ktor client for Kotlin Multiplatform. Shared networking layer with platform-specific engines (OkHttp for Android, Darwin for iOS).
How do I install this agent skill?
npx skills add https://github.com/ahmed3elshaer/everything-claude-code-mobile --skill kmp-networkingIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a standard, high-quality template for networking in Kotlin Multiplatform projects using the Ktor client. It follows best practices for secure communication (HTTPS), authentication (Bearer tokens), and platform-specific engine configuration. No malicious code, credential harvesting, or suspicious network behavior was detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
KMP Networking with Ktor
Configure Ktor client for cross-platform networking with platform-optimized engines.
Dependencies
// build.gradle.kts (shared module)
plugins {
kotlin("multiplatform")
kotlin("plugin.serialization")
}
kotlin {
sourceSets {
val commonMain by getting {
dependencies {
implementation("io.ktor:ktor-client-core:2.3.7")
implementation("io.ktor:ktor-client-content-negotiation:2.3.7")
implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.7")
implementation("io.ktor:ktor-client-logging:2.3.7")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
}
}
val androidMain by getting {
dependencies {
implementation("io.ktor:ktor-client-okhttp:2.3.7")
}
}
val iosMain by getting {
dependencies {
implementation("io.ktor:ktor-client-darwin:2.3.7")
}
}
}
}
HttpClient Factory
// commonMain/kotlin/network/HttpClientFactory.kt
object HttpClientFactory {
fun create(
platform: Platform,
isDebug: Boolean = false
): HttpClient {
return HttpClient(createEngine(platform)) {
install(ContentNegotiation) {
json(Json {
ignoreUnknownKeys = true
isLenient = true
encodeDefaults = false
})
}
if (isDebug) {
install(Logging) {
level = LogLevel.INFO
logger = object : Logger {
override fun log(message: String) {
println("Ktor: $message")
}
}
}
}
install(Auth) {
bearer {
loadTokens {
// Access Token from secure storage
BearerTokens(
accessTokenStorage.get() ?: "",
refreshTokenStorage.get() ?: ""
)
}
refreshTokens {
// Refresh token logic
val newTokens = authApi.refreshToken()
accessTokenStorage.save(newTokens.accessToken)
refreshTokenStorage.save(newTokens.refreshToken)
BearerTokens(newTokens.accessToken, newTokens.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 -> {
val statusCode = exception.response.status.value
when (statusCode) {
401 -> throw UnauthorizedException()
403 -> throw ForbiddenException()
404 -> throw NotFoundException()
in 500..599 -> throw ServerException()
}
}
is ServerResponseException -> throw ServerException()
}
}
}
install(ResponseObserver) {
onResponse { response ->
// Track response times, errors
}
}
}
}
private fun createEngine(platform: Platform): HttpClientEngine {
return when (platform) {
Platform.ANDROID -> createOkhttpEngine()
Platform.IOS -> createDarwinEngine()
}
}
}
Platform-Specific Engines
Android (OkHttp)
// androidMain/kotlin/network/OkHttpEngineFactory.kt
fun createOkhttpEngine(): OkHttpEngine {
val config = OkHttpConfig {
preconfigured = OkHttpClient.Builder()
.connectTimeout(30, TimeUnit.SECONDS)
.readTimeout(30, TimeUnit.SECONDS)
.writeTimeout(30, TimeUnit.SECONDS)
.addInterceptor { chain ->
val request = chain.request().newBuilder()
.header("User-Agent", "Android App/1.0")
.build()
chain.proceed(request)
}
.addInterceptor(HttpLoggingInterceptor().apply {
level = if (BuildConfig.DEBUG) {
HttpLoggingInterceptor.Level.BODY
} else {
HttpLoggingInterceptor.Level.NONE
}
})
.cache(
Cache(
File(context.cacheDir, "http_cache"),
10 * 1024 * 1024 // 10MB
)
)
.build()
}
return OkHttpEngine(config)
}
iOS (Darwin)
// iosMain/kotlin/network/DarwinEngineFactory.kt
fun createDarwinEngine(): DarwinEngine {
val config = DarwinClientConfig {
configureSession {
setAllowsCellularAccess(true)
setAllowsExpensiveNetworkAccess(true)
setAllowsConstrainedNetworkAccess(true)
// Configure timeout
setTimeoutIntervalForRequest(30.0)
setTimeoutIntervalForResource(60.0)
// Configure cache
URLCache(
sharedCacheDirectory,
10 * 1024 * 1024 // 10MB
).let {
URLCache.setSharedURLCache(it)
}
}
}
return DarwinEngine(config)
}
API Service Pattern
// commonMain/kotlin/network/api/UserApi.kt
class UserApi(
private val client: HttpClient
) {
suspend fun getUsers(page: Int = 1): PaginatedResponse<User> {
return client.get("/users") {
parameter("page", page)
parameter("limit", 20)
}.body()
}
suspend fun getUser(id: String): User {
return client.get("/users/$id").body()
}
suspend fun createUser(request: CreateUserRequest): User {
return client.post("/users") {
setBody(request)
contentType(ContentType.Application.Json)
}.body()
}
suspend fun updateUser(id: String, request: UpdateUserRequest): User {
return client.put("/users/$id") {
setBody(request)
contentType(ContentType.Application.Json)
}.body()
}
suspend fun deleteUser(id: String) {
return client.delete("/users/$id")
}
suspend fun uploadAvatar(userId: String, file: ByteArray): String {
return client.submitFormWithBinaryData(
url = "https://api.example.com/users/$userId/avatar",
formData = formData {
append("avatar", file, Headers.build {
append(HttpHeaders.ContentDisposition, "filename=avatar.jpg")
})
}
).body()
}
}
Network Exceptions
// commonMain/kotlin/network/NetworkExceptions.kt
sealed class NetworkException(message: String? = null) : Exception(message)
class UnauthorizedException : NetworkException("User not authenticated")
class ForbiddenException : NetworkException("Access forbidden")
class NotFoundException : NetworkException("Resource not found")
class ServerException : NetworkException("Server error occurred")
class NetworkUnavailableException : NetworkException("Network unavailable")
class TimeoutException : NetworkException("Request timeout")
// Wrap Ktor exceptions
fun Throwable.toNetworkException(): NetworkException {
return when (this) {
is NetworkException -> this
is ClientRequestException -> when (response.status.value) {
401 -> UnauthorizedException()
403 -> ForbiddenException()
404 -> NotFoundException()
else -> NetworkException(message)
}
is ServerResponseException -> ServerException()
is HttpRequestTimeoutException -> TimeoutException()
is UnreachableAddressException,
is ConnectTimeoutException -> NetworkUnavailableException()
else -> NetworkException(message ?: "Unknown network error")
}
}
Result Wrapper
// commonMain/kotlin/network/ApiResult.kt
sealed class ApiResult<out T> {
data class Success<T>(val data: T) : ApiResult<T>()
data class Error(val error: NetworkException) : ApiResult<Nothing>()
suspend fun <R> map(transform: (T) -> R): ApiResult<R> = when (this) {
is Success -> Success(transform(data))
is Error -> this
}
suspend fun <R> flatMap(transform: (T) -> ApiResult<R>): ApiResult<R> = when (this) {
is Success -> transform(data)
is Error -> this
}
fun getOrNull(): T? = when (this) {
is Success -> data
is Error -> null
}
fun getOrElse(defaultValue: T): T = when (this) {
is Success -> data
is Error -> defaultValue
}
}
suspend fun <T> apiCall(block: suspend () -> T): ApiResult<T> = try {
ApiResult.Success(block())
} catch (e: Exception) {
ApiResult.Error(e.toNetworkException())
}
// Usage
val result: ApiResult<User> = apiCall { userApi.getUser("123") }
when (result) {
is ApiResult.Success -> showUser(result.data)
is ApiResult.Error -> showError(result.error)
}
Retry Logic
// commonMain/kotlin/network/Retry.kt
suspend fun <T> retryApiCall(
maxRetries: Int = 3,
delayMs: Long = 1000,
block: suspend () -> T
): T {
var lastException: Exception? = null
repeat(maxRetries) { attempt ->
try {
return block()
} catch (e: Exception) {
lastException = e
if (e is NetworkUnavailableException || e is TimeoutException) {
if (attempt < maxRetries - 1) {
delay(delayMs * (attempt + 1))
}
} else {
throw e
}
}
}
throw lastException ?: RuntimeException("Max retries exceeded")
}
Offline Support
// commonMain/kotlin/network/OfflineCapableApi.kt
class OfflineCapableApi<T : Any>(
private val api: T,
private val cache: DatabaseCache
) : OfflineCapableApi<T> by api {
suspend fun <R> withCache(
key: String,
ttl: Duration,
block: suspend () -> R
): R = withContext(Dispatchers.IO) {
// Try cache first
cache.get<R>(key)?.let { cached ->
if (cached.timestamp + ttl.toMillisMilliseconds() > Clock.System.now()) {
return@withContext cached.data
}
}
// Fetch from network
try {
val result = block()
cache.put(key, CachedData(result, Clock.System.now()))
result
} catch (e: NetworkException) {
// Return stale cache if network fails
cache.get<R>(key)?.data ?: throw e
}
}
}
Dependency Injection Setup
// commonMain/kotlin/di/NetworkModule.kt
val networkModule = module {
single { HttpClientFactory.create(get(), get()) }
single { UserApi(get()) }
single { AuthApi(get()) }
factory { ConnectivityMonitor(get()) }
}
Best Practices
✅ DO
// ✅ Use typed API services
class UserApi(private val client: HttpClient)
// ✅ Wrap calls in result types
suspend fun getUser(): ApiResult<User>
// ✅ Configure timeouts
config { setTimeoutIntervalForRequest(30.0) }
// ✅ Add logging for debug builds
if (isDebug) { install(Logging) }
// ✅ Handle exceptions at boundaries
try { api.call() } catch (e: NetworkException) { /* handle */ }
❌ DON'T
// ❌ Don't create multiple HttpClient instances
// Use singleton via DI
// ❌ Don't block on suspend calls
runBlocking { api.call() } // ❌
// ❌ Don't ignore exceptions
try { api.call() } catch (e: Exception) { } // ❌
// ❌ Don't hardcode URLs
client.get("https://api.example.com/users") // ❌
// Configure base URL in defaultRequest
Remember: Networking is the bridge between your app and the world. Make it robust, testable, and platform-optimized.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/ahmed3elshaer/everything-claude-code-mobile/kmp-networking">View kmp-networking on skillZs</a>