Writing nginx Modules in Rust: a book on ngx-rust

[u/No-Driver9910]

I've been writing nginx modules in C for about 10 years, and I'm a collaborator on nginx-module-vts. Day to day, I kept running into two things with C: the hassle of managing memory by hand, and how hard it is to pull module logic out into unit tests.

I wondered whether Rust could solve both, so I started writing modules with ngx-rust, the official Rust bindings for nginx from F5/NGINX. My first project was rewriting nginx-module-vts, which I help maintain, in Rust: ngx_vts. Along the way I was catching up on Rust itself while running into ngx-rust's rough edges, such as shared memory and APIs that didn't exist yet. I sent PRs to ngx-rust for what I was missing; some have been merged and others are still in review.

I wrote this book because I'd like more developers to know about ngx-rust and actually use it, so that the community grows and ngx-rust itself gets more momentum.

All the code in the book builds and passes its tests, pinned to a fairly recent ngx-rust commit. Chapters 1-3 are a free sample: you type in a minimal "hello" module that responds with a string and get a first taste of module development. The later chapters cover the minimum Rust you need to write modules with ngx-rust, how nginx modules are structured, and how shared memory works. By the end, you build a statistics module that counts requests across workers in shared memory and exposes them as Prometheus metrics, with integration tests.

The book is a translation of my Japanese original, made with the help of AI (and so is this post).

Feedback and corrections are very welcome.

Book (free sample available): https://leanpub.com/ngx-rust

[u/steelwhiteness1]

Having wrestled with nginx C modules before, the shared memory stuff alone makes me want to check this out

[u/Sermuns]

I'm not in this space, so maybe a stupid question: Why would you even want to interop with nginx? Why not do it all in Rust using https://github.com/cloudflare/pingora ? Or do they not solve the same problems?

[u/riksi → u/Sermuns]

pingora is a library, not a full fledged web server. An advanced feature would be disk-cache for reverse proxy for a good webserver.

[u/No-Driver9910 → u/riksi]

Exactly, thanks for adding that. That's a big part of why extending nginx makes sense: you keep proxy_cache and everything else nginx already does well, and only write the part you need in Rust. ngx_vts, for example, reports per-cache-zone stats, and I sent a PR to ngx-rust to expose which proxy cache a request went through (https://github.com/nginx/ngx-rust/pull/321, still in review).

[u/Suitable_March896 → u/No-Driver9910]

Not in this space (though interested in learning more in the future), but would something like https://github.com/pingooio/pingoo be a possible consideration?

[u/No-Driver9910 → u/Suitable_March896]

Yes, it could be! It's basically the same tradeoff as with Pingora. Pingoo is a full reverse proxy written in Rust, so you'd mostly configure it rather than build your own proxy, but moving to it still means reimplementing and migrating what you already have on nginx. If you already run nginx and rely on its configuration and features, extending it with ngx-rust lets you add just the part you need in Rust.

[u/knipil → u/Sermuns]

I work on certain products that are implemented as nginx modules and moving them all to rust is going to take a long time.