First Commit

libraries/wellknown/api/build.gradle.kts

@@ -0,0 +1,14 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+plugins {
+    id("io.element.android-library")
+}
+
+android {
+    namespace = "io.element.android.libraries.wellknown.api"
+}

libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/ElementWellKnown.kt

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.wellknown.api
+
+data class ElementWellKnown(
+    val registrationHelperUrl: String?,
+    val enforceElementPro: Boolean?,
+    val rageshakeUrl: String?,
+    val brandColor: String?,
+)

libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/SessionWellknownRetriever.kt

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.wellknown.api
+
+interface SessionWellknownRetriever {
+    suspend fun getElementWellKnown(): WellknownRetrieverResult<ElementWellKnown>
+}

libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/WellknownRetriever.kt

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.wellknown.api
+
+interface WellknownRetriever {
+    suspend fun getElementWellKnown(baseUrl: String): WellknownRetrieverResult<ElementWellKnown>
+}

libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/WellknownRetrieverResult.kt

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.wellknown.api
+
+sealed interface WellknownRetrieverResult<out T> {
+    /**
+     * Well-known data has been successfully retrieved.
+     */
+    data class Success<out T>(val data: T) : WellknownRetrieverResult<T>
+
+    /**
+     * Well-known data is not found (file does not exist server side, we got a 404).
+     */
+    data object NotFound : WellknownRetrieverResult<Nothing>
+
+    /**
+     * Any other error.
+     */
+    data class Error(val exception: Exception) : WellknownRetrieverResult<Nothing>
+
+    fun dataOrNull(): T? = when (this) {
+        is Success<T> -> data
+        is Error -> null
+        NotFound -> null
+    }
+}

libraries/wellknown/impl/build.gradle.kts

@@ -0,0 +1,41 @@
+import extension.setupDependencyInjection
+import extension.testCommonDependencies
+
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+plugins {
+    id("io.element.android-library")
+    id("kotlin-parcelize")
+    alias(libs.plugins.kotlin.serialization)
+}
+
+android {
+    namespace = "io.element.android.libraries.wellknown.impl"
+}
+
+setupDependencyInjection()
+
+dependencies {
+    api(projects.libraries.wellknown.api)
+    implementation(libs.androidx.annotationjvm)
+    implementation(libs.coroutines.core)
+    implementation(platform(libs.network.retrofit.bom))
+    implementation(libs.network.retrofit)
+    implementation(libs.serialization.json)
+    implementation(projects.libraries.core)
+    implementation(projects.libraries.androidutils)
+    implementation(projects.libraries.architecture)
+    implementation(projects.libraries.matrix.api)
+    implementation(projects.libraries.network)
+
+    testCommonDependencies(libs)
+    testImplementation(libs.coroutines.core)
+    testImplementation(projects.libraries.matrix.test)
+    testImplementation(projects.services.toolbox.test)
+}

libraries/wellknown/impl/src/main/kotlin/io/element/android/libraries/wellknown/impl/DefaultSessionWellknownRetriever.kt

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.wellknown.impl
+
+import dev.zacsweers.metro.ContributesBinding
+import io.element.android.libraries.androidutils.json.JsonProvider
+import io.element.android.libraries.core.extensions.mapCatchingExceptions
+import io.element.android.libraries.di.SessionScope
+import io.element.android.libraries.matrix.api.MatrixClient
+import io.element.android.libraries.matrix.api.exception.ClientException
+import io.element.android.libraries.wellknown.api.ElementWellKnown
+import io.element.android.libraries.wellknown.api.SessionWellknownRetriever
+import io.element.android.libraries.wellknown.api.WellknownRetrieverResult
+import timber.log.Timber
+
+@ContributesBinding(SessionScope::class)
+class DefaultSessionWellknownRetriever(
+    private val matrixClient: MatrixClient,
+    private val json: JsonProvider,
+) : SessionWellknownRetriever {
+    private val domain by lazy { matrixClient.userIdServerName() }
+
+    override suspend fun getElementWellKnown(): WellknownRetrieverResult<ElementWellKnown> {
+        val url = "https://$domain/.well-known/element/element.json"
+        return matrixClient
+            .getUrl(url)
+            .mapCatchingExceptions {
+                val data = String(it)
+                json().decodeFromString<InternalElementWellKnown>(data).map()
+            }
+            .toWellknownRetrieverResult()
+    }
+
+    private fun <T> Result<T>.toWellknownRetrieverResult(): WellknownRetrieverResult<T> = fold(
+        onSuccess = {
+            WellknownRetrieverResult.Success(it)
+        },
+        onFailure = {
+            Timber.e(it, "Failed to retrieve Element .well-known from $domain")
+            // This check on message value is not ideal but this is what we got from the SDK.
+            if ((it as? ClientException.Generic)?.message?.contains("404") == true) {
+                WellknownRetrieverResult.NotFound
+            } else {
+                WellknownRetrieverResult.Error(it as Exception)
+            }
+        }
+    )
+}

