refactor!: Decouple Request from HttpExchange to enable swappable transports

Request now holds transport-neutral primitives: body bytes, parsed body,
TypeMapper, operationId, path parameters, raw query string, and a
Function<String,String> header lookup. The JDK HttpServer adapter
(RequestPreparationFilter) is the only place that touches HttpExchange.

Why: keeps the door open to a Netty / Helidon Nima / Jetty backend later
if JDK HttpServer's throughput becomes the bottleneck. The handler-facing
API (Request, Response, RequestHandler, RequestInterceptor,
ResponseDecorator, TypeMapper) is now genuinely transport-neutral — a
future adapter would live in com.retailsvc.http.internal and leave
handler code untouched.

README's 'Performance and caveats' section documents the rationale.

Author: thced

README.md

@@ -433,7 +433,7 @@ The library wraps the JDK's bundled `com.sun.net.httpserver.HttpServer` and uses
 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.
+- **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, the handler-facing API (`Request`, `Response`, `RequestHandler`, `RequestInterceptor`, `ResponseDecorator`, `TypeMapper`) is transport-neutral by design — `Request` is built from primitives (body bytes, raw query string, path parameters, a header lookup function), not a JDK `HttpExchange`. A future enhancement could plug in a higher-throughput backend (Jetty, Helidon Níma, Netty) by writing a new adapter behind `com.retailsvc.http.internal` while leaving handlers untouched.
 - **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 use `Response.empty()` (204) or `Response.status(code)` for other no-body statuses.** The renderer sends `responseLength = -1` (`Content-Length: 0`, no body) for any `Response` with `body() == null`, regardless of status code. Passing `0` to the JDK directly produces a chunked response with zero chunks, which is technically non-conformant — `Response` factories handle this for you.
 

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

@@ -1,43 +1,64 @@
 package com.retailsvc.http;
 
-import com.sun.net.httpserver.HttpExchange;
 import java.net.URLDecoder;
 import java.nio.charset.StandardCharsets;
 import java.util.LinkedHashMap;
 import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
+import java.util.function.Function;
 
 /**
  * Read-only per-request handle passed to {@link RequestHandler}. Carries the parsed body, path
- * parameters, query parameters, headers, and operation ID. Handlers consume a {@code Request} and
- * return a {@link Response}.
+ * parameters, query parameters, headers, and operation ID.
+ *
+ * <p>{@code Request} is transport-neutral: it holds the body bytes, the raw query string, the path
+ * parameter map, and a header lookup function. The transport adapter (today the built-in JDK {@code
+ * HttpServer}, tomorrow potentially Netty or another backend) is responsible for extracting those
+ * primitives from its own request representation. Handlers consume a {@code Request} and return a
+ * {@link Response}.
  */
 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 final String rawQuery;
+  private final Function<String, String> headerLookup;
   private Map<String, String> queryParamCache;
 
