guardrail-dev / guardrail-dev/guardrail

Add intermediate status class interfaces to Java client response classes

Open
#1,113 0 comments 0 reactions 0 assignees View on GitHub
good first issue java
Dominant language
Scala
Stars
541
Forks
138
PR merge metrics
No merged PRs in 30d

Description

From some real-world usage, the `fold` method on Java client response classes isn't quite as useful as it is with Scala. Lack of named arguments makes it more error-prone, and it's just not very idiomatic. The most common use case seems to be doing one thing on success status codes, and another (single) thing on error status codes, so duplicating the error logic -- even if it's just a function call -- is tedious.

Most users would prefer to do an `instanceof` check for the success case (or `.getStatusCode() / 100 == 2`), and just have a catch-all `else` branch for the failure cases. Sometimes users would like to handle a single specific error case (say, 404), and catch-all the rest of them, or perhaps have three branches, one for success, one for client errors, and one for server errors.

This is all possible today, but it's a little awkward at times depending on use case. We already have a base `ClientResponse` interface (which has `.getStatusCode()` on it), and it would be helpful to also introduce status-class sub-interfaces. For example:

```java
interface ClientResponse {
int getStatusCode()
}

interface InformationalResponse extends ClientResponse {}
interface SuccessResponse extends ClientResponse {}
interface RedirectResponse extends ClientResponse {}
interface ClientErrorResponse extends ClientResponse {}
interface ServerErrorResponse extends ClientResponse {}

abstract class GetFooResponse implements ClientResponse {
static class Ok extends GetFooResponse implements SuccessResponse {}
static class NotFound extends GetFooResponse implements ClientErrorResponse {}
static class Conflict extends GetFooResponse implements ClientErrorResponse {}
static class InternalServerError extends GetFooResponse implements ServerErrorResponse {}
}
```
Then users can do things like:
```java
final GetFooResponse response = doStuff();
if (response instanceof SuccessResponse) {
// happy path
} else if (response instanceof GetFooResponse.NotFound) {
// specific handling for 404
} else if (response instanceof ServerErrorResponse) {
// handling for any server error
} else {
// handling for any other error
}
```

Contributor guide

Open the contributing guide

Research direction

Start by locating the Java client response classes and the existing ClientResponse interface described in the issue. Trace how response variants are generated, then add the status-class interfaces so success, client-error, and server-error responses can be distinguished; done means generated responses expose the expected interfaces and existing behavior remains intact.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.