コンテンツにスキップ
ngx_mruby
2.xのドキュメントEnglishGitHub

リクエストのフェーズ

nginxは、HTTPのリクエストを決まった順のフェーズで処理します。ngx_mrubyは、そのうちの6つのフェーズにハンドラを加えます。また、rewriteモジュールの中でmruby_setを実行し、nginxのフィルタチェーンにヘッダフィルタとボディフィルタを加えます。TLSのハンドシェイクの間にもハンドラを1つ実行します。TCPとUDPでは、streamモジュールのaccessフェーズでハンドラを実行します。

nginxがHTTPのリクエストを処理するフェーズを順に並べ、各フェーズでRubyを実行するngx_mrubyのディレクティブを示します。TCPとUDPのセッションで動くハンドラも示します。ngx_mrubyとnginxのソースの次の行から描きました。ngx_mrubyの行は、2026-10-19のコミット0c72e3970の行です。
  • src/http/ngx_http_mruby_module.cの431行、638行から721行、1742行から1824行、1954行から1965行
  • src/stream/ngx_stream_mruby_module.cの787行
  • nginx 1.31.6のソースツリーにあるsrc/http/ngx_http_core_module.hの111行から128行

表の各ディレクティブは、Rubyのスクリプトのパスを受け取ります。どのディレクティブにも、mruby_access_handler_codeのように名前の最後に_codeが付く形があります。その形はRubyのコードを直接受け取ります。

実行する時点 ディレクティブ
TLSのハンドシェイクの間 mruby_ssl_handshake_handler
post-read mruby_post_read_handler
server rewrite mruby_server_rewrite_handler
rewrite mruby_rewrite_handler
access mruby_access_handler
content mruby_content_handler
レスポンスのヘッダを送るとき mruby_output_header_filter
レスポンスのボディを送るとき mruby_output_body_filter
log mruby_log_handler
rewriteモジュールが動くserver rewriteとrewrite mruby_set
streamモジュールのaccess mruby_stream

nginxは、リクエストを読む前にTLSのハンドシェイクを済ませます。find config、post-rewrite、preaccess、post-access、precontentの各フェーズでは、ngx_mrubyのハンドラは動きません。mruby_setは、rewriteモジュールがsetを実行するところで、Rubyで変数を設定します。serverブロックに書いたmruby_setはserver rewriteフェーズで動き、locationに書いたmruby_setはrewriteフェーズで動きます。ヘッダフィルタとボディフィルタは、nginxがレスポンスを送る間に動きます。レスポンスを作ったのが、contentフェーズのハンドラでも、upstreamでも、前のフェーズのreturnやエラーでも同じです。logフェーズは、レスポンスを送った後に来ます。nginxのフィルタチェーンの中では、ngx_mrubyのフィルタは、nginxのnot modifiedのヘッダフィルタと、rangeとcopyのボディフィルタの後に動き、ほかのモジュールのフィルタより先に動きます。mruby_post_read_handlerはhttpとserverのブロックに、mruby_ssl_handshake_handlerはserverブロックに書けます。そのほかのハンドラはlocationにも書けます。