Support conventional access key sources (#455)

Support using an access key from the conventional locations, matching
the official tooling. Simplifies configuration for users of this
library, which most likely also use the official tooling. Currently,
they're required to set both `DEVELOCITY_API_TOKEN` (for this library)
and `DEVELOCITY_ACCESS_KEY` (for official tooling), which is possibly
redundant if the access keys are from the same user and instance. If an
access key different from the one defined in usual locations must be
used for the API, then a custom `Config.accessKey` is still supported.
The name "API token" was also unintuitive considering that all
Develocity documentation refers to them as "access keys". Resolves #338.

This is a breaking change for projects using `DEVELOCITY_API_TOKEN` or
`Config.apiToken`, targeting the upcoming 2025.1.0 major release.

Thanks to @mcumings for providing an initial reference implementation.

Author: gabrielfeo

.github/workflows/pr.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       DEVELOCITY_API_URL: "${{ vars.DEVELOCITY_API_URL }}"
-      DEVELOCITY_API_TOKEN: "${{ secrets.DEVELOCITY_API_TOKEN }}"
+      DEVELOCITY_ACCESS_KEY: "${{ secrets.DEVELOCITY_ACCESS_KEY }}"
       DEVELOCITY_API_CACHE_ENABLED: "false"
     steps:
       - name: Checkout

.github/workflows/publish-library.yml

@@ -26,7 +26,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       DEVELOCITY_API_URL: "${{ vars.DEVELOCITY_API_URL }}"
-      DEVELOCITY_API_TOKEN: "${{ secrets.DEVELOCITY_API_TOKEN }}"
+      DEVELOCITY_ACCESS_KEY: "${{ secrets.DEVELOCITY_ACCESS_KEY }}"
     steps:
       - name: Checkout
         uses: actions/checkout@v5

gradle/libs.versions.toml

@@ -14,7 +14,9 @@ slf4j = "2.0.17"
 guava = "33.4.8-jre"
 
 [libraries]
+junit-jupiter-params = { module = "org.junit.jupiter:junit-jupiter-params" }
 okio = { module = "com.squareup.okio:okio", version.ref = "okio" }
+okio-fakeFileSystem = { module = "com.squareup.okio:okio-fakefilesystem", version.ref = "okio" }
 moshi = { module = "com.squareup.moshi:moshi", version.ref = "moshi" }
 moshi-kotlin = { module = "com.squareup.moshi:moshi-kotlin", version.ref = "moshi" }
 okhttp = { module = "com.squareup.okhttp3:okhttp", version.ref = "okhttp" }

library/api/library.api

@@ -90,7 +90,7 @@ public final class com/gabrielfeo/develocity/api/Config {
 	public final fun copy (Ljava/lang/String;Ljava/lang/String;Lkotlin/jvm/functions/Function0;Lokhttp3/OkHttpClient$Builder;Ljava/lang/Integer;JLcom/gabrielfeo/develocity/api/Config$CacheConfig;)Lcom/gabrielfeo/develocity/api/Config;
 	public static synthetic fun copy$default (Lcom/gabrielfeo/develocity/api/Config;Ljava/lang/String;Ljava/lang/String;Lkotlin/jvm/functions/Function0;Lokhttp3/OkHttpClient$Builder;Ljava/lang/Integer;JLcom/gabrielfeo/develocity/api/Config$CacheConfig;ILjava/lang/Object;)Lcom/gabrielfeo/develocity/api/Config;
 	public fun equals (Ljava/lang/Object;)Z
-	public final fun getApiToken ()Lkotlin/jvm/functions/Function0;
+	public final fun getAccessKey ()Lkotlin/jvm/functions/Function0;
 	public final fun getApiUrl ()Ljava/lang/String;
 	public final fun getCacheConfig ()Lcom/gabrielfeo/develocity/api/Config$CacheConfig;
 	public final fun getClientBuilder ()Lokhttp3/OkHttpClient$Builder;

library/build.gradle.kts

@@ -28,8 +28,10 @@ dependencies {
     runtimeOnly(libs.slf4j.simple)
     compileOnly(libs.kotlin.jupyter.api)
     testImplementation(libs.okhttp.mockwebserver)
+    testImplementation(libs.okio.fakeFileSystem)
     testImplementation(libs.okio)
     testImplementation(libs.kotlin.coroutines.test)
+    testImplementation(libs.junit.jupiter.params)
     integrationTestImplementation(libs.kotlin.coroutines.test)
     integrationTestImplementation(libs.guava)
     integrationTestImplementation(libs.kotlin.jupyter.testkit)
@@ -104,6 +106,7 @@ tasks.named("compileKotlin", KotlinCompile::class) {
 }
 
 tasks.withType<Test>().configureEach {
+    maxParallelForks = 4
     systemProperty(
         "junit.jupiter.tempdir.cleanup.mode.default",
         System.getProperty("junit.jupiter.tempdir.cleanup.mode.default") ?: "always",
@@ -120,5 +123,4 @@ tasks.named<Test>("examplesTest") {
     inputs.files(files(publishUnsignedSnapshotDevelocityApiKotlinPublicationToMavenLocal))
         .withPropertyName("snapshotPublicationArtifacts")
         .withNormalizer(ClasspathNormalizer::class)
-    maxParallelForks = 4
 }

library/src/integrationTest/kotlin/com/gabrielfeo/develocity/api/DevelocityApiIntegrationTest.kt

@@ -36,7 +36,7 @@ class DevelocityApiIntegrationTest {
         assertDoesNotThrow {
             val config = Config(
                 apiUrl = "https://google.com/api/",
-                apiToken = { "" },
+                accessKey = { "" },
             )
             DevelocityApi.newInstance(config)
         }

library/src/main/kotlin/com/gabrielfeo/develocity/api/Config.kt

@@ -1,10 +1,13 @@
 package com.gabrielfeo.develocity.api
 
-import com.gabrielfeo.develocity.api.Config.CacheConfig
-import com.gabrielfeo.develocity.api.internal.*
+import com.gabrielfeo.develocity.api.internal.auth.accessKeyResolver
+import com.gabrielfeo.develocity.api.internal.basicOkHttpClient
+import com.gabrielfeo.develocity.api.internal.env
+import com.gabrielfeo.develocity.api.internal.systemProperties
 import okhttp3.Dispatcher
 import okhttp3.OkHttpClient
 import java.io.File
+import java.net.URI
 import kotlin.time.Duration.Companion.days
 
 /**
@@ -46,15 +49,32 @@ data class Config(
      */
     val apiUrl: String =
         env["DEVELOCITY_API_URL"]
+            ?.also { requireValidUrl(it) }
             ?: error(ERROR_NULL_API_URL),
 
     /**
-     * Provides the access token for a Develocity API instance. By default, uses environment
-     * variable `DEVELOCITY_API_TOKEN`.
+     * Provides the access key for a Develocity API instance. By default, resolves to the first
+     * key from these sources that matches the host of [apiUrl]:
+     *
+     * - variable `DEVELOCITY_ACCESS_KEY`
+     * - variable `GRADLE_ENTERPRISE_ACCESS_KEY`
+     * - file `$GRADLE_USER_HOME/.gradle/develocity/keys.properties` or, if `GRADLE_USER_HOME` is
+     *   not set, `~/.gradle/develocity/keys.properties`
+     * - file `~/.m2/.develocity/keys.properties`
+     *
+     * Refer to Develocity documentation for details on the format of such variables and files:
+     *
+     * - [Develocity Gradle Plugin User Manual][1]
+     * - [Develocity Maven Extension User Manual][2]
+     *
+     * [1]: https://docs.gradle.com/develocity/gradle-plugin/current/#manual_access_key_configuration
+     * [2]: https://docs.gradle.com/develocity/maven-extension/current/#manual_access_key_configuration
+     *
+     * @throws IllegalArgumentException if no matching key is found.
      */
-    val apiToken: () -> String = {
-        env["DEVELOCITY_API_TOKEN"]
-            ?: error(ERROR_NULL_API_TOKEN)
+    val accessKey: () -> String = {
+        val host = URI(apiUrl).host
+        requireNotNull(accessKeyResolver.resolve(host)) { ERROR_NULL_ACCESS_KEY }
     },
 
     /**
@@ -216,6 +236,15 @@ data class Config(
     )
 }
 
+private fun requireValidUrl(string: String) {
+    requireNotNull(runCatching { URI(string) }.getOrNull()) {
+        ERROR_MALFORMED_API_URL.format(string)
+    }
+}
+
 private const val ERROR_NULL_API_URL = "DEVELOCITY_API_URL is required"
-private const val ERROR_NULL_API_TOKEN = "DEVELOCITY_API_TOKEN is required"
+private const val ERROR_MALFORMED_API_URL = "DEVELOCITY_API_URL contains a malformed URL: %s"
+private const val ERROR_NULL_ACCESS_KEY = "Develocity access key not found. " +
+    "Please set DEVELOCITY_ACCESS_KEY='[host]=[accessKey]' or see Config.accessKey javadoc for " +
+    "other supported options."
 private const val ERROR_NULL_USER_HOME = "'user.home' system property must not be null"

library/src/main/kotlin/com/gabrielfeo/develocity/api/internal/OkHttpClient.kt

@@ -61,7 +61,8 @@ private fun OkHttpClient.Builder.addNetworkInterceptors(
     val logger = loggerFactory.newLogger(HttpLoggingInterceptor::class)
     addNetworkInterceptor(HttpLoggingInterceptor(logger = logger::debug).apply { level = BASIC })
     addNetworkInterceptor(HttpLoggingInterceptor(logger = logger::trace).apply { level = BODY })
-    addNetworkInterceptor(HttpBearerAuth("bearer", config.apiToken()))
+    // Add authentication after logging to prevent clients from leaking their access key
+    addNetworkInterceptor(HttpBearerAuth("bearer", config.accessKey()))
 }
 
 internal fun buildCache(

library/src/main/kotlin/com/gabrielfeo/develocity/api/internal/auth/AccessKeyResolver.kt

@@ -0,0 +1,56 @@
+package com.gabrielfeo.develocity.api.internal.auth
+
+import com.gabrielfeo.develocity.api.internal.Env
+import com.gabrielfeo.develocity.api.internal.env
+import com.gabrielfeo.develocity.api.internal.systemProperties
+import okio.FileSystem
+import okio.Path
+import okio.Path.Companion.toPath
+
+internal var accessKeyResolver = AccessKeyResolver(
+    env,
+    homeDirectory = checkNotNull(systemProperties.userHome).toPath(),
+    fileSystem = FileSystem.SYSTEM,
+)
+
+internal class AccessKeyResolver(
+    private val env: Env,
+    private val homeDirectory: Path,
+    private val fileSystem: FileSystem,
+) {
+
+    private val gradleUserHome: Path
+        get() = env["GRADLE_USER_HOME"]?.toPath() ?: (homeDirectory / ".gradle")
+
+    fun resolve(host: String): String? {
+        val keyEntry = fromEnvVar("DEVELOCITY_ACCESS_KEY", host)
+            ?: fromEnvVar("GRADLE_ENTERPRISE_ACCESS_KEY", host)
+            ?: fromFile(gradleUserHome / "develocity/keys.properties", host)
+            ?: fromFile(homeDirectory / ".m2/.develocity/keys.properties", host)
+        return keyEntry?.accessKey
+    }
+
+    private fun fromEnvVar(varName: String, host: String): HostAccessKeyEntry? =
+        env[varName]?.let { envVar ->
+            envVar.split(';')
+                .firstNotNullOfOrNull { entry ->
+                    if (entry.isBlank()) null
+                    else HostAccessKeyEntry(entry).takeIf { it.host == host }
+                }
+        }
+
+    private fun fromFile(path: Path, host: String): HostAccessKeyEntry? {
+        if (!fileSystem.exists(path)) return null
+        fileSystem.read(path) {
+            while (true) {
+                val line = readUtf8Line()?.trim(' ') ?: break
+                if (line.isBlank() || line.isComment()) continue
+                val entry = HostAccessKeyEntry(line)
+                if (entry.host == host) return entry
+            }
+        }
+        return null
+    }
+
+    private fun String.isComment() = startsWith('#')
+}

library/src/main/kotlin/com/gabrielfeo/develocity/api/internal/auth/HostAccessKeyEntry.kt

@@ -0,0 +1,21 @@
+package com.gabrielfeo.develocity.api.internal.auth
+
+internal class HostAccessKeyEntry(entry: String) {
+
+    private val components = entry.substringBefore(" #").trim().split('=')
+
+    init {
+        require(components.size == 2 && host.isNotBlank() && accessKey.isNotBlank()) {
+            "Invalid access key entry format: '${redact(entry)}'. Expected format is 'host=accessKey'."
+        }
+    }
+
+    val host: String get() = components[0]
+    val accessKey: String get() = components[1]
+}
+
+private const val REDACTED_MAX_LENGTH = 5
+
+private fun redact(entry: String): String =
+    if (entry.length <= REDACTED_MAX_LENGTH) entry
+    else "${entry.substring(0, REDACTED_MAX_LENGTH - 1)}[redacted]"