Mark client-generated results as synthetic (#211)

Step 3 of #6. The client returns a failed Result in three cases where no
HTTP error occurred:

  processResponseGetOne  200 with an empty body   -> code 404
  processResponseGetOne  200 with a null body     -> code 500
  badRequestResult       rejected before sending  -> code 400

Those codes were indistinguishable from the same codes reported by Koios,
so a caller branching on getCode() could not tell a real 404 from "the
list came back empty", nor a real 400 from a request that never left the
client.

Adds Result.synthetic, true for exactly those three cases and false for
every result reflecting an actual HTTP response. The codes themselves are
unchanged, so existing callers keep working; the flag is there for callers
that need the distinction.

Co-authored-by: dudiedri <dudi.edri@ox.security>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: 3 people

src/main/java/rest/koios/client/backend/api/base/BaseService.java

@@ -139,9 +139,9 @@ protected <T> Result<T> processResponseGetOne(Call<List<T>> call) throws ApiExce
                 if (response.body() != null && !response.body().isEmpty()) {
                     return (Result<T>) Result.builder().successful(true).response(response.toString()).value(response.body().get(0)).code(response.code()).build();
                 } else if (response.body() != null) {
-                    return (Result<T>) Result.builder().successful(false).response("Response Body is Empty").code(404).build();
+                    return (Result<T>) Result.builder().successful(false).response("Response Body is Empty").code(404).synthetic(true).build();
                 } else {
-                    return (Result<T>) Result.builder().successful(false).response("Response Body is Invalid").code(500).build();
+                    return (Result<T>) Result.builder().successful(false).response("Response Body is Invalid").code(500).synthetic(true).build();
                 }
             } else {
                 String errorBody = Objects.requireNonNull(response.errorBody()).string();
@@ -174,7 +174,7 @@ private static KoiosError parseError(String body) {
     }
 
     protected <T> Result<T> badRequestResult(String responseText) {
-        return (Result<T>) Result.builder().successful(false).response(responseText).code(400).build();
+        return (Result<T>) Result.builder().successful(false).response(responseText).code(400).synthetic(true).build();
     }
 
     /**

src/main/java/rest/koios/client/backend/api/base/Result.java

@@ -23,5 +23,19 @@ public class Result<T> {
      * Null on success, and null when the body was not JSON of that shape.
      */
     KoiosError error;
+
+    /**
+     * Whether this result was constructed by the client rather than reported by the server.
+     * <p>
+     * The client returns a failed result in a few cases where no HTTP error occurred at all - a
+     * request rejected by local validation before it was sent, or a 200 response whose body was
+     * empty or missing where a single object was expected. Those results still carry a
+     * {@code code} so that callers branching on it keep working, but the code was chosen by the
+     * client and never came from Koios.
+     * <p>
+     * False for every result that reflects an actual HTTP response, successful or not. Check this
+     * before treating {@code code} as a server status.
+     */
+    boolean synthetic;
 }
 

src/test/java/rest/koios/client/backend/api/base/BaseServiceErrorHandlingTest.java

@@ -7,11 +7,14 @@
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import rest.koios.client.backend.api.base.exception.ApiException;
+import rest.koios.client.backend.api.asset.model.AssetInformation;
 import rest.koios.client.backend.api.network.model.Tip;
+import rest.koios.client.backend.factory.options.Options;
 import rest.koios.client.backend.factory.BackendFactory;
 import rest.koios.client.backend.factory.BackendService;
 
 import java.io.IOException;
+import java.util.List;
 
 /**
  * Error handling tests that run against a local {@link MockWebServer} instead of a live Koios
@@ -49,6 +52,19 @@ void successfulResponseIsReturnedTest() throws ApiException {
         Assertions.assertEquals("Conway", result.getValue().getEra());
     }
 
+    @Test
+    void locallyRejectedRequestIsSyntheticTest() throws ApiException {
+        // rejected by client-side validation, so no request is ever sent
+        Result<List<AssetInformation>> result =
+                backendService.getAssetService().getAssetInformationBulk(null, Options.EMPTY);
+
+        Assertions.assertFalse(result.isSuccessful());
+        Assertions.assertEquals(400, result.getCode());
+        Assertions.assertTrue(result.isSynthetic(), "no request was sent, so the 400 is the client's");
+        Assertions.assertNull(result.getError());
+        Assertions.assertEquals(0, server.getRequestCount(), "nothing should have been sent");
+    }
+
     @Test
     void successCarriesNoErrorTest() throws ApiException {
         server.enqueue(new MockResponse()
@@ -60,6 +76,7 @@ void successCarriesNoErrorTest() throws ApiException {
 
         Assertions.assertTrue(result.isSuccessful());
         Assertions.assertNull(result.getError());
+        Assertions.assertFalse(result.isSynthetic());
     }
 
     @Test
@@ -91,6 +108,7 @@ void serverErrorBodyIsSurfacedTest() throws ApiException {
 
         Assertions.assertFalse(result.isSuccessful());
         Assertions.assertEquals(400, result.getCode());
+        Assertions.assertFalse(result.isSynthetic(), "a real server 400 is not synthetic");
         Assertions.assertEquals(postgrestError, result.getResponse());
         Assertions.assertNull(result.getValue());
         // the same body, parsed
@@ -110,6 +128,7 @@ void internalServerErrorIsSurfacedTest() throws ApiException {
 
         Assertions.assertFalse(result.isSuccessful());
         Assertions.assertEquals(500, result.getCode());
+        Assertions.assertFalse(result.isSynthetic(), "a real server 500 is not synthetic");
         Assertions.assertEquals("upstream failure", result.getResponse());
         // a plain-text body is not a structured error; the raw text is still available
         Assertions.assertNull(result.getError());
@@ -135,7 +154,10 @@ void emptyResponseBodyReportsNotFoundTest() throws ApiException {
         Result<Tip> result = backendService.getNetworkService().getChainTip();
 
         Assertions.assertFalse(result.isSuccessful());
+        // the server returned 200; this 404 is the client's, not Koios's
         Assertions.assertEquals(404, result.getCode());
+        Assertions.assertTrue(result.isSynthetic(), "an empty body yields a client-generated code");
+        Assertions.assertNull(result.getError());
         Assertions.assertEquals("Response Body is Empty", result.getResponse());
     }