JAVA-6194 Add MongoSocksProxyException for CMAP backpressure labeling

driver-core/src/main/com/mongodb/MongoSocksProxyException.java

@@ -0,0 +1,165 @@
+/*
+ * 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;
+
+import com.mongodb.lang.Nullable;
+
+/**
+ * Thrown when an error occurs while establishing a connection to a SOCKS5 proxy.
+ *
+ * <p>Per the CMAP specification, errors of this type are excluded from backpressure
+ * error labels ({@link MongoException#SYSTEM_OVERLOADED_ERROR_LABEL},
+ * {@link MongoException#RETRYABLE_ERROR_LABEL}).
+ *
+ * <p>The {@link #getHandshakePhase()} identifies which phase of the SOCKS5 handshake failed.
+ * For {@link HandshakePhase#CONNECT_RELAY} failures, {@link #getProxyReplyCode()} returns
+ * the RFC 1928 reply code sent by the proxy; for all other phases it returns {@code null}.
+ *
+ * <p>RFC 1928 reply codes: 1=general failure, 2=connection not allowed by ruleset,
+ * 3=network unreachable, 4=host unreachable, 5=connection refused, 6=TTL expired,
+ * 7=command not supported, 8=address type not supported.
+ *
+ * @since 5.8
+ */
+public class MongoSocksProxyException extends MongoSocketOpenException {
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * The phase of the SOCKS5 handshake at which the failure occurred.
+     *
+     * @since 5.8
+     */
+    public enum HandshakePhase {
+        /**
+         * TCP connection to the proxy host itself failed before any SOCKS5 exchange.
+         * The proxy may be temporarily unreachable.
+         */
+        PROXY_TCP_CONNECT,
+
+        /**
+         * SOCKS5 method-selection exchange failed: the proxy version is incompatible,
+         * no common authentication method was found, or the proxy returned an
+         * unrecognised method. This is always a configuration error.
+         */
+        NEGOTIATION,
+
+        /**
+         * Credential verification with the proxy failed. This is always a
+         * configuration error (wrong username or password).
+         */
+        AUTHENTICATION,
+
+        /**
+         * The proxy processed the CONNECT command for the target host and returned
+         * a non-success reply code. See {@link MongoSocksProxyException#getProxyReplyCode()}
+         * for the specific RFC 1928 reply code.
+         */
+        CONNECT_RELAY
+    }
+
+    private final HandshakePhase handshakePhase;
+
+    @Nullable
+    private final Integer proxyReplyCode;
+
+    /**
+     * Construct an instance for failures that have no RFC 1928 reply code and no cause
+     * ({@link HandshakePhase#PROXY_TCP_CONNECT}, {@link HandshakePhase#NEGOTIATION},
+     * {@link HandshakePhase#AUTHENTICATION}).
+     *
+     * @param message        the message
+     * @param serverAddress  the server address
+     * @param handshakePhase the phase at which the failure occurred
+     */
+    public MongoSocksProxyException(final String message, final ServerAddress serverAddress, final HandshakePhase handshakePhase) {
+        this(message, serverAddress, handshakePhase, null);
+    }
+
+    /**
+     * Construct an instance for failures that have no RFC 1928 reply code
+     * ({@link HandshakePhase#PROXY_TCP_CONNECT}, {@link HandshakePhase#NEGOTIATION},
+     * {@link HandshakePhase#AUTHENTICATION}).
+     *
+     * @param message        the message
+     * @param address        the server address
+     * @param cause          the cause
+     * @param handshakePhase the phase at which the failure occurred
+     */
+    public MongoSocksProxyException(final String message, final ServerAddress address,
+                                    final Throwable cause, final HandshakePhase handshakePhase) {
+        this(message, address, cause, handshakePhase, null);
+    }
+
+    /**
+     * Construct an instance with an optional RFC 1928 reply code.
+     * Use {@code null} for phases that do not carry a reply code
+     * ({@link HandshakePhase#PROXY_TCP_CONNECT}, {@link HandshakePhase#NEGOTIATION},
+     * {@link HandshakePhase#AUTHENTICATION}).
+     *
+     * @param message        the message
+     * @param address        the server address
+     * @param handshakePhase the phase at which the failure occurred
+     * @param proxyReplyCode the RFC 1928 reply code, or {@code null}
+     */
+    public MongoSocksProxyException(final String message, final ServerAddress address, final HandshakePhase handshakePhase,
+            @Nullable final Integer proxyReplyCode) {
+        super(message, address);
+        this.handshakePhase = handshakePhase;
+        this.proxyReplyCode = proxyReplyCode;
+    }
+
+    /**
+     * Construct an instance with an optional RFC 1928 reply code.
+     * Use {@code null} for phases that do not carry a reply code
+     * ({@link HandshakePhase#PROXY_TCP_CONNECT}, {@link HandshakePhase#NEGOTIATION},
+     * {@link HandshakePhase#AUTHENTICATION}).
+     *
+     * @param message        the message
+     * @param address        the server address
+     * @param cause          the cause
+     * @param handshakePhase the phase at which the failure occurred
+     * @param proxyReplyCode the RFC 1928 reply code, or {@code null}
+     */
+    public MongoSocksProxyException(final String message, final ServerAddress address,
+                                    final Throwable cause, final HandshakePhase handshakePhase,
+                                    @Nullable final Integer proxyReplyCode) {
+        super(message, address, cause);
+        this.handshakePhase = handshakePhase;
+        this.proxyReplyCode = proxyReplyCode;
+    }
+
+    /**
+     * Returns the phase of the SOCKS5 handshake at which the failure occurred.
+     *
+     * @return the handshake phase, never {@code null}
+     */
+    public HandshakePhase getHandshakePhase() {
+        return handshakePhase;
+    }
+
+    /**
+     * Returns the RFC 1928 reply code sent by the SOCKS5 proxy in response to a CONNECT request,
+     * or {@code null} if the failure occurred before the proxy sent a CONNECT response
+     * (i.e. phase is not {@link HandshakePhase#CONNECT_RELAY}).
+     *
+     * @return the RFC 1928 proxy reply code, or {@code null}
+     */
+    @Nullable
+    public Integer getProxyReplyCode() {
+        return proxyReplyCode;
+    }
+}

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