libraries/wellknown/impl/src/main/kotlin/io/element/android/libraries/wellknown/impl/DefaultWellknownRetriever.kt

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.wellknown.impl
+
+import dev.zacsweers.metro.AppScope
+import dev.zacsweers.metro.ContributesBinding
+import io.element.android.libraries.core.extensions.runCatchingExceptions
+import io.element.android.libraries.core.uri.ensureProtocol
+import io.element.android.libraries.network.RetrofitFactory
+import io.element.android.libraries.wellknown.api.ElementWellKnown
+import io.element.android.libraries.wellknown.api.WellknownRetriever
+import io.element.android.libraries.wellknown.api.WellknownRetrieverResult
+import retrofit2.HttpException
+import timber.log.Timber
+import java.net.HttpURLConnection
+
+@ContributesBinding(AppScope::class)
+class DefaultWellknownRetriever(
+    private val retrofitFactory: RetrofitFactory,
+) : WellknownRetriever {
+    override suspend fun getElementWellKnown(baseUrl: String): WellknownRetrieverResult<ElementWellKnown> {
+        return buildWellknownApi(baseUrl)
+            .map { wellknownApi ->
+                try {
+                    val result = wellknownApi.getElementWellKnown().map()
+                    WellknownRetrieverResult.Success(result)
+                } catch (e: Exception) {
+                    // Is it a 404?
+                    Timber.e(e, "Failed to retrieve Element well-known data for $baseUrl")
+                    if ((e as? HttpException)?.code() == HttpURLConnection.HTTP_NOT_FOUND) {
+                        WellknownRetrieverResult.NotFound
+                    } else {
+                        WellknownRetrieverResult.Error(e)
+                    }
+                }
+            }
+            .fold(
+                onSuccess = { it },
+                onFailure = { WellknownRetrieverResult.Error(it as Exception) }
+            )
+    }
+
+    private fun buildWellknownApi(accountProviderUrl: String): Result<WellknownAPI> {
+        return runCatchingExceptions {
+            retrofitFactory.create(accountProviderUrl.ensureProtocol())
+                .create(WellknownAPI::class.java)
+        }.onFailure { e ->
+            // If the base URL is not valid, we cannot retrieve the well-known data
+            Timber.e(e, "Failed to create Retrofit instance for $accountProviderUrl")
+        }
+    }
+}

libraries/wellknown/impl/src/main/kotlin/io/element/android/libraries/wellknown/impl/InternalElementWellKnown.kt

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.wellknown.impl
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+/**
+ * Example:
+ * <pre>
+ * {
+ *     "registration_helper_url": "https://element.io"
+ * }
+ * </pre>
+ * .
+ */
+@Serializable
+data class InternalElementWellKnown(
+    @SerialName("registration_helper_url")
+    val registrationHelperUrl: String? = null,
+    @SerialName("enforce_element_pro")
+    val enforceElementPro: Boolean? = null,
+    @SerialName("rageshake_url")
+    val rageshakeUrl: String? = null,
+    @SerialName("brand_color")
+    val brandColor: String? = null,
+)

libraries/wellknown/impl/src/main/kotlin/io/element/android/libraries/wellknown/impl/InternalWellKnown.kt

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.wellknown.impl
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+/**
+ * https://matrix.org/docs/spec/client_server/r0.4.0.html#server-discovery
+ * <pre>
+ * {
+ *     "m.homeserver": {
+ *         "base_url": "https://matrix.org"
+ *     },
+ *     "m.identity_server": {
+ *         "base_url": "https://vector.im"
+ *     },
+ * }
+ * </pre>
+ * .
+ */
+@Serializable
+data class InternalWellKnown(
+    @SerialName("m.homeserver")
+    val homeServer: InternalWellKnownBaseConfig? = null,
+    @SerialName("m.identity_server")
+    val identityServer: InternalWellKnownBaseConfig? = null,
+)

