GreptimeTeam / GreptimeTeam/greptimedb-ingester-java
Expose GreptimeDB status codes for bulk stream write failures
- Dominant language
- Java
- Stars
- 4
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
## Background
`BulkStreamWriter.writeNext()` completes exceptionally with an Arrow `FlightRuntimeException`. After GreptimeTeam/greptimedb#8349 (tracked in #102), server error details and GreptimeDB error metadata are propagated through Arrow Flight, but callers still have no Greptime Java API for obtaining the corresponding `io.greptime.Status`.
This makes it difficult to implement correct retry logic. In particular, callers should be able to use the retry policy already defined by `Status.isShouldRetry()` for server application errors, while separately handling transport failures such as Arrow Flight `UNAVAILABLE` and `TIMED_OUT`.
The retry example in #107 currently has to inspect Arrow Flight status codes directly and cannot reuse `Status` for server errors.
## Proposed API
Provide a public, stable way to retrieve the GreptimeDB status from a bulk-stream failure. For example, either:
- wrap server failures in a GreptimeDB-specific exception that exposes an optional `Status` (and possibly the raw integer status code), or
- provide a helper that extracts an optional `Status` from the exception returned by `BulkStreamWriter`.
The exact API shape is open for discussion. A possible usage could look like:
```java
Status status = BulkWriteErrors.statusOf(cause);
if (status != null && status.isShouldRetry()) {
// Close the failed writer, rebuild it, and replay the retained batch.
}
```
Transport-only failures, where no GreptimeDB status exists, should remain distinguishable so callers can apply a transport retry policy.
## Requirements
- Expose the public GreptimeDB status code carried by bulk-write error metadata.
- Reuse `io.greptime.Status` and its `isShouldRetry()` policy rather than duplicating the server-status retry list.
- Preserve the original exception/cause and server error message.
- Define behavior when the status metadata is absent, unknown, or malformed.
- Do not expose or make the public API depend on the internal `x-greptime-err-retry-hint` header.
- Add tests for retryable and non-retryable server status codes, plus failures without a GreptimeDB status.
- Update the bulk-writer retry example from #107 to use the API once available.
## Related
- #102
- #107
Contributor guide
No contributing guide indexed for this repository
Research direction
Start at BulkStreamWriter.writeNext() and trace how Arrow Flight failures carry server metadata and the GreptimeDB Status type. Review the retry example in #107 and related context in #102, then define and test behavior for retryable, non-retryable, absent, unknown, and malformed statuses while preserving causes and messages. Done means the example uses the public API and transport-only failures remain distinguishable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100