Merge pull request #50897 from radcortez/redis-enable-disable

Support runtime active / inactive Redis Clients

Author: Ladicek

docs/src/main/asciidoc/redis-reference.adoc

@@ -138,6 +138,70 @@ public class RedisExample {
 
 TIP: You can omit the `@Inject` annotation when using `@RedisClientName`.
 
+=== Activate or deactivate Redis Clients
+
+When a Redis Clients is configured at build time, and its URL is set at runtime, it is active by default. Quarkus
+starts the corresponding Redis Client when the application starts.
+
+To deactivate a Redis Client at runtime, either:
+
+* Do not set `quarkus.redis[.optional name].hosts` or `quarkus.redis[.optional name].hosts-provider-name`.
+* Set `quarkus.redis[.optional name].active` to `false`.
+
+If a Redis Client is not active:
+
+* The Redis Client does not attempt to connect to Redis during application startup.
+* The Redis Client does not contribute a <<redis-health-check,health check>>.
+* Static CDI injection points involving the Redis Client, such as `@Inject ReactiveRedisDataSource redis` or `@Inject RedisDataSource redis`, cause application startup to fail.
+* Dynamic retrieval of the Redis Client, such as through `CDI.getBeanContainer()`, `Arc.instance()`, or an injected `Instance<ReactiveRedisDataSource>`, causes an exception to be thrown.
+* Other Quarkus extensions that consume the Redis Client may cause application startup to fail.
+
+This feature is especially useful when the application must dynamically select a Redis Client from a predefined set at
+runtime.
+
+.An example of configuring multiple Redis Clients for runtime selection:
+
+[source,properties]
+----
+quarkus.redis.one.active=false
+quarkus.redis.one.hosts=redis://localhost:64251
+
+quarkus.redis.two.active=false
+quarkus.redis.two.hosts=redis://localhost:64251
+----
+
+[source,java]
+----
+import io.quarkus.arc.InjectableInstance;
+
+@ApplicationScoped
+public class MyConsumer {
+    @Inject
+    @RedisClientName("one")
+    InjectableInstance<ReactiveRedisDataSource> one;
+    @Inject
+    @RedisClientName("two")
+    InjectableInstance<ReactiveRedisDataSource> two;
+
+    public void doSomething() {
+        ReactiveRedisDataSource redis = one.getActive();
+        // ...
+    }
+}
+----
+
+Setting `quarkus.redis.one.active=true` xref:config-reference.adoc#configuration-sources[at runtime] makes only the
+Redis Client `one` available.
+Setting `quarkus.redis.two.active=true` at runtime makes only the Redis Client `two` available.
+
+[IMPORTANT]
+====
+A Redis Client (either default or named) must always be discoverable at build-time to be considered for runtime
+injection. This can be done by injecting the Redis Client name with `@RedisClientName`. If the Redis Client name may be
+active or inactive, it needs to use the wrapper `InjectableInstance<>`, or else Quarkus will throw an exception at
+startup time if the Redis Client is inactive. Alternatively, Redis Clients may also be discovered via configuration.
+====
+
 == Connect to the Redis server
 
 The Redis extension can operate in 4 distinct modes:
@@ -1014,6 +1078,7 @@ See xref:redis-dev-services.adoc[Redis Dev Service].
 
 == Configure Redis observability
 
+[[redis-health-check]]
 === Enable the health checks
 
 If you are using the `quarkus-smallrye-health` extension, `quarkus-redis` will automatically add a readiness health check to validate the connection to the Redis server.

extensions/redis-client/deployment/src/main/java/io/quarkus/redis/deployment/client/DevServicesRedisProcessor.java

@@ -2,12 +2,14 @@
 
 import static io.quarkus.devservices.common.ConfigureUtil.configureSharedServiceLabel;
 import static io.quarkus.devservices.common.ContainerLocator.locateContainerWithLabels;
+import static io.quarkus.redis.runtime.client.config.RedisConfig.HOSTS;
+import static io.quarkus.redis.runtime.client.config.RedisConfig.getPropertyName;
 
-import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
-import java.util.Map.Entry;
 import java.util.OptionalInt;
+import java.util.Set;
 
 import org.jboss.logging.Logger;
 import org.testcontainers.containers.GenericContainer;
@@ -28,7 +30,6 @@
 import io.quarkus.devservices.common.ComposeLocator;
 import io.quarkus.devservices.common.ConfigureUtil;
 import io.quarkus.devservices.common.ContainerLocator;
-import io.quarkus.redis.deployment.client.RedisBuildTimeConfig.DevServiceConfiguration;
 import io.quarkus.redis.runtime.client.config.RedisConfig;
 import io.quarkus.runtime.LaunchMode;
 import io.quarkus.runtime.configuration.ConfigUtils;
@@ -50,9 +51,6 @@ public class DevServicesRedisProcessor {
     private static final ContainerLocator redisContainerLocator = locateContainerWithLabels(REDIS_EXPOSED_PORT,
             DEV_SERVICE_LABEL);
 
-    private static final String QUARKUS = "quarkus.";
-    private static final String DOT = ".";
-
     @BuildStep
     public void startRedisContainers(LaunchModeBuildItem launchMode,
             DockerStatusBuildItem dockerStatusBuildItem,
@@ -62,23 +60,21 @@ public void startRedisContainers(LaunchModeBuildItem launchMode,
             BuildProducer<DevServicesResultBuildItem> devServicesResult,
             DevServicesConfig devServicesConfig) {
 
-        Map<String, DevServiceConfiguration> currentDevServicesConfiguration = new HashMap<>(config.additionalDevServices());
-        currentDevServicesConfiguration.put(RedisConfig.DEFAULT_CLIENT_NAME, config.defaultDevService());
+        Set<String> names = new HashSet<>(config.clients().keySet());
+        names.add(RedisConfig.DEFAULT_CLIENT_NAME);
 
         try {
-            for (Entry<String, DevServiceConfiguration> entry : currentDevServicesConfiguration.entrySet()) {
-                String name = entry.getKey();
+            for (String name : names) {
                 boolean useSharedNetwork = DevServicesSharedNetworkBuildItem.isSharedNetworkRequired(devServicesConfig,
                         devServicesSharedNetworkBuildItem);
 
-                String configPrefix = getConfigPrefix(name);
-                io.quarkus.redis.deployment.client.DevServicesConfig redisConfig = entry.getValue().devservices();
-                if (redisDevServicesEnabled(dockerStatusBuildItem, name, redisConfig, configPrefix)) {
+                io.quarkus.redis.deployment.client.DevServicesConfig redisConfig = config.clients().get(name).devservices();
+                if (redisDevServicesEnabled(dockerStatusBuildItem, name, redisConfig)) {
                     // If the dev services are disabled, we don't need to do anything
                     continue;
                 }
 
-                DevServicesResultBuildItem discovered = discoverRunningService(composeProjectBuildItem, configPrefix,
+                DevServicesResultBuildItem discovered = discoverRunningService(composeProjectBuildItem, name,
                         redisConfig, launchMode.getLaunchMode(), useSharedNetwork);
                 if (discovered != null) {
                     devServicesResult.produce(discovered);
@@ -97,15 +93,14 @@ public void startRedisContainers(LaunchModeBuildItem launchMode,
                                             // Dev Service discovery works using a global dev service label applied in DevServicesCustomizerBuildItem
                                             // for backwards compatibility we still add the custom label
                                             .withSharedServiceLabel(launchMode.getLaunchMode(), redisConfig.serviceName()))
-                                    .configProvider(Map.of(configPrefix + RedisConfig.HOSTS_CONFIG_NAME,
-                                            s -> REDIS_SCHEME + s.getConnectionInfo()))
+                                    .configProvider(
+                                            Map.of(getPropertyName(name, HOSTS), s -> REDIS_SCHEME + s.getConnectionInfo()))
                                     .build());
                 }
             }
         } catch (Throwable t) {
             throw new RuntimeException(t);
         }
-
     }
 
     /**
@@ -127,7 +122,7 @@ public void startRedisContainers(LaunchModeBuildItem launchMode,
      * extra sure we'd put on a special 'not external' label and filter for that, too
      */
     private DevServicesResultBuildItem discoverRunningService(DevServicesComposeProjectBuildItem composeProjectBuildItem,
-            String configPrefix,
+            String name,
             io.quarkus.redis.deployment.client.DevServicesConfig devServicesConfig,
             LaunchMode launchMode,
             boolean useSharedNetwork) {
@@ -140,22 +135,22 @@ private DevServicesResultBuildItem discoverRunningService(DevServicesComposeProj
                     return DevServicesResultBuildItem.discovered()
                             .feature(Feature.REDIS_CLIENT)
                             .containerId(containerAddress.getId())
-                            .config(Map.of(configPrefix + RedisConfig.HOSTS_CONFIG_NAME, redisUrl))
+                            .config(Map.of(RedisConfig.getPropertyName(name, HOSTS), redisUrl))
                             .build();
                 }).orElse(null);
     }
 
     private static boolean redisDevServicesEnabled(DockerStatusBuildItem dockerStatusBuildItem, String name,
-            io.quarkus.redis.deployment.client.DevServicesConfig devServicesConfig,
-            String configPrefix) {
+            io.quarkus.redis.deployment.client.DevServicesConfig devServicesConfig) {
         if (!devServicesConfig.enabled()) {
             // explicitly disabled
             log.debug("Not starting devservices for " + (RedisConfig.isDefaultClient(name) ? "default redis client" : name)
                     + " as it has been disabled in the config");
             return true;
         }
 
-        boolean needToStart = !ConfigUtils.isPropertyNonEmpty(configPrefix + RedisConfig.HOSTS_CONFIG_NAME);
+        // TODO - We shouldn't query runtime config during deployment
+        boolean needToStart = !ConfigUtils.isPropertyNonEmpty(RedisConfig.getPropertyName(name, HOSTS));
         if (!needToStart) {
             log.debug("Not starting dev services for " + (RedisConfig.isDefaultClient(name) ? "default redis client" : name)
                     + " as hosts have been provided");
@@ -171,14 +166,6 @@ private static boolean redisDevServicesEnabled(DockerStatusBuildItem dockerStatu
         return false;
     }
 
-    private String getConfigPrefix(String name) {
-        String configPrefix = QUARKUS + RedisConfig.REDIS_CONFIG_ROOT_NAME + DOT;
-        if (!RedisConfig.isDefaultClient(name)) {
-            configPrefix = configPrefix + name + DOT;
-        }
-        return configPrefix;
-    }
-
     private static class QuarkusPortRedisContainer extends GenericContainer<QuarkusPortRedisContainer> implements Startable {
         private final OptionalInt fixedExposedPort;
         private final boolean useSharedNetwork;

extensions/redis-client/deployment/src/main/java/io/quarkus/redis/deployment/client/RedisBuildTimeConfig.java

@@ -1,86 +1,95 @@
 package io.quarkus.redis.deployment.client;
 
+import static io.quarkus.redis.runtime.client.config.RedisConfig.DEFAULT_CLIENT_NAME;
+
+import java.util.ArrayList;
+import java.util.List;
 import java.util.Map;
 
 import io.quarkus.runtime.annotations.ConfigDocMapKey;
-import io.quarkus.runtime.annotations.ConfigDocSection;
-import io.quarkus.runtime.annotations.ConfigGroup;
 import io.quarkus.runtime.annotations.ConfigPhase;
 import io.quarkus.runtime.annotations.ConfigRoot;
 import io.smallrye.config.ConfigMapping;
 import io.smallrye.config.WithDefault;
+import io.smallrye.config.WithDefaults;
 import io.smallrye.config.WithName;
 import io.smallrye.config.WithParentName;
+import io.smallrye.config.WithUnnamedKey;
 
 @ConfigMapping(prefix = "quarkus.redis")
 @ConfigRoot(phase = ConfigPhase.BUILD_TIME)
 public interface RedisBuildTimeConfig {
-
-    /**
-     * The default redis client
-     */
-    @WithParentName
-    RedisClientBuildTimeConfig defaultRedisClient();
-
     /**
-     * Configures additional (named) Redis clients.
+     * Configures the Redis clients.
      * <p>
-     * Each client has a unique name which must be identified to select the right client.
-     * For example:
+     * The default client does not have a name, and it is configured as:
+     *
+     * <pre>
+     * quarkus.redis.hosts = redis://localhost:6379
+     * </pre>
+     *
+     * And then use {@link jakarta.inject.Inject} to inject the client:
+     *
+     * <pre>
+     * &#64;Inject
+     * RedisAPI redis;
+     * </pre>
+     *
      * <p>
+     * Named clients must be identified to select the right client:
      *
      * <pre>
      * quarkus.redis.client1.hosts = redis://localhost:6379
      * quarkus.redis.client2.hosts = redis://localhost:6380
      * </pre>
-     * <p>
-     * And then use the {@link io.quarkus.redis.client.RedisClientName} annotation to select the
-     * {@link io.vertx.mutiny.redis.client.Redis},
-     * {@link io.vertx.redis.client.Redis}, {@link io.vertx.mutiny.redis.client.RedisAPI} and
-     * {@link io.vertx.redis.client.RedisAPI} beans.
-     * <p>
+     *
+     * And then use the {@link io.quarkus.redis.client.RedisClientName} annotation to select any of the beans:
+     * <ul>
+     * <li>{@link io.vertx.mutiny.redis.client.Redis}</li>
+     * <li>{@link io.vertx.redis.client.Redis}</li>
+     * <li>{@link io.vertx.mutiny.redis.client.RedisAPI}</li>
+     * <li>{@link io.vertx.redis.client.RedisAPI}</li>
+     * <li>{@link io.quarkus.redis.datasource.RedisDataSource}</li>
+     * <li>{@link io.quarkus.redis.datasource.ReactiveRedisDataSource}</li>
+     * </ul>
+     * And inject the client:
      *
      * <pre>
-     * {
-     *     &#64;code
-     *     &#64;RedisClientName("client1")
-     *     &#64;Inject
-     *     RedisAPI redis;
-     * }
+     * &#64;RedisClientName("client1")
+     * &#64;Inject
+     * RedisAPI redis;
      * </pre>
      */
     @WithParentName
+    @WithDefaults
+    @WithUnnamedKey(DEFAULT_CLIENT_NAME)
     @ConfigDocMapKey("redis-client-name")
-    Map<String, RedisClientBuildTimeConfig> namedRedisClients();
+    Map<String, RedisClientBuildTimeConfig> clients();
+
+    /**
+     * Returns a {@code List} of Redis Client names. The first element of the list is the default Redis Client if
+     * available. The remaining order is unspecified.
+     *
+     * @return a {@code List} of Redis Client names
+     */
+    default List<String> clientsNames() {
+        List<String> names = new ArrayList<>();
+        if (clients().containsKey(DEFAULT_CLIENT_NAME)) {
+            names.add(DEFAULT_CLIENT_NAME);
+        }
+        for (String name : clients().keySet()) {
+            if (name.equals(DEFAULT_CLIENT_NAME)) {
+                continue;
+            }
+            names.add(name);
+        }
+        return names;
+    }
 
     /**
      * Whether a health check is published in case the smallrye-health extension is present.
      */
     @WithName("health.enabled")
     @WithDefault("true")
     boolean healthEnabled();
-
-    /**
-     * Default Dev services configuration.
-     */
-    @WithParentName
-    DevServiceConfiguration defaultDevService();
-
-    /**
-     * Additional dev services configurations
-     */
-    @WithParentName
-    @ConfigDocMapKey("additional-redis-clients")
-    Map<String, DevServiceConfiguration> additionalDevServices();
-
-    @ConfigGroup
-    public interface DevServiceConfiguration {
-        /**
-         * Dev Services
-         * <p>
-         * Dev Services allows Quarkus to automatically start Redis in dev and test mode.
-         */
-        @ConfigDocSection(generated = true)
-        DevServicesConfig devservices();
-    }
 }

extensions/redis-client/deployment/src/main/java/io/quarkus/redis/deployment/client/RedisClientBuildTimeConfig.java

@@ -4,14 +4,14 @@
 import java.util.Optional;
 
 import io.quarkus.runtime.annotations.ConfigDocDefault;
+import io.quarkus.runtime.annotations.ConfigDocSection;
 import io.quarkus.runtime.annotations.ConfigGroup;
 import io.quarkus.runtime.configuration.TrimmedStringConverter;
 import io.smallrye.config.WithConverter;
 import io.smallrye.config.WithDefault;
 
 @ConfigGroup
 public interface RedisClientBuildTimeConfig {
-
     /**
      * A list of files allowing to pre-load data into the Redis server.
      * The file is formatted as follows:
@@ -38,4 +38,9 @@ public interface RedisClientBuildTimeConfig {
     @WithDefault("true")
     boolean loadOnlyIfEmpty();
 
+    /**
+     * Dev Services allows Quarkus to automatically start Redis in dev and test mode.
+     */
+    @ConfigDocSection(generated = true)
+    DevServicesConfig devservices();
 }