The reactive gateway runs on a small Netty event-loop thread pool. What are the consequences of blocking inside a filter, and how do you handle work that must block?

## The event-loop model Netty (via reactor-netty) runs on an **event loop**: a small, fixed pool of threads, by default about `Runtime.getRuntime().availableProcessors()` (one per core, sometimes ×2). Each thread runs a loop that reacts to socket-readiness events for *many* connections. The entire premise is that a thread never sits idle waiting — it processes a chunk of work for request A, then request B, then C, cycling as events arrive. This is what lets a few threads carry huge concurrency. ## Why blocking is catastrophic here The model only works if **no task blocks**. A blocking call parks the *whole* thread until it returns: - Blocking JDBC (`DataSource`/JPA), `Thread.sleep`, `Object.wait`, blocking `RestTemplate`, blocking file I/O, `future.get()`, or `mono.block()`. With ~8 event-loop threads, 8 concurrent blocking calls occupy *all* of them. Every other in-flight request — hundreds or thousands — is now stalled with **zero** threads to advance it. Throughput doesn't degrade gracefully; it falls off a cliff. On the servlet stack a blocking call just holds one of hundreds/thousands of worker threads; on the event loop it can take down the whole server. This asymmetry is the single most important operational gotcha of the reactive gateway. ## How to handle work that must run **Preference 1 — use non-blocking equivalents:** - HTTP: `WebClient` / reactor-netty `HttpClient` instead of `RestTemplate`. - DB: **R2DBC** (reactive drivers) instead of JDBC. - Redis/messaging: reactive clients (Lettuce reactive, reactive Kafka). **Preference 2 — offload unavoidable blocking to a separate scheduler:** ```java return Mono.fromCallable(() -> legacyBlockingCall()) // the blocking work .subscribeOn(Schedulers.boundedElastic()) // runs on a bounded elastic pool, NOT the event loop .flatMap(result -> chain.filter(exchange)); // resumes on the reactive chain ``` `Schedulers.boundedElastic()` is Reactor's pool for blocking/long-running tasks: it creates worker threads on demand up to a cap and reuses them, isolating blocking work so it can't starve the event loop. `subscribeOn` moves the subscription (and thus the blocking `fromCallable`) onto that pool. **Never do `.block()`** in a filter — it blocks the calling thread (often an event-loop thread) and is exactly the failure above. It also throws in some reactor-netty contexts precisely to prevent this. ## Detecting accidental blocking - **Reactor BlockHound:** an agent that instruments the JVM to throw when a blocking call happens on a non-blocking thread. Wire it into tests to catch regressions early. - Watch for latency that spikes non-linearly under load, or thread dumps showing event-loop threads parked in JDBC/socket reads. ## Gotchas - **Hidden blocking in libraries:** many 'convenient' libraries block internally (some auth/JWT libs, DNS lookups, logging appenders with blocking I/O, metrics exporters). Audit anything called in the hot path. - **CPU-heavy work also hurts:** a filter doing heavy CPU (large crypto, big JSON transform) monopolizes the loop just like blocking; offload to `boundedElastic` or `parallel` scheduler if significant. - **boundedElastic isn't a free pass:** it's bounded — flooding it with blocking work still queues and adds latency; it just protects the event loop. Heavy blocking workloads may mean the reactive gateway is the wrong tool (or use the MVC gateway variant). - **Logging/tracing MDC:** context can be lost across scheduler hops; use Reactor context propagation. ## When to worry Any custom `GlobalFilter`/`GatewayFilter` that touches a database, calls a blocking client, does synchronous file/network I/O, or heavy CPU. Plain routing with predicates/header filters is safe.