@mmerterden/multi-agent-pipeline 20.1.0 → 20.2.0

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

@@ -9,12 +9,20 @@ Networking patterns for Android using Retrofit 2.11+, OkHttp 4.x, and
 kotlinx.serialization. Covers API definition, interceptors, error handling,
 caching, and Hilt integration.
 
+Full code for every pattern below lives in
+[`references/patterns.md`](references/patterns.md), under headings that mirror
+these sections. This file is the guide: read a section for the decision, then
+load the matching reference section when writing the implementation.
+
 ## Contents
 
 - [API Interface](#api-interface)
 - [Retrofit Setup with Hilt](#retrofit-setup-with-hilt)
 - [OkHttp Interceptors](#okhttp-interceptors)
 - [Error Handling](#error-handling)
+- [Envelope to Typed Exception](#envelope-to-typed-exception)
+- [Unknown-Tolerant Enum Serialization](#unknown-tolerant-enum-serialization)
+- [Client Composition and Environment Config](#client-composition-and-environment-config)
 - [Network-Bound Resource](#network-bound-resource)
 - [Multipart Uploads](#multipart-uploads)
 - [WebSocket Support](#websocket-support)
@@ -24,232 +32,52 @@ caching, and Hilt integration.
 
 ## API Interface
 
-Define endpoints as suspend functions. Retrofit handles coroutine integration.
+Define endpoints as `suspend` functions so Retrofit integrates with coroutines
+directly (no `Call<T>`/`enqueue`). Use `@Query`, `@Path`, `@Body` and `@Header`
+for request shaping, and annotate DTOs with `@Serializable` plus `@SerialName`
+for JSON keys that differ from Kotlin property names.
 
 ```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,
-)
-```
+See `references/patterns.md` -> "API Interface" for the full endpoint set
+(GET/POST/PUT/DELETE, header params) and the `@Serializable` DTO classes.
 
 ## 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)
-}
-```
+Provide `Json`, `OkHttpClient`, `Retrofit`, and each API service as singletons in
+a Hilt `@Module`. Configure `Json` with `ignoreUnknownKeys = true`, set explicit
+timeouts (connect/read/write 30s), and read the base URL from `BuildConfig`.
 
-## 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")
-    }
-}
-```
+See `references/patterns.md` -> "Retrofit Setup with Hilt" for the complete
+`NetworkModule` with all `@Provides` functions.
 
-### Cache Interceptor
+## OkHttp Interceptors
 
-```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()
-    }
-}
+Three interceptors cover most needs:
 
-// Add cache to OkHttpClient
-val cacheDir = File(context.cacheDir, "http_cache")
-val cache = Cache(cacheDir, 10L * 1024 * 1024) // 10 MB
+- Auth interceptor: attaches the bearer token and, on a 401, refreshes and
+  retries once. Keep token refresh here, not in every API call.
+- Retry interceptor: retries 5xx / IO failures with exponential backoff.
+- Cache interceptor: rewrites `Cache-Control` so GET responses cache for a bounded
+  window; pair it with an OkHttp `Cache` on the client.
 
-OkHttpClient.Builder()
-    .cache(cache)
-    .addNetworkInterceptor(CacheInterceptor())
-    .build()
-```
+See `references/patterns.md` -> "OkHttp Interceptors" for the `AuthInterceptor`,
+`RetryInterceptor`, and `CacheInterceptor` implementations plus the cache wiring.
 
 ## Error Handling
 
-### Sealed Result Type
+Model outcomes with a sealed `NetworkResult` (Success / Error / Exception) and
+wrap every call in `safeApiCall`. Always rethrow `CancellationException` -- never
+let it fall into a generic catch. Repositories return `NetworkResult`; ViewModels
+map it to UI state.
 
 ```kotlin
 sealed interface NetworkResult<out T> {
@@ -259,203 +87,76 @@ sealed interface NetworkResult<out T> {
 }
 ```
 
-### Safe API Call Wrapper
+See `references/patterns.md` -> "Error Handling" for `safeApiCall` and the
+repository + ViewModel consumption examples.
 
-```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
-}
-```
+## Envelope to Typed Exception
 
-### Usage in Repository
+When the backend wraps every payload in a `success` envelope, fold that envelope
+into the same failure path as transport errors instead of checking `success` at
+every call site. A delegating `Converter.Factory` deserializes the envelope, and
+when `success == false` throws a typed `ApiException(code, message)`. A central
+throwable-to-sealed-error mapper then turns `ApiException`, `HttpException` and
+IO failures into one `NetworkResult.Error`, so `safeApiCall` needs a single
+catch path.
 
-```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)
-    }
-}
-```
+See `references/patterns.md` -> "Envelope to Typed Exception" for the
+`EnvelopeUnwrapFactory`, `ApiException`, and the `toNetworkError` mapper.
 
-### ViewModel Consumption
+## Unknown-Tolerant Enum Serialization
 
-```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"
-                )
-            }
-        }
-    }
-}
-```
+`ignoreUnknownKeys` tolerates unknown object keys, not unknown enum values -- a
+new server code crashes the whole response. Give backend-driven enums a base
+`KSerializer` that maps any unrecognized value to a declared default (e.g.
+`UNKNOWN`), so one added server code degrades a single field instead of failing
+the payload.
 
-## Network-Bound Resource
+See `references/patterns.md` -> "Unknown-Tolerant Enum Serialization" for the
+`UnknownTolerantEnumSerializer` base class and an enum wired to it.
 
-Pattern for showing cached data while fetching fresh data from the network.
+## Client Composition and Environment Config
 
-```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)
-}
+Derive specialized clients from one base with `newBuilder()`; an image pipeline
+that must not carry auth headers clears inherited interceptors with
+`newBuilder().interceptors().clear()`. Resolve the per-flavor base URL and
+certificate-pin hashes from build config, and gate a runtime base-URL override
+to non-production builds only (QA environment switching). For a suspend token
+fetch inside `intercept()`, use the deadlock-safe bridge (`runBlocking` pinned to
+a dedicated single-thread dispatcher) rather than a bare `runBlocking { }` that
+resumes on the interceptor's own thread.
 
-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()
-        },
-    )
-```
+See `references/patterns.md` -> "Client Composition and Environment Config" for
+the image-client provider, `NetworkConfig`, and the `TokenInterceptor` bridge.
 
-## Multipart Uploads
+## Network-Bound Resource
 
-```kotlin
-interface FileApiService {
-
-    @Multipart
-    @POST("documents/upload")
-    suspend fun uploadDocument(
-        @Part file: MultipartBody.Part,
-        @Part("description") description: RequestBody,
-    ): UploadResponse
-}
+Use `networkBoundResource` to show cached data immediately while fetching fresh
+data, then re-emit from the cache after saving. It emits a `Resource`
+(Loading / Success / Error) that always carries the latest cached data. Rethrow
+`CancellationException` inside the fetch block.
 
-// 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)
+See `references/patterns.md` -> "Network-Bound Resource" for the
+`networkBoundResource` builder, the `Resource` sealed class, and a DAO + API
+usage example.
 
-    val requestBody = inputStream.readBytes()
-        .toRequestBody("application/octet-stream".toMediaType())
+## Multipart Uploads
 
-    val part = MultipartBody.Part.createFormData("file", fileName, requestBody)
-    val descriptionBody = description.toRequestBody("text/plain".toMediaType())
+Declare a `@Multipart @POST` endpoint taking `MultipartBody.Part` for the file
+and `RequestBody` parts for metadata. Build the file part from the content
+resolver stream with `createFormData`, matching the `@Part` name to the server's
+expectation.
 
-    api.uploadDocument(part, descriptionBody)
-}
-```
+See `references/patterns.md` -> "Multipart Uploads" for the `FileApiService`
+endpoint and the `uploadFile` helper.
 
 ## 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
-    }
-}
-```
+Wrap an OkHttp `WebSocket` in a `callbackFlow` so updates arrive as a cold `Flow`.
+Forward `onMessage` with `trySend`, close the flow on `onFailure`/`onClosed`, and
+close the socket in `awaitClose`.
+
+See `references/patterns.md` -> "WebSocket Support" for the
+`FlightUpdatesWebSocket` implementation.
 
 ## Do's and Don'ts
 
@@ -468,6 +169,10 @@ class FlightUpdatesWebSocket @Inject constructor(
 - 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
+- Fold a `success` response envelope into a typed `ApiException` in a converter
+- Map backend-driven enums with an unknown-tolerant serializer (default value)
+- Derive specialized clients from one base with `newBuilder()`
+- Read base URL and pin hashes from build config; override only in non-prod
 
 ### Don'ts
 - Do not use `enqueue()` with callbacks -- use `suspend` functions instead
@@ -478,6 +183,8 @@ class FlightUpdatesWebSocket @Inject constructor(
 - 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
+- Do not rely on `ignoreUnknownKeys` to survive unknown enum values -- it does not
+- Do not call a bare `runBlocking { }` in `intercept()` -- pin it to a dedicated dispatcher
 
 ## Troubleshooting
 
@@ -503,4 +210,8 @@ class FlightUpdatesWebSocket @Inject constructor(
 - [ ] `OkHttpClient` is a singleton via Hilt
 - [ ] Timeouts are set (connect, read, write)
 - [ ] Error handling uses sealed `NetworkResult` type
+- [ ] Response envelope failures surface as a typed `ApiException`
+- [ ] Backend-driven enums use an unknown-tolerant serializer
+- [ ] Base URL + pin hashes come from build config; override gated to non-prod
+- [ ] Suspend work in interceptors is bridged on a dedicated dispatcher
 - [ ] No tokens stored in plain SharedPreferences