@@ -16,9 +16,11 @@
 
 package com.mongodb.internal.connection;
 
+import com.mongodb.MongoInterruptedException;
 import com.mongodb.MongoSocketException;
 import com.mongodb.MongoSocketOpenException;
 import com.mongodb.MongoSocketReadException;
+import com.mongodb.MongoSocksProxyException;
 import com.mongodb.ServerAddress;
 import com.mongodb.connection.AsyncCompletionHandler;
 import com.mongodb.connection.ProxySettings;
@@ -38,6 +40,7 @@
 import java.net.SocketTimeoutException;
 import java.util.Iterator;
 import java.util.List;
+import java.util.Optional;
 
 import static com.mongodb.assertions.Assertions.assertTrue;
 import static com.mongodb.assertions.Assertions.notNull;
@@ -79,10 +82,21 @@ public void open(final OperationContext operationContext) {
             socket = initializeSocket(operationContext);
             outputStream = socket.getOutputStream();
             inputStream = socket.getInputStream();
+        } catch (MongoSocksProxyException e) {
+            close();
+            throw e;
         } catch (IOException e) {
             close();
-            throw translateInterruptedException(e, "Interrupted while connecting")
-                    .orElseThrow(() -> new MongoSocketOpenException("Exception opening socket", getAddress(), e));
+            Optional<MongoInterruptedException> interrupted = translateInterruptedException(e, "Interrupted while connecting");
+            if (interrupted.isPresent()) {
+                throw interrupted.get();
+            }
+            if (settings.getProxySettings().isProxyEnabled()) {
+                throw new MongoSocksProxyException(
+                        "Exception connecting to SOCKS5 proxy", getAddress(), e,
+                        MongoSocksProxyException.HandshakePhase.PROXY_TCP_CONNECT);
+            }
+            throw new MongoSocketOpenException("Exception opening socket", getAddress(), e);
         }
     }
 
