Provide better exception when connection limit reached in LimitingCon… (

#2454)

Motivation:

Before this change, when the LimitingConnectionFactoryFilter does not allow more connections
for a given host, a generic ConnectException is returned. Developer productivity can be
improved since at the moment the user needs to inspect the text message for further
information and to distinguish different failure cases.

Modifications:

This changeset subclasses the ConnectException for backwards compatibility and returns a
ConnectionLimitReachedException instead. The actual message is also preserved for
compatibility reasons.

Result:

Better user experience when matching on the exception instance while still being
backwards compatible.

servicetalk-client-api/src/main/java/io/servicetalk/client/api/ConnectionLimitReachedException.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright © 2022 Apple Inc. and the ServiceTalk project authors
+ *
+ * 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 io.servicetalk.client.api;
+
+import java.net.ConnectException;
+
+/**
+ * Thrown when the number of connections reached their limit for a given resource (i.e. a host)
+ * depending on the context.
+ *
+ * @see LimitingConnectionFactoryFilter
+ */
+public class ConnectionLimitReachedException extends ConnectException {
+
+    private static final long serialVersionUID = 645105614301638032L;
+
+    /**
+     * Creates a new instance.
+     *
+     * @param message the detail message.
+     */
+    public ConnectionLimitReachedException(final String message) {
+        super(message);
+    }
+}

servicetalk-client-api/src/main/java/io/servicetalk/client/api/LimitingConnectionFactoryFilter.java

@@ -126,14 +126,14 @@ public interface ConnectionLimiter<ResolvedAddress, C extends ListenableAsyncClo
         void onConnectionClose(ResolvedAddress target);
 
         /**
-         * Create a {@link Throwable} representing a connection attempt refused, typically  as a result of returning
-         * {@code false} from {@link #isConnectAllowed(Object)}.
+         * Create a {@link ConnectionLimitReachedException} representing a connection attempt refused, typically
+         * as a result of returning {@code false} from {@link #isConnectAllowed(Object)}.
          *
          * @param target {@link ResolvedAddress} for which connection was refused.
          * @return {@link Throwable} representing a connection attempt was refused.
          */
         default Throwable newConnectionRefusedException(ResolvedAddress target) {
-            return new ConnectException("No more connections allowed for the host: " + target);
+            return new ConnectionLimitReachedException("No more connections allowed for the host: " + target);
         }
     }
 

servicetalk-client-api/src/test/java/io/servicetalk/client/api/LimitingConnectionFactoryFilterTest.java

@@ -46,12 +46,12 @@
 
 class LimitingConnectionFactoryFilterTest {
 
-    private final TestSingleSubscriber<ListenableAsyncCloseable> connectlistener = new TestSingleSubscriber<>();
+    private final TestSingleSubscriber<ListenableAsyncCloseable> connectListener = new TestSingleSubscriber<>();
     private ConnectionFactory<String, ListenableAsyncCloseable> original;
     private BlockingQueue<Processor> connectionOnClose;
 
     @BeforeEach
-    public void setUp() {
+    void setUp() {
         original = newMockConnectionFactory();
         connectionOnClose = new LinkedBlockingQueue<>();
         when(original.newConnection(any(), any(), any())).thenAnswer(invocation -> {
@@ -76,7 +76,8 @@ void enforceMaxConnections() throws Exception {
         cf.newConnection("c1", null, null).toFuture().get();
         Exception e = assertThrows(ExecutionException.class, () -> cf.newConnection("c2", null, null)
                 .toFuture().get());
-        assertThat(e.getCause(), instanceOf(ConnectException.class));
+        assertThat(e.getCause(), instanceOf(ConnectException.class)); // ensure backwards compatibility
+        assertThat(e.getCause(), instanceOf(ConnectionLimitReachedException.class));
     }
 
     @Test
@@ -95,10 +96,10 @@ void cancelReleasesPermit() throws Exception {
         when(o.newConnection(any(), any(), any())).thenReturn(never());
         ConnectionFactory<String, ? extends ListenableAsyncCloseable> cf =
                 makeCF(LimitingConnectionFactoryFilter.withMax(1), o);
-        toSource(cf.newConnection("c1", null, null)).subscribe(connectlistener);
-        assertThat(connectlistener.pollTerminal(10, MILLISECONDS), is(nullValue()));
+        toSource(cf.newConnection("c1", null, null)).subscribe(connectListener);
+        assertThat(connectListener.pollTerminal(10, MILLISECONDS), is(nullValue()));
         connectAndVerifyFailed(cf);
-        connectlistener.awaitSubscription().cancel();
+        connectListener.awaitSubscription().cancel();
 
         ListenableAsyncCloseable c = mock(ListenableAsyncCloseable.class);
         when(c.onClose()).thenReturn(Completable.never());