Registry client option to set a low boundary for recommended streams on

the client side

Author: aloubyansky

docs/src/main/asciidoc/extension-registry-user.adoc

@@ -221,19 +221,55 @@ Applications using a registry client can be configured using environment variabl
 
 `QUARKUS_REGISTRIES` environment variable can be used to specify which registries should be enabled as a comma-separated list of registry IDs.
 For example
-```
+----
 QUARKUS_REGISTRIES=registry.acme.org,registry.quarkus.io
-```
+----
 That alone will be enough to initialize a registry client to pull extension catalogs from two registries using their default configurations.
 
 Certain registry options could be initialized with their specific environment variables. Each such option will have the following environment variable prefix:
-```
+----
 QUARKUS_REGISTRY_<UPPERCASED_AND_UNDERSCORED_REGISTRY_ID>_
-```
+----
 where `<UPPERCASED_AND_UNDERSCORED_REGISTRY_ID>` is a registry ID with each character converted to uppercase and a `.` replaced with `_`. For example, `REGISTRY_ACME_ORG`.
 
-The following options can be configured with this approach:
+Below are examples of various options that can be configured following this approach.
 
-- Repository URL, for example `QUARKUS_REGISTRY_REGISTRY_ACME_ORG_REPO_URL=https://internal.registry.acme.org/maven`
-- Update policy, for example `QUARKUS_REGISTRY_REGISTRY_ACME_ORG_UPDATE_POLICY=always`
-- Offering, for example `QUARKUS_REGISTRY_REGISTRY_ACME_ORG_OFFERING=acme-magic`
+===== Repository URL
+
+`QUARKUS_REGISTRY_<UPPERCASED_AND_UNDERSCORED_REGISTRY_ID>_REPO_URL=<REPO_URL>`
+
+Example:
+----
+QUARKUS_REGISTRY_REGISTRY_ACME_ORG_REPO_URL=https://internal.registry.acme.org/maven
+----
+
+===== Update policy
+
+`QUARKUS_REGISTRY_<UPPERCASED_AND_UNDERSCORED_REGISTRY_ID>_UPDATE_POLICY=<UPDATE_POLICY>`
+
+Example:
+----
+QUARKUS_REGISTRY_REGISTRY_ACME_ORG_UPDATE_POLICY=always
+----
+
+===== Offering
+
+`QUARKUS_REGISTRY_<UPPERCASED_AND_UNDERSCORED_REGISTRY_ID>_OFFERING=<OFFERING>`
+
+Example:
+----
+QUARKUS_REGISTRY_REGISTRY_ACME_ORG_OFFERING=acme-magic
+----
+
+===== Recommend Streams From
+
+Set the oldest acceptable stream value per platform. Streams older than the configured values will be ignored by the client.
+
+`QUARKUS_REGISTRY_<UPPERCASED_AND_UNDERSCORED_REGISTRY_ID>_RECOMMEND_STREAMS_FROM_<UPPERCASED_AND_UNDERSCORED_PLATFORM_KEY>=<STREAM_ID>`
+
+Where `UPPERCASED_AND_UNDERSCORED_PLATFORM_KEY` is a platform key with each character converted to uppercase and a `.` replaced with `_`. For example, `IO_QUARKUS_PLATFORM`.
+
+Example:
+----
+QUARKUS_REGISTRY_REGISTRY_ACME_ORG_RECOMMEND_STREAMS_FROM_IO_QUARKUS_PLATFORM=3.27
+----

independent-projects/tools/devtools-common/src/main/java/io/quarkus/devtools/commands/handlers/CreateProjectCommandHandler.java

