JVMCBC-1665 Let internal Couchbase products bypass cluster type check

Modifications
-------------
Add AnalyticsAccessor.skipClusterTypeCheck().
Internal projects can call this to disable
the check that prevents the operational SDK
from executing queries against Enterprise Analytics.

Model the `prodName` field of the cluster topology JSON
as a new `ClusterType` class.

Rename ClusterIdentifier.prodName() -> clusterType(),
and modify it to always return a non-null value.
If the value would previously have been null,
assume ClusterType.COUCHBASE_SERVER.

Extract the cluster type check into a new method:
requireCouchbaseServer().

Change-Id: I389ccf6d64f780525b62a8d9cd3c261f2d146200
Reviewed-on: https://review.couchbase.org/c/couchbase-jvm-clients/+/229924
Reviewed-by: Michael Reiche <[email protected]>
Tested-by: Build Bot <[email protected]>

Author: dnault

core-io/src/main/java/com/couchbase/client/core/topology/ClusterIdentifier.java

@@ -15,35 +15,36 @@
  */
 package com.couchbase.client.core.topology;
 
-import com.couchbase.client.core.annotation.SinceCouchbase;
 import com.couchbase.client.core.annotation.Stability;
 import com.couchbase.client.core.deps.com.fasterxml.jackson.databind.JsonNode;
 import com.couchbase.client.core.deps.com.fasterxml.jackson.databind.node.ObjectNode;
 import org.jspecify.annotations.Nullable;
 
 import static com.couchbase.client.core.logging.RedactableArgument.redactMeta;
