Upgrade Guide for v5

The 5.0 release of NetworkResponseAdapter is an overhaul of the internals of the library. Most users should be able to update the version number in their dependencies without any other changes.

Contributors

Huge thanks to community members Gil Goldzweig and Leandro for their help with this release.

Changes

Breaking

• Removal of deprecated CoroutinesNetworkResponseAdapterFactory and CoroutinesNetworkResponseAdapter classes.

These classes had been deprecated for a very long time. v5 removes them from the codebase. If you're still using them, please move to NetworkResponseAdapterFactory and NetworkResponseAdapter classes as a replacement.

• The constructors for NetworkResponse subclasses have changed (#59)

NetworkResponse.Success, NetworkResponse.ServerError and NetworkResponse.UnknownError no longer accept status code, headers or body as constructor parameters. Instead, you must supply a correctly configured instance of a Retrofit Response.

Here's an example with Mockito:

In v4:

whenever(apiService.signOut(any()))
    .thenReturn(NetworkResponse.Success(code = 200, body = Unit))

In v5:

// NetworkResponse.Success
whenever(apiService.signOut(any()))
    .thenReturn(NetworkResponse.Success(response = Response.success(200), body = Unit))

// NetworkResponse.Error
val errorResponse = Response.error<String>(
    500,
    "{\"error\": \"boom\"}"
        .toResponseBody("application/json")
        .toMediaTypeOrNull(),
)

whenever(apiService.signOut(any()))
    .thenReturn(NetworkResponse.ServerError(response = errorResponse, body = ErrorResponse("boom")))

Backward Compatible (Non-Breaking)

• Migration to a sealed interface for the NetworkResponse type

Sealed interfaces allow more succinct when expressions if you don't care about the specific type of the error.

when (response) {
    is NetworkResponse.Success -> // ...
    is NetworkResponse.Error -> // ...
}

You can still access the full range of subtypes if you need to:

when (response) {
    is NetworkResponse.Success -> // ...
    is NetworkResponse.ServerError -> // ...
    is NetworkResponse.NetworkError -> // ...
    is NetworkResponse.UnknownError -> // ...
}

Attention

This can be a potentially breaking change if you relied on sealed class specific behaviour of NetworkResponse. Most users will not be affected it.

• Bundled Retrofit responses:

NetworkResponse.Success, NetworkResponse.ServerError and NetworkResponse.UnknownError now bundle the original Retrofit response with them (when it is available). This allows you to look at the raw response directly, if needed.

when (networkResponse) {
  is NetworkResponse.Success -> {
    val retrofitResponse = networkResponse.response
  }
}

• Tests Overhaul & Migration to Kotest

This PR gets refactors the library's test suite to get rid of redundant and obscure tests, and replaces them with a streamlined test suite focused on publicly exposed functionality.

We've also finally moved away from the deprecated kotlintest artifacts to the new kotest libraries.

• Kotlin 1.6

The library now depends on Kotlin 1.6

• New Sample App

The repository now includes a sample app to demonstrate the usage of this library with Retrofit and the kotlinx.serialization library.