@@ -119,15 +133,28 @@ private SSLSocket initializeSslSocketOverSocksProxy(final OperationContext opera
         final int serverPort = address.getPort();
 
         SocksSocket socksProxy = new SocksSocket(settings.getProxySettings());
-        configureSocket(socksProxy, operationContext, settings);
-        InetSocketAddress inetSocketAddress = toSocketAddress(serverHost, serverPort);
-        socksProxy.connect(inetSocketAddress, operationContext.getTimeoutContext().getConnectTimeoutMs());
-
-        SSLSocket sslSocket = (SSLSocket) sslSocketFactory.createSocket(socksProxy, serverHost, serverPort, true);
-        //Even though Socks proxy connection is already established, TLS handshake has not been performed yet.
-        //So it is possible to set SSL parameters before handshake is done.
-        configureSslSocket(sslSocket, sslSettings, inetSocketAddress);
-        return sslSocket;
+        // Track the outermost socket layer to close on failure. Initially this is socksProxy;
+        // once we wrap it into an SSLSocket, that becomes the outermost layer and closing it
+        // tears down the underlying socksProxy as well.
+        Socket toClose = socksProxy;
+        try {
+            configureSocket(socksProxy, operationContext, settings);
+            InetSocketAddress inetSocketAddress = toSocketAddress(serverHost, serverPort);
+            socksProxy.connect(inetSocketAddress, operationContext.getTimeoutContext().getConnectTimeoutMs());
+            SSLSocket sslSocket = (SSLSocket) sslSocketFactory.createSocket(socksProxy, serverHost, serverPort, true);
+            toClose = sslSocket;
+            //Even though Socks proxy connection is already established, TLS handshake has not been performed yet.
+            //So it is possible to set SSL parameters before handshake is done.
+            configureSslSocket(sslSocket, sslSettings, inetSocketAddress);
+            return sslSocket;
+        } catch (IOException | RuntimeException e) {
+            try {
+                toClose.close();
+            } catch (IOException closeException) {
+                e.addSuppressed(closeException);
+            }
+            throw e;
+        }
     }
 
 
