Skip to content
From Netty to Controller: How an HTTP Request Traverses Spring Boot's Web Stacks

From Netty to Controller: How an HTTP Request Traverses Spring Boot's Web Stacks

This article traces an HTTP request through Spring Boot's Servlet and reactive stacks, explaining how SpringApplication chooses between Tomcat and Netty, detailing Netty's event-loop decoding, Spring Cloud Gateway's routing and filtering, Tomcat's request processing to DispatcherServlet, and four common gateway-downstream issues including timeout alignment, header forwarding, thread-model mismatch, and unsafe retries.

Java Tech Workshop
Java Tech Workshop
Java Tech Workshop

1. Identify Which Stack You Are On

Spring Boot decides the web type in SpringApplication.deduceWebApplicationType() by scanning the classpath. Finding DispatcherServlet and ServletContext selects the Servlet stack (Tomcat, Jetty, Undertow). Only DispatcherHandler without Servlet classes selects the reactive stack (Netty via WebFlux). If both starters are present, Servlet wins and WebFlux auto-configuration is skipped — no Netty startup line appears in logs.

"Netty hands request to MVC" usually means one of three patterns:

Gateway pattern: Request hits Spring Cloud Gateway on Netty, which routes and filters, then uses Netty's HttpClient to make a new HTTP call to a downstream Tomcat running MVC. This is a real network hop across processes, not an in-JVM method call.

WebFlux on Netty: Controllers use familiar annotations ( @RestController, @GetMapping, @RequestBody) but from the reactive package. Return types become Mono or Flux; parameters use ServerWebExchange; HttpServletRequest does not exist here.

Custom Netty + Servlet bridge: Running a real DispatcherServlet on Netty requires a third-party bridge or custom ServletContext. MVC's contract assumes blocking I/O ( HttpServletRequest.getInputStream() blocks), so forcing it onto Netty sacrifices much of Netty's non-blocking advantage.

Check startup logs: Tomcat started on port means MVC; Netty started on port means WebFlux; neither means non-web or disabled port. Knowing the path tells you which logs to read, which thread dump to take, and which connection pool to tune. In cross-process setups, correlate gateway and downstream logs with a shared trace ID.

2. Netty: How Bytes Become an HttpRequest

Incoming connections hit NioServerSocketChannel; a single boss thread (default 1) accepts. Accepted NioSocketChannel registers to a worker EventLoop (default threads = NettyRuntime.availableProcessors() * 2, overridable via io.netty.eventLoopThreads). Each EventLoop owns one thread, one Selector, many channels — serial loop: select ready events, process I/O, run pipeline, drain task queue, repeat.

This design avoids locks per channel, but any blocking in the EventLoop stalls all its connections. Hard rule: never block in the EventLoop. Offload DB/remote calls to a separate business thread pool or go fully reactive.

EventLoopGroup boss = new NioEventLoopGroup(1);
EventLoopGroup worker = new NioEventLoopGroup(); // default CPU * 2
new ServerBootstrap()
    .group(boss, worker)
    .channel(NioServerSocketChannel.class)
    .childHandler(new ChannelInitializer<SocketChannel>() {
        @Override
        protected void initChannel(SocketChannel ch) {
            ch.pipeline()
                .addLast(new HttpServerCodec()) // request line 4096 / headers 8192 / chunk 8192
                .addLast(new HttpObjectAggregator(1024 * 1024))
                .addLast(new BusinessHandler());
        }
    })
    .option(ChannelOption.SO_BACKLOG, 1024)
    .childOption(ChannelOption.SO_KEEPALIVE, true)
    .bind(8080).sync();
HttpServerCodec

combines request decoder and response encoder. Decoder parses request line, headers, body chunks into three object types: request+headers, body content, last chunk. HttpObjectAggregator buffers them into a single FullHttpRequest. Default limits: request line 4096 bytes, headers 8192, chunk 8192. Large headers (JWT, trace context) need explicit larger values; otherwise some clients get 400 errors hard to reproduce locally.

TCP is a byte stream — HTTP uses Content-Length and chunked encoding for framing. Large POST bodies arrive in multiple chunks. Without aggregator, handler must type-check and reassemble manually. ByteBufs are pooled off-heap with reference counting. Subclassing SimpleChannelInboundHandler auto-releases; implementing ChannelInboundHandler directly requires manual release. Leaks show as rising off-heap memory while heap looks clean.

Keep-alive (HTTP/1.1 default) multiplexes requests per connection; decoder uses length/chunk boundaries to separate responses. Backpressure: when processing lags, disable auto-read ( channel.config().setAutoRead(false)), let kernel buffer fill, re-enable at high-water mark. Blocking models lack this — data piles in app memory.

