Enhance error reporting for failed gRPC client stub creation. (#5387)

Motivation: I got a report that it's not easy to trouble shoot when an exception is raised while creating a gRPC client stub because the exception is swallowed currently. Modification: - Introduce `ServiceDescriptorResolutionException` to capture exceptions raised during the invocation of `GrpcClientStubFactory#findServiceDescriptor(Class)` within Armeria's built-in factories. - Store these exceptions and display them to the user if `GrpcClientFactory` fails to create the client stub. Result: - You can now easily identify issues when failing to create a gRPC client stub.
line · Jan 25, 2024 · fbcd997 · fbcd997
1 parent e3ba6ec
commit fbcd997
Show file tree

Hide file tree

Showing 6 changed files with 83 additions and 27 deletions.
diff --git a/grpc/src/main/java/com/linecorp/armeria/internal/client/grpc/GrpcClientFactory.java b/grpc/src/main/java/com/linecorp/armeria/internal/client/grpc/GrpcClientFactory.java
@@ -21,6 +21,7 @@
 import static com.linecorp.armeria.internal.client.grpc.GrpcClientUtil.maxInboundMessageSizeBytes;
 import static java.util.Objects.requireNonNull;
 
+import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
@@ -109,19 +110,32 @@ public Object newClient(ClientBuilderParams params) {
         GrpcClientStubFactory clientStubFactory = options.get(GrpcClientOptions.GRPC_CLIENT_STUB_FACTORY);
         ServiceDescriptor serviceDescriptor = null;
 
+        final List<ServiceDescriptorResolutionException> exceptions = new ArrayList<>();
         if (clientStubFactory == NullGrpcClientStubFactory.INSTANCE) {
             for (GrpcClientStubFactory stubFactory : clientStubFactories) {
-                serviceDescriptor = stubFactory.findServiceDescriptor(clientType);
-                if (serviceDescriptor != null) {
-                    clientStubFactory = stubFactory;
-                    break;
+                try {
+                    serviceDescriptor = stubFactory.findServiceDescriptor(clientType);
+                    if (serviceDescriptor != null) {
+                        clientStubFactory = stubFactory;
+                        break;
+                    }
+                } catch (ServiceDescriptorResolutionException e) {
+                    exceptions.add(e);
                 }
             }
         } else {
             serviceDescriptor = clientStubFactory.findServiceDescriptor(clientType);
         }
         if (serviceDescriptor == null) {
-            throw newUnknownClientTypeException(clientType);
+            if (!exceptions.isEmpty()) {
+                throw new IllegalArgumentException(
+                        "Failed to create a gRPC client stub for " + clientType.getName() +
+                        ". Possible reasons: no gRPC client stub class or due to one of the " +
+                        "following exceptions. " + exceptions);
+            }
+            throw new IllegalArgumentException(
+                    "Unknown client type: " + clientType.getName() +
+                    " (expected: a gRPC client stub class, e.g. MyServiceGrpc.MyServiceStub)");
         }
 
         final Map<MethodDescriptor<?, ?>, String> simpleMethodNames =
@@ -212,12 +226,6 @@ private static ClientBuilderParams addTrailersExtractor(
                 params.clientType(), optionsBuilder.build());
     }
 
-    private static IllegalArgumentException newUnknownClientTypeException(Class<?> clientType) {
-        return new IllegalArgumentException(
-                "Unknown client type: " + clientType.getName() +
-                " (expected: a gRPC client stub class, e.g. MyServiceGrpc.MyServiceStub)");
-    }
-
     @Override
     public <T> T unwrap(Object client, Class<T> type) {
         final T unwrapped = super.unwrap(client, type);

diff --git a/grpc/src/main/java/com/linecorp/armeria/internal/client/grpc/JavaGrpcClientStubFactory.java b/grpc/src/main/java/com/linecorp/armeria/internal/client/grpc/JavaGrpcClientStubFactory.java
@@ -22,6 +22,7 @@
 import java.lang.reflect.Method;
 
 import com.linecorp.armeria.client.grpc.GrpcClientStubFactory;
+import com.linecorp.armeria.common.util.Exceptions;
 
 import io.grpc.Channel;
 import io.grpc.ServiceDescriptor;
@@ -51,7 +52,7 @@ public ServiceDescriptor findServiceDescriptor(Class<?> clientType) {
             final Method getServiceDescriptorMethod = enclosingClass.getDeclaredMethod("getServiceDescriptor");
             return (ServiceDescriptor) getServiceDescriptorMethod.invoke(null);
         } catch (NoSuchMethodException | IllegalAccessException | InvocationTargetException e) {
-            return null;
+            throw new ServiceDescriptorResolutionException(getClass().getSimpleName(), Exceptions.peel(e));
         }
     }
 

diff --git a/.../src/main/java/com/linecorp/armeria/internal/client/grpc/KotlinGrpcClientStubFactory.java b/.../src/main/java/com/linecorp/armeria/internal/client/grpc/KotlinGrpcClientStubFactory.java
@@ -25,6 +25,7 @@
 
 import com.linecorp.armeria.client.grpc.GrpcClientStubFactory;
 import com.linecorp.armeria.common.annotation.Nullable;
+import com.linecorp.armeria.common.util.Exceptions;
 
 import io.grpc.BindableService;
 import io.grpc.Channel;
@@ -40,19 +41,20 @@ public final class KotlinGrpcClientStubFactory implements GrpcClientStubFactory
     public ServiceDescriptor findServiceDescriptor(Class<?> clientType) {
         if (clientType.getName().endsWith("CoroutineStub")) {
             final Annotation annotation = stubForAnnotation(clientType);
+            final Method getServiceDescriptor;
+            final Class<?> generatedStub;
             try {
                 final Method valueMethod = annotation.annotationType().getDeclaredMethod("value", null);
-                final Class<?> generatedStub = generatedStub(annotation, valueMethod);
-                final Method getServiceDescriptor =
-                        generatedStub.getDeclaredMethod("getServiceDescriptor", null);
-                try {
-                    return (ServiceDescriptor) getServiceDescriptor.invoke(generatedStub);
-                } catch (IllegalAccessException | InvocationTargetException e) {
-                    throw new IllegalStateException(
-                            "Could not invoke getServiceDescriptor on a gRPC Kotlin client stub.");
-                }
+                generatedStub = generatedStub(annotation, valueMethod);
+                getServiceDescriptor = generatedStub.getDeclaredMethod("getServiceDescriptor", null);
             } catch (NoSuchMethodException e) {
-                throw new IllegalStateException("Could not find value getter on StubFor annotation.");
+                throw new IllegalArgumentException("Could not find value getter on StubFor annotation.", e);
+            }
+            try {
+                return (ServiceDescriptor) getServiceDescriptor.invoke(generatedStub);
+            } catch (IllegalAccessException | InvocationTargetException e) {
+                throw new IllegalArgumentException(
+                        "Could not invoke getServiceDescriptor on a gRPC Kotlin client stub.", e);
             }
         }
 
@@ -66,20 +68,22 @@ private static Annotation stubForAnnotation(Class<?> clientType) {
                     BindableService.class.getPackage().getName() + ".kotlin.StubFor");
             final Annotation annotation = clientType.getAnnotation(annotationClass);
             if (annotation == null) {
-                throw new IllegalStateException(
+                throw new IllegalArgumentException(
                         "Could not find StubFor annotation on a gRPC Kotlin client stub.");
             }
             return annotation;
         } catch (ClassNotFoundException e) {
-            throw new IllegalStateException("Could not find StubFor annotation on a gRPC Kotlin client stub.");
+            throw new IllegalArgumentException(
+                    "Could not find StubFor annotation on a gRPC Kotlin client stub.", e);
         }
     }
 
     private static Class<?> generatedStub(Annotation annotation, Method valueMethod) {
         try {
             return (Class<?>) valueMethod.invoke(annotation, null);
         } catch (IllegalAccessException | InvocationTargetException e) {
-            throw new IllegalStateException("Could not find a gRPC Kotlin generated client stub.");
+            throw new IllegalArgumentException(
+                    "Could not find a gRPC Kotlin generated client stub.", Exceptions.peel(e));
         }
     }
 

diff --git a/...src/main/java/com/linecorp/armeria/internal/client/grpc/ReactorGrpcClientStubFactory.java b/...src/main/java/com/linecorp/armeria/internal/client/grpc/ReactorGrpcClientStubFactory.java
@@ -22,6 +22,7 @@
 import java.lang.reflect.Method;
 
 import com.linecorp.armeria.client.grpc.GrpcClientStubFactory;
+import com.linecorp.armeria.common.util.Exceptions;
 
 import io.grpc.Channel;
 import io.grpc.ServiceDescriptor;
@@ -45,7 +46,7 @@ public ServiceDescriptor findServiceDescriptor(Class<?> clientType) {
             return (ServiceDescriptor) getServiceDescriptorMethod.invoke(null);
         } catch (NoSuchMethodException | IllegalAccessException |
                 InvocationTargetException | NoSuchFieldException e) {
-            return null;
+            throw new ServiceDescriptorResolutionException(getClass().getSimpleName(), Exceptions.peel(e));
         }
     }
 

diff --git a/...src/main/java/com/linecorp/armeria/internal/client/grpc/ScalaPbGrpcClientStubFactory.java b/...src/main/java/com/linecorp/armeria/internal/client/grpc/ScalaPbGrpcClientStubFactory.java
@@ -22,6 +22,7 @@
 import java.lang.reflect.Method;
 
 import com.linecorp.armeria.client.grpc.GrpcClientStubFactory;
+import com.linecorp.armeria.common.util.Exceptions;
 
 import io.grpc.Channel;
 import io.grpc.ServiceDescriptor;
@@ -42,7 +43,7 @@ public ServiceDescriptor findServiceDescriptor(Class<?> clientType) {
             final Method method = stubClass.getDeclaredMethod("SERVICE");
             return (ServiceDescriptor) method.invoke(null);
         } catch (IllegalAccessException | InvocationTargetException | NoSuchMethodException e) {
-            return null;
+            throw new ServiceDescriptorResolutionException(getClass().getSimpleName(), Exceptions.peel(e));
         }
     }
 

