refactor: Use TypeMapper for health serialisation and boolean outcome

Author: thced

src/main/java/com/retailsvc/http/Dependency.java

@@ -5,13 +5,14 @@
 /**
  * A single dependency entry within a {@link HealthOutcome}.
  *
+ * <p>The library translates {@code up} into the wire value {@code "Up"} or {@code "Down"} for the
+ * {@code status} field.
+ *
  * @param id stable identifier of the dependency (e.g. {@code "jdbc"})
- * @param status free-form status; {@code "Up"} (case-insensitive) is treated as healthy by {@link
- *     HealthOutcome#isUp()}; any other value is treated as unhealthy
+ * @param up whether the dependency is healthy
  */
-public record Dependency(String id, String status) {
+public record Dependency(String id, boolean up) {
   public Dependency {
     Objects.requireNonNull(id, "id");
-    Objects.requireNonNull(status, "status");
   }
 }

src/main/java/com/retailsvc/http/Handlers.java

@@ -10,12 +10,12 @@
 import static java.nio.charset.StandardCharsets.UTF_8;
 
 import com.retailsvc.http.internal.ClasspathResourceHandler;
-import com.retailsvc.http.internal.HealthRenderer;
 import com.retailsvc.http.internal.MethodLimitedHandler;
 import com.retailsvc.http.internal.ProblemDetailRenderer;
 import com.sun.net.httpserver.HttpHandler;
 import java.io.IOException;
 import java.util.List;
+import java.util.Map;
 import java.util.Objects;
 import java.util.function.Supplier;
 import java.util.stream.Collectors;
@@ -75,14 +75,27 @@ public static HttpHandler aliveHandler() {
 
   /**
    * Health endpoint handler. Accepts GET and HEAD; returns 200 with {@code application/json} body
-   * when the supplied probe reports {@code "Up"} (case-insensitive), and 503 with the same body
-   * shape otherwise. A probe that throws a {@link RuntimeException} or returns {@code null} is
-   * mapped to a {@code "Down"} outcome with an empty dependency list (and 503); the failure is
-   * never propagated to the default exception handler.
+   * when the supplied probe reports {@code up == true}, and 503 with the same body shape otherwise.
+   * A probe that throws a {@link RuntimeException} or returns {@code null} is mapped to a {@code
+   * Down} outcome with an empty dependency list (and 503); the failure is never propagated to the
+   * default exception handler.
    *
+   * <p>The wire shape is
+   *
+   * <pre>{@code
+   * {"outcome":"Up","dependencies":[{"id":"jdbc","status":"Up"}]}
+   * }</pre>
+   *
+   * <p>Serialisation is delegated to the supplied {@code jsonMapper} — typically the same {@link
+   * TypeMapper} the caller registered for {@code application/json} on the server. The handler hands
+   * the mapper a {@code Map<String,Object>} matching the shape above; any standard JSON library
+   * (Gson, Jackson, …) serialises it identically.
+   *
+   * @param jsonMapper used to encode the wire-shape {@code Map} to bytes
    * @param probe supplier of the current {@link HealthOutcome}
    */
-  public static HttpHandler healthHandler(Supplier<HealthOutcome> probe) {
+  public static HttpHandler healthHandler(TypeMapper jsonMapper, Supplier<HealthOutcome> probe) {
+    Objects.requireNonNull(jsonMapper, "jsonMapper");
     Objects.requireNonNull(probe, "probe");
     return new MethodLimitedHandler(
         exchange -> {
@@ -92,17 +105,30 @@ public static HttpHandler healthHandler(Supplier<HealthOutcome> probe) {
               outcome = Objects.requireNonNull(probe.get(), "Health probe returned null");
             } catch (RuntimeException e) {
               LOG.warn("Health probe failed", e);
-              outcome = new HealthOutcome("Down", List.of());
+              outcome = new HealthOutcome(false, List.of());
             }
-            byte[] body = HealthRenderer.toJson(outcome).getBytes(UTF_8);
-            int status = outcome.isUp() ? HTTP_OK : HTTP_UNAVAILABLE;
+            byte[] body = jsonMapper.writeTo(toWireShape(outcome));
+            int status = outcome.up() ? HTTP_OK : HTTP_UNAVAILABLE;
             exchange.getResponseHeaders().add("Content-Type", "application/json");
             exchange.sendResponseHeaders(status, body.length);
             exchange.getResponseBody().write(body);
           }
         });
   }
 
+  private static Map<String, Object> toWireShape(HealthOutcome outcome) {
+    return Map.of(
+        "outcome", label(outcome.up()),
+        "dependencies",
+            outcome.dependencies().stream()
+                .map(d -> Map.<String, Object>of("id", d.id(), "status", label(d.up())))
+                .toList());
+  }
+
+  private static String label(boolean up) {
+    return up ? "Up" : "Down";
+  }
+
   /**
    * Serves a classpath resource. Content-Type is inferred from the file extension. The resource is
    * loaded eagerly; a missing resource fails immediately with {@link IllegalArgumentException}.

src/main/java/com/retailsvc/http/HealthOutcome.java

@@ -4,24 +4,19 @@
 import java.util.Objects;
 
 /**
- * Wire-shape carrier for the {@link Handlers#healthHandler health handler} response.
+ * Carrier for the {@link Handlers#healthHandler health handler} response.
  *
- * <p>The record owns the JSON shape on the wire — {@code {"outcome": "...", "dependencies": [
- * {"id": "...", "status": "..."} ]}}. Construct it from whatever check-running mechanism the caller
- * prefers; this library has no opinion.
+ * <p>The library translates {@code up} into the wire value {@code "Up"} or {@code "Down"} on the
+ * way out; callers work in booleans. Construct the outcome from whatever check-running mechanism
+ * the caller prefers — this library has no opinion.
  *
- * @param outcome overall outcome; {@code "Up"} (case-insensitive) means healthy
+ * @param up overall health — {@code true} renders as {@code "Up"} with HTTP 200; {@code false}
+ *     renders as {@code "Down"} with HTTP 503
  * @param dependencies per-dependency statuses; {@code null} is normalised to an empty list
  */
-public record HealthOutcome(String outcome, List<Dependency> dependencies) {
+public record HealthOutcome(boolean up, List<Dependency> dependencies) {
 
   public HealthOutcome {
-    Objects.requireNonNull(outcome, "outcome");
     dependencies = List.copyOf(Objects.requireNonNullElse(dependencies, List.of()));
   }
-
-  /** Returns {@code true} when {@link #outcome()} equals {@code "Up"} ignoring case. */
-  public boolean isUp() {
-    return "Up".equalsIgnoreCase(outcome);
-  }
 }

src/main/java/com/retailsvc/http/internal/HealthRenderer.java

@@ -17,41 +17,77 @@ public final class ProblemDetailRenderer {
   /** Initial capacity of the JSON buffer; sized for a typical problem-detail document. */
   private static final int INITIAL_BUFFER_CAPACITY = 128;
 
+  /** Codepoints below this value are control characters and must be unicode-escaped in JSON. */
+  private static final int FIRST_PRINTABLE_ASCII = 0x20;
+
   private ProblemDetailRenderer() {}
 
   public static String render(int status, String title, String detail) {
     StringBuilder out = new StringBuilder(INITIAL_BUFFER_CAPACITY);
     out.append('{');
-    JsonStrings.appendStringField(out, "type", PROBLEM_TYPE);
+    appendStringField(out, "type", PROBLEM_TYPE);
     out.append(',');
-    JsonStrings.appendStringField(out, "title", title);
+    appendStringField(out, "title", title);
     out.append(',');
     appendIntField(out, "status", status);
     out.append(',');
-    JsonStrings.appendStringField(out, "detail", detail);
+    appendStringField(out, "detail", detail);
     out.append('}');
     return out.toString();
   }
 
   public static String render(ValidationError error) {
     StringBuilder out = new StringBuilder(INITIAL_BUFFER_CAPACITY);
     out.append('{');
-    JsonStrings.appendStringField(out, "type", PROBLEM_TYPE);
+    appendStringField(out, "type", PROBLEM_TYPE);
     out.append(',');
-    JsonStrings.appendStringField(out, "title", PROBLEM_TITLE);
+    appendStringField(out, "title", PROBLEM_TITLE);
     out.append(',');
     appendIntField(out, "status", PROBLEM_STATUS);
     out.append(',');
-    JsonStrings.appendStringField(out, "detail", error.message());
+    appendStringField(out, "detail", error.message());
     out.append(',');
-    JsonStrings.appendStringField(out, "pointer", error.pointer());
+    appendStringField(out, "pointer", error.pointer());
     out.append(',');
-    JsonStrings.appendStringField(out, "keyword", error.keyword());
+    appendStringField(out, "keyword", error.keyword());
     out.append('}');
     return out.toString();
   }
 
+  private static void appendStringField(StringBuilder out, String name, String value) {
+    out.append('"').append(name).append("\":\"");
+    appendEscaped(out, value);
+    out.append('"');
+  }
+
   private static void appendIntField(StringBuilder out, String name, int value) {
     out.append('"').append(name).append("\":").append(value);
   }
+
+  /**
+   * Appends {@code value} to {@code out} with JSON-string escaping applied. Handles the six
+   * mandatory escape sequences and emits {@code \uXXXX} for control characters below {@link
+   * #FIRST_PRINTABLE_ASCII}.
+   */
+  private static void appendEscaped(StringBuilder out, String value) {
+    for (int i = 0; i < value.length(); i++) {
+      char c = value.charAt(i);
+      switch (c) {
+        case '\\' -> out.append("\\\\");
+        case '"' -> out.append("\\\"");
+        case '\n' -> out.append("\\n");
+        case '\r' -> out.append("\\r");
+        case '\t' -> out.append("\\t");
+        default -> appendUnicodeOrLiteral(out, c);
+      }
+    }
+  }
+
+  private static void appendUnicodeOrLiteral(StringBuilder out, char c) {
+    if (c < FIRST_PRINTABLE_ASCII) {
+      out.append(String.format("\\u%04x", (int) c));
+    } else {
+      out.append(c);
+    }
+  }
 }

src/main/java/com/retailsvc/http/internal/JsonStrings.java

@@ -8,23 +8,16 @@
 class DependencyTest {
 
   @Test
-  void holdsIdAndStatus() {
-    Dependency d = new Dependency("jdbc", "Up");
+  void holdsIdAndUp() {
+    Dependency d = new Dependency("jdbc", true);
     assertThat(d.id()).isEqualTo("jdbc");
-    assertThat(d.status()).isEqualTo("Up");
+    assertThat(d.up()).isTrue();
   }
 
   @Test
   void rejectsNullId() {
     assertThatNullPointerException()
-        .isThrownBy(() -> new Dependency(null, "Up"))
+        .isThrownBy(() -> new Dependency(null, true))
         .withMessageContaining("id");
   }
-
-  @Test
-  void rejectsNullStatus() {
-    assertThatNullPointerException()
-        .isThrownBy(() -> new Dependency("jdbc", null))
-        .withMessageContaining("status");
-  }
 }