tessl/maven-com-google-api-grpc--proto-google-common-protos

Java Protocol Buffer classes for Google's common protos, providing type-safe access to core Google Cloud API structures and gRPC service definitions

—

Pending

Overview

Eval results

Files

RPC Status and Error Handling

Name: tessl/maven-com-google-api-grpc--proto-google-common-protos
Author: tessl

Standard error model and status codes for consistent error handling across gRPC services. Includes structured error details and context information for debugging and client error handling.

Core Status Types

Status

The canonical error model used across gRPC services.

class Status {
  int getCode();
  String getMessage();
  repeated Any getDetailsList();
  
  static Status.Builder newBuilder();
  Status.Builder toBuilder();
  static Status parseFrom(byte[] data);
  static Status parseFrom(InputStream input);
  byte[] toByteArray();
}

interface StatusOrBuilder {
  int getCode();
  String getMessage();
  java.util.List<com.google.protobuf.Any> getDetailsList();
  int getDetailsCount();
  com.google.protobuf.Any getDetails(int index);
}

Code

Standard gRPC status codes indicating the error type.

enum Code {
  OK(0),
  CANCELLED(1),
  UNKNOWN(2),
  INVALID_ARGUMENT(3),
  DEADLINE_EXCEEDED(4),
  NOT_FOUND(5),
  ALREADY_EXISTS(6),
  PERMISSION_DENIED(7),
  RESOURCE_EXHAUSTED(8),
  FAILED_PRECONDITION(9),
  ABORTED(10),
  OUT_OF_RANGE(11),
  UNIMPLEMENTED(12),
  INTERNAL(13),
  UNAVAILABLE(14),
  DATA_LOSS(15),
  UNAUTHENTICATED(16);
  
  int getNumber();
  static Code forNumber(int value);
  static Code valueOf(int value);
}

Error Detail Types

ErrorInfo

Structured error information with reason, domain, and metadata.

class ErrorInfo {
  String getReason();
  String getDomain();
  Struct getMetadata();
  
  static ErrorInfo.Builder newBuilder();
}

BadRequest

Details for field-level validation errors.

class BadRequest {
  repeated FieldViolation getFieldViolationsList();
  
  static BadRequest.Builder newBuilder();
}

class BadRequest.FieldViolation {
  String getField();
  String getDescription();
  
  static FieldViolation.Builder newBuilder();
}

PreconditionFailure

Information about failed preconditions.

class PreconditionFailure {
  repeated Violation getViolationsList();
  
  static PreconditionFailure.Builder newBuilder();
}

class PreconditionFailure.Violation {
  String getType();
  String getSubject();
  String getDescription();
  
  static Violation.Builder newBuilder();
}

QuotaFailure

Details about quota violations.

class QuotaFailure {
  repeated Violation getViolationsList();
  
  static QuotaFailure.Builder newBuilder();
}

class QuotaFailure.Violation {
  String getSubject();
  String getDescription();
  
  static Violation.Builder newBuilder();
}

RetryInfo

Information about retry timing for retryable errors.

class RetryInfo {
  Duration getRetryDelay();
  
  static RetryInfo.Builder newBuilder();
}

DebugInfo

Debug information for development and troubleshooting.

class DebugInfo {
  repeated String getStackEntriesList();
  String getDetail();
  
  static DebugInfo.Builder newBuilder();
}

ResourceInfo

Information about the resource that caused the error.

class ResourceInfo {
  String getResourceType();
  String getResourceName();
  String getOwner();
  String getDescription();
  
  static ResourceInfo.Builder newBuilder();
}

Help

Links and information for error resolution.

class Help {
  repeated Link getLinksList();
  
  static Help.Builder newBuilder();
}

class Help.Link {
  String getDescription();
  String getUrl();
  
  static Link.Builder newBuilder();
}

LocalizedMessage

Localized error messages for user-facing errors.

class LocalizedMessage {
  String getLocale();
  String getMessage();
  
  static LocalizedMessage.Builder newBuilder();
}

Context Information

AttributeContext

Request context attributes for audit and debugging.

class AttributeContext {
  Request getRequest();
  Response getResponse();
  Resource getResource();
  Peer getSource();
  Peer getDestination();
  
  static AttributeContext.Builder newBuilder();
}

class AttributeContext.Request {
  String getId();
  String getMethod();
  Struct getHeaders();
  String getPath();
  String getHost();
  String getScheme();
  String getQuery();
  Timestamp getTime();
  long getSize();
  String getProtocol();
  String getReason();
  Auth getAuth();
  
  static Request.Builder newBuilder();
}

class AttributeContext.Response {
  long getCode();
  long getSize();
  Struct getHeaders();
  Timestamp getTime();
  Duration getBackendLatency();
  
  static Response.Builder newBuilder();
}

class AttributeContext.Peer {
  String getIp();
  long getPort();
  Struct getLabels();
  String getPrincipal();
  String getRegionCode();
  
  static Peer.Builder newBuilder();
}

Usage Examples

Creating Basic Status

import com.google.rpc.Status;
import com.google.rpc.Code;

// Success status
Status success = Status.newBuilder()
    .setCode(Code.OK.getNumber())
    .setMessage("Operation completed successfully")
    .build();

