@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/retrofit-networking/SKILL.md

@@ -0,0 +1,506 @@
+---
+name: retrofit-networking
+description: "Build networking layers on Android with Retrofit, OkHttp, and Kotlin Coroutines. Covers suspend functions in API interfaces, OkHttp interceptors (auth, logging, retry), sealed Result error handling, multipart uploads, WebSocket support, network-bound resource pattern (cache + API), and Hilt integration for Retrofit instances. Use when building API clients, handling network errors, implementing caching, or setting up networking infrastructure."
+---
+
+# Retrofit Networking
+
+Networking patterns for Android using Retrofit 2.11+, OkHttp 4.x, and
+kotlinx.serialization. Covers API definition, interceptors, error handling,
+caching, and Hilt integration.
+
+## Contents
+
+- [API Interface](#api-interface)
+- [Retrofit Setup with Hilt](#retrofit-setup-with-hilt)
+- [OkHttp Interceptors](#okhttp-interceptors)
+- [Error Handling](#error-handling)
+- [Network-Bound Resource](#network-bound-resource)
+- [Multipart Uploads](#multipart-uploads)
+- [WebSocket Support](#websocket-support)
+- [Do's and Don'ts](#dos-and-donts)
+- [Troubleshooting](#troubleshooting)
+- [Review Checklist](#review-checklist)
+
+## API Interface
+
+Define endpoints as suspend functions. Retrofit handles coroutine integration.
+
+```kotlin
+interface FlightApiService {
+
+    @GET("flights")
+    suspend fun searchFlights(
+        @Query("origin") origin: String,
+        @Query("destination") destination: String,
+        @Query("date") date: String,
+    ): List<FlightDto>
+
+    @GET("flights/{id}")
+    suspend fun getFlightDetail(
+        @Path("id") flightId: String,
+    ): FlightDetailDto
+
+    @POST("bookings")
+    suspend fun createBooking(
+        @Body request: BookingRequest,
+    ): BookingResponse
+
+    @PUT("bookings/{id}")
+    suspend fun updateBooking(
+        @Path("id") bookingId: String,
+        @Body request: UpdateBookingRequest,
+    ): BookingResponse
+
+    @DELETE("bookings/{id}")
+    suspend fun cancelBooking(
+        @Path("id") bookingId: String,
+    ): Response<Unit>
+
+    @GET("flights")
+    suspend fun searchFlightsWithHeaders(
+        @Query("origin") origin: String,
+        @Header("Accept-Language") language: String = "en",
+    ): List<FlightDto>
+}
+```
+
+### DTO Classes
+
+```kotlin
+@Serializable
+data class FlightDto(
+    val id: String,
+    val origin: AirportDto,
+    val destination: AirportDto,
+    @SerialName("departure_time")
+    val departureTime: String,
+    @SerialName("arrival_time")
+    val arrivalTime: String,
+    val price: PriceDto,
+    val status: String,
+)
+
+@Serializable
+data class AirportDto(
+    val code: String,
+    val name: String,
+)
+
+@Serializable
+data class PriceDto(
+    val amount: Double,
+    val currency: String,
+)
+```
+
+## Retrofit Setup with Hilt
+
+```kotlin
+@Module
+@InstallIn(SingletonComponent::class)
+object NetworkModule {
+
+    @Provides
+    @Singleton
+    fun provideJson(): Json = Json {
+        ignoreUnknownKeys = true
+        coerceInputValues = true
+        encodeDefaults = true
+    }
+
+    @Provides
+    @Singleton
+    fun provideOkHttpClient(
+        authInterceptor: AuthInterceptor,
+        loggingInterceptor: HttpLoggingInterceptor,
+    ): OkHttpClient = OkHttpClient.Builder()
+        .connectTimeout(30, TimeUnit.SECONDS)
+        .readTimeout(30, TimeUnit.SECONDS)
+        .writeTimeout(30, TimeUnit.SECONDS)
+        .addInterceptor(authInterceptor)
+        .addInterceptor(loggingInterceptor)
+        .build()
+
+    @Provides
+    @Singleton
+    fun provideLoggingInterceptor(): HttpLoggingInterceptor =
+        HttpLoggingInterceptor().apply {
+            level = if (BuildConfig.DEBUG) {
+                HttpLoggingInterceptor.Level.BODY
+            } else {
+                HttpLoggingInterceptor.Level.NONE
+            }
+        }
+
+    @Provides
+    @Singleton
+    fun provideRetrofit(
+        client: OkHttpClient,
+        json: Json,
+    ): Retrofit = Retrofit.Builder()
+        .baseUrl(BuildConfig.BASE_URL)
+        .client(client)
+        .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
+        .build()
+
+    @Provides
+    @Singleton
+    fun provideFlightApiService(retrofit: Retrofit): FlightApiService =
+        retrofit.create(FlightApiService::class.java)
+}
+```
+
+## OkHttp Interceptors
+
+### Auth Interceptor (Token Injection)
+
+```kotlin
+class AuthInterceptor @Inject constructor(
+    private val tokenProvider: TokenProvider,
+) : Interceptor {
+
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val token = tokenProvider.getAccessToken()
+        val request = chain.request().newBuilder().apply {
+            token?.let { addHeader("Authorization", "Bearer $it") }
+        }.build()
+
+        val response = chain.proceed(request)
+
+        // Handle 401: refresh token and retry
+        if (response.code == 401) {
+            response.close()
+            val newToken = tokenProvider.refreshToken()
+                ?: return response
+
+            val retryRequest = chain.request().newBuilder()
+                .header("Authorization", "Bearer $newToken")
+                .build()
+
+            return chain.proceed(retryRequest)
+        }
+
+        return response
+    }
+}
+```
+
+### Retry Interceptor
+
+```kotlin
+class RetryInterceptor(
+    private val maxRetries: Int = 3,
+    private val initialDelayMs: Long = 1_000,
+) : Interceptor {
+
+    override fun intercept(chain: Interceptor.Chain): Response {
+        var lastException: IOException? = null
+        var delay = initialDelayMs
+
+        repeat(maxRetries) { attempt ->
+            try {
+                val response = chain.proceed(chain.request())
+                if (response.isSuccessful || response.code !in 500..599) {
+                    return response
+                }
+                response.close()
+            } catch (e: IOException) {
+                lastException = e
+            }
+
+            if (attempt < maxRetries - 1) {
+                Thread.sleep(delay)
+                delay *= 2 // Exponential backoff
+            }
+        }
+
+        throw lastException ?: IOException("Request failed after $maxRetries retries")
+    }
+}
+```
+
+### Cache Interceptor
+
+```kotlin
+class CacheInterceptor : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val response = chain.proceed(chain.request())
+        val cacheControl = CacheControl.Builder()
+            .maxAge(5, TimeUnit.MINUTES)
+            .build()
+
+        return response.newBuilder()
+            .header("Cache-Control", cacheControl.toString())
+            .removeHeader("Pragma")
+            .build()
+    }
+}
+
+// Add cache to OkHttpClient
+val cacheDir = File(context.cacheDir, "http_cache")
+val cache = Cache(cacheDir, 10L * 1024 * 1024) // 10 MB
+
+OkHttpClient.Builder()
+    .cache(cache)
+    .addNetworkInterceptor(CacheInterceptor())
+    .build()
+```
+
+## Error Handling
+
+### Sealed Result Type
+
+```kotlin
+sealed interface NetworkResult<out T> {
+    data class Success<T>(val data: T) : NetworkResult<T>
+    data class Error(val code: Int, val message: String) : NetworkResult<Nothing>
+    data class Exception(val throwable: Throwable) : NetworkResult<Nothing>
+}
+```
+
+### Safe API Call Wrapper
+
+```kotlin
+suspend fun <T> safeApiCall(
+    apiCall: suspend () -> T,
+): NetworkResult<T> = try {
+    NetworkResult.Success(apiCall())
+} catch (e: HttpException) {
+    val errorBody = e.response()?.errorBody()?.string()
+    NetworkResult.Error(
+        code = e.code(),
+        message = errorBody ?: e.message(),
+    )
+} catch (e: IOException) {
+    NetworkResult.Exception(e)
+} catch (e: CancellationException) {
+    throw e // Never swallow cancellation
+}
+```
+
+### Usage in Repository
+
+```kotlin
+class FlightRepositoryImpl @Inject constructor(
+    private val api: FlightApiService,
+    private val mapper: FlightMapper,
+) : FlightRepository {
+
+    override suspend fun searchFlights(
+        origin: String,
+        destination: String,
+        date: LocalDate,
+    ): NetworkResult<List<Flight>> = safeApiCall {
+        api.searchFlights(origin, destination, date.toString())
+            .map(mapper::toDomain)
+    }
+}
+```
+
+### ViewModel Consumption
+
+```kotlin
+@HiltViewModel
+class SearchViewModel @Inject constructor(
+    private val repository: FlightRepository,
+) : ViewModel() {
+
+    private val _uiState = MutableStateFlow<SearchUiState>(SearchUiState.Idle)
+    val uiState: StateFlow<SearchUiState> = _uiState.asStateFlow()
+
+    fun search(origin: String, destination: String, date: LocalDate) {
+        viewModelScope.launch {
+            _uiState.value = SearchUiState.Loading
+
+            _uiState.value = when (val result = repository.searchFlights(origin, destination, date)) {
+                is NetworkResult.Success -> SearchUiState.Success(result.data)
+                is NetworkResult.Error -> SearchUiState.Error("Server error: ${result.message}")
+                is NetworkResult.Exception -> SearchUiState.Error(
+                    result.throwable.localizedMessage ?: "Network error"
+                )
+            }
+        }
+    }
+}
+```
+
+## Network-Bound Resource
+
+Pattern for showing cached data while fetching fresh data from the network.
+
+```kotlin
+inline fun <ResultType, RequestType> networkBoundResource(
+    crossinline query: () -> Flow<ResultType>,
+    crossinline fetch: suspend () -> RequestType,
+    crossinline saveFetchResult: suspend (RequestType) -> Unit,
+    crossinline shouldFetch: (ResultType) -> Boolean = { true },
+): Flow<Resource<ResultType>> = flow {
+    emit(Resource.Loading())
+
+    val data = query().first()
+
+    val flow = if (shouldFetch(data)) {
+        emit(Resource.Loading(data))
+        try {
+            val fetchedData = fetch()
+            saveFetchResult(fetchedData)
+            query().map { Resource.Success(it) }
+        } catch (throwable: Throwable) {
+            if (throwable is CancellationException) throw throwable
+            query().map { Resource.Error(throwable, it) }
+        }
+    } else {
+        query().map { Resource.Success(it) }
+    }
+
+    emitAll(flow)
+}
+
+sealed class Resource<T>(
+    val data: T? = null,
+    val error: Throwable? = null,
+) {
+    class Success<T>(data: T) : Resource<T>(data)
+    class Loading<T>(data: T? = null) : Resource<T>(data)
+    class Error<T>(throwable: Throwable, data: T? = null) : Resource<T>(data, throwable)
+}
+```
+
+### Usage
+
+```kotlin
+override fun getFlights(origin: String, destination: String): Flow<Resource<List<Flight>>> =
+    networkBoundResource(
+        query = {
+            dao.getFlights(origin, destination)
+                .map { entities -> entities.map(mapper::toDomain) }
+        },
+        fetch = { api.searchFlights(origin, destination, today()) },
+        saveFetchResult = { dtos ->
+            dao.upsertFlights(dtos.map(mapper::toEntity))
+        },
+        shouldFetch = { cachedFlights ->
+            cachedFlights.isEmpty() || cacheExpired()
+        },
+    )
+```
+
+## Multipart Uploads
+
+```kotlin
+interface FileApiService {
+
+    @Multipart
+    @POST("documents/upload")
+    suspend fun uploadDocument(
+        @Part file: MultipartBody.Part,
+        @Part("description") description: RequestBody,
+    ): UploadResponse
+}
+
+// Usage
+suspend fun uploadFile(context: Context, uri: Uri, description: String) {
+    val contentResolver = context.contentResolver
+    val inputStream = contentResolver.openInputStream(uri) ?: return
+    val fileName = getFileName(context, uri)
+
+    val requestBody = inputStream.readBytes()
+        .toRequestBody("application/octet-stream".toMediaType())
+
+    val part = MultipartBody.Part.createFormData("file", fileName, requestBody)
+    val descriptionBody = description.toRequestBody("text/plain".toMediaType())
+
+    api.uploadDocument(part, descriptionBody)
+}
+```
+
+## WebSocket Support
+
+```kotlin
+class FlightUpdatesWebSocket @Inject constructor(
+    private val client: OkHttpClient,
+) {
+    private var webSocket: WebSocket? = null
+
+    fun connect(flightId: String): Flow<FlightUpdate> = callbackFlow {
+        val request = Request.Builder()
+            .url("wss://api.example.com/flights/$flightId/updates")
+            .build()
+
+        val listener = object : WebSocketListener() {
+            override fun onMessage(webSocket: WebSocket, text: String) {
+                val update = Json.decodeFromString<FlightUpdate>(text)
+                trySend(update)
+            }
+
+            override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
+                close(t)
+            }
+
+            override fun onClosed(webSocket: WebSocket, code: Int, reason: String) {
+                channel.close()
+            }
+        }
+
+        webSocket = client.newWebSocket(request, listener)
+
+        awaitClose {
+            webSocket?.close(1000, "Client closed")
+        }
+    }
+
+    fun disconnect() {
+        webSocket?.close(1000, "Client closed")
+        webSocket = null
+    }
+}
+```
+
+## Do's and Don'ts
+
+### Do's
+- Use `suspend` functions in Retrofit interfaces for coroutine integration
+- Use `kotlinx.serialization` or Moshi for JSON parsing (not Gson for new projects)
+- Set logging to `NONE` in release builds
+- Handle `CancellationException` specially -- always rethrow it
+- Use `@SerialName` for JSON keys that differ from Kotlin property names
+- Implement token refresh in an interceptor, not in every API call
+- Set reasonable timeouts (connect: 30s, read: 30s, write: 30s)
+- Use OkHttp `Cache` for GET requests that tolerate staleness
+
+### Don'ts
+- Do not use `enqueue()` with callbacks -- use `suspend` functions instead
+- Do not catch `CancellationException` in `safeApiCall` -- rethrow it
+- Do not log request/response bodies in production (security risk)
+- Do not hardcode base URLs -- use `BuildConfig` or remote config
+- Do not create new `OkHttpClient` instances per request -- share a singleton
+- Do not use `Gson` for new projects -- prefer `kotlinx.serialization` or Moshi
+- Do not store tokens in SharedPreferences -- use EncryptedSharedPreferences
+- Do not perform API calls on the main thread
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| `JsonDecodingException` | API response does not match DTO | Add `ignoreUnknownKeys = true` to Json config; check field names |
+| `SocketTimeoutException` | Server slow or timeout too short | Increase timeout; check server health |
+| 401 on every request | Token not attached or expired | Verify AuthInterceptor and token refresh logic |
+| Response body consumed twice | Reading `errorBody()` after checking `body()` | Read error body once and store the string |
+| `NetworkOnMainThreadException` | Retrofit call not in coroutine | Use `suspend` functions and call from `viewModelScope` |
+| SSL handshake failure | Certificate pinning mismatch or expired cert | Update pins; check server certificate chain |
+| Cache not working | Missing `Cache` on OkHttpClient or no GET cache headers | Add `Cache` and `CacheInterceptor` |
+| Multipart upload fails | Wrong content type or part name mismatch | Match `@Part` name to server expectation |
+
+## Review Checklist
+
+- [ ] API interface uses `suspend` functions (not `Call<T>`)
+- [ ] `kotlinx.serialization` or Moshi used (not Gson)
+- [ ] Logging disabled in release builds
+- [ ] Auth interceptor handles 401 with token refresh
+- [ ] `CancellationException` is rethrown in error handling
+- [ ] Base URL comes from `BuildConfig`, not hardcoded string
+- [ ] `OkHttpClient` is a singleton via Hilt
+- [ ] Timeouts are set (connect, read, write)
+- [ ] Error handling uses sealed `NetworkResult` type
+- [ ] No tokens stored in plain SharedPreferences