+  /**
+   * Builds a {@code Request} from transport-neutral primitives. Adapters call this; handlers
+   * receive the constructed instance.
+   *
+   * @param body raw request body bytes; never {@code null}, may be empty
+   * @param parsed loose structural view of the body (Map / List / boxed primitive), or {@code null}
+   * @param bodyMapper {@link TypeMapper} that produced {@code parsed}, used for typed conversion;
+   *     may be {@code null} if there is no body
+   * @param operationId the OpenAPI {@code operationId} the request was routed to
+   * @param pathParameters path variables extracted by the router
+   * @param rawQuery raw (percent-encoded) query string, or {@code null} if absent
+   * @param headerLookup first-value, case-insensitive header lookup; returns {@code null} if absent
+   */
   public Request(
-      HttpExchange exchange,
       byte[] body,
       Object parsed,
       TypeMapper bodyMapper,
       String operationId,
-      Map<String, String> pathParameters) {
-    this.exchange = exchange;
+      Map<String, String> pathParameters,
+      String rawQuery,
+      Function<String, String> headerLookup) {
     this.body = body;
     this.parsed = parsed;
     this.bodyMapper = bodyMapper;
     this.operationId = operationId;
     this.pathParameters = pathParameters;
+    this.rawQuery = rawQuery;
+    this.headerLookup = headerLookup;
   }
 
   public byte[] bytes() {
@@ -71,7 +92,7 @@ public <T> T asPojo(Class<T> type) {
     if (parsed != null && type.isInstance(parsed)) {
       return type.cast(parsed);
     }
-    String contentType = exchange.getRequestHeaders().getFirst(CONTENT_TYPE);
+    String contentType = headerLookup.apply(CONTENT_TYPE);
     if (bodyMapper instanceof TypedTypeMapper typed) {
       return typed.readAs(body, contentType, type);
     }
@@ -100,7 +121,7 @@ public String pathParam(String name) {
    * without the extra {@code filter(v -> !v.isBlank())} step.
    */
   public Optional<String> header(String name) {
-    String raw = exchange.getRequestHeaders().getFirst(name);
+    String raw = headerLookup.apply(name);
     return raw == null || raw.isBlank() ? Optional.empty() : Optional.of(raw);
   }
 
@@ -109,7 +130,7 @@ public Optional<String> header(String name) {
    * query component.
    */
   public String rawQuery() {
-    return exchange.getRequestURI().getRawQuery();
+    return rawQuery;
   }
 
   /**
@@ -118,7 +139,7 @@ public String rawQuery() {
    */
   public Map<String, String> queryParams() {
     if (queryParamCache == null) {
-      queryParamCache = parseQuery(rawQuery());
+      queryParamCache = parseQuery(rawQuery);
     }
     return queryParamCache;
   }

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

@@ -64,14 +64,16 @@ public void doFilter(HttpExchange exchange, Chain chain) throws IOException {
     validateParameters(exchange, op, match.pathParameters());
     ParsedBody parsedBody = validateAndParseBody(exchange, op, body);
 
+    var headers = exchange.getRequestHeaders();
     Request request =
         new Request(
-            exchange,
             body,
             parsedBody.value(),
             parsedBody.mapper(),
             op.operationId(),
-            match.pathParameters());
+            match.pathParameters(),
+            exchange.getRequestURI().getRawQuery(),
+            headers::getFirst);
 
     try {
       ScopedValue.where(DispatchHandler.CURRENT, request)

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

@@ -2,27 +2,38 @@
 
 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 java.util.function.Function;
 import org.junit.jupiter.api.Test;
 
 class RequestTest {
 
+  private static final Function<String, String> NO_HEADERS = name -> null;
+
+  private static Function<String, String> headers(String... pairs) {
+    Map<String, String> map = new java.util.HashMap<>();
+    for (int i = 0; i < pairs.length; i += 2) {
+      map.put(pairs[i].toLowerCase(), pairs[i + 1]);
+    }
+    return name -> map.get(name.toLowerCase());
+  }
+
   @Test
   void readsBoundContext() throws Exception {
-    HttpExchange exchange = mock(HttpExchange.class);
     Request req =
         new Request(
-            exchange, new byte[] {1, 2, 3}, Map.of("k", "v"), null, "get-x", Map.of("id", "42"));
+            new byte[] {1, 2, 3},
+            Map.of("k", "v"),
+            null,
+            "get-x",
+            Map.of("id", "42"),
+            null,
+            NO_HEADERS);
 
     AtomicReference<byte[]> seenBytes = new AtomicReference<>();
     AtomicReference<Object> seenParsed = new AtomicReference<>();
@@ -48,14 +59,17 @@ void readsBoundContext() throws Exception {
 
   @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());
+        new Request(
+            body,
+            Map.of("id", "x-1", "qty", 7),
+            mapper,
+            "op",
+            Map.of(),
+            null,
+            headers("Content-Type", "application/json"));
 
     Item item = req.asPojo(Item.class);
 
@@ -65,18 +79,17 @@ void asPojoDeserialisesViaTypedMapper() {
 
   @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());
+    Request req =
+        new Request("x".getBytes(), alreadyParsed, null, "op", Map.of(), null, NO_HEADERS);
 
     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());
+    Request req = new Request(new byte[0], null, null, "op", Map.of(), null, NO_HEADERS);
 
     assertThatThrownBy(() -> req.asPojo(Item.class))
         .isInstanceOf(IllegalStateException.class)
@@ -85,10 +98,6 @@ void asPojoThrowsWhenBodyEmpty() {
 
   @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
@@ -101,7 +110,15 @@ public byte[] writeTo(Object v) {
             return v.toString().getBytes(StandardCharsets.UTF_8);
           }
         };
-    Request req = new Request(exchange, "hello".getBytes(), "hello", plain, "op", Map.of());
+    Request req =
+        new Request(
+            "hello".getBytes(),
+            "hello",
+            plain,
+            "op",
+            Map.of(),
+            null,
+            headers("Content-Type", "text/plain"));
 
     assertThatThrownBy(() -> req.asPojo(Item.class))
         .isInstanceOf(IllegalStateException.class)
@@ -115,19 +132,23 @@ static final class Item {
 
   @Test
   void pathParamReturnsValueOrNull() {
-    HttpExchange exchange = mock(HttpExchange.class);
-    Request req = new Request(exchange, new byte[0], null, null, "op", Map.of("id", "42"));
+    Request req = new Request(new byte[0], null, null, "op", Map.of("id", "42"), null, NO_HEADERS);
 
     assertThat(req.pathParam("id")).isEqualTo("42");
     assertThat(req.pathParam("missing")).isNull();
   }
 
   @Test
   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, null, "op", Map.of());
+    Request req =
+        new Request(
+            new byte[0],
+            null,
+            null,
+            "op",
+            Map.of(),
+            "name=Alice%20Smith&active=true&active=false",
+            NO_HEADERS);
 
     assertThat(req.rawQuery()).isEqualTo("name=Alice%20Smith&active=true&active=false");
     assertThat(req.queryParam("name")).contains("Alice Smith");
@@ -140,9 +161,7 @@ void exposesQueryParams() {
 
   @Test
   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, null, "op", Map.of());
+    Request req = new Request(new byte[0], null, null, "op", Map.of(), null, NO_HEADERS);
 
     assertThat(req.rawQuery()).isNull();
     assertThat(req.queryParams()).isEmpty();
@@ -151,22 +170,24 @@ void queryParamsEmptyWhenNoQuery() {
 
   @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());
+    Request req =
+        new Request(new byte[0], null, null, "op", Map.of(), "limit=&offset=%20", NO_HEADERS);
 
     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());
+    Request req =
+        new Request(
+            new byte[0],
+            null,
+            null,
+            "op",
+            Map.of(),
+            null,
+            headers("X-Trace", "abc", "X-Empty", "   "));
 
     assertThat(req.header("X-Trace")).contains("abc");
     assertThat(req.header("X-Empty")).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, null, operationId, Map.of());
+    Request req = new Request(new byte[0], null, null, operationId, Map.of(), null, n -> null);
     ScopedValue.where(DispatchHandler.CURRENT, req).call(body);
   }