docs: Update README for TypeMapper and RequestHandler

Author: thced

README.md

@@ -26,45 +26,27 @@ It is designed to be simple to use while providing the essential features needed
 
 ### Basic Usage
 1. Create an OpenAPI specification file named `openapi.json` in your project resources.
-2. Define your HTTP handlers by implementing the `HttpHandler` interface:
+2. Define your handlers using the `RequestHandler` functional interface:
 ``` java
-public class GetDataHandler implements HttpHandler {
-  @Override
-  public void handle(HttpExchange exchange) throws IOException {
-    try (exchange) {
-      byte[] bytes = """
-      {
-        "id": "some-id"
-      }""".getBytes();
-
-      var responseHeaders = exchange.getResponseHeaders();
-      responseHeaders.add("content-type", "application/json");
-
-      exchange.sendResponseHeaders(HTTP_OK, bytes.length);
-
-      try (var os = exchange.getResponseBody()) {
-        os.write(bytes);
-      }
-    }
-  }
-}
+// Inline lambda — returns JSON using the built-in Gson mapper.
+RequestHandler getDataHandler = req ->
+    req.respond(200).json(Map.of("id", "some-id"));
 
-public class PostDataHandler implements HttpHandler {
+// Class form — reads raw bytes or the pre-parsed body object.
+public class PostDataHandler implements RequestHandler {
   @Override
-  public void handle(HttpExchange exchange) throws IOException {
-    try (exchange) {
-      // Access the raw request body bytes.
-      byte[] body = Request.bytes(exchange);
-      // Or get the already-parsed object (Map or List) produced by your JsonMapper.
-      Object parsed = Request.parsed(exchange);
-
-      exchange.sendResponseHeaders(HTTP_OK, -1);
-    }
+  public void handle(Request request) throws IOException {
+    // Access the raw request body bytes.
+    byte[] body = request.bytes();
+    // Or get the already-parsed object (Map / List) produced by the registered TypeMapper.
+    Object parsed = request.parsed();
+
+    request.respond(200).json(parsed);
   }
 }
 ```
 
-3. Initialize the server (using Gson in this example):
+3. Initialize the server:
 ``` java
 public class YourServerLauncher {
   public static void main(String[] args) throws Exception {
@@ -75,17 +57,13 @@ public class YourServerLauncher {
     Map<String, Object> raw = (Map<String, Object>) gson.fromJson(text, Map.class);
     Spec spec = Spec.from(raw);
 
-    // Body parser. Returns a Map for objects, List for arrays.
-    JsonMapper mapper = body -> gson.fromJson(new String(body), Object.class);
-
     // Handlers by operationId.
-    Map<String, HttpHandler> handlers = new HashMap<>();
-    handlers.put("get-data", new GetDataHandler());
+    Map<String, RequestHandler> handlers = new HashMap<>();
+    handlers.put("get-data", getDataHandler);
     handlers.put("post-data", new PostDataHandler());
 
     var server = OpenApiServer.builder()
         .spec(spec)
-        .jsonMapper(mapper)
         .handlers(handlers)
         .exceptionHandler(Handlers.defaultExceptionHandler())
         .build();
@@ -100,13 +78,51 @@ Map<String, Object> raw = new Yaml().load(Files.newInputStream(Path.of("openapi.
 ```
 The rest is identical.
 
+### JSON mapping
+
+The library ships an internal `GsonJsonMapper` that is auto-registered for `application/json` when Gson is on the classpath and no user-supplied JSON mapper has been registered. It:
+
+- Returns JSON integers as `Long` and fractional numbers as `Double`.
+- Writes JSR-310 types (`Instant`, `OffsetDateTime`, `ZonedDateTime`, `LocalDateTime`, `LocalDate`, `LocalTime`) as ISO-8601 strings.
+
+For non-ISO date formats, custom naming strategies, or other custom serialization, register your own `TypeMapper`:
+
+``` java
+var server = OpenApiServer.builder()
+    .spec(spec)
+    .bodyMapper("application/json", new MyCustomJsonMapper())
+    .handlers(handlers)
+    .build();
+```
+
+If Gson is not on the classpath and no `application/json` mapper is registered, `build()` throws `IllegalStateException`.
+
+### Body parsers and response writers
+
+`TypeMapper` is the per-media-type read/write contract:
+
+``` java
+public interface TypeMapper {
+  Object readFrom(byte[] body, String contentTypeHeader);
+  byte[] writeTo(Object value);
+}
+```
+
+Register a custom mapper for any media type via `Builder.bodyMapper(mediaType, mapper)`. Built-in defaults:
+
+- `application/x-www-form-urlencoded` — read-only. Produces `Map<String, Object>`. A single value is a `String`; repeated keys produce a `List`.
+- `text/plain` — read and write. Produces a decoded `String`; writes via `String.getBytes()`.
+- `application/json` — auto-registered when Gson is on the classpath (see above).
+
+User-supplied mappers take precedence over built-in defaults, so you can override any of the above.
+
 ### Request body content types
 
