feat: Let callers register their own content codings

Adds ContentCoding, a public extension point for HTTP content codings,
so a service can offer zstd, brotli or deflate without this library
taking a compression dependency. gzip becomes the built-in instance of
the same interface.

Codings are registered on the builder with contentCoding, or with
requestContentCoding / responseContentCoding for one direction only; a
request coded with a response-only coding is answered 415. The client's
q-weights pick the response coding, and on a tie registered codings win
over gzip in registration order.

The interface wraps streams rather than whole bodies. That keeps the
decompression cap in the library: the server reads at most
maxDecompressedRequestBytes from whatever stream a coding returns, so a
lazy decoder is bounded without doing anything itself.

Registration fails fast on reserved tokens (gzip, x-gzip, identity, *),
on duplicates within a direction, and on anything that is not a
lower-case RFC 9110 token. Tokens are written verbatim into response
headers, so that check is what keeps them free of injected CR/LF.

Author: thced

CLAUDE.md

@@ -28,11 +28,11 @@ Request flow when `OpenApiServer` boots (`src/main/java/com/retailsvc/http/OpenA
 1. `HttpServer` is created on a port with a virtual-thread-per-task executor.
 2. One `HttpContext` is registered per spec binding at `spec.basePath()` (the first `servers[].url` path from the OpenAPI doc). Unless a binding owns `/`, a catch-all `/` context serves extra routes via `ExtrasRouter` and 404s everything else; `ExceptionFilter` wraps that context only.
 3. On a binding context, two filters run in order, then the handler:
-    - `RequestPreparationFilter` — reads the request body through `RequestBodyReader` (which inflates a gzip `Content-Encoding` under a size cap), resolves the route, runs OpenAPI parameter + body validation via `DefaultValidator`, and binds the resulting `Request` into the `DispatchHandler.CURRENT` scoped value. It renders its own failures through the `ExceptionHandler` rather than relying on `ExceptionFilter`.
+    - `RequestPreparationFilter` — reads the request body through `RequestBodyReader` (which decodes a registered `Content-Encoding` — gzip is built in — under a size cap), resolves the route, runs OpenAPI parameter + body validation via `DefaultValidator`, and binds the resulting `Request` into the `DispatchHandler.CURRENT` scoped value. It renders its own failures through the `ExceptionHandler` rather than relying on `ExceptionFilter`.
     - `SecurityFilter` — enforces the spec's `securitySchemes` / `security`, re-binding the `Request` with resolved principals. It writes its 401/403 responses straight to the exchange.
     - `DispatchHandler` — looks up the `RequestHandler` registered for the resolved `operationId` in the user-supplied map and invokes it, applying interceptors and response decorators. Handler coverage is verified at boot, so the lookup never returns `null`.
 
-Every response except `SecurityFilter`'s rejections is written by `ResponseRenderer`, which is also where response gzip coding is applied.
+Every response except `SecurityFilter`'s rejections is written by `ResponseRenderer`, which is also where response content coding is applied.
 
 Key abstractions:
 
@@ -42,7 +42,7 @@ Key abstractions:
 - `com.retailsvc.http.internal.Router` — two indexes: exact path map and templated path list. Resolves `operationId` + extracted path variables for each request.
 - `TypeMapper` — per-media-type request parsing and response writing; registered via `Builder.bodyMapper(...)`, with `GsonTypeMapper` auto-registered when Gson is on the classpath.
 - `com.retailsvc.http.Request` — an immutable record-like carrier built from primitives (body bytes, path parameters, raw query string, a header lookup function), never the `HttpExchange`. `bytes()` returns the decoded body, `parsed()` the object produced by the `TypeMapper`.
-- `com.retailsvc.http.internal.RequestBodyReader` / `ResponseCompression` — inbound and outbound gzip. See the README's "Content encoding" section for the policy.
+- `com.retailsvc.http.ContentCoding` — a pluggable HTTP content coding. gzip is built in (`internal/GzipCoding`); callers register others on the builder, held per direction in `internal/ContentCodings`. `RequestBodyReader` decodes requests under the size cap and `ResponseRenderer` codes responses. See the README's "Content encoding" section for the policy.
 
 ## Conventions
 

README.md

@@ -468,8 +468,8 @@ gzip is handled in both directions, with no configuration required.
 
 **Requests.** A body sent with `Content-Encoding: gzip` is inflated before OpenAPI validation runs,
 so the validator, your `TypeMapper` and your handler all see plain bytes. `identity` is accepted as
-the no-op it is. Any other coding — `br`, `deflate`, or two codings stacked — is rejected with
-`415 Unsupported Media Type`, and a corrupt or truncated gzip stream with `400 Bad Request`.
+the no-op it is. A coding the server has not registered — `br`, say — or two codings stacked is
+rejected with `415 Unsupported Media Type`, and a corrupt or truncated body with `400 Bad Request`.
 
 Once a body is inflated it no longer matches the headers that described it, so `Content-Encoding` is
 hidden from `Request.header(...)` and `Content-Length` reports the inflated size.
@@ -484,8 +484,8 @@ OpenApiServer.builder()
     .build();
 ```
 
-Note this bounds the *inflated* size of a gzip body. It is not a request size limit — a body that
-arrives uncompressed is read in full, as it always has been.
+Note this bounds the *inflated* size of a coded body, whatever the coding. It is not a request size
+limit — a body that arrives uncompressed is read in full, as it always has been.
 
 **Responses.** A body is gzipped when the client sends `Accept-Encoding: gzip`, the media type is
 text-shaped (`text/*`, `application/json`, `application/xml`, `application/yaml`, and the `+json` /
@@ -506,18 +506,34 @@ threshold above anything this server returns.
 
 `Vary: Accept-Encoding` is set whenever a body *could* have been coded, not only when it was, so
 shared caches keep the two forms apart. It is merged into any `Vary` your handler already set.
-A handler that sets its own `Content-Encoding` is left alone, and so is a payload gzip fails to
-shrink. Statuses that carry no content never get a coding.
+A handler that sets its own `Content-Encoding` is left alone, and so is a payload the coding
+fails to shrink. Statuses that carry no content never get a coding.
 
-Streamed responses (`Response.stream(...)`) are deflated as they are written. A length declared by
+Streamed responses (`Response.stream(...)`) are coded as they are written. A length declared by
 the sized overload describes the uncoded body, so a coded stream goes out chunked; a stream of
 unknown length is coded regardless of the threshold, since measuring it would defeat streaming it.
 For the same reason a `HEAD` whose `GET` would be compressed omits `Content-Length` rather than
 advertising the uncoded length.
 
+**Other codings.** The library ships gzip only, and so carries no compression dependency. To offer
+another, implement `ContentCoding` and register it:
+
+```java
+OpenApiServer.builder()
+    .spec(spec)
+    .handlers(handlers)
+    .contentCoding(new ZstdCoding())  // your ContentCoding implementation
+    .build();
+```
+
+The client's weights pick the coding; on a tie, registered codings win over gzip, in registration
+order. `decode` and `encode` wrap streams rather than whole bodies, so a decoder that reads lazily
+is held to `maxDecompressedRequestBytes` without doing anything itself. `requestContentCoding` and
+`responseContentCoding` register one direction only; a request coded with a response-only coding
+gets 415. Tokens must be lower-case, and `gzip`, `x-gzip`, `identity` and `*` are reserved.
+
 **Not in this release** (each can land later without breaking the API):
 
-- brotli, zstd and `deflate`, in either direction
 - the `Accept-Encoding` response header RFC 9110 recommends alongside a 415
 - compression of the `401`/`403` bodies produced by security scheme enforcement — those bypass the
   renderer and are well under any sensible threshold

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

@@ -0,0 +1,53 @@
+package com.retailsvc.http;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.util.Set;
+
+/**
+ * An HTTP content coding (RFC 9110 §8.4.1) that the server decodes on requests and applies to
+ * responses. The library ships {@code gzip}; anything else — {@code zstd}, {@code br}, {@code
+ * deflate} — is supplied by the caller and registered on {@link
+ * OpenApiServer.Builder#contentCoding(ContentCoding)}, which keeps this library free of any
+ * compression dependency.
+ *
+ * <p>One instance serves every request, so implementations must be immutable and safe for
+ * concurrent use.
+ *
+ * <p>Both methods wrap a stream rather than convert a whole body: return a stream that codes as it
+ * is read or written. For {@link #decode} this is what bounds the work — the server reads at most
+ * {@code maxDecompressedRequestBytes} from the stream you return, so a lazy decoder is protected
+ * from decompression bombs without doing anything, while one that expands the whole body up front
+ * has already spent what that limit exists to protect.
+ */
+public interface ContentCoding {
+
+  /**
+   * The {@code Content-Encoding} and {@code Accept-Encoding} token, such as {@code zstd}. Must be a
+   * lower-case RFC 9110 token; {@code gzip}, {@code x-gzip}, {@code identity} and {@code *} are
+   * reserved.
+   */
+  String token();
+
+  /**
+   * Further tokens that mean this same coding on the wire, such as a legacy {@code x-} name.
+   * Recognised on input only; a coded response always announces {@link #token()}.
+   */
+  default Set<String> aliases() {
+    return Set.of();
+  }
+
+  /**
+   * Wraps a coded request body in a stream of the decoded bytes. The argument is always held in
+   * memory, so a read failure means the body is malformed: throw {@link IOException} and the server
+   * answers 400. Any other exception is treated as a fault in the coding.
+   */
+  InputStream decode(InputStream coded) throws IOException;
+
+  /**
+   * Wraps a response stream so that everything written to the returned stream reaches {@code sink}
+   * coded. Closing the returned stream must finish the coded payload and close {@code sink}.
+   */
+  OutputStream encode(OutputStream sink) throws IOException;
+}

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

@@ -4,6 +4,7 @@
 import static java.util.Objects.requireNonNull;
 import static java.util.concurrent.Executors.newThreadPerTaskExecutor;
 
+import com.retailsvc.http.internal.ContentCodings;
 import com.retailsvc.http.internal.DispatchHandler;
 import com.retailsvc.http.internal.ExceptionFilter;
 import com.retailsvc.http.internal.ExtrasRouter;
@@ -247,6 +248,8 @@ public static final class Builder {
     private boolean externalAuth = false;
     private long maxDecompressedRequestBytes = RequestBodyReader.DEFAULT_MAX_DECOMPRESSED_BYTES;
     private long minCompressibleResponseBytes = ResponseRenderer.DEFAULT_MIN_COMPRESSIBLE_BYTES;
+    private final List<ContentCoding> requestCodings = new ArrayList<>();
+    private final List<ContentCoding> responseCodings = new ArrayList<>();
     private final List<SpecBinding> bindings = new ArrayList<>();
 
     private Builder() {}
@@ -424,6 +427,45 @@ public Builder minCompressibleResponseBytes(long minCompressibleResponseBytes) {
       return this;
     }
 
+    /**
+     * Registers a content coding the server decodes on requests and applies to responses, alongside
+     * the built-in gzip. When a client weights several codings equally, the ones registered here
+     * win over gzip, in registration order; otherwise the client's weights decide. A decoded body
+     * is still held to {@link #maxDecompressedRequestBytes(long)}.
+     *
+     * @throws IllegalArgumentException if a token or alias is not a lower-case RFC 9110 token, or
+     *     is one of the reserved {@code gzip}, {@code x-gzip}, {@code identity} or {@code *}
+     * @throws IllegalStateException if a token or alias is already registered in either direction
+     */
+    public Builder contentCoding(ContentCoding coding) {
+      ContentCodings.requireRegistrable(coding, requestCodings);
+      ContentCodings.requireRegistrable(coding, responseCodings);
+      requestCodings.add(coding);
+      responseCodings.add(coding);
+      return this;
+    }
+
+    /**
+     * Registers a coding the server only decodes on requests; responses never use it. Validated as
+     * for {@link #contentCoding(ContentCoding)}.
+     */
+    public Builder requestContentCoding(ContentCoding coding) {
+      ContentCodings.requireRegistrable(coding, requestCodings);
+      requestCodings.add(coding);
+      return this;
+    }
+
+    /**
+     * Registers a coding the server only applies to responses. A request coded with it is answered
+     * 415, which keeps a decoder you have no use for off the request path. Validated as for {@link
+     * #contentCoding(ContentCoding)}.
+     */
+    public Builder responseContentCoding(ContentCoding coding) {
+      ContentCodings.requireRegistrable(coding, responseCodings);
+      responseCodings.add(coding);
+      return this;
+    }
+
     /**
      * Sets the default drain timeout used by {@link OpenApiServer#close()}. {@code 0} (the default)
      * stops immediately; positive values wait up to that many seconds for in-flight exchanges to
@@ -463,6 +505,7 @@ public OpenApiServer build() throws IOException {
       Map<String, TypeMapper> resolved = resolveBodyMappers(bodyMappers);
       ExceptionHandler effectiveExceptionHandler =
           exceptionHandler != null ? exceptionHandler : Handlers.defaultExceptionHandler();
+      ContentCodings codings = ContentCodings.of(requestCodings, responseCodings);
       HandlerConfig handlerConfig =
           new HandlerConfig(
               interceptors,
@@ -471,8 +514,8 @@ public OpenApiServer build() throws IOException {
               extras,
               externalAuth,
               List.copyOf(afterHooks),
-              new RequestBodyReader(maxDecompressedRequestBytes),
-              new ResponseRenderer(resolved, minCompressibleResponseBytes));
+              new RequestBodyReader(maxDecompressedRequestBytes, codings.decoders()),
+              new ResponseRenderer(resolved, minCompressibleResponseBytes, codings.encoders()));
       int resolvedPort = resolvePort();
       SSLContext sslContext =
           httpsCertChain != null ? PemSslContext.load(httpsCertChain, httpsPrivateKey) : null;

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

@@ -1,51 +1,87 @@
 package com.retailsvc.http.internal;
 
+import com.retailsvc.http.ContentCoding;
+import java.util.HashMap;
+import java.util.List;
 import java.util.Locale;
+import java.util.Map;
+import java.util.Optional;
 
 /** Parses {@code Accept-Encoding} request header values (RFC 9110 §12.5.3). */
 public final class AcceptEncodingHeader {
 
+  private static final double DEFAULT_WEIGHT = 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.
+   * Chooses the coding the client weights highest among {@code candidates}, which arrive in server
+   * preference order, so the earlier candidate wins a tie. Empty means send the body uncoded — also
+   * the answer for an absent header, since not asking for a coding is not the same as accepting
+   * any.
+   *
+   * <p>A coding the client names outranks its {@code *} entry, so {@code gzip;q=0} refuses gzip
+   * even beside a positive wildcard. A weight of zero refuses, and a name listed twice takes its
+   * higher weight.
    */
-  public static boolean acceptsGzip(String header) {
-    if (header == null) {
-      return false;
+  public static Optional<ContentCoding> select(String header, List<ContentCoding> candidates) {
+    if (header == null || candidates.isEmpty()) {
+      return Optional.empty();
+    }
+    Map<String, Double> weights = weights(header);
+    ContentCoding best = null;
+    double bestWeight = 0;
+    for (ContentCoding candidate : candidates) {
+      double weight = weightOf(candidate, weights);
+      if (weight > bestWeight) {
+        best = candidate;
+        bestWeight = weight;
+      }
     }
-    boolean gzipSeen = false;
-    boolean gzipAccepted = false;
-    boolean wildcardAccepted = false;
+    return Optional.ofNullable(best);
+  }
+
+  /** The weight the client gave each coding it listed, keeping the higher for a repeated one. */
+  private static Map<String, Double> weights(String header) {
+    Map<String, Double> weights = new HashMap<>();
     for (String token : header.split(",")) {
       int semi = token.indexOf(';');
       String coding = (semi < 0 ? token : token.substring(0, semi)).trim().toLowerCase(Locale.ROOT);
-      boolean accepted = positiveWeight(token);
-      if ("gzip".equals(coding) || "x-gzip".equals(coding)) {
-        gzipSeen = true;
-        gzipAccepted |= accepted;
-      } else if ("*".equals(coding)) {
-        wildcardAccepted |= accepted;
+      if (!coding.isEmpty()) {
+        weights.merge(coding, weight(token), Math::max);
       }
     }
-    return gzipSeen ? gzipAccepted : wildcardAccepted;
+    return weights;
+  }
+
+  /** A candidate's weight from its own name or an alias, and only failing both, the wildcard. */
+  private static double weightOf(ContentCoding coding, Map<String, Double> weights) {
+    Double listed = weights.get(coding.token());
+    for (String alias : coding.aliases()) {
+      Double aliased = weights.get(alias);
+      if (aliased != null && (listed == null || aliased > listed)) {
+        listed = aliased;
+      }
+    }
+    if (listed != null) {
+      return listed;
+    }
+    return weights.getOrDefault("*", 0.0);
   }
 
   /**
-   * Whether the token's {@code q} weight admits the coding. An absent or unparsable weight reads as
-   * the default 1.0 — a malformed header should not silently disable compression.
+   * Reads the {@code q} weight from a token. An absent or unparsable weight reads as the default
+   * 1.0 — a malformed header should not silently disable compression.
    */
-  private static boolean positiveWeight(String token) {
+  private static double weight(String token) {
     String weight = ContentTypeHeader.parameter(token, "q").orElse(null);
     if (weight == null) {
-      return true;
+      return DEFAULT_WEIGHT;
     }
     try {
-      return Double.parseDouble(weight) > 0;
+      return Double.parseDouble(weight);
     } catch (NumberFormatException _) {
-      return true;
+      return DEFAULT_WEIGHT;
     }
   }
 }