docs: Document gzip content encoding

Adds a "Content encoding" section under Server configuration covering
both directions, the two limits and their defaults, the media types that
qualify, and the deliberate non-goals. Adds Caveats entries for the two
consequences a handler author can be surprised by: a strong ETag now
spans two byte streams, and throwing mid-stream produces a valid gzip
trailer over a short body rather than a framing error.

Also corrects the architecture notes in CLAUDE.md, which still described
a filter chain that no longer exists — ExceptionFilter on the spec
context, the request body stashed as an exchange attribute, and a static
`Request.bytes(exchange)` helper — and mentioned neither SecurityFilter
nor ExtrasRouter.

Author: thced

CLAUDE.md

@@ -26,20 +26,23 @@ Java 25 is required (see `.java-version`). The server uses thread-per-request wi
 Request flow when `OpenApiServer` boots (`src/main/java/com/retailsvc/http/OpenApiServer.java`):
 
 1. `HttpServer` is created on a port with a virtual-thread-per-task executor.
-2. A single `HttpContext` is registered at `spec.basePath()` (the first `servers[].url` path from the OpenAPI doc). A catch-all `/` context returns 404.
-3. Three filters run in order on every request:
-    - `ExceptionFilter` — wraps the chain; delegates uncaught exceptions to the user-supplied `ExceptionHandler` (default in `Handlers`).
-    - `RequestPreparationFilter` — reads the raw request body, stashes it as an exchange attribute, runs OpenAPI parameter + body validation via `DefaultValidator`, and stores the resolved `operationId` on the exchange.
-    - `DispatchHandler` — looks up the `HttpHandler` registered for that `operationId` in the user-supplied map and invokes it. Handler coverage is verified at boot, so the lookup never returns `null`.
+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`.
+    - `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.
 
 Key abstractions:
 
 - `com.retailsvc.http.spec.Spec` — parsed from a consumer-supplied `Map<String, Object>` via `Spec.from(raw)`. No JSON library dependency in the library itself; callers use Gson, Jackson, SnakeYAML, etc. to produce the map.
 - Sealed `com.retailsvc.http.spec.schema.Schema` interface with per-kind records (`StringSchema`, `NumberSchema`, `IntegerSchema`, `ArraySchema`, `ObjectSchema`, `BooleanSchema`, `NullSchema`, `AnyOfSchema`, `AllOfSchema`, `OneOfSchema`). Pattern-match dispatch eliminates instanceof chains.
-- `com.retailsvc.http.validate.DefaultValidator` — single class using `switch` pattern-match over `Schema` subtypes. Validation failures produce RFC 7807 `application/problem+json` 400 responses.
+- `com.retailsvc.http.validate.DefaultValidator` — single class using `switch` pattern-match over `Schema` subtypes. Validation failures produce RFC 9457 `application/problem+json` 400 responses.
 - `com.retailsvc.http.internal.Router` — two indexes: exact path map and templated path list. Resolves `operationId` + extracted path variables for each request.
