Redesign API for better usage in projects (#49)

### 1. Single library entrypoint

Migrate library API from a few top-level variables and functions to a
single entrypoint interface called `GradleEnterpriseApi`.

The current setup isn't great because one has to remember symbol names
without much help from autocomplete. A single interface results in a
better experience with autocomplete, especially considering the limited
Jupyter and Jupyter Lab environments.

This also improves use in projects by removing broadly-named symbols
such as `options`, which could be easily confused with anything else the
project does:

```kotlin
class MyProjectCliClass {
  fun startup() {
    // "Options of what? Which library? Our CLI is caching something?"
    options.cache.cacheEnabled = true
  }
}
```

Faking `shutdown` and other library methods is now supported.

### 2. Redesign library options

Replace the cumbersome global, var-based `Options` with a (mostly)
immutable version. Previously, one had to ensure changing the vars
before the first time the `gradleEnterpriseApi` global instance is
accessed. Now, each `GradleEnterpriseApi` instance contains an immutable
set of options and one can obtain a copy with different settings at any
time.

### 3. Split API service interface to match Gradle's docs

Replace the current Retrofit service interface with four others, also
generated, to match Gradle's docs. The docs group endpoints in four:

- Builds
- Build cache
- Meta 
- Test Distribution

Splitting it in smaller interfaces can also make it simpler to fake the
libraries APIs for testing.

Author: gabrielfeo

.github/workflows/pr.yml

@@ -17,7 +17,7 @@ jobs:
       - name: gradle check
         uses: ./.github/actions/build
         with:
-          args: 'check'
+          args: 'check compileIntegrationTestKotlin'
           # artifact-name: 'Test reports (${{matrix.runner}})'
           # path-to-upload: '**/build/reports/tests/**'
 

examples/example-notebooks/MostFrequentBuilds.ipynb

@@ -153,7 +153,7 @@
     "\n",
     "val builds: List<GradleAttributes> = runBlocking {\n",
     "    val startMilli = startDate.atStartOfDay(ZoneId.of(\"UTC\")).toInstant().toEpochMilli()\n",
-    "    gradleEnterpriseApi.getGradleAttributesFlow(since = startMilli)\n",
+    "    GradleEnterprise.api.getGradleAttributesFlow(since = startMilli)\n",
     "        .filter(buildFilter)\n",
     "        .printProgress { i, build ->\n",
     "            val buildDate = Instant.ofEpochMilli(build.buildStartTime).atOffset(ZoneOffset.UTC)\n",

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

@@ -1,9 +1,7 @@
 package com.gabrielfeo.gradle.enterprise.api.example
 
+import com.gabrielfeo.gradle.enterprise.api.GradleEnterpriseApi
 import com.gabrielfeo.gradle.enterprise.api.example.analysis.mostFrequentBuilds
-import com.gabrielfeo.gradle.enterprise.api.gradleEnterpriseApi
-import com.gabrielfeo.gradle.enterprise.api.options
-import com.gabrielfeo.gradle.enterprise.api.shutdown
 import okhttp3.OkHttpClient
 
 /*
@@ -15,11 +13,14 @@ import okhttp3.OkHttpClient
 val clientBuilder = OkHttpClient.Builder()
 
 suspend fun main() {
-    options.httpClient.clientBuilder = { clientBuilder }
-    runAllAnalysis()
-    shutdown()
+    val newOptions = GradleEnterpriseApi.options.copy(
+        clientBuilder = clientBuilder,
+    )
+    val gradleEnterpriseApi = GradleEnterpriseApi.withOptions(newOptions)
+    runAllAnalysis(gradleEnterpriseApi)
+    gradleEnterpriseApi.shutdown()
 }
 
-private suspend fun runAllAnalysis() {
-    mostFrequentBuilds(api = gradleEnterpriseApi)
+private suspend fun runAllAnalysis(gradleEnterpriseApi: GradleEnterpriseApi) {
+    mostFrequentBuilds(api = gradleEnterpriseApi.buildsApi)
 }

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

@@ -22,7 +22,7 @@ import java.util.LinkedList
  *   legacy tests. We should suggest they run test instead, leaving check for CI to run."
  */
 suspend fun mostFrequentBuilds(
-    api: GradleEnterpriseApi,
+    api: BuildsApi,
     startDate: LocalDate = LocalDate.now().minusWeeks(1),
     buildFilter: (GradleAttributes) -> Boolean = { build ->
         "LOCAL" in build.tags
@@ -63,6 +63,7 @@ suspend fun mostFrequentBuilds(
 
 
 // A utility to print progress as builds are fetched. You may ignore this.
+@OptIn(DelicateCoroutinesApi::class)
 fun <T> Flow<T>.printProgress(produceMsg: (i: Int, current: T) -> String): Flow<T> {
     var i = -1
     var current: T? = null

examples/example-script.main.kts

@@ -58,7 +58,7 @@ fun <T> Flow<T>.printProgress(produceMsg: (i: Int, current: T) -> String): Flow<
 // Fetch builds from the API
 val builds: List<GradleAttributes> = runBlocking {
     val startMilli = startDate.atStartOfDay(ZoneId.of("UTC")).toInstant().toEpochMilli()
-    gradleEnterpriseApi.getGradleAttributesFlow(since = startMilli)
+    GradleEnterprise.api.getGradleAttributesFlow(since = startMilli)
         .filter(buildFilter)
         .printProgress { i, build ->
             val buildDate = Instant.ofEpochMilli(build.buildStartTime).atOffset(ZoneOffset.UTC)

library/.openapi-generator-ignore

@@ -5,8 +5,5 @@ build/generated/openapi-generator/gradle/**/*
 build/generated/openapi-generator/docs/*
 build/generated/openapi-generator/src/main/AndroidManifest.xml
 build/generated/openapi-generator/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/internal/infrastructure/ApiClient.kt
-build/generated/openapi-generator/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/BuildsApi.kt
-build/generated/openapi-generator/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/BuildCacheApi.kt
-build/generated/openapi-generator/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/MetaApi.kt
-build/generated/openapi-generator/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/TestDistributionApi.kt
+build/generated/openapi-generator/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/GradleEnterpriseApi.kt
 build/generated/openapi-generator/src/test/**/*

library/build.gradle.kts

@@ -56,45 +56,45 @@ openApiGenerate {
 }
 
 tasks.openApiGenerate.configure {
+    val srcDir = File(outputDir.get(), "src/main/kotlin")
     doFirst {
         logger.info("Using API spec ${inputSpec.get()}")
     }
     // Replace Response<X> with X in every method return type of GradleEnterpriseApi.kt
     doLast {
-        val apiFile = File(
-            outputDir.get(),
-            "src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/GradleEnterpriseApi.kt",
-        )
         ant.withGroovyBuilder {
             "replaceregexp"(
-                "file" to apiFile,
                 "match" to ": Response<(.*?)>$",
                 "replace" to """: \1""",
                 "flags" to "gm",
-            )
+            ) {
+                "fileset"(
+                    "dir" to srcDir,
+                    "includes" to "com/gabrielfeo/gradle/enterprise/api/*Api.kt",
+                )
+            }
         }
     }
     // Add @JvmSuppressWildcards to avoid square/retrofit#3275
     doLast {
-        val apiFile = File(
-            outputDir.get(),
-            "src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/GradleEnterpriseApi.kt",
-        )
         ant.withGroovyBuilder {
             "replaceregexp"(
-                "file" to apiFile,
-                "match" to "interface GradleEnterpriseApi",
+                "match" to "interface",
                 "replace" to """
                     @JvmSuppressWildcards
-                    interface GradleEnterpriseApi
+                    interface
                 """.trimIndent(),
                 "flags" to "m",
-            )
+            ) {
+                "fileset"(
+                    "dir" to srcDir,
+                    "includes" to "com/gabrielfeo/gradle/enterprise/api/*Api.kt",
+                )
+            }
         }
     }
     // Workaround for properties generated with `arrayListOf(null,null)` as default value
     doLast {
-        val srcDir = File(outputDir.get(), "src/main/kotlin")
         ant.withGroovyBuilder {
             "replaceregexp"(
                 "match" to """arrayListOf\(null,null\)""",
@@ -109,7 +109,6 @@ tasks.openApiGenerate.configure {
     }
     // Workaround for missing imports of exploded queries
     doLast {
-        val srcDir = File(outputDir.get(), "src/main/kotlin")
         val modelPackage = openApiGenerate.modelPackage.get()
         val modelPackagePattern = modelPackage.replace(".", "\\.")
         ant.withGroovyBuilder {
@@ -193,7 +192,7 @@ testing {
         }
         register<JvmTestSuite>("integrationTest") {
             dependencies {
-                implementation(project())
+//                implementation(project())
                 implementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.7.1")
             }
         }
@@ -203,6 +202,14 @@ testing {
     }
 }
 
+kotlin {
+    target {
+        val main by compilations.getting
+        val integrationTest by compilations.getting
+        integrationTest.associateWith(main)
+    }
+}
+
 java {
     consistentResolution {
         useRuntimeClasspathVersions()

library/src/integrationTest/kotlin/com/gabrielfeo/gradle/enterprise/api/internal/GradleEnterpriseApiIntegrationTest.kt

@@ -0,0 +1,16 @@
+package com.gabrielfeo.gradle.enterprise.api.internal
+
+import com.gabrielfeo.gradle.enterprise.api.GradleEnterpriseApi
+import kotlinx.coroutines.test.runTest
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class GradleEnterpriseApiIntegrationTest {
+
+    @Test
+    fun canFetchBuilds() = runTest {
+        val builds = GradleEnterpriseApi.buildsApi.getBuilds(since = 0, maxBuilds = 1)
+        assertEquals(1, builds.size)
+        GradleEnterpriseApi.shutdown()
+    }
+}

library/src/integrationTest/kotlin/com/gabrielfeo/gradle/enterprise/api/internal/GradleEnterpriseIntegrationTest.kt

@@ -1,17 +1,16 @@
 package com.gabrielfeo.gradle.enterprise.api.internal
 
+import com.gabrielfeo.gradle.enterprise.api.internal.keychain
 import kotlin.test.Test
 import kotlin.test.assertFalse
+import kotlin.test.assertIs
 
-class KeychainIntegrationTest {
-
-    val keychain = RealKeychain(RealSystemProperties)
+internal class KeychainIntegrationTest {
 
     @Test
     fun getApiToken() {
-        assertFalse(
-            keychain["gradle-enterprise-api-token"].isNullOrEmpty(),
-            "Keychain returned null or empty",
-        )
+        val result = keychain.get("gradle-enterprise-api-token")
+        assertIs<KeychainResult.Success>(result)
+        assertFalse(result.token.isNullOrBlank(), "Keychain returned null or blank")
     }
 }