feat: Add TypedTypeMapper + Request.asPojo(Class) for direct POJO deserialisation

Author: thced

README.md

@@ -36,20 +36,22 @@ It is designed to be simple to use while providing the essential features needed
 // Inline lambda — returns JSON using the built-in Gson mapper.
 RequestHandler getDataHandler = req -> Response.ok(Map.of("id", "some-id"));
 
-// Class form — reads raw bytes or the pre-parsed body object.
+// Class form — reads raw bytes, the loose Map view, or a typed POJO.
 public class PostDataHandler implements RequestHandler {
   @Override
   public Response handle(Request request) {
     // Access the raw request body bytes.
     byte[] body = request.bytes();
-    // Or get the already-parsed object (Map / List) produced by the registered TypeMapper.
+    // Loose structural view (Map / List / boxed primitives), produced by the registered TypeMapper.
     Object parsed = request.parsed();
+    // Or, when the JSON mapper is Jackson (a TypedTypeMapper), get a typed POJO directly.
+    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");
 
-    return Response.ok(parsed);
+    return Response.ok(dto);
   }
 }
 ```
@@ -132,7 +134,7 @@ var server = OpenApiServer.builder()
     .build();
 ```
 
-The same shape applies to any custom mapper — implement `TypeMapper` and register it.
+The same shape applies to any custom mapper — implement `TypeMapper` (and optionally `TypedTypeMapper` if you can deserialise directly into a target type, so handlers can call `request.asPojo(MyDto.class)`).
 
 If neither Gson is on the classpath nor any `application/json` mapper is registered, `build()` throws `IllegalStateException`.
 

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

@@ -10,6 +10,9 @@
  * fully-configured {@link ObjectMapper}; this class never adds modules or changes settings — the
  * mapper you pass is the mapper you get.
  *
