Writing nginx Modules in Rust

nginx modules have long been written in C, where every pointer lifetime, every allocation, and every access to shared memory is the author's responsibility. ngx-rust, the official Rust binding from F5/NGINX, lets the compiler take over the part of that responsibility it can check.

This book shows you how to write nginx modules in Rust, all the way to a statistics module you could run in production: it reads configuration directives, counts requests across worker processes in shared memory, serves Prometheus metrics on /status, and is verified by integration tests.

Every explanation is tied to code that actually runs. The examples come from ngx-rust itself, from nginx-acme, from ports of nginx's own stub_status and not_modified filter modules, and from ngx_vts, a Rust version of nginx-module-vts that passes 13 integration test files with 300 assertions. Where an API was missing, the author sent it upstream to ngx-rust, and the book shows how.

What you will learn:

- The Rust you need to read ngx-rust code: ownership, Option and Result, traits and monomorphization, lifetimes, and unsafe, explained through real ngx-rust code rather than toy examples

- How a module is put together: directives, the three configuration levels, the 11 phases, requests and responses

- Where values live: request pools, cycle pools, and shared memory, and why the allocator is a type parameter

- Shared memory across worker processes: zones, slab, rbtree, inter-process locks, and what happens on reload

- Filters and load balancers, where ngx-rust has no wrapper yet

- Building, testing, and debugging a real statistics module, including the pitfalls the author actually hit

Who this book is for: anyone who runs nginx and wants to extend it. No Rust experience is assumed; Part 1 covers what you need. Knowing C helps but is not required.

The book targets ngx-rust main as of September 17, 2026 (commit f5aacab) and nginx 1.30.x, tested on x86_64 Linux and Apple Silicon.

This English edition was translated from the author's Japanese original, available on Zenn, with the help of an AI model. The technical content and code are the author's own.