feat: Decompress gzip request bodies

Requests carrying `Content-Encoding: gzip` are now inflated before
OpenAPI body validation runs, so the validator, the type mappers and
handlers all see plain bytes.

Inflation runs through a counting loop under a hard cap (10 MiB) so a
small compressed payload cannot expand into an OOM. Exceeding the cap
yields 413, an unsupported coding yields 415, and a malformed or
truncated gzip stream yields 400 — all as problem+json. Only
ZipException and EOFException are converted; a genuine socket failure
stays an IOException and still renders 500.

Once inflated, the body no longer matches the request headers that
described it, so the handler's header view hides `Content-Encoding` and
reports the inflated `Content-Length`.

Author: thced

docs/plans/dynamic-discovering-piglet.md

@@ -9,6 +9,7 @@
 import com.retailsvc.http.internal.ExtrasRouter;
 import com.retailsvc.http.internal.FormTypeMapper;
 import com.retailsvc.http.internal.PemSslContext;
+import com.retailsvc.http.internal.RequestBodyReader;
 import com.retailsvc.http.internal.RequestPreparationFilter;
 import com.retailsvc.http.internal.ResponseRenderer;
 import com.retailsvc.http.internal.SecurityFilter;
@@ -93,9 +94,24 @@ record HandlerConfig(
     httpServer.setExecutor(newThreadPerTaskExecutor(ofVirtual().name("http-", 0).factory()));
 
     ResponseRenderer renderer = new ResponseRenderer(bodyMappers);
+    RequestBodyReader bodyReader =
+        new RequestBodyReader(RequestBodyReader.DEFAULT_MAX_DECOMPRESSED_BYTES);
     boolean anyBindingAtRoot =
-        wireBindings(httpServer, bindings, bodyMappers, handlerConfig, exceptionHandler, renderer);
-    wireExtras(httpServer, anyBindingAtRoot, handlerConfig.extras(), exceptionHandler, renderer);
+        wireBindings(
+            httpServer,
+            bindings,
+            bodyMappers,
+            handlerConfig,
+            exceptionHandler,
+            renderer,
+            bodyReader);
+    wireExtras(
+        httpServer,
+        anyBindingAtRoot,
+        handlerConfig.extras(),
+        exceptionHandler,
+        renderer,
+        bodyReader);
 
     httpServer.start();
     this.shutdownTimeoutSeconds = shutdownTimeoutSeconds;
@@ -119,13 +135,21 @@ private static boolean wireBindings(
       Map<String, TypeMapper> bodyMappers,
       HandlerConfig handlerConfig,
       ExceptionHandler exceptionHandler,
-      ResponseRenderer renderer) {
+      ResponseRenderer renderer,
+      RequestBodyReader bodyReader) {
     boolean anyBindingAtRoot = false;
     for (SpecBinding binding : bindings) {
       String basePath = Optional.ofNullable(binding.spec().basePath()).orElse("/");
       anyBindingAtRoot |= "/".equals(basePath);
       wireBinding(
-          httpServer, basePath, binding, bodyMappers, handlerConfig, exceptionHandler, renderer);
+          httpServer,
+          basePath,
+          binding,
+          bodyMappers,
+          handlerConfig,
+          exceptionHandler,
+          renderer,
+          bodyReader);
     }
     return anyBindingAtRoot;
   }
