Skip to content
This repository has been archived by the owner on Sep 26, 2023. It is now read-only.

Commit

Permalink
feat: Error Details Improvements - GRPC (#1634)
Browse files Browse the repository at this point in the history
Fixes: #1635 
Key design notes:
1. All `ApiException` created for GRPC clients will go through `GrpcApiExceptionFactory` and the cause of `ApiException` already has all the info we need, hence the majority of the logic is in `GrpcApiExceptionFactory`.
2. Promoted all the fields of `ErrorInfo` to top level of `ApiException`, accessible through getters directly.
3. Encapsulated all the raw error messages from server to `ErrorDetails`. The unpacked error messages are accessible through getters.
4. If error messages from server are corrupted and unable to unpack, a `ProtocolBufferParsingException` will be thrown.
  • Loading branch information
blakeli0 authored Apr 4, 2022
1 parent d4f9ad8 commit 00c3b9d
Show file tree
Hide file tree
Showing 27 changed files with 906 additions and 43 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -31,20 +31,26 @@

import com.google.api.gax.rpc.ApiException;
import com.google.api.gax.rpc.ApiExceptionFactory;
import com.google.api.gax.rpc.ErrorDetails;
import com.google.api.gax.rpc.StatusCode.Code;
import com.google.common.annotations.VisibleForTesting;
import com.google.common.collect.ImmutableSet;
import com.google.protobuf.InvalidProtocolBufferException;
import io.grpc.Metadata;
import io.grpc.Status;
import io.grpc.StatusException;
import io.grpc.StatusRuntimeException;
import java.util.Set;

/**
* Core logic for transforming GRPC exceptions into {@link ApiException}s. This logic is shared
* amongst all of the call types.
* amongst all the call types.
*
* <p>Package-private for internal use.
*/
class GrpcApiExceptionFactory {

@VisibleForTesting static final String ERROR_DETAIL_KEY = "grpc-status-details-bin";
private final ImmutableSet<Code> retryableCodes;

GrpcApiExceptionFactory(Set<Code> retryCodes) {
Expand All @@ -54,10 +60,10 @@ class GrpcApiExceptionFactory {
ApiException create(Throwable throwable) {
if (throwable instanceof StatusException) {
StatusException e = (StatusException) throwable;
return create(throwable, e.getStatus().getCode());
return create(throwable, e.getStatus().getCode(), e.getTrailers());
} else if (throwable instanceof StatusRuntimeException) {
StatusRuntimeException e = (StatusRuntimeException) throwable;
return create(throwable, e.getStatus().getCode());
return create(throwable, e.getStatus().getCode(), e.getTrailers());
} else if (throwable instanceof ApiException) {
return (ApiException) throwable;
} else {
Expand All @@ -67,8 +73,29 @@ ApiException create(Throwable throwable) {
}
}

private ApiException create(Throwable throwable, Status.Code statusCode) {
private ApiException create(Throwable throwable, Status.Code statusCode, Metadata metadata) {
boolean canRetry = retryableCodes.contains(GrpcStatusCode.grpcCodeToStatusCode(statusCode));
return ApiExceptionFactory.createException(throwable, GrpcStatusCode.of(statusCode), canRetry);
GrpcStatusCode grpcStatusCode = GrpcStatusCode.of(statusCode);

if (metadata == null) {
return ApiExceptionFactory.createException(throwable, grpcStatusCode, canRetry);
}

byte[] bytes = metadata.get(Metadata.Key.of(ERROR_DETAIL_KEY, Metadata.BINARY_BYTE_MARSHALLER));
if (bytes == null) {
return ApiExceptionFactory.createException(throwable, grpcStatusCode, canRetry);
}

com.google.rpc.Status status;
try {
status = com.google.rpc.Status.parseFrom(bytes);
} catch (InvalidProtocolBufferException e) {
return ApiExceptionFactory.createException(throwable, grpcStatusCode, canRetry);
}

ErrorDetails.Builder errorDetailsBuilder = ErrorDetails.builder();
errorDetailsBuilder.setRawErrorMessages(status.getDetailsList());
return ApiExceptionFactory.createException(
throwable, grpcStatusCode, canRetry, errorDetailsBuilder.build());
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
/*
* Copyright 2022 Google LLC
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are
* met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above
* copyright notice, this list of conditions and the following disclaimer
* in the documentation and/or other materials provided with the
* distribution.
* * Neither the name of Google LLC nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
package com.google.api.gax.grpc;

import static com.google.api.gax.grpc.GrpcApiExceptionFactory.ERROR_DETAIL_KEY;

import com.google.api.gax.rpc.ApiException;
import com.google.api.gax.rpc.ErrorDetails;
import com.google.common.collect.ImmutableList;
import com.google.common.truth.Truth;
import com.google.protobuf.Any;
import com.google.protobuf.Duration;
import com.google.rpc.ErrorInfo;
import com.google.rpc.RetryInfo;
import com.google.rpc.Status;
import io.grpc.Metadata;
import io.grpc.StatusException;
import io.grpc.StatusRuntimeException;
import java.util.Collections;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.junit.runners.JUnit4;

@RunWith(JUnit4.class)
public class GrpcApiExceptionFactoryTest {

private static final ErrorInfo ERROR_INFO =
ErrorInfo.newBuilder()
.setDomain("googleapis.com")
.setReason("SERVICE_DISABLED")
.putAllMetadata(Collections.emptyMap())
.build();

private static final RetryInfo RETRY_INFO =
RetryInfo.newBuilder().setRetryDelay(Duration.newBuilder().setSeconds(213).build()).build();

private static final ImmutableList<Any> RAW_ERROR_MESSAGES =
ImmutableList.of(Any.pack(ERROR_INFO), Any.pack(RETRY_INFO));

private static final ErrorDetails ERROR_DETAILS =
ErrorDetails.builder().setRawErrorMessages(RAW_ERROR_MESSAGES).build();

private static final io.grpc.Status GRPC_STATUS = io.grpc.Status.CANCELLED;

private GrpcApiExceptionFactory factory;

@Before
public void setUp() throws Exception {
factory = new GrpcApiExceptionFactory(Collections.emptySet());
}

@Test
public void create_shouldCreateApiExceptionWithErrorDetailsForStatusException() {
Metadata trailers = new Metadata();
Status status = Status.newBuilder().addAllDetails(RAW_ERROR_MESSAGES).build();
trailers.put(
Metadata.Key.of(ERROR_DETAIL_KEY, Metadata.BINARY_BYTE_MARSHALLER), status.toByteArray());
StatusException statusException = new StatusException(GRPC_STATUS, trailers);

ApiException actual = factory.create(statusException);

Truth.assertThat(actual.getErrorDetails()).isEqualTo(ERROR_DETAILS);
}

@Test
public void create_shouldCreateApiExceptionWithErrorDetailsForStatusRuntimeException() {
Metadata trailers = new Metadata();
Status status = Status.newBuilder().addAllDetails(RAW_ERROR_MESSAGES).build();
trailers.put(
Metadata.Key.of(ERROR_DETAIL_KEY, Metadata.BINARY_BYTE_MARSHALLER), status.toByteArray());
StatusRuntimeException statusException = new StatusRuntimeException(GRPC_STATUS, trailers);

ApiException actual = factory.create(statusException);

Truth.assertThat(actual.getErrorDetails()).isEqualTo(ERROR_DETAILS);
}

@Test
public void create_shouldCreateApiExceptionWithNoErrorDetailsIfMetadataIsNull() {
StatusRuntimeException statusException = new StatusRuntimeException(GRPC_STATUS, null);

ApiException actual = factory.create(statusException);

Truth.assertThat(actual.getErrorDetails()).isNull();
}

@Test
public void create_shouldCreateApiExceptionWithNoErrorDetailsIfMetadataDoesNotHaveErrorDetails() {
StatusRuntimeException statusException =
new StatusRuntimeException(GRPC_STATUS, new Metadata());

ApiException actual = factory.create(statusException);

Truth.assertThat(actual.getErrorDetails()).isNull();
}

@Test
public void create_shouldCreateApiExceptionWithNoErrorDetailsIfStatusIsMalformed() {
Metadata trailers = new Metadata();
Status status = Status.newBuilder().addDetails(Any.pack(ERROR_INFO)).build();
byte[] bytes = status.toByteArray();
// manually manipulate status bytes array
bytes[0] = 123;
trailers.put(Metadata.Key.of(ERROR_DETAIL_KEY, Metadata.BINARY_BYTE_MARSHALLER), bytes);
StatusRuntimeException statusException = new StatusRuntimeException(GRPC_STATUS, trailers);

ApiException actual = factory.create(statusException);

Truth.assertThat(actual.getErrorDetails()).isNull();
}
}
2 changes: 2 additions & 0 deletions gax/BUILD.bazel
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ _JAVA_COPTS = [

_COMPILE_DEPS = [
"@com_google_api_api_common//jar",
"@com_google_api_grpc_proto_google_common_protos//jar",
"@com_google_protobuf_java//jar",
"@com_google_auth_google_auth_library_credentials//jar",
"@com_google_auth_google_auth_library_oauth2_http//jar",
"@com_google_auto_value_auto_value//jar",
Expand Down
3 changes: 2 additions & 1 deletion gax/build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ project.version = "2.14.0" // {x-version-update:gax:current}

dependencies {
api(libraries['maven.com_google_api_api_common'],
libraries['maven.com_google_auth_google_auth_library_credentials'],
libraries['maven.com_google_api_grpc_proto_google_common_protos'],
libraries['maven.com_google_auth_google_auth_library_credentials'],
libraries['maven.org_threeten_threetenbp'])

implementation(libraries['maven.com_google_auth_google_auth_library_oauth2_http'],
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -42,4 +42,9 @@ public AbortedException(
String message, Throwable cause, StatusCode statusCode, boolean retryable) {
super(message, cause, statusCode, retryable);
}

public AbortedException(
Throwable cause, StatusCode statusCode, boolean retryable, ErrorDetails errorDetails) {
super(cause, statusCode, retryable, errorDetails);
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -42,4 +42,9 @@ public AlreadyExistsException(
String message, Throwable cause, StatusCode statusCode, boolean retryable) {
super(message, cause, statusCode, retryable);
}

public AlreadyExistsException(
Throwable cause, StatusCode statusCode, boolean retryable, ErrorDetails errorDetails) {
super(cause, statusCode, retryable, errorDetails);
}
}
55 changes: 52 additions & 3 deletions gax/src/main/java/com/google/api/gax/rpc/ApiException.java
Original file line number Diff line number Diff line change
Expand Up @@ -30,24 +30,34 @@
package com.google.api.gax.rpc;

import com.google.common.base.Preconditions;
import java.util.Map;

/** Represents an exception thrown during an RPC call. */
public class ApiException extends RuntimeException {

private static final long serialVersionUID = -4375114339928877996L;

private final ErrorDetails errorDetails;
private final StatusCode statusCode;
private final boolean retryable;

public ApiException(Throwable cause, StatusCode statusCode, boolean retryable) {
super(cause);
this.statusCode = Preconditions.checkNotNull(statusCode);
this.retryable = retryable;
this(cause, statusCode, retryable, null);
}

public ApiException(String message, Throwable cause, StatusCode statusCode, boolean retryable) {
super(message, cause);
this.statusCode = Preconditions.checkNotNull(statusCode);
this.retryable = retryable;
this.errorDetails = null;
}

public ApiException(
Throwable cause, StatusCode statusCode, boolean retryable, ErrorDetails errorDetails) {
super(cause);
this.statusCode = Preconditions.checkNotNull(statusCode);
this.retryable = retryable;
this.errorDetails = errorDetails;
}

/** Returns whether the failed request can be retried. */
Expand All @@ -59,4 +69,43 @@ public boolean isRetryable() {
public StatusCode getStatusCode() {
return statusCode;
}

/**
* Returns the reason of the exception. This is a constant value that identifies the proximate
* cause of the error. e.g. SERVICE_DISABLED
*/
public String getReason() {
if (isErrorInfoEmpty()) {
return null;
}
return errorDetails.getErrorInfo().getReason();
}

/**
* Returns the logical grouping to which the "reason" belongs. The error domain is typically the
* registered service name of the tool or product that generates the error. e.g. googleapis.com
*/
public String getDomain() {
if (isErrorInfoEmpty()) {
return null;
}
return errorDetails.getErrorInfo().getDomain();
}

/** Returns additional structured details about this exception. */
public Map<String, String> getMetadata() {
if (isErrorInfoEmpty()) {
return null;
}
return errorDetails.getErrorInfo().getMetadataMap();
}

/** Returns all standard error messages that server sends. */
public ErrorDetails getErrorDetails() {
return errorDetails;
}

private boolean isErrorInfoEmpty() {
return errorDetails == null || errorDetails.getErrorInfo() == null;
}
}
Loading

0 comments on commit 00c3b9d

Please sign in to comment.