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

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)
 

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
@@ -156,15 +156,19 @@ 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 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()
             },

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 }
                 )
             }

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 ->

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()

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()