Directives
ngx_mruby enables you to run mruby scripts on nginx. For example, you can implement:
- your own auth mechanism like nginx auth_basic
- reverse proxy with your own backend selection algorithm
- content handler that returns any HTTP response
See use cases page for more examples. The scripts can be invoked at any of nginx HTTP phases. See nginx phases doc for more details of the phases.
ngx_mruby provides 2 modules. One is HTTP module for HTTP, the other is Stream module for TCP/UDP stream. See HTTP module directives and Stream module directive section for more details.
Here is a simple example of a content handler for HTTP.
nginx.conf
location /hello { mruby_content_handler /path/to/hello.rb;}/path/to/hello.rb
Nginx.echo "Hello World"$ curl http://127.0.0.1/helloHello World‘mruby_
‘Nginx.echo’ is a method to creates a response body. ngx_mruby provides classes for accessing or manipulating nginx internal data structures. See classes for ngx_mruby for more information.
Caching compile code
Section titled “Caching compile code”By default, mruby script is compiled whenever it is invoked. You can enable compiled code cache with ‘cache’ argument for performance.
nginx.conf
location /hello { mruby_content_handler /path/to/hello.rb cache;}Inline code
Section titled “Inline code”You can write mruby code in nginx.conf instead of creating a script file. The compiled code is cached.
nginx.conf
location /hello { mruby_content_handler_code ' Nginx.echo "Hello World" ';}Nginx variables
Section titled “Nginx variables”You can set nginx variable by a mruby script. The following example set a value returned from ‘proxy.rb’ to the variable ‘$backend’.
nginx.conf
location /proxy { mruby_set $backend /path/to/proxy.rb;}Also you can enable caching, or write inline mruby code as same as other directives.
nginx.conf
location /proxy { mruby_set $backend /path/to/proxy.rb cache;}nginx.conf
location /proxy { mruby_set_code $backend ' backends = [ "test1.example.com", "test2.example.com", "test3.example.com", ] backends[rand(backends.length)] ';}Hooks on initialization phases
Section titled “Hooks on initialization phases”ngx_mruby provides hooks invoked on several nginx initialization phases as below. See nginx Core Modules doc for more about initialization phases.
http { mruby_init /path/to/init.rb; mruby_init_worker /path/to/init_worker.rb; mruby_exit_worker /path/to/exit_worker.rb; server { location / { mruby_content_handler /path/to/handler.rb; } }}Script file as a handler
Section titled “Script file as a handler”You can run a ruby script file directly without location definition. In the following example, the script is exposed at http://127.0.0.1/YOUR_MRUBY_SCRIPT.rb
location ~ \.rb$ { mruby_add_handler on;}Messages logged while nginx reads the configuration
Section titled “Messages logged while nginx reads the configuration”While nginx reads the configuration, ngx_mruby logs these messages at the info level:
ngx_mruby/VERSION (mruby/VERSION) mechanism enabled, once for thehttp {}blockcompile info: code->code.file=(...)orcompile info: code->code.string=(...)for each directive with Ruby code, inhttp {}and instream {}target variable=(...)for eachmruby_setandmruby_set_code
nginx logs what happens while it reads the configuration through its startup log, not through the log that error_log configures.
The startup log is the file given with nginx -e (nginx 1.19.5 and later), or else the error log path compiled into nginx (--error-log-path, logs/error.log under the prefix by default), and its level is notice whatever error_log says.
nginx uses the configured error_log only after it has read the configuration. So:
- A start of nginx does not write these messages, whatever the level of
error_log. nginx -traises the startup log toinfo, so it writes them to the startup log.- A reload (
nginx -s reload) reads the new configuration through theerror_logof the running configuration, so it writes them when thaterror_logis atinfoordebug.
A script file that cannot be opened, or an argument that a directive does not accept, is still logged at emerg, and nginx stops.
In ngx_mruby 2.x these messages were logged at notice, so the startup log wrote them at every start, also with error_log ... warn; (#320).
From v3 on, to see them, run nginx -t -e stderr, read the startup log after nginx -t, or reload with error_log at info.
HTTP module directives
Section titled “HTTP module directives”- mruby_init and mruby_
init_ code - mruby_
init_ worker and mruby_ init_ worker_ code - mruby_
exit_ worker and mruby_ exit_ worker_ code - mruby_
ssl_ handshake_ handler and mruby_ ssl_ handshake_ handler_ code - mruby_
server_ context_ handler_ code - mruby_
add_ handler - mruby_cache
- mruby_
post_ read_ handler and mruby_ post_ read_ handler_ code - mruby_
server_ rewrite_ handler, mruby_ server_ rewrite_ handler_ code, mruby_ rewrite_ handler and mruby_ rewrite_ handler_ code - mruby_
access_ handler and mruby_ access_ handler_ code - mruby_
content_ handler and mruby_ content_ handler_ code - mruby_
log_ handler and mruby_ log_ handler_ code - mruby_set and mruby_
set_ code - mruby_variable
- mruby_
output_ body_ filter, mruby_ output_ body_ filter_ code, mruby_ output_ header_ filter and mruby_ output_ header_ filter_ code - mruby_
enable_ read_ request_ body - mruby_
upstream_ keepalive - mruby_
output_ filter and mruby_ output_ filter_ code (removed)
mruby_init and mruby_init_code
Section titled “mruby_init and mruby_init_code”Syntax: mruby_init /PATH/TO/YOUR/MRUBY/SCRIPT.rb [cache];Default: -Context: httpPhase: initialize master processSyntax: mruby_init_code 'YOUR MRUBY CODE HERE';Default: -Context: httpPhase: initialize master process‘mruby_init’ and ‘mruby_
mruby_init_worker and mruby_init_worker_code
Section titled “mruby_init_worker and mruby_init_worker_code”Syntax: mruby_init_worker /PATH/TO/YOUR/MRUBY/SCRIPT.rb [cache];Default: -Context: httpPhase: initialize worker processSyntax: mruby_init_worker_code 'YOUR MRUBY CODE HERE';Default: -Context: httpPhase: initialize worker processAfter initializing nginx master process, it creates worker processes.
‘mruby_
The code runs outside any request.
Nginx.log writes to nginx’s error log here (since 2.7.1; 2.7.0 raised a RuntimeError).
Request-scoped methods such as Nginx::Request, Nginx::Var and Nginx.rputs raise a RuntimeError here (since 2.7.1; in 2.7.0 they crashed the worker).
See Nginx.errlogger for what code outside a request can call.
mruby_exit_worker and mruby_exit_worker_code
Section titled “mruby_exit_worker and mruby_exit_worker_code”Syntax: mruby_exit_worker /PATH/TO/YOUR/MRUBY/SCRIPT.rb [cache];Default: -Context: httpPhase: exit worker processSyntax: mruby_exit_worker_code 'YOUR MRUBY CODE HERE';Default: -Context: httpPhase: exit worker process‘mruby_
The code runs outside any request.
Nginx.log writes to nginx’s error log here (since 2.7.1).
Request-scoped methods such as Nginx::Request, Nginx::Var and Nginx.rputs raise a RuntimeError here (since 2.7.1; in 2.7.0 they used the last request that the worker had handled, or crashed the worker when it had handled none).
See Nginx.errlogger for what code outside a request can call.
mruby_ssl_handshake_handler and mruby_ssl_handshake_handler_code
Section titled “mruby_ssl_handshake_handler and mruby_ssl_handshake_handler_code”Syntax: mruby_ssl_handshake_handler /PATH/TO/YOUR/MRUBY/SCRIPT.rb [cache];Default: -Context: serverPhase: SSL handshakeSyntax: mruby_ssl_handshake_handler_code 'YOUR MRUBY CODE HERE';Default: -Context: serverPhase: SSL handshake‘mruby_
The code runs for a TLS connection, before any request on it, and uses Nginx::Nginx::SSL.log writes to the log of the connection, and Nginx.log writes to nginx’s error log (since 2.7.1).
Request-scoped methods such as Nginx::Request, Nginx::Var and Nginx.rputs raise a RuntimeError here (since 2.7.1; in 2.7.0 they used the last request that the worker had handled, or crashed the worker when it had handled none).
See Nginx.errlogger for what code outside a request can call.
mruby_server_context_handler_code
Section titled “mruby_server_context_handler_code”Syntax: mruby_server_context_handler_code 'YOUR MRUBY CODE HERE';Default: -Context: serverPhase: read the configuration, in the master processThe code runs once for its server block, while nginx reads the configuration, in the master process.
It configures the server: Nginx::Server#add_listener adds a listen address to it.
No request exists yet, so the request-scoped methods raise a RuntimeError here.
mruby_add_handler
Section titled “mruby_add_handler”Syntax: mruby_add_handler on | off;Default: offContext: server, locationPhase: initialize master processWhen set to the value on, mruby scripts are added as handlers. You can run the script files directly without endpoint definition.
mruby_cache
Section titled “mruby_cache”Syntax: mruby_cache on | off;Default: offContext: server, locationPhase: initialize master processWhen set to the value on, nginx compiles the script files of the post-read, server rewrite, rewrite, access, content and log handlers, the header and body filters and mruby_set of the server or location once, when it reads the configuration, as the parameter cache does for one directive.
mruby_ssl_handshake_handler and the init and exit hooks take only their own parameter cache.
With off, a script file without cache is read from disk and compiled for every request, so that a change of the file takes effect at the next request (see Caching compile code).
mruby_post_read_handler and mruby_post_read_handler_code
Section titled “mruby_post_read_handler and mruby_post_read_handler_code”Syntax: mruby_post_read_handler /PATH/TO/YOUR/MRUBY/SCRIPT.rb [cache];Default: -Context: serverPhase: NGX_HTTP_POST_READ_PHASESyntax: mruby_post_read_handler_code 'YOUR MRUBY CODE HERE';Default: -Context: serverPhase: NGX_HTTP_POST_READ_PHASE‘mruby_
mruby_server_rewrite_handler, mruby_server_rewrite_handler_code, mruby_rewrite_handler and mruby_rewrite_handler_code
Section titled “mruby_server_rewrite_handler, mruby_server_rewrite_handler_code, mruby_rewrite_handler and mruby_rewrite_handler_code”Syntax: mruby_server_rewrite_handler /PATH/TO/YOUR/MRUBY/SCRIPT.rb [cache];Default: -Context: server, locationPhase: NGX_HTTP_SERVER_REWRITE_PHASESyntax: mruby_server_rewrite_handler_code 'YOUR MRUBY CODE HERE';Default: -Context: server, locationPhase: NGX_HTTP_SERVER_REWRITE_PHASESyntax: mruby_rewrite_handler /PATH/TO/YOUR/MRUBY/SCRIPT.rb [cache];Default: -Context: server, locationPhase: NGX_HTTP_REWRITE_PHASESyntax: mruby_rewrite_handler_code 'YOUR MRUBY CODE HERE';Default: -Context: server, locationPhase: NGX_HTTP_REWRITE_PHASEThe rewrite handlers are mainly used for URL rewrite.
‘mruby_
TODO: I’m not sure if the above contexts are correct.
mruby_access_handler and mruby_access_handler_code
Section titled “mruby_access_handler and mruby_access_handler_code”Syntax: mruby_access_handler /PATH/TO/YOUR/MRUBY/SCRIPT.rb [cache];Default: -Context: server, locationPhase: NGX_HTTP_ACCESS_PHASESyntax: mruby_access_handler_code 'YOUR MRUBY CODE HERE';Default: -Context: server, locationPhase: NGX_HTTP_ACCESS_PHASE‘mruby_
mruby_content_handler and mruby_content_handler_code
Section titled “mruby_content_handler and mruby_content_handler_code”Syntax: mruby_content_handler /PATH/TO/YOUR/MRUBY/SCRIPT.rb [cache];Default: -Context: server, locationPhase: NGX_HTTP_CONTENT_PHASESyntax: mruby_content_handler_code 'YOUR MRUBY CODE HERE';Default: -Context: server, locationPhase: NGX_HTTP_CONTENT_PHASEmruby_
mruby_log_handler and mruby_log_handler_code
Section titled “mruby_log_handler and mruby_log_handler_code”Syntax: mruby_log_handler /PATH/TO/YOUR/MRUBY/SCRIPT.rb [cache];Default: -Context: server, locationPhase: NGX_HTTP_LOG_PHASESyntax: mruby_log_handler_code 'YOUR MRUBY CODE HERE';Default: -Context: server, locationPhase: NGX_HTTP_LOG_PHASE‘mruby_Nginx.rputs, Nginx.return and Nginx::Headers_out#[]=, raise a RuntimeError, because the response is already sent (since 3.0.0; on 2.x Nginx.rputs and Nginx.echo wrote no response bytes there; see Where the methods work). Use Nginx.log to write to the error log, and Nginx::Var to pass values to access_log.
Since 3.0.0, they run first in the log phase, before access_log: an access_log whose log_format names a variable that a log handler assigns with Nginx::Var writes the assigned value. When a location has both, the handler of mruby_log_handler runs before that of mruby_log_handler_code. They also run before the log-phase handlers of the other modules whose postconfiguration runs before that of ngx_mruby; a module whose postconfiguration runs later adds its log-phase handlers after them.
A log handler does not change the status that access_log and the later log-phase handlers write. After each log handler, the status of the response is the one that was sent, also when the handler raised an exception, which still goes to error.log.
In a log handler, Nginx.redirect with a local URI raises a RuntimeError and makes no internal redirect, because the log-phase handlers after it run on the same request (since 3.0.0; see the release notes of 3.0.0).
On 2.x, the log handlers ran after access_log, and the access log line had the values of the variables from before them (see the release notes of 3.0.0).
log_format with_value '$request_uri $status $log_value';
server { access_log logs/access.log with_value;
location = /assign { set $log_value "unset"; mruby_content_handler_code 'Nginx.rputs "assign"'; mruby_log_handler_code 'Nginx::Var.new.log_value = "from-ruby"'; }}The access log line of GET /assign is /assign 200 from-ruby.
mruby_set and mruby_set_code
Section titled “mruby_set and mruby_set_code”Syntax: mruby_set $VARNAME /PATH/TO/YOUR/MRUBY/SCRIPT.rb [cache];Default: -Context: server, locationPhase: NGX_HTTP_SERVER_REWRITE_PHASE, NGX_HTTP_REWRITE_PHASESyntax: mruby_set_code $VARNAME 'YOUR MRUBY CODE HERE';Default: -Context: server, locationPhase: NGX_HTTP_SERVER_REWRITE_PHASE, NGX_HTTP_REWRITE_PHASE‘mruby_set’ and ‘mruby_
If the code raises an exception before it waits in Nginx::Async.sleep, ngx_mruby logs it, the variable is set to an empty string (as when the code returns nil), also when an earlier directive of the location gave it a value, and the request goes on.
Text that the code wrote with Nginx.rputs or Nginx.echo before the exception is not sent and does not count in the Content-Length of the response.
If the code raises after the sleep, the request gets 500 and the output of Nginx.rputs is not sent, as described under Nginx::
The value of the code is converted to a String with to_s. When the value has no to_s, when to_s raises, or when it returns an object that is not a String, ngx_mruby logs the exception (a TypeError for the object that is not a String) and the request gets 500, with or without a sleep. Unlike an exception of the code, which leaves the variable empty, such a value ends the request: the code returned a value that the variable cannot hold.
Nginx::Async::HTTP.sub_request raises a RuntimeError in mruby_set and mruby_set_code, because nginx does not wait for a subrequest of the rewrite script: call it in a rewrite or access handler, and set the variable there with Nginx::Var#set. Since 3.0.0; on 2.x nginx went on without waiting for the variable (see the release notes of 3.0.0).
Nginx.redirect with a local URI raises a RuntimeError in mruby_set and mruby_set_code and makes no internal redirect, because the rewrite script goes on after the handler (since 3.0.0; see the release notes of 3.0.0). The handler ends as after any other exception: the variable is empty and the request goes on. A redirect with a URL works there. To send the request to another location, call Nginx.redirect in a rewrite or access handler.
When the code waits in Nginx::Async.sleep, the directives of the same rewrite script after the mruby_set run before the sleep ends, without the value. When the code returns, the variable is set and the request goes on with the next handler of its phase, as without the sleep, so the later phases (proxy_pass, a content handler) read the value. A status that the code sets with Nginx.return does not end the request, with or without the sleep. Since 3.0.0; on 2.x, a request whose code slept ended without a response, unless an earlier handler of the request had returned Nginx::DECLINED, and a status set after the sleep ended the request with that status (see the release notes of 3.0.0).
mruby_variable
Section titled “mruby_variable”Syntax: mruby_variable $VARNAME [value];Default: -Context: httpPhase: initialize master processSince 3.0.0. Declares the variable $VARNAME for scripts to assign with Nginx::Var, without a set that runs in the request. nginx needs a variable to be declared before a script can assign it, and before proxy_set_header, add_header, log_format and the other directives can read it. A set does declare it, but it also runs in its phase: a set at the server level runs in the server rewrite phase after the handler of mruby_server_rewrite_handler or mruby_server_rewrite_handler_code, and overwrites the value that the handler assigned.
Until a script, or a set, assigns the variable in a request, it reads as value, which may contain variables, as the value of set may. Without value, the variable reads as the empty string. An assignment replaces the value for the rest of the request, as set does; the next request starts again from value.
nginx computes value when the request reads the variable for the first time, not in a phase as set does, and keeps the result for the rest of the request. Nothing runs for a request that does not read the variable. The time of that first read decides what a variable in value gives:
- With
mruby_variable $t "$request_time";, when onlyaccess_logreads$t, the log line has the time of the whole request (for example0.152), whereset $t $request_time;in the location gives the time at the rewrite phase (0.000). When a server rewrite handler readsNginx::Var.new.tfirst, the value is fixed at that read (0.000), and the access log line has0.000too. - With
mruby_variable $up "$upstream_addr";, alog_formator anadd_headerthat reads$upgives the address of the upstream (for example127.0.0.1:8080), whereset $up $upstream_addr;gives the empty string, because nginx has chosen no upstream in the rewrite phase. A read in a rewrite or access handler fixes the empty string for the rest of the request. - The value is kept with the variables of the request, which an internal redirect keeps and a subrequest shares with its main request, as for
set. A default that a subrequest reads first, such as"$uri", has the value of the subrequest for the main request as well.
To fix the value at a phase, assign it in that phase, with set or a handler.
mruby_variable refuses, when nginx reads the configuration, a name that nginx or another module defines with a value of its own: nginx -t fails for $uri or $args, for the names of the variables of a request header, an argument or a cookie ($http_NAME, $arg_NAME, $cookie_NAME and the other prefixes), for a variable of map or geo before or after the directive, and for a second mruby_variable of the same name. A named capture of a regular expression with the same name, in a location, an if or a map ((?<agent_key>...) for $agent_key), is refused as well, before or after the directive: nginx gives such a variable a get handler that ngx_mruby cannot tell from that of another module, so the message names both causes.
The directives that only assign a variable and are accepted before or after mruby_variable are set, mruby_set, mruby_set_code and the other directives built on ngx_auth_request_set is refused before mruby_variable and accepted after it, because it gives the variable its own get handler only when the variable has none.
The directive is only allowed in the http block, because nginx declares a variable for the whole http block. Its value is the same in every location.
http { mruby_variable $agent_key; mruby_variable $agent_tier "free";
log_format agent '$request_uri $agent_key $agent_tier';
upstream backend { server 127.0.0.1:8080; }
server { access_log logs/agent.log agent;
mruby_server_rewrite_handler_code ' v = Nginx::Var.new key = Nginx::Request.new.headers_in["X-Agent-Key"].to_s v.agent_key = key v.agent_tier = "paid" if key.start_with?("paid-") ';
location / { proxy_set_header X-Agent-Key $agent_key; proxy_set_header X-Agent-Tier $agent_tier; proxy_pass http://backend; } }}A request with X-Agent-Key: paid-1 reaches the backend with X-Agent-Key: paid-1 and X-Agent-Tier: paid, and its access log line is / paid-1 paid. A request without the header reaches it with X-Agent-Tier: free and without X-Agent-Key, because proxy_set_header does not send a header whose value is empty.
mruby_output_body_filter, mruby_output_body_filter_code, mruby_output_header_filter and mruby_output_header_filter_code
Section titled “mruby_output_body_filter, mruby_output_body_filter_code, mruby_output_header_filter and mruby_output_header_filter_code”Syntax: mruby_output_body_filter /PATH/TO/YOUR/MRUBY/SCRIPT.rb [cache];Default: -Context: http, server, location, if in locationPhase:Syntax: mruby_output_body_filter_code 'YOUR MRUBY CODE HERE';Default: -Context: http, server, location, if in locationPhase:Syntax: mruby_output_header_filter /PATH/TO/YOUR/MRUBY/SCRIPT.rb [cache];Default: -Context: http, server, location, if in locationPhase:Syntax: mruby_output_header_filter_code 'YOUR MRUBY CODE HERE';Default: -Context: http, server, location, if in locationPhase:The filters are used for processing a response. The header filters are for HTTP header, the body filters are for HTTP body.
A filter given in the http block, in a server block or in a location runs in the locations, nested locations and if blocks below it that give no filter of the same kind of their own (since 3.0.0; up to 2.x, it ran only at the level of its directive, see the release notes of 3.0.0).
A level that gives a filter of one kind runs its own filter of that kind instead of the one above it, and still runs the filter of the other kind from above.
For example, every location of this server runs the header filter, and /api also runs its own body filter:
server { mruby_output_header_filter_code 'Nginx::Request.new.headers_out["X-Served-By"] = "ngx_mruby"';
location / { root html; }
location /api { mruby_content_handler /path/to/api.rb cache; mruby_output_body_filter /path/to/body_filter.rb cache; }}There is no directive that turns an inherited filter off: give the filter in the locations that should run it instead.
A body filter reads the response body with Nginx::Filter#body and can replace it with Nginx::Filter#body= (or #output).
The response then has exactly that body, and Content-Length is its length.
Since 2.7.1 this also holds when the body was written with Nginx.rputs or Nginx.echo; in 2.7.0 such a response kept the length that Nginx.rputs had produced, so a replacement body of another length was cut or padded.
In a location that a subrequest runs, such as one that an SSI page includes with <!--# include virtual=... -->, the body filter works on the body of the subrequest, and the parent response goes on after it with the rest of the page.
When the page includes more than one location, nginx sends the body of each include in the order of the page, after the includes before it.
Since 2.7.10 this also holds for an include that is not the first of the page and has a body filter, when its content handler wrote the body with Nginx.rputs or Nginx.echo, or when a rewrite handler of the location wrote with them before the request went on to the content; up to 2.7.9 the client got at most the part of the page before such an include, and nginx closed the connection after send_timeout (see the 2.7.10 release notes).
A header filter runs before the body has been read.
There Nginx::Filter#body and Nginx::Filter#body= raise a RuntimeError (#body= since 2.7.1; #body since 3.0.0, it returned an empty string from 2.7.1).
A response that ends at its header, the response to a HEAD request or a 204 or 304, sends no body after the header in a location with an output filter, and nginx keeps an otherwise reusable connection for the next request. Up to 2.7.11, nginx closed the connection after such a response when it passed a header filter in a location without a body filter, or a body filter, except a HEAD response with a known length through a body filter, which keeps its connection since 2.7.5 (see the 2.7.12 release notes).
Nginx::Async.sleep and Nginx::Async::HTTP.sub_request raise a RuntimeError in both kinds of filter (since 2.7.1), because nginx cannot resume a filter that waits.
Nginx.redirect with a local URI raises a RuntimeError in both kinds of filter and makes no internal redirect, because nginx is sending the response of the request (since 3.0.0; see the release notes of 3.0.0). A redirect with a URL sets Location and the status there, as before.
mruby_enable_read_request_body
Section titled “mruby_enable_read_request_body”Syntax: mruby_enable_read_request_body on | off;Default: offContext: server, locationPhase: initialize master processWhen set to the value on, ngx_mruby reads a HTTP request body before calling mruby code.
Due to nginx event driven nature, a request body is not always read when invoking a handler like mruby_
When the body is not complete yet, a post-read, server rewrite, rewrite, access or content handler runs once nginx has read the rest of it, and the request then goes on with the later phases, also with a phase handler that waits for a subrequest, such as auth_request.
If the client closes the connection or client_body_timeout expires first, nginx ends the request and the handler does not run; after client_body_timeout nginx closes the connection without a response, and the access log records status 408.
Before 2.7.1, a server rewrite, rewrite or content handler whose body was not complete never ran, and the client got no response; after a post-read or access handler had waited for the body, a later phase handler that waits for a subrequest, such as auth_request, was not resumed.
mruby_set and mruby_set_code handlers, log handlers and header and body filters cannot wait for the rest of the body, because nginx goes on as soon as they return.
They see the body only when it is complete before they run: when an earlier handler or module has read it, or, for HTTP/1.x with a Content-Length header, when the whole body is in the buffer that nginx read the request headers into (client_header_buffer_size, or a buffer of large_client_header_buffers when the headers needed one).
A chunked body, an HTTP/2 or HTTP/3 body, and a body of which only a part is in that buffer count as not complete, even when the rest has already arrived.
Otherwise they run without the body (Nginx::Request#body returns nil), and ngx_mruby logs that at the info level.
A body that a post-read, server rewrite, rewrite, access or content handler is still waiting for does not count as complete either: when nginx ends that read without the rest of the body (the client closes the connection, client_body_timeout expires, or nginx answers 400 or 413 to the body), a log handler or a filter that runs afterwards runs at once, without waiting for the rest, and the waiting handler does not run.
Nginx::Request#body then returns the part of the body that nginx had read before it ended the read, or nil when that part did not fit in client_body_buffer_size and nginx had written it to a temporary file.
A later handler that can wait, or a module such as proxy_pass, still reads the whole body.
To give these handlers the whole body, read it first in a handler that can wait and runs before them, such as a server-level mruby_post_read_handler_code.
Before 2.7.1, such a handler did not run its code when the body was not complete, and the body read that it had started ran the phases of the request again when it completed (since 2.7.1 it runs at once, without waiting for the rest of the body, as described above).
mruby_upstream_keepalive
Section titled “mruby_upstream_keepalive”Syntax: mruby_upstream_keepalive connections;Default: -Context: upstreamPhase: initialize master processActivates the cache for connections to upstream servers.
It’s same as ngx_
TODO: describe the difference between keepalive and mruby_
mruby_output_filter and mruby_output_filter_code (removed)
Section titled “mruby_output_filter and mruby_output_filter_code (removed)”Both directives were removed in v1.17.2. nginx -t rejects a configuration that has one of them, with the message mruby_output_filter{,_code} was deleted from v1.17.2, you should use mruby_output_body_filter{,_code} for response body, or use mruby_output_header_filter{,_code} for response headers.
Use mruby_
Stream module directives
Section titled “Stream module directives”The stream module directives run Ruby for TCP and UDP sessions in the stream {} block, which has an mruby state of its own.
nginx compiles the code of each directive once, when it reads the configuration.
Each hook takes one directive in a context: the file and the inline form of a hook are the same hook. nginx -t refuses a second one with "NAME" directive is duplicated, as for the HTTP directives: mruby_stream and mruby_stream_code in one server or in the stream block, either of them twice, and both forms (or one form twice) of mruby_stream_init, mruby_stream_init_worker or mruby_stream_exit_worker in the stream block. One mruby_stream or mruby_stream_code in the stream block and one in a server are allowed: the one of the server is its handler. mruby_stream_server_context_code runs once per directive. Before 3.0.0, the later directive of a hook replaced the earlier one without a message.
The code of mruby_stream and mruby_stream_code runs in the session’s access phase. When a UDP handler waits in Nginx::Stream::Async.sleep, later datagrams of that session do not restart it or extend its current wait. Those later payloads are discarded, not queued for the phase after the code; the first datagram remains available. See Nginx::
- mruby_
stream_ init and mruby_ stream_ init_ code - mruby_
stream_ init_ worker and mruby_ stream_ init_ worker_ code - mruby_
stream_ exit_ worker and mruby_ stream_ exit_ worker_ code - mruby_stream and mruby_
stream_ code - mruby_
stream_ server_ context_ code
nginx.conf
stream { mruby_stream_init_code ' Userdata.new.allowed = ["127.0.0.1"] ';
upstream backend { server 127.0.0.1:8080; }
server { listen 12346; mruby_stream_code ' c = Nginx::Stream::Connection c.stream_status = Nginx::Stream::ABORT unless Userdata.new.allowed.include?(c.remote_ip) '; proxy_pass backend; }}The guide Allow TCP connections in Ruby has a sample that CI runs.
mruby_stream_init and mruby_stream_init_code
Section titled “mruby_stream_init and mruby_stream_init_code”Syntax: mruby_stream_init /PATH/TO/YOUR/MRUBY/SCRIPT.rb;Default: -Context: streamPhase: initialize master processSyntax: mruby_stream_init_code 'YOUR MRUBY CODE HERE';Default: -Context: streamPhase: initialize master processThe code runs once while nginx reads the configuration, in the master process, before nginx starts the workers.
Each worker gets a copy of what it leaves in the mruby state of the stream {} block.
mruby_stream_init_worker and mruby_stream_init_worker_code
Section titled “mruby_stream_init_worker and mruby_stream_init_worker_code”Syntax: mruby_stream_init_worker /PATH/TO/YOUR/MRUBY/SCRIPT.rb;Default: -Context: streamPhase: initialize worker processSyntax: mruby_stream_init_worker_code 'YOUR MRUBY CODE HERE';Default: -Context: streamPhase: initialize worker processThe code runs in each worker process when nginx starts it, outside any session.
Session-scoped methods such as Nginx::Stream::Connection.remote_ip raise a RuntimeError here; Nginx::Stream.log writes to nginx’s error log.
mruby_stream_exit_worker and mruby_stream_exit_worker_code
Section titled “mruby_stream_exit_worker and mruby_stream_exit_worker_code”Syntax: mruby_stream_exit_worker /PATH/TO/YOUR/MRUBY/SCRIPT.rb;Default: -Context: streamPhase: exit worker processSyntax: mruby_stream_exit_worker_code 'YOUR MRUBY CODE HERE';Default: -Context: streamPhase: exit worker processThe code runs in each worker process when nginx stops it, outside any session.
mruby_stream and mruby_stream_code
Section titled “mruby_stream and mruby_stream_code”Syntax: mruby_stream /PATH/TO/YOUR/MRUBY/SCRIPT.rb;Default: -Context: stream, serverPhase: NGX_STREAM_ACCESS_PHASESyntax: mruby_stream_code 'YOUR MRUBY CODE HERE';Default: -Context: stream, serverPhase: NGX_STREAM_ACCESS_PHASEThe code runs once per session, in the access phase of the stream module, before nginx reads data from the client and before it connects to the upstream of proxy_pass.
It reads the session through Nginx::Nginx::Stream::Connection.stream_status = Nginx::Stream::ABORT.
In the stream block, the code applies to every server that has none of its own.
mruby_stream_server_context_code
Section titled “mruby_stream_server_context_code”Syntax: mruby_stream_server_context_code 'YOUR MRUBY CODE HERE';Default: -Context: serverPhase: read the configuration, in the master processThe code runs once for its server block, while nginx reads the configuration.
Nginx::Stream.add_listener adds a listen address to the server.