feat: Add ResponseDecorator and RequestInterceptor for cross-cutting concerns

Author: thced

README.md

@@ -120,6 +120,59 @@ Register a custom mapper for any media type via `Builder.bodyMapper(mediaType, m
 
 User-supplied mappers take precedence over built-in defaults, so you can override any of the above.
 
+### Response decorators
+
+`Builder.responseDecorator(...)` registers a `ResponseDecorator` that runs whenever a handler calls `request.respond(status)`. Decorators set headers (or other pre-terminal state) before the handler reaches a terminal call. They run in registration order, and handler-supplied headers override decorator-supplied ones (last write wins).
+
+Use cases: stamping correlation IDs, tenant IDs, server identifiers, or any cross-cutting header on every response.
+
+``` java
+OpenApiServer.builder()
+    .spec(spec)
+    .handlers(handlers)
+    .responseDecorator(
+        (request, response) ->
+            response.header("X-Correlation-Id", CorrelationId.current()))
+    .responseDecorator(
+        (request, response) -> response.header("X-Tenant-Id", TenantId.current()))
+    .build();
+```
+
+`ResponseDecorator` is a `@FunctionalInterface`; the lambda receives the `Request` and the `ResponseBuilder` that's about to be returned from `respond(...)`. Don't call a terminal method (`empty()` / `bytes()` / `json()` / ...) from a decorator — terminals belong to the handler.
+
+### Request interceptors
+
+`Builder.interceptor(...)` registers a `RequestInterceptor` that wraps every handler invocation. Use it for `ScopedValue` bindings, MDC, authentication, tracing, or any concern that needs to run uniformly around handlers. Interceptors compose in registration order: the first registered runs outermost.
+
+``` java
+OpenApiServer.builder()
+    .spec(spec)
+    .handlers(handlers)
+    .interceptor(
+        (request, next) -> {
+          // Resolve once per request.
+          String tenant = request.header("X-Tenant-Id");
+          ScopedValue.where(TENANT, tenant)
+              .call(
+                  () -> {
+                    next.proceed();
+                    return null;
+                  });
+        })
+    .interceptor(
+        (request, next) -> {
+          MDC.put("op", request.operationId());
+          try {
+            next.proceed();
+          } finally {
+            MDC.remove("op");
+          }
+        })
+    .build();
+```
+
+Each interceptor must call `next.proceed()` to continue the chain. Exceptions propagate to the library's standard `ExceptionFilter` and `ExceptionHandler` pipeline.
+
 ### Request body content types
 
 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):
@@ -224,6 +277,7 @@ try (var server = OpenApiServer.builder()
 - `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)
+- `ResponseDecorator` for cross-cutting response headers and `RequestInterceptor` for around-style ScopedValue / MDC / auth concerns
 - Built on Java's native `HttpServer` with Thread-Per-Request behaviour using Virtual Threads
 
 

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

@@ -17,7 +17,9 @@
 import com.sun.net.httpserver.HttpServer;
 import java.io.IOException;
 import java.net.InetSocketAddress;
+import java.util.ArrayList;
 import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Locale;
 import java.util.Map;
 import java.util.Optional;
