Merge pull request #26 from haroldadmin/development

Add ability to parse status code and headers to NetworkResponse.UnknownError

Author: haroldadmin

docs/docs/docs/index.md

@@ -30,7 +30,7 @@ data class DetailsError(
 )
 
 interface Api {
-  @Get("/details)
+  @Get("/details")
   suspend fun details(): NetworkResponse<DetailsResponse, DetailsError>
 }
 

docs/docs/docs/special-cases.md

@@ -31,3 +31,19 @@ val retrofit = Retrofit.Builder()
  .baseUrl("...")
  .build()
 ```
+
+## Status code and Headers in `NetworkResponse.UnknownError`
+
+Network requests that result in a `NetworkResponse.UnknownError` can still convey useful information through their headers and status code. Unfortunately, it is not always possible to extract these values from a failed request.
+
+Therefore, the `NetworkResponse.UnknownError` class contains nullable fields for the status code and headers. These fields are populated if their values can be extract from a failed request.
+
+```kotlin
+data class UnknownError(
+    val error: Throwable,
+    val code: Int? = null,
+    val headers: Headers? = null,
+) : NetworkResponse<Nothing, Nothing>()
+```
+
+It is possible to extract this information from a failed request in most cases. However, if the server responds with a successful status code (200 <= code < 300) and an invalid body (which can not be parsed correctly), Retrofit assumes the network request failed. It forwards only the raised error and the original call to the registered call adapter, and thus all information about the response is lost resulting in a `NetworkResponse.UnknownError` with null `code` and `headers`.

src/main/kotlin/com/haroldadmin/cnradapter/NetworkResponse.kt

@@ -32,5 +32,9 @@ sealed class NetworkResponse<out T : Any, out U : Any> {
      *
      * An example of such an error is JSON parsing exception thrown by a serialization library.
      */
-    data class UnknownError(val error: Throwable) : NetworkResponse<Nothing, Nothing>()
+    data class UnknownError(
+        val error: Throwable,
+        val code: Int? = null,
+        val headers: Headers? = null,
+    ) : NetworkResponse<Nothing, Nothing>()
 }

src/main/kotlin/com/haroldadmin/cnradapter/ResponseHandler.kt

@@ -10,52 +10,56 @@ import java.lang.reflect.Type
  */
 internal object ResponseHandler {
 
-    /**
-     * Converts the given [response] to a subclass of [NetworkResponse] based on different conditions.
-     *
-     * If the server response is successful with:
-     * => a non-empty body -> NetworkResponse.Success<S, E>
-     * => an empty body (and [successBodyType] is Unit) -> NetworkResponse.Success<Unit, E>
-     * => an empty body (and [successBodyType] is not Unit) -> NetworkResponse.ServerError<E>
-     *
-     * @param response Retrofit's response object supplied to the call adapter
-     * @param successBodyType A [Type] representing the success body
-     * @param errorConverter A retrofit converter to convert the error body into the error response type (E)
-     * @param S The success body type generic parameter
-     * @param E The error body type generic parameter
-     */
-    fun <S : Any, E : Any> handle(
-        response: Response<S>,
-        successBodyType: Type,
-        errorConverter: Converter<ResponseBody, E>
-    ): NetworkResponse<S, E> {
-        val body = response.body()
-        val headers = response.headers()
-        val code = response.code()
-        val errorBody = response.errorBody()
+  /**
+   * Converts the given [response] to a subclass of [NetworkResponse] based on different conditions.
+   *
+   * If the server response is successful with:
+   * => a non-empty body -> NetworkResponse.Success<S, E>
+   * => an empty body (and [successBodyType] is Unit) -> NetworkResponse.Success<Unit, E>
+   * => an empty body (and [successBodyType] is not Unit) -> NetworkResponse.ServerError<E>
+   *
+   * @param response Retrofit's response object supplied to the call adapter
+   * @param successBodyType A [Type] representing the success body
+   * @param errorConverter A retrofit converter to convert the error body into the error response type (E)
+   * @param S The success body type generic parameter
+   * @param E The error body type generic parameter
+   */
+  fun <S : Any, E : Any> handle(
+      response: Response<S>,
+      successBodyType: Type,
+      errorConverter: Converter<ResponseBody, E>
+  ): NetworkResponse<S, E> {
+    val body = response.body()
+    val headers = response.headers()
+    val code = response.code()
+    val errorBody = response.errorBody()
 
-        return if (response.isSuccessful) {
-            if (body != null) {
-                NetworkResponse.Success(body, headers, code)
-            } else {
-                // Special case: If the response is successful and the body is null, return a successful response
-                // if the service method declares the success body type as Unit. Otherwise, return a server error
-                if (successBodyType == Unit::class.java) {
-                    @Suppress("UNCHECKED_CAST")
-                    NetworkResponse.Success(Unit, headers, code) as NetworkResponse<S, E>
-                } else {
-                    NetworkResponse.ServerError(null, code, headers)
-                }
-            }
+    return if (response.isSuccessful) {
+      if (body != null) {
+        NetworkResponse.Success(body, headers, code)
+      } else {
+        // Special case: If the response is successful and the body is null, return a successful response
+        // if the service method declares the success body type as Unit. Otherwise, return a server error
+        if (successBodyType == Unit::class.java) {
+          @Suppress("UNCHECKED_CAST")
+          NetworkResponse.Success(Unit, headers, code) as NetworkResponse<S, E>
         } else {
-            val networkResponse: NetworkResponse<S, E> = try {
-                val convertedBody = errorConverter.convert(errorBody)
-                NetworkResponse.ServerError(convertedBody, code, headers)
-            } catch (ex: Exception) {
-                NetworkResponse.UnknownError(ex)
-            }
-            networkResponse
+          NetworkResponse.ServerError(null, code, headers)
         }
+      }
+    } else {
+      val networkResponse: NetworkResponse<S, E> = try {
+        val convertedBody = if (errorBody == null) {
+          null
+        } else {
+          errorConverter.convert(errorBody)
+        }
+        NetworkResponse.ServerError(convertedBody, code, headers)
+      } catch (ex: Exception) {
+        NetworkResponse.UnknownError(ex, code = code, headers = headers)
+      }
+      networkResponse
     }
+  }
 
 }

src/test/kotlin/com/haroldadmin/cnradapter/MoshiApplicationTest.kt

@@ -25,6 +25,7 @@ internal data class GenericErrorResponse(val error: String)
 
 internal data class GenericErrorResponseInvalid(@Json(name = "errrorrrr") val error: String)
 
+@Suppress("DeferredIsResult")
 internal interface LaunchesService {
     @GET("launches/{flightNumber}")
     suspend fun launchForFlightNumber(
@@ -143,12 +144,32 @@ internal class MoshiApplicationTest: AnnotationSpec() {
         server.enqueue(MockResponse().apply {
             setBody(resourceFileContents("/falconsat_launch.json"))
             setResponseCode(200)
+            setHeader("test", "true")
         })
         val response = app.getLaunchWithFailure(validFlightNumber)
 
         response.shouldBeInstanceOf<NetworkResponse.UnknownError>()
         response as NetworkResponse.UnknownError
         response.error.shouldBeInstanceOf<JsonDataException>()
+        response.code shouldBe null
+        response.headers shouldBe null
+    }
+
+    @Test
+    fun shouldParseResponseCodeAndHeadersOfUnsuccessfulRequestWithInvalidBodyCorrectly() {
+        val app = TestApplication(service)
+        server.enqueue(MockResponse().apply {
+            setBody("""{ "message": "Too many requests!" }""")
+            setResponseCode(429)
+            setHeader("test", "true")
+        })
+        val response = app.getLaunchWithFailure(validFlightNumber)
+
+        response.shouldBeInstanceOf<NetworkResponse.UnknownError>()
+        response as NetworkResponse.UnknownError
+        response.error.shouldBeInstanceOf<JsonDataException>()
+        response.code shouldBe 429
+        response.headers!!["test"] shouldBe "true"
     }
 
     @Test