Make TestContainers DevService self-provisioning (#239)

* Make TestContainers DevService self-provisioning
* Make extension status stable
* Create scope and collection in TestContainer
* Map fixed ports if dynamic ports aren't used
* Initialize JacksonHelper at run-time

Author: emilienbev

deployment/src/main/java/com/couchbase/quarkus/extension/deployment/CouchbaseDevService.java

@@ -16,10 +16,13 @@
 package com.couchbase.quarkus.extension.deployment;
 
 import java.util.Map;
+import java.util.Optional;
 
 import jakarta.inject.Inject;
 
 import org.eclipse.microprofile.config.ConfigProvider;
+import org.jboss.logging.Logger;
+import org.testcontainers.couchbase.BucketDefinition;
 import org.testcontainers.couchbase.CouchbaseContainer;
 import org.testcontainers.couchbase.CouchbaseService;
 
@@ -39,6 +42,10 @@
 @BuildSteps(onlyIfNot = IsNormal.class, onlyIf = DevServicesConfig.Enabled.class)
 public class CouchbaseDevService {
 
+    private static final Logger log = Logger.getLogger(CouchbaseDevService.class);
+    private static final String DEFAULT_USERNAME = "Administrator";
+    private static final String DEFAULT_PASSWORD = "password";
+
     static volatile RunningDevService devService;
 
     @Inject
@@ -47,20 +54,36 @@ public class CouchbaseDevService {
     @BuildStep
     DevServicesResultBuildItem startCouchBase(
             CuratedApplicationShutdownBuildItem closeBuildItem) {
+
+        if (ConfigProvider.getConfig()
+                .getOptionalValue("quarkus.couchbase.connection-string", String.class)
+                .filter(connectionString -> !connectionString.isBlank())
+                .isPresent()) {
+            log.info("quarkus.couchbase.connection-string is set, skipping TestContainer deployment.");
+            return null;
+        }
+
         if (devService != null) {
             return devService.toBuildItem();
         }
-        QuarkusCouchbaseContainer couchbase = startContainer();
-
-        Map<String, String> dynamicConfig = Map.of();
-        if (buildTimeConfig.useDynamicPorts()) {
-            // Capture the dynamic connection string and UI port from the running container
-            String connectionString = couchbase.getConnectionString();
-            int uiPort = couchbase.getMappedPort(8091);
-            dynamicConfig = Map.of(
-                    "quarkus.couchbase.connection-string", connectionString,
-                    "quarkus.couchbase.devservices.ui-port", String.valueOf(uiPort));
-        }
+
+        // Credentials are required runtime config, but when DevServices provisions a container we
+        // supply them ourselves (defaulting if unset) and inject the same values at runtime so the
+        // app needs no credential configuration to connect to the container.
+        var config = ConfigProvider.getConfig();
+        String username = config.getOptionalValue("quarkus.couchbase.username", String.class).orElse(DEFAULT_USERNAME);
+        String password = config.getOptionalValue("quarkus.couchbase.password", String.class).orElse(DEFAULT_PASSWORD);
+
+        QuarkusCouchbaseContainer couchbase = startContainer(username, password);
+
+        // The container always determines the connection string and UI port whether
+        // dynamic or fixed, so we inject both at runtime. Since we only reach this point when no
+        // connection string was set, we can safely set it.
+        Map<String, String> dynamicConfig = Map.of(
+                "quarkus.couchbase.connection-string", couchbase.getConnectionString(),
+                "quarkus.couchbase.username", username,
+                "quarkus.couchbase.password", password,
+                "quarkus.couchbase.devservices.ui-port", String.valueOf(couchbase.getMappedPort(8091)));
 
         // Pass the dynamic values via config overrides so they're available at runtime
         devService = new RunningDevService(CouchbaseQuarkusExtensionProcessor.FEATURE,
@@ -70,15 +93,14 @@ DevServicesResultBuildItem startCouchBase(
 
     }
 
-    private QuarkusCouchbaseContainer startContainer() {
-        // Credentials are runtime config (CouchbaseRuntimeConfig), but the dev-services container
-        // needs to provision them at build time. Read directly from the config provider — these
-        // are sourced from application.properties, so they're visible during the build phase.
-        var config = ConfigProvider.getConfig();
-        String username = config.getValue("quarkus.couchbase.username", String.class);
-        String password = config.getValue("quarkus.couchbase.password", String.class);
+    private QuarkusCouchbaseContainer startContainer(String username, String password) {
+        // bucket-name is runtime config but sourced from application.properties, so it's visible
+        // during the build phase. Provision that bucket so an injected Bucket bean is usable.
+        Optional<String> bucketName = ConfigProvider.getConfig()
+                .getOptionalValue("quarkus.couchbase.bucket-name", String.class)
+                .filter(name -> !name.isBlank());
         QuarkusCouchbaseContainer couchbase = new QuarkusCouchbaseContainer(buildTimeConfig.version(), username, password,
-                buildTimeConfig.useDynamicPorts());
+                buildTimeConfig.useDynamicPorts(), bucketName);
         couchbase.start();
         return couchbase;
     }
@@ -105,18 +127,23 @@ private static class QuarkusCouchbaseContainer extends CouchbaseContainer {
         private static final int KV_PORT = 11210;
         private static final int KV_SSL_PORT = 11207;
 
-        public QuarkusCouchbaseContainer(String version, String userName, String password, boolean useDynamicPorts) {
+        private final boolean useDynamicPorts;
+
+        public QuarkusCouchbaseContainer(String version, String userName, String password, boolean useDynamicPorts,
+                Optional<String> bucketName) {
             super("couchbase/server:" + version);
+            this.useDynamicPorts = useDynamicPorts;
             withCredentials(userName, password);
             // we enable all non-enterprise services because we don't know which ones are needed
             withEnabledServices(CouchbaseService.EVENTING, CouchbaseService.INDEX, CouchbaseService.KV,
                     CouchbaseService.QUERY, CouchbaseService.SEARCH);
 
+            bucketName.ifPresent(name -> withBucket(new BucketDefinition(name)));
+
             if (!useDynamicPorts) {
-                // Fixed ports mode - map container ports to same host ports
+                // Fixed ports mode, map container ports to the same host ports.
                 addFixedExposedPort(MGMT_PORT, MGMT_PORT);
                 addFixedExposedPort(MGMT_SSL_PORT, MGMT_SSL_PORT);
-                addFixedExposedPort(ANALYTICS_PORT, ANALYTICS_PORT);
                 addFixedExposedPort(VIEW_PORT, VIEW_PORT);
                 addFixedExposedPort(VIEW_SSL_PORT, VIEW_SSL_PORT);
                 addFixedExposedPort(ANALYTICS_PORT, ANALYTICS_PORT);
@@ -131,5 +158,14 @@ public QuarkusCouchbaseContainer(String version, String userName, String passwor
                 addFixedExposedPort(KV_SSL_PORT, KV_SSL_PORT);
             }
         }
+
+        /**
+         * In fixed-ports mode, return the original port instead of the parent's random mapping so the
+         * container's advertised ports, bindings, and connection string all stay consistent.
+         */
+        @Override
+        public Integer getMappedPort(int originalPort) {
+            return useDynamicPorts ? super.getMappedPort(originalPort) : originalPort;
+        }
     }
 }

deployment/src/main/java/com/couchbase/quarkus/extension/deployment/CouchbaseProcessor.java

@@ -198,7 +198,10 @@ void configureRuntimeInitializedClasses(BuildProducer<RuntimeInitializedClassBui
                 "com.couchbase.client.core.io.netty.SslHandlerFactory$InitOnDemandHolder",
                 "com.couchbase.client.core.cnc.apptelemetry.reporter.AppTelemetryReporterImpl", // has static Random instance
                 "com.couchbase.client.core.deps.io.netty.handler.ssl.ReferenceCountedOpenSslEngine",
-                "com.couchbase.client.core.endpoint.http.CoreHttpRequest$Builder");
+                "com.couchbase.client.core.endpoint.http.CoreHttpRequest$Builder",
+                // has a static JsonMapper (from the shaded Jackson) used to parse the cluster config.
+                // At build time it captures a live ForkJoinWorkerThread into the heap, which breaks native compilation
+                "com.couchbase.client.core.topology.JacksonHelper");
 
         for (String className : classes) {
             runtimeInitialized.produce(new RuntimeInitializedClassBuildItem(className));

docs/modules/ROOT/pages/configuration.adoc

@@ -4,7 +4,6 @@ Full details can be found in the https://javadoc.io/doc/io.quarkiverse.couchbase
 
 Currently, a minimal set of configuration options for the `Cluster` bean is provided.
 
-[IMPORTANT]
 ====
 Configuration options fall into two categories that differ in *when* they take effect:
 
@@ -27,11 +26,13 @@ These config items do not default to placeholder values, and are required to be
 
 * `quarkus.couchbase.connection-string`
 ** *String*: Examples `localhost`, `couchbase://127.0.0.1`.
-** *Note*: Optional when DevServices are enabled with dynamic ports. DevServices will automatically set this value.
+** *Note*: This should be unset if using DevServices, else the TestContainer won't start.
 * `quarkus.couchbase.username`
 ** *String*: The username to authenticate with.
+** *Note*: Not required when DevServices starts a container, injected to `Administrator`.
 * `quarkus.couchbase.password`
 ** *String*: The password to authenticate with.
+** *Note*: Not required when DevServices starts a container injected to `password`.
 
 == Optional
 These config items have default values, but can be overridden in `application.properties`.
@@ -49,7 +50,7 @@ These config items have default values, but can be overridden in `application.pr
 ** *Seconds*: The interval at which metrics are emitted.
 ** *Default*: `600` (10min)
 * `quarkus.couchbase.bucket-name`
-** *String*: A bucket exposed as an injectable `Bucket` bean. Only required if a `Bucket` is injected.
+** *String*: A bucket exposed as an injectable `Bucket` bean. Only required if a `Bucket` is injected. When DevServices starts a container, this bucket is also provisioned in it so the injected `Bucket` is immediately usable. If unset, DevServices creates no bucket.
 ** *Default*: None
 * `quarkus.couchbase.preferredServerGroup`
 ** *String*: The preferred server group for operations which support it.

docs/modules/ROOT/pages/index.adoc

@@ -10,7 +10,7 @@ include::./includes/attributes.adoc[]
 
 Integrates Couchbase into Quarkus.
 
-This extension is currently in beta status. It supports:
+This extension currently supports:
 
 - Dependency injecting a Couchbase `Cluster`.
 - Configuring the Cluster through `application.properties`. Currently, a minimal set of configuration options is provided.
@@ -82,6 +82,12 @@ public class TestCouchbaseResource {
 
 And test it at http://localhost:8080/couchbase/test.
 
+== Dev Services
+
+DevServices (Couchbase TestContainers) activate when `quarkus.devservices.enabled` is `true` and no `quarkus.couchbase.connection-string` is set.
+
+Setting `quarkus.couchbase.connection-string` (for example to point at a real cluster or Capella) disables DevServices.
+
 == Micrometer Metrics
 
 You can enable Micrometer metrics by adding the following dependencies to your application:

integration-tests/pom.xml

@@ -20,7 +20,7 @@
     </dependency>
     <dependency>
       <groupId>io.quarkus</groupId>
-      <artifactId>quarkus-junit5</artifactId>
+      <artifactId>quarkus-junit</artifactId>
       <version>${quarkus.version}</version>
       <scope>test</scope>
     </dependency>
@@ -88,7 +88,6 @@
             <configuration>
               <systemPropertyVariables>
                 <quarkus.couchbase.devservices.use-dynamic-ports>false</quarkus.couchbase.devservices.use-dynamic-ports>
-                <quarkus.couchbase.connection-string>couchbase://localhost</quarkus.couchbase.connection-string>
               </systemPropertyVariables>
               <reportNameSuffix>fixed-ports</reportNameSuffix>
             </configuration>

integration-tests/src/test/java/com/couchbase/quarkus/extension/it/DevServiceTest.java

@@ -82,33 +82,42 @@ public DevServiceTest(Cluster cluster, Bucket injectedBucket) {
 
     @BeforeAll
     void createAndGetKeyspace() {
-        var isKeyspacePresent = false;
-
-        // Checks if the test bucket already exists, assuming the
-        // scope and collection must exist with it. Relevant for continuous testing.
         try {
             cluster.buckets().createBucket(BucketSettings.create(BUCKET_NAME));
+            ConsistencyUtil.waitUntilBucketPresent(cluster.core(), BUCKET_NAME);
         } catch (BucketExistsException exists) {
-            isKeyspacePresent = true;
-            logger.info("Bucket already exists, skipping keyspace creation.");
+            logger.info("Bucket already exists, skipping bucket creation.");
         }
-        // Create Bucket, Scope and Collection
-        if (!isKeyspacePresent) {
-            ConsistencyUtil.waitUntilBucketPresent(cluster.core(), BUCKET_NAME);
-            bucket = cluster.bucket(BUCKET_NAME);
-            bucket.waitUntilReady(Duration.ofSeconds(20));
+
+        bucket = cluster.bucket(BUCKET_NAME);
+        bucket.waitUntilReady(Duration.ofSeconds(20));
+
+        if (!scopeExists(SCOPE_NAME)) {
             bucket.collections().createScope(SCOPE_NAME);
             ConsistencyUtil.waitUntilScopePresent(cluster.core(), BUCKET_NAME, SCOPE_NAME);
+        }
+
+        if (!collectionExists(SCOPE_NAME, COLLECTION_NAME)) {
             bucket.collections().createCollection(SCOPE_NAME, COLLECTION_NAME);
             ConsistencyUtil.waitUntilCollectionPresent(cluster.core(), BUCKET_NAME, SCOPE_NAME, COLLECTION_NAME);
-        } else {
-            bucket = cluster.bucket(BUCKET_NAME);
         }
 
         scope = bucket.scope(SCOPE_NAME);
         collection = scope.collection(COLLECTION_NAME);
     }
 
+    private boolean scopeExists(String scopeName) {
+        return bucket.collections().getAllScopes().stream()
+                .anyMatch(s -> s.name().equals(scopeName));
+    }
+
+    private boolean collectionExists(String scopeName, String collectionName) {
+        return bucket.collections().getAllScopes().stream()
+                .filter(s -> s.name().equals(scopeName))
+                .flatMap(s -> s.collections().stream())
+                .anyMatch(c -> c.name().equals(collectionName));
+    }
+
     @Test
     void injectedBucketBeanIsUsable() {
         assertEquals(BUCKET_NAME, injectedBucket.name());

runtime/src/main/java/com/couchbase/quarkus/extension/runtime/CouchbaseRuntimeConfig.java

@@ -35,11 +35,13 @@ public interface CouchbaseRuntimeConfig {
 
     /**
      * The username to authenticate with.
+     * Required, except when DevServices starts a container, in which case it is injected
      */
     String username();
 
     /**
      * The password to authenticate with.
+     * Required, except when DevServices starts a container, in which case it is injected
      */
     String password();
 

runtime/src/main/resources/META-INF/quarkus-extension.yaml

@@ -12,4 +12,4 @@ metadata:
   config:
     - "quarkus.couchbase."
   iconUrl: "https://raw.githubusercontent.com/quarkiverse/quarkus-couchbase/master/docs/modules/ROOT/assets/images/couchbase-filled.svg"
-  status: "preview"
+  status: "stable"