Networking with Retrofit, OkHttp and Ktor

<!-- app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />

<?xml version="1.0" encoding="utf-8"?>
<!-- app/src/debug/res/xml/network_security_config.xml -->
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="false">10.0.2.2</domain>
    </domain-config>
    <base-config cleartextTrafficPermitted="false" />
</network-security-config>

// core/network/src/main/kotlin/com/example/trailmate/core/network/TrailApi.kt
package com.example.trailmate.core.network

import retrofit2.Response
import retrofit2.http.Body
import retrofit2.http.GET
import retrofit2.http.Path
import retrofit2.http.PUT
import retrofit2.http.Query
import kotlinx.serialization.Serializable

interface TrailApi {
    @GET("trails")
    suspend fun getTrails(
        @Query("page") page: Int,
        @Query("region") region: String? = null,
    ): List<TrailDto>

    @GET("trails/{id}")
    suspend fun getTrail(@Path("id") id: String): Response<TrailDto>

    @PUT("trails/{id}/favorite")
    suspend fun setFavorite(
        @Path("id") id: String,
        @Body body: SetFavoriteRequest,
    ): Response<Unit>
}

// Sent through the kotlinx.serialization converter, so it needs a generated serializer too.
@Serializable
data class SetFavoriteRequest(val isFavorite: Boolean)

// core/network/src/main/kotlin/com/example/trailmate/core/network/NetworkResult.kt
package com.example.trailmate.core.network

import retrofit2.HttpException
import retrofit2.Response
import java.io.IOException

sealed interface NetworkResult<out T> {
    data class Success<T>(val value: T) : NetworkResult<T>
    data class ApiError(val code: Int, val message: String?) : NetworkResult<Nothing>
    data class NetworkError(val cause: IOException) : NetworkResult<Nothing>
}

suspend fun <T> safeApiCall(block: suspend () -> T): NetworkResult<T> =
    try {
        NetworkResult.Success(block())
    } catch (httpException: HttpException) {
        NetworkResult.ApiError(httpException.code(), httpException.message())
    } catch (ioException: IOException) {
        NetworkResult.NetworkError(ioException)
    }

suspend fun <T> Response<T>.toNetworkResult(): NetworkResult<T> =
    if (isSuccessful) {
        body()?.let { NetworkResult.Success(it) }
            ?: NetworkResult.ApiError(code(), "Empty body")
    } else {
        NetworkResult.ApiError(code(), errorBody()?.string())
    }

// core/network/src/main/kotlin/com/example/trailmate/core/network/di/RetrofitModule.kt
import kotlinx.serialization.json.Json
import okhttp3.MediaType.Companion.toMediaType
import retrofit2.Retrofit
import retrofit2.converter.kotlinx.serialization.asConverterFactory

fun buildTrailApi(
    okHttpClient: okhttp3.OkHttpClient,
    baseUrl: String = "https://api.example.com/v1/", // overridden by tests with a MockWebServer URL
): TrailApi {
    val json = Json { ignoreUnknownKeys = true }
    val retrofit = Retrofit.Builder()
        .baseUrl(baseUrl)
        .client(okHttpClient)
        .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
        .build()
    return retrofit.create(TrailApi::class.java)
}

// core/network/src/main/kotlin/com/example/trailmate/core/network/TrailApiClient.kt
package com.example.trailmate.core.network

import io.ktor.client.HttpClient
import io.ktor.client.call.body
import io.ktor.client.engine.HttpClientEngine
import io.ktor.client.engine.okhttp.OkHttp
import io.ktor.client.plugins.HttpTimeout
import io.ktor.client.plugins.auth.Auth
import io.ktor.client.plugins.auth.providers.BearerTokens
import io.ktor.client.plugins.auth.providers.bearer
import io.ktor.client.plugins.contentnegotiation.ContentNegotiation
import io.ktor.client.plugins.defaultRequest
import io.ktor.client.plugins.logging.LogLevel
import io.ktor.client.plugins.logging.Logging
import io.ktor.client.request.get
import io.ktor.client.request.parameter
import io.ktor.http.URLProtocol
import io.ktor.serialization.kotlinx.json.json
import kotlinx.serialization.json.Json
import okhttp3.OkHttpClient

class TrailApiClient(
    private val tokenStore: TokenStore,
    // The app's shared OkHttpClient, so Ktor reuses its connection pool, interceptors and Authenticator.
    sharedOkHttpClient: OkHttpClient? = null,
    // Any HttpClientEngine: OkHttp in production, a MockEngine in tests.
    engine: HttpClientEngine = OkHttp.create { preconfigured = sharedOkHttpClient },
) {
    private val httpClient = HttpClient(engine) {
        install(ContentNegotiation) {
            json(Json { ignoreUnknownKeys = true })
        }
        install(Logging) {
            level = LogLevel.INFO
        }
        install(HttpTimeout) {
            requestTimeoutMillis = 15_000
            connectTimeoutMillis = 10_000
        }
        install(Auth) {
            bearer {
                loadTokens {
                    BearerTokens(
                        accessToken = tokenStore.currentAccessToken(),
                        refreshToken = "",
                    )
                }
                refreshTokens {
                    val refreshed = tokenStore.refreshAccessTokenBlocking()
                    refreshed?.let { BearerTokens(accessToken = it, refreshToken = "") }
                }
            }
        }
        defaultRequest {
            url {
                protocol = URLProtocol.HTTPS
                host = "api.example.com"
                encodedPath = "/v1/" + encodedPath.removePrefix("/")
            }
        }
    }

    suspend fun getTrails(page: Int, region: String? = null): List<TrailDto> =
        httpClient.get("trails") {
            parameter("page", page)
            region?.let { parameter("region", it) }
        }.body()
}

