fix(http): Use ScopedValue for per-request state, not HttpExchange attributes

HttpExchange.setAttribute writes to a context-shared map; concurrent
requests overwrote each other's body bytes/operation-id/path-parameters,
which manifested in k6 as ~30% empty 200 response bodies under modest
keep-alive load. The original master code avoided this via a private
attribute map on its BodyHandler.RequestBodyWrapper, which the refactor
inadvertently dropped.

Replaces the four exchange attributes with a single immutable
RequestContext bound to ScopedValue.CONTEXT for the duration of the
request. Request.bytes/parsed/operationId/pathParams are now no-arg
accessors on the bound value; they throw NoSuchElementException if read
outside a request scope.

Verified with the curl-equivalent k6 profile: 30 sustained VUs / 45 s /
1,436,394 requests / 2,393,990 checks → 100% pass, 0% HTTP failures.

README updated to retract the keep-alive caveat (it was a misdiagnosis)
and document the ScopedValue ⇒ off-thread capture rule for handlers.

Author: thced

.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(mvn *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git push *)",
+      "Bash(k6 run *)"
+    ]
+  }
+}

README.md

@@ -124,13 +124,13 @@ Schemas are located under test resources folder.
 
 The library wraps the JDK's bundled `com.sun.net.httpserver.HttpServer` and uses a virtual-thread-per-request executor. On a developer laptop (Apple Silicon, single instance, default JVM flags) it sustains roughly:
 
-- **20k–35k requests/second** for small JSON GETs and POSTs (~300 byte bodies), measured both via parallelised `curl` (no connection reuse) and via `k6` at moderate VU counts.
-- The HTTP layer reports **0% request failures** even when sustained at 30 concurrent virtual users for 45 seconds (~1.5M requests).
+- **~32k requests/second** for small JSON GETs and POSTs (~300 byte bodies), measured via `k6` at 30 sustained VUs over 45 seconds (1.4M requests, **100% of checks passing**, 0% HTTP failures).
 
-That said, the underlying JDK HttpServer is documented as a low-throughput / dev-test server, and a few caveats are worth knowing:
+A few things to know:
 
-- **Keep-alive reuse at high concurrency.** k6 and other clients that aggressively reuse HTTP/1.1 connections will occasionally observe empty response bodies (with the correct `Content-Length` header) when running tens of VUs against this server. Curl-style clients that open a fresh connection per request do not see this. If you need consistent throughput above a few thousand RPS with keep-alive clients, consider deploying behind a real HTTP server (Jetty, Helidon Níma, Netty) — this library's filter/validator stack is independent of the underlying server and could be ported.
 - **Single-process model.** No horizontal scaling primitives are bundled; run multiple instances behind a load balancer for production scale.
-- **`HttpExchange.sendResponseHeaders(rCode, length)` semantics.** When a handler has no response body, pass `-1` (no body, `Content-Length: 0`); passing `0` produces a chunked response with zero chunks, which is technically non-conformant.
+- **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.
 
 ## Known limitations or missing features

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

@@ -1,30 +1,39 @@
 package com.retailsvc.http;
 
-import com.sun.net.httpserver.HttpExchange;
+import com.retailsvc.http.internal.RequestContext;
 import java.util.Map;
 
