GreptimeTeam / GreptimeTeam/greptimedb-ingester-java

Expose GreptimeDB status codes for bulk stream write failures

Open
#108 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.