JAVA-5949 preserve connection pool on backpressure errors when establishing connections

driver-core/src/main/com/mongodb/internal/connection/BackpressureErrorLabeler.java

@@ -0,0 +1,108 @@
+/*
+ * Copyright 2008-present MongoDB, 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
+ *
+ *   http://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.mongodb.internal.connection;
+
+import com.mongodb.MongoException;
+import com.mongodb.MongoSocketException;
+
+import javax.net.ssl.SSLHandshakeException;
+import javax.net.ssl.SSLPeerUnverifiedException;
+import javax.net.ssl.SSLProtocolException;
+import java.net.UnknownHostException;
+import java.security.cert.CertPathBuilderException;
+import java.security.cert.CertPathValidatorException;
+import java.security.cert.CertificateException;
+import java.util.Locale;
+
+/**
+ * Attaches {@link MongoException#SYSTEM_OVERLOADED_ERROR_LABEL} and
+ * {@link MongoException#RETRYABLE_ERROR_LABEL} to network errors encountered during connection
+ * establishment or the hello message, per the CMAP specification.
+ *
+ * <p>This is topology-agnostic: it must be invoked from the connection-establishment path so that
+ * both default SDAM and load-balanced modes are covered.
+ */
+final class BackpressureErrorLabeler {
+
+    private BackpressureErrorLabeler() {
+    }
+
+    static void applyLabelsIfEligible(final Throwable t) {
+        if (!(t instanceof MongoSocketException)) {
+            return;
+        }
+        MongoSocketException socketException = (MongoSocketException) t;
+        if (isDnsLookupFailure(socketException)) {
+            return;
+        }
+        if (isTlsConfigurationError(socketException)) {
+            return;
+        }
+        // TODO-BACKPRESSURE Nabil - SOCKS5 Revisit alongside JAVA-5205 (SOCKS5 in async) so both sync and
+        // async proxy error surfaces can be handled together — likely via a dedicated internal
+        // exception thrown from the proxy code path.
+        socketException.addLabel(MongoException.SYSTEM_OVERLOADED_ERROR_LABEL);
+        socketException.addLabel(MongoException.RETRYABLE_ERROR_LABEL);
+    }
+
+    private static boolean isDnsLookupFailure(final MongoSocketException t) {
+        Throwable cause = t.getCause();
+        while (cause != null) {
+            if (cause instanceof UnknownHostException) {
+                return true;
+            }
+            cause = cause.getCause();
+        }
+        return false;
+    }
+
+    private static boolean isTlsConfigurationError(final MongoSocketException t) {
+        Throwable cause = t.getCause();
+        while (cause != null) {
+            if (cause instanceof CertificateException
+                    || cause instanceof CertPathBuilderException
+                    || cause instanceof CertPathValidatorException
+                    || cause instanceof SSLPeerUnverifiedException
+                    || cause instanceof SSLProtocolException) {
+                return true;
+            }
+            if (cause instanceof SSLHandshakeException) {
+                String message = cause.getMessage();
+                if (message != null) {
+                    String lowerMessage = message.toLowerCase(Locale.ROOT);
+                    if (lowerMessage.contains("certificate")
+                            || lowerMessage.contains("verify")
+                            || lowerMessage.contains("trust")
+                            || lowerMessage.contains("hostname")
+                            || lowerMessage.contains("protocol")
+                            || lowerMessage.contains("cipher")
+                            // PKIX path building/validation failures surface as SSLHandshakeException
+                            // when the underlying CertPath* cause is not in the chain.
+                            || lowerMessage.contains("pkix")
+                            // Any "Received fatal alert: X" from OpenJDK's JSSE provider means the
+                            // server actively answered with a TLS protocol error — not an overload
+                            // signal. Catches all 25 RFC handshake alert descriptions in one rule.
+                            || lowerMessage.contains("received fatal alert")) {
+                        return true;
+                    }
+                }
+            }
+            cause = cause.getCause();
+        }
+        return false;
+    }
+}

