feat!: Request.queryParam/header return Optional<String>, treat blank as absent

Every list handler was writing:

    int limit = Optional.ofNullable(req.queryParam("limit"))
        .filter(v -> !v.isBlank())
        .map(Integer::parseInt)
        .orElse(DEFAULT_LIMIT);

The blank-vs-absent question is the kind of HTTP-API trap that's better
solved once in the library than copied across every consumer. Returning
Optional<String> with blank already filtered shrinks the call site to:

    int limit = req.queryParam("limit").map(Integer::parseInt).orElse(DEFAULT_LIMIT);

Same treatment for header(name). pathParam(name) is unchanged (still
nullable) — path parameters come from the route template, not from the
client, so blank is genuinely a different case.

Author: thced

README.md

@@ -48,9 +48,9 @@ public class PostDataHandler implements RequestHandler {
     // TypedTypeMapper).
     MyDto dto = request.asPojo(MyDto.class);
     // Path parameters, query parameters, and headers are also available.
-    String id = request.pathParam("id");
-    String filter = request.queryParam("filter");
-    String corr = request.header("correlation-id");
+    String id = request.pathParam("id");                     // null if absent
+    Optional<String> filter = request.queryParam("filter");  // empty if absent or blank
+    Optional<String> corr = request.header("correlation-id");
 
     return Response.ok(dto);
   }
