Improve existing APIs

libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/encryption/EncryptionService.kt

@@ -64,16 +64,52 @@ interface EncryptionService {
      */
     suspend fun deviceEd25519(): String?
 
+    /**
+     * Starts the identity reset process. This will return a handle that can be used to reset the identity.
+     */
     suspend fun startIdentityReset(): Result<IdentityResetHandle?>
 }
 
-interface IdentityResetHandle
+/**
+ * A handle to reset the user's identity.
+ */
+interface IdentityResetHandle {
+    /**
+     * Cancel the reset process and drops the existing handle in the SDK.
+     */
+    suspend fun cancel()
+}
 
+/**
+ * A handle to reset the user's identity with a password login type.
+ */
 interface IdentityPasswordResetHandle : IdentityResetHandle {
+    /**
+     * Reset the password of the user.
+     *
+     * This method will block the coroutine it's running on and keep polling indefinitely until either the coroutine is cancelled, the [cancel] method is
+     * called, or the identity is reset.
+     *
+     * @param userId the user id of the user to reset the password for.
+     * @param password the current password, which will be validated before the process takes place.
+     */
     suspend fun resetPassword(userId: UserId, password: String): Result<Unit>
 }
 
+/**
+ * A handle to reset the user's identity with an OIDC login type.
+ */
 interface IdentityOidcResetHandle : IdentityResetHandle {
+    /**
+     * The URL to open in a webview/custom tab to reset the identity.
+     */
     val url: String
+
+    /**
+     * Reset the identity using the OIDC flow.
+     *
+     * This method will block the coroutine it's running on and keep polling indefinitely until either the coroutine is cancelled, the [cancel] method is
+     * called, or the identity is reset.
+     */
     suspend fun resetOidc(): Result<Unit>
 }

libraries/matrix/impl/src/main/kotlin/io/element/android/libraries/matrix/impl/encryption/RustIdentityResetHandle.kt

@@ -42,6 +42,10 @@ class RustPasswordIdentityResetHandle(
     override suspend fun resetPassword(userId: UserId, password: String): Result<Unit> {
         return runCatching { identityResetHandle.reset(AuthData.Password(AuthDataPasswordDetails(userId.value, password))) }
     }
+
+    override suspend fun cancel() {
+        identityResetHandle.cancelAndDestroy()
+    }
 }
 
 class RustOidcIdentityResetHandle(
@@ -51,4 +55,13 @@ class RustOidcIdentityResetHandle(
     override suspend fun resetOidc(): Result<Unit> {
         return runCatching { identityResetHandle.reset(null) }
     }
+
+    override suspend fun cancel() {
+        identityResetHandle.cancelAndDestroy()
+    }
+}
+
+private suspend fun org.matrix.rustcomponents.sdk.IdentityResetHandle.cancelAndDestroy() {
+    cancel()
+    destroy()
 }

libraries/matrix/test/src/main/kotlin/io/element/android/libraries/matrix/test/encryption/FakeIdentityResetHandle.kt

@@ -22,17 +22,27 @@ import io.element.android.libraries.matrix.api.encryption.IdentityPasswordResetH
 
 class FakeIdentityOidcResetHandle(
     override val url: String = "",
-    var resetOidcLambda: () -> Result<Unit> = { error("Not implemented") }
+    var resetOidcLambda: () -> Result<Unit> = { error("Not implemented") },
+    var cancelLambda: () -> Unit = { error("Not implemented") },
 ) : IdentityOidcResetHandle {
     override suspend fun resetOidc(): Result<Unit> {
         return resetOidcLambda()
     }
+
+    override suspend fun cancel() {
+        cancelLambda()
+    }
 }
 
 class FakeIdentityPasswordResetHandle(
-    var resetPasswordLambda: (UserId, String) -> Result<Unit> = { _, _ -> error("Not implemented") }
+    var resetPasswordLambda: (UserId, String) -> Result<Unit> = { _, _ -> error("Not implemented") },
+    var cancelLambda: () -> Unit = { error("Not implemented") },
 ) : IdentityPasswordResetHandle {
     override suspend fun resetPassword(userId: UserId, password: String): Result<Unit> {
         return resetPasswordLambda(userId, password)
     }
+
+    override suspend fun cancel() {
+        cancelLambda()
+    }
 }