feat: ExtraRoute accepts RequestHandler via ExtraRouteAdapter

Author: thced

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

@@ -5,13 +5,11 @@
 import static java.net.HttpURLConnection.HTTP_BAD_METHOD;
 import static java.net.HttpURLConnection.HTTP_BAD_REQUEST;
 import static java.net.HttpURLConnection.HTTP_INTERNAL_ERROR;
-import static java.net.HttpURLConnection.HTTP_NOT_FOUND;
 import static java.net.HttpURLConnection.HTTP_OK;
 import static java.net.HttpURLConnection.HTTP_UNAVAILABLE;
 
 import com.retailsvc.http.internal.ClasspathResourceHandler;
 import com.retailsvc.http.internal.ProblemDetail;
-import com.sun.net.httpserver.HttpHandler;
 import java.util.List;
 import java.util.Objects;
 import java.util.function.Supplier;
@@ -52,14 +50,6 @@ public static ExceptionHandler defaultExceptionHandler(TypeMapper jsonMapper) {
         };
   }
 
-  public static HttpHandler notFoundHandler() {
-    return exchange -> {
-      try (exchange) {
-        exchange.sendResponseHeaders(HTTP_NOT_FOUND, -1);
-      }
-    };
-  }
-
   /** Returns 204 No Content on GET/HEAD; 405 with {@code Allow: GET, HEAD} otherwise. */
   public static RequestHandler aliveHandler() {
     return req ->

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

@@ -6,7 +6,9 @@
 
 import com.retailsvc.http.internal.DispatchHandler;
 import com.retailsvc.http.internal.ExceptionFilter;
+import com.retailsvc.http.internal.ExtraRouteAdapter;
 import com.retailsvc.http.internal.FormTypeMapper;
+import com.retailsvc.http.internal.NotFoundHandler;
 import com.retailsvc.http.internal.RequestPreparationFilter;
 import com.retailsvc.http.internal.ResponseRenderer;
 import com.retailsvc.http.internal.Router;
@@ -18,7 +20,6 @@
 import com.retailsvc.http.spec.security.SecurityScheme;
 import com.retailsvc.http.validate.DefaultValidator;
 import com.sun.net.httpserver.HttpContext;
-import com.sun.net.httpserver.HttpHandler;
 import com.sun.net.httpserver.HttpServer;
 import java.io.IOException;
 import java.net.InetAddress;
@@ -57,7 +58,7 @@ record HandlerConfig(
       List<RequestInterceptor> interceptors,
       List<ResponseDecorator> decorators,
       ExceptionHandler exceptionHandler,
-      Map<String, HttpHandler> extras,
+      Map<String, RequestHandler> extras,
       Map<String, SchemeValidator> securityValidators,
       boolean externalAuth) {}
 
@@ -110,14 +111,14 @@ record HandlerConfig(
             handlerConfig.decorators(),
             renderer));
 
