Improve javadoc and rename withOptions (#67)

- Add missing docs to `GradleEnterpriseApi`
- Fix obsolete references to the old `GradleEnterpriseApi` replacing
with `BuildsApi`
- Move javadoc comments that were on the `GradleEnterpriseApi` impl by
mistake
- Name the companion instance so that it's clearer in the javadoc that
it's a default instance
- Rename `GradleEnterpriseApi.withOptions` to `newInstance`, which also
fits and is more conventional
- Minimize the number of symbols in the root javadoc page to the most
important ones, by making `CacheOptions` a nested class, moving
extensions to a new package, etc.

Author: gabrielfeo

README.md

@@ -106,6 +106,7 @@ shutdown()
 ```kotlin
 import com.gabrielfeo.gradle.enterprise.api.*
 import com.gabrielfeo.gradle.enterprise.api.model.*
+import com.gabrielfeo.gradle.enterprise.api.model.extension.*
 ```
 
 ###  Internals

examples/example-project/app/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/example/Main.kt

@@ -16,7 +16,7 @@ suspend fun main() {
     val newOptions = GradleEnterpriseApi.options.copy(
         clientBuilder = clientBuilder,
     )
-    val gradleEnterpriseApi = GradleEnterpriseApi.withOptions(newOptions)
+    val gradleEnterpriseApi = GradleEnterpriseApi.newInstance(newOptions)
     runAllAnalysis(gradleEnterpriseApi)
     gradleEnterpriseApi.shutdown()
 }

examples/example-project/app/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/example/analysis/MostFrequentBuilds.kt

@@ -1,6 +1,7 @@
 package com.gabrielfeo.gradle.enterprise.api.example.analysis
 
 import com.gabrielfeo.gradle.enterprise.api.*
+import com.gabrielfeo.gradle.enterprise.api.extension.*
 import com.gabrielfeo.gradle.enterprise.api.model.*
 import kotlinx.coroutines.*
 import kotlinx.coroutines.flow.*

library/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/CacheOptions.kt

@@ -6,22 +6,65 @@ import com.gabrielfeo.gradle.enterprise.api.internal.infrastructure.Serializer
 import retrofit2.Retrofit
 import retrofit2.create
 
+/**
+ * Gradle Enterprise API client. API endpoints are grouped exactly as in the
+ * [Gradle Enterprise API Manual](https://docs.gradle.com/enterprise/api-manual/#reference_documentation):
+ *
+ * - [buildsApi]
+ * - [buildCacheApi]
+ * - [metaApi]
+ * - [testDistributionApi]
+ *
+ * For simple use cases, you may use the companion instance ([DefaultInstance]) directly, as if
+ * calling static methods:
+ *
+ * ```kotlin
+ * GradleEnterpriseApi.buildsApi.getBuilds(...)
+ * ```
+ *
+ * However, if you need to change [options] at runtime or own the instance's lifecycle (e.g.
+ * with an IoC container like Dagger), create a new instance:
+ *
+ * ```kotlin
+ * val options = Options(clientBuilder = myOwnOkHttpClient.newBuilder())
+ * val api = GradleEnterpriseApi.newInstance(options)
+ * api.buildsApi.getBuilds(...)
+ * ```
+ */
 interface GradleEnterpriseApi {
 
     val buildsApi: BuildsApi
     val buildCacheApi: BuildCacheApi
     val metaApi: MetaApi
     val testDistributionApi: TestDistributionApi
 
+    /**
+     * Library configuration options.
+     */
     val options: Options
-    fun withOptions(options: Options): GradleEnterpriseApi
+
+    /**
+     * Release resources allowing the program to finish before the internal client's idle timeout.
+     */
     fun shutdown()
 
-    companion object : GradleEnterpriseApi by DefaultGradleEnterpriseApi()
+    /**
+     * The default, companion instance of the Gradle Enterprise API client. See
+     * [GradleEnterpriseApi].
+     */
+    companion object DefaultInstance : GradleEnterpriseApi by RealGradleEnterpriseApi() {
+
+        /**
+         * Create a new instance of `GradleEnterpriseApi` with new options.
+         */
+        fun newInstance(options: Options): GradleEnterpriseApi {
+            return RealGradleEnterpriseApi(options)
+        }
+    }
 
 }
 
-private class DefaultGradleEnterpriseApi(
+private class RealGradleEnterpriseApi(
     override val options: Options = Options(),
 ) : GradleEnterpriseApi {
 
@@ -42,12 +85,6 @@ private class DefaultGradleEnterpriseApi(
     override val metaApi: MetaApi by lazy(retrofit::create)
     override val testDistributionApi: TestDistributionApi by lazy(retrofit::create)
 
-    override fun withOptions(options: Options) = DefaultGradleEnterpriseApi(options)
-
-
-    /**
-     * Release resources allowing the program to finish before the internal client's idle timeout.
-     */
     override fun shutdown() {
         okHttpClient.run {
             dispatcher.executorService.shutdown()

library/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/GradleEnterpriseApi.kt

@@ -3,11 +3,12 @@ package com.gabrielfeo.gradle.enterprise.api
 import com.gabrielfeo.gradle.enterprise.api.internal.*
 import okhttp3.Dispatcher
 import okhttp3.OkHttpClient
+import java.io.File
 import java.util.logging.Logger
+import kotlin.time.Duration.Companion.days
 
 /**
- * Library configuration options. Should not be changed after accessing the [gradleEnterpriseApi]
- * object for the first time.
+ * Library configuration options.
  */
 @Suppress("MemberVisibilityCanBePrivate", "unused")
 data class Options(
@@ -73,9 +74,124 @@ data class Options(
      */
     val cacheOptions: CacheOptions =
         CacheOptions(),
-)
+) {
 
-fun requireEnvOrKeychainToken(debugLoggingEnabled: Boolean): String {
+    /**
+     * HTTP cache is off by default, but can speed up requests significantly. The Gradle Enterprise
+     * API disallows HTTP caching, but this library forcefully enables it by overwriting
+     * cache-related headers in API responses. Enable with [cacheEnabled].
+     *
+     * Responses can be:
+     *
+     * - cached short-term: default max-age of 1 day
+     *   - `/api/builds`
+     * - cached long-term: default max-age of 1 year
+     *   - `/api/builds/{id}/gradle-attributes`
+     *   - `/api/builds/{id}/maven-attributes`
+     *   - `/api/builds/{id}/gradle-build-cache-performance`
+     *   - `/api/builds/{id}/maven-build-cache-performance`
+     * - not cached
+     *   - all other paths
+     *
+     * Whether a response is cached short-term, long-term or not cached at
+     * all depends on whether it was matched by [shortTermCacheUrlPattern] or
+     * [longTermCacheUrlPattern].
+     *
+     * Whenever GE is upgraded, cache should be [clear]ed.
+     *
+     * ### Caveats
+     *
+     * While not encouraged by the API, caching shouldn't have any major downsides other than a
+     * time gap for certain queries, or having to reset cache when GE is upgraded.
+     *
+     * #### Time gap
+     *
+     * `/api/builds` responses always change as new builds are uploaded. Caching this path
+     * short-term (default 1 day) means new builds uploaded after the cached response won't be
+     * included in the query until the cache is invalidated 24h later. If that's a problem,
+     * caching can be disabled for this `/api/builds` by changing [shortTermCacheUrlPattern].
+     *
+     * #### GE upgrades
+     *
+     * When GE is upgraded, any API response can change. New data might be available in API
+     * endpoints such as `/api/build/{id}/gradle-attributes`. Thus, whenever the GE version
+     * itself is upgraded, cache should be [clear]ed.
+     */
+    @Suppress("MemberVisibilityCanBePrivate")
+    data class CacheOptions(
+
+        /**
+         * Whether caching is enabled. By default, uses environment variable
+         * `GRADLE_ENTERPRISE_API_CACHE_ENABLED` or `false`.
+         */
+        val cacheEnabled: Boolean =
+            env["GRADLE_ENTERPRISE_API_CACHE_ENABLED"].toBoolean(),
+
+        /**
+         * 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).
+         */
+        val cacheDir: File =
+            env["GRADLE_ENTERPRISE_API_CACHE_DIR"]?.let(::File)
+                ?: File(System.getProperty("java.io.tmpdir"), "gradle-enterprise-api-kotlin-cache"),
+
+        /**
+         * Max size of the HTTP cache. By default, uses environment variable
+         * `GRADLE_ENTERPRISE_API_MAX_CACHE_SIZE` or ~1 GB.
+         */
+        val maxCacheSize: Long = env["GRADLE_ENTERPRISE_API_MAX_CACHE_SIZE"]?.toLong()
+            ?: 1_000_000_000L,
+
+        /**
+         * Regex pattern to match API URLs that are OK to store long-term in the HTTP cache, up to
+         * [longTermCacheMaxAge] (1y by default, max value). By default, uses environment variable
+         * `GRADLE_ENTERPRISE_API_LONG_TERM_CACHE_URL_PATTERN` or a pattern matching:
+         * - {host}/api/builds/{id}/gradle-attributes
+         * - {host}/api/builds/{id}/maven-attributes
+         * - {host}/api/builds/{id}/gradle-build-cache-performance
+         * - {host}/api/builds/{id}/maven-build-cache-performance
+         *
+         * Use `|` to define multiple patterns in one, e.g. `.*gradle-attributes|.*test-distribution`.
+         */
+        val longTermCacheUrlPattern: Regex =
+            env["GRADLE_ENTERPRISE_API_LONG_TERM_CACHE_URL_PATTERN"]?.toRegex()
+                ?: Regex(
+                    """
+                    .*/api/builds/[\d\w]+/(?:gradle|maven)-(?:attributes|build-cache-performance)
+                """.trimIndent()
+                ),
+
+        /**
+         * Max age in seconds for URLs to be cached long-term (matched by [longTermCacheUrlPattern]).
+         * By default, uses environment variable `GRADLE_ENTERPRISE_API_LONG_TERM_CACHE_MAX_AGE` or 1 year.
+         */
+        val longTermCacheMaxAge: Long =
+            env["GRADLE_ENTERPRISE_API_SHORT_TERM_CACHE_MAX_AGE"]?.toLong()
+                ?: 365.days.inWholeSeconds,
+
+        /**
+         * Regex pattern to match API URLs that are OK to store short-term in the HTTP cache, up to
+         * [shortTermCacheMaxAge] (1d by default). By default, uses environment variable
+         * `GRADLE_ENTERPRISE_API_SHORT_TERM_CACHE_URL_PATTERN` or a pattern matching:
+         * - {host}/api/builds
+         *
+         * Use `|` to define multiple patterns in one, e.g. `.*gradle-attributes|.*test-distribution`.
+         */
+        val shortTermCacheUrlPattern: Regex =
+            env["GRADLE_ENTERPRISE_API_SHORT_TERM_CACHE_URL_PATTERN"]?.toRegex()
+                ?: """.*/builds(?:\?.*|\Z)""".toRegex(),
+
+        /**
+         * Max age in seconds for URLs to be cached short-term (matched by [shortTermCacheUrlPattern]).
+         * By default, uses environment variable `GRADLE_ENTERPRISE_API_SHORT_TERM_CACHE_MAX_AGE` or 1 day.
+         */
+        val shortTermCacheMaxAge: Long =
+            env["GRADLE_ENTERPRISE_API_SHORT_TERM_CACHE_MAX_AGE"]?.toLong()
+                ?: 1.days.inWholeSeconds,
+    )
+}
+
+internal fun requireEnvOrKeychainToken(debugLoggingEnabled: Boolean): String {
     if (systemProperties["os.name"] == "Mac OS X") {
         when (val result = keychain.get("gradle-enterprise-api-token")) {
             is KeychainResult.Success -> return result.token

library/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/Options.kt

@@ -1,4 +1,6 @@
-package com.gabrielfeo.gradle.enterprise.api.model
+package com.gabrielfeo.gradle.enterprise.api.extension
+
+import com.gabrielfeo.gradle.enterprise.api.model.BuildAttributesValue
 
 operator fun List<BuildAttributesValue>.get(name: String): String? {
     return find { it.name == name }?.value