-The server reads `requestBody.content` from the spec and selects a parser by the request's media type (the bare `type/subtype` from `Content-Type`, e.g. `application/json`; lookup is case-insensitive):
+The server reads `requestBody.content` from the spec and selects a mapper by the request's media type (the bare `type/subtype` from `Content-Type`, e.g. `application/json`; lookup is case-insensitive):
 
 | Content type                          | Parser                                                                       | Coercion |
 | ------------------------------------- | ---------------------------------------------------------------------------- | -------- |
-| `application/json`                    | Caller-supplied `JsonMapper`                                                 | No — strict against the schema |
+| `application/json`                    | `GsonJsonMapper` (auto) or caller-supplied `TypeMapper`                      | No — strict against the schema |
 | `application/x-www-form-urlencoded`   | Built-in. `Map<String, Object>`. A single value is a `String`; repeated keys produce a `List`. After coercion the element type tracks the schema (e.g. an `integer` array yields `List<Long>`). | Yes — field values coerced to the property schema type (integer / number / boolean / array of those) |
 | `text/plain`                          | Built-in. Decoded `String`                                                   | No — schema should be `type: string` |
 
@@ -159,7 +175,6 @@ to OpenAPI parameter / body validation.
 ``` java
 var server = OpenApiServer.builder()
     .spec(spec)
-    .jsonMapper(mapper)
     .handlers(handlers)
     .addHandler("/alive", Handlers.aliveHandler())
     .addHandler("/schemas/v1/openapi.yaml",
@@ -189,7 +204,6 @@ try-with-resources) via the builder:
 ```java
 try (var server = OpenApiServer.builder()
     .spec(spec)
-    .jsonMapper(mapper)
     .handlers(handlers)
     .shutdownTimeoutSeconds(5)   // close() drains up to 5s; default is 0
     .build()) {
@@ -202,20 +216,15 @@ try (var server = OpenApiServer.builder()
 
 ## Features
 - OpenAPI specification support
-- Automatic request body parsing for JSON arrays and objects
-- Custom HTTP handler support
-- Built on Java's native `HttpServer` with Thread-Per-Request behaviour using Virtual Threads.
-- Custom integration for JSON serialization/deserialization
+- Automatic request body parsing and response writing per media type via `TypeMapper`
+- `RequestHandler` functional interface — a single `handle(Request)` method replaces raw `HttpExchange` manipulation
+- Fluent `ResponseBuilder` via `request.respond(status)` with terminals: `empty()`, `bytes()`, `text()`, `json()`, `body()`, `stream()`
+- Built-in `GsonJsonMapper` auto-registered when Gson is on the classpath (no explicit wiring needed)
+- Built on Java's native `HttpServer` with Thread-Per-Request behaviour using Virtual Threads
 
 
 ## Handler Registration
-Handlers are registered using string keys that correspond to your OpenAPI operation IDs.
-
-
-## JSON Mapping
-The library uses a flexible JSON mapping system that automatically detects and parses (using a mapper of choice):
-- JSON arrays (`[...]`)
-- JSON objects (`{...}`)
+Handlers are registered in a `Map<String, RequestHandler>` keyed by OpenAPI `operationId`.
 
 ## Local development
 
@@ -235,7 +244,7 @@ A few things to know:
 
 - **Single-process model.** No horizontal scaling primitives are bundled; run multiple instances behind a load balancer for production scale.
 - **JDK HttpServer is the throughput ceiling.** It's documented as a low-throughput / dev-test server. If you need to go materially above the rates above, deploy the same filter/validator/router stack on Jetty, Helidon Níma, or Netty — the spec and validation code is server-agnostic.
-- **Per-request state uses `ScopedValue`** (Java 25, JEP 506), not `HttpExchange.setAttribute`. This matters if a handler offloads work to an executor that's not a `StructuredTaskScope`-managed child thread: the `ScopedValue` is not visible there, so the handler must capture the values it needs (e.g. `byte[] body = Request.bytes();`) before submitting.
-- **`HttpExchange.sendResponseHeaders(rCode, length)` gotcha.** When a handler has no response body, pass `-1` (`Content-Length: 0`, no body); passing `0` produces a chunked response with zero chunks, which is technically non-conformant.
+- **Per-request state uses `ScopedValue`** (Java 25, JEP 506). This matters if a handler offloads work to an executor that's not a `StructuredTaskScope`-managed child thread: the `ScopedValue` is not visible there, so the handler must capture the values it needs (e.g. `byte[] body = request.bytes();`) before submitting.
+- **Empty responses must use `request.respond(status).empty()`**, which sends `responseLength = -1` (`Content-Length: 0`, no body). Passing `0` produces a chunked response with zero chunks, which is technically non-conformant.
 
 ## Known limitations or missing features