-    for (Map.Entry<String, HttpHandler> e : handlerConfig.extras().entrySet()) {
+    for (Map.Entry<String, RequestHandler> e : handlerConfig.extras().entrySet()) {
       HttpContext extraCtx = httpServer.createContext(e.getKey());
       extraCtx.getFilters().add(new ExceptionFilter(exceptionHandler, renderer));
-      extraCtx.setHandler(e.getValue());
+      extraCtx.setHandler(new ExtraRouteAdapter(e.getValue(), renderer));
     }
 
     if (!"/".equals(basePath)) {
-      httpServer.createContext("/", Handlers.notFoundHandler());
+      httpServer.createContext("/", new NotFoundHandler());
     }
     httpServer.start();
 
@@ -180,7 +181,7 @@ public static final class Builder {
     private int port = DEFAULT_PORT;
     private InetAddress bindAddress;
     private int shutdownTimeoutSeconds = 0;
-    private final LinkedHashMap<String, HttpHandler> extras = new LinkedHashMap<>();
+    private final LinkedHashMap<String, RequestHandler> extras = new LinkedHashMap<>();
     private final Map<String, SchemeValidator> securityValidators = new LinkedHashMap<>();
     private boolean externalAuth = false;
 
@@ -294,7 +295,7 @@ public Builder shutdownTimeoutSeconds(int shutdownTimeoutSeconds) {
      * anything that isn't an OpenAPI {@code operationId}. For OpenAPI-described operations use
      * {@link #handlers(Map)}.
      */
-    public Builder extraRoute(String path, HttpHandler handler) {
+    public Builder extraRoute(String path, RequestHandler handler) {
       requireNonNull(path, "path must not be null");
       requireNonNull(handler, "handler must not be null");
       if (extras.containsKey(path)) {

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

@@ -0,0 +1,49 @@
+package com.retailsvc.http.internal;
+
+import com.retailsvc.http.Request;
+import com.retailsvc.http.RequestHandler;
+import com.retailsvc.http.Response;
+import com.retailsvc.http.spec.HttpMethod;
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpHandler;
+import java.io.IOException;
+import java.util.Map;
+
+/**
+ * Bridges an extra-route {@link RequestHandler} to the underlying JDK {@link HttpHandler}.
+ *
+ * <p>Builds a {@link Request} with {@code operationId=null}, empty path-params, empty principals,
+ * raw body bytes, raw query, and the parsed HTTP method, then renders the returned {@link Response}
+ * through the shared {@link ResponseRenderer}. OpenAPI validation, body parsing, and security are
+ * intentionally bypassed — extras are by definition outside the spec.
+ */
+public final class ExtraRouteAdapter implements HttpHandler {
+
+  private final RequestHandler handler;
+  private final ResponseRenderer renderer;
+
+  public ExtraRouteAdapter(RequestHandler handler, ResponseRenderer renderer) {
+    this.handler = handler;
+    this.renderer = renderer;
+  }
+
+  @Override
+  public void handle(HttpExchange exchange) throws IOException {
+    byte[] body = exchange.getRequestBody().readAllBytes();
+    HttpMethod method = HttpMethod.parse(exchange.getRequestMethod());
+    var headers = exchange.getRequestHeaders();
+    Request request =
+        new Request(
+            body,
+            null,
+            null,
+            null,
+            Map.of(),
+            exchange.getRequestURI().getRawQuery(),
+            headers::getFirst,
+            Map.of(),
+            method);
+    Response response = handler.handle(request);
+    renderer.render(exchange, response);
+  }
+}

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

@@ -0,0 +1,18 @@
+package com.retailsvc.http.internal;
+
+import static java.net.HttpURLConnection.HTTP_NOT_FOUND;
+
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpHandler;
+import java.io.IOException;
+
+/** Returns 404 with no body. Used for the framework's catch-all {@code /} context. */
+public final class NotFoundHandler implements HttpHandler {
+
+  @Override
+  public void handle(HttpExchange exchange) throws IOException {
+    try (exchange) {
+      exchange.sendResponseHeaders(HTTP_NOT_FOUND, -1);
+    }
+  }
+}

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

@@ -11,16 +11,14 @@
 class ExtraHandlersIT extends ServerBaseTest {
 
   @Test
-  // MIGRATED-IN-TASK-6: re-enable Handlers.aliveHandler() once extraRoute accepts RequestHandler
   void aliveExtraReturns204AndBypassesValidation() throws Exception {
-    com.sun.net.httpserver.HttpHandler alive =
-        ex -> {
-          try (ex) {
-            ex.sendResponseHeaders(204, -1);
-          }
-        };
     try (var s =
-            newBuilder().spec(spec).handlers(Map.of()).port(0).extraRoute("/alive", alive).build();
+            newBuilder()
+                .spec(spec)
+                .handlers(Map.of())
+                .port(0)
+                .extraRoute("/alive", Handlers.aliveHandler())
+                .build();
         var client = httpClient()) {
 
       var req =
@@ -36,23 +34,13 @@ void aliveExtraReturns204AndBypassesValidation() throws Exception {
   }
 
   @Test
-  // MIGRATED-IN-TASK-6: re-enable Handlers.specHandler() once extraRoute accepts RequestHandler
   void specHandlerServesClasspathResource() throws Exception {
-    byte[] yamlBytes = ExtraHandlersIT.class.getResourceAsStream("/openapi.yaml").readAllBytes();
-    com.sun.net.httpserver.HttpHandler serveYaml =
-        ex -> {
-          try (ex) {
-            ex.getResponseHeaders().add("Content-Type", "application/yaml");
-            ex.sendResponseHeaders(200, yamlBytes.length);
-            ex.getResponseBody().write(yamlBytes);
-          }
-        };
     try (var s =
             newBuilder()
                 .spec(spec)
                 .handlers(Map.of())
                 .port(0)
-                .extraRoute("/openapi.yaml", serveYaml)
+                .extraRoute("/openapi.yaml", Handlers.specHandler("/openapi.yaml"))
                 .build();
         var client = httpClient()) {
 
@@ -71,8 +59,8 @@ void specHandlerServesClasspathResource() throws Exception {
 
   @Test
   void extraHandlerExceptionFlowsThroughExceptionHandler() throws Exception {
-    com.sun.net.httpserver.HttpHandler boom =
-        ex -> {
+    RequestHandler boom =
+        req -> {
           throw new RuntimeException("boom");
         };
 

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

@@ -5,7 +5,6 @@
 import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 
 import com.retailsvc.http.spec.Spec;
-import com.sun.net.httpserver.HttpHandler;
 import java.util.List;
 import java.util.Map;
 import org.junit.jupiter.api.Test;
@@ -26,9 +25,7 @@ void buildsWithRequiredFieldsOnly() {
 
   @Test
   void rejectsDuplicateExtraPathOnSecondAddHandler() {
-    // MIGRATED-IN-TASK-6: replace stub with Handlers.aliveHandler() once extraRoute accepts
-    // RequestHandler
-    HttpHandler duplicate = exchange -> {};
+    RequestHandler duplicate = req -> Response.empty();
     OpenApiServer.Builder b =
         OpenApiServer.builder().spec(spec).handlers(emptyMap()).extraRoute("/alive", duplicate);
 
@@ -40,13 +37,11 @@ void rejectsDuplicateExtraPathOnSecondAddHandler() {
   @Test
   void rejectsExtraPathEqualToSpecBasePathAtBuildTime() {
     // testSpec() uses "/api" as the basePath (servers[0].url = http://localhost:8080/api).
-    // MIGRATED-IN-TASK-6: replace stub with Handlers.aliveHandler() once extraRoute accepts
-    // RequestHandler
     OpenApiServer.Builder b =
         OpenApiServer.builder()
             .spec(spec)
             .handlers(emptyMap())
-            .extraRoute("/api", exchange -> {})
+            .extraRoute("/api", Handlers.aliveHandler())
             .port(0);
 
     assertThatThrownBy(b::build)

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

@@ -0,0 +1,58 @@
+package com.retailsvc.http.internal;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import com.retailsvc.http.GsonTypeMapper;
+import com.retailsvc.http.Request;
+import com.retailsvc.http.RequestHandler;
+import com.retailsvc.http.Response;
+import com.retailsvc.http.TypeMapper;
+import com.retailsvc.http.spec.HttpMethod;
+import com.sun.net.httpserver.Headers;
+import com.sun.net.httpserver.HttpExchange;
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.net.URI;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicReference;
+import org.junit.jupiter.api.Test;
+
+class ExtraRouteAdapterTest {
+
+  @Test
+  void buildsRequestWithMethodQueryHeadersAndBodyBytesAndNullOperationId() throws Exception {
+    AtomicReference<Request> captured = new AtomicReference<>();
+    RequestHandler handler =
+        req -> {
+          captured.set(req);
+          return Response.empty();
+        };
+
+    Map<String, TypeMapper> mappers = Map.of("application/json", new GsonTypeMapper());
+    ResponseRenderer renderer = new ResponseRenderer(mappers);
+    ExtraRouteAdapter adapter = new ExtraRouteAdapter(handler, renderer);
+
+    HttpExchange ex = mock(HttpExchange.class);
+    Headers reqHeaders = new Headers();
+    reqHeaders.add("X-Trace", "abc");
+    when(ex.getRequestMethod()).thenReturn("POST");
+    when(ex.getRequestURI()).thenReturn(new URI("/alive?x=1"));
+    when(ex.getRequestHeaders()).thenReturn(reqHeaders);
+    when(ex.getRequestBody()).thenReturn(new ByteArrayInputStream("hi".getBytes()));
+    when(ex.getResponseHeaders()).thenReturn(new Headers());
+    when(ex.getResponseBody()).thenReturn(new ByteArrayOutputStream());
+
+    adapter.handle(ex);
+
+    Request r = captured.get();
+    assertThat(r.operationId()).isNull();
+    assertThat(r.pathParams()).isEmpty();
+    assertThat(r.principals()).isEmpty();
+    assertThat(r.method()).isEqualTo(HttpMethod.POST);
+    assertThat(r.rawQuery()).isEqualTo("x=1");
+    assertThat(r.header("X-Trace")).contains("abc");
+    assertThat(r.bytes()).containsExactly('h', 'i');
+  }
+}