android-sdd 1.0.0

package/skills/Meta Skills/Error Mapping/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: error-mapping
+description: >
+  Error mapping between layers in Android Clean Architecture.
+  Load this skill when converting HTTP exceptions to domain errors,
+  mapping Room/SQLite exceptions to domain errors, translating domain
+  errors to UI messages, or designing the error translation pipeline.
+---
+
+# Error Mapping
+
+## Overview
+Error mapping converts layer-specific errors (HTTP status codes, Room exceptions, IO errors) into domain errors at each architectural boundary. The domain layer defines a typed error hierarchy; the data layer maps raw exceptions to it; the presentation layer maps domain errors to user-facing messages.
+
+---
+
+## Core Principles
+
+- **Map at boundaries** — data layer maps to domain errors; ViewModel maps to messages
+- **Domain errors know nothing** about HTTP, Room, or Retrofit
+- **Exhaustive mapping** — every possible error type has an explicit mapping
+- **Preserve context** — include enough info in domain errors to display meaningful messages
+- **One mapper per data source** — separate HTTP mapper, Room mapper, etc.
+
+---
+
+## Domain Error Model
+
+```kotlin
+// ✅ Domain errors — pure Kotlin, no framework imports
+// (See domain-error-model skill for full hierarchy)
+sealed interface AppError {
+    // Network
+    sealed interface Network : AppError {
+        data object NoConnection : Network
+        data object Timeout : Network
+        data class ServerError(val code: Int) : Network
+        data object Unauthorized : Network
+        data object Forbidden : Network
+        data object NotFound : Network
+    }
+    // Data
+    sealed interface Data : AppError {
+        data object NotFound : Data
+        data class Conflict(val field: String) : Data
+        data class Validation(val errors: Map<String, String>) : Data
+    }
+    // Local storage
+    sealed interface Storage : AppError {
+        data object DiskFull : Storage
+        data object Corrupted : Storage
+        data class Unknown(val cause: Throwable) : Storage
+    }
+    // Unknown
+    data class Unexpected(val cause: Throwable) : AppError
+}
+```
+
+---
+
+## HTTP Error Mapper
+
+```kotlin
+// ✅ Map Retrofit/HTTP exceptions to domain errors
+object HttpErrorMapper {
+
+    fun map(throwable: Throwable): AppError = when (throwable) {
+        is HttpException -> mapHttpException(throwable)
+        is IOException   -> mapIoException(throwable)
+        is SSLException  -> AppError.Network.NoConnection
+        else             -> AppError.Unexpected(throwable)
+    }
+
+    private fun mapHttpException(e: HttpException): AppError = when (e.code()) {
+        400  -> parseValidationError(e) ?: AppError.Unexpected(e)
+        401  -> AppError.Network.Unauthorized
+        403  -> AppError.Network.Forbidden
+        404  -> AppError.Network.NotFound
+        409  -> parseConflictError(e) ?: AppError.Data.Conflict("unknown")
+        in 500..599 -> AppError.Network.ServerError(e.code())
+        else -> AppError.Unexpected(e)
+    }
+
+    private fun mapIoException(e: IOException): AppError = when (e) {
+        is SocketTimeoutException,
+        is ConnectTimeoutException -> AppError.Network.Timeout
+        else                       -> AppError.Network.NoConnection
+    }
+
+    private fun parseValidationError(e: HttpException): AppError? = try {
+        val body = e.response()?.errorBody()?.string() ?: return null
+        val errors = Json.decodeFromString<ValidationErrorDto>(body)
+        AppError.Data.Validation(errors.fields)
+    } catch (parseException: Exception) {
+        null
+    }
+
+    private fun parseConflictError(e: HttpException): AppError? = try {
+        val body = e.response()?.errorBody()?.string() ?: return null
+        val error = Json.decodeFromString<ConflictErrorDto>(body)
+        AppError.Data.Conflict(error.field)
+    } catch (parseException: Exception) {
+        null
+    }
+}
+```
+
+---
+
+## Room Error Mapper
+
+```kotlin
+// ✅ Map Room/SQLite exceptions to domain errors
+object RoomErrorMapper {
+
+    fun map(throwable: Throwable): AppError = when (throwable) {
+        is SQLiteFullException        -> AppError.Storage.DiskFull
+        is SQLiteDatabaseCorruptException -> AppError.Storage.Corrupted
+        is SQLiteConstraintException  -> parseConstraintError(throwable)
+        else                          -> AppError.Storage.Unknown(throwable)
+    }
+
+    private fun parseConstraintError(e: SQLiteConstraintException): AppError {
+        val message = e.message ?: ""
+        return when {
+            message.contains("UNIQUE") -> AppError.Data.Conflict(
+                extractColumnName(message)
+            )
+            else -> AppError.Storage.Unknown(e)
+        }
+    }
+
+    private fun extractColumnName(message: String): String {
+        // "UNIQUE constraint failed: users.email" → "email"
+        return message.substringAfterLast(".").takeIf { it.isNotBlank() } ?: "unknown"
+    }
+}
+```
+
+---
+
+## Repository Using Mappers
+
+```kotlin
+// ✅ Repository applies mappers at the boundary
+class UserRepositoryImpl @Inject constructor(
+    private val api: UserApiService,
+    private val dao: UserDao
+) : UserRepository {
+
+    override suspend fun getUser(id: String): Result<User> =
+        runCatching {
+            dao.getById(id)?.toDomain()
+                ?: api.getUser(id).toDomain().also { dao.insert(it.toEntity()) }
+        }.mapFailure { throwable ->
+            when (throwable) {
+                is HttpException,
+                is IOException -> HttpErrorMapper.map(throwable)
+                is SQLiteException -> RoomErrorMapper.map(throwable)
+                else -> AppError.Unexpected(throwable)
+            }
+        }
+
+    override suspend fun createUser(user: User): Result<User> =
+        runCatching {
+            api.createUser(user.toCreateRequest()).toDomain()
+        }.mapFailure { HttpErrorMapper.map(it) }
+}
+
+// ✅ Extension to map the failure in a Result
+fun <T> Result<T>.mapFailure(transform: (Throwable) -> Throwable): Result<T> =
+    fold(
+        onSuccess = { Result.success(it) },
+        onFailure = { Result.failure(transform(it)) }
+    )
+
+// Or use domain error as sealed class (not Throwable)
+fun <T> Result<T>.mapError(transform: (Throwable) -> AppError): Result<T> =
+    recoverCatching { throw AppErrorException(transform(it)) }
+
+class AppErrorException(val error: AppError) : Exception()
+```
+
+---
+
+## ViewModel → UI Message Mapping
+
+```kotlin
+// ✅ ViewModel maps domain errors to UI strings
+fun AppError.toUiMessage(context: Context): String = when (this) {
+    is AppError.Network.NoConnection  -> context.getString(R.string.error_no_connection)
+    is AppError.Network.Timeout       -> context.getString(R.string.error_timeout)
+    is AppError.Network.Unauthorized  -> context.getString(R.string.error_session_expired)
+    is AppError.Network.Forbidden     -> context.getString(R.string.error_no_permission)
+    is AppError.Network.NotFound      -> context.getString(R.string.error_not_found)
+    is AppError.Network.ServerError   -> context.getString(R.string.error_server, code)
+    is AppError.Data.NotFound         -> context.getString(R.string.error_item_not_found)
+    is AppError.Data.Conflict         -> context.getString(R.string.error_conflict, field)
+    is AppError.Data.Validation       -> errors.values.first()
+    is AppError.Storage.DiskFull      -> context.getString(R.string.error_disk_full)
+    is AppError.Storage.Corrupted     -> context.getString(R.string.error_data_corrupted)
+    is AppError.Storage.Unknown,
+    is AppError.Unexpected            -> context.getString(R.string.error_unexpected)
+}
+
+// ✅ Or without Context — use string keys resolved in Compose
+fun AppError.toMessageKey(): Int = when (this) {
+    is AppError.Network.NoConnection -> R.string.error_no_connection
+    is AppError.Network.Timeout      -> R.string.error_timeout
+    // ...
+    else                             -> R.string.error_unexpected
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Mapping HTTP codes in the ViewModel — belongs in the data layer mapper
+- Domain error types that import `retrofit2` or `androidx.room` — domain must stay pure
+- Catch-all `else -> AppError.Unexpected` without logging — unexpected errors should be tracked
+- Showing raw exception messages to users — `e.message` is for developers, not users
+- One giant `when(throwable)` across all layers — each layer has its own mapper
+
+---
+
+## Related Skills
+- `error-handling` — overall error propagation strategy
+- `domain-error-model` — the domain error sealed class hierarchy
+- `failure-strategy` — how to respond to each error type
+- `user-friendly-errors` — composable/string resource error display
+- `repository-pattern` — where mappers are applied

package/skills/Meta Skills/Failure Strategy/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: failure-strategy
+description: >
+  Failure response strategy for Android apps.
+  Load this skill when deciding how to respond to different error types,
+  implementing retry logic, handling session expiry globally,
+  designing fallback behavior, or choosing between silent fail and user notification.
+---
+
+# Failure Strategy
+
+## Overview
+Failure strategy defines what the app does when an error occurs — not just what message to show, but whether to retry, fall back to cached data, redirect to login, or block the user. Different errors require different responses, and some responses (like session expiry handling) should be centralized rather than handled per-screen.
+
+---
+
+## Core Principles
+
+- **Match response to error severity** — silent fail for non-critical, block for auth failures
+- **Centralize cross-cutting failures** — session expiry and network availability are app-level concerns
+- **Retry with backoff** for transient errors — network timeouts and server errors
+- **Fallback to cache** when possible — offline-first is better than blank error screens
+- **Let the user decide** on recoverable errors — show retry, not just error message
+
+---
+
+## Failure Response Matrix
+
+| Error | Response |
+|---|---|
+| `Network.NoConnection` | Show offline banner + cached data |
+| `Network.Timeout` | Auto-retry (1-2x), then show retry button |
+| `Network.ServerError` | Show error + retry button |
+| `Network.Unauthorized` | Redirect to login (global handler) |
+| `Network.Forbidden` | Show permission error, no retry |
+| `Network.NotFound` | Show not-found state, no retry |
+| `Data.Validation` | Show inline field errors |
+| `Data.Conflict` | Show specific conflict message |
+| `Storage.DiskFull` | Show disk full warning, prompt to free space |
+| `Auth.AccountSuspended` | Show suspension message, no retry |
+| `Unexpected` | Log + show generic error + retry |
+
+---
+
+## Retry with Exponential Backoff
+
+```kotlin
+// ✅ Retry helper for transient errors
+suspend fun <T> retryWithBackoff(
+    times: Int = 3,
+    initialDelay: Long = 500L,
+    maxDelay: Long = 5_000L,
+    factor: Double = 2.0,
+    retryIf: (Throwable) -> Boolean = { true },
+    block: suspend () -> T
+): T {
+    var currentDelay = initialDelay
+    repeat(times - 1) { attempt ->
+        try {
+            return block()
+        } catch (e: CancellationException) {
+            throw e  // never retry cancellation
+        } catch (e: Exception) {
+            if (!retryIf(e)) throw e
+            Timber.w(e, "Attempt ${attempt + 1} failed, retrying in ${currentDelay}ms")
+            delay(currentDelay)
+            currentDelay = (currentDelay * factor).toLong().coerceAtMost(maxDelay)
+        }
+    }
+    return block()  // last attempt — let it throw
+}
+
+// ✅ Usage in Repository
+override suspend fun syncData(): Result<Unit> = runCatching {
+    retryWithBackoff(
+        times = 3,
+        retryIf = { e -> e is IOException || (e is HttpException && e.code() >= 500) }
+    ) {
+        api.syncData()
+    }
+}
+```
+
+---
+
+## Global Session Expiry Handler
+
+```kotlin
+// ✅ Intercept 401 globally via OkHttp Authenticator
+class TokenRefreshAuthenticator @Inject constructor(
+    private val securePreferences: SecurePreferences,
+    private val authApi: AuthApiService,
+    private val sessionManager: SessionManager
+) : Authenticator {
+
+    private val isRefreshing = AtomicBoolean(false)
+
+    override fun authenticate(route: Route?, response: Response): Request? {
+        if (response.code != 401) return null
+        if (responseCount(response) >= 2) {
+            // Refresh failed — force logout
+            sessionManager.logout()
+            return null
+        }
+
+        synchronized(this) {
+            if (isRefreshing.get()) return null
+            isRefreshing.set(true)
+
+            return try {
+                val refreshToken = securePreferences.refreshToken ?: run {
+                    sessionManager.logout()
+                    return null
+                }
+
+                val newTokens = runBlocking { authApi.refreshToken(refreshToken) }
+                securePreferences.authToken = newTokens.accessToken
+                securePreferences.refreshToken = newTokens.refreshToken
+
+                response.request.newBuilder()
+                    .header("Authorization", "Bearer ${newTokens.accessToken}")
+                    .build()
+            } catch (e: Exception) {
+                sessionManager.logout()
+                null
+            } finally {
+                isRefreshing.set(false)
+            }
+        }
+    }
+
+    private fun responseCount(response: Response): Int {
+        var count = 1
+        var prior = response.priorResponse
+        while (prior != null) { count++; prior = prior.priorResponse }
+        return count
+    }
+}
+
+// ✅ SessionManager broadcasts logout event to all screens
+class SessionManager @Inject constructor() {
+    private val _sessionEvents = MutableSharedFlow<SessionEvent>(extraBufferCapacity = 1)
+    val sessionEvents: SharedFlow<SessionEvent> = _sessionEvents.asSharedFlow()
+
+    fun logout() {
+        _sessionEvents.tryEmit(SessionEvent.SessionExpired)
+    }
+}
+
+sealed interface SessionEvent {
+    data object SessionExpired : SessionEvent
+    data object LoggedOut : SessionEvent
+}
+```
+
+---
+
+## App-Level Session Observer
+
+```kotlin
+// ✅ Observe session events in root ViewModel or Activity
+@HiltViewModel
+class AppViewModel @Inject constructor(
+    private val sessionManager: SessionManager
+) : ViewModel() {
+
+    private val _navigationEvents = Channel<AppNavigationEvent>(Channel.BUFFERED)
+    val navigationEvents: Flow<AppNavigationEvent> = _navigationEvents.receiveAsFlow()
+
+    init {
+        viewModelScope.launch {
+            sessionManager.sessionEvents.collect { event ->
+                when (event) {
+                    SessionEvent.SessionExpired -> {
+                        _navigationEvents.send(AppNavigationEvent.NavigateToLogin)
+                    }
+                    SessionEvent.LoggedOut -> {
+                        _navigationEvents.send(AppNavigationEvent.NavigateToLogin)
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+---
+
+## Fallback to Cache Strategy
+
+```kotlin
+// ✅ Show stale cache while fetching fresh data
+class ProductRepositoryImpl @Inject constructor(
+    private val api: ProductApiService,
+    private val dao: ProductDao
+) : ProductRepository {
+
+    override fun observeProducts(): Flow<List<Product>> = flow {
+        // 1. Emit cached data immediately
+        val cached = dao.getAll().map { it.toDomain() }
+        if (cached.isNotEmpty()) emit(cached)
+
+        // 2. Fetch fresh data in background
+        try {
+            val fresh = api.getProducts().map { it.toDomain() }
+            dao.replaceAll(fresh.map { it.toEntity() })
+            emit(fresh)
+        } catch (e: IOException) {
+            // Network failed — cached data already emitted, just log
+            Timber.w(e, "Failed to refresh products, showing cached data")
+        }
+    }
+}
+```
+
+---
+
+## Per-Screen Retry Pattern
+
+```kotlin
+// ✅ Retry button in UiState
+data class ProductListUiState(
+    val isLoading: Boolean = false,
+    val products: List<Product> = emptyList(),
+    val error: ErrorState? = null
+)
+
+data class ErrorState(
+    val message: String,
+    val canRetry: Boolean
+)
+
+// ✅ Retry composable
+@Composable
+fun ErrorView(
+    error: ErrorState,
+    onRetry: () -> Unit,
+    modifier: Modifier = Modifier
+) {
+    Column(
+        modifier = modifier,
+        horizontalAlignment = Alignment.CenterHorizontally
+    ) {
+        Text(error.message)
+        if (error.canRetry) {
+            Spacer(Modifier.height(16.dp))
+            Button(onClick = onRetry) { Text("Try Again") }
+        }
+    }
+}
+
+// ✅ ViewModel
+fun loadProducts() {
+    viewModelScope.launch {
+        _state.update { it.copy(isLoading = true, error = null) }
+        getProductsUseCase().fold(
+            onSuccess = { products ->
+                _state.update { it.copy(isLoading = false, products = products) }
+            },
+            onFailure = { error ->
+                _state.update {
+                    it.copy(
+                        isLoading = false,
+                        error = ErrorState(
+                            message = error.toUserMessage(),
+                            canRetry = (error as? AppException)?.error?.isRetryable() ?: true
+                        )
+                    )
+                }
+            }
+        )
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Same error response for all error types — `Unauthorized` needs redirect, `Timeout` needs retry
+- Retrying non-retryable errors — `403 Forbidden` won't succeed on retry; don't offer it
+- Handling session expiry in every screen — centralize in OkHttp Authenticator + AppViewModel
+- Silently swallowing errors without logging — bugs become invisible
+- Infinite retry without backoff — hammers the server during outages
+
+---
+
+## Related Skills
+- `error-handling` — error propagation across layers
+- `domain-error-model` — typed errors that drive strategy decisions
+- `error-mapping` — mapping raw exceptions to domain errors
+- `user-friendly-errors` — displaying error states in UI
+- `offline-first` — cache fallback as part of failure strategy
+- `secure-networking` — token refresh interceptor