[GRPC] Map to proper GRPC status codes and achieve exception handling parity with HTTP by karenyrx · Pull Request #18925 · opensearch-project/OpenSearch

karenyrx · 2025-08-05T16:43:24Z

Description

Improve transport-grpc error handling, to use proper GRPC conventions, but also maintain parity with HTTP APIs.

Replace HTTP status codes in responses with gRPC ones: Previously, returned 2xx, 4xx, 5xx in the protobuf responses, but now return GRPC codes (0, 1, 2)
Proper gRPC error codes: Previously, all GRPC errors were mapped to the GRPC.INTERNAL code. Now returns the correct fine-grained status codes (INVALID_ARGUMENT, RESOURCE_EXHAUSTED, etc.)
Exact Parity of error messages: Both APIs now use constants and shared methods to provide identical error messages, including use the correct wrapping.
Graceful Fallback: Uses appropriate fallback messages for null/empty exception messages (parity with HTTP as well)

Detailed Examples

1. Remove HTTP status codes from protobuf messages

Before: HTTP status codes in protobuf responses

ResponseItem {
  status: 201  // HTTP Created status code
}

After: gRPC status codes in protobuf responses

ResponseItem {
  status: 0    // gRPC OK status code
}

2. Return proper GRPC status codes instead of all showing as GRPC.INTERNAL

Before: Inconsistent status codes

OpenSearchRejectedExecutionException -> INTERNAL (status code 13)
CircuitBreakingException -> INTERNAL (status code 13)
// HTTP returned 429 TOO_MANY_REQUESTS, gRPC returned INTERNAL

After: Proper resource exhaustion status

OpenSearchRejectedExecutionException -> RESOURCE_EXHAUSTED (status code 8)
CircuitBreakingException -> RESOURCE_EXHAUSTED (status code 8)
// Message: "Too many requests" (consistent with HTTP 429)

3. Use constants for error messages so both HTTP and gRPC now use identical error messages from `ExceptionsHelper.ErrorMessages`

Before: Different error messages between HTTP and gRPC

// HTTP API returned: "Invalid argument"
// gRPC API returned: "Invalid parameter" (inconsistent)

After: Identical error messages using shared constants

// Both HTTP and gRPC return: "Invalid argument"
// (using ExceptionsHelper.ErrorMessages.INVALID_ARGUMENT)

4. Wrap error messages in the same way as HTTP

Before: Different error formats

// HTTP API: "OpenSearchException[Index not found]"
// gRPC API: "Index not found" (lost exception type context)

After: Identical error format using ExceptionsHelper.summaryMessage()

// Both APIs: "OpenSearchException[Index not found]"

Related Issues

Resolves #18926

Check List

Functionality includes testing.
API changes companion pull request created, if applicable.
Public documentation issue/PR created, if applicable.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

github-actions · 2025-08-05T17:07:40Z

❌ Gradle check result for 159a844: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

github-actions · 2025-08-05T17:19:18Z

❌ Gradle check result for 945bb64: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

github-actions · 2025-08-05T17:43:03Z

❌ Gradle check result for dd84c75: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

Signed-off-by: Karen Xu <karenxyr@gmail.com>

github-actions · 2025-08-05T19:25:49Z

✅ Gradle check result for 352aaa1: SUCCESS

codecov · 2025-08-05T19:26:15Z

Codecov Report

❌ Patch coverage is 88.50575% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.90%. Comparing base (696ed65) to head (5dcf5c7).
⚠️ Report is 8 commits behind head on main.

Files with missing lines	Patch %	Lines
...transport/grpc/util/RestToGrpcStatusConverter.java	82.60%	3 Missing and 1 partial ⚠️
...rt/grpc/listeners/SearchRequestActionListener.java	50.00%	3 Missing ⚠️
...ensearch/transport/grpc/util/GrpcErrorHandler.java	93.54%	1 Missing and 1 partial ⚠️
...src/main/java/org/opensearch/ExceptionsHelper.java	90.90%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main   #18925      +/-   ##
============================================
+ Coverage     72.88%   72.90%   +0.02%     
- Complexity    69300    69333      +33     
============================================
  Files          5642     5644       +2     
  Lines        318640   318707      +67     
  Branches      46108    46119      +11     
============================================
+ Hits         232237   232355     +118     
+ Misses        67566    67525      -41     
+ Partials      18837    18827      -10

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

libs/core/src/main/java/org/opensearch/ExceptionsHelper.java

...ansport-grpc/src/main/java/org/opensearch/transport/grpc/util/HttpToGrpcStatusConverter.java

...rt-grpc/src/main/java/org/opensearch/transport/grpc/listeners/BulkRequestActionListener.java