+/**
+ * Static accessors for per-request state populated by the request-preparation filter.
+ *
+ * <p>The state is bound to a {@link ScopedValue} for the duration of the request rather than stored
+ * on the {@code HttpExchange}, because {@code HttpExchange.setAttribute} writes to a context-shared
+ * map and would race across concurrent requests.
+ *
+ * <p>If a handler dispatches work to a non-structured executor (i.e. not a {@code
+ * StructuredTaskScope}-managed thread), it must capture the values it needs before submitting — the
+ * {@link ScopedValue} is not visible from arbitrary worker threads.
+ */
 public final class Request {
-  public static final String BODY = "body";
-  public static final String PARSED_BODY = "parsed-body";
-  public static final String OPERATION_ID = "operation-id";
-  public static final String PATH_PARAMETERS = "path-parameters";
+
+  /** Bound by {@code RequestPreparationFilter} for the duration of each request. */
+  public static final ScopedValue<RequestContext> CONTEXT = ScopedValue.newInstance();
 
   private Request() {}
 
-  public static byte[] bytes(HttpExchange e) {
-    return (byte[]) e.getAttribute(BODY);
+  public static byte[] bytes() {
+    return CONTEXT.get().body();
   }
 
-  public static Object parsed(HttpExchange e) {
-    return e.getAttribute(PARSED_BODY);
+  public static Object parsed() {
+    return CONTEXT.get().parsedBody();
   }
 
-  public static String operationId(HttpExchange e) {
-    return (String) e.getAttribute(OPERATION_ID);
+  public static String operationId() {
+    return CONTEXT.get().operationId();
   }
 
-  @SuppressWarnings("unchecked")
-  public static Map<String, String> pathParams(HttpExchange e) {
-    return (Map<String, String>) e.getAttribute(PATH_PARAMETERS);
+  public static Map<String, String> pathParams() {
+    return CONTEXT.get().pathParameters();
   }
 }

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

@@ -16,7 +16,7 @@ public DispatchHandler(Map<String, HttpHandler> handlers) {
 
   @Override
   public void handle(HttpExchange exchange) throws IOException {
-    String opId = Request.operationId(exchange);
+    String opId = Request.operationId();
     HttpHandler h = handlers.get(opId);
     if (h == null) {
       throw new MissingOperationHandlerException(opId);

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

@@ -0,0 +1,11 @@
+package com.retailsvc.http.internal;
+
+import java.util.Map;
+
+/**
+ * Immutable per-request data populated by {@link RequestPreparationFilter} and read by handlers via
+ * {@link com.retailsvc.http.Request}. Bound to a {@link ScopedValue} for the duration of a single
+ * request — never written to the {@code HttpExchange}'s context-shared attribute map.
+ */
+public record RequestContext(
+    byte[] body, Object parsedBody, String operationId, Map<String, String> pathParameters) {}

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

@@ -1,13 +1,9 @@
 package com.retailsvc.http.internal;
 
-import static com.retailsvc.http.Request.BODY;
-import static com.retailsvc.http.Request.OPERATION_ID;
-import static com.retailsvc.http.Request.PARSED_BODY;
-import static com.retailsvc.http.Request.PATH_PARAMETERS;
-
 import com.retailsvc.http.JsonMapper;
 import com.retailsvc.http.MethodNotAllowedException;
 import com.retailsvc.http.NotFoundException;
+import com.retailsvc.http.Request;
 import com.retailsvc.http.ValidationException;
 import com.retailsvc.http.spec.HttpMethod;
 import com.retailsvc.http.spec.MediaType;
@@ -48,7 +44,6 @@ public String description() {
   @Override
   public void doFilter(HttpExchange exchange, Chain chain) throws IOException {
     byte[] body = exchange.getRequestBody().readAllBytes();
-    exchange.setAttribute(BODY, body);
 
     HttpMethod method = HttpMethod.parse(exchange.getRequestMethod());
     String path = stripBasePath(exchange.getRequestURI().getPath());
@@ -64,13 +59,35 @@ public void doFilter(HttpExchange exchange, Chain chain) throws IOException {
     Router.Match match = matchOpt.get();
 
     Operation op = match.operation();
-    exchange.setAttribute(OPERATION_ID, op.operationId());
-    exchange.setAttribute(PATH_PARAMETERS, match.pathParameters());
-
     validateParameters(exchange, op, match.pathParameters());
-    validateBody(exchange, op, body);
+    Object parsedBody = validateAndParseBody(exchange, op, body);
+
+    RequestContext ctx =
+        new RequestContext(body, parsedBody, op.operationId(), match.pathParameters());
+
+    runWithRequestContext(ctx, () -> chain.doFilter(exchange));
+  }
+
+  private static void runWithRequestContext(RequestContext ctx, IORunnable work)
+      throws IOException {
+    try {
+      ScopedValue.where(Request.CONTEXT, ctx)
+          .call(
+              () -> {
+                work.run();
+                return null;
+              });
+    } catch (IOException | RuntimeException e) {
+      throw e;
+    } catch (Exception e) {
+      // Callable.call() throws Exception; nothing else can actually be thrown by the chain.
+      throw new IOException(e);
+    }
+  }
 
-    chain.doFilter(exchange);
+  @FunctionalInterface
+  private interface IORunnable {
+    void run() throws IOException;
   }
 
   private String stripBasePath(String path) {
@@ -108,17 +125,17 @@ private void validateParameters(
     }
   }
 
-  private void validateBody(HttpExchange exchange, Operation op, byte[] body) {
+  private Object validateAndParseBody(HttpExchange exchange, Operation op, byte[] body) {
     Optional<RequestBody> rb = op.requestBody();
     if (rb.isEmpty()) {
-      return;
+      return null;
     }
     if (body.length == 0) {
       if (rb.get().required()) {
         throw new ValidationException(
             new ValidationError("/body", "required", "request body is required", null));
       }
-      return;
+      return null;
     }
     String contentType = exchange.getRequestHeaders().getFirst("Content-Type");
     if (contentType == null) {
@@ -132,8 +149,8 @@ private void validateBody(HttpExchange exchange, Operation op, byte[] body) {
               "/body", "content-type", "unsupported content type: " + contentType, null));
     }
     Object parsed = jsonMapper.mapFrom(body);
-    exchange.setAttribute(PARSED_BODY, parsed);
     validator.validate(parsed, mt.schema(), "");
+    return parsed;
   }
 
   private static Map<String, String> parseQuery(String query) {

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

@@ -1,24 +1,44 @@
 package com.retailsvc.http;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 
-import com.sun.net.httpserver.HttpExchange;
+import com.retailsvc.http.internal.RequestContext;
 import java.util.Map;
+import java.util.NoSuchElementException;
+import java.util.concurrent.atomic.AtomicReference;
 import org.junit.jupiter.api.Test;
-import org.mockito.Mockito;
 
 class RequestTest {
+
+  @Test
+  void readsBoundContext() throws Exception {
+    RequestContext ctx =
+        new RequestContext(new byte[] {1, 2, 3}, Map.of("k", "v"), "get-x", Map.of("id", "42"));
+
+    AtomicReference<byte[]> seenBytes = new AtomicReference<>();
+    AtomicReference<Object> seenParsed = new AtomicReference<>();
+    AtomicReference<String> seenOpId = new AtomicReference<>();
+    AtomicReference<Map<String, String>> seenPathParams = new AtomicReference<>();
+
+    ScopedValue.where(Request.CONTEXT, ctx)
+        .call(
+            () -> {
+              seenBytes.set(Request.bytes());
+              seenParsed.set(Request.parsed());
+              seenOpId.set(Request.operationId());
+              seenPathParams.set(Request.pathParams());
+              return null;
+            });
+
+    assertThat(seenBytes.get()).containsExactly(1, 2, 3);
+    assertThat(seenParsed.get()).isEqualTo(Map.of("k", "v"));
+    assertThat(seenOpId.get()).isEqualTo("get-x");
+    assertThat(seenPathParams.get()).containsEntry("id", "42");
+  }
+
   @Test
-  void readsAttributes() {
-    HttpExchange ex = Mockito.mock(HttpExchange.class);
-    Mockito.when(ex.getAttribute("body")).thenReturn(new byte[] {1, 2, 3});
-    Mockito.when(ex.getAttribute("parsed-body")).thenReturn(Map.of("k", "v"));
-    Mockito.when(ex.getAttribute("operation-id")).thenReturn("get-x");
-    Mockito.when(ex.getAttribute("path-parameters")).thenReturn(Map.of("id", "42"));
-
-    assertThat(Request.bytes(ex)).containsExactly(1, 2, 3);
-    assertThat(Request.parsed(ex)).isEqualTo(Map.of("k", "v"));
-    assertThat(Request.operationId(ex)).isEqualTo("get-x");
-    assertThat(Request.pathParams(ex)).containsEntry("id", "42");
+  void readingOutsideScopeThrows() {
+    assertThrows(NoSuchElementException.class, () -> Request.bytes());
   }
 }

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

@@ -11,23 +11,42 @@
 import org.mockito.Mockito;
 
 class DispatchHandlerTest {
-  private HttpExchange exchange(String operationId) {
-    HttpExchange ex = Mockito.mock(HttpExchange.class);
-    Mockito.when(ex.getAttribute(Request.OPERATION_ID)).thenReturn(operationId);
-    return ex;
+
+  private static void withOperationId(
+      String operationId, ScopedValue.CallableOp<Void, Exception> body) throws Exception {
+    RequestContext ctx = new RequestContext(new byte[0], null, operationId, Map.of());
+    ScopedValue.where(Request.CONTEXT, ctx).call(body);
   }
 
   @Test
   void invokesRegisteredHandler() throws Exception {
     HttpHandler handler = Mockito.mock(HttpHandler.class);
-    new DispatchHandler(Map.of("get-x", handler)).handle(exchange("get-x"));
+    HttpExchange ex = Mockito.mock(HttpExchange.class);
+
+    withOperationId(
+        "get-x",
+        () -> {
+          new DispatchHandler(Map.of("get-x", handler)).handle(ex);
+          return null;
+        });
+    // bound op-id is "get-x"; DispatchHandler should look up the registered HttpHandler.
+
     Mockito.verify(handler).handle(Mockito.any());
   }
 
   @Test
   void throwsWhenHandlerMissing() {
     DispatchHandler d = new DispatchHandler(Map.of());
-    HttpExchange ex = exchange("ghost");
-    assertThatThrownBy(() -> d.handle(ex)).isInstanceOf(MissingOperationHandlerException.class);
+    HttpExchange ex = Mockito.mock(HttpExchange.class);
+
+    assertThatThrownBy(
+            () ->
+                withOperationId(
+                    "ghost",
+                    () -> {
+                      d.handle(ex);
+                      return null;
+                    }))
+        .isInstanceOf(MissingOperationHandlerException.class);
   }
 }