+ * <p>Implements {@link TypedTypeMapper}, so handlers can ask for a typed view of the body via
+ * {@link Request#parsed(Class)}.
+ *
  * <p>Typical wiring:
  *
  * <pre>{@code
@@ -24,7 +27,7 @@
  * must declare {@code jackson-databind} themselves. Consumers that use Gson can rely on the
  * built-in {@code GsonJsonMapper} auto-fallback instead.
  */
-public final class JacksonJsonTypeMapper implements TypeMapper {
+public final class JacksonJsonTypeMapper implements TypedTypeMapper {
 
   private final ObjectMapper mapper;
 
@@ -34,8 +37,13 @@ public JacksonJsonTypeMapper(ObjectMapper mapper) {
 
   @Override
   public Object readFrom(byte[] body, String contentTypeHeader) {
+    return readAs(body, contentTypeHeader, Object.class);
+  }
+
+  @Override
+  public <T> T readAs(byte[] body, String contentTypeHeader, Class<T> type) {
     try {
-      return mapper.readValue(body, Object.class);
+      return mapper.readValue(body, type);
     } catch (IOException e) {
       throw new UncheckedIOException(e);
     }

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

@@ -5,6 +5,7 @@
 import java.nio.charset.StandardCharsets;
 import java.util.LinkedHashMap;
 import java.util.Map;
+import java.util.Objects;
 
 /**
  * Read-only per-request handle passed to {@link RequestHandler}. Carries the parsed body, path
@@ -13,9 +14,12 @@
  */
 public final class Request {
 
+  private static final String CONTENT_TYPE = "Content-Type";
+
   private final HttpExchange exchange;
   private final byte[] body;
   private final Object parsed;
+  private final TypeMapper bodyMapper;
   private final String operationId;
   private final Map<String, String> pathParameters;
   private Map<String, String> queryParamCache;
@@ -24,11 +28,13 @@ public Request(
       HttpExchange exchange,
       byte[] body,
       Object parsed,
+      TypeMapper bodyMapper,
       String operationId,
       Map<String, String> pathParameters) {
     this.exchange = exchange;
     this.body = body;
     this.parsed = parsed;
+    this.bodyMapper = bodyMapper;
     this.operationId = operationId;
     this.pathParameters = pathParameters;
   }
@@ -37,10 +43,42 @@ public byte[] bytes() {
     return body;
   }
 
+  /**
+   * Loose structural view of the body (typically a {@code Map} / {@code List} / boxed primitive).
+   */
   public Object parsed() {
     return parsed;
   }
 
+  /**
+   * Typed view of the body, deserialised into {@code type} by the request's body mapper.
+   *
+   * <p>Requires the registered {@link TypeMapper} for the request's {@code Content-Type} to
+   * implement {@link TypedTypeMapper} — Jackson does, the built-in form and text mappers do not. If
+   * the loose {@link #parsed()} value already is an instance of {@code type}, it is returned
+   * directly without re-deserialising.
+   *
+   * @throws NullPointerException if {@code type} is null
+   * @throws IllegalStateException if there is no body, or if the body mapper does not implement
+   *     {@link TypedTypeMapper}
+   */
+  public <T> T asPojo(Class<T> type) {
+    Objects.requireNonNull(type, "type must not be null");
+    if (body == null || body.length == 0) {
+      throw new IllegalStateException("request has no body");
+    }
+    if (parsed != null && type.isInstance(parsed)) {
+      return type.cast(parsed);
+    }
+    if (bodyMapper instanceof TypedTypeMapper typed) {
+      return typed.readAs(body, header(CONTENT_TYPE), type);
+    }
+    throw new IllegalStateException(
+        "body mapper for "
+            + header(CONTENT_TYPE)
+            + " does not support typed conversion; the mapper must implement TypedTypeMapper");
+  }
+
   public String operationId() {
     return operationId;
   }

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

@@ -0,0 +1,22 @@
+package com.retailsvc.http;
+
+/**
+ * Optional capability for {@link TypeMapper}s that can deserialise a request body directly into a
+ * caller-supplied target type. The framework uses this when handlers call {@link
+ * Request#asPojo(Class)}; mappers that cannot meaningfully honour a target type (e.g. the built-in
+ * form / text mappers) should not implement this interface.
+ *
+ * <p>Implementations should wrap any underlying {@link java.io.IOException} as a {@link
+ * java.io.UncheckedIOException} — consistent with the surrounding {@link TypeMapper} contract.
+ */
+public interface TypedTypeMapper extends TypeMapper {
+
+  /**
+   * Deserialise {@code body} into an instance of {@code type}.
+   *
+   * @param body raw request body bytes
+   * @param contentTypeHeader the full raw {@code Content-Type} header (for charset / params)
+   * @param type the target type
+   */
+  <T> T readAs(byte[] body, String contentTypeHeader, Class<T> type);
+}

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

@@ -62,10 +62,16 @@ public void doFilter(HttpExchange exchange, Chain chain) throws IOException {
 
     Operation op = match.operation();
     validateParameters(exchange, op, match.pathParameters());
-    Object parsedBody = validateAndParseBody(exchange, op, body);
+    ParsedBody parsedBody = validateAndParseBody(exchange, op, body);
 
     Request request =
-        new Request(exchange, body, parsedBody, op.operationId(), match.pathParameters());
+        new Request(
+            exchange,
+            body,
+            parsedBody.value(),
+            parsedBody.mapper(),
+            op.operationId(),
+            match.pathParameters());
 
     try {
       ScopedValue.where(DispatchHandler.CURRENT, request)
@@ -119,17 +125,22 @@ private void validateParameters(
     }
   }
 
-  private Object validateAndParseBody(HttpExchange exchange, Operation op, byte[] body) {
+  /** Result of {@link #validateAndParseBody}: parsed payload plus the mapper that produced it. */
+  private record ParsedBody(Object value, TypeMapper mapper) {
+    static final ParsedBody EMPTY = new ParsedBody(null, null);
+  }
+
+  private ParsedBody validateAndParseBody(HttpExchange exchange, Operation op, byte[] body) {
     Optional<RequestBody> rb = op.requestBody();
     if (rb.isEmpty()) {
-      return null;
+      return ParsedBody.EMPTY;
     }
     if (body.length == 0) {
       if (rb.get().required()) {
         throw new ValidationException(
             new ValidationError(BODY_POINTER, "required", "request body is required", null));
       }
-      return null;
+      return ParsedBody.EMPTY;
     }
     String header = exchange.getRequestHeaders().getFirst("Content-Type");
     String mediaType = ContentTypeHeader.mediaType(header);
@@ -152,7 +163,7 @@ private Object validateAndParseBody(HttpExchange exchange, Operation op, byte[]
       parsed = FormBodyCoercion.coerce(typed, mt.schema());
     }
     validator.validate(parsed, mt.schema(), "");
-    return parsed;
+    return new ParsedBody(parsed, mapper);
   }
 
   private static Map<String, String> parseQuery(String query) {

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

@@ -1,12 +1,16 @@
 package com.retailsvc.http;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.when;
 
+import com.fasterxml.jackson.databind.ObjectMapper;
 import com.retailsvc.http.internal.DispatchHandler;
+import com.sun.net.httpserver.Headers;
 import com.sun.net.httpserver.HttpExchange;
 import java.net.URI;
+import java.nio.charset.StandardCharsets;
 import java.util.Map;
 import java.util.concurrent.atomic.AtomicReference;
 import org.junit.jupiter.api.Test;
@@ -17,7 +21,8 @@ class RequestTest {
   void readsBoundContext() throws Exception {
     HttpExchange exchange = mock(HttpExchange.class);
     Request req =
-        new Request(exchange, new byte[] {1, 2, 3}, Map.of("k", "v"), "get-x", Map.of("id", "42"));
+        new Request(
+            exchange, new byte[] {1, 2, 3}, Map.of("k", "v"), null, "get-x", Map.of("id", "42"));
 
     AtomicReference<byte[]> seenBytes = new AtomicReference<>();
     AtomicReference<Object> seenParsed = new AtomicReference<>();
@@ -41,10 +46,77 @@ void readsBoundContext() throws Exception {
     assertThat(seenPathParams.get()).containsEntry("id", "42");
   }
 
+  @Test
+  void asPojoDeserialisesViaTypedMapper() {
+    HttpExchange exchange = mock(HttpExchange.class);
+    Headers headers = new Headers();
+    headers.add("Content-Type", "application/json");
+    when(exchange.getRequestHeaders()).thenReturn(headers);
+    JacksonJsonTypeMapper mapper = new JacksonJsonTypeMapper(new ObjectMapper());
+    byte[] body = "{\"id\":\"x-1\",\"qty\":7}".getBytes(StandardCharsets.UTF_8);
+    Request req =
+        new Request(exchange, body, Map.of("id", "x-1", "qty", 7), mapper, "op", Map.of());
+
+    Item item = req.asPojo(Item.class);
+
+    assertThat(item.id).isEqualTo("x-1");
+    assertThat(item.qty).isEqualTo(7);
+  }
+
+  @Test
+  void asPojoFastPathWhenParsedAlreadyMatchesType() {
+    HttpExchange exchange = mock(HttpExchange.class);
+    Map<String, Object> alreadyParsed = Map.of("k", "v");
+    Request req = new Request(exchange, "x".getBytes(), alreadyParsed, null, "op", Map.of());
+
+    Map<?, ?> result = req.asPojo(Map.class);
+    assertThat(result).isSameAs(alreadyParsed);
+  }
+
+  @Test
+  void asPojoThrowsWhenBodyEmpty() {
+    HttpExchange exchange = mock(HttpExchange.class);
+    Request req = new Request(exchange, new byte[0], null, null, "op", Map.of());
+
+    assertThatThrownBy(() -> req.asPojo(Item.class))
+        .isInstanceOf(IllegalStateException.class)
+        .hasMessageContaining("no body");
+  }
+
+  @Test
+  void asPojoThrowsWhenMapperNotTyped() {
+    HttpExchange exchange = mock(HttpExchange.class);
+    Headers headers = new Headers();
+    headers.add("Content-Type", "text/plain");
+    when(exchange.getRequestHeaders()).thenReturn(headers);
+    TypeMapper plain =
+        new TypeMapper() {
+          @Override
+          public Object readFrom(byte[] b, String h) {
+            return new String(b, StandardCharsets.UTF_8);
+          }
+
+          @Override
+          public byte[] writeTo(Object v) {
+            return v.toString().getBytes(StandardCharsets.UTF_8);
+          }
+        };
+    Request req = new Request(exchange, "hello".getBytes(), "hello", plain, "op", Map.of());
+
+    assertThatThrownBy(() -> req.asPojo(Item.class))
+        .isInstanceOf(IllegalStateException.class)
+        .hasMessageContaining("TypedTypeMapper");
+  }
+
+  static final class Item {
+    public String id;
+    public int qty;
+  }
+
   @Test
   void pathParamReturnsValueOrNull() {
     HttpExchange exchange = mock(HttpExchange.class);
-    Request req = new Request(exchange, new byte[0], null, "op", Map.of("id", "42"));
+    Request req = new Request(exchange, new byte[0], null, null, "op", Map.of("id", "42"));
 
     assertThat(req.pathParam("id")).isEqualTo("42");
     assertThat(req.pathParam("missing")).isNull();
@@ -55,7 +127,7 @@ void exposesQueryParams() {
     HttpExchange exchange = mock(HttpExchange.class);
     when(exchange.getRequestURI())
         .thenReturn(URI.create("http://h/x?name=Alice%20Smith&active=true&active=false"));
-    Request req = new Request(exchange, new byte[0], null, "op", Map.of());
+    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");
@@ -70,7 +142,7 @@ void exposesQueryParams() {
   void queryParamsEmptyWhenNoQuery() {
     HttpExchange exchange = mock(HttpExchange.class);
     when(exchange.getRequestURI()).thenReturn(URI.create("http://h/x"));
-    Request req = new Request(exchange, new byte[0], null, "op", Map.of());
+    Request req = new Request(exchange, new byte[0], null, null, "op", Map.of());
 
     assertThat(req.rawQuery()).isNull();
     assertThat(req.queryParams()).isEmpty();

src/test/java/com/retailsvc/http/internal/DispatchHandlerTest.java

@@ -32,7 +32,7 @@ private static DispatchHandler dispatcher(Map<String, RequestHandler> handlers)
   private static void withRequest(
       HttpExchange exchange, String operationId, ScopedValue.CallableOp<Void, Exception> body)
       throws Exception {
-    Request req = new Request(exchange, new byte[0], null, operationId, Map.of());
+    Request req = new Request(exchange, new byte[0], null, null, operationId, Map.of());
     ScopedValue.where(DispatchHandler.CURRENT, req).call(body);
   }