Polaris Apprunner Gradle and Maven Plugins

[snazy]

This change introduces Gradle and Maven plugins to run Polaris Quarkus server for integration tests. This work is based on projectnessie's apprunner.

The Gradle plugin can be used in other project and in the Polaris "main" code base.

Integration tests of the plugin still use Nessie artifacts to satisfy the need for integration tests of the plugins against binary released available on Maven Central. The actual application, whether it's Polaris or Nessie or any other Quarkus (web) application, not really matter - all work, as long as the syntax of the log message emitted by Quarkus is the same.

Noting that this is intentionally implemented as a "Gradle included build", so that the Polaris "main" build can actually use the Plugin and that it could be released independently, if needed.

Hopefully extensive documentation is included in the README.md in tools/apprunner.

[snazy]

Well, it actually works from an included-build :)

The below patch, running ./gradlew :polaris-quarkus-server:demoTest --info shows the Polaris server starting up (and being shutdown).

diff --git a/quarkus/server/build.gradle.kts b/quarkus/server/build.gradle.kts
index 83e94435d..94f39b026 100644
--- a/quarkus/server/build.gradle.kts
+++ b/quarkus/server/build.gradle.kts
@@ -17,14 +17,22 @@
  * under the License.
  */
 
+import io.quarkus.gradle.tasks.QuarkusBuild
+
 plugins {
   alias(libs.plugins.quarkus)
   alias(libs.plugins.openapi.generator)
   id("polaris-server")
   id("polaris-license-report")
   id("distribution")
+  id("org.apache.polaris.apprunner")
 }
 
+val quarkusRunner by
+  configurations.creating {
+    description = "Used to reference the generated runner-jar (either fast-jar or uber-jar)"
+  }
+
 dependencies {
   implementation(project(":polaris-core"))
   implementation(project(":polaris-api-management-service"))
@@ -38,6 +46,8 @@ dependencies {
 
   // override dnsjava version in dependencies due to https://github.com/dnsjava/dnsjava/issues/329
   implementation(platform(libs.dnsjava))
+
+  polarisQuarkusServer(project(":polaris-quarkus-server", "quarkusRunner"))
 }
 
 quarkus {
@@ -71,3 +81,44 @@ distributions {
     }
   }
 }
+
+testing {
+  suites {
+    val demoTest by registering(JvmTestSuite::class)
+  }
+}
+
+val quarkusFatJar = project.hasProperty("uber-jar")
+val quarkusBuild = tasks.named<QuarkusBuild>("quarkusBuild")
+
+// Expose runnable jar via quarkusRunner configuration for integration-tests that require the
+// server.
+artifacts {
+  add(
+    quarkusRunner.name,
+    provider {
+      if (quarkusFatJar) quarkusBuild.get().runnerJar
+      else quarkusBuild.get().fastJar.resolve("quarkus-run.jar")
+    },
+  ) {
+    builtBy(quarkusBuild)
+  }
+}
+
+// Add the uber-jar, if built, to the Maven publication
+if (quarkusFatJar) {
+  afterEvaluate {
+    publishing {
+      publications {
+        named<MavenPublication>("maven") {
+          artifact(quarkusBuild.get().runnerJar) {
+            classifier = "runner"
+            builtBy(quarkusBuild)
+          }
+        }
+      }
+    }
+  }
+}
+
+polarisQuarkusApp { includeTask(tasks.named("demoTest")) }
diff --git a/quarkus/server/src/demoTest/java/foo/DemoTest.java b/quarkus/server/src/demoTest/java/foo/DemoTest.java
new file mode 100644
index 000000000..e2e2dd81a
--- /dev/null
+++ b/quarkus/server/src/demoTest/java/foo/DemoTest.java
@@ -0,0 +1,27 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package foo;
+
+import org.junit.jupiter.api.Test;
+
+public class DemoTest {
+    @Test
+    public void test() {}
+}

[collado-mike]

When this PR is ready for review, can you update the description or add an issue explaining why this build change is necessary? This seems like it radically complicates the build to something that is much harder to understand and I think it would be good to clarify why that complexity is needed over the blackbox test setup that @dimas-b added previously.

[snazy]

When this PR is ready for review, can you update the description or add an issue explaining why this build change is necessary? This seems like it radically complicates the build to something that is much harder to understand and I think it would be good to clarify why that complexity is needed over the blackbox test setup that @dimas-b added previously.