-- `JsonMapper` — `@FunctionalInterface`; single method `Object mapFrom(byte[])`. Callers supply a lambda (see README).
-- `com.retailsvc.http.Request` — static helper; `Request.bytes(exchange)` returns raw body bytes, `Request.parsed(exchange)` returns the `Object` produced by the `JsonMapper`.
+- `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.
 
 ## Conventions
 

README.md

@@ -23,6 +23,7 @@ endpoints declared in an OpenAPI 3.1.x specification. Handlers are pure function
 - [Body parsers and response writers](#body-parsers-and-response-writers)
 - [Server configuration](#server-configuration)
   - [HTTPS](#https)
+  - [Content encoding](#content-encoding)
 - [Interceptors and response decorators](#interceptors-and-response-decorators)
 - [After-response hooks](#after-response-hooks)
 - [Security](#security)
@@ -48,6 +49,8 @@ endpoints declared in an OpenAPI 3.1.x specification. Handlers are pure function
 - OpenAPI `securitySchemes` and `security` enforcement (`apiKey`, `http bearer`, `http basic`),
   with an opt-out for sidecar / gateway authentication
 - RFC 9457 `application/problem+json` validation errors with an `errors[]` array of JSON-Pointers to the failing locations
+- Transparent gzip: request bodies are inflated under a zip-bomb ceiling, responses are compressed
+  when the client accepts it and the payload is worth it
 - Built on the JDK's native `HttpServer` with thread-per-request behaviour using virtual threads
 
 ## Maven artifact
@@ -459,6 +462,67 @@ explicitly — it isn't signed by a public CA.
 - TLS protocol / cipher overrides (JDK defaults apply: TLS 1.2 and 1.3)
 - Serving HTTP and HTTPS from one `OpenApiServer` instance
 
+### Content encoding
+
+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`.
+
+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.
+
+Inflation runs under a ceiling, because a few compressed kilobytes can expand into gigabytes:
+
+```java
+OpenApiServer.builder()
+    .spec(spec)
+    .handlers(handlers)
+    .maxDecompressedRequestBytes(32 * 1024 * 1024)  // default 10 MiB; over it, 413
+    .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.
+
+**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` /
+`+xml` / `+yaml` structured suffixes), and it is at least 1 KiB. Below that the coding costs more
+than it saves; `application/octet-stream`, images and other already-compressed media are never
+coded, and neither is `text/event-stream`, which has to stay unbuffered.
+
+```java
+OpenApiServer.builder()
+    .spec(spec)
+    .handlers(handlers)
+    .minimumGzipResponseBytes(4096)  // default 1024; 0 compresses everything compressible
+    .build();
+```
+
+There is no on/off flag. If a proxy in front of you already terminates compression, set the
+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.
+
+Streamed responses (`Response.stream(...)`) are deflated 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.
+
+**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
+- per-route or per-operation opt-out
+
 ### Graceful shutdown
 
 `OpenApiServer` exposes `stop(int delaySeconds)` for explicit shutdown that waits up to the given
@@ -1218,6 +1282,12 @@ A few things worth keeping in mind when reading this:
   JDK `HttpExchange`. A future enhancement could plug in a higher-throughput backend (Jetty,
   Helidon Níma, Netty) by writing a new adapter behind `com.retailsvc.http.internal` while
   leaving handlers untouched.
+- **gzip changes what an `ETag` identifies.** The library sets none, but a handler that sets a
+  strong `ETag` would use one entity tag for both the coded and uncoded forms of a body. Use a weak
+  tag (`W/"..."`), or set `Content-Encoding` yourself to opt that response out of compression.
+- **A handler that throws mid-stream yields a valid gzip trailer.** Closing the coded stream
+  finishes the gzip member, so a client sees a complete-looking short body rather than the framing
+  error a truncated chunked response would have produced.
 - **Per-request state uses `ScopedValue`** (Java 25, JEP 506). 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.

docs/plans/dynamic-discovering-piglet.md

@@ -304,15 +304,15 @@ as it completes.
 
 ### Task 6 — docs
 
-- [ ] **Step 11** README: `### Request decompression` and `### Response compression` under
+- [x] **Step 11** README: `### Request decompression` and `### Response compression` under
       `## Server configuration`, a TOC entry, a `## Highlights` bullet, and a **"Not in this
       release"** list matching the HTTPS section's convention — brotli/deflate/zstd,
       `Accept-Encoding` on 415 responses (RFC 9110 §15.5.16 SHOULD; `BadRequestException` carries no
       headers), compression of `SecurityFilter` 401/403 bodies, per-route opt-out. Plus `Caveats`
       bullets: the cap bounds *inflated* bytes only and is not a request size limit; a strong `ETag`
       set by a handler now spans two byte streams; a handler that throws mid-stream yields a valid
       gzip trailer over truncated content rather than a framing error.
-- [ ] **Step 12** Correct the stale request-flow description in `CLAUDE.md` — it describes three
+- [x] **Step 12** Correct the stale request-flow description in `CLAUDE.md` — it describes three
       filters including `ExceptionFilter` on the spec context, exchange-attribute body stashing and
       a `Request.bytes(exchange)` static helper, none of which match the current code, and it
       mentions neither `SecurityFilter` nor `ExtrasRouter`.