Improve use in full Kotlin projects (#17)

Improve use in full Kotlin projects (as opposed to standalone Kotlin
scripts), especially projects that aren't exclusively about Gradle
Enterprise and/or talk to other APIs.

- Use a more descriptive name for the global `GradleEnterpriseApi`
instance, that doesn't create confusion with other APIs that the project
might communicate with.
- Allow sharing resources of the internal `OkHttpClient` with another

Author: gabrielfeo

README.md

@@ -7,7 +7,7 @@ A Kotlin library to access the [Gradle Enterprise API][1], easy to use from Kotl
 scripts:
 
 ```kotlin
-api.getBuilds(since = yesterday).forEach {
+gradleEnterpriseApi.getBuilds(since = yesterday).forEach {
   println(it)
 }
 ```
@@ -28,7 +28,7 @@ API:
 @file:Repository("https://jitpack.io")
 @file:DependsOn("com.github.gabrielfeo:gradle-enterprise-api-kotlin:1.0")
 
-api.getBuild(id = "hy5nxbzfjxe5k")
+gradleEnterpriseApi.getBuild(id = "hy5nxbzfjxe5k")
 ```
 
 For configuring base URL and token via code and other available options, see the
@@ -69,28 +69,28 @@ for caveats.
 
 API endpoints are provided as a single interface: [`GradleEnterpriseApi`][9]. The Javadoc is a
 the same as Gradle's online docs, as they're generated from the same spec. An instance is
-initialized and ready-to-use as the global `api` instance:
+initialized and ready-to-use as the global `gradleEnterpriseApi` instance:
 
 ```kotlin
-api.getBuild(id = "hy5nxbzfjxe5k")
+gradleEnterpriseApi.getBuild(id = "hy5nxbzfjxe5k")
 ```
 
 The library also provides a few extension functions on top of the regular API, such as paged
 requests and joining. See [`GradleEnterpriseApi` extensions][10].
 
 ```kotlin
 // Standard query to /api/builds, limited to 1000 builds server-side
-api.getBuilds(since = lastMonth)
+gradleEnterpriseApi.getBuilds(since = lastMonth)
 // Extension: Streams all available builds since given date (paging underneath)
-api.getBuildsFlow(since = lastMonth)
+gradleEnterpriseApi.getBuildsFlow(since = lastMonth)
 ```
 
 It's recommended to call [`shutdown()`][11] at the end of scripts to release resources and let the
 program exit. Otherwise, it'll keep running for an extra ~60s after code finishes, as an [expected
 behavior of OkHttp][4].
 
 ```kotlin
-val builds = api.getBuilds()
+val builds = gradleEnterpriseApi.getBuilds()
 // do work ...
 shutdown()
 ```

sample.main.kts

@@ -1,5 +1,5 @@
 @file:Repository("https://jitpack.io")
-@file:DependsOn("com.github.gabrielfeo:gradle-enterprise-api-kotlin:0.9")
+@file:DependsOn("com.github.gabrielfeo:gradle-enterprise-api-kotlin:0.12.0")
 
 /*
  * Counts how many developers don't run tests on their local machine
@@ -19,7 +19,7 @@ val oneMonthAgo = LocalDate.now()
 runBlocking {
 
     // Filter builds from the API
-    val buildsByUser = api.getGradleAttributesFlow(since = oneMonthAgo)
+    val buildsByUser = gradleEnterpriseApi.getGradleAttributesFlow(since = oneMonthAgo)
         .filter { "CI" !in it.tags }
         .toList()
         .groupBy { it.environment.username }

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

@@ -3,13 +3,11 @@
 package com.gabrielfeo.gradle.enterprise.api
 
 import com.gabrielfeo.gradle.enterprise.api.internal.*
-import java.io.File
-import kotlin.time.Duration.Companion.days
 
 /**
  * The global instance of [GradleEnterpriseApi].
  */
-val api: GradleEnterpriseApi by lazy {
+val gradleEnterpriseApi: GradleEnterpriseApi by lazy {
     retrofit.create(GradleEnterpriseApi::class.java)
 }
 

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

@@ -3,6 +3,8 @@
 package com.gabrielfeo.gradle.enterprise.api
 
 import com.gabrielfeo.gradle.enterprise.api.internal.*
+import okhttp3.Dispatcher
+import okhttp3.OkHttpClient
 import java.io.File
 import kotlin.time.Duration.Companion.days
 
@@ -12,8 +14,8 @@ import kotlin.time.Duration.Companion.days
 val options = Options(env = RealEnv, keychain = RealKeychain(RealEnv))
 
 /**
- * Library configuration options. Should not be changed after accessing the [api] object for the
- * first time.
+ * Library configuration options. Should not be changed after accessing the [gradleEnterpriseApi]
+ * object for the first time.
  *
  * Use the global [options] instance.
  */
@@ -23,14 +25,14 @@ class Options internal constructor(
 ) {
 
     val gradleEnterpriseInstance = GradleEnterpriseInstanceOptions(env, keychain)
-    val concurrency = ConcurrencyOptions(env)
+    val httpClient = HttpClientOptions(env)
     val cache = CacheOptions(env)
     val debugging = DebuggingOptions(env)
 
     /**
      * Options about the GE instance, such as URL and API token.
      *
-     * Access via the global [options] instance.
+     * Access via the global [options] instance: `options.gradleEnterpriseInstance`.
      */
     class GradleEnterpriseInstanceOptions internal constructor(
         private val env: Env,
@@ -58,31 +60,45 @@ class Options internal constructor(
     }
 
     /**
-     * Concurrency options.
+     * HTTP client options.
      *
-     * Access via the global [options] instance.
+     * Access via the global [options] instance: `options.httpClient`.
      */
-    class ConcurrencyOptions internal constructor(
+    class HttpClientOptions internal constructor(
         env: Env,
     ) {
 
+        /**
+         * Provider of an [OkHttpClient.Builder] to use when building the library's internal client.
+         * Has a default value and shouldn't be needed in scripts.
+         *
+         * This is aimed at using the library inside a full Kotlin project. Allows the internal client to
+         * share resources such as thread pools with another [OkHttpClient], useful for full Kotlin projects
+         * and rarely needed for scripting. See [OkHttpClient] for all that is shared.
+         */
+        var clientBuilder: () -> OkHttpClient.Builder = {
+            OkHttpClient.Builder()
+        }
+
         /**
          * Maximum amount of concurrent requests allowed. Further requests will be queued. By default,
-         * uses environment variable `GRADLE_ENTERPRISE_API_MAX_CONCURRENT_REQUESTS` or 15.
+         * uses environment variable `GRADLE_ENTERPRISE_API_MAX_CONCURRENT_REQUESTS` or 5 (OkHttp's
+         * default value of [Dispatcher.maxRequestsPerHost]).
          *
-         * https://square.github.io/okhttp/4.x/okhttp/okhttp3/-dispatcher
+         * If set, will set [Dispatcher.maxRequests] and [Dispatcher.maxRequestsPerHost] of the
+         * internal client, overwriting what's inherited from the base client of [clientBuilder],
+         * if any.
          */
         var maxConcurrentRequests =
             env["GRADLE_ENTERPRISE_API_MAX_CONCURRENT_REQUESTS"]?.toInt()
-                ?: 15
     }
 
     /**
      * 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].
      *
-     * Access via the global [options] instance.
+     * Access via the global [options] instance: `options.cache`.
      *
      * Responses can be:
      *
@@ -197,7 +213,7 @@ class Options internal constructor(
     /**
      * Library debugging options.
      *
-     * Access via the global [options] instance.
+     * Access via the global [options] instance: `options.debugging`.
      */
     class DebuggingOptions internal constructor(
         env: Env,

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

@@ -5,7 +5,6 @@ import com.gabrielfeo.gradle.enterprise.api.internal.auth.HttpBearerAuth
 import com.gabrielfeo.gradle.enterprise.api.internal.caching.CacheEnforcingInterceptor
 import com.gabrielfeo.gradle.enterprise.api.internal.caching.CacheHitLoggingInterceptor
 import okhttp3.Cache
-import okhttp3.OkHttpClient
 import java.util.logging.Level
 import java.util.logging.Logger
 
@@ -15,7 +14,7 @@ internal val okHttpClient by lazy {
 
 internal fun buildOkHttpClient(
     options: Options,
-) = with(OkHttpClient.Builder()) {
+) = with(options.httpClient.clientBuilder()) {
     if (options.cache.cacheEnabled) {
         cache(buildCache(options))
     }
@@ -27,8 +26,10 @@ internal fun buildOkHttpClient(
         addNetworkInterceptor(buildCacheEnforcingInterceptor(options))
     }
     build().apply {
-        dispatcher.maxRequests = options.concurrency.maxConcurrentRequests
-        dispatcher.maxRequestsPerHost = options.concurrency.maxConcurrentRequests
+        options.httpClient.maxConcurrentRequests?.let {
+            dispatcher.maxRequests = it
+            dispatcher.maxRequestsPerHost = it
+        }
     }
 }
 

src/test/kotlin/com/gabrielfeo/gradle/enterprise/api/OkHttpClientTest.kt

@@ -1,15 +1,13 @@
 package com.gabrielfeo.gradle.enterprise.api
 
-import com.gabrielfeo.gradle.enterprise.api.internal.Env
 import com.gabrielfeo.gradle.enterprise.api.internal.FakeEnv
 import com.gabrielfeo.gradle.enterprise.api.internal.FakeKeychain
 import com.gabrielfeo.gradle.enterprise.api.internal.auth.HttpBearerAuth
 import com.gabrielfeo.gradle.enterprise.api.internal.buildOkHttpClient
 import com.gabrielfeo.gradle.enterprise.api.internal.caching.CacheEnforcingInterceptor
 import com.gabrielfeo.gradle.enterprise.api.internal.caching.CacheHitLoggingInterceptor
-import okhttp3.Interceptor
+import okhttp3.Dispatcher
 import okhttp3.OkHttpClient
-import kotlin.reflect.KClass
 import kotlin.test.*
 
 class OkHttpClientTest {
@@ -21,14 +19,28 @@ class OkHttpClientTest {
     }
 
     @Test
-    fun `Sets max concurrency from options`() {
+    fun `Given maxConcurrentRequests, sets values in Dispatcher`() {
         val client = buildClient(
             "GRADLE_ENTERPRISE_API_MAX_CONCURRENT_REQUESTS" to "123"
         )
         assertEquals(123, client.dispatcher.maxRequests)
         assertEquals(123, client.dispatcher.maxRequestsPerHost)
     }
 
+    @Test
+    fun `Given no maxConcurrentRequests, preserves original client's Dispatcher values`() {
+        val baseClient = OkHttpClient.Builder()
+            .dispatcher(
+                Dispatcher().apply {
+                    maxRequests = 1
+                    maxRequestsPerHost = 1
+                }
+            ).build()
+        val client = buildClient(clientBuilder = baseClient.newBuilder())
+        assertEquals(1, client.dispatcher.maxRequests)
+        assertEquals(1, client.dispatcher.maxRequestsPerHost)
+    }
+
     @Test
     fun `Given debug logging and cache enabled, adds logging interceptors`() {
         val client = buildClient(
@@ -64,12 +76,18 @@ class OkHttpClientTest {
 
     private fun buildClient(
         vararg envVars: Pair<String, String?>,
+        clientBuilder: OkHttpClient.Builder? = null,
     ): OkHttpClient {
         val env = FakeEnv(*envVars)
         if ("GRADLE_ENTERPRISE_API_TOKEN" !in env)
             env["GRADLE_ENTERPRISE_API_TOKEN"] = "example-token"
         if ("GRADLE_ENTERPRISE_API_URL" !in env)
             env["GRADLE_ENTERPRISE_API_URL"] = "example-url"
-        return buildOkHttpClient(Options(env, FakeKeychain()))
+        val options = Options(env, FakeKeychain()).apply {
+            clientBuilder?.let {
+                httpClient.clientBuilder = { it }
+            }
+        }
+        return buildOkHttpClient(options)
     }
 }

src/test/kotlin/com/gabrielfeo/gradle/enterprise/api/OptionsTest.kt

@@ -64,7 +64,7 @@ class OptionsTest {
             env = FakeEnv("GRADLE_ENTERPRISE_API_MAX_CONCURRENT_REQUESTS" to "1"),
         )
         assertDoesNotThrow {
-            options.concurrency.maxConcurrentRequests
+            options.httpClient.maxConcurrentRequests
         }
     }