feat: add request cancellation (#123)

Author: edeckers

README.md

@@ -256,6 +256,34 @@ Object.getOwnPropertySymbols({
 
 ```
 
+### Cancel request
+
+```tsx
+import BlobCourier from 'react-native-blob-courier';
+
+// ...
+
+const abortController = new AbortController();
+
+const { signal } = abortController;
+
+const request0 = {
+  // ...
+  signal,
+};
+
+try {
+  BlobCourier.fetchBlob(request0);
+
+  abortController.abort();
+} catch (e) {
+  if (e.code === ERROR_CANCELED_EXCEPTION) {
+    // ...
+  }
+}
+
+// ...
+```
 
 ## Fluent interface
 
@@ -298,10 +326,11 @@ Optional
 | ------------ | -------------------------------- | ----------------------------------------- | ---------------------------------------------------- |
 | `android`    | `AndroidSettings`                | Settings to be used on Android            | `{ downloadManager: {}, target: 'cache', useDownloadManager: false }` |
 | `headers`    | `{ [key: string]: string }`      | Map of headers to send with the request   | `{}`                                                 |
-| `ios`        | `IOSSettings`                    | Settings to be used on iOS                | `{ target: 'cache' }` |
+| `ios`        | `IOSSettings`                    | Settings to be used on iOS                | `{ target: 'cache' }`                                |
 | `headers`    | `{ [key: string]: string }`      | Map of headers to send with the request   | `{}`                                                 |
 | `method`     | `string`                         | Representing the HTTP method              | `GET`                                                |
 | `onProgress` | `(e: BlobProgressEvent) => void` | Function handling progress updates        | `() => { }`                                          |
+| `signal`     | `AbortSignal`                    | Request cancellation manager              | `null`                                               |
 
 Response
 
@@ -354,6 +383,7 @@ Optional
 | `multipartName`  | `string`                         | Name for the file multipart               | `"file"`                            |
 | `onProgress`     | `(e: BlobProgressEvent) => void` | Function handling progress updates        | `() => { }`                         |
 | `returnResponse` | `boolean`                        | Return the HTTP response body?            | `false`                             |
+| `signal`         | `AbortSignal`                    | Request cancellation manager              | `null`                              | 
 
 ### `uploadParts(input: BlobMultipartUploadRequest)`
 
@@ -369,9 +399,10 @@ Optional
 | **Field**        | **Type**                         | **Description**                           | **Default** |
 | ---------------- | -------------------------------- | ----------------------------------------- | ----------- |
 | `headers`        | `{ [key: string]: string }`      | Map of headers to send with the request   | `{}`        |
-| `method`         | `string`                         | The HTTP method to be used in the request | `"POST"`      |
+| `method`         | `string`                         | The HTTP method to be used in the request | `"POST"`    |
 | `onProgress`     | `(e: BlobProgressEvent) => void` | Function handling progress updates        | `() => { }` |
 | `returnResponse` | `boolean`                        | Return the HTTP response body?            | `false`     |
+| `signal`         | `AbortSignal`                    | Request cancellation manager              | `null`      |
 
 Response
 

android/build.gradle

@@ -156,6 +156,7 @@ dependencies {
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
   implementation 'com.android.support:multidex:1.0.3'
   implementation "com.squareup.okhttp3:okhttp:3.14.9"
+  implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.0.0'
   testImplementation 'androidx.test:core:1.3.0'
   testImplementation 'junit:junit:4.13.1'
   testImplementation "io.mockk:mockk:1.10.2"

android/src/androidTest/java/io/deckers/blob_courier/BlobCourierInstrumentedModuleTests.kt

@@ -4,6 +4,7 @@
  * This source code is licensed under the MPL-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
  */
+
 import androidx.test.core.app.ApplicationProvider
 import androidx.test.platform.app.InstrumentationRegistry
 import com.facebook.react.bridge.Arguments
@@ -13,29 +14,39 @@ import com.facebook.react.bridge.ReactApplicationContext
 import io.deckers.blob_courier.BuildConfig.ADB_COMMAND_TIMEOUT_MILLISECONDS
 import io.deckers.blob_courier.BuildConfig.PROMISE_TIMEOUT_MILLISECONDS
 import io.deckers.blob_courier.Fixtures
+import io.deckers.blob_courier.Fixtures.createSparseFile
 import io.deckers.blob_courier.Fixtures.createValidTestFetchParameterMap
+import io.deckers.blob_courier.Fixtures.createValidUploadTestParameterMap
+import io.deckers.blob_courier.Fixtures.runCancelFetchBlobSuspend
+import io.deckers.blob_courier.Fixtures.runCancelUploadBlobSuspend
 import io.deckers.blob_courier.Fixtures.runFetchBlobSuspend
+import io.deckers.blob_courier.TestUtils
 import io.deckers.blob_courier.TestUtils.assertRequestFalse
 import io.deckers.blob_courier.TestUtils.assertRequestTrue
 import io.deckers.blob_courier.TestUtils.circumventHiddenApiExemptionsForMockk
 import io.deckers.blob_courier.TestUtils.runInstrumentedRequestToBoolean
 import io.deckers.blob_courier.common.DOWNLOAD_TYPE_MANAGED
+import io.deckers.blob_courier.common.ERROR_CANCELED_EXCEPTION
 import io.deckers.blob_courier.common.Logger
 import io.deckers.blob_courier.common.MANAGED_DOWNLOAD_SUCCESS
+import io.deckers.blob_courier.common.fold
+import io.deckers.blob_courier.common.ifLeft
 import io.deckers.blob_courier.common.left
 import io.deckers.blob_courier.common.right
 import io.deckers.blob_courier.react.toReactMap
 import io.mockk.every
 import io.mockk.mockkStatic
-import java.util.UUID
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.TimeoutCancellationException
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.withContext
 import kotlinx.coroutines.withTimeout
+import org.junit.Assert
 import org.junit.Before
 import org.junit.Test
+import java.util.UUID
+
 
 private val TAG = BlobCourierInstrumentedModuleTests::class.java.name
 
@@ -194,7 +205,9 @@ class BlobCourierInstrumentedModuleTests {
           val receivedType = result.getString("type") ?: ""
           val check = receivedType == DOWNLOAD_TYPE_MANAGED
 
-          if (check) right(result) else left("Received incorrect type `$receivedType`")
+          if (check)
+            right(result)
+          else left(Fixtures.TestPromiseError(message = "Received incorrect type `$receivedType`"))
         }
     }
 
@@ -221,21 +234,64 @@ class BlobCourierInstrumentedModuleTests {
           val receivedResult = result.getMap("data")?.getString("result") ?: ""
           val check = receivedResult == MANAGED_DOWNLOAD_SUCCESS
 
-          if (check) right(result) else left("Received incorrect result `$receivedResult`")
+          if (check)
+            right(result)
+          else left(Fixtures.TestPromiseError(message = "Received incorrect result `$receivedResult`"))
         }
     }
 
     assertRequestTrue(message, succeeded)
   }
 
+  @Test
+  fun cancel_successful_fetch_request_resolves_promise() = runBlocking {
+    val allRequiredParametersMap =
+      createValidTestFetchParameterMap().plus("url" to Fixtures.LARGE_FILE).toReactMap()
+
+    val ctx = ReactApplicationContext(ApplicationProvider.getApplicationContext())
+
+    val errorOrResult =
+      TestUtils.runRequest(
+        { runCancelFetchBlobSuspend(ctx, allRequiredParametersMap) },
+        ADB_COMMAND_TIMEOUT_MILLISECONDS)
+
+    val isError = errorOrResult.map { false }.ifLeft(true)
+    val code = errorOrResult.fold({ e -> e.code }, { _ -> "INVALID" })
+
+    Assert.assertTrue(isError)
+    Assert.assertEquals(ERROR_CANCELED_EXCEPTION, code)
+  }
+
+  @Test
+  fun cancel_successful_upload_request_resolves_promise() = runBlocking {
+    val file = createSparseFile(100 * 1024 * 1024)
+
+    val taskId = UUID.randomUUID().toString()
+
+    val allRequiredParametersMap =
+      createValidUploadTestParameterMap(taskId, file.absolutePath)
+
+    val ctx = ReactApplicationContext(ApplicationProvider.getApplicationContext())
+
+    val errorOrResult = TestUtils.runRequest(
+      { runCancelUploadBlobSuspend(ctx, allRequiredParametersMap.toReactMap()) },
+      60_000)
+
+    val isError = errorOrResult.map { false }.ifLeft(true)
+    val code = errorOrResult.fold({ e -> e.code }, { _ -> "INVALID" })
+
+    Assert.assertTrue(isError)
+    Assert.assertEquals(ERROR_CANCELED_EXCEPTION, code)
+  }
+
   @Test
   fun uploading_a_file_from_outside_app_data_directory_resolves_promise() = runBlocking {
     val someFileThatIsAlwaysAvailable = "file:///system/etc/fonts.xml"
 
     val ctx = ReactApplicationContext(ApplicationProvider.getApplicationContext())
 
     val uploadParametersMap =
-      Fixtures.createValidUploadTestParameterMap(
+      createValidUploadTestParameterMap(
         UUID.randomUUID().toString(),
         someFileThatIsAlwaysAvailable
       )
@@ -254,8 +310,7 @@ class BlobCourierInstrumentedModuleTests {
     val irrelevantTaskId = UUID.randomUUID().toString()
     val someNonExistentPath = "file:///this/path/does/not/exist.png"
     val allRequiredParametersMap =
-      Fixtures.createValidUploadTestParameterMap(irrelevantTaskId, someNonExistentPath)
-
+      createValidUploadTestParameterMap(irrelevantTaskId, someNonExistentPath)
 
     val ctx = ReactApplicationContext(ApplicationProvider.getApplicationContext())
 

android/src/main/AndroidManifest.xml

@@ -1,7 +1,9 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
-          package="io.deckers.blob_courier">
+  package="io.deckers.blob_courier">
 
   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
 
+  <application android:usesCleartextTraffic="true" />
+
 </manifest>

android/src/main/java/io/deckers/blob_courier/BlobCourierModule.kt

@@ -12,6 +12,8 @@ import com.facebook.react.bridge.ReactContextBaseJavaModule
 import com.facebook.react.bridge.ReactMethod
 import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.modules.network.OkHttpClientProvider
+import io.deckers.blob_courier.cancel.CancellationParameterFactory
+import io.deckers.blob_courier.cancel.RequestCanceller
 import io.deckers.blob_courier.common.DEFAULT_PROGRESS_TIMEOUT_MILLISECONDS
 import io.deckers.blob_courier.common.ERROR_UNEXPECTED_ERROR
 import io.deckers.blob_courier.common.ERROR_UNEXPECTED_EXCEPTION
@@ -51,6 +53,38 @@ class BlobCourierModule(private val reactContext: ReactApplicationContext) :
 
   override fun getName(): String = LIBRARY_NAME
 
+  @ReactMethod
+  fun cancelRequest(input: ReadableMap, promise: Promise) {
+    li("Calling cancelRequest")
+
+    thread {
+      try {
+        val errorOrCancelResult =
+          CancellationParameterFactory()
+            .fromInput(input)
+            .fold(::Failure, ::Success)
+            .map { RequestCanceller(reactContext).cancel(it.taskId) }
+
+        errorOrCancelResult
+          .fmap { Success(emptyMap<String, Any>().toReactMap()) }
+          .`do`(
+            { e ->
+              lv("Something went wrong during cancellation (code=${e.code},message=${e.message})")
+              promise.reject(e.code, e.message)
+            },
+            promise::resolve)
+      } catch (e: Exception) {
+        le("Unexpected exception", e)
+        promise.reject(ERROR_UNEXPECTED_EXCEPTION, processUnexpectedException(e).message)
+      } catch (e: Error) {
+        le("Unexpected error", e)
+        promise.reject(ERROR_UNEXPECTED_ERROR, processUnexpectedError(e).message)
+      }
+    }
+
+    li("Called cancelRequest")
+  }
+
   @ReactMethod
   fun fetchBlob(input: ReadableMap, promise: Promise) {
     li("Calling fetchBlob")
@@ -64,7 +98,7 @@ class BlobCourierModule(private val reactContext: ReactApplicationContext) :
               BlobDownloader(
                 reactContext,
                 createHttpClient(),
-                createProgressFactory(reactContext)
+                createProgressFactory(reactContext),
               )::download
             )
 

android/src/main/java/io/deckers/blob_courier/cancel/CancelController.kt

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) Ely Deckers.
+ *
+ * This source code is licensed under the MPL-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+package io.deckers.blob_courier.cancel
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import androidx.localbroadcastmanager.content.LocalBroadcastManager
+import io.deckers.blob_courier.common.ACTION_CANCEL_REQUEST
+import io.deckers.blob_courier.common.Logger
+import okhttp3.Call
+
+private const val TAG = "CancelController"
+
+private val logger = Logger(TAG)
+private fun lv(m: String, e: Throwable? = null) = logger.v(m, e)
+
+fun registerCancellationHandler(context: Context, taskId: String, call: Call) {
+  lv("Registering $ACTION_CANCEL_REQUEST receiver")
+
+  LocalBroadcastManager.getInstance(context)
+    .registerReceiver(object : BroadcastReceiver() {
+      override fun onReceive(p0: Context?, intent: Intent?) {
+        if (intent?.getStringExtra("taskId") != taskId) {
+          return
+        }
+
+        call.cancel()
+      }
+    }, IntentFilter(ACTION_CANCEL_REQUEST))
+
+  lv("Registered $ACTION_CANCEL_REQUEST receiver")
+}

android/src/main/java/io/deckers/blob_courier/cancel/CancellationParameterFactory.kt

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) Ely Deckers.
+ *
+ * This source code is licensed under the MPL-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+package io.deckers.blob_courier.cancel
+
+import com.facebook.react.bridge.ReadableMap
+import io.deckers.blob_courier.common.PARAMETER_TASK_ID
+import io.deckers.blob_courier.common.PROVIDED_PARAMETERS
+import io.deckers.blob_courier.common.ValidationResult
+import io.deckers.blob_courier.common.ValidationSuccess
+import io.deckers.blob_courier.common.hasRequiredStringField
+import io.deckers.blob_courier.common.isNotNull
+import io.deckers.blob_courier.common.right
+import io.deckers.blob_courier.common.testKeep
+import io.deckers.blob_courier.common.validationContext
+
+data class RequiredParameters(
+  val taskId: String,
+)
+
+data class CancellationParameters(
+  val taskId: String,
+)
+
+private fun verifyRequiredParametersProvided(input: ReadableMap):
+  ValidationResult<RequiredParameters> =
+  validationContext(input, isNotNull(PROVIDED_PARAMETERS))
+    .fmap(testKeep(hasRequiredStringField(PARAMETER_TASK_ID)))
+    .fmap { (_, validatedParameters) ->
+      val (taskId, _) = validatedParameters
+
+      ValidationSuccess(RequiredParameters(taskId))
+    }
+
+class CancellationParameterFactory {
+  fun fromInput(input: ReadableMap): ValidationResult<CancellationParameters> =
+    verifyRequiredParametersProvided(input)
+      .fmap {
+        val (taskId) = it
+
+        right(CancellationParameters(
+          taskId
+        ))
+      }
+}