fix(gax): propagate structured LRO error details to ApiException

[nnicolee]

Description:

When a Long-Running Operation (LRO) completes with a failure, structured error details inside the operation's error payload were previously dropped. This made it impossible for client applications to access fine-grained provider error messages (such as quota or usage violations) via the public ApiException.getErrorDetails() API.

This PR implements Phase 1 of the LRO error propagation design by establishing the transport-agnostic mechanism to propagate structured LRO error details in GAX for both gRPC and HTTP/JSON (REST) transports.

Design doc: go/sdk:java-lro-error-details

Key Changes:

1. Core GAX Interfaces:
   • Added support to fetch structured error details from the LRO operation snapshots.
2. gRPC Transport:
   • Implemented error details extraction from LRO operation error payloads (only populated if structured error details are present).
   • Updated the gRPC response transformer to pass these error details when converting failed operations into exception objects.
   • Added unit test validation checking details propagation for LRO failures over gRPC.
3. HTTP/JSON (REST) Transport:
   • Implemented error details extraction and storage in REST LRO operation snapshots (only populated if structured error details are present).
   • Updated the REST response transformer to fetch and pass the snapshot's error details.
   • Added unit test validation checking details propagation for LRO failures over HTTP/JSON.
4. Integration & Unit Testing:
   • Added a Showcase integration test verifying successful end-to-end propagation of error details over gRPC.
   • Note on HTTP/JSON Integration Test: Deferring the end-to-end Showcase integration test for HTTP/JSON LROs to Phase 2 because HTTP/JSON relies on a TypeRegistry in generated stubs to parse custom/standard payload types packed in Any details, the test client fails to deserialize these details. Once we roll out the generator changes in Phase 2 to automatically add error details types to generated stub registries, the Showcase REST integration test will pass out-of-the-box. We have added unit tests to cover the HTTP/JSON LRO response parsing pathway in the interim.

Testing:

• Verified that all gRPC and HTTP/JSON transformer unit tests pass successfully:
  mvn test -pl sdk-platform-java/gax-java/gax-grpc,sdk-platform-java/gax-java/gax-httpjson -Dtest=ProtoOperationTransformersTest
• Verified that the Showcase LRO integration test passes successfully:
  mvn test -pl java-showcase/gapic-showcase -Dtest=ITLongRunningOperation

[gemini-code-assist]

Code Review

This pull request adds support for propagating error details in long-running operations (LRO) for both gRPC and HTTP/JSON transports. This is achieved by adding getErrorDetails() to the OperationSnapshot interface and implementing it in GrpcOperationSnapshot and HttpJsonOperationSnapshot. The ProtoOperationTransformers are updated to pass these error details when throwing exceptions, and corresponding integration and unit tests are added. Feedback on the changes includes renaming a misleadingly named test that asserts error propagation rather than dropping, and ensuring that ErrorDetails is only instantiated and returned in GrpcOperationSnapshot and HttpJsonOperationSnapshot if there are actual details present (i.e., checking that the details count is greater than zero).

[nnicolee]

/gemini review

[gemini-code-assist]

Code Review

This pull request adds support for propagating error details from long-running operations (LROs) across both gRPC and HTTP/JSON transports by introducing a getErrorDetails() method to the OperationSnapshot interface and implementing it in GrpcOperationSnapshot and HttpJsonOperationSnapshot. It also updates ProtoOperationTransformers to pass these error details when throwing exceptions and adds corresponding integration and unit tests. Feedback on the changes highlights a potential issue in HttpJsonOperationSnapshot.Builder.setOperation where errorDetails is not reset to null if the operation has no error, which could lead to stale state if the builder is reused.

[sonarqubecloud]

Quality Gate failed for 'gapic-generator-java-root'

Failed conditions
60.7% Coverage on New Code (required ≥ 80%)
3.2% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud

[sonarqubecloud]

Quality Gate failed for 'gapic-generator-java-root'

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)
3.2% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud

[nnicolee]

/gemini review

[gemini-code-assist]

Code Review

This pull request adds support for propagating error details in long-running operations (LRO) for both gRPC and HTTP/JSON transports. It introduces the getErrorDetails() method to the OperationSnapshot interface and implements it in GrpcOperationSnapshot and HttpJsonOperationSnapshot. Additionally, it updates the ProtoOperationTransformers to include these error details when constructing exceptions, and adds corresponding unit and integration tests. The reviewer suggested adding a timeout to the operationFuture.get() call in the new integration test to prevent the test suite from hanging indefinitely.

[lqiu96]

qq, what do you think about returning a non-null empty ErrorDetails instead of null here? I think this would be similar to the proto messages where there is a default value.

IIUC, this is primarily used within ProtoOperationTransformers's ResponseTransformer which operations on a response and it should return Status.getDefaultInstance() if there is no error