Netty is not a web framework

This article is a work in progress and still pending review.

Recently, I have seen more and more web frameworks adopt Netty as their backend (the part that handles the actual HTTP requests). Examples are Spring WebFlux (the spring reactive web stack), Vert.x and Ktor.

What is Netty?

Netty calls itself “an asynchronous event-driven network application framework”. Let’s go over this word for word.

  • Netty is used for network applications: Instead of the “normal” APIs (Socket, InputStream, …) you can use the Netty framework to build network applications.
  • Netty is a framework, not a library. It is fairly opinionated for things like connection management and expects you to use its pipeline model (more on that later) to build your application. This is in contrast to a framework like XNIO that aims to simplify and complement the existing Java nio APIs.
  • Netty is asynchronous by design. When processing data from a network connection, you do not do so by calling blocking read methods like you would with InputStream, you instead get chunks of data asynchronously (in a “callback” you register). This is one of the main selling points – it allows you to serve many connections with few threads, which can help performance, and makes for a very convenient programming model.
  • Netty is event-driven. An idiomatic Netty application has a pipeline of “transformations” it applies on incoming and outgoing data. For example, you might first get incoming chunks of bytes, buffer them until a packet boundary and then send the full packet further downstream. The next handler in the pipeline would then parse the packet, and the handler after that finally runs the code that actually handles the packet.

In addition, Netty offers many implementations of common protocols out-of-the-box that you can basically mix-and-match as you wish. This goes from simple handlers such as DelimiterBasedFrameDecoder used for splitting incoming data on delimiters such as newline, to advanced handlers for full protocols like TLS or HTTP 1.1/2.

All this makes Netty one of the best (if not the best) general-purpose network application frameworks of any language out there. Nowhere else do you get network application development that is so convenient and powerful. I have used Netty in many projects over the years, and have contributed to it, and it remains my number one recommendation for anyone writing code that deals with custom protocols.

So why is Netty not appropriate for the Web?

Netty and HTTP

Netty includes handlers for parsing HTTP messages, both versions 1.1 and HTTP 2. It even supports SPDY if you wish to go back a few years! Netty got HTTP 2 support very early while other frameworks were still catching up, which may have contributed to its newfound popularity as a web framework.

I will not dispute Netty HTTP support can be very convenient. Netty’s design allows you to do things using its built-in HTTP handlers that would be impossible or difficult with traditional web frameworks. Is your HTTP/2 connection somehow TLS-less and wrapped in a custom encryption scheme? Does the remote server use upgrade mechanisms that are anything but to spec? Netty can implement your protocol anyway!

However, there are two disadvantages that Netty has that you will not get around easily.

Netty is not optimized as a HTTP server. Netty’s programming model brings with it certain static overhead – per-connection memory use is pretty high compared to raw Java NIO and its buffer management is convenient but not free. “Real” web frameworks can do more here: They can minimize parsing overhead, tune their buffer management to use patterns commonly seen for web servers and drop the niceties that Netty offers internally in favor of performance. When it’s not actually you doing the protocol parsing, the convenience of Netty’s internals don’t matter anymore.

Netty is not binary compatible, even across minor versions. This came as a surprise to me a few years back, but it makes sense: Netty offers very detailed views of its internals and evolution of the API would be hard without breaking binary compatibility at some point. Now this is not necessarily a problem for most Netty users that use Netty directly from their application. However, if you try to use two libraries on the same classpath at the same time that both use Netty (maybe Vert.x and the Java mongo driver) you could be in for a rude awakening in the future. You will either need to recompile or even patch one of the two. An alternative is relocation but that is inconvenient for reasons I will not discuss here. The incompatibility may become an even larger problem in the future when Netty 5 releases (if it ever does, it’s been in development for years).

So what’s the alternative?

Use Undertow. Undertow is a relatively new web server and the backend in Wildfly. Undertow was designed from the ground up as an asynchronous server, same as Netty. However, it is actually designed as a HTTP server and uses NIO directly instead of more expensive wrappers. This makes Undertow faster than Netty HTTP and appropriate for asynchronous applications. On top of that it is binary compatible with previous versions.

When you are building a “vanilla” HTTP server or client – one that does not mess with the HTTP protocol in non-standard ways – or you develop a web framework, use Undertow. There are few advantages Netty offers for the purely HTTP use case, and you are less likely to regret picking Undertow in the future.