How do nested routes (nest / path) and filter functions (filter / before / after / onError) work in WebMvc.fn?

## Nesting routes When many routes share a condition (usually a path prefix), repeating that predicate is noisy and error-prone. The builder provides: - **`nest(RequestPredicate, Consumer<Builder>)`** — the general nesting operator: every route defined in the consumer is implicitly ANDed with the outer predicate. - **`path(String pattern, Consumer<Builder>)`** — a shortcut for `nest(RequestPredicates.path(pattern), ...)`, the common case of a shared path prefix. ```java RouterFunctions.route() .path("/users", b -> b .GET("", handler::list) // GET /users .GET("/{id}", handler::get) // GET /users/{id} .POST("", handler::create)) // POST /users .build(); ``` Nesting can be **arbitrarily deep**, and you can nest on any predicate, not just paths — e.g. `nest(accept(APPLICATION_JSON), ...)` to scope routes to a content type. ## Filter functions — the four flavors Filters wrap handler invocation. Registered on the builder, they apply to **all routes defined at that level or below** (so a filter inside a `nest` is scoped to that nest only). 1. **`filter(HandlerFilterFunction<T,R>)`** — the general form. Signature: `R filter(ServerRequest request, HandlerFunction<T> next)`. You decide whether/when to call `next.handle(request)`, so you can run code **before and after**, modify inputs/outputs, or **short-circuit** by returning a response without calling `next` (e.g. reject unauthenticated requests). This is the analogue of a servlet `Filter` or `HandlerInterceptor`, scoped to routes. 2. **`before(Function<ServerRequest,ServerRequest>)`** — pre-processing that returns a (possibly new) `ServerRequest`. Because `ServerRequest` is immutable, you return a transformed copy (e.g. add an attribute). Good for logging or enriching the request. 3. **`after(BiFunction<ServerRequest,ServerResponse,ServerResponse>)`** — post-processing that receives the original request and the produced response and returns a (possibly new) response (e.g. add a header). Runs after the handler. 4. **`onError(Predicate<Throwable>, BiFunction<Throwable,ServerRequest,ServerResponse>)`** — error mapping: if the handler (or a downstream filter) throws a `Throwable` matching the predicate, the function produces a `ServerResponse` instead of propagating. A convenience overload takes an exception `Class`. ```java RouterFunctions.route() .path("/admin", b -> b .GET("/stats", handler::stats) .filter((request, next) -> { // scoped to /admin/** if (!isAuthorized(request)) { return ServerResponse.status(HttpStatus.FORBIDDEN).build(); } return next.handle(request); })) .before(req -> { log.info("{} {}", req.method(), req.uri()); return req; }) .after((req, res) -> ServerResponse.from(res).header("X-Trace", id()).build()) .onError(IllegalArgumentException.class, (e, req) -> ServerResponse.badRequest().body(e.getMessage())) .build(); ``` ## Ordering and composition semantics - Filters compose like nested wrappers. When multiple `filter`s are registered, they wrap in a defined order; conceptually the **last-registered filter is the outermost** wrapper around the handler in the Spring MVC functional builder. Because ordering can be subtle, keep filters at the level where their scope is clear (top-level for global, inside a `nest` for group-scoped). - `before` runs before the handler; `after` runs after; `onError` catches downstream throwables. A general `filter` can straddle all of these in one place. - Short-circuiting: only the general `filter` form (and `onError`) can produce a response *without* invoking the handler. `before`/`after` always let the handler run. ## When to use which - **Cross-cutting auth / rate-limit / short-circuit** → `filter` (needs to optionally skip the handler). - **Request enrichment / MDC / logging pre** → `before`. - **Response decoration / headers / logging post** → `after`. - **Turning exceptions into HTTP responses locally** → `onError`. - **Shared path or media-type grouping** → `nest` / `path`. ## Gotchas - `ServerRequest`/`ServerResponse` are immutable — `before`/`after` must **return** the transformed instance; mutating in place does nothing. Use `ServerResponse.from(existing)` to copy-and-modify. - Filter scope follows the builder structure: a filter placed *after* some routes and *inside* a nest still applies to the whole nest, not just routes below it — think in terms of the nest block, not textual position. - `onError` only catches throwables from routes it wraps; unhandled ones still fall through to the global `HandlerExceptionResolver` chain (e.g. `@ControllerAdvice`).