diff --git a/.../java/com/linecorp/armeria/internal/client/grpc/ServiceDescriptorResolutionException.java b/.../java/com/linecorp/armeria/internal/client/grpc/ServiceDescriptorResolutionException.java
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2024 LINE Corporation
+ *
+ * LINE Corporation licenses this file to you 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.linecorp.armeria.internal.client.grpc;
+
+import static java.util.Objects.requireNonNull;
+
+import com.linecorp.armeria.client.grpc.GrpcClientStubFactory;
+
+/**
+ * A wrapper exception for propagating exceptions raised during the invocation of
+ * {@link GrpcClientStubFactory#findServiceDescriptor(Class)} within Armeria's built-in factories.
+ * Note that this class is for internal use thus it's not exposed to users.
+ */
+public final class ServiceDescriptorResolutionException extends RuntimeException {
+
+    private static final long serialVersionUID = -4062645240586772465L;
+    private final String stubFactoryName;
+
+    public ServiceDescriptorResolutionException(String stubFactoryName, Throwable cause) {
+        super(requireNonNull(cause, "cause"));
+        this.stubFactoryName = requireNonNull(stubFactoryName, "stubFactoryName");
+    }
+
+    @Override
+    public String toString() {
+        return stubFactoryName + '=' + getCause().toString();
+    }
+}