From b08f10a98fab0374605e7c87386a889bc291cb1e Mon Sep 17 00:00:00 2001 From: Ricki Hirner Date: Mon, 1 Dec 2025 11:54:36 +0100 Subject: [PATCH] `HttpClientBuilder`: clarify documentation for `authDomain` (#1857) * Update authentication domain parameter - Rename `onlyHost` to `authDomain` in `fromAccount` - Update `authenticate` method to use `domain` instead of `host` - Clarify documentation for `authDomain` parameter * More KDoc * Fix other calls / tests --- .../servicedetection/DavResourceFinderTest.kt | 2 +- .../davdroid/network/HttpClientBuilder.kt | 18 +++++++++++------- .../servicedetection/DavResourceFinder.kt | 2 +- .../davdroid/sync/ResourceDownloader.kt | 2 +- .../davdroid/webdav/DavHttpClientBuilder.kt | 5 ++++- .../davdroid/webdav/WebDavMountRepository.kt | 2 +- 6 files changed, 19 insertions(+), 12 deletions(-) diff --git a/app/src/androidTest/kotlin/at/bitfire/davdroid/servicedetection/DavResourceFinderTest.kt b/app/src/androidTest/kotlin/at/bitfire/davdroid/servicedetection/DavResourceFinderTest.kt index 20d31ab4a..76f2dee15 100644 --- a/app/src/androidTest/kotlin/at/bitfire/davdroid/servicedetection/DavResourceFinderTest.kt +++ b/app/src/androidTest/kotlin/at/bitfire/davdroid/servicedetection/DavResourceFinderTest.kt @@ -74,7 +74,7 @@ class DavResourceFinderTest { val credentials = Credentials(username = "mock", password = "12345".toSensitiveString()) client = httpClientBuilder - .authenticate(host = null, getCredentials = { credentials }) + .authenticate(domain = null, getCredentials = { credentials }) .build() Assume.assumeTrue(NetworkSecurityPolicy.getInstance().isCleartextTrafficPermitted) diff --git a/app/src/main/kotlin/at/bitfire/davdroid/network/HttpClientBuilder.kt b/app/src/main/kotlin/at/bitfire/davdroid/network/HttpClientBuilder.kt index 87bd93a2e..e233683a9 100644 --- a/app/src/main/kotlin/at/bitfire/davdroid/network/HttpClientBuilder.kt +++ b/app/src/main/kotlin/at/bitfire/davdroid/network/HttpClientBuilder.kt @@ -49,7 +49,7 @@ import javax.net.ssl.TrustManagerFactory import javax.net.ssl.X509TrustManager /** - * Builder for the [OkHttpClient]. + * Builder for the HTTP client. * * **Attention:** If the builder is injected, it shouldn't be used from multiple locations to generate different clients because then * there's only one [HttpClientBuilder] object and setting properties from one location would influence the others. @@ -105,7 +105,7 @@ class HttpClientBuilder @Inject constructor( private var authenticator: Authenticator? = null private var certificateAlias: String? = null - fun authenticate(host: String?, getCredentials: () -> Credentials, updateAuthState: ((AuthState) -> Unit)? = null): HttpClientBuilder { + fun authenticate(domain: String?, getCredentials: () -> Credentials, updateAuthState: ((AuthState) -> Unit)? = null): HttpClientBuilder { val credentials = getCredentials() if (credentials.authState != null) { // OAuth @@ -124,7 +124,7 @@ class HttpClientBuilder @Inject constructor( } else if (credentials.username != null && credentials.password != null) { // basic/digest auth val authHandler = BasicDigestAuthHandler( - domain = UrlUtils.hostToDomain(host), + domain = domain, username = credentials.username, password = credentials.password.asCharArray(), insecurePreemptive = true @@ -155,16 +155,20 @@ class HttpClientBuilder @Inject constructor( * * **Must not be run on main thread, because it creates [AccountSettings]!** Use [fromAccountAsync] if possible. * - * @param account the account to take authentication from - * @param onlyHost if set: only authenticate for this host name + * @param account the account to take authentication from + * @param authDomain (optional) Send credentials only for the hosts of the given domain. Can be: + * + * - a full host name (`caldav.example.com`): then credentials are only sent for the domain of that host name (`example.com`), or + * - a domain name (`example.com`): then credentials are only sent for the given domain, or + * - or _null_: then credentials are always sent, regardless of the resource host name. * * @throws at.bitfire.davdroid.sync.account.InvalidAccountException when the account doesn't exist */ @WorkerThread - fun fromAccount(account: Account, onlyHost: String? = null): HttpClientBuilder { + fun fromAccount(account: Account, authDomain: String? = null): HttpClientBuilder { val accountSettings = accountSettingsFactory.create(account) authenticate( - host = onlyHost, + domain = UrlUtils.hostToDomain(authDomain), getCredentials = { accountSettings.credentials() }, diff --git a/app/src/main/kotlin/at/bitfire/davdroid/servicedetection/DavResourceFinder.kt b/app/src/main/kotlin/at/bitfire/davdroid/servicedetection/DavResourceFinder.kt index b3e2298d1..3f1177605 100644 --- a/app/src/main/kotlin/at/bitfire/davdroid/servicedetection/DavResourceFinder.kt +++ b/app/src/main/kotlin/at/bitfire/davdroid/servicedetection/DavResourceFinder.kt @@ -83,7 +83,7 @@ class DavResourceFinder @AssistedInject constructor( .apply { if (credentials != null) authenticate( - host = null, + domain = null, getCredentials = { credentials } ) } diff --git a/app/src/main/kotlin/at/bitfire/davdroid/sync/ResourceDownloader.kt b/app/src/main/kotlin/at/bitfire/davdroid/sync/ResourceDownloader.kt index 5d680beb3..6706fced5 100644 --- a/app/src/main/kotlin/at/bitfire/davdroid/sync/ResourceDownloader.kt +++ b/app/src/main/kotlin/at/bitfire/davdroid/sync/ResourceDownloader.kt @@ -54,7 +54,7 @@ class ResourceDownloader @AssistedInject constructor( suspend fun download(url: Url): ByteArray? { httpClientBuilder .get() - .fromAccount(account, onlyHost = originalHost) // restricts authentication to original domain + .fromAccount(account, authDomain = originalHost) // restricts authentication to original domain .followRedirects(true) // allow redirects .buildKtor() .use { httpClient -> diff --git a/app/src/main/kotlin/at/bitfire/davdroid/webdav/DavHttpClientBuilder.kt b/app/src/main/kotlin/at/bitfire/davdroid/webdav/DavHttpClientBuilder.kt index 07c8311cd..5ea906b24 100644 --- a/app/src/main/kotlin/at/bitfire/davdroid/webdav/DavHttpClientBuilder.kt +++ b/app/src/main/kotlin/at/bitfire/davdroid/webdav/DavHttpClientBuilder.kt @@ -32,7 +32,10 @@ class DavHttpClientBuilder @Inject constructor( .setCookieStore(cookieStore) credentialsStore.getCredentials(mountId)?.let { credentials -> - builder.authenticate(host = null, getCredentials = { credentials }) + builder.authenticate( + domain = null, + getCredentials = { credentials } + ) } return builder.build() diff --git a/app/src/main/kotlin/at/bitfire/davdroid/webdav/WebDavMountRepository.kt b/app/src/main/kotlin/at/bitfire/davdroid/webdav/WebDavMountRepository.kt index 61a3c837e..638bb23b5 100644 --- a/app/src/main/kotlin/at/bitfire/davdroid/webdav/WebDavMountRepository.kt +++ b/app/src/main/kotlin/at/bitfire/davdroid/webdav/WebDavMountRepository.kt @@ -129,7 +129,7 @@ class WebDavMountRepository @Inject constructor( val builder = httpClientBuilder.get() if (credentials != null) builder.authenticate( - host = null, + domain = null, getCredentials = { credentials } ) val httpClient = builder.build()