feat!: Actionable Error

google-cloud-datastore/clirr-ignored-differences.xml

@@ -26,4 +26,14 @@
         <method>com.google.cloud.datastore.AggregationResults runAggregation(com.google.cloud.datastore.AggregationQuery)</method>
         <differenceType>7012</differenceType>
     </difference>
+    <difference>
+        <className>com/google/cloud/datastore/DatastoreException</className>
+        <differenceType>5000</differenceType>
+        <to>com/google/cloud/grpc/BaseGrpcServiceException</to>
+    </difference>
+    <difference>
+        <className>com/google/cloud/datastore/DatastoreException</className>
+        <differenceType>5001</differenceType>
+        <to>com/google/cloud/http/BaseHttpServiceException</to>
+    </difference>
 </differences>

google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreException.java

@@ -16,11 +16,16 @@
 
 package com.google.cloud.datastore;
 
+import static com.google.cloud.BaseServiceException.isRetryable;
+
+import com.google.api.gax.rpc.ApiException;
+import com.google.api.gax.rpc.ErrorDetails;
 import com.google.cloud.BaseServiceException;
 import com.google.cloud.RetryHelper.RetryHelperException;
-import com.google.cloud.http.BaseHttpServiceException;
+import com.google.cloud.grpc.BaseGrpcServiceException;
 import com.google.common.collect.ImmutableSet;
 import java.io.IOException;
+import java.util.Map;
 import java.util.Set;
 
 /**
@@ -29,7 +34,7 @@
  * @see <a href="https://cloud.google.com/datastore/docs/concepts/errors#Error_Codes">Google Cloud
  *     Datastore error codes</a>
  */