I've added a README to the PR hopefully explaining lots of it.
The reason is to be able to use the plugin in the main Polaris code base - it completely separates any kind of tests against the in-tree Polaris server. Another reason is that there is (naturally) no release of these plugins yet - so it would be impossible to use those. We can certainly later decide to move this stuff into a separate Git repo - but for now this is the actually only way to use the plugin(s).

[snazy]

Updated the "actual" change w/ changes for polaris-quarkus-server + added a demo (just for review purposes) as a separate commit. That demo can be run with

./gradlew :apprunner-demo:demoTest --info --rerun

and shows something like this illustrating that the actual HTTP ports are available in the test to be run. Noteworthy: the server is only started, when the Gradle test task needs to run. (line wraps by me)

Starting process: [.../java, -Dquarkus.http.port=0, -Dquarkus.management.port=0, -Dquarkus.log.level=INFO, -Dquarkus.log.console.level=INFO, -jar, /home/snazy/devel/polaris/polaris/quarkus/server/build/quarkus-app/quarkus-run.jar]
[output] realm: POLARIS root principal credentials: fbd8c4aea9fd96ac:2710f409041047ecad21aeb791f114a8
[output] 
[output]  @@@@   @@@  @       @    @@@@   @  @@@@    @@@@    @  @@@@@  @    @     @@@   @@@@
[output]  @   @ @   @ @      @ @   @   @  @  @@     @       @ @   @   @ @   @    @   @ @     
[output]  @@@@  @   @ @     @@@@@  @@@@   @    @@   @      @@@@@  @  @@@@@  @    @   @ @  @@@
[output]  @      @@@  @@@@ @     @ @  @@  @  @@@@    @@@@ @     @ @ @@   @@ @@@@  @@@   @@@@ 
[output]                                                                                     
[output]                      *
[output]                                                                                     
[output]                                                                                     
[output]                                       /////\                                        
[output]                                    //\\///T\\\                                      
[output]                                 ///\\\////\\\\\\                                    
[output]                                //\\\\T////\\\\\\\\\                                 
[output]                           /T\ //\\\\\T///T\\//T\\\\\\                               
[output]                         //\\\/////T\\////\\/////\\\\\\\  //\\                       
[output]                      //\\\\\\T///////////////////T\\\\\\\T\\\\\                     
[output]                   //\\\\/////T\//////////\///////T\\\\\T\\\\\\\\                    
[output]                  //\\\\\/////\\\T////////////////\\\\\\/\\\\\\\\\                   
[output] ,,..,,,..,,,..,//\\\\////////\\\\\\\\\\/////////\\\\\///\\\\\\\\\\,,,..,,..,,,..,,,.
[output] ,,..,,,..,,,..,,,..,,,..,,,..,,,..,,,..,,,..,,,..,,,..,,,..,,,..,,,..,,,.,,,..,,,..,
[output] 
[output]                                                            Powered by Quarkus 3.17.8
[output] 2025-01-27 14:20:59,121 INFO  [io.quarkus] [,] [,,,] (main) Apache Polaris Server (incubating) 1.0.0-incubating-SNAPSHOT on JVM (powered by Quarkus 3.17.8) started in 1.270s. 
    Listening on: http://0.0.0.0:38495. Management interface listening on http://0.0.0.0:37345.
...
Starting process 'Gradle Test Executor 17'. Working directory: /home/snazy/devel/polaris/polaris/apprunner-demo Command: /home/snazy/.sdkman/candidates/java/23.0.2-zulu/bin/java 
   -Dquarkus.http.test-port=38495 -Dquarkus.http.test-url=http://0.0.0.0:38495
   -Dquarkus.management.test-port=37345 -Dquarkus.management.test-url=http://0.0.0.0:37345 ...
Successfully started process 'Gradle Test Executor 17'

DemoTest > test() STANDARD_ERROR
    38495
    http://0.0.0.0:38495
    37345
    http://0.0.0.0:37345

[snazy]

Depending on whether an uber-jar (#797) or a distribution tarball/zip would be released to Maven Central additional changes might be necessary to let the apprunner deal with released distributables. The latter would also depend on how the contents of an (extracted) distributable tarball/zip looks like.

[ajantha-bhat]

This can be helpful for the test framework of catalog migrator. Are we planning to merge this soon?

[snazy]

Extracted the 2nd commit as #1082