Understanding Nginx HTTP Request Processing Flow

Basic Concepts

Nginx is a high‑performance open‑source HTTP server and reverse proxy; this article, based on nginx‑1.15.0, briefly introduces its HTTP processing workflow.

Typical Nginx configuration includes a master‑worker model where the master initializes configuration, creates listening sockets, and manages worker processes, while workers handle client requests. Key directive blocks are:

events : configures event handling, e.g., worker_connections for the maximum number of sockets per worker.

http : configures HTTP request handling, e.g., access_log .

server : defines virtual servers, each with its own listen port and root directory.

location : defines how specific request paths are processed, using directives such as proxy_pass or fastcgi_pass .

Nginx is highly modular; each module implements a specific function (e.g., ngx_http_limit_req_module for rate limiting). Modules declare their configuration commands in ngx_command_t arrays, specifying name, type, and handler.

Server Initialization

The http block is parsed by ngx_http_block, which processes main, server, and location configurations, initializes handlers, and sets up listening sockets stored in conf->cycle->listening.

Each listening socket is represented by ngx_listening_t and is associated with the handler ngx_http_init_connection. The main function calls ngx_init_cycle, which ultimately invokes ngx_open_listening_sockets to start listening.

When using epoll, the event core module registers listening events via ngx_event_process_init, adding them to the epoll set.

HTTP Request Parsing

Core Structures

ngx_connection_t

stores socket‑related information and is pooled in ngx_cycle->free_connections. The worker_connections directive sets the pool size. ngx_http_request_t holds all data needed for processing a request, linking to its ngx_connection_t, read/write event handlers, headers, body, request line, method, and HTTP version.

Parsed request headers are stored in ngx_http_headers_in_t. Header definitions reside in the ngx_http_headers_in array, each entry being a ngx_http_header_t with name, offset, and handler. For efficiency, Nginx converts this array into a hash table via ngx_http_init_headers_in_hash.

HTTP Request Handling Stages

11 Processing Phases

Nginx divides HTTP request handling into eleven phases, each represented by a handler array. Modules register their handlers to specific phases, except for four phases that are reserved.

NGX_HTTP_POST_READ_PHASE – e.g., ngx_http_realip_module NGX_HTTP_SERVER_REWRITE_PHASE – URL rewrite in server block

NGX_HTTP_FIND_CONFIG_PHASE – location lookup (cannot add custom handler)

NGX_HTTP_REWRITE_PHASE – URL rewrite in location block

NGX_HTTP_POST_REWRITE_PHASE – checks for rewrites and may restart config lookup

NGX_HTTP_PREACCESS_PHASE – e.g., rate‑limit modules

NGX_HTTP_ACCESS_PHASE – access control (IP, auth, etc.)

NGX_HTTP_POST_ACCESS_PHASE – post‑access processing (cannot add custom handler)

NGX_HTTP_TRY_FILES_PHASE – triggered by try_files (cannot add custom handler)

NGX_HTTP_CONTENT_PHASE – content generation (e.g., static, proxy, fastcgi modules)

NGX_HTTP_LOG_PHASE – logging

Modules register their handlers through the postconfiguration callback, which populates a two‑dimensional phases array. The function ngx_http_init_phase_handlers flattens this into a one‑dimensional cmcf->phase_engine.handlers array, where each handler has a checker and a next index for flow control.

Content Generation Phase

During the NGX_HTTP_CONTENT_PHASE, the selected content handler (e.g., ngx_http_static_module, ngx_http_proxy_module, or ngx_http_fastcgi_module) produces the response. The handler is determined earlier in the NGX_HTTP_FIND_CONFIG_PHASE and stored in r->content_handler.

Summary

Nginx’s HTTP request processing is intricate: the master process sets up listening sockets, workers manage connections from a pre‑allocated pool, request parsing populates various structures, and the request traverses eleven configurable phases before content is generated and logged.