Pass error codes on close to Amplify (#106)

Co-authored-by: Thomas Leing <[email protected]>
Co-authored-by: tjroach <[email protected]>

Author: 3 people

gradle/libs.versions.toml

@@ -1,6 +1,6 @@
 [versions]
 agp = "8.1.4"
-amplify = "2.14.5"
+amplify = "2.14.8"
 cameraX = "1.2.0"
 compose = "1.5.4"
 coroutines = "1.7.3"

liveness/src/main/java/com/amplifyframework/ui/liveness/camera/LivenessCoordinator.kt

@@ -44,6 +44,7 @@ import com.amplifyframework.ui.liveness.BuildConfig
 import com.amplifyframework.ui.liveness.model.FaceLivenessDetectionException
 import com.amplifyframework.ui.liveness.model.LivenessCheckState
 import com.amplifyframework.ui.liveness.state.LivenessState
+import com.amplifyframework.ui.liveness.util.WebSocketCloseCode
 import java.util.Date
 import java.util.Timer
 import java.util.concurrent.Executors
@@ -219,7 +220,12 @@ internal class LivenessCoordinator(
         faceLivenessException: FaceLivenessDetectionException,
         stopLivenessSession: Boolean
     ) {
-        livenessState.onError(stopLivenessSession)
+        val webSocketCloseCode = when (faceLivenessException) {
+            is FaceLivenessDetectionException.UserCancelledException -> WebSocketCloseCode.CANCELED
+            is FaceLivenessDetectionException.FaceInOvalMatchExceededTimeLimitException -> WebSocketCloseCode.TIMEOUT
+            else -> WebSocketCloseCode.RUNTIME_ERROR
+        }
+        livenessState.onError(stopLivenessSession, webSocketCloseCode)
         unbindCamera(context)
         onChallengeFailed.accept(faceLivenessException)
     }
@@ -270,12 +276,17 @@ internal class LivenessCoordinator(
         }
     }
 
+    /**
+     * This is only called when onDispose is triggered from FaceLivenessDetector view.
+     * If we begin calling destroy in other places, we should ensure we are still tracking the proper error code.
+     */
     fun destroy(context: Context) {
         // Destroy all resources so a new coordinator can safely be created
         encoder.stop {
             encoder.destroy()
         }
-        livenessState.onDestroy(true)
+        val webSocketCloseCode = if (!disconnectEventReceived) WebSocketCloseCode.DISPOSED else null
+        livenessState.onDestroy(true, webSocketCloseCode)
         unbindCamera(context)
         analysisExecutor.shutdown()
     }

liveness/src/main/java/com/amplifyframework/ui/liveness/model/FaceLivenessDetectionException.kt

@@ -50,4 +50,11 @@ open class FaceLivenessDetectionException(
         recoverySuggestion: String = "Retry the face liveness check.",
         throwable: Throwable? = null
     ) : FaceLivenessDetectionException(message, recoverySuggestion, throwable)
+
+    /**
+     * This is not an error we have determined to publicly expose.
+     * The error will come to the customer in onError, but only instance checked as FaceLivenessDetectionException.
+     */
+    internal class FaceInOvalMatchExceededTimeLimitException :
+        FaceLivenessDetectionException("Face did not match oval within time limit.")
 }

liveness/src/main/java/com/amplifyframework/ui/liveness/state/LivenessState.kt

@@ -34,6 +34,7 @@ import com.amplifyframework.ui.liveness.ml.FaceOval
 import com.amplifyframework.ui.liveness.model.FaceLivenessDetectionException
 import com.amplifyframework.ui.liveness.model.LivenessCheckState
 import com.amplifyframework.ui.liveness.ui.helper.VideoViewportSize
+import com.amplifyframework.ui.liveness.util.WebSocketCloseCode
 import java.util.Date
 import java.util.Timer
 import java.util.TimerTask
@@ -87,19 +88,21 @@ internal data class LivenessState(
         }
     }
 