// core/network/src/main/kotlin/com/example/trailmate/core/network/ConnectivityObserver.kt
package com.example.trailmate.core.network

import android.content.Context
import android.net.ConnectivityManager
import android.net.Network
import android.net.NetworkCapabilities
import android.net.NetworkRequest
import kotlinx.coroutines.channels.awaitClose
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.callbackFlow
import kotlinx.coroutines.flow.distinctUntilChanged

class ConnectivityObserver(context: Context) {
    private val connectivityManager =
        context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager

    val isOnline: Flow<Boolean> = callbackFlow {
        val callback = object : ConnectivityManager.NetworkCallback() {
            override fun onAvailable(network: Network) {
                trySend(true)
            }

            override fun onLost(network: Network) {
                trySend(false)
            }

            override fun onCapabilitiesChanged(
                network: Network,
                networkCapabilities: NetworkCapabilities,
            ) {
                val validated = networkCapabilities.hasCapability(
                    NetworkCapabilities.NET_CAPABILITY_VALIDATED,
                )
                trySend(validated)
            }
        }

        val request = NetworkRequest.Builder()
            .addCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
            .build()
        connectivityManager.registerNetworkCallback(request, callback)

        awaitClose { connectivityManager.unregisterNetworkCallback(callback) }
    }.distinctUntilChanged()
}

// core/network/src/test/kotlin/com/example/trailmate/core/network/TrailApiTest.kt
package com.example.trailmate.core.network

import kotlinx.coroutines.test.runTest
import mockwebserver3.MockResponse
import mockwebserver3.MockWebServer
import org.junit.After
import org.junit.Before
import org.junit.Test
import kotlin.test.assertEquals

class TrailApiTest {
    private lateinit var server: MockWebServer
    private lateinit var trailApi: TrailApi

    @Before
    fun setUp() {
        server = MockWebServer()
        server.start()
        trailApi = buildTrailApi(okHttpClient = okhttp3.OkHttpClient(), baseUrl = server.url("/v1/").toString())
    }

    @After
    fun tearDown() {
        server.shutdown()
    }

    @Test
    fun `getTrails parses a successful response`() = runTest {
        server.enqueue(
            MockResponse.Builder()
                .code(200)
                .body("""[{"id":"t1","name":"Eagle Ridge"}]""")
                .addHeader("Content-Type", "application/json")
                .build(),
        )

        val trails = trailApi.getTrails(page = 0)

        assertEquals(1, trails.size)
        assertEquals("Eagle Ridge", trails.first().name)
        val recordedRequest = server.takeRequest()
        assertEquals("/v1/trails?page=0", recordedRequest.target)
    }
}

// core/network/src/test/kotlin/com/example/trailmate/core/network/TrailApiClientTest.kt
package com.example.trailmate.core.network

import io.ktor.client.engine.mock.MockEngine
import io.ktor.client.engine.mock.respond
import io.ktor.http.HttpHeaders
import io.ktor.http.headersOf
import kotlinx.coroutines.test.runTest
import org.junit.Test
import kotlin.test.assertEquals

class TrailApiClientTest {
    @Test
    fun `getTrails parses a successful response`() = runTest {
        val mockEngine = MockEngine { request ->
            respond(
                content = """[{"id":"t1","name":"Eagle Ridge"}]""",
                headers = headersOf(HttpHeaders.ContentType, "application/json"),
            )
        }
        val client = TrailApiClient(tokenStore = FakeTokenStore(), engine = mockEngine)

        val trails = client.getTrails(page = 0)

        assertEquals(1, trails.size)
    }
}

// core/network/src/main/kotlin/com/example/trailmate/core/network/LiveHikeSocket.kt
package com.example.trailmate.core.network

import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.Response
import okhttp3.WebSocket
import okhttp3.WebSocketListener

class LiveHikeSocket(private val okHttpClient: OkHttpClient) {
    fun connect(hikeId: String): WebSocket {
        val request = Request.Builder()
            .url("wss://api.example.com/v1/hikes/$hikeId/live")
            .build()
        return okHttpClient.newWebSocket(request, object : WebSocketListener() {
            override fun onMessage(webSocket: WebSocket, text: String) {
                // Parse a position update and forward it to a Flow/StateFlow.
            }

            override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
                // Schedule a reconnect with backoff.
            }
        })
    }
}

// core/network/src/main/kotlin/com/example/trailmate/core/network/LiveHikeKtorSocket.kt
import io.ktor.client.plugins.websocket.WebSockets
import io.ktor.client.plugins.websocket.webSocket
import io.ktor.websocket.Frame
import io.ktor.websocket.readText

// install(WebSockets) on the HttpClient, then:
suspend fun collectLiveHike(httpClient: io.ktor.client.HttpClient, hikeId: String) {
    httpClient.webSocket(urlString = "wss://api.example.com/v1/hikes/$hikeId/live") {
        for (frame in incoming) {
            if (frame is Frame.Text) {
                val text = frame.readText()
                // Parse a position update and forward it to a Flow/StateFlow.
            }
        }
    }
}