From c6af196bf0ca6008e9c0a0f750b902791b265a40 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Fri, 14 Aug 2026 09:50:08 +0200 Subject: [PATCH] Add KDoc to the `libraries/wellknown` API interfaces Document WellknownRetriever, ElementWellknownStore, ElementWellKnownParser and their factories, along with every member. The caching semantics are the part callers need and cannot see in the signatures, so they are recorded here: the store reports entries older than a day as outdated rather than missing, the retriever returns such a value immediately and refreshes in the background, an enterprise build with a hardcoded configuration short-circuits entirely, and the parser ignores unknown JSON fields. Co-Authored-By: Claude Opus 5 (1M context) --- .../wellknown/api/ElementWellKnownParser.kt | 8 +++++ .../wellknown/api/ElementWellknownStore.kt | 29 +++++++++++++++++++ .../wellknown/api/WellknownRetriever.kt | 17 +++++++++++ 3 files changed, 54 insertions(+) diff --git a/libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/ElementWellKnownParser.kt b/libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/ElementWellKnownParser.kt index db0a323a5f..1466a5b422 100644 --- a/libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/ElementWellKnownParser.kt +++ b/libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/ElementWellKnownParser.kt @@ -7,6 +7,14 @@ package io.element.android.libraries.wellknown.api +/** + * Parses the raw JSON of an Element `.well-known` document. + */ fun interface ElementWellKnownParser { + /** + * Parses the document, failing when it is not valid JSON; unknown fields are ignored so a newer server does not break an older client. + * + * @param json the raw document as served by the server. + */ fun parse(json: String): Result } diff --git a/libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/ElementWellknownStore.kt b/libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/ElementWellknownStore.kt index abb1cf53c7..93256fa6f1 100644 --- a/libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/ElementWellknownStore.kt +++ b/libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/ElementWellknownStore.kt @@ -7,12 +7,41 @@ package io.element.android.libraries.wellknown.api +/** + * On-disk cache of the Element `.well-known` documents already fetched, so the app has a configuration to work with while offline. + */ interface ElementWellknownStore { + /** + * Reads the cached document of a domain. + * Entries older than a day are reported as outdated rather than missing, so the caller can use them while refreshing; + * a document that no longer parses is reported as an error. + * + * @param domain the server whose cached document is requested. + */ suspend fun get(domain: String): WellknownRetrieverResult + + /** + * Stores the document of a domain and stamps it as fetched now, replacing any previous entry. + * + * @param domain the server the document belongs to. + * @param wellknown the raw document, stored as-is rather than parsed. + */ suspend fun update(domain: String, wellknown: String): Result + + /** + * Removes the cached document of a domain, used when the stored value turns out to be unusable. + * + * @param domain the server whose entry is removed. + */ suspend fun delete(domain: String): Result + /** + * Creates a store, one per configuration source so that their entries never collide. + */ fun interface Factory { + /** + * @param prefix namespaces the cache keys, or `null` for the default well-known endpoint. + */ fun create(prefix: String?): ElementWellknownStore } } diff --git a/libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/WellknownRetriever.kt b/libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/WellknownRetriever.kt index 56d251426a..9e265bc213 100644 --- a/libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/WellknownRetriever.kt +++ b/libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/WellknownRetriever.kt @@ -10,13 +10,30 @@ package io.element.android.libraries.wellknown.api import io.element.android.libraries.matrix.api.UrlContentFetcher +/** + * Retrieves the Element specific `.well-known` configuration of a server, which is how a deployment advertises its own settings. + */ interface WellknownRetriever { + /** + * Returns the configuration of a host, served from the local cache when possible. + * A cached value that has gone stale is returned as outdated while a refresh runs in the background, so this rarely waits on the network. + * An enterprise build with a hardcoded configuration always short-circuits and returns that instead. + * + * @param host the server to look up; a full URL is accepted and reduced to its host. + * @param source which endpoint to read the configuration from, which also selects the cache it is stored in. + */ suspend fun getElementWellKnown( host: String, source: EnterpriseRemoteConfigSource ): WellknownRetrieverResult + /** + * Creates a retriever, which needs a fetcher because the configuration is read over HTTP. + */ interface Factory { + /** + * @param urlContentFetcher used to perform the request; a client that is not authenticated yet also works. + */ fun create(urlContentFetcher: UrlContentFetcher): WellknownRetriever } }