+import static java.util.Objects.requireNonNull;
 
 @Stability.Internal
 public class ClusterIdentifier {
   private final String clusterUuid;
   private final String clusterName;
-  @SinceCouchbase("8.0")
-  private final @Nullable String prodName;
+  private final ClusterType clusterType;
 
-  ClusterIdentifier(String clusterUuid, String clusterName, @Nullable String prodName) {
-    this.clusterUuid = clusterUuid;
-    this.clusterName = clusterName;
-    this.prodName = prodName;
+  ClusterIdentifier(String clusterUuid, String clusterName, ClusterType product) {
+    this.clusterUuid = requireNonNull(clusterUuid);
+    this.clusterName = requireNonNull(clusterName);
+    this.clusterType = requireNonNull(product);
   }
 
   public static @Nullable ClusterIdentifier parse(ObjectNode config) {
     JsonNode clusterUuid = config.path("clusterUUID");
     JsonNode clusterName = config.path("clusterName");
-    JsonNode prodName = config.path("prodName");
     if (clusterUuid.isMissingNode() || clusterName.isMissingNode()) {
       return null;
     }
-    return new ClusterIdentifier(clusterUuid.asText(), clusterName.asText(), prodName.isMissingNode() ? null : prodName.asText());
+
+    JsonNode prodName = config.path("prodName"); // field added in Couchbase Server 8.0.
+    ClusterType type = ClusterType.of(prodName.textValue());
+    return new ClusterIdentifier(clusterUuid.asText(), clusterName.asText(), type);
   }
 
   public String clusterUuid() {
@@ -54,16 +55,16 @@ public String clusterName() {
     return clusterName;
   }
 
-  public @Nullable String prodName() {
-    return prodName;
+  public ClusterType clusterType() {
+    return clusterType;
   }
 
   @Override
   public String toString() {
     return "ClusterIdent{" +
       "clusterUuid='" + clusterUuid + '\'' +
       ", clusterName='" + redactMeta(clusterName) + '\'' +
-      ", prodName='" + prodName + '\'' +
+      ", clusterType='" + clusterType + '\'' +
       '}';
   }
 }

core-io/src/main/java/com/couchbase/client/core/topology/ClusterProdName.java

@@ -44,7 +44,7 @@ public final class ClusterTopologyBuilder {
   private NetworkResolution networkResolution = NetworkResolution.DEFAULT;
   private String clusterName = "fake-cluster";
   private String clusterUuid = "fake-cluster-uuid";
-  private String prodName = ClusterProdName.COUCHBASE_SERVER;
+  private ClusterType clusterType = ClusterType.COUCHBASE_SERVER;
   private Set<ClusterCapability> capabilities = EnumSet.allOf(ClusterCapability.class);
   private final List<HostAndServicePorts> nodes = new ArrayList<>();
 
@@ -55,7 +55,7 @@ public ClusterTopology build() {
   private ClusterTopology buildWithOrWithoutBucket(@Nullable BucketTopology bucket) {
     return ClusterTopology.of(
       revision,
-      new ClusterIdentifier(clusterUuid, clusterName, prodName),
+      new ClusterIdentifier(clusterUuid, clusterName, clusterType),
       nodes,
       capabilities,
       networkResolution,

core-io/src/main/java/com/couchbase/client/core/topology/ClusterTopologyBuilder.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2025 Couchbase, Inc.
+ *
+ * Licensed 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
+ *
+ * https://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 com.couchbase.client.core.topology;
+
+import com.couchbase.client.core.annotation.Stability;
+import org.jspecify.annotations.Nullable;
+
+import static java.util.Objects.requireNonNull;
+
+/**
+ * Sourced from the "prodName" (product name) field of the cluster topology JSON.
+ */
+@Stability.Internal
+public class ClusterType {
+  private static final String COUCHBASE_SERVER_NAME = "Couchbase Server";
+
+  public static ClusterType COUCHBASE_SERVER = new ClusterType(COUCHBASE_SERVER_NAME);
+
+  private final String name;
+  private final boolean couchbaseServer;
+
+  private ClusterType(String name) {
+    this.name = requireNonNull(name);
+    this.couchbaseServer = name.startsWith(COUCHBASE_SERVER_NAME);
+  }
+
+  public boolean isCouchbaseServer() {
+    return couchbaseServer;
+  }
+
+  public static ClusterType from(@Nullable ClusterIdentifier id) {
+    return id == null ? of(null) : id.clusterType();
+  }
+
+  public static ClusterType of(@Nullable String name) {
+    return name == null || name.equals(COUCHBASE_SERVER_NAME)
+      ? COUCHBASE_SERVER
+      : new ClusterType(name);
+  }
+
+  public String name() {
+    return name;
+  }
+
+  @Override
+  public String toString() {
+    return name;
+  }
+}

core-io/src/main/java/com/couchbase/client/core/topology/ClusterType.java

@@ -18,22 +18,37 @@
 
 import com.couchbase.client.core.Core;
 import com.couchbase.client.core.Reactor;
+import com.couchbase.client.core.annotation.Stability;
 import com.couchbase.client.core.error.CouchbaseException;
 import com.couchbase.client.core.msg.analytics.AnalyticsRequest;
 import com.couchbase.client.core.msg.analytics.AnalyticsResponse;
-import com.couchbase.client.core.topology.ClusterProdName;
+import com.couchbase.client.core.topology.ClusterType;
 import com.couchbase.client.java.codec.JsonSerializer;
 import reactor.core.publisher.Mono;
 
+import java.time.Duration;
 import java.util.concurrent.CompletableFuture;
 
 /**
  * Internal helper to map the results from the analytics requests.
  *
  * @since 3.0.0
  */
+@Stability.Internal
 public class AnalyticsAccessor {
 
+  private static volatile boolean skipClusterTypeCheck = false;
+
+  /**
+   * Call this method once when your app starts up to disable the check that
+   * prevents the operational SDK from being used with an Enterprise Analytics cluster.
+   * <p>
+   * This is super-extra-unsupported internal API.
+   */
+  public static void skipClusterTypeCheck() {
+    skipClusterTypeCheck = true;
+  }
+
   public static CompletableFuture<AnalyticsResult> analyticsQueryAsync(final Core core,
                                                                        final AnalyticsRequest request,
                                                                        final JsonSerializer serializer) {
@@ -54,28 +69,33 @@ public static Mono<ReactiveAnalyticsResult> analyticsQueryReactive(final Core co
   }
 
   private static Mono<AnalyticsResponse> analyticsQueryInternal(final Core core, final AnalyticsRequest request) {
-    return core.waitForClusterTopology(request.timeout())
-                    .flatMap(clusterTopology -> {
+    return requireCouchbaseServer(core, request.timeout())
+      .then(Mono.defer(() -> {
+        core.send(request);
+        return Reactor.wrap(request, request.response(), true)
+          .doOnNext(ignored -> request.context().logicallyComplete())
+          .doOnError(err -> request.context().logicallyComplete(err));
+      }));
+  }
 
-                      if (clusterTopology.id() != null
-                              && clusterTopology.id().prodName() != null
-                              && !clusterTopology.id().prodName().startsWith(ClusterProdName.COUCHBASE_SERVER)) {
-                        StringBuilder sb = new StringBuilder();
-                        sb.append("This '");
-                        sb.append(clusterTopology.id().prodName());
-                        sb.append("' cluster cannot be used with this SDK, which is intended for use with operational clusters");
-                        if (clusterTopology.id().prodName().startsWith(ClusterProdName.ENTERPRISE_ANALYTICS)) {
-                          sb.append(". For this cluster, an Enterprise Analytics SDK should be used.");
-                        }
-                        return Mono.error(new CouchbaseException(sb.toString()));
-                      }
+  private static Mono<Void> requireCouchbaseServer(Core core, Duration timeout) {
+    if (skipClusterTypeCheck) {
+      return Mono.empty();
+    }
 
-                      return Mono.defer(() -> {
-                        core.send(request);
-                        return Reactor.wrap(request, request.response(), true);
-                      }).doOnNext(ignored -> request.context().logicallyComplete())
-                        .doOnError(err -> request.context().logicallyComplete(err));
-                    });
-  }
+    return core.waitForClusterTopology(timeout)
+      .mapNotNull(clusterTopology -> {
+        ClusterType type = ClusterType.from(clusterTopology.id());
+        if (type.isCouchbaseServer()) {
+          return null; // success! complete the empty mono.
+        }
+
+        String message = "This SDK is for Couchbase Server (operational) clusters, but the remote cluster type is '" + type + "'.";
+        if (type.name().startsWith("Enterprise Analytics")) {
+          message += " Please use the Enterprise Analytics SDK to access this cluster.";
+        }
 
+        throw new CouchbaseException(message);
+      });
+  }
 }