// Error status
Status error = Status.newBuilder()
    .setCode(Code.INVALID_ARGUMENT.getNumber())
    .setMessage("Invalid user ID provided")
    .build();

Creating Status with Error Details

import com.google.rpc.BadRequest;
import com.google.rpc.ErrorInfo;
import com.google.protobuf.Any;

// Create field validation error
BadRequest.FieldViolation fieldError = BadRequest.FieldViolation.newBuilder()
    .setField("email")
    .setDescription("Invalid email format")
    .build();

BadRequest badRequest = BadRequest.newBuilder()
    .addFieldViolations(fieldError)
    .build();

// Create error info
ErrorInfo errorInfo = ErrorInfo.newBuilder()
    .setReason("INVALID_EMAIL_FORMAT")
    .setDomain("myservice.googleapis.com")
    .build();

// Pack details into Any messages
Any badRequestAny = Any.pack(badRequest);
Any errorInfoAny = Any.pack(errorInfo);

// Create status with details
Status detailedError = Status.newBuilder()
    .setCode(Code.INVALID_ARGUMENT.getNumber())
    .setMessage("Validation failed")
    .addDetails(badRequestAny)
    .addDetails(errorInfoAny)
    .build();

Handling Status Responses

// Check if operation was successful
public void handleResponse(Status status) {
    Code code = Code.forNumber(status.getCode());
    
    switch (code) {
        case OK:
            System.out.println("Success: " + status.getMessage());
            break;
            
        case INVALID_ARGUMENT:
            System.err.println("Invalid argument: " + status.getMessage());
            handleValidationErrors(status.getDetailsList());
            break;
            
        case NOT_FOUND:
            System.err.println("Resource not found: " + status.getMessage());
            break;
            
        case PERMISSION_DENIED:
            System.err.println("Access denied: " + status.getMessage());
            break;
            
        case RESOURCE_EXHAUSTED:
            System.err.println("Quota exceeded: " + status.getMessage());
            handleRetry(status.getDetailsList());
            break;
            
        default:
            System.err.println("Error " + code + ": " + status.getMessage());
    }
}

private void handleValidationErrors(java.util.List<Any> details) {
    for (Any detail : details) {
        if (detail.is(BadRequest.class)) {
            try {
                BadRequest badRequest = detail.unpack(BadRequest.class);
                for (BadRequest.FieldViolation violation : badRequest.getFieldViolationsList()) {
                    System.err.println("Field '" + violation.getField() + "': " + violation.getDescription());
                }
            } catch (InvalidProtocolBufferException e) {
                System.err.println("Error unpacking BadRequest: " + e.getMessage());
            }
        }
    }
}

private void handleRetry(java.util.List<Any> details) {
    for (Any detail : details) {
        if (detail.is(RetryInfo.class)) {
            try {
                RetryInfo retryInfo = detail.unpack(RetryInfo.class);
                Duration delay = retryInfo.getRetryDelay();
                long seconds = delay.getSeconds() + delay.getNanos() / 1_000_000_000L;
                System.out.println("Retry after " + seconds + " seconds");
            } catch (InvalidProtocolBufferException e) {
                System.err.println("Error unpacking RetryInfo: " + e.getMessage());
            }
        }
    }
}

Exception Mapping

import io.grpc.Status.Code as GrpcCode;
import io.grpc.StatusException;

// Convert between Proto Status and gRPC Status
public StatusException toGrpcException(com.google.rpc.Status protoStatus) {
    GrpcCode grpcCode = GrpcCode.values()[protoStatus.getCode()];
    io.grpc.Status grpcStatus = io.grpc.Status.fromCode(grpcCode)
        .withDescription(protoStatus.getMessage());
    
    return grpcStatus.asException();
}

// Create Proto Status from gRPC Status
public com.google.rpc.Status fromGrpcStatus(io.grpc.Status grpcStatus) {
    return com.google.rpc.Status.newBuilder()
        .setCode(grpcStatus.getCode().value())
        .setMessage(grpcStatus.getDescription() != null ? grpcStatus.getDescription() : "")
        .build();
}

Common Status Code Usage

Code	Usage	Retry?
`OK`	Success	No
`CANCELLED`	Request cancelled by client	No
`INVALID_ARGUMENT`	Invalid request parameters	No
`DEADLINE_EXCEEDED`	Request timeout	Yes
`NOT_FOUND`	Resource doesn't exist	No
`ALREADY_EXISTS`	Resource already exists	No
`PERMISSION_DENIED`	Access denied	No
`RESOURCE_EXHAUSTED`	Rate limited or quota exceeded	Yes
`FAILED_PRECONDITION`	System not in valid state	No
`UNAVAILABLE`	Service temporarily unavailable	Yes
`INTERNAL`	Internal server error	No
`UNAUTHENTICATED`	Authentication required	No

Best Practices

Use appropriate status codes: Choose the most specific code that describes the error condition
Provide meaningful messages: Include actionable information in the message field
Add structured details: Use typed error details for programmatic error handling
Include context: Add relevant context information for debugging
Handle retryable errors: Implement proper retry logic for transient failures
Localize messages: Use LocalizedMessage for user-facing errors

Install with Tessl CLI

npx tessl i tessl/maven-com-google-api-grpc--proto-google-common-protos

docs

api-infrastructure.md

longrunning-operations.md

rpc-status.md

tile.json