libraries/wellknown/impl/src/main/kotlin/io/element/android/libraries/wellknown/impl/InternalWellKnownBaseConfig.kt

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.wellknown.impl
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+/**
+ * https://matrix.org/docs/spec/client_server/r0.4.0.html#server-discovery
+ * <pre>
+ * {
+ *     "base_url": "https://element.io"
+ * }
+ * </pre>
+ * .
+ */
+@Serializable
+data class InternalWellKnownBaseConfig(
+    @SerialName("base_url")
+    val baseURL: String? = null
+)

libraries/wellknown/impl/src/main/kotlin/io/element/android/libraries/wellknown/impl/Mapper.kt

@@ -0,0 +1,18 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.wellknown.impl
+
+import io.element.android.libraries.wellknown.api.ElementWellKnown
+
+internal fun InternalElementWellKnown.map() = ElementWellKnown(
+    registrationHelperUrl = registrationHelperUrl,
+    enforceElementPro = enforceElementPro,
+    rageshakeUrl = rageshakeUrl,
+    brandColor = brandColor,
+)

libraries/wellknown/impl/src/main/kotlin/io/element/android/libraries/wellknown/impl/WellknownAPI.kt

@@ -0,0 +1,19 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.wellknown.impl
+
+import retrofit2.http.GET
+
+internal interface WellknownAPI {
+    @GET(".well-known/matrix/client")
+    suspend fun getWellKnown(): InternalWellKnown
+
+    @GET(".well-known/element/element.json")
+    suspend fun getElementWellKnown(): InternalElementWellKnown
+}

libraries/wellknown/impl/src/test/kotlin/io/element/android/libraries/wellknown/impl/DefaultSessionWellknownRetrieverTest.kt

@@ -0,0 +1,131 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.wellknown.impl
+
+import com.google.common.truth.Truth.assertThat
+import io.element.android.libraries.androidutils.json.DefaultJsonProvider
+import io.element.android.libraries.matrix.test.AN_EXCEPTION
+import io.element.android.libraries.matrix.test.FakeMatrixClient
+import io.element.android.libraries.wellknown.api.ElementWellKnown
+import io.element.android.libraries.wellknown.api.WellknownRetrieverResult
+import io.element.android.tests.testutils.lambda.lambdaRecorder
+import io.element.android.tests.testutils.lambda.value
+import kotlinx.coroutines.test.runTest
+import org.junit.Test
+
+class DefaultSessionWellknownRetrieverTest {
+    @Test
+    fun `get empty element wellknown`() = runTest {
+        val getUrlLambda = lambdaRecorder<String, Result<ByteArray>> {
+            Result.success("{}".toByteArray())
+        }
+        val sut = createDefaultSessionWellknownRetriever(
+            getUrlLambda = getUrlLambda,
+        )
+        assertThat(sut.getElementWellKnown()).isEqualTo(
+            WellknownRetrieverResult.Success(
+                ElementWellKnown(
+                    registrationHelperUrl = null,
+                    enforceElementPro = null,
+                    rageshakeUrl = null,
+                    brandColor = null,
+                )
+            )
+        )
+        getUrlLambda.assertions().isCalledOnce()
+            .with(value("https://user.domain.org/.well-known/element/element.json"))
+    }
+
+    @Test
+    fun `get element wellknown with full content`() = runTest {
+        val sut = createDefaultSessionWellknownRetriever(
+            getUrlLambda = {
+                Result.success(
+                    """{
+                    "registration_helper_url": "a_registration_url",
+                    "enforce_element_pro": true,
+                    "rageshake_url": "a_rageshake_url",
+                    "brand_color": "#FF0000"
+                }""".trimIndent().toByteArray()
+                )
+            }
+        )
+        assertThat(sut.getElementWellKnown()).isEqualTo(
+            WellknownRetrieverResult.Success(
+                ElementWellKnown(
+                    registrationHelperUrl = "a_registration_url",
+                    enforceElementPro = true,
+                    rageshakeUrl = "a_rageshake_url",
+                    brandColor = "#FF0000",
+                )
+            )
+        )
+    }
+
+    @Test
+    fun `get element wellknown with unknown key`() = runTest {
+        val sut = createDefaultSessionWellknownRetriever(
+            getUrlLambda = {
+                Result.success(
+                    """{
+                    "registration_helper_url": "a_registration_url",
+                    "enforce_element_pro": true,
+                    "rageshake_url": "a_rageshake_url",
+                    "other": true
+                }""".trimIndent().toByteArray()
+                )
+            },
+        )
+        assertThat(sut.getElementWellKnown()).isEqualTo(
+            WellknownRetrieverResult.Success(
+                ElementWellKnown(
+                    registrationHelperUrl = "a_registration_url",
+                    enforceElementPro = true,
+                    rageshakeUrl = "a_rageshake_url",
+                    brandColor = null,
+                )
+            )
+        )
+    }
+
+    @Test
+    fun `get element wellknown json error`() = runTest {
+        val sut = createDefaultSessionWellknownRetriever(
+            getUrlLambda = {
+                Result.success(
+                    """{
+                    "registration_helper_url" = "a_registration_url",
+                    error
+                }""".trimIndent().toByteArray()
+                )
+            }
+        )
+        assertThat(sut.getElementWellKnown()).isInstanceOf(WellknownRetrieverResult.Error::class.java)
+    }
+
+    @Test
+    fun `get element wellknown network error`() = runTest {
+        val sut = createDefaultSessionWellknownRetriever(
+            getUrlLambda = {
+                Result.failure(AN_EXCEPTION)
+            }
+        )
+        assertThat(sut.getElementWellKnown()).isInstanceOf(WellknownRetrieverResult.Error::class.java)
+    }
+
+    private fun createDefaultSessionWellknownRetriever(
+        getUrlLambda: (String) -> Result<ByteArray>,
+    ) = DefaultSessionWellknownRetriever(
+        matrixClient = FakeMatrixClient(
+            userIdServerNameLambda = { "user.domain.org" },
+            getUrlLambda = getUrlLambda,
+        ),
+        json = DefaultJsonProvider(),
+    )
+}