@@ -44,6 +46,8 @@ public class OpenApiServer implements AutoCloseable {
       Spec spec,
       Map<String, TypeMapper> bodyMappers,
       Map<String, RequestHandler> handlers,
+      List<ResponseDecorator> decorators,
+      List<RequestInterceptor> interceptors,
       ExceptionHandler exceptionHandler,
       int port,
       Map<String, HttpHandler> extras,
@@ -67,8 +71,9 @@ public class OpenApiServer implements AutoCloseable {
 
     HttpContext ctx = httpServer.createContext(Optional.ofNullable(spec.basePath()).orElse("/"));
     ctx.getFilters().add(new ExceptionFilter(exceptionHandler));
-    ctx.getFilters().add(new RequestPreparationFilter(spec, router, validator, bodyMappers));
-    ctx.setHandler(new DispatchHandler(handlers));
+    ctx.getFilters()
+        .add(new RequestPreparationFilter(spec, router, validator, bodyMappers, decorators));
+    ctx.setHandler(new DispatchHandler(handlers, interceptors));
 
     for (Map.Entry<String, HttpHandler> e : extras.entrySet()) {
       HttpContext extraCtx = httpServer.createContext(e.getKey());
@@ -118,6 +123,8 @@ public static final class Builder {
     private Spec spec;
     private final LinkedHashMap<String, TypeMapper> bodyMappers = new LinkedHashMap<>();
     private Map<String, RequestHandler> handlers;
+    private final List<ResponseDecorator> decorators = new ArrayList<>();
+    private final List<RequestInterceptor> interceptors = new ArrayList<>();
     private ExceptionHandler exceptionHandler;
     private int port = DEFAULT_PORT;
     private int shutdownTimeoutSeconds = 0;
@@ -142,6 +149,25 @@ public Builder handlers(Map<String, RequestHandler> handlers) {
       return this;
     }
 
+    /**
+     * Registers a {@link ResponseDecorator} that mutates the {@link ResponseBuilder} returned by
+     * {@link Request#respond(int)} before the handler receives it. Decorators run in registration
+     * order; handler-supplied headers override decorator-supplied ones.
+     */
+    public Builder responseDecorator(ResponseDecorator decorator) {
+      decorators.add(requireNonNull(decorator, "decorator must not be null"));
+      return this;
+    }
+
+    /**
+     * Registers a {@link RequestInterceptor} that wraps the handler invocation. Interceptors run in
+     * registration order; the first registered is the outermost.
+     */
+    public Builder interceptor(RequestInterceptor interceptor) {
+      interceptors.add(requireNonNull(interceptor, "interceptor must not be null"));
+      return this;
+    }
+
     public Builder exceptionHandler(ExceptionHandler exceptionHandler) {
       this.exceptionHandler = exceptionHandler;
       return this;
@@ -188,7 +214,15 @@ public OpenApiServer build() throws IOException {
       }
       Map<String, TypeMapper> resolved = resolveBodyMappers(bodyMappers);
       return new OpenApiServer(
-          spec, resolved, handlers, exceptionHandler, port, extras, shutdownTimeoutSeconds);
+          spec,
+          resolved,
+          handlers,
+          decorators,
+          interceptors,
+          exceptionHandler,
+          port,
+          extras,
+          shutdownTimeoutSeconds);
     }
 
     private static Map<String, TypeMapper> resolveBodyMappers(

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

@@ -5,6 +5,7 @@
 import java.net.URLDecoder;
 import java.nio.charset.StandardCharsets;
 import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
 
 /**
@@ -19,6 +20,7 @@ public final class Request {
   private final String operationId;
   private final Map<String, String> pathParameters;
   private final Map<String, TypeMapper> bodyMappers;
+  private final List<ResponseDecorator> decorators;
   private Map<String, String> queryParamCache;
   private boolean responseSent;
 
@@ -28,13 +30,15 @@ public Request(
       Object parsed,
       String operationId,
       Map<String, String> pathParameters,
-      Map<String, TypeMapper> bodyMappers) {
+      Map<String, TypeMapper> bodyMappers,
+      List<ResponseDecorator> decorators) {
     this.exchange = exchange;
     this.body = body;
     this.parsed = parsed;
     this.operationId = operationId;
     this.pathParameters = pathParameters;
     this.bodyMappers = bodyMappers;
+    this.decorators = List.copyOf(decorators);
   }
 
   public byte[] bytes() {
@@ -104,6 +108,11 @@ public ResponseBuilder respond(int status) {
     if (responseSent) {
       throw new IllegalStateException("Response already sent");
     }
-    return new DefaultResponseBuilder(exchange, status, bodyMappers, () -> responseSent = true);
+    ResponseBuilder builder =
+        new DefaultResponseBuilder(exchange, status, bodyMappers, () -> responseSent = true);
+    for (ResponseDecorator decorator : decorators) {
+      decorator.decorate(this, builder);
+    }
+    return builder;
   }
 }

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

@@ -0,0 +1,24 @@
+package com.retailsvc.http;
+
+import java.io.IOException;
+
+/**
+ * Wraps the {@link RequestHandler} invocation. Use for {@link ScopedValue} bindings, MDC, tracing,
+ * authentication, or any other concern that should run uniformly around every handler.
+ *
+ * <p>Interceptors compose in registration order: the first registered runs outermost. Each
+ * interceptor must call {@link Continuation#proceed()} to invoke the next interceptor (or the
+ * handler, when last). Exceptions propagate to the library's standard {@code ExceptionFilter} and
+ * {@code ExceptionHandler} pipeline.
+ */
+@FunctionalInterface
+public interface RequestInterceptor {
+
+  void around(Request request, Continuation next) throws IOException;
+
+  /** Continues the chain — calls the next interceptor, or the handler if this is the last one. */
+  @FunctionalInterface
+  interface Continuation {
+    void proceed() throws IOException;
+  }
+}

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

@@ -0,0 +1,14 @@
+package com.retailsvc.http;
+
+/**
+ * Mutates the {@link ResponseBuilder} returned by {@link Request#respond(int)} before the handler
+ * receives it. Decorators run in registration order. They may set headers (including {@code
+ * Content-Type}) but must not call a terminal method — terminals belong to the handler.
+ *
+ * <p>Decorators fire before the handler runs, so any headers the handler sets via the returned
+ * builder override decorator-supplied values.
+ */
+@FunctionalInterface
+public interface ResponseDecorator {
+  void decorate(Request request, ResponseBuilder builder);
+}

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

@@ -3,19 +3,24 @@
 import com.retailsvc.http.MissingOperationHandlerException;
 import com.retailsvc.http.Request;
 import com.retailsvc.http.RequestHandler;
+import com.retailsvc.http.RequestInterceptor;
 import com.sun.net.httpserver.HttpExchange;
 import com.sun.net.httpserver.HttpHandler;
 import java.io.IOException;
+import java.util.List;
 import java.util.Map;
 
 public final class DispatchHandler implements HttpHandler {
 
   public static final ScopedValue<Request> CURRENT = ScopedValue.newInstance();
 
   private final Map<String, RequestHandler> handlers;
+  private final List<RequestInterceptor> interceptors;
 
-  public DispatchHandler(Map<String, RequestHandler> handlers) {
+  public DispatchHandler(
+      Map<String, RequestHandler> handlers, List<RequestInterceptor> interceptors) {
     this.handlers = Map.copyOf(handlers);
+    this.interceptors = List.copyOf(interceptors);
   }
 
   @Override
@@ -25,6 +30,14 @@ public void handle(HttpExchange exchange) throws IOException {
     if (h == null) {
       throw new MissingOperationHandlerException(request.operationId());
     }
-    h.handle(request);
+    invoke(0, request, h);
+  }
+
+  private void invoke(int idx, Request request, RequestHandler handler) throws IOException {
+    if (idx == interceptors.size()) {
+      handler.handle(request);
+      return;
+    }
+    interceptors.get(idx).around(request, () -> invoke(idx + 1, request, handler));
   }
 }

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

@@ -3,6 +3,7 @@
 import com.retailsvc.http.MethodNotAllowedException;
 import com.retailsvc.http.NotFoundException;
 import com.retailsvc.http.Request;
+import com.retailsvc.http.ResponseDecorator;
 import com.retailsvc.http.TypeMapper;
 import com.retailsvc.http.ValidationException;
 import com.retailsvc.http.spec.HttpMethod;
@@ -17,6 +18,7 @@
 import com.sun.net.httpserver.HttpExchange;
 import java.io.IOException;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Locale;
 import java.util.Map;
 import java.util.Optional;
@@ -29,13 +31,19 @@ public final class RequestPreparationFilter extends Filter {
   private final Router router;
   private final Validator validator;
   private final Map<String, TypeMapper> bodyMappers;
+  private final List<ResponseDecorator> decorators;
 
   public RequestPreparationFilter(
-      Spec spec, Router router, Validator validator, Map<String, TypeMapper> bodyMappers) {
+      Spec spec,
+      Router router,
+      Validator validator,
+      Map<String, TypeMapper> bodyMappers,
+      List<ResponseDecorator> decorators) {
     this.spec = spec;
     this.router = router;
     this.validator = validator;
     this.bodyMappers = Map.copyOf(bodyMappers);
+    this.decorators = List.copyOf(decorators);
   }
 
   @Override
@@ -66,7 +74,13 @@ public void doFilter(HttpExchange exchange, Chain chain) throws IOException {
 
     Request request =
         new Request(
-            exchange, body, parsedBody, op.operationId(), match.pathParameters(), bodyMappers);
+            exchange,
+            body,
+            parsedBody,
+            op.operationId(),
+            match.pathParameters(),
+            bodyMappers,
+            decorators);
 
     try {
       ScopedValue.where(DispatchHandler.CURRENT, request)