Skip to content
ngx_mruby
2.x docs日本語GitHub

Request phases

nginx handles an HTTP request in a fixed order of phases. ngx_mruby adds a handler to six of them, runs mruby_set inside the rewrite module, adds a header filter and a body filter to nginx’s filter chains, and runs a handler during the TLS handshake. For TCP and UDP, it runs one handler in the access phase of nginx’s stream module.

nginx's HTTP phases in order, the ngx_mruby directive that runs Ruby in each of them, and the handler for TCP and UDP sessions.Drawn from these lines of ngx_mruby at 0c72e3970 (2026-10-19) and of nginx:
  • src/http/ngx_http_mruby_module.c lines 431, 638 to 721, 1742 to 1824 and 1954 to 1965
  • src/stream/ngx_stream_mruby_module.c line 787
  • src/http/ngx_http_core_module.h lines 111 to 128 of nginx 1.31.6

Each directive in the table takes the path of a Ruby script. Each also has a form with the suffix _code, such as mruby_access_handler_code, which takes the Ruby code itself.

When it runs Directive
TLS handshake mruby_ssl_handshake_handler
post-read phase mruby_post_read_handler
server rewrite phase mruby_server_rewrite_handler
rewrite phase mruby_rewrite_handler
access phase mruby_access_handler
content phase mruby_content_handler
as the response header goes out mruby_output_header_filter
as the response body goes out mruby_output_body_filter
log phase mruby_log_handler
server rewrite and rewrite phases mruby_set
access phase of the stream module mruby_stream

The TLS handshake comes before nginx reads the request. nginx runs the find config, post-rewrite, preaccess, post-access and precontent phases without an ngx_mruby handler. mruby_set sets a variable from Ruby where the rewrite module runs set: in the server rewrite phase for a mruby_set in a server block, and in the rewrite phase for one in a location. The header filter and the body filter run while nginx sends a response, whichever phase made it: a content handler, an upstream, or a return or an error of an earlier phase. The log phase comes after the response is sent. In nginx’s filter chains, ngx_mruby’s filters run after nginx’s not-modified header filter and its range and copy body filters, and before the filters of nginx’s other modules. mruby_post_read_handler is accepted in the http and server blocks, and mruby_ssl_handshake_handler in a server block; the other handlers are also accepted in a location.