Merge branch 'develop' into feature/bca/spaces_fix_invites

CHANGES.md

@@ -10,6 +10,7 @@ Improvements 🙌:
 Bugfix 🐛:
  - Space Invite by link not always displayed for public space (#3345)
  - Wrong copy in share space bottom sheet (#3346)
+ - Fix a problem with database migration on nightly builds (#3335)
 
 Translations 🗣:
  -
@@ -24,7 +25,7 @@ Test:
  -
 
 Other changes:
- -
+ - Add documentation on LoginWizard and RegistrationWizard (#3303)
 
 Changes in Element 1.1.7 (2021-05-12)
 ===================================================

matrix-sdk-android/build.gradle

@@ -9,7 +9,7 @@ buildscript {
         mavenCentral()
     }
     dependencies {
-        classpath "io.realm:realm-gradle-plugin:10.4.0"
+        classpath "io.realm:realm-gradle-plugin:10.5.0"
     }
 }
 
@@ -169,7 +169,7 @@ dependencies {
     implementation 'com.otaliastudios:transcoder:0.10.3'
 
     // Phone number https://github.com/google/libphonenumber
-    implementation 'com.googlecode.libphonenumber:libphonenumber:8.12.22'
+    implementation 'com.googlecode.libphonenumber:libphonenumber:8.12.23'
 
     testImplementation 'junit:junit:4.13.2'
     testImplementation 'org.robolectric:robolectric:4.5.1'

matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/AuthenticationService.kt

@@ -51,11 +51,15 @@ interface AuthenticationService {
 
     /**
      * Return a LoginWizard, to login to the homeserver. The login flow has to be retrieved first.
+     *
+     * See [LoginWizard] for more details
      */
     fun getLoginWizard(): LoginWizard
 
     /**
      * Return a RegistrationWizard, to create an matrix account on the homeserver. The login flow has to be retrieved first.
+     *
+     * See [RegistrationWizard] for more details.
      */
     fun getRegistrationWizard(): RegistrationWizard
 

matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/login/LoginWizard.kt

@@ -17,34 +17,46 @@
 package org.matrix.android.sdk.api.auth.login
 
 import org.matrix.android.sdk.api.session.Session
-import org.matrix.android.sdk.api.util.Cancelable
 
+/**
+ * Set of methods to be able to login to an existing account on a homeserver.
+ *
+ * More documentation can be found in the file https://github.com/vector-im/element-android/blob/main/docs/signin.md
+ */
 interface LoginWizard {
-
     /**
-     * @param login the login field
+     * Login to the homeserver.
-     * @param password the password field
+     *
+     * @param login the login field. Can be a user name, or a msisdn (email or phone number) associated to the account
+     * @param password the password of the account
      * @param deviceName the initial device name
-     * @param callback  the matrix callback on which you'll receive the result of authentication.
+     * @return a [Session] if the login is successful
-     * @return a [Cancelable]
      */
     suspend fun login(login: String,
                       password: String,
                       deviceName: String): Session
 
     /**
-     * Exchange a login token to an access token
+     * Exchange a login token to an access token.
+     *
+     * @param loginToken login token, obtain when login has happen in a WebView, using SSO
+     * @return a [Session] if the login is successful
      */
     suspend fun loginWithToken(loginToken: String): Session
 
     /**
-     * Reset user password
+     * Ask the homeserver to reset the user password. The password will not be reset until
+     * [resetPasswordMailConfirmed] is successfully called.
+     *
+     * @param email an email previously associated to the account the user wants the password to be reset.
+     * @param newPassword the desired new password
      */
     suspend fun resetPassword(email: String,
                               newPassword: String)
 
     /**
      * Confirm the new password, once the user has checked their email
+     * When this method succeed, tha account password will be effectively modified.
      */
     suspend fun resetPasswordMailConfirmed()
 }

matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/registration/RegistrationWizard.kt

@@ -16,32 +16,98 @@
 
 package org.matrix.android.sdk.api.auth.registration
 
+/**
+ * Set of methods to be able to create an account on a homeserver.
+ *
+ * Common scenario to register an account successfully:
+ *  - Call [getRegistrationFlow] to check that you application supports all the mandatory registration stages
+ *  - Call [createAccount] to start the account creation
+ *  - Fulfill all mandatory stages using the methods [performReCaptcha] [acceptTerms] [dummy], etc.
+ *
+ * More documentation can be found in the file https://github.com/vector-im/element-android/blob/main/docs/signup.md
+ * and https://matrix.org/docs/spec/client_server/latest#account-registration-and-management
+ */
 interface RegistrationWizard {
-
+    /**
+     * Call this method to get the possible registration flow of the current homeserver.
+     * It can be useful to ensure that your application implementation supports all the stages
+     * required to create an account. If it is not the case, you will have to use the web fallback
+     * to let the user create an account with your application.
+     * See [org.matrix.android.sdk.api.auth.AuthenticationService.getFallbackUrl]
+     */
     suspend fun getRegistrationFlow(): RegistrationResult
 
+    /**
+     * Can be call to check is the desired userName is available for registration on the current homeserver.
+     * It may also fails if the desired userName is not correctly formatted or does not follow any restriction on
+     * the homeserver. Ex: userName with only digits may be rejected.
+     * @param userName the desired username. Ex: "alice"
+     */
+    suspend fun registrationAvailable(userName: String): RegistrationAvailability
+
+    /**
+     * This is the first method to call in order to create an account and start the registration process.
+     *
+     * @param userName the desired username. Ex: "alice"
+     * @param password the desired password
+     * @param initialDeviceDisplayName the device display name
+     */
     suspend fun createAccount(userName: String?,
                               password: String?,
                               initialDeviceDisplayName: String?): RegistrationResult
 
+    /**
+     * Perform the "m.login.recaptcha" stage.
+     *
+     * @param response the response from ReCaptcha
+     */
     suspend fun performReCaptcha(response: String): RegistrationResult
 
+    /**
+     * Perform the "m.login.terms" stage.
+     */
     suspend fun acceptTerms(): RegistrationResult
 
+    /**
+     * Perform the "m.login.dummy" stage.
+     */
     suspend fun dummy(): RegistrationResult
 
+    /**
+     * Perform the "m.login.email.identity" or "m.login.msisdn" stage.
+     *
+     * @param threePid the threePid to add to the account. If this is an email, the homeserver will send an email
+     * to validate it. For a msisdn a SMS will be sent.
+     */
     suspend fun addThreePid(threePid: RegisterThreePid): RegistrationResult
 
+    /**
+     * Ask the homeserver to send again the current threePid (email or msisdn).
+     */
     suspend fun sendAgainThreePid(): RegistrationResult
 
+    /**
+     * Send the code received by SMS to validate a msisdn.
+     * If the code is correct, the registration request will be executed to validate the msisdn.
+     */
     suspend fun handleValidateThreePid(code: String): RegistrationResult
 
+    /**
+     * Useful to poll the homeserver when waiting for the email to be validated by the user.
+     * Once the email is validated, this method will return successfully.
+     * @param delayMillis the SDK can wait before sending the request
+     */
     suspend fun checkIfEmailHasBeenValidated(delayMillis: Long): RegistrationResult
 
-    suspend fun registrationAvailable(userName: String): RegistrationAvailability
+    /**
-
+     * This is the current ThreePid, waiting for validation. The SDK will store it in database, so it can be
+     * restored even if the app has been killed during the registration
+     */
     val currentThreePid: String?
 
-    // True when login and password has been sent with success to the homeserver
+    /**
+     * True when login and password have been sent with success to the homeserver, i.e. [createAccount] has been
+     * called successfully.
+     */
     val isRegistrationStarted: Boolean
 }

matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/session/room/Room.kt

@@ -83,7 +83,7 @@ interface Room :
      * @param beforeLimit how many events before the result are returned.
      * @param afterLimit how many events after the result are returned.
      * @param includeProfile requests that the server returns the historic profile information for the users that sent the events that were returned.
-     * @param callback Callback to get the search result
+     * @return The search result
      */
     suspend fun search(searchTerm: String,
                nextBatch: String?,

matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/database/RealmSessionStoreMigration.kt

@@ -44,7 +44,7 @@ import javax.inject.Inject
 class RealmSessionStoreMigration @Inject constructor() : RealmMigration {
 
     companion object {
-        const val SESSION_STORE_SCHEMA_VERSION = 12L
+        const val SESSION_STORE_SCHEMA_VERSION = 13L
     }
 
     override fun migrate(realm: DynamicRealm, oldVersion: Long, newVersion: Long) {
@@ -62,6 +62,7 @@ class RealmSessionStoreMigration @Inject constructor() : RealmMigration {
         if (oldVersion <= 9) migrateTo10(realm)
         if (oldVersion <= 10) migrateTo11(realm)
         if (oldVersion <= 11) migrateTo12(realm)
+        if (oldVersion <= 12) migrateTo13(realm)
     }
 
     private fun migrateTo1(realm: DynamicRealm) {
@@ -274,4 +275,14 @@ class RealmSessionStoreMigration @Inject constructor() : RealmMigration {
                 ?.addField(SpaceChildSummaryEntityFields.SUGGESTED, Boolean::class.java)
                 ?.setNullable(SpaceChildSummaryEntityFields.SUGGESTED, true)
     }
+
+    private fun migrateTo13(realm: DynamicRealm) {
+        Timber.d("Step 12 -> 13")
+
+        // Fix issue with the nightly build. Eventually play again the migration which has been included in migrateTo12()
+        realm.schema.get("SpaceChildSummaryEntity")
+                ?.takeIf { !it.hasField(SpaceChildSummaryEntityFields.SUGGESTED) }
+                ?.addField(SpaceChildSummaryEntityFields.SUGGESTED, Boolean::class.java)
+                ?.setNullable(SpaceChildSummaryEntityFields.SUGGESTED, true)
+    }
 }

vector/build.gradle

@@ -343,7 +343,7 @@ dependencies {
     implementation 'com.facebook.stetho:stetho:1.6.0'
 
     // Phone number https://github.com/google/libphonenumber
-    implementation 'com.googlecode.libphonenumber:libphonenumber:8.12.22'
+    implementation 'com.googlecode.libphonenumber:libphonenumber:8.12.23'
 
     // rx
     implementation 'io.reactivex.rxjava2:rxkotlin:2.4.0'

vector/src/main/java/im/vector/app/core/utils/ExternalApplicationsUtil.kt

@@ -509,7 +509,7 @@ fun selectTxtFileToWrite(
  * @param sourceFile     the file source path
  * @param dstDirPath     the dst path
  * @param outputFilename optional the output filename
- * @param callback       the asynchronous callback
+ * @return               the created file
  */
 @Suppress("DEPRECATION")
 fun saveFileIntoLegacy(sourceFile: File, dstDirPath: File, outputFilename: String?): File? {