-public final class DatastoreException extends BaseHttpServiceException {
+public final class DatastoreException extends BaseGrpcServiceException {
 
   // see https://cloud.google.com/datastore/docs/concepts/errors#Error_Codes"
   private static final Set<Error> RETRYABLE_ERRORS =
@@ -38,22 +43,96 @@ public final class DatastoreException extends BaseHttpServiceException {
           new Error(4, "DEADLINE_EXCEEDED", false),
           new Error(14, "UNAVAILABLE", true));
   private static final long serialVersionUID = 2663750991205874435L;
+  private String reason;
+  private ApiException apiException;
 
   public DatastoreException(int code, String message, String reason) {
     this(code, message, reason, true, null);
+    this.reason = reason;
   }
 
   public DatastoreException(int code, String message, String reason, Throwable cause) {
-    super(code, message, reason, true, RETRYABLE_ERRORS, cause);
+    super(message, cause, code, isRetryable(code, reason, true, RETRYABLE_ERRORS));
+    this.reason = reason;
   }
 
   public DatastoreException(
       int code, String message, String reason, boolean idempotent, Throwable cause) {
-    super(code, message, reason, idempotent, RETRYABLE_ERRORS, cause);
+    super(message, cause, code, isRetryable(code, reason, idempotent, RETRYABLE_ERRORS));
+    this.reason = reason;
   }
 
   public DatastoreException(IOException exception) {
-    super(exception, true, RETRYABLE_ERRORS);
+    super(exception, true);
+  }
+
+  public DatastoreException(ApiException apiException) {
+    super(apiException);
+    this.apiException = apiException;
+  }
+
+  /**
+   * Checks the underlying reason of the exception and if it's {@link ApiException} then return the
+   * specific domain otherwise null.
+   *
+   * @see <a
+   *     href="https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto#L125">Domain</a>
+   * @return the logical grouping to which the "reason" belongs.
+   */
+  public String getDomain() {
+    if (this.apiException != null) {
+      return this.apiException.getDomain();
+    }
+    return null;
+  }
+
+  /**
+   * Checks the underlying reason of the exception and if it's {@link ApiException} then return a
+   * map of key-value pairs otherwise null.
+   *
+   * @see <a
+   *     href="https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto#L135">Metadata</a>
+   * @return the map of additional structured details about an error.
+   */
+  public Map<String, String> getMetadata() {
+    if (this.apiException != null) {
+      return this.apiException.getMetadata();
+    }
+    return null;
+  }
+
+  /**
+   * Checks the underlying reason of the exception and if it's {@link ApiException} then return the
+   * ErrorDetails otherwise null.
+   *
+   * @see <a
+   *     href="https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto">Status</a>
+   * @see <a
+   *     href="https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto">Error
+   *     Details</a>
+   * @return An object containing getters for structured objects from error_details.proto.
+   */
+  public ErrorDetails getErrorDetails() {
+    if (this.apiException != null) {
+      return this.apiException.getErrorDetails();
+    }
+    return null;
+  }
+
+  /**
+   * Checks the underlying reason of the exception and if it's {@link ApiException} then return the
+   * reason otherwise null/custom reason.
+   *
+   * @see <a
+   *     href="https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto#L117">Reason</a>
+   * @return the reason of an error.
+   */
+  @Override
+  public String getReason() {
+    if (this.apiException != null) {
+      return this.apiException.getReason();
+    }
+    return this.reason;
   }
 
   /**
@@ -64,6 +143,9 @@ public DatastoreException(IOException exception) {
    */
   static DatastoreException translateAndThrow(RetryHelperException ex) {
     BaseServiceException.translate(ex);
+    if (ex.getCause() instanceof ApiException) {
+      throw new DatastoreException((ApiException) ex.getCause());
+    }
     throw new DatastoreException(UNKNOWN_CODE, ex.getMessage(), null, ex.getCause());
   }
 

google-cloud-datastore/src/main/java/com/google/cloud/datastore/spi/v1/GrpcDatastoreRpc.java

@@ -185,8 +185,7 @@ private ClientContext getClientContext(DatastoreOptions datastoreOptions) throws
     settingsBuilder.setInternalHeaderProvider(internalHeaderProvider);
     settingsBuilder.setHeaderProvider(
         datastoreOptions.getMergedHeaderProvider(new NoHeaderProvider()));
-    ClientContext clientContext = ClientContext.create(settingsBuilder.build());
-    return clientContext;
+    return ClientContext.create(settingsBuilder.build());
   }
 
   private String getResourceToken(DatastoreOptions datastoreOptions) {

google-cloud-datastore/src/test/java/com/google/cloud/datastore/DatastoreExceptionTest.java

@@ -16,6 +16,9 @@
 
 package com.google.cloud.datastore;
 
+import static com.google.common.truth.Truth.assertThat;
+import static com.google.rpc.Code.FAILED_PRECONDITION;
+import static java.util.Collections.singletonMap;
 import static org.easymock.EasyMock.createMock;
 import static org.easymock.EasyMock.expect;
 import static org.easymock.EasyMock.replay;
@@ -24,11 +27,20 @@
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
 import static org.junit.Assert.assertTrue;
 import static org.junit.Assert.fail;
 
+import com.google.api.gax.grpc.GrpcStatusCode;
+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;
 import com.google.cloud.BaseServiceException;
 import com.google.cloud.RetryHelper;
+import com.google.protobuf.Any;
+import com.google.rpc.ErrorInfo;
+import io.grpc.Status;
 import java.io.IOException;
 import java.net.SocketTimeoutException;
 import org.junit.Test;
@@ -76,39 +88,78 @@ public void testDatastoreException() {
     assertEquals("message", exception.getMessage());
     assertFalse(exception.isRetryable());
     assertSame(cause, exception.getCause());
+
+    exception = new DatastoreException(2, "message", "INTERNAL", true, cause);
+    assertEquals(2, exception.getCode());
+    assertEquals("INTERNAL", exception.getReason());
+    assertEquals("message", exception.getMessage());
+    assertFalse(exception.isRetryable());
+    assertSame(cause, exception.getCause());
+
+    ApiException apiException = createApiException();
+    exception = new DatastoreException(apiException);
+    assertEquals(400, exception.getCode());
+    assertEquals("MISSING_INDEXES", exception.getReason());
+    assertThat(exception.getMetadata())
+        .isEqualTo(singletonMap("missing_indexes_url", "__some__url__"));
+    assertSame(apiException, exception.getCause());
+  }
+
+  @Test
+  public void testApiException() {
+    ApiException apiException = createApiException();
+    DatastoreException datastoreException = new DatastoreException(apiException);
+
+    assertThat(datastoreException.getReason()).isEqualTo("MISSING_INDEXES");
+    assertThat(datastoreException.getDomain()).isEqualTo("datastore.googleapis.com");
+    assertThat(datastoreException.getMetadata())
+        .isEqualTo(singletonMap("missing_indexes_url", "__some__url__"));
+    assertThat(datastoreException.getErrorDetails()).isEqualTo(apiException.getErrorDetails());
   }
 
   @Test
   public void testTranslateAndThrow() {
     Exception cause = new DatastoreException(14, "message", "UNAVAILABLE");
-    RetryHelper.RetryHelperException exceptionMock =
+    final RetryHelper.RetryHelperException exceptionMock =
         createMock(RetryHelper.RetryHelperException.class);
     expect(exceptionMock.getCause()).andReturn(cause).times(2);
     replay(exceptionMock);
-    try {
-      DatastoreException.translateAndThrow(exceptionMock);
-    } catch (BaseServiceException ex) {
-      assertEquals(14, ex.getCode());
-      assertEquals("message", ex.getMessage());
-      assertTrue(ex.isRetryable());
-    } finally {
-      verify(exceptionMock);
-    }
+    BaseServiceException ex =
+        assertThrows(
+            BaseServiceException.class, () -> DatastoreException.translateAndThrow(exceptionMock));
+    assertEquals(14, ex.getCode());
+    assertEquals("message", ex.getMessage());
+    assertTrue(ex.isRetryable());
+    verify(exceptionMock);
+
+    cause = createApiException();
+    final RetryHelper.RetryHelperException exceptionMock2 =
+        createMock(RetryHelper.RetryHelperException.class);
+    expect(exceptionMock2.getCause()).andReturn(cause).times(3);
+    replay(exceptionMock2);
+    DatastoreException ex2 =
+        assertThrows(
+            DatastoreException.class, () -> DatastoreException.translateAndThrow(exceptionMock2));
+    assertThat(ex2.getReason()).isEqualTo("MISSING_INDEXES");
+    assertThat(ex2.getDomain()).isEqualTo("datastore.googleapis.com");
+    assertThat(ex2.getMetadata()).isEqualTo(singletonMap("missing_indexes_url", "__some__url__"));
+    assertThat(ex2.getErrorDetails()).isEqualTo(((ApiException) cause).getErrorDetails());
+    verify(exceptionMock2);
+
     cause = new IllegalArgumentException("message");
-    exceptionMock = createMock(RetryHelper.RetryHelperException.class);
-    expect(exceptionMock.getMessage()).andReturn("message").times(1);
-    expect(exceptionMock.getCause()).andReturn(cause).times(2);
-    replay(exceptionMock);
-    try {
-      DatastoreException.translateAndThrow(exceptionMock);
-    } catch (BaseServiceException ex) {
-      assertEquals(DatastoreException.UNKNOWN_CODE, ex.getCode());
-      assertEquals("message", ex.getMessage());
-      assertFalse(ex.isRetryable());
-      assertSame(cause, ex.getCause());
-    } finally {
-      verify(exceptionMock);
-    }
+    final RetryHelper.RetryHelperException exceptionMock3 =
+        createMock(RetryHelper.RetryHelperException.class);
+    expect(exceptionMock3.getMessage()).andReturn("message").times(1);
+    expect(exceptionMock3.getCause()).andReturn(cause).times(3);
+    replay(exceptionMock3);
+    BaseServiceException ex3 =
+        assertThrows(
+            BaseServiceException.class, () -> DatastoreException.translateAndThrow(exceptionMock3));
+    assertEquals(DatastoreException.UNKNOWN_CODE, ex3.getCode());
+    assertEquals("message", ex3.getMessage());
+    assertFalse(ex3.isRetryable());
+    assertSame(cause, ex3.getCause());
+    verify(exceptionMock3);
   }
 
   @Test
@@ -121,4 +172,26 @@ public void testThrowInvalidRequest() {
       assertEquals("message a 1", ex.getMessage());
     }
   }
+
+  private ApiException createApiException() {
+    // Simulating google.rpc.Status with an ErrorInfo
+    ErrorInfo errorInfo =
+        ErrorInfo.newBuilder()
+            .setDomain("datastore.googleapis.com")
+            .setReason("MISSING_INDEXES")
+            .putMetadata("missing_indexes_url", "__some__url__")
+            .build();
+    com.google.rpc.Status status =
+        com.google.rpc.Status.newBuilder()
+            .setCode(FAILED_PRECONDITION.getNumber())
+            .setMessage("The query requires indexes.")
+            .addDetails(Any.pack(errorInfo))
+            .build();
+
+    // Using Gax to convert to ApiException
+    StatusCode statusCode = GrpcStatusCode.of(Status.fromCodeValue(status.getCode()).getCode());
+    ErrorDetails errorDetails =
+        ErrorDetails.builder().setRawErrorMessages(status.getDetailsList()).build();
+    return ApiExceptionFactory.createException(null, statusCode, true, errorDetails);
+  }
 }