driver-core/src/main/com/mongodb/internal/connection/DefaultSdamServerDescriptionManager.java

@@ -137,6 +137,9 @@ private void handleException(final SdamIssue sdamIssue, final boolean beforeHand
             serverMonitor.connect();
         } else if (sdamIssue.relatedToNetworkNotTimeout()
                 || (beforeHandshake && (sdamIssue.relatedToNetworkTimeout() || sdamIssue.relatedToAuth()))) {
+            if (sdamIssue.hasSystemOverloadedLabel()) {
+                return;
+            }
             updateDescription(sdamIssue.serverDescription());
             connectionPool.invalidate(sdamIssue.exception().orElse(null));
             serverMonitor.cancelCurrentCheck();

driver-core/src/main/com/mongodb/internal/connection/InternalStreamConnection.java

@@ -230,9 +230,11 @@ public void open(final OperationContext originalOperationContext) {
         isTrue("Open already called", stream == null);
         stream = streamFactory.create(serverId.getAddress());
         OperationContext operationContext = originalOperationContext;
+        boolean beforeHandshake = true;
         try {
             stream.open(operationContext);
             InternalConnectionInitializationDescription initializationDescription = connectionInitializer.startHandshake(this, operationContext);
+            beforeHandshake = false;
 
             operationContext = operationContext.withOverride(TimeoutContext::withNewlyStartedMaintenanceTimeout);
             initAfterHandshakeStart(initializationDescription);
@@ -241,6 +243,9 @@ public void open(final OperationContext originalOperationContext) {
             initAfterHandshakeFinish(initializationDescription);
         } catch (Throwable t) {
             close();
+            if (beforeHandshake) {
+                BackpressureErrorLabeler.applyLabelsIfEligible(t);
+            }
             if (t instanceof MongoException) {
                 throw (MongoException) t;
             } else {
@@ -263,6 +268,7 @@ public void completed(@Nullable final Void aVoid) {
                             (initialResult, initialException) -> {
                                     if (initialException != null) {
                                         close();
+                                        BackpressureErrorLabeler.applyLabelsIfEligible(initialException);
                                         callback.onResult(null, initialException);
                                     } else {
                                         assertNotNull(initialResult);
@@ -278,11 +284,13 @@ public void completed(@Nullable final Void aVoid) {
                 @Override
                 public void failed(final Throwable t) {
                     close();
+                    BackpressureErrorLabeler.applyLabelsIfEligible(t);
                     callback.onResult(null, t);
                 }
             });
         } catch (Throwable t) {
             close();
+            BackpressureErrorLabeler.applyLabelsIfEligible(t);
             callback.onResult(null, t);
         }
     }

driver-core/src/main/com/mongodb/internal/connection/SdamServerDescriptionManager.java

@@ -17,6 +17,7 @@
 package com.mongodb.internal.connection;
 
 import com.mongodb.MongoCommandException;
+import com.mongodb.MongoException;
 import com.mongodb.MongoNodeIsRecoveringException;
 import com.mongodb.MongoNotPrimaryException;
 import com.mongodb.MongoSecurityException;
@@ -162,6 +163,11 @@ boolean relatedToWriteConcern() {
             return exception instanceof MongoWriteConcernWithResponseException;
         }
 
+        boolean hasSystemOverloadedLabel() {
+            return exception instanceof MongoException
+                    && ((MongoException) exception).hasErrorLabel(MongoException.SYSTEM_OVERLOADED_ERROR_LABEL);
+        }
+
         private static boolean stale(@Nullable final Throwable t, final ServerDescription currentServerDescription) {
             return TopologyVersionHelper.topologyVersion(t)
                     .map(candidateTopologyVersion -> TopologyVersionHelper.newerOrEqual(

driver-core/src/test/unit/com/mongodb/internal/connection/AbstractServerDiscoveryAndMonitoringTest.java

@@ -113,6 +113,7 @@ protected void applyApplicationError(final BsonDocument applicationError) {
 
         switch (when) {
             case "beforeHandshakeCompletes":
+                BackpressureErrorLabeler.applyLabelsIfEligible(exception);
                 server.sdamServerDescriptionManager().handleExceptionBeforeHandshake(
                         SdamIssue.of(exception, new SdamIssue.Context(server.serverId(), errorGeneration, maxWireVersion)));
                 break;

driver-core/src/test/unit/com/mongodb/internal/connection/BackpressureErrorLabelerTest.java

@@ -0,0 +1,183 @@
+/*
+ * Copyright 2008-present MongoDB, 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
+ *
+ *   http://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.mongodb.internal.connection;
+
+import com.mongodb.MongoCredential;
+import com.mongodb.MongoException;
+import com.mongodb.MongoSecurityException;
+import com.mongodb.MongoSocketException;
+import com.mongodb.MongoSocketOpenException;
+import com.mongodb.MongoSocketReadTimeoutException;
+import com.mongodb.ServerAddress;
+import org.junit.jupiter.api.Named;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
+import org.junit.jupiter.params.provider.ValueSource;
+
+import javax.net.ssl.SSLHandshakeException;
+import javax.net.ssl.SSLPeerUnverifiedException;
+import javax.net.ssl.SSLProtocolException;
+import java.io.EOFException;
+import java.io.IOException;
+import java.net.UnknownHostException;
+import java.security.cert.CertPathBuilderException;
+import java.security.cert.CertPathValidatorException;
+import java.security.cert.CertificateException;
+import java.util.stream.Stream;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class BackpressureErrorLabelerTest {
+
+    private static final ServerAddress ADDRESS = new ServerAddress();
+
+    static Stream<Named<MongoSocketException>> networkErrorShouldBeLabeled() {
+        return Stream.of(
+                named(new MongoSocketException("boom", ADDRESS)),
+                named(new MongoSocketReadTimeoutException("slow", ADDRESS, new IOException("read timed out"))),
+                named(new MongoSocketOpenException("open failed", ADDRESS, new IOException("connection refused"))),
+                // FIN-during-handshake: server closed the TCP connection while the client was mid-handshake
+                // (no protocol-level alert). I/O failure → must be labeled per CMAP "I/O error during TLS handshake".
+                named(new MongoSocketException("tls", ADDRESS, initCause(
+                        new SSLHandshakeException("Remote host terminated the handshake"),
+                        new EOFException("SSL peer shut down incorrectly"))))
+        );
+    }
+
+    @ParameterizedTest
+    @MethodSource
+    void networkErrorShouldBeLabeled(final MongoSocketException e) {
+        BackpressureErrorLabeler.applyLabelsIfEligible(e);
+        assertHasBackpressureLabels(e);
+    }
+
+    static Stream<Named<MongoSocketException>> dnsFailureShouldNotBeLabeled() {
+        return Stream.of(
+                named(new MongoSocketException("lookup failed", ADDRESS, new UnknownHostException("nope"))),
+                named(new MongoSocketException("wrap", ADDRESS, new IOException("wrap", new UnknownHostException("nope"))))
+        );
+    }
+
+    @ParameterizedTest
+    @MethodSource
+    void dnsFailureShouldNotBeLabeled(final MongoSocketException e) {
+        BackpressureErrorLabeler.applyLabelsIfEligible(e);
+        assertLacksBackpressureLabels(e);
+    }
+
+    static Stream<Named<Throwable>> localTlsConfigErrorShouldNotBeLabeled() {
+        return Stream.of(
+                named(new CertificateException("bad cert")),
+                named(new CertPathBuilderException("path build failed")),
+                named(new CertPathValidatorException("validation failed")),
+                named(new SSLPeerUnverifiedException("peer not verified")),
+                named(new SSLProtocolException("protocol error")),
+                named(new SSLHandshakeException("PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: "
+                        + "unable to find valid certification path to requested target"))
+        );
+    }
+
+    @ParameterizedTest
+    @MethodSource
+    void localTlsConfigErrorShouldNotBeLabeled(final Throwable cause) {
+        MongoSocketException e = new MongoSocketException("tls", ADDRESS, cause);
+        BackpressureErrorLabeler.applyLabelsIfEligible(e);
+        assertLacksBackpressureLabels(e);
+    }
+
+    /**
+     * "Received fatal alert: <description>" means the peer actively answered with a TLS protocol
+     * error — definitively a config/protocol issue, not an overload signal. Covers all 25
+     * handshake-only RFC alert descriptions emitted by OpenJDK's JSSE provider.
+     */
+    @ParameterizedTest(name = "Received fatal alert: {0}")
+    @ValueSource(strings = {
+            "handshake_failure",
+            "no_certificate",
+            "bad_certificate",
+            "unsupported_certificate",
+            "certificate_revoked",
+            "certificate_expired",
+            "certificate_unknown",
+            "illegal_parameter",
+            "unknown_ca",
+            "access_denied",
+            "decode_error",
+            "decrypt_error",
+            "export_restriction",
+            "protocol_version",
+            "insufficient_security",
+            "no_renegotiation",
+            "missing_extension",
+            "unsupported_extension",
+            "certificate_unobtainable",
+            "unrecognized_name",
+            "bad_certificate_status_response",
+            "bad_certificate_hash_value",
+            "unknown_psk_identity",
+            "certificate_required",
+            "no_application_protocol"
+    })
+    void receivedTlsAlertShouldNotBeLabeled(final String alertDescription) {
+        SSLHandshakeException tls = new SSLHandshakeException("Received fatal alert: " + alertDescription);
+        MongoSocketException e = new MongoSocketException("tls", ADDRESS, tls);
+        BackpressureErrorLabeler.applyLabelsIfEligible(e);
+        assertLacksBackpressureLabels(e);
+    }
+
+    static Stream<Named<Throwable>> nonSocketErrorShouldNotBeLabeled() {
+        return Stream.of(
+                named(new MongoSecurityException(
+                        MongoCredential.createCredential("user", "db", "pwd".toCharArray()), "auth failed")),
+                named(new MongoException(42, "some command error")),
+                named(new IOException("raw"))
+        );
+    }
+
+    @ParameterizedTest
+    @MethodSource
+    void nonSocketErrorShouldNotBeLabeled(final Throwable e) {
+        BackpressureErrorLabeler.applyLabelsIfEligible(e);
+        if (e instanceof MongoException) {
+            assertLacksBackpressureLabels((MongoException) e);
+        }
+    }
+
+    private static <T extends Throwable> Named<T> named(final T e) {
+        return Named.of(e.getClass().getSimpleName(), e);
+    }
+
+    private static <T extends Throwable> T initCause(final T exception, final Throwable cause) {
+        exception.initCause(cause);
+        return exception;
+    }
+
+    private static void assertHasBackpressureLabels(final MongoException e) {
+        assertTrue(e.hasErrorLabel(MongoException.SYSTEM_OVERLOADED_ERROR_LABEL),
+                "expected SystemOverloadedError label");
+        assertTrue(e.hasErrorLabel(MongoException.RETRYABLE_ERROR_LABEL),
+                "expected RetryableError label");
+    }
+
+    private static void assertLacksBackpressureLabels(final MongoException e) {
+        assertFalse(e.hasErrorLabel(MongoException.SYSTEM_OVERLOADED_ERROR_LABEL),
+                "unexpected SystemOverloadedError label");
+        assertFalse(e.hasErrorLabel(MongoException.RETRYABLE_ERROR_LABEL),
+                "unexpected RetryableError label");
+    }
+}