Support advanced query in BuildsApi extensions (#126)

Advanced query is supported in the GE API from 2023.3 as the `query`
parameter in `BuildsApi.getBuilds`. Extensions should support the same
parameters, including `query`. This parameter allows for server-side
filtering, which can make querying the API significantly faster.

Also rename some files to prepare for the next PR.

Author: gabrielfeo

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

@@ -3,6 +3,7 @@ package com.gabrielfeo.gradle.enterprise.api.internal
 import com.gabrielfeo.gradle.enterprise.api.Config
 import com.gabrielfeo.gradle.enterprise.api.GradleEnterpriseApi
 import kotlinx.coroutines.test.runTest
+import okhttp3.HttpUrl.Companion.toHttpUrl
 import org.junit.jupiter.api.assertDoesNotThrow
 import kotlin.test.assertEquals
 import kotlin.test.Test
@@ -14,8 +15,12 @@ class GradleEnterpriseApiIntegrationTest {
         env = RealEnv
         keychain = RealKeychain(RealSystemProperties)
         val api = GradleEnterpriseApi.newInstance()
-        val builds = api.buildsApi.getBuilds(since = 0, maxBuilds = 1)
-        assertEquals(1, builds.size)
+        val builds = api.buildsApi.getBuilds(
+            since = 0,
+            maxBuilds = 5,
+            query = """tag:local value:"Email=gabriel.feo*""""
+        )
+        assertEquals(5, builds.size)
         api.shutdown()
     }
 

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

@@ -2,10 +2,10 @@
 
 package com.gabrielfeo.gradle.enterprise.api.extension
 
+import com.gabrielfeo.gradle.enterprise.api.Config
 import com.gabrielfeo.gradle.enterprise.api.BuildsApi
 import com.gabrielfeo.gradle.enterprise.api.internal.API_MAX_BUILDS
 import com.gabrielfeo.gradle.enterprise.api.internal.operator.pagedUntilLastBuild
-import com.gabrielfeo.gradle.enterprise.api.internal.operator.withGradleAttributes
 import com.gabrielfeo.gradle.enterprise.api.model.*
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.DelicateCoroutinesApi
@@ -17,15 +17,21 @@ import kotlinx.coroutines.flow.*
  * for queries of any size, as opposed to [BuildsApi.getBuilds] which is limited by the
  * API itself to 1000.
  *
- * - Will request from the API until results end or an error occurs.
- * - Use [Sequence.take] and similar functions to stop collecting early.
- * - A subset of `getBuilds` params are supported
+ * - Will request from the API until results end, collection stops or an error occurs.
+ * - Parameters same as [BuildsApi.getBuilds].
+ * - Using [query] is highly recommended for server-side filtering (equivalent to GE advanced
+ * query).
+ * - `maxBuilds` is the only unsupported parameter, because this Flow will instead fetch
+ * continously. Use [Flow.take] to stop collecting at a specific count.
  */
 fun BuildsApi.getBuildsFlow(
     since: Long = 0,
     sinceBuild: String? = null,
     fromInstant: Long? = null,
     fromBuild: String? = null,
+    query: String? = null,
+    reverse: Boolean? = null,
+    maxWaitSecs: Int? = null,
     buildsPerPage: Int = API_MAX_BUILDS,
 ): Flow<Build> {
     val api = this
@@ -35,6 +41,9 @@ fun BuildsApi.getBuildsFlow(
             sinceBuild = sinceBuild,
             fromInstant = fromInstant,
             fromBuild = fromBuild,
+            query = query,
+            reverse = reverse,
+            maxWaitSecs = maxWaitSecs,
             maxBuilds = buildsPerPage,
         )
         val pagedBuilds = firstBuilds.asFlow().pagedUntilLastBuild(api, buildsPerPage)
@@ -43,13 +52,20 @@ fun BuildsApi.getBuildsFlow(
 }
 
 /**
- * Gets [GradleAttributes] of all builds from a given date. Queries [BuildsApi.getBuilds]
- * first, since it's the only endpoint providing a timeline of builds, then maps each to
- * [BuildsApi.getGradleAttributes].
+ * Gets [GradleAttributes] of all builds from a given date. Queries [BuildsApi.getBuilds] first,
+ * the endpoint providing a timeline of builds, then maps each to [BuildsApi.getGradleAttributes].
  *
- * Don't expect client-side filtering to be efficient. Will request up to [Int.MAX_VALUE]
- * builds and their attributes concurrently and eagerly, with a buffer, in coroutines started in
- * [scope]. For other params, see [getBuildsFlow] and [BuildsApi.getBuilds].
+ * Instead of filtering builds downstream based on `GradleAttributes` (e.g. using [Flow.filter]),
+ * prefer filtering server-side using a `query` (see [BuildsApi.getBuilds]).
+ *
+ * ### Buffering
+ *
+ * Will request eagerly and buffer up to [Int.MAX_VALUE] calls.
+ *
+ * ### Concurrency
+ *
+ * Attributes are requested concurrently in coroutines started in [scope]. The number of
+ * concurrent requests underneath is still limited by [Config.maxConcurrentRequests].
  *
  * @param scope CoroutineScope in which to create coroutines. Defaults to [GlobalScope].
  */
@@ -59,13 +75,19 @@ fun BuildsApi.getGradleAttributesFlow(
     sinceBuild: String? = null,
     fromInstant: Long? = null,
     fromBuild: String? = null,
+    query: String? = null,
+    reverse: Boolean? = null,
+    maxWaitSecs: Int? = null,
     scope: CoroutineScope = GlobalScope,
 ): Flow<GradleAttributes> =
     getBuildsFlow(
         since = since,
         sinceBuild = sinceBuild,
         fromInstant = fromInstant,
-        fromBuild = fromBuild
+        fromBuild = fromBuild,
+        query = query,
+        reverse = reverse,
+        maxWaitSecs = maxWaitSecs,
     ).withGradleAttributes(scope, api = this).map { (_, attrs) ->
         attrs
     }

library/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/internal/operator/withGradleAttributes.kt renamed to library/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/extension/Mapping.kt

@@ -1,4 +1,4 @@
-package com.gabrielfeo.gradle.enterprise.api.internal.operator
+package com.gabrielfeo.gradle.enterprise.api.extension
 
 import com.gabrielfeo.gradle.enterprise.api.*
 import com.gabrielfeo.gradle.enterprise.api.model.*

library/src/test/kotlin/com/gabrielfeo/gradle/enterprise/api/internal/operator/WithGradleAttributesTest.kt renamed to library/src/test/kotlin/com/gabrielfeo/gradle/enterprise/api/extension/MappingTest.kt

@@ -1,16 +1,22 @@
-package com.gabrielfeo.gradle.enterprise.api.internal.operator
+package com.gabrielfeo.gradle.enterprise.api.extension
 
 import com.gabrielfeo.gradle.enterprise.api.FakeBuildsApi
 import com.gabrielfeo.gradle.enterprise.api.model.FakeBuild
-import kotlinx.coroutines.*
-import kotlinx.coroutines.flow.*
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.flow.asFlow
+import kotlinx.coroutines.flow.collect
+import kotlinx.coroutines.flow.take
+import kotlinx.coroutines.flow.toList
+import kotlinx.coroutines.launch
 import kotlinx.coroutines.test.runTest
+import kotlinx.coroutines.withTimeoutOrNull
 import org.junit.jupiter.api.Test
 import kotlin.test.assertEquals
 import kotlin.time.Duration.Companion.seconds
 
 @OptIn(ExperimentalCoroutinesApi::class)
-class WithGradleAttributesTest {
+class MappingTest {
 
     private val api = FakeBuildsApi(
         builds = listOf(
@@ -23,7 +29,7 @@ class WithGradleAttributesTest {
     )
 
     @Test
-    fun `Pairs each build with its GradleAttributes`() = runTest {
+    fun `withGradleAttributes pairs each build with its GradleAttributes`() = runTest {
         val buildsToAttrs = api.builds.asFlow().withGradleAttributes(scope = this, api).toList()
         assertEquals(5, api.getGradleAttributesCallCount.value)
         assertEquals(5, buildsToAttrs.size)
@@ -33,7 +39,7 @@ class WithGradleAttributesTest {
     }
 
     @Test
-    fun `Fetches GradleAttributes for all builds eagerly`() = runTest {
+    fun `withGradleAttributes fetches GradleAttributes for all builds eagerly`() = runTest {
         backgroundScope.launch {
             api.builds.asFlow().withGradleAttributes(scope = this, api).collect {
                 // Make the first collect never complete, simulating a slow collector
@@ -46,4 +52,4 @@ class WithGradleAttributesTest {
         }
         assertEquals(5, api.getGradleAttributesCallCount.value)
     }
-}
+}