Business handler skeleton:

public class BusinessHandler extends SimpleChannelInboundHandler<FullHttpRequest> {
    @Override
    protected void channelRead0(ChannelHandlerContext ctx, FullHttpRequest req) {
        String uri = req.uri();
        HttpMethod method = req.method();
        ByteBuf content = req.content(); // body here, framework releases after
        Object result = dispatch(uri, method, content);
        byte[] body = toJson(result);
        FullHttpResponse resp = new DefaultFullHttpResponse(
            HttpVersion.HTTP_1_1, HttpResponseStatus.OK,
            Unpooled.copiedBuffer(body));
        resp.headers().set(HttpHeaderNames.CONTENT_TYPE, "application/json");
        HttpUtil.setContentLength(resp, body.length);
        ctx.writeAndFlush(resp);
    }
}

This code combines what MVC splits into handler mapping, handler adapter, and message converters — but you must reimplement all edge cases yourself.

3. Gateway: Routing and Forwarding

Spring Cloud Gateway uses the reactive mapping system. Route predicates are evaluated in configuration order; first match wins. A broad Path=/api/** placed before specific routes starves them — a recurring pitfall when adding routes.

spring:
  cloud:
    gateway:
      routes:
        - id: order-service
          uri: lb://order-service
          predicates:
            - Path=/api/order/**
          filters:
            - StripPrefix=1

On match, FilteringWebHandler merges global filters (all routes) and route-specific filters, sorts by getOrder(), builds a chain. Request flows forward through chain; response flows backward. Key filter positions:

Order 10000: NettyRoutingFilter builds absolute URI (scheme, host, port).

Order 10150: LoadBalancerClientFilter resolves lb://service-name to real instance.

Last: NettyRoutingFilter (again) sends request via reactor-netty HttpClient.

Order -1: WebFilter writes response to client.

Scheme must be http or https. If lb:// reaches the routing filter unchanged, it throws UnknownHostException: lb — usually missing load-balancer dependency or malformed URI.

HttpClient uses a connection pool (reuses TCP). Pool max limits concurrent outbound requests; acquire timeout bounds wait time. Pool exhaustion + timeout throws connection acquisition error — often misread as "downstream down". Fix: increase pool or add gateway rate limiting.

Timeouts: global response timeout, plus per-route metadata for response/connect timeout (higher priority). Per-route relaxation is safer than raising global timeout, which removes protection for all routes.

4. MVC: How Tomcat Delivers to doDispatch

Downstream MVC request enters Tomcat. Its NIO implementation also has acceptor and poller threads: acceptor does accept; poller runs Selector, wraps ready connections as tasks to worker thread pool. Defaults: maxThreads=200, minSpareThreads=10, maxConnections=8192, acceptCount=100, connectionTimeout=20s. These cap simultaneous request handling.

Both Tomcat NIO and Netty use Reactor pattern but differ in work division:

Ready events: Tomcat NIO – Poller thread; Netty – EventLoop

Actual I/O: Tomcat NIO – Worker thread (blocking); Netty – EventLoop (non-blocking)

Business handling: Tomcat NIO – Worker thread (blocking); Netty – Business thread pool or reactive

Concurrency limit: Tomcat NIO – maxThreads 200; Netty – Connections far exceed threads

Programming model: Tomcat NIO – Servlet blocking API; Netty – Callbacks or Reactor

Worker thread adapts Tomcat request to HttpServletRequest, invokes container pipeline: Engine → Host → Context → Servlet wrapper (assembles filter chain) → Servlet.service(). DispatcherServlet initializes nine components (handler mappings, adapters, exception resolvers, view resolvers, locale/theme resolvers, view name translator, flash map manager, multipart resolver). Missing ones fall back to defaults. doDispatch is the backbone:

mappedHandler = getHandler(processedRequest);
HandlerAdapter ha = getHandlerAdapter(mappedHandler.getHandler());
if (!mappedHandler.applyPreHandle(processedRequest, response)) return;
ModelAndView mv = ha.handle(processedRequest, response, mappedHandler.getHandler());
applyDefaultViewName(processedRequest, mv);
mappedHandler.applyPostHandle(processedRequest, mv);
processDispatchResult(processedRequest, response, mappedHandler, mv, dispatchException);
getHandler

iterates handler mappings; RequestMappingHandlerMapping scans @RequestMapping at startup, registers method-to-path map. Matching considers HTTP method, params, headers, consumes, produces — so same path with different methods doesn't conflict.

Handler adapter ( RequestMappingHandlerAdapter) shields DispatcherServlet from handler shape. Its flow: resolve arguments → invoke method → handle return value.

Argument resolvers chain: @RequestParam → RequestParamMethodArgumentResolver; @PathVariable → PathVariableMethodArgumentResolver; @RequestBody → RequestResponseBodyMethodProcessor; unannotated POJO → ModelAttributeMethodProcessor (data binder + type conversion + validation). Validation failure throws exception for global handler to format.

Return value handlers mirror this. @ResponseBody → RequestResponseBodyMethodProcessor does content negotiation (Accept header vs produces), picks message converter (Jackson for JSON), serializes to response body.

WebFlux has same-named mappings/adapters in different packages — annotations barely change when migrating. Invisible changes: thread-local user context breaks (use Reactor Context), filters become reactive, HttpServletRequest disappears from signatures, blocking libraries (e.g., old tracing clients using thread-locals) fail.

Filter vs Interceptor boundary: Filters (Servlet spec) run before DispatcherServlet, see raw request/response. Interceptors (Spring MVC) wrap handler adapter invocation, access target method/handler. Business pre-processing → interceptor; encoding, compression, CORS → filter.

5. Four Problems at the Handoff

Timeout misalignment: Gateway response timeout must be longer than downstream. Gateway 2s, downstream 3s → gateway cuts first, client retries, duplicate work. Reverse: gateway waits forever, connections clog. Correct layering: outermost timeout longest, tighten inward; downstream fails fast, returns error to gateway.

Lost headers: After one hop, downstream sees gateway IP as remoteAddr; getScheme() returns http not https, breaking redirects. Gateway adds X-Forwarded-* headers, but downstream must enable server.forward-headers-strategy=framework to parse them back into request object. Missing this causes http redirect loops.

Thread model discontinuity: Gateway non-blocking handles tens of thousands of connections on few EventLoops; downstream Tomcat blocks on 200 threads. Gateway throughput ≠ downstream capacity. Gateway becomes amplifier, pushing more load than downstream can absorb. Fix: rate-limit at gateway per route/instance to match downstream capacity.

Retry amplifies side effects: Gateway retry filter defaults to GET only. POST timeout ambiguous: request never arrived vs response lost. Retrying non-idempotent POST duplicates orders. Safe retry requires idempotency key recognized by downstream.

6. Should You Run MVC on Netty?

Easy path: WebFlux natively supports @RequestMapping family. Controller example:

@RestController
@RequestMapping("/order")
public class OrderController {
    @GetMapping("/{id}")
    public Mono<Order> detail(@PathVariable Long id) {
        return orderService.findById(id); // returns Mono, non-blocking
    }
    @PostMapping
    public Mono<ResponseEntity<Void>> create(@RequestBody Mono<CreateOrderCmd> cmd) {
        return cmd.flatMap(orderService::create)
            .map(id -> ResponseEntity.created(URI.create("/order/" + id)).build());
    }
}

Annotations barely change; invisible changes: thread-local context → Reactor Context, Servlet filters → WebFilters, no HttpServletRequest in signatures, blocking libraries (old tracing clients) break.

Hard path: Bridge real DispatcherServlet onto Netty via servlet adapter. Must maintain two contracts: Netty pipeline non-blocking, Servlet I/O blocking. Most teams find bridging cost higher than rewriting controllers reactively.

Not worth migrating if: team lacks reactive experience, business uses blocking JDBC, bottleneck is DB not connection count. Wrapping blocking calls in reactive shell just moves wait from business thread to EventLoop — no gain.

Pragmatic compromise: Keep Netty at gateway (connection count, throughput); keep MVC in services (ecosystem, dev efficiency); communicate via HTTP. At gateway, add rate limiting, timeout alignment, header forwarding. This combo handles most production loads and is the common pattern.

Troubleshooting checklist: 1) Did request reach gateway? Check access logs, route match. 2) Connection pool exhausted? Acquisition timeout → gateway-side issue. 3) Compare timeout configs — who cuts first? 4) Downstream Tomcat thread pool saturated? Dump threads, find blocking line. 5) Verify header forwarding — client IP and scheme correct?

From NIC to Netty: byte buffers + pipeline pass. Past gateway: new HTTP request. At Tomcat: request object → container pipeline. Into DispatcherServlet: handler mapping finds your method. Each segment has own timeout, thread model, failure modes. Separate them to get a grip on debugging.

Original Source

Signed-in readers can open the original source through BestHub's protected redirect.

Sign in to view source
Republication Notice

This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactadmin@besthub.devand we will review it promptly.

NettyReactive ProgrammingSpring BootWebFluxTomcatSpring MVCSpring Cloud GatewayDispatcherServlet
Reader feedback

How this landed with the community

Sign in to like

Rate this article

Was this worth your time?

Sign in to rate
Discussion

0 Comments

Thoughtful readers leave field notes, pushback, and hard-won operational detail here.