@@ -138,7 +162,8 @@ private static void wireBinding(
       Map<String, TypeMapper> bodyMappers,
       HandlerConfig handlerConfig,
       ExceptionHandler exceptionHandler,
-      ResponseRenderer renderer) {
+      ResponseRenderer renderer,
+      RequestBodyReader bodyReader) {
     Map<String, Operation> operationsById =
         binding.spec().operations().stream()
             .collect(Collectors.toUnmodifiableMap(Operation::operationId, op -> op));
@@ -152,7 +177,8 @@ private static void wireBinding(
                 bodyMappers,
                 exceptionHandler,
                 renderer,
-                handlerConfig.afterHooks()));
+                handlerConfig.afterHooks(),
+                bodyReader));
     ctx.getFilters()
         .add(
             new SecurityFilter(
@@ -174,15 +200,16 @@ private static void wireExtras(
       boolean anyBindingAtRoot,
       Map<String, RequestHandler> extras,
       ExceptionHandler exceptionHandler,
-      ResponseRenderer renderer) {
+      ResponseRenderer renderer,
+      RequestBodyReader bodyReader) {
     if (anyBindingAtRoot) {
       if (!extras.isEmpty()) {
         throw new IllegalStateException(
             "extras cannot be registered when a binding owns basePath '/'");
       }
       return;
     }
-    ExtrasRouter extrasRouter = new ExtrasRouter(extras, renderer);
+    ExtrasRouter extrasRouter = new ExtrasRouter(extras, renderer, bodyReader);
     HttpContext extrasCtx = httpServer.createContext("/", extrasRouter);
     extrasCtx.getFilters().add(new ExceptionFilter(exceptionHandler, renderer));
   }

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

@@ -0,0 +1,73 @@
+package com.retailsvc.http.internal;
+
+import java.util.Locale;
+
+/** Parses {@code Accept-Encoding} request header values (RFC 9110 §12.5.3). */
+public final class AcceptEncodingHeader {
+
+  private static final String GZIP = "gzip";
+  private static final String X_GZIP = "x-gzip";
+  private static final String WILDCARD = "*";
+  private static final String QUALITY = "q";
+  private static final double DEFAULT_QUALITY = 1.0;
+
+  private AcceptEncodingHeader() {}
+
+  /**
+   * Whether the client accepts a gzip-coded response. A {@code null}, blank, or unrelated header
+   * yields {@code false}. An explicit {@code gzip;q=0} is a refusal and outranks a positive
+   * wildcard; a wildcard applies only when gzip is not listed in its own right.
+   */
+  public static boolean acceptsGzip(String header) {
+    if (header == null) {
+      return false;
+    }
+    Boolean gzipAccepted = null;
+    Boolean wildcardAccepted = null;
+    for (String token : header.split(",")) {
+      String trimmed = token.trim();
+      if (trimmed.isEmpty()) {
+        continue;
+      }
+      int semi = trimmed.indexOf(';');
+      String coding =
+          (semi < 0 ? trimmed : trimmed.substring(0, semi)).trim().toLowerCase(Locale.ROOT);
+      boolean accepted = quality(semi < 0 ? null : trimmed.substring(semi + 1)) > 0;
+      if (GZIP.equals(coding) || X_GZIP.equals(coding)) {
+        gzipAccepted = gzipAccepted == null ? accepted : gzipAccepted || accepted;
+      } else if (WILDCARD.equals(coding)) {
+        wildcardAccepted = wildcardAccepted == null ? accepted : wildcardAccepted || accepted;
+      }
+    }
+    if (gzipAccepted != null) {
+      return gzipAccepted;
+    }
+    return wildcardAccepted != null && wildcardAccepted;
+  }
+
+  /**
+   * Reads the {@code q} weight from a token's parameter list. An absent or unparsable weight is
+   * read as the default 1.0 — a malformed header should not silently disable compression.
+   */
+  private static double quality(String parameters) {
+    if (parameters == null) {
+      return DEFAULT_QUALITY;
+    }
+    for (String parameter : parameters.split(";")) {
+      String trimmed = parameter.trim();
+      int equals = trimmed.indexOf('=');
+      if (equals <= 0) {
+        continue;
+      }
+      String name = trimmed.substring(0, equals).trim().toLowerCase(Locale.ROOT);
+      if (QUALITY.equals(name)) {
+        try {
+          return Double.parseDouble(trimmed.substring(equals + 1).trim());
+        } catch (NumberFormatException e) {
+          return DEFAULT_QUALITY;
+        }
+      }
+    }
+    return DEFAULT_QUALITY;
+  }
+}

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

@@ -0,0 +1,50 @@
+package com.retailsvc.http.internal;
+
+import java.util.Locale;
+
+/** Classifies a request {@code Content-Encoding} into the codings the server can decode. */
+public final class ContentEncodingHeader {
+
+  private static final String IDENTITY_CODING = "identity";
+  private static final String GZIP_CODING = "gzip";
+  private static final String X_GZIP_CODING = "x-gzip";
+
+  private ContentEncodingHeader() {}
+
+  /** The content coding applied to a request body. */
+  public enum Coding {
+    /** No coding, or the explicit {@code identity} no-op. */
+    NONE,
+    /** A single gzip coding. */
+    GZIP,
+    /** A coding this server cannot decode; the caller renders 415. */
+    UNSUPPORTED
+  }
+
+  /**
+   * Classifies the header value. {@code null}, blank and {@code identity} are all {@link
+   * Coding#NONE}; a single gzip coding — optionally alongside {@code identity} — is {@link
+   * Coding#GZIP}. Anything else, including two stacked codings, is {@link Coding#UNSUPPORTED}.
+   */
+  public static Coding parse(String header) {
+    if (header == null) {
+      return Coding.NONE;
+    }
+    Coding result = Coding.NONE;
+    for (String token : header.split(",")) {
+      String coding = token.trim().toLowerCase(Locale.ROOT);
+      if (coding.isEmpty() || IDENTITY_CODING.equals(coding)) {
+        continue;
+      }
+      if (result != Coding.NONE) {
+        return Coding.UNSUPPORTED;
+      }
+      if (GZIP_CODING.equals(coding) || X_GZIP_CODING.equals(coding)) {
+        result = Coding.GZIP;
+      } else {
+        return Coding.UNSUPPORTED;
+      }
+    }
+    return result;
+  }
+}

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

@@ -21,9 +21,12 @@ private record Entry(PathPattern pattern, RequestHandler handler) {}
   private final Map<String, RequestHandler> exact;
   private final List<Entry> wildcards;
   private final ResponseRenderer renderer;
+  private final RequestBodyReader bodyReader;
 
-  public ExtrasRouter(Map<String, RequestHandler> extras, ResponseRenderer renderer) {
+  public ExtrasRouter(
+      Map<String, RequestHandler> extras, ResponseRenderer renderer, RequestBodyReader bodyReader) {
     this.renderer = renderer;
+    this.bodyReader = bodyReader;
     Map<String, RequestHandler> exactBuilder = new LinkedHashMap<>();
     List<Entry> wildcardBuilder = new ArrayList<>();
     for (Map.Entry<String, RequestHandler> e : extras.entrySet()) {
@@ -55,18 +58,17 @@ public void handle(HttpExchange exchange) throws IOException {
       throw new NotFoundException(exchange.getRequestMethod() + " " + decoded);
     }
 
-    byte[] body = exchange.getRequestBody().readAllBytes();
+    RequestBodyReader.Body body = bodyReader.read(exchange);
     HttpMethod method = HttpMethod.parse(exchange.getRequestMethod());
-    var headers = exchange.getRequestHeaders();
     Request request =
         new Request(
-            body,
+            body.bytes(),
             null,
             null,
             null,
             Map.of(),
             exchange.getRequestURI().getRawQuery(),
-            headers::getFirst,
+            body.headerLookup(),
             Map.of(),
             method);
     Response response = hit.handle(request);

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

@@ -1,6 +1,7 @@
 package com.retailsvc.http.internal;
 
 import static java.net.HttpURLConnection.HTTP_BAD_REQUEST;
+import static java.net.HttpURLConnection.HTTP_ENTITY_TOO_LARGE;
 
 import com.retailsvc.http.BadRequestException;
 import com.retailsvc.http.validate.ValidationError;
@@ -79,27 +80,18 @@ private static int depth(String pointer) {
   }
 
   private static final Map<Integer, String> TITLES =
-      Map.of(
-          HTTP_BAD_REQUEST,
-          BAD_REQUEST,
-          401,
-          "Unauthorized",
-          403,
-          "Forbidden",
-          404,
-          "Not Found",
-          405,
-          "Method Not Allowed",
-          409,
-          "Conflict",
-          410,
-          "Gone",
-          412,
-          "Precondition Failed",
-          415,
-          "Unsupported Media Type",
-          422,
-          "Unprocessable Content");
+      Map.ofEntries(
+          Map.entry(HTTP_BAD_REQUEST, BAD_REQUEST),
+          Map.entry(401, "Unauthorized"),
+          Map.entry(403, "Forbidden"),
+          Map.entry(404, "Not Found"),
+          Map.entry(405, "Method Not Allowed"),
+          Map.entry(409, "Conflict"),
+          Map.entry(410, "Gone"),
+          Map.entry(412, "Precondition Failed"),
+          Map.entry(HTTP_ENTITY_TOO_LARGE, "Content Too Large"),
+          Map.entry(415, "Unsupported Media Type"),
+          Map.entry(422, "Unprocessable Content"));
 
   private static String titleFor(int status) {
     return TITLES.getOrDefault(status, BAD_REQUEST);