Document public API and support more custom settings

Author: gabrielfeo

src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/Api.kt

@@ -1,23 +1,82 @@
 package com.gabrielfeo.gradle.enterprise.api
 
 import com.gabrielfeo.gradle.enterprise.api.internal.*
-import retrofit2.create
+import java.io.File
 
+/**
+ * The global instance of [GradleEnterpriseApi].
+ */
 val api: GradleEnterpriseApi by lazy {
     retrofit.create(GradleEnterpriseApi::class.java)
 }
 
+/**
+ * Provides the URL of a Gradle Enterprise API instance. By default, uses environment variable
+ * `GRADLE_ENTERPRISE_URL`.
+ */
+var baseUrl: () -> String = {
+    requireBaseUrl(envName = "GRADLE_ENTERPRISE_URL")
+}
+
+/**
+ * Provides the access token for a Gradle Enterprise API instance. By default, uses keychain entry
+ * `gradle-enterprise-api-token` or environment variable `GRADLE_ENTERPRISE_URL`.
+ */
+var accessToken: () -> String = {
+    requireToken(
+        keychainName = "gradle-enterprise-api-token",
+        envName = "GRADLE_ENTERPRISE_API_TOKEN",
+    )
+}
+
+/**
+ * Shutdown the internal OkHttp client, releasing resources and allowing the program to finish
+ * before the client's idle timeout.
+ *
+ * https://square.github.io/okhttp/4.x/okhttp/okhttp3/-ok-http-client/#shutdown-isnt-necessary
+ */
 fun shutdown() {
     okHttpClient.dispatcher.executorService.shutdownNow()
 }
 
-var maxCacheSize = 500_000_000L
+/**
+ * List of patterns matching API URLs that are OK to store in the HTTP cache. Matches by default:
+ * - {host}/api/builds/{id}/gradle-attributes
+ * - {host}/api/builds/{id}/maven-attributes
+ *
+ * By default, the Gradle Enterprise disallows HTTP caching via response headers. This library
+ * removes such headers to forcefully allow caching, if the path is matched by any of these
+ * patterns.
+ */
 val cacheablePaths: MutableList<Regex> = mutableListOf(
     """.*/api/builds/[\d\w]+/(?:gradle|maven)-attributes""".toRegex(),
 )
 
-var baseUrl: () -> String = { requireBaseUrl() }
-var accessToken: () -> String = { requireToken() }
+/**
+ * Maximum amount of concurrent requests allowed. Further requests will be queued. By default,
+ * uses environment variable `GRADLE_ENTERPRISE_API_MAX_CONCURRENT_REQUESTS` or 15.
+ *
+ * https://square.github.io/okhttp/4.x/okhttp/okhttp3/-dispatcher
+ */
+var maxConcurrentRequests = System.getenv("GRADLE_ENTERPRISE_API_MAX_CONCURRENT_REQUESTS")?.toInt()
+    ?: 15
+
+/**
+ * Max size of the HTTP cache. By default, uses environment variable
+ * `GRADLE_ENTERPRISE_API_MAX_CACHE_SIZE` or ~1 GB.
+ */
+var maxCacheSize = System.getenv("GRADLE_ENTERPRISE_API_MAX_CACHE_SIZE")?.toLong()
+    ?: 1_000_000_000L
+
+/**
+ * HTTP cache location. By default, uses environment variable `GRADLE_ENTERPRISE_API_CACHE_DIR`
+ * or the system temporary folder (`java.io.tmpdir` / gradle-enterprise-api-kotlin-cache).
+ */
+var cacheDir = System.getenv("GRADLE_ENTERPRISE_API_CACHE_DIR")?.let(::File)
+    ?: File(System.getProperty("java.io.tmpdir"), "gradle-enterprise-api-kotlin-cache")
 
-var maxConcurrentRequests = 15
+/**
+ * Enables debug logging from the library. All logging is output to the program's standard streams.
+ * By default, uses environment variable `GRADLE_ENTERPRISE_API_DEBUG_LOGGING` or `false`.
+ */
 var debugLoggingEnabled = System.getenv("GRADLE_ENTERPRISE_API_DEBUG_LOGGING").toBoolean()

src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/internal/Authentication.kt

@@ -4,19 +4,16 @@ import com.gabrielfeo.gradle.enterprise.api.debugLoggingEnabled
 import java.util.logging.Level.INFO
 import java.util.logging.Logger
 
-private const val DEFAULT_KEY_NAME = "gradle-enterprise-api-token"
-private const val DEFAULT_VAR_NAME = "GRADLE_ENTERPRISE_API_TOKEN"
-
 internal fun requireToken(
-    keyName: String = DEFAULT_KEY_NAME,
-    varName: String = DEFAULT_VAR_NAME,
+    keychainName: String,
+    envName: String,
 ): String {
-    return tokenFromKeychain(keyName)
-        ?: tokenFromEnv(varName)
+    return tokenFromKeychain(keychainName)
+        ?: tokenFromEnv(envName)
         ?: error("""
-            No API token. Either
-              - create a key in macOS keychain labeled $DEFAULT_KEY_NAME
-              - export in environment variable $DEFAULT_VAR_NAME
+            No API token found. Either
+              - create a key in macOS keychain labeled `gradle-enterprise-api-token`
+              - export in environment variable `GRADLE_ENTERPRISE_API_TOKEN`
               - set the global property `accessToken`
         """.trimIndent())
 }

src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/internal/BaseUrl.kt

@@ -1,14 +1,12 @@
 package com.gabrielfeo.gradle.enterprise.api.internal
 
-private const val DEFAULT_VAR_NAME = "GRADLE_ENTERPRISE_URL"
-
 internal fun requireBaseUrl(
-    varName: String = DEFAULT_VAR_NAME,
+    envName: String,
 ): String {
-    return checkNotNull(System.getenv(varName)) {
+    return checkNotNull(System.getenv(envName)) {
         """
             No base URL provided. Either
-              - export an environment variable $DEFAULT_VAR_NAME
+              - export an environment variable `GRADLE_ENTERPRISE_BASE_URL`
               - set the global property `baseUrl`
         """.trimIndent()
     }

src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/internal/caching/Cache.kt

@@ -1,20 +1,15 @@
 package com.gabrielfeo.gradle.enterprise.api.internal.caching
 
-import com.gabrielfeo.gradle.enterprise.api.baseUrl
+import com.gabrielfeo.gradle.enterprise.api.cacheDir
 import com.gabrielfeo.gradle.enterprise.api.debugLoggingEnabled
 import com.gabrielfeo.gradle.enterprise.api.maxCacheSize
 import okhttp3.Cache
-import okhttp3.HttpUrl.Companion.toHttpUrl
-import java.io.File
 import java.util.logging.Level.INFO
 import java.util.logging.Logger
 
 internal val cache: Cache = run {
-    val host = baseUrl().toHttpUrl().host
-    val tempDir = System.getProperty("java.io.tmpdir")
-    val dir = File(tempDir, "gradle-enterprise-api-cache-$host")
     if (debugLoggingEnabled) {
-        Logger.getGlobal().log(INFO, "HTTP cache dir: $dir")
+        Logger.getGlobal().log(INFO, "HTTP cache dir with max size $maxCacheSize: $cacheDir")
     }
-    Cache(dir, maxSize = maxCacheSize)
+    Cache(cacheDir, maxSize = maxCacheSize)
 }