-    fun onError(stopLivenessSession: Boolean) {
+    fun onError(stopLivenessSession: Boolean, webSocketCloseCode: WebSocketCloseCode) {
         livenessCheckState.value = LivenessCheckState.Error
-        onDestroy(stopLivenessSession)
+        onDestroy(stopLivenessSession, webSocketCloseCode)
     }
 
-    // Cleans up state when challenge is completed or cancelled
-    fun onDestroy(stopLivenessSession: Boolean) {
+    // Cleans up state when challenge is completed or cancelled.
+    // We only send webSocketCloseCode if error encountered.
+    fun onDestroy(stopLivenessSession: Boolean, webSocketCloseCode: WebSocketCloseCode? = null) {
+        livenessCheckState.value = LivenessCheckState.Error
         faceOvalMatchTimer?.cancel()
         readyForOval = false
         faceGuideRect = null
         runningFreshness = false
         if (stopLivenessSession) {
-            livenessSessionInfo?.stopSession()
+            livenessSessionInfo?.stopSession(webSocketCloseCode?.code)
         }
     }
 
@@ -300,9 +303,7 @@ internal data class LivenessState(
                         if (!detectedFaceMatchedOval && faceGuideRect != null) {
                             readyForOval = false
                             val timeoutError =
-                                FaceLivenessDetectionException(
-                                    "Face did not match oval within time limit."
-                                )
+                                FaceLivenessDetectionException.FaceInOvalMatchExceededTimeLimitException()
                             onSessionError(timeoutError, true)
                         }
                         cancel()

liveness/src/main/java/com/amplifyframework/ui/liveness/util/WebSocketCloseCode.kt

@@ -0,0 +1,8 @@
+package com.amplifyframework.ui.liveness.util
+
+internal enum class WebSocketCloseCode(val code: Int) {
+    TIMEOUT(4001),
+    CANCELED(4003),
+    RUNTIME_ERROR(4005),
+    DISPOSED(4008)
+}

liveness/src/test/java/com/amplifyframework/ui/liveness/state/LivenessStateTest.kt

@@ -28,6 +28,7 @@ import com.amplifyframework.predictions.models.VideoEvent
 import com.amplifyframework.ui.liveness.ml.FaceDetector
 import com.amplifyframework.ui.liveness.model.FaceLivenessDetectionException
 import com.amplifyframework.ui.liveness.model.LivenessCheckState
+import com.amplifyframework.ui.liveness.util.WebSocketCloseCode
 import io.mockk.mockk
 import io.mockk.verify
 import org.junit.Assert.assertEquals
@@ -131,26 +132,44 @@ internal class LivenessStateTest {
 
     @Test
     fun `state is error after on error`() {
-        livenessState.onError(true)
+        livenessState.onError(true, WebSocketCloseCode.RUNTIME_ERROR)
         assertTrue(livenessState.livenessCheckState.value is LivenessCheckState.Error)
     }
 
     @Test
     fun `session is stopped when stopLivenessSession is true and error occurs`() {
         val challenges = mockk<List<FaceLivenessSessionChallenge>>(relaxed = true)
-        val stopSession = mockk<() -> Unit>(relaxed = true)
+        val stopSession = mockk<(Int?) -> Unit>(relaxed = true)
         livenessState.livenessSessionInfo = FaceLivenessSession(challenges, { }, { }, stopSession)
-        livenessState.onError(true)
-        verify(exactly = 1) { stopSession() }
+        livenessState.onError(true, WebSocketCloseCode.RUNTIME_ERROR)
+        verify(exactly = 1) { stopSession(WebSocketCloseCode.RUNTIME_ERROR.code) }
+    }
+
+    @Test
+    fun `proper code is sent when provided in onDestroy`() {
+        val challenges = mockk<List<FaceLivenessSessionChallenge>>(relaxed = true)
+        val stopSession = mockk<(Int?) -> Unit>(relaxed = true)
+        livenessState.livenessSessionInfo = FaceLivenessSession(challenges, { }, { }, stopSession)
+        livenessState.onDestroy(true, WebSocketCloseCode.DISPOSED)
+        verify(exactly = 1) { stopSession(WebSocketCloseCode.DISPOSED.code) }
+    }
+
+    @Test
+    fun `null close code is sent when no close code provided in onDestroy`() {
+        val challenges = mockk<List<FaceLivenessSessionChallenge>>(relaxed = true)
+        val stopSession = mockk<(Int?) -> Unit>(relaxed = true)
+        livenessState.livenessSessionInfo = FaceLivenessSession(challenges, { }, { }, stopSession)
+        livenessState.onDestroy(true, null)
+        verify(exactly = 1) { stopSession(null) }
     }
 
     @Test
     fun `session is not stopped when stopLivenessSession is false and error occurs`() {
         val challenges = mockk<List<FaceLivenessSessionChallenge>>(relaxed = true)
-        val stopSession = mockk<() -> Unit>(relaxed = true)
+        val stopSession = mockk<(Int?) -> Unit>(relaxed = true)
         livenessState.livenessSessionInfo = FaceLivenessSession(challenges, { }, { }, stopSession)
-        livenessState.onError(false)
-        verify(exactly = 0) { stopSession() }
+        livenessState.onError(false, WebSocketCloseCode.RUNTIME_ERROR)
+        verify(exactly = 0) { stopSession(any()) }
     }
 
     @Test
@@ -205,7 +224,7 @@ internal class LivenessStateTest {
     @Test
     fun `state is error after freshness completes and an error occurs`() {
         livenessState.faceGuideRect = mockk(relaxed = true)
-        livenessState.onError(false)
+        livenessState.onError(false, WebSocketCloseCode.RUNTIME_ERROR)
         livenessState.onFreshnessComplete()
         assertTrue(livenessState.livenessCheckState.value is LivenessCheckState.Error)
     }