@@ -99,14 +99,15 @@ private static class ProjectDependencyInfo {
             // necessary to set the versions from the selected origins
             this.dataCatalog = CatalogMergeUtility.merge(extensionOrigins);
             // collect platform BOMs to import
-            boolean sawFirstPlatform = false;
             ExtensionCatalog primaryCatalog = null;
             this.platformBoms = new ArrayList<>(extensionOrigins.size());
             for (ExtensionCatalog c : extensionOrigins) {
                 if (c.isPlatform()) {
-                    if (c.getBom().getArtifactId().equals(QUARKUS_BOM) || !sawFirstPlatform) {
+                    // use either the first platform catalog or the first quarkus-bom catalog, if found
+                    if (primaryCatalog == null
+                            || !primaryCatalog.getBom().getArtifactId().equals(QUARKUS_BOM)
+                                    && c.getBom().getArtifactId().equals(QUARKUS_BOM)) {
                         primaryCatalog = c;
-                        sawFirstPlatform = true;
                     }
                     platformBoms.add(c.getBom());
                 }

independent-projects/tools/devtools-testing/src/main/java/io/quarkus/devtools/testing/registry/client/TestRegistryClientBuilder.java

@@ -1,5 +1,8 @@
 package io.quarkus.devtools.testing.registry.client;
 
+import static io.quarkus.registry.Constants.OFFERING;
+import static io.quarkus.registry.Constants.RECOMMEND_STREAMS_FROM;
+
 import java.io.BufferedWriter;
 import java.io.IOException;
 import java.io.UncheckedIOException;
@@ -390,12 +393,26 @@ public TestRegistryBuilder recognizedQuarkusVersions(String expr, boolean exclus
         }
 
         public TestRegistryBuilder setOffering(String offering) {
+            return setExtraOption(OFFERING, offering);
+        }
+
+        public TestRegistryBuilder setRecommendStreamsFrom(String platformKey, String streamId) {
+            Map<String, String> recommendStreamsFrom = (Map<String, String>) config.getExtra().get(RECOMMEND_STREAMS_FROM);
+            if (recommendStreamsFrom == null) {
+                recommendStreamsFrom = new HashMap<>(2);
+                setExtraOption(RECOMMEND_STREAMS_FROM, recommendStreamsFrom);
+            }
+            recommendStreamsFrom.put(platformKey, streamId);
+            return this;
+        }
+
+        private TestRegistryBuilder setExtraOption(String name, Object value) {
             var extra = config.getExtra();
             if (extra == null || extra.isEmpty()) {
-                extra = new HashMap<>(1);
+                extra = new HashMap<>(4);
                 config.setExtra(extra);
             }
-            extra.put(Constants.OFFERING, offering);
+            extra.put(name, value);
             return this;
         }
 

independent-projects/tools/devtools-testing/src/test/java/io/quarkus/devtools/project/create/RecommendStreamsFromScenario1Test.java

@@ -0,0 +1,31 @@
+package io.quarkus.devtools.project.create;
+
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+
+import io.quarkus.maven.dependency.ArtifactCoords;
+
+/**
+ * This test does not configure the recommend-streams-from but tests the default setup
+ */
+public class RecommendStreamsFromScenario1Test extends RecommendStreamsFromScenarioBase {
+
+    @Test
+    public void createOfferingA() throws Exception {
+        final Path projectDir = newProjectDir(getClass().getSimpleName());
+        createProject(projectDir, List.of("ext-a", "ext-b"));
+
+        assertModel(projectDir,
+                List.of(mainPlatformBom(),
+                        platformMemberBomCoords("acme-a-bom"),
+                        platformMemberBomCoords("acme-b-bom")),
+                List.of(ArtifactCoords.jar("io.acme", "ext-a", null),
+                        ArtifactCoords.jar("io.acme", "ext-b", null)),
+                Map.of("quarkus.platform.group-id", DOWNSTREAM_PLATFORM_KEY,
+                        "quarkus.platform.artifact-id", "quarkus-bom",
+                        "quarkus.platform.version", "2.2.2.downstream"));
+    }
+}

independent-projects/tools/devtools-testing/src/test/java/io/quarkus/devtools/project/create/RecommendStreamsFromScenario2Test.java

@@ -0,0 +1,38 @@
+package io.quarkus.devtools.project.create;
+
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+
+import io.quarkus.devtools.testing.registry.client.TestRegistryClientBuilder;
+import io.quarkus.maven.dependency.ArtifactCoords;
+
+/**
+ * This test does not configure the recommend-streams-from but configures an offering, which makes the tools give preference to
+ * an older stream
+ */
+public class RecommendStreamsFromScenario2Test extends RecommendStreamsFromScenarioBase {
+
+    @Override
+    protected void setDownstreamRegistryExtraOptions(TestRegistryClientBuilder.TestRegistryBuilder registry) {
+        registry.setOffering("offering-a");
+    }
+
+    @Test
+    public void createOfferingA() throws Exception {
+        final Path projectDir = newProjectDir(getClass().getSimpleName());
+        createProject(projectDir, List.of("ext-a", "ext-b"));
+
+        assertModel(projectDir,
+                List.of(mainPlatformBom(),
+                        platformMemberBomCoords("acme-a-bom"),
+                        platformMemberBomCoords("acme-b-bom")),
+                List.of(ArtifactCoords.jar("io.acme", "ext-a", null),
+                        ArtifactCoords.jar("io.acme", "ext-b", null)),
+                Map.of("quarkus.platform.group-id", DOWNSTREAM_PLATFORM_KEY,
+                        "quarkus.platform.artifact-id", "quarkus-bom",
+                        "quarkus.platform.version", "1.1.1.downstream"));
+    }
+}

independent-projects/tools/devtools-testing/src/test/java/io/quarkus/devtools/project/create/RecommendStreamsFromScenario3Test.java

@@ -0,0 +1,35 @@
+package io.quarkus.devtools.project.create;
+
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+
+import io.quarkus.devtools.testing.registry.client.TestRegistryClientBuilder;
+import io.quarkus.maven.dependency.ArtifactCoords;
+
+public class RecommendStreamsFromScenario3Test extends RecommendStreamsFromScenarioBase {
+
+    @Override
+    protected void setDownstreamRegistryExtraOptions(TestRegistryClientBuilder.TestRegistryBuilder registry) {
+        registry.setOffering("offering-a")
+                .setRecommendStreamsFrom(DOWNSTREAM_PLATFORM_KEY, "2.2");
+    }
+
+    @Test
+    public void createOfferingA() throws Exception {
+        final Path projectDir = newProjectDir(getClass().getSimpleName());
+        createProject(projectDir, List.of("ext-a", "ext-b"));
+
+        assertModel(projectDir,
+                List.of(mainPlatformBom(),
+                        platformMemberBomCoords("acme-a-bom"),
+                        ArtifactCoords.pom(UPSTREAM_PLATFORM_KEY, "acme-b-bom", "2.2.2")),
+                List.of(ArtifactCoords.jar("io.acme", "ext-a", null),
+                        ArtifactCoords.jar("io.acme", "ext-b", null)),
+                Map.of("quarkus.platform.group-id", DOWNSTREAM_PLATFORM_KEY,
+                        "quarkus.platform.artifact-id", "quarkus-bom",
+                        "quarkus.platform.version", "2.2.2.downstream"));
+    }
+}

independent-projects/tools/devtools-testing/src/test/java/io/quarkus/devtools/project/create/RecommendStreamsFromScenario4Test.java

@@ -0,0 +1,40 @@
+package io.quarkus.devtools.project.create;
+
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+
+import io.quarkus.devtools.testing.registry.client.TestRegistryClientBuilder;
+import io.quarkus.maven.dependency.ArtifactCoords;
+
+public class RecommendStreamsFromScenario4Test extends RecommendStreamsFromScenarioBase {
+
+    @Override
+    protected void setDownstreamRegistryExtraOptions(TestRegistryClientBuilder.TestRegistryBuilder registry) {
+        registry.setOffering("offering-a")
+                .setRecommendStreamsFrom(DOWNSTREAM_PLATFORM_KEY, "2.2");
+    }
+
+    @Override
+    protected void setUpstreamRegistryExtraOptions(TestRegistryClientBuilder.TestRegistryBuilder registry) {
+        registry.setRecommendStreamsFrom(UPSTREAM_PLATFORM_KEY, "3.3");
+    }
+
+    @Test
+    public void createOfferingA() throws Exception {
+        final Path projectDir = newProjectDir(getClass().getSimpleName());
+        createProject(projectDir, List.of("ext-a", "ext-b"));
+
+        assertModel(projectDir,
+                List.of(mainPlatformBom(),
+                        platformMemberBomCoords("acme-a-bom"),
+                        platformMemberBomCoords("acme-b-bom")),
+                List.of(ArtifactCoords.jar("io.acme", "ext-a", null),
+                        ArtifactCoords.jar("io.acme", "ext-b", null)),
+                Map.of("quarkus.platform.group-id", UPSTREAM_PLATFORM_KEY,
+                        "quarkus.platform.artifact-id", "quarkus-bom",
+                        "quarkus.platform.version", "3.3.3"));
+    }
+}

independent-projects/tools/devtools-testing/src/test/java/io/quarkus/devtools/project/create/RecommendStreamsFromScenarioBase.java

@@ -0,0 +1,111 @@
+package io.quarkus.devtools.project.create;
+
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.BeforeEach;
+
+import io.quarkus.devtools.testing.registry.client.TestRegistryClientBuilder;
+
+public class RecommendStreamsFromScenarioBase extends MultiplePlatformBomsTestBase {
+    protected static final String UPSTREAM_PLATFORM_KEY = "io.upstream.platform";
+    protected static final String DOWNSTREAM_PLATFORM_KEY = "io.downstream.platform";
+
+    @BeforeEach
+    public void setup() throws Exception {
+        TestRegistryClientBuilder registryClientBuilder = TestRegistryClientBuilder.newInstance()
+                //.debug()
+                .baseDir(configDir());
+
+        var downstreamRegistry = registryClientBuilder
+                // registry
+                .newRegistry("downstream.registry.test")
+                .recognizedQuarkusVersions("*downstream");
+        setDownstreamRegistryExtraOptions(downstreamRegistry);
+
+        downstreamRegistry
+                // platform key
+                .newPlatform(DOWNSTREAM_PLATFORM_KEY)
+                .newStream("2.2")
+                // 2.2.2 release
+                .newRelease("2.2.2.downstream")
+                .quarkusVersion("2.2.2.downstream")
+                .upstreamQuarkusVersion("2.2.2")
+                // default bom including quarkus-core + essential metadata
+                .addCoreMember().release()
+                // platform member
+                .newMember("acme-a-bom")
+                .addExtensionWithMetadata("io.acme", "ext-a", "2.2.2.downstream",
+                        Map.of("offering-a-support", List.of("supported")))
+                .release()
+                .newMember("acme-b-bom")
+                .addExtensionWithMetadata("io.acme", "ext-b", "2.2.2.downstream",
+                        Map.of("offering-b-support", List.of("supported")))
+                .release().stream().platform()
+                .newStream("1.1")
+                // 1.1.1 release
+                .newRelease("1.1.1.downstream")
+                .quarkusVersion("1.1.1.downstream")
+                .upstreamQuarkusVersion("1.1.1")
+                // default bom including quarkus-core + essential metadata
+                .addCoreMember().release()
+                // platform member
+                .newMember("acme-a-bom")
+                .addExtensionWithMetadata("io.acme", "ext-a", "1.1.1.downstream",
+                        Map.of("offering-a-support", List.of("supported")))
+                .release()
+                .newMember("acme-b-bom")
+                .addExtensionWithMetadata("io.acme", "ext-b", "1.1.1.downstream",
+                        // on purpose included in offering-a
+                        Map.of("offering-a-support", List.of("supported")));
+
+        var upstreamRegistry = registryClientBuilder.newRegistry("upstream.registry.test");
+        setUpstreamRegistryExtraOptions(upstreamRegistry);
+
+        upstreamRegistry
+                // platform key
+                .newPlatform(UPSTREAM_PLATFORM_KEY)
+                // 3.3 STREAM
+                .newStream("3.3")
+                // 3.3.3 release
+                .newRelease("3.3.3")
+                .quarkusVersion("3.3.3")
+                // default bom including quarkus-core + essential metadata
+                .addCoreMember().release()
+                .newMember("acme-a-bom").addExtension("io.acme", "ext-a", "3.3.3").release()
+                .newMember("acme-b-bom").addExtension("io.acme", "ext-b", "3.3.3").release()
+                .stream().platform()
+                // 2.2 STREAM
+                .newStream("2.2")
+                // 2.2.2 release
+                .newRelease("2.2.2")
+                .quarkusVersion("2.2.2")
+                // default bom including quarkus-core + essential metadata
+                .addCoreMember().release()
+                .newMember("acme-a-bom").addExtension("io.acme", "ext-a", "2.2.2").release()
+                .newMember("acme-b-bom").addExtension("io.acme", "ext-b", "2.2.2").release()
+                .stream().platform()
+                // 1.1 STREAM
+                .newStream("1.1")
+                // 1.1.1 release
+                .newRelease("1.1.1")
+                .quarkusVersion("1.1.1")
+                // default bom including quarkus-core + essential metadata
+                .addCoreMember().release()
+                .newMember("acme-a-bom").addExtension("io.acme", "ext-a", "1.1.1").release()
+                .newMember("acme-b-bom").addExtension("io.acme", "ext-b", "1.1.1");
+
+        registryClientBuilder.build();
+        enableRegistryClient();
+    }
+
+    protected void setDownstreamRegistryExtraOptions(TestRegistryClientBuilder.TestRegistryBuilder registry) {
+    }
+
+    protected void setUpstreamRegistryExtraOptions(TestRegistryClientBuilder.TestRegistryBuilder registry) {
+    }
+
+    protected String getMainPlatformKey() {
+        return DOWNSTREAM_PLATFORM_KEY;
+    }
+}

independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/Constants.java

@@ -22,10 +22,15 @@ public interface Constants {
     String LAST_UPDATED = "last-updated";
 
     /**
-     * Registry configuration option allowing users to limit the extension catalog from a registry to a specific offering
+     * Registry client configuration option allowing users to limit the extension catalog from a registry to a specific offering
      */
     String OFFERING = "offering";
 
+    /**
+     * Registry client configuration option allowing users to set a low boundary for the recommended streams per platform
+     */
+    String RECOMMEND_STREAMS_FROM = "recommend-streams-from";
+
     /**
      * An internal key optionally added to extension metadata by a registry client
      * to indicate a user configured offering-based support key that should be displayed by extension listing commands