@@ -141,17 +168,30 @@ private static InetSocketAddress toSocketAddress(final String serverHost, final
 
     private Socket initializeSocketOverSocksProxy(final OperationContext operationContext) throws IOException {
         Socket createdSocket = socketFactory.createSocket();
-        configureSocket(createdSocket, operationContext, settings);
-        /*
-          Wrap the configured socket with SocksSocket to add extra functionality.
-          Reason for separate steps: We can't directly extend Java 11 methods within 'SocksSocket'
-          to configure itself.
-         */
-        SocksSocket socksProxy = new SocksSocket(createdSocket, settings.getProxySettings());
-
-        socksProxy.connect(toSocketAddress(address.getHost(), address.getPort()),
-                operationContext.getTimeoutContext().getConnectTimeoutMs());
-        return socksProxy;
+        try {
+            configureSocket(createdSocket, operationContext, settings);
+            /*
+              Wrap the configured socket with SocksSocket to add extra functionality.
+              Reason for separate steps: We can't directly extend Java 11 methods within 'SocksSocket'
+              to configure itself.
+             */
+            SocksSocket socksProxy = new SocksSocket(createdSocket, settings.getProxySettings());
+            socksProxy.connect(toSocketAddress(address.getHost(), address.getPort()),
+                    operationContext.getTimeoutContext().getConnectTimeoutMs());
+            return socksProxy;
+        } catch (IOException | RuntimeException e) {
+            // SocksSocket.connect() now closes itself on failure, but createdSocket may not yet
+            // be owned by a SocksSocket (e.g. configureSocket threw). Close defensively; on success
+            // path SocksSocket holds the reference and this catch is not entered.
+            // Note: when SocksSocket.connect() has already closed the inner socket, this is a
+            // no-op (java.net.Socket.close() is idempotent per the JDK contract).
+            try {
+                createdSocket.close();
+            } catch (IOException closeException) {
+                e.addSuppressed(closeException);
+            }
+            throw e;
+        }
     }
 
     @Override

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

@@ -15,6 +15,9 @@
  */
 package com.mongodb.internal.connection;
 
+import com.mongodb.MongoSocksProxyException;
+import com.mongodb.MongoSocksProxyException.HandshakePhase;
+import com.mongodb.ServerAddress;
 import com.mongodb.connection.ProxySettings;
 import com.mongodb.internal.time.Timeout;
 import com.mongodb.lang.Nullable;
@@ -100,6 +103,16 @@ public void connect(final SocketAddress endpoint, final int connectTimeoutMs) th
             SocksAuthenticationMethod authenticationMethod = performNegotiation(timeout);
             authenticate(authenticationMethod, timeout);
             sendConnect(timeout);
+        } catch (MongoSocksProxyException e) {
+            // The underlying proxy TCP socket is already connected at this point.
+            // MongoSocksProxyException is a RuntimeException and is not caught below,
+            // so close the socket here to avoid leaking the FD on every SOCKS5 protocol failure.
+            try {
+                close();
+            } catch (Exception closeException) {
+                e.addSuppressed(closeException);
+            }
+            throw e;
         } catch (SocketException socketException) {
             /*
              * The 'close()' call here has two purposes:
@@ -125,6 +138,8 @@ private void socketConnect(final InetSocketAddress proxyAddress, final int rem)
     }
 
     private void sendConnect(final Timeout timeout) throws IOException {
+        // remoteAddress is unresolved (asserted in connect()), so getHostName() returns the stored
+        // hostname string without triggering DNS. The SOCKS5 CONNECT request requires this string.
         final String host = remoteAddress.getHostName();
         final int port = remoteAddress.getPort();
         final byte[] bytesOfHost = host.getBytes(StandardCharsets.US_ASCII);
@@ -223,7 +238,7 @@ private void checkServerReply(final Timeout timeout) throws IOException {
             }
             return;
         }
-        throw new ConnectException(reply.getMessage());
+        throw new MongoSocksProxyException(reply.message, targetServerAddress(), HandshakePhase.CONNECT_RELAY, reply.replyNumber);
     }
 
     private void authenticate(final SocksAuthenticationMethod authenticationMethod, final Timeout timeout) throws IOException {
@@ -249,7 +264,9 @@ private void authenticate(final SocksAuthenticationMethod authenticationMethod,
             byte authStatus = authResult[1];
 
             if (authStatus != AUTHENTICATION_SUCCEEDED_STATUS) {
-                throw new ConnectException("Authentication failed. Proxy server returned status: " + authStatus);
+                throw new MongoSocksProxyException(
+                        "Authentication failed. Proxy server returned status: " + authStatus,
+                        targetServerAddress(), HandshakePhase.AUTHENTICATION);
             }
         }
     }
@@ -273,21 +290,32 @@ private SocksAuthenticationMethod performNegotiation(final Timeout timeout) thro
         byte[] handshakeReply = readSocksReply(2, timeout);
 
         if (handshakeReply[0] != SOCKS_VERSION) {
-            throw new ConnectException("Remote server doesn't support socks version 5"
-                    + " Received version: " + handshakeReply[0]);
+            throw new MongoSocksProxyException("Remote server doesn't support socks version 5"
+                    + " Received version: " + handshakeReply[0],
+                    targetServerAddress(), HandshakePhase.NEGOTIATION);
         }
         byte authMethodNumber = handshakeReply[1];
         if (authMethodNumber == (byte) 0xFF) {
-            throw new ConnectException("None of the authentication methods listed are acceptable. Attempted methods: "
-                    + Arrays.toString(authenticationMethods));
+            throw new MongoSocksProxyException(
+                    "None of the authentication methods listed are acceptable. Attempted methods: "
+                    + Arrays.toString(authenticationMethods),
+                    targetServerAddress(), HandshakePhase.NEGOTIATION);
         }
         if (authMethodNumber == SocksAuthenticationMethod.NO_AUTH.getMethodNumber()) {
             return SocksAuthenticationMethod.NO_AUTH;
         } else if (authMethodNumber == SocksAuthenticationMethod.USERNAME_PASSWORD.getMethodNumber()) {
             return SocksAuthenticationMethod.USERNAME_PASSWORD;
         }
 
-        throw new ConnectException("Proxy returned unsupported authentication method: " + authMethodNumber);
+        throw new MongoSocksProxyException("Proxy returned unsupported authentication method: " + authMethodNumber,
+                targetServerAddress(), HandshakePhase.NEGOTIATION);
+    }
+
+    private ServerAddress targetServerAddress() {
+        // remoteAddress is asserted unresolved in connect(), so getHostName() would also be safe today.
+        // Using getHostString() defensively guarantees no reverse DNS in this exception-reporting path
+        // even if that invariant is ever weakened.
+        return new ServerAddress(remoteAddress.getHostString(), remoteAddress.getPort());
     }
 
     private SocksAuthenticationMethod[] getSocksAuthenticationMethods() {