...transport-grpc/src/main/java/org/opensearch/transport/grpc/services/DocumentServiceImpl.java

Signed-off-by: Karen Xu <karenxyr@gmail.com>

Signed-off-by: Karen X <karenxyr@gmail.com>

github-actions · 2025-08-06T04:18:27Z

❌ Gradle check result for 6b93cb6: null

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

github-actions · 2025-08-06T05:28:38Z

❌ Gradle check result for 6b93cb6: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

Signed-off-by: Karen X <karenxyr@gmail.com>

github-actions · 2025-08-06T17:35:11Z

✅ Gradle check result for 859e0fa: SUCCESS

Signed-off-by: Karen X <karenxyr@gmail.com>

github-actions · 2025-08-06T19:33:11Z

❌ Gradle check result for 5ff1ad2: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

libs/core/src/main/java/org/opensearch/ExceptionsHelper.java

Signed-off-by: Karen X <karenxyr@gmail.com>

Signed-off-by: Karen Xu <karenxyr@gmail.com>

github-actions · 2025-08-07T20:17:30Z

❌ Gradle check result for 5dcf5c7: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

github-actions · 2025-08-07T21:56:30Z

✅ Gradle check result for 5dcf5c7: SUCCESS

… parity with HTTP (#18925) * [GRPC] Add proper GRPC status code and error handling Signed-off-by: Karen Xu <karenxyr@gmail.com> * rename Http to Rest, group together some convertRestToGrpcStatus codes Signed-off-by: Karen Xu <karenxyr@gmail.com> * make final Signed-off-by: Karen Xu <karenxyr@gmail.com> --------- Signed-off-by: Karen Xu <karenxyr@gmail.com> Signed-off-by: Karen X <karenxyr@gmail.com> (cherry picked from commit be8bbe1) Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

…eption handling parity with HTTP (#18990) * [GRPC] Map to proper GRPC status codes and achieve exception handling parity with HTTP (#18925) * [GRPC] Add proper GRPC status code and error handling Signed-off-by: Karen Xu <karenxyr@gmail.com> * rename Http to Rest, group together some convertRestToGrpcStatus codes Signed-off-by: Karen Xu <karenxyr@gmail.com> * make final Signed-off-by: Karen Xu <karenxyr@gmail.com> --------- Signed-off-by: Karen Xu <karenxyr@gmail.com> Signed-off-by: Karen X <karenxyr@gmail.com> (cherry picked from commit be8bbe1) Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> * Add entry to release notes Signed-off-by: Andrew Ross <andrross@amazon.com> --------- Signed-off-by: Karen Xu <karenxyr@gmail.com> Signed-off-by: Karen X <karenxyr@gmail.com> Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Signed-off-by: Andrew Ross <andrross@amazon.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Andrew Ross <andrross@amazon.com>

… parity with HTTP (opensearch-project#18925) * [GRPC] Add proper GRPC status code and error handling Signed-off-by: Karen Xu <karenxyr@gmail.com> * rename Http to Rest, group together some convertRestToGrpcStatus codes Signed-off-by: Karen Xu <karenxyr@gmail.com> * make final Signed-off-by: Karen Xu <karenxyr@gmail.com> --------- Signed-off-by: Karen Xu <karenxyr@gmail.com> Signed-off-by: Karen X <karenxyr@gmail.com>

karenyrx force-pushed the errorhandling branch from 52b1e23 to 2339cae Compare August 5, 2025 16:45

karenyrx marked this pull request as ready for review August 5, 2025 16:46

karenyrx requested a review from a team as a code owner August 5, 2025 16:46

github-actions bot added enhancement Enhancement or improvement to existing feature or request Libraries Lucene Upgrades and Libraries, Any 3rd party library that Core depends on, ex: nebula; team is respo labels Aug 5, 2025

karenyrx force-pushed the errorhandling branch from 2339cae to 159a844 Compare August 5, 2025 16:52

karenyrx moved this to In Progress in gRPC/Protobuf Aug 5, 2025

karenyrx added this to gRPC/Protobuf Aug 5, 2025

karenyrx force-pushed the errorhandling branch from 159a844 to 945bb64 Compare August 5, 2025 17:10

karenyrx force-pushed the errorhandling branch from 945bb64 to dd84c75 Compare August 5, 2025 17:21

karenyrx force-pushed the errorhandling branch from dd84c75 to 49a1a72 Compare August 5, 2025 17:55

[GRPC] Add proper GRPC status code and error handling

352aaa1

Signed-off-by: Karen Xu <karenxyr@gmail.com>

karenyrx force-pushed the errorhandling branch from 49a1a72 to 352aaa1 Compare August 5, 2025 18:01

finnegancarroll reviewed Aug 6, 2025

View reviewed changes

libs/core/src/main/java/org/opensearch/ExceptionsHelper.java Outdated Show resolved Hide resolved

finnegancarroll reviewed Aug 6, 2025

View reviewed changes

rename Http to Rest, group together some convertRestToGrpcStatus codes

e96fac9

Signed-off-by: Karen Xu <karenxyr@gmail.com>

karenyrx force-pushed the errorhandling branch from 98d5ca1 to e96fac9 Compare August 6, 2025 02:14

Merge branch 'main' into errorhandling

6b93cb6

Signed-off-by: Karen X <karenxyr@gmail.com>

prudhvigodithi mentioned this pull request Aug 6, 2025

[RELEASE] Release version 3.2.0 #18577

Closed

23 tasks

karenyrx closed this Aug 6, 2025

github-project-automation bot moved this from In Progress to Done/Won't Do in gRPC/Protobuf Aug 6, 2025

karenyrx reopened this Aug 6, 2025

opensearch-ci-bot mentioned this pull request Aug 6, 2025

[AUTOCUT] Gradle Check Flaky Test Report for FullClusterRestartIT #15813

Open

Merge branch 'main' into errorhandling

859e0fa

Signed-off-by: Karen X <karenxyr@gmail.com>

finnegancarroll approved these changes Aug 6, 2025

View reviewed changes

Merge branch 'main' into errorhandling

5ff1ad2

Signed-off-by: Karen X <karenxyr@gmail.com>

msfroh approved these changes Aug 7, 2025

View reviewed changes

libs/core/src/main/java/org/opensearch/ExceptionsHelper.java Outdated Show resolved Hide resolved

karenyrx added 2 commits August 7, 2025 14:58

Merge branch 'main' into errorhandling

a0430d6

Signed-off-by: Karen X <karenxyr@gmail.com>

make final

5dcf5c7

Signed-off-by: Karen Xu <karenxyr@gmail.com>

karenyrx closed this Aug 7, 2025

karenyrx reopened this Aug 7, 2025

opensearch-ci-bot mentioned this pull request Aug 7, 2025

[AUTOCUT] Gradle Check Flaky Test Report for RestoreShallowSnapshotV2IT #16658

Open

andrross approved these changes Aug 7, 2025

View reviewed changes

andrross merged commit be8bbe1 into opensearch-project:main Aug 7, 2025
58 of 60 checks passed

opensearch-ci-bot mentioned this pull request Aug 5, 2025

[AUTOCUT] Gradle Check Flaky Test Report for ClusterDisruptionIT #14308

Open

andrross added the backport 3.2 Backport to 3.2 branch label Aug 8, 2025

opensearch-trigger-bot bot mentioned this pull request Aug 8, 2025

[Backport 3.2] [GRPC] Map to proper GRPC status codes and achieve exception handling parity with HTTP #18990

Merged

karenyrx mentioned this pull request Aug 15, 2025

Add GRPC PR 18925 to 3.2 release notes #19087

Merged

3 tasks

BrewTestBot mentioned this pull request Aug 20, 2025

opensearch 3.2.0 Homebrew/homebrew-core#234146

Merged

tkykenmt mentioned this pull request Jan 10, 2026

[feature] GRPC Transport tkykenmt/opensearch-feature-explorer#1117

Closed

3 tasks

Conversation

karenyrx commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Detailed Examples

1. Remove HTTP status codes from protobuf messages

2. Return proper GRPC status codes instead of all showing as GRPC.INTERNAL

3. Use constants for error messages so both HTTP and gRPC now use identical error messages from ExceptionsHelper.ErrorMessages

4. Wrap error messages in the same way as HTTP

Related Issues

Check List

Uh oh!

github-actions bot commented Aug 5, 2025

Uh oh!

github-actions bot commented Aug 5, 2025

Uh oh!

github-actions bot commented Aug 5, 2025

Uh oh!

github-actions bot commented Aug 5, 2025

Uh oh!

codecov bot commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Aug 6, 2025

Uh oh!

github-actions bot commented Aug 6, 2025

Uh oh!

github-actions bot commented Aug 6, 2025

Uh oh!

github-actions bot commented Aug 6, 2025

Uh oh!

Uh oh!

github-actions bot commented Aug 7, 2025

Uh oh!

github-actions bot commented Aug 7, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

karenyrx commented Aug 5, 2025 •

edited

Loading

3. Use constants for error messages so both HTTP and gRPC now use identical error messages from `ExceptionsHelper.ErrorMessages`

codecov bot commented Aug 5, 2025 •

edited

Loading