JVMCBC-1660 Change Network Heuristic for JVM SDKs

Motivation
----------
Consistent behavior between SDKs.

Make certain private endpoint deployments work
without the user having to explicitly specify
`network=external`.

Modifications
-------------
When there's no exact match between a seed node and
an address in the cluster topology, fall back to
"external" network (if present) instead of "default".

Throw an exception if the user explicitly specifies
a non-existent network. This results in a `ConfigIgnoredEvent`
in the log at WARN level with a message that includes:

"""
Requested network 'external' is not available for this cluster.
Available networks: [default]
"""

CAVEATS
-------
This is potentially a breaking behavior change.
Upgrade with caution.

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

Author: dnault

core-io/src/main/java/com/couchbase/client/core/env/NetworkResolution.java

@@ -18,7 +18,7 @@
 
 import java.util.Objects;
 
-import static com.couchbase.client.core.util.CbStrings.isNullOrEmpty;
+import static com.couchbase.client.core.util.CbStrings.nullToEmpty;
 import static java.util.Objects.requireNonNull;
 
 /**
@@ -64,7 +64,17 @@ public class NetworkResolution {
    * if the given name is null or empty.
    */
   public static NetworkResolution valueOf(final String name) {
-    return isNullOrEmpty(name) ? AUTO : new NetworkResolution(name);
+    switch (nullToEmpty(name)) {
+      case "":
+      case "auto":
+        return AUTO;
+
+      case "external":
+        return EXTERNAL;
+
+      default:
+        return new NetworkResolution(name);
+    }
   }
 
   /**

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

@@ -72,8 +72,14 @@ public static ClusterTopology parse(
       HostAndServicePortsParser.parse(addHostnameIfMissing(node, originHost), portSelector)
     );
 
-    NetworkResolution resolvedNetwork = networkSelector.selectNetwork(nodes)
-      .orElse(NetworkResolution.DEFAULT); // Hope for the best!
+    NetworkResolution resolvedNetwork = networkSelector.selectNetwork(nodes);
+
+    if (nodes.stream().noneMatch(it -> it.containsKey(resolvedNetwork))) {
+      // User explicitly specified a network that doesn't exist.
+      Set<NetworkResolution> availableNetworks = new HashSet<>();
+      nodes.forEach(it -> availableNetworks.addAll(it.keySet()));
+      throw new CouchbaseException("Requested network '" + resolvedNetwork + "' is not available for this cluster. Available networks: " + availableNetworks);
+    }
 
     // Discard node info from networks we don't care about.
     //

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

@@ -21,10 +21,11 @@
 import com.couchbase.client.core.env.NetworkResolution;
 import com.couchbase.client.core.env.SeedNode;
 import org.jspecify.annotations.Nullable;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import java.util.List;
 import java.util.Map;
-import java.util.Optional;
 import java.util.Set;
 
 import static com.couchbase.client.core.util.CbCollections.setCopyOf;
@@ -36,7 +37,7 @@
 @Stability.Internal
 public interface NetworkSelector {
 
-  Optional<NetworkResolution> selectNetwork(List<Map<NetworkResolution, HostAndServicePorts>> nodes);
+  NetworkResolution selectNetwork(List<Map<NetworkResolution, HostAndServicePorts>> nodes);
 
   /**
    * @param network The config parser's final output will include only addresses for the specified network.
@@ -54,8 +55,8 @@ static NetworkSelector create(NetworkResolution network, Set<SeedNode> seedNodes
 
     return new NetworkSelector() {
       @Override
-      public Optional<NetworkResolution> selectNetwork(List<Map<NetworkResolution, HostAndServicePorts>> nodes) {
-        return Optional.of(network);
+      public NetworkResolution selectNetwork(List<Map<NetworkResolution, HostAndServicePorts>> nodes) {
+        return network;
       }
 
       @Override
@@ -66,16 +67,18 @@ public String toString() {
 
   }
 
-  @SuppressWarnings({"OptionalAssignedToNull", "OptionalUsedAsFieldOrParameterType"})
   class AutoNetworkSelector implements NetworkSelector {
+    private static final Logger log = LoggerFactory.getLogger(AutoNetworkSelector.class);
+
     private final Set<SeedNode> seedNodes;
-    private @Nullable Optional<NetworkResolution> cachedResult; // @GuardedBy(this)
+    private @Nullable NetworkResolution cachedResult; // @GuardedBy(this)
+    private boolean usedFallback; // @GuardedBy(this)
 
     public AutoNetworkSelector(Set<SeedNode> seedNodes) {
       this.seedNodes = setCopyOf(seedNodes);
     }
 
-    public synchronized Optional<NetworkResolution> selectNetwork(List<Map<NetworkResolution, HostAndServicePorts>> nodes) {
+    public synchronized NetworkResolution selectNetwork(List<Map<NetworkResolution, HostAndServicePorts>> nodes) {
       if (cachedResult == null) {
         cachedResult = doSelectNetwork(nodes);
       }
@@ -86,11 +89,11 @@ public synchronized Optional<NetworkResolution> selectNetwork(List<Map<NetworkRe
     public synchronized String toString() {
       String network = cachedResult == null
         ? "<TBD>"
-        : cachedResult.map(NetworkResolution::name).orElse("no match -> default");
+        : (usedFallback ? "no match -> " : "") + cachedResult.name();
       return "auto(" + network + "; seedNodes=" + seedNodes + ")";
     }
 
-    private Optional<NetworkResolution> doSelectNetwork(List<Map<NetworkResolution, HostAndServicePorts>> nodes) {
+    private NetworkResolution doSelectNetwork(List<Map<NetworkResolution, HostAndServicePorts>> nodes) {
       // Search the given map for nodes whose host and KV or Manager port
       // match one of the addresses used to bootstrap the connection to the cluster.
       for (Map<NetworkResolution, HostAndServicePorts> node : nodes) {
@@ -99,14 +102,23 @@ private Optional<NetworkResolution> doSelectNetwork(List<Map<NetworkResolution,
             if (entry.getValue().matches(seedNode)) {
               // We bootstrapped using an address associated with this network+node,
               // so this is very likely the correct network.
-              return Optional.of(entry.getKey());
+              NetworkResolution exactMatch = entry.getKey();
+              log.debug("Found exact match for {} in network '{}'", seedNode, exactMatch);
+              return exactMatch;
             }
           }
         }
       }
 
       // Didn't find a match.
-      return Optional.empty();
+      NetworkResolution fallback = nodes.stream().anyMatch(it -> it.containsKey(NetworkResolution.EXTERNAL))
+        ? NetworkResolution.EXTERNAL
+        : NetworkResolution.DEFAULT;
+
+      log.info("Automatic network selection was requested, but no bootstrap address exactly matches an address in the cluster topology. Falling back to network: {}", fallback);
+
+      usedFallback = true;
+      return fallback;
     }
   }
 

core-io/src/test/java/com/couchbase/client/core/config/DefaultConfigurationProviderTest.java

@@ -30,7 +30,9 @@
 import com.couchbase.client.core.msg.ResponseStatus;
 import com.couchbase.client.core.msg.kv.GetCollectionIdRequest;
 import com.couchbase.client.core.msg.kv.GetCollectionIdResponse;
+import com.couchbase.client.core.topology.ClusterTopology;
 import com.couchbase.client.core.topology.NodeIdentifier;
+import com.couchbase.client.core.topology.TopologyRevision;
 import com.couchbase.client.core.util.ConnectionString;
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.AfterEach;
@@ -60,6 +62,7 @@
 import static java.util.stream.Collectors.toSet;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.doAnswer;
@@ -149,13 +152,23 @@ void canProposeNewBucketConfig() {
     provider.proposeBucketConfig(new ProposedBucketConfigContext(bucket, config, ORIGIN));
     assertEquals(1, configsPushed.get());
     assertFalse(provider.config().bucketConfigs().isEmpty());
-    assertEquals(1073, provider.config().bucketConfig("default").rev());
 
-    assertEquals(3, getSeedNodesFromConfig(provider).size());
-    for (SeedNode node : getSeedNodesFromConfig(provider)) {
-      assertEquals(11210, node.kvPort().orElse(null));
-      assertEquals(8091, node.clusterManagerPort().orElse(null));
-    }
+    ClusterTopology topology = provider.config().bucketTopology("default");
+    assertNotNull(topology);
+
+    assertEquals(new TopologyRevision(0, 1073), topology.revision());
+
+    // No address in the default network matches a seed node, so the SDK should fall back to external network.
+    assertEquals(NetworkResolution.EXTERNAL, topology.network());
+
+    assertEquals(
+      setOf(
+        SeedNode.create("192.168.132.234").withKvPort(32775).withManagerPort(32790),
+        SeedNode.create("192.168.132.234").withKvPort(32799).withManagerPort(32814),
+        SeedNode.create("192.168.132.234").withKvPort(32823).withManagerPort(32838)
+      ),
+      getSeedNodesFromConfig(provider)
+    );
   }
 
   @Test

core-io/src/test/java/com/couchbase/client/core/topology/NetworkSelectorTest.java

@@ -0,0 +1,98 @@
+/*
+ * 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.env.NetworkResolution;
+import com.couchbase.client.core.env.SeedNode;
+import com.couchbase.client.core.service.ServiceType;
+import org.junit.jupiter.api.Test;
+
+import java.util.Set;
+
+import static com.couchbase.client.core.util.CbCollections.listOf;
+import static com.couchbase.client.core.util.CbCollections.mapOf;
+import static com.couchbase.client.core.util.CbCollections.setOf;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class NetworkSelectorTest {
+
+  private static HostAndServicePorts nodeWithHostAndKvPort(String host, int kvPort) {
+    return new HostAndServicePorts(
+      host,
+      mapOf(
+        ServiceType.KV, kvPort,
+        ServiceType.MANAGER, 8091
+      ),
+      NodeIdentifier.forBootstrap(host, 8091),
+      null,
+      null,
+      null,
+      null
+    );
+  }
+
+  @Test
+  void autoSelectsDefaultIfExactMatch() {
+    Set<SeedNode> seeds = setOf(SeedNode.create("example.com").withKvPort(11210));
+
+    NetworkResolution selected = NetworkSelector.autoDetect(seeds)
+      .selectNetwork(listOf(
+        mapOf(NetworkResolution.DEFAULT, nodeWithHostAndKvPort("example.com", 11210)),
+        mapOf(NetworkResolution.EXTERNAL, nodeWithHostAndKvPort("example.com", 11210))
+      ));
+
+    assertEquals(NetworkResolution.DEFAULT, selected);
+  }
+
+  @Test
+  void autoSelectsExternalIfExactMatch() {
+    Set<SeedNode> seeds = setOf(SeedNode.create("example.com").withKvPort(11210));
+
+    NetworkResolution selected = NetworkSelector.autoDetect(seeds)
+      .selectNetwork(listOf(
+        mapOf(NetworkResolution.DEFAULT, nodeWithHostAndKvPort("example.com", 1)),
+        mapOf(NetworkResolution.EXTERNAL, nodeWithHostAndKvPort("example.com", 11210))
+      ));
+
+    assertEquals(NetworkResolution.EXTERNAL, selected);
+  }
+
+  @Test
+  void autoFallsBackToExternalIfPresent() {
+    Set<SeedNode> seeds = setOf(SeedNode.create("example.com").withKvPort(11210));
+
+    NetworkResolution selected = NetworkSelector.autoDetect(seeds)
+      .selectNetwork(listOf(
+        mapOf(NetworkResolution.DEFAULT, nodeWithHostAndKvPort("example.com", 1)),
+        mapOf(NetworkResolution.EXTERNAL, nodeWithHostAndKvPort("example.com", 2))
+      ));
+
+    assertEquals(NetworkResolution.EXTERNAL, selected);
+  }
+
+  @Test
+  void autoFallsBackToDefaultIfExternalIsAbsent() {
+    Set<SeedNode> seeds = setOf(SeedNode.create("example.com").withKvPort(11210));
+
+    NetworkResolution selected = NetworkSelector.autoDetect(seeds)
+      .selectNetwork(listOf(
+        mapOf(NetworkResolution.DEFAULT, nodeWithHostAndKvPort("127.0.0.1", 1))
+      ));
+
+    assertEquals(NetworkResolution.DEFAULT, selected);
+  }
+}