@@ -182,7 +182,7 @@ OpenApiServer.builder()
     .handlers(handlers)
     .interceptor((request, next) -> {
       // Resolve once per request; bind to a ScopedValue for the rest of the chain.
-      String tenant = request.header("X-Tenant-Id");
+      String tenant = request.header("X-Tenant-Id").orElse("public");
       return ScopedValue.where(TENANT, tenant).call(next::proceed);
     })
     .interceptor((request, next) -> {
@@ -213,8 +213,7 @@ OpenApiServer.builder()
     // 1. Resolve once per request and bind to ScopedValues.
     .interceptor((request, next) -> {
       String correlationId =
-          Optional.ofNullable(request.header("X-Correlation-Id"))
-              .orElseGet(() -> UUID.randomUUID().toString());
+          request.header("X-Correlation-Id").orElseGet(() -> UUID.randomUUID().toString());
       String tenantId = resolveTenant(request);
       return ScopedValue.where(CORRELATION_ID, correlationId)
           .where(TENANT_ID, tenantId)
@@ -282,10 +281,9 @@ public final class App {
         .handlers(Map.of("get-promotion", getPromotion))
         // Bind tenant + correlation id once per request.
         .interceptor((req, next) -> {
-          String tenant = req.header("X-Tenant-Id");
+          String tenant = req.header("X-Tenant-Id").orElse("public");
           String correlationId =
-              Optional.ofNullable(req.header("X-Correlation-Id"))
-                  .orElseGet(() -> UUID.randomUUID().toString());
+              req.header("X-Correlation-Id").orElseGet(() -> UUID.randomUUID().toString());
           return ScopedValue.where(TENANT, tenant)
               .where(CORRELATION_ID, correlationId)
               .call(next::proceed);

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

@@ -6,6 +6,7 @@
 import java.util.LinkedHashMap;
 import java.util.Map;
 import java.util.Objects;
+import java.util.Optional;
 
 /**
  * Read-only per-request handle passed to {@link RequestHandler}. Carries the parsed body, path
@@ -70,12 +71,13 @@ public <T> T asPojo(Class<T> type) {
     if (parsed != null && type.isInstance(parsed)) {
       return type.cast(parsed);
     }
+    String contentType = exchange.getRequestHeaders().getFirst(CONTENT_TYPE);
     if (bodyMapper instanceof TypedTypeMapper typed) {
-      return typed.readAs(body, header(CONTENT_TYPE), type);
+      return typed.readAs(body, contentType, type);
     }
     throw new IllegalStateException(
         "body mapper for "
-            + header(CONTENT_TYPE)
+            + contentType
             + " does not support typed conversion; the mapper must implement TypedTypeMapper");
   }
 
@@ -92,8 +94,14 @@ public String pathParam(String name) {
     return pathParameters.get(name);
   }
 
-  public String header(String name) {
-    return exchange.getRequestHeaders().getFirst(name);
+  /**
+   * First value of the request header {@code name}, or {@link Optional#empty()} if absent or blank.
+   * Blank values are treated as missing so callers can write {@code req.header("X").map(...)}
+   * without the extra {@code filter(v -> !v.isBlank())} step.
+   */
+  public Optional<String> header(String name) {
+    String raw = exchange.getRequestHeaders().getFirst(name);
+    return raw == null || raw.isBlank() ? Optional.empty() : Optional.of(raw);
   }
 
   /**
@@ -115,9 +123,15 @@ public Map<String, String> queryParams() {
     return queryParamCache;
   }
 
-  /** First decoded value for {@code name}, or {@code null} if absent. */
-  public String queryParam(String name) {
-    return queryParams().get(name);
+  /**
+   * First decoded value for query parameter {@code name}, or {@link Optional#empty()} if absent or
+   * blank. Blank values are treated as missing so callers can write {@code
+   * req.queryParam("limit").map(Integer::parseInt).orElse(DEFAULT)} without the extra {@code
+   * filter(v -> !v.isBlank())} step.
+   */
+  public Optional<String> queryParam(String name) {
+    String raw = queryParams().get(name);
+    return raw == null || raw.isBlank() ? Optional.empty() : Optional.of(raw);
   }
 
   private static Map<String, String> parseQuery(String query) {

src/test/java/com/retailsvc/http/RequestTest.java

@@ -130,9 +130,9 @@ void exposesQueryParams() {
     Request req = new Request(exchange, new byte[0], null, null, "op", Map.of());
 
     assertThat(req.rawQuery()).isEqualTo("name=Alice%20Smith&active=true&active=false");
-    assertThat(req.queryParam("name")).isEqualTo("Alice Smith");
-    assertThat(req.queryParam("active")).isEqualTo("true");
-    assertThat(req.queryParam("missing")).isNull();
+    assertThat(req.queryParam("name")).contains("Alice Smith");
+    assertThat(req.queryParam("active")).contains("true");
+    assertThat(req.queryParam("missing")).isEmpty();
     assertThat(req.queryParams())
         .containsEntry("name", "Alice Smith")
         .containsEntry("active", "true");
@@ -146,6 +146,30 @@ void queryParamsEmptyWhenNoQuery() {
 
     assertThat(req.rawQuery()).isNull();
     assertThat(req.queryParams()).isEmpty();
-    assertThat(req.queryParam("anything")).isNull();
+    assertThat(req.queryParam("anything")).isEmpty();
+  }
+
+  @Test
+  void queryParamBlankIsTreatedAsAbsent() {
+    HttpExchange exchange = mock(HttpExchange.class);
+    when(exchange.getRequestURI()).thenReturn(URI.create("http://h/x?limit=&offset=%20"));
+    Request req = new Request(exchange, new byte[0], null, null, "op", Map.of());
+
+    assertThat(req.queryParam("limit")).isEmpty();
+    assertThat(req.queryParam("offset")).isEmpty();
+  }
+
+  @Test
+  void headerReturnsOptionalAndBlankIsAbsent() {
+    HttpExchange exchange = mock(HttpExchange.class);
+    com.sun.net.httpserver.Headers h = new com.sun.net.httpserver.Headers();
+    h.add("X-Trace", "abc");
+    h.add("X-Empty", "   ");
+    when(exchange.getRequestHeaders()).thenReturn(h);
+    Request req = new Request(exchange, new byte[0], null, null, "op", Map.of());
+
+    assertThat(req.header("X-Trace")).contains("abc");
+    assertThat(req.header("X-Empty")).isEmpty();
+    assertThat(req.header("Missing")).isEmpty();
   }
 }