libraries/wellknown/test/build.gradle.kts

@@ -0,0 +1,20 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+plugins {
+    id("io.element.android-library")
+}
+
+android {
+    namespace = "io.element.android.features.wellknown.test"
+}
+
+dependencies {
+    implementation(projects.libraries.wellknown.api)
+    implementation(projects.tests.testutils)
+}

libraries/wellknown/test/src/main/kotlin/io/element/android/features/wellknown/test/FakeSessionWellknownRetriever.kt

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.features.wellknown.test
+
+import io.element.android.libraries.wellknown.api.ElementWellKnown
+import io.element.android.libraries.wellknown.api.SessionWellknownRetriever
+import io.element.android.libraries.wellknown.api.WellknownRetrieverResult
+import io.element.android.tests.testutils.simulateLongTask
+
+class FakeSessionWellknownRetriever(
+    private val getElementWellKnownResult: () -> WellknownRetrieverResult<ElementWellKnown> = { WellknownRetrieverResult.NotFound },
+) : SessionWellknownRetriever {
+    override suspend fun getElementWellKnown(): WellknownRetrieverResult<ElementWellKnown> = simulateLongTask {
+        getElementWellKnownResult()
+    }
+}

libraries/wellknown/test/src/main/kotlin/io/element/android/features/wellknown/test/FakeWellknownRetriever.kt

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.features.wellknown.test
+
+import io.element.android.libraries.wellknown.api.ElementWellKnown
+import io.element.android.libraries.wellknown.api.WellknownRetriever
+import io.element.android.libraries.wellknown.api.WellknownRetrieverResult
+import io.element.android.tests.testutils.simulateLongTask
+
+class FakeWellknownRetriever(
+    private val getElementWellKnownResult: (String) -> WellknownRetrieverResult<ElementWellKnown> = { WellknownRetrieverResult.NotFound },
+) : WellknownRetriever {
+    override suspend fun getElementWellKnown(baseUrl: String): WellknownRetrieverResult<ElementWellKnown> = simulateLongTask {
+        getElementWellKnownResult(baseUrl)
+    }
+}

libraries/wellknown/test/src/main/kotlin/io/element/android/features/wellknown/test/Fixtures.kt

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.features.wellknown.test
+
+import io.element.android.libraries.wellknown.api.ElementWellKnown
+
+fun anElementWellKnown(
+    registrationHelperUrl: String? = null,
+    enforceElementPro: Boolean? = null,
+    rageshakeUrl: String? = null,
+    brandColor: String? = null,
+) = ElementWellKnown(
+    registrationHelperUrl = registrationHelperUrl,
+    enforceElementPro = enforceElementPro,
+    rageshakeUrl = rageshakeUrl,
+    brandColor = brandColor,
+)