RichStatus

ugrpc::RichStatus is a userver wrapper around google::rpc::Status that provides a convenient API for creating and managing gRPC status responses with rich error details. It follows the Google AIP-193 standard for structured error reporting, allowing services to provide detailed error information that clients can use for better error handling and user experience.

Introduction to RichStatus

ugrpc::RichStatus allows you to create gRPC status responses with structured error information conforming to the Google RPC error model. It supports adding multiple error details of various types to provide comprehensive error information to clients.

The main benefits of using ugrpc::RichStatus include:

• Structured error information that can be programmatically processed by clients
• Support for multiple error detail types in a single response
• Easy conversion to and from standard gRPC status objects
• Compliance with Google AIP-193 standard for error details

Creating RichStatus with Error Details

You can create a ugrpc::RichStatus in several ways:

1. Default constructor creates an OK status with no error details:

       ugrpc::RichStatus status;  // Creates OK status

2. From a gRPC status:

       grpc::Status grpc_status{grpc::StatusCode::NOT_FOUND, "Resource not found"};
       ugrpc::RichStatus status{grpc_status};

3. With status code, message, and error details:

       ugrpc::RichStatus status{
           grpc::StatusCode::INVALID_ARGUMENT,
           "Invalid request",
           ugrpc::BadRequest{{{"field", "error description"}}}
       };

4. Adding details after creation:

       auto status =
           ugrpc::RichStatus(grpc::StatusCode::OUT_OF_RANGE, "value out of range")
               .AddDetail(ugrpc::RetryInfo{std::chrono::seconds{1}})
               .AddDetail(ugrpc::DebugInfo{{"line1"}, "detail"});

Supported Error Detail Types

ugrpc::RichStatus supports all standard Google error detail types:

• ugrpc::ErrorInfo - Provides structured error information about the cause of an error
• ugrpc::RetryInfo - Describes when the client can retry a failed request
• ugrpc::DebugInfo - Provides debugging information such as stack traces
• ugrpc::QuotaFailure - Describes quota violations that caused the request to fail
• ugrpc::PreconditionFailure - Describes preconditions that failed during request processing
• ugrpc::BadRequest - Describes violations in a client request
• ugrpc::RequestInfo - Contains metadata about the request for debugging and logging
• ugrpc::ResourceInfo - Provides information about a resource that is related to the error
• ugrpc::Help - Provides links to documentation and help resources
• ugrpc::LocalizedMessage - Provides a localized error message that is safe to return to the user

Extracting Error Details on the Client Side

When a client receives an error response with ugrpc::RichStatus details, it can extract specific error details using the TryGetDetail method:

UTEST_F(GrpcClientWithDetailedRichErrorTest, TryGetErrorDetail) {
    sample::ugrpc::GreetingRequest out;
    out.set_name("userver");
    try {
        GetClient().SayHello(out);
        FAIL() << "Expected ResourceExhaustedError";
    } catch (const ugrpc::client::ResourceExhaustedError& e) {
        const auto& status = e.GetStatus();
        auto gstatus = ugrpc::ToGoogleRpcStatus(status);
        EXPECT_TRUE(gstatus.has_value());
 
        const auto help_detail = ugrpc::RichStatus::TryGetDetail<ugrpc::Help>(*gstatus);
        EXPECT_TRUE(help_detail.has_value());
 
        EXPECT_EQ(help_detail->links.size(), 1);
        EXPECT_EQ(help_detail->links[0].description, "test_url");
        EXPECT_EQ(help_detail->links[0].url, "http://help.url/auth/fts-documentation/tvm");
 
        const auto quota_failure_detail = ugrpc::RichStatus::TryGetDetail<ugrpc::QuotaFailure>(*gstatus);
        EXPECT_TRUE(quota_failure_detail.has_value());
 
        EXPECT_EQ(quota_failure_detail->violations.size(), 1);
        EXPECT_EQ(quota_failure_detail->violations[0].subject, "123-pipepline000");
        EXPECT_EQ(quota_failure_detail->violations[0].description, "fts quota [fts-receive] exhausted");
    }
}

Integration with gRPC Services

In a gRPC service implementation, you can return a ugrpc::RichStatus by converting it to a gRPC status:

    SayHelloResult SayHello(CallContext& /*context*/, sample::ugrpc::GreetingRequest&& /*request*/) override {
        ugrpc::RichStatus rich_status{
            grpc::StatusCode::RESOURCE_EXHAUSTED,
            "message",
            ugrpc::Help{{{"test_url", "http://help.url/auth/fts-documentation/tvm"}}},
            ugrpc::QuotaFailure{{{"123-pipepline000", "fts quota [fts-receive] exhausted"}}},
        };
 
        return rich_status.ToGrpcStatus();
    }

The ugrpc::RichStatus is automatically converted to a gRPC status with serialized error details that can be unpacked by the client.

Examples

ErrorInfo Example

    ugrpc::RichStatus status{
        grpc::StatusCode::UNAUTHENTICATED,
        "Authentication failed",
        ugrpc::ErrorInfo{
            "INVALID_TOKEN",
            "auth.example.com",
            {{"token_type", "bearer"}, {"error", "expired"}},
        },
    };

RetryInfo Example

    ugrpc::RichStatus status{
        grpc::StatusCode::UNAVAILABLE,
        "Service overloaded",
        ugrpc::RetryInfo{std::chrono::minutes{5}},
    };

BadRequest Example

    ugrpc::RichStatus status{
        grpc::StatusCode::INVALID_ARGUMENT,
        "Invalid request",
        ugrpc::BadRequest{{
            {"user.email", "Invalid email format"},
            {"user.age", "Must be between 18 and 120"},
            {"user.name", "Required field is missing"},
        }},
    };

LocalizedMessage Example

    ugrpc::RichStatus status{
        grpc::StatusCode::INVALID_ARGUMENT,
        "Invalid email address",
        ugrpc::LocalizedMessage{
            "ru-RU",
            "Неверный формат электронной почты. Пожалуйста, используйте name@example.com",
        },
    };

For more information about the Google error model, see:

• Google AIP-193
• gRPC Error Model