Ruby classes and methods
このリファレンスは英語で載せています。v3の計画では、このリファレンスを今後src/のコードから生成します。そのため、生成のたびに古くなる日本語訳は作りません。
This is the mruby API documentation for ngx_mruby.
ngx_mruby provides mruby APIs to access and manipulate nginx internal data structure.
You can use these classes and methods in handlers like mruby_content_handler_code.
Available APIs depend on your build configuration. See Configuring mrbgems and Build options for the build configuration.
ngx_mruby HTTP module
Section titled “ngx_mruby HTTP module”The ngx_mruby HTTP module is a nginx module to extend the HTTP server by mruby and the core of ngx_mruby.
Notice: ngx_mruby_mrblib is a required mrbgem and a part of The HTTP module. The classes and methods provided by ngx_mruby_mrblib are documented here.
- Kernel Module
- Nginx Class
- Nginx::
SSL Class - Nginx::
Request Class - Nginx::
Server Class - Nginx::
Connection Class - Nginx::
Var Class - Nginx::
Headers_in Class - Nginx::
Headers_out Class - Nginx::
Filter Class - Nginx::
Upstream Class - Nginx::
Async Class - Nginx::
Async:: HTTP Class
ngx_mruby stream module
Section titled “ngx_mruby stream module”The ngx_mruby stream module is an optional nginx module to handle TCP and UDP stream.
Where the methods work
Section titled “Where the methods work”Each method works in the handlers that the table names. Since 3.0.0, a
method of the HTTP module called in another handler of a request raises a
RuntimeError whose message names the method and the handler, for example
Nginx::Headers_out#[]= is not available in a log handler; it does not
return as if it had worked. The handler then ends as after any other
exception. Methods that have no effect in a handler raise a RuntimeError there
in the release notes of 3.0.0 lists what raised before.
The handlers of a request are mruby_set and mruby_set_code (an mruby_set
handler); the post_read, server rewrite, rewrite, access and content handlers
(the phase handlers); the log handlers; and the output header and body filters.
| Methods | Where they work | Elsewhere in a request |
|---|---|---|
Reading the request: the getters of Nginx::Request (uri, args, method, get_body and the others), Nginx::Headers_in#[] and #all, Nginx::Headers_out#[] and #all, the reads of Nginx::Var, Nginx::Connection, the getters of Nginx::Server |
every handler and filter of a request | none |
Changing the request: Nginx::Request#uri=, #args=, #method=, #request_line=, Nginx::Headers_in#[]= and #delete |
an mruby_set handler and the phase handlers | log handlers, header filters and body filters raise |
Assigning variables: Nginx::Var#NAME=, Nginx::Var#set |
every handler and filter of a request | none |
The head of the response: Nginx::Headers_out#[]= and #delete, Nginx.status_code=, Nginx.return and Nginx.send_header with a status (a value from 0 up), Nginx::Request#content_type= |
every handler and filter of a request but a log handler, while nginx has not sent the response header | log handlers raise, and so do the other handlers once nginx has sent the response header (... is not available after the response header is sent) |
Output: Nginx.rputs, Nginx.echo |
the phase handlers and body filters | mruby_set handlers, log handlers and header filters raise |
The body of a body filter: Nginx::Filter#body, #body=, #output |
body filters | every other handler raises (... can only be used in an output body filter) |
Nginx.redirect |
with a URL, every handler and filter of a request; with a local URI, the phase handlers (see Nginx.redirect) | a local URI raises in mruby_set handlers, log handlers, header filters and body filters, and in Ruby code of a phase handler that runs outside its fiber |
Nginx::Async.sleep, Nginx::Async::HTTP.sub_request |
see Nginx:: |
log handlers, header filters and body filters raise; sub_request also in an mruby_set handler |
Nginx.return and Nginx.send_header with a return code below 0 (Nginx::DECLINED), Nginx::Request#unparsed_uri=, #protocol=, Nginx::Upstream, Nginx::Async::HTTP.last_response, Nginx::Request#sub_request?, Nginx::Request#store |
every handler and filter of a request | none |
Nginx.log, Nginx.errlogger, the constants, Nginx.module_name and the other methods that need no request |
everywhere | none |
Outside a request, in the code of mruby_init*, mruby_init_worker*,
mruby_exit_worker*, mruby_ssl_handshake_handler* and
mruby_server_context_handler_code, the methods of the rows that need a
request raise this method can only be used while processing a request, as
since 2.7.1 (see Nginx.errlogger).
Nginx::SSL works only in mruby_ssl_handshake_handler*, and
Nginx::Server#add_listener only in mruby_server_context_handler_code.
In the stream module, the methods of a session (Nginx::Stream::Connection
and Nginx::Stream::Async.sleep) work in mruby_stream and
mruby_stream_code, and raise this method can only be used while processing a stream session elsewhere; Nginx::Stream.add_listener works
only in mruby_stream_server_context_code.
rack-based-api mrbgem
Section titled “rack-based-api mrbgem”The rack-based-api mrbgem is an optional bundled mrbgem. It provides RACK (Ruby Webserver Interface) compatible APIs to make development and testing easier.
auto-ssl mrbgem
Section titled “auto-ssl mrbgem”ngx_mruby 3.0.0 does not have the auto-ssl mrbgem (Nginx::SSL::ACME::Client
and Nginx::SSL::ACME::Dehydrated). The
documentation of 2.x describes it, and
The auto-ssl mrbgem and NGX_MRUBY_AUTO_SSL are removed
says why it was removed and what to use instead.
Add classes and methods reference.
Section titled “Add classes and methods reference.”built-in mrbgems
Section titled “built-in mrbgems”The default build adds the classes of the mrbgems that Default mrbgems in the build reference lists, with the class of each gem and a link to the repository that documents it.
Dir comes from the mruby core gem mruby-dir
(mruby/mrbgems/mruby-dir). ngx_mruby 2.x took it from
iij/mruby-dir, which the core gem started from; every method of that gem
stays. The differences:
- Reading or closing a closed
DirraisesIOErrorinstead ofRuntimeError. Dir.openwith a block no longer raises when the block closed theDir.Dir.foreachwith a block closes theDirthat it opened.DirincludesEnumerable, and hasDir.children,Dir.empty?andDir#each_child. With the bundled mruby 4.1.0-rc2,Dir.childrenandDir#each_childleave out.and.., as in CRuby. (With mruby 3.3.0 they were aliases ofDir.entriesandDir#eachand included them.)
ENV and Process come from the mruby core gems mruby-env and
mruby-process, and Signal from mruby-signal, which mruby-process depends
on. ngx_mruby 2.x took ENV and Process from iij/mruby-env and
iij/mruby-process. The differences:
ENV.to_hashis gone;ENV.to_hreturns the variables as a Hash.ENVincludesEnumerable.Process.fork,Kernel#forkandKernel#systemare gone.Processhasclock_gettime,times,waitandwait2.exitin a handler raisesSystemExit, and the handler answers 500; with 2.x it ended the worker process.sleepwithout an argument raisesArgumentError; with 2.x it waited until a signal came.
Digest and SecureRandom come from two gems of this repository,
mrbgems/digest and mrbgems/secure-random, described below. ngx_mruby
2.x took them from iij/mruby-digest and monochromegane/mruby-secure-random.
Vedis (matsumotory/mruby-vedis) and Cache
(matsumotory/mruby-localmemcache), which the default build of 2.x has, are
not in the default build of 3.0.0. The entries of these changes are under
Behavior changes: read before upgrading
in the release notes of v3.0.0.
The Redis class was left out of the default build in 2.7.1 and is in it again since 2.7.2 (see “Redis is in the default build again” in the 2.7.2 release notes).
You can also use the classes of the mruby core gems that NGX_MRUBY_CORE_GEMS in
build_config.rb lists (the gems in mruby/mrbgems
of that name). Core gems in the install
guide says which core gems of mruby 4.1.0-rc2 are in the list, which are
left out and why. The changes that the bundled mruby brings to scripts are listed
under Behavior changes: read before upgrading
in the release notes of v3.0.0, and
Migrating from ngx_mruby 2.x to 3.0.0 has the
steps for finding and changing the scripts that they affect.
Digest
Section titled “Digest”mrbgems/digest computes the hashes with the EVP API of OpenSSL 3 and
HMAC with its EVP_MAC API. It has the classes and methods of
iij/mruby-digest, the gem of 2.x:
Digest::MD5,Digest::RMD160,Digest::SHA1,Digest::SHA256,Digest::SHA384andDigest::SHA512are subclasses ofDigest::Base.Digest::Base.newraisesNotImplementedError.newof a class whose algorithm the OpenSSL of the process does not provide raisesNotImplementedErroras well: RIPEMD160 is in the default provider of OpenSSL since 3.0.7, and the FIPS provider has no MD5.- The class methods
digest(data)andhexdigest(data)return the digest of a String, as bytes or as lowercase hexadecimal digits.file(path)returns a new object that has taken the content of the file. - The instance methods:
update(data)and<<add a String and return the object.digest,hexdigestandto_sreturn the digest of the data so far, and the object can take more data afterwards.digest!andhexdigest!return the digest and reset the object, andresetresets it.file(path)adds the content of a file.digest_length,lengthandsizereturn the length of the digest in bytes, andblock_lengththe block size of the hash.==compares the digest with that of another object, or the hexdigest with a String.dupandclonecopy the data that the object has taken. Digest::HMAC.new(key, digest_class)takes the class of the hash, for exampleDigest::SHA256. An HMAC object hasupdate,<<,digest,hexdigest,digest_lengthandblock_length, anddigestandhexdigestleave it as it was.dupandcloneraiseRuntimeError.Digest::HMAC.digest(data, key, digest_class)andDigest::HMAC.hexdigest(data, key, digest_class)compute the HMAC of a String in one call.
Digest::SHA256.hexdigest("abc")# => "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"Digest::HMAC.hexdigest("what do ya want for nothing?", "Jefe", Digest::SHA256)# => "5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843"file reads the whole file in the worker when a script calls it. The
differences from iij/mruby-digest are in the entry
Digest and SecureRandom come from gems of ngx_mruby that need OpenSSL 3.0 or later
of the release notes of v3.0.0.
SecureRandom
Section titled “SecureRandom”mrbgems/secure-random takes the random bytes from RAND_bytes of
OpenSSL. OpenSSL seeds its generator from the operating system, and seeds
it again in each worker process that nginx forks. A call opens no file. It
has the methods of monochromegane/mruby-secure-random, the gem of 2.x, as
class methods of the class SecureRandom. In the first four, n is a
number of bytes, 16 when it is nil or not given, and is converted with
to_int:
random_bytes(n)returnsnrandom bytes.hex(n)returnsnbytes as2 * nlowercase hexadecimal digits.base64(n)returnsnbytes in Base64, with padding and without line breaks.urlsafe_base64(n, padding = false)returnsbase64(n)with-and_in place of+and/, and without=unlesspaddingis true.random_number(n)returns an Integer of 0 or more and less thann, for an Integernof 1 or more.nof 0 or less raisesNotImplementedError, and a Float raisesArgumentError.uuidreturns a random UUID of version 4, in lowercase.
The other methods call random_bytes through self, so a subclass of
SecureRandom that redefines random_bytes changes them too. The
differences from monochromegane/mruby-secure-random are in the same entry
of the release notes.
Kernel Module
Section titled “Kernel Module”ngx_mruby HTTP module adds two methods to Kernel module. These methods are called without a receiver.
Both are provided to write portable code for mod_mruby.
Module Methods
Section titled “Module Methods”get_server_class -> class_object
Section titled “get_server_class -> class_object”Returns server software class Nginx.
Server = get_server_class
Server.echo "hello world" # Nginx.echo is calledserver_name -> string
Section titled “server_name -> string”Returns server software name NGINX as a string.
if server_name == "NGINX" Server = Nginxelsif server_name == "Apache" Server = ApacheendNginx Class
Section titled “Nginx Class”Class Methods
Section titled “Class Methods”Nginx.rputs(string)
Section titled “Nginx.rputs(string)”Puts response text. In an mruby_set* handler, a log handler and a header filter, Nginx.rputs and Nginx.echo raise a RuntimeError (Nginx.rputs is not available in a log handler) before they keep any text (since 3.0.0; on 2.x a log handler converted the argument and wrote no response bytes, and the other two added the text to the output of a later handler; see Where the methods work). Use Nginx.log to write to the error log.
If a post-read, server rewrite, rewrite, access or content handler raises an exception afterwards, the request gets 500 and the text is not sent, unless the response was already started, for example by the location that Nginx.redirect ran.
Since 2.7.1 this also holds for a handler that raises before it waits in Nginx::Async; in 2.7.0 such a handler sent the text with status 200.
In an output body filter, the text is not sent after an exception either, and the request goes on as after an exception without output: Content-Length does not count the text (since 2.7.1).
For an mruby_set* handler this holds when the code raises before it waits in Nginx::Async.sleep. When it raises after the sleep, the request gets 500, as described under Nginx::Nginx::Async::HTTP.sub_request raises a RuntimeError in an mruby_set* handler (since 3.0.0; on 2.x nginx went on without waiting for the variable, and an exception after the call left the client without a response; see the release notes of 3.0.0).
To end a content handler early after writing the text, leave it with return instead of raise.
In a post_read or access handler, the text ends the request: nginx sends the response and does not go on with the phases, with or without Nginx::Async.sleep before. Since 3.0.0; on 2.x, such a handler that did not wait sent the response and nginx then went on with the next handlers, and closed the connection when the content phase tried to answer once more (see the release notes of 3.0.0).
Nginx.rputs "hello ngx_mruby world!"An argument that is not a String is converted with to_s, so Nginx.rputs nil
writes nothing, as print nil does in CRuby. A content handler that writes
nothing and sets no status answers 200 with an empty body (see
Nginx.return).
When to_s is missing (a BasicObject, for example) or raises, Nginx.rputs
raises that exception (NoMethodError when to_s is missing), and since
2.7.6 a to_s that returns something other than a String makes it raise
TypeError; up to 2.7.5 such a to_s could end the worker process. In each
case nothing is written.
Nginx.echo(string)
Section titled “Nginx.echo(string)”Puts response text with a newline.
Like Nginx.rputs, the text is not sent when the handler raises an exception afterwards (since 2.7.1).
An argument that is not a String is converted with to_s as for Nginx.rputs, which raises the same exceptions when it cannot be converted.
Nginx.echo "hello ngx_mruby world!"is equal to
Nginx.rputs "hello ngx_mruby world!\n"Nginx.return(nginx_status_code)
Section titled “Nginx.return(nginx_status_code)”Returns nginx status code to send back HTTP status to the client or control nginx request processing flow. The status code consists of nginx internal status and HTTP status.
Nginx.return Nginx::HTTP_SERVICE_UNAVAILABLE # returns HTTP status 503The value is the result of the handler that calls it, not of the later handlers of the request (since 3.0.0).
A handler that calls none of Nginx.return, Nginx.send_header and Nginx.status_code= has no result, whatever an earlier handler of the request returned: a content handler of the main request without output answers 200 with an empty body (below), and a post_read or access handler goes on as with Nginx::OK.
On 2.x, a handler without a result returned the value that an earlier handler of the request had set, for example the Nginx::DECLINED of a server rewrite handler that runs for every request, so that a content handler without output went on to the next content handler (see the release notes of 3.0.0).
A rewrite or server rewrite handler without a result, or with Nginx::OK, goes on to the next phase handler, as with Nginx::DECLINED (since 3.0.0; on 2.x nginx ended the request without a response, see the release notes of 3.0.0).
A return code below 0, such as Nginx::DECLINED, is the result of the handler only: it does not change the status of the response.
With a status from 0 up, the method raises a RuntimeError in a log handler (Nginx.return is not available in a log handler) and in any handler that runs after nginx has sent the response header (... is not available after the response header is sent), where the status would not reach the client (since 3.0.0; see Where the methods work). A return code below 0 works there. The status of the response in the log phase stays the one that was sent: when a log handler ends, it is put back, also after an exception (see mruby_
A content handler that ends without output answers as nginx’s return 200;
does: with the status it set, 200 when it set none, Content-Length: 0 and an
empty body, and nginx keeps a keep-alive connection for the next request. It
sends no Content-Type, as the answers with output do not; nginx’s
return 200; sends the one of default_type. A
request body that no handler read is discarded before the empty answer, as
before an answer with output. This
covers Nginx::HTTP_OK and the other statuses from 200 to 299 that nginx does
not answer by itself (for example Nginx::HTTP_ACCEPTED), a handler that
writes nothing or only "" or nil with Nginx.rputs, and a handler that only
sets response headers. A HEAD request gets the same header, and the output
filters of the location run on the empty response. After the header of a
HEAD request, nginx keeps an otherwise reusable connection for the next
request, also in a location with an mruby output header or body filter, as
it does there for a handler with output. nginx answers
Nginx::HTTP_CREATED, Nginx::HTTP_NO_CONTENT (204 without a body) and the
statuses from 300 up by itself, for example with its error page. A status below
200 without output answers 500 with nginx’s error page, and error.log gets a
line at the error level that ends with
response body is empty. return NGX_HTTP_INTERNAL_SERVER_ERROR.
location /empty { mruby_content_handler_code 'Nginx.return Nginx::HTTP_OK'; # 200 with Content-Length: 0}In the other handlers, for example a rewrite or an access handler,
Nginx::HTTP_OK without output answers 500 with nginx’s error page and logs
that line. In the content handler of a subrequest
(Nginx::Async::HTTP.sub_request, an SSI include, auth_request),
Nginx::HTTP_OK without output sets the status of the subrequest to 500 and
logs that line too. A content handler of a subrequest that writes nothing and
sets no status or another status below 300 ends the subrequest without a
response body, and the parent request answers.
On the 2.x line, a content handler that ends without output and with no status or a status from 200 to 299 that nginx does not answer by itself answers 500 instead (see docs/releases/v3.0.0.md).
A handler that writes output with Nginx.rputs or Nginx.echo and calls
Nginx.return (or Nginx.send_header, Nginx.status_code=) before or after
the output sends the output with that status; when it calls them more than
once, the last call decides. This holds for post_read, server rewrite,
rewrite, access and content handlers, on the main request and in
subrequests, also after Nginx::Async::HTTP.sub_request resumed the
handler:
- A status from 200 up, other than
Nginx::HTTP_CLOSE(below): the output goes out with that status and theContent-Lengthof the output, like nginx’s ownreturn 401 "text";without itsContent-Type. Anerror_pageof the location for the status does not apply to this response, as it does not apply to nginx’sreturnwith a text. For 301, 302, 303, 307 and 308, ngx_mruby adds noLocation: set it with Nginx::Headers_out when the client needs it. ForNginx::HTTP_NO_CONTENTandNginx::HTTP_NOT_MODIFIED, nginx sends the header without the output. The 304 keeps theContent-Lengthof the output, as nginx’s ownreturn 304 "text";does. A HEAD request gets the header, with theContent-Lengthof the output. - A status below 200: 500 with nginx’s error page, without the output.
error.log gets a line at the error level that ends with
with the output is not the status of a final response. return NGX_HTTP_INTERNAL_SERVER_ERROR. Nginx::HTTP_CLOSE(444), nginx’s value for closing a connection without a response: the output is not sent, and nginx closes the connection, as for 444 without output. In a subrequest, this closes the connection of the client, as nginx’s ownreturn 444does there.Nginx.redirectwith a URL after the output: the output goes out with 200 and theLocation, also when a status was set before the output.Nginx.return 0sets no status, and the output of a content handler gets 200.- A return code below 0, such as
Nginx::DECLINED, after the output: the output is not sent, and the phase gets the code. Before the output, such a code does not apply to it.
location /api { mruby_access_handler_code ' Nginx.rputs %({"error":"no key"}) Nginx.return Nginx::HTTP_UNAUTHORIZED # 401 with the JSON, not the error_page '; error_page 401 /401.html;}To answer with nginx’s own response for a status, and with the
error_page of the location, set the status without output:
Nginx.return Nginx::HTTP_UNAUTHORIZED alone answers nginx’s 401 page, or
/401.html in the location above.
This is the behavior since 3.0.0 (see
the release notes of 3.0.0).
On the 2.x line, a status set before the first Nginx.rputs or
Nginx.echo does not apply to the output, which is sent with 200, and only a
content handler on the main request sends its output with a status set
after it, for Nginx::HTTP_OK and the statuses below 300 other than
Nginx::HTTP_CREATED and Nginx::HTTP_NO_CONTENT, a status below 200
included (since 2.7.2). For Nginx::HTTP_CREATED, Nginx::HTTP_NO_CONTENT
and the statuses from 300 up, nginx drops the output and sends its own
response for the status, through the error_page of the location. In the
other handlers and in subrequests, the output is sent only with
Nginx::HTTP_OK or without a status set after it.
Don’t confuse Nginx.return method with mruby’s return statement.
ngx_mruby supports return statement in handler code as below.
It just returns from the handler. Since 3.0.0 this holds also for a return
inside a block or the body of for at the top level of the code: the code
after it does not run, and the response is the one that the code set before
it (see the release notes of 3.0.0).
location /foo { mruby_content_handler_code ' Nginx.rputs "foo" # generates HTTP body "foo" Nginx.return Nginx::HTTP_OK # returns HTTP status 200 return if true # returns from this handler Nginx.rputs "bar" # not reached ';}In 2.x, a return inside a block or inside the body of for at the top
level of handler code does not return from the handler: mruby 3.3.0, which
2.x bundles, raises LocalJumpError (unexpected return) there, and
error.log records it as mrb_run failed. The handler then fails as after any
other exception: a rewrite or content handler answers 500, and the output
that the code wrote before the return is not sent (2.7.0 sent it with 200;
see Nginx.rputs). On both versions, calling
Nginx.return in a block does not end the code: it sets the status, and the
code after the block still runs. To end the handler from a block in code
that runs on 2.x as well as on 3.0.0, leave the block with break and
return at the top level of the code, or put the code in a method (or in a
lambda, ->() do ... end.call) and call it, so that the return returns
from the method or the lambda:
location /foo_break { mruby_content_handler_code ' done = false ["foo"].each do |body| Nginx.rputs body # generates HTTP body "foo" Nginx.return Nginx::HTTP_OK # returns HTTP status 200 done = true break # leaves the block end return if done # returns from this handler Nginx.rputs "bar" # not reached ';}
location /foo_method { mruby_content_handler_code ' def foo ["foo"].each do |body| Nginx.rputs body # generates HTTP body "foo" Nginx.return Nginx::HTTP_OK # returns HTTP status 200 return # returns from the method foo end Nginx.rputs "bar" # not reached end foo ';}Nginx.send_header(nginx_status_code)
Section titled “Nginx.send_header(nginx_status_code)”Alias for Nginx.return
Nginx.status_code=(nginx_status_code)
Section titled “Nginx.status_code=(nginx_status_code)”Alias for Nginx.return
Nginx.errlogger(log_level, string)
Section titled “Nginx.errlogger(log_level, string)”Sends an error to the log file via ngx_
Nginx.errlogger Nginx::LOG_ERR, "ngx_mruby error!"You will see an error message in error.log as below.
2014/03/03 00:07:09 [error] 37667#0: *2 ngx_mruby error!, client: 192.168.12.9, server: localhost, request: "GET /log-test HTTP/1.1", host: "192.168.12.9:8001"The code of mruby_init*, mruby_init_worker*, mruby_exit_worker*, mruby_ssl_handshake_handler* and mruby_server_context_handler_code runs outside a request.
There the method writes the message to nginx’s error log, without the client and request part (since 2.7.1; 2.7.0 raised a RuntimeError when the process had not handled a request yet, and otherwise wrote through the last request that the process had handled).
Code outside a request can also call Nginx.module_name, Nginx.module_version, Nginx.nginx_version, Nginx.server_version, Nginx.configure, Nginx.remove_global_variable and server_name, use the constants, and use classes that do not depend on a request, such as Userdata.
Since 2.7.1 the request-scoped methods raise a RuntimeError (this method can only be used while processing a request) there: the methods of Nginx::Request, Nginx::Var, Nginx::Headers_in, Nginx::Headers_out, Nginx::Connection, Nginx::Server, Nginx::Filter, Nginx::Upstream and Nginx::Async, and Nginx.rputs, Nginx.echo, Nginx.return, Nginx.send_header, Nginx.status_code= and Nginx.redirect.
In 2.7.0 they crashed the process when it had not handled a request yet, and otherwise returned or changed data of the last request that the process had handled.
Nginx::Server#add_listener works only in mruby_server_context_handler_code, and Nginx::SSL only in mruby_ssl_handshake_handler*.
Nginx.log(log_level, string)
Section titled “Nginx.log(log_level, string)”Alias for Nginx.errlogger.
Outside a request it writes to nginx’s error log, as described under Nginx.errlogger (since 2.7.1).
Nginx.module_name -> string
Section titled “Nginx.module_name -> string”Returns module name ngx_mruby.
Nginx.echo Nginx.module_name #=> ngx_mrubyNginx.module_version -> string
Section titled “Nginx.module_version -> string”Returns ngx_mruby version as a string. 2.7.2 to 2.7.8 return 2.7.1, not their own version; from 2.7.9 on, it is the version of the release (v2.7.9.md). 3.0.0 and its alpha, beta and rc pre-releases return 3.0.0 (v3.0.0.md).
Nginx.echo Nginx.module_version #=> 3.0.0Nginx.nginx_version -> string
Section titled “Nginx.nginx_version -> string”Returns nginx version as a string.
Nginx.echo Nginx.nginx_version #=> 1.4.4Nginx.server_version -> string
Section titled “Nginx.server_version -> string”Returns server software version as a string. Alias for Nginx.nginx_version.
It’s provided to write portable code for mod_mruby.
Nginx.configure -> string
Section titled “Nginx.configure -> string”Returns nginx build configuration as a string. It’s same as output of nginx -V configure arguments.
Nginx.echo Nginx.configure #=> --add-module=/home/matsumoto_r/DEV/ngx_mruby \ # --add-module=/home/matsumoto_r/DEV/ngx_mruby/dependence/ngx_devel_kit \ # --prefix=/usr/local/nginx-1.4.4Nginx.redirect(url_or_internal_location, http_status=Nginx::HTTP_MOVED_TEMPORARILY)
Section titled “Nginx.redirect(url_or_internal_location, http_status=Nginx::HTTP_MOVED_TEMPORARILY)”Redirects to the URL or the internal location. It is designed to be used in the rewrite handlers.
A url_or_internal_location that is not a String is converted with to_s. When to_s is missing or raises, Nginx.redirect raises that exception, and since 2.7.6 a to_s that returns something other than a String makes it raise TypeError; up to 2.7.5 such a to_s could end the worker process. In each case no redirect is made.
The URL redirect returns HTTP status codes 3xx like 307 Temporary Redirect with Location header to the client.
The http_status of a URL redirect must be an Integer. Since 2.7.8, another value, nil included, makes Nginx.redirect raise TypeError (String cannot be converted to Integer, with the class of the value) and no redirect is made; up to 2.7.7 such a value gave a status line without a valid status, or no response for nil. An internal redirect has no status code and ignores http_status.
Nginx.redirect takes one or two arguments. Since 2.7.8, a third argument makes it raise ArgumentError (wrong number of arguments (given 3, expected 1..2)) and no redirect is made; up to 2.7.7 a call with three arguments raised no error, and its result was not defined.
Nginx.redirect "http://ngx.mruby.org/", Nginx::HTTP_MOVED_PERMANENTLYThe internal redirect never returns response to the client. The original request is internally forwarded to other location, then the location returns to a response to the client. See error_page and internal directives, and Creating NGINX Rewrite Rules for more about the internal redirect.
In a post_read, server rewrite, rewrite, access or content handler, the internal redirect takes effect when the handler ends (since 3.0.0): the code after the call runs first, and then nginx runs the phases of the other location, whose handlers answer the request and can wait like any handler.
The output and the status that the handler writes or sets are not sent; when the code writes output or sets a status after the call, error.log gets a line at the warn level that ends with set after Nginx.redirect are not sent.
Response headers that the handler sets, and changes that it makes to the request such as its arguments (Nginx::Request#args=), stay, also after the call: the answer of the other location carries those headers, and that location sees those arguments.
When the handler raises an exception, the request gets 500, and the redirect does not take effect.
When an mruby handler or filter of the other location raises an exception, the exception ends that handler as it does without the redirect: the request gets 500 unless its response was already started.
On 2.x the internal redirect ran the handlers of the other location before the call returned, and the calling handler went on after the call and could answer the request as well (see the release notes of 3.0.0).
In a log handler, Nginx.redirect with a local URI raises a RuntimeError and makes no internal redirect (since 3.0.0; see the release notes of 3.0.0); a URL works there as before.
In an mruby_set* handler, an output header filter and an output body filter, Nginx.redirect with a local URI raises a RuntimeError as well (Nginx.redirect with a local URI is not available in an mruby_set handler, ... in a header filter, ... in a body filter) and makes no internal redirect (since 3.0.0; see the release notes of 3.0.0); a URL works there as before. On 2.x these handlers ran the handlers of the other location before the call returned. To send the request to another location, call Nginx.redirect from a rewrite or access handler.
Ruby code that ngx_mruby runs for a phase handler outside the handler’s fiber, such as an inspect or a backtrace that an exception class redefines, has no end that could take the redirect, and the call raises there too (Nginx.redirect with a local URI is not available without a running handler fiber, since 3.0.0).
location /secret-location { internal; mruby_content_handler_code ' r = Nginx::Request.new Nginx.echo "Returns from /secret-location." Nginx.return Nginx::HTTP_OK ';}
location /public-location { mruby_content_handler_code ' Nginx.redirect "/secret-location" ';}Nginx.remove_global_variable
Section titled “Nginx.remove_global_variable”Removes a mruby’s global variable.
$a = 1Nginx.echo global_variables #=> [:$stdout, :$$, :$/, :$stdin, :$?, :$a, :$stderr, :$1, :$2, :$3, :$4, :$5, :$6, :$7, :$8, :$9]Nginx.remove_global_variable :$aNginx.echo global_variables #=> [:$stdout, :$$, :$/, :$stdin, :$?, :$stderr, :$1, :$2, :$3, :$4, :$5, :$6, :$7, :$8, :$9]Constants
Section titled “Constants”Constants for log levels
Section titled “Constants for log levels”Log levels for Nginx.errlogger that mirror nginx error log levels.
See nginx log levels and
core/ngx_log.h.
| Name | Description |
|---|---|
| Nginx:: |
Defined in core/ngx_log.h, but it’s never used |
| Nginx:: |
Emergency error log level |
| Nginx:: |
Alert error log level |
| Nginx:: |
Critical error log level |
| Nginx:: |
Error log level |
| Nginx:: |
Warning log level |
| Nginx:: |
Notice log level |
| Nginx:: |
Information log level |
| Nginx:: |
Debug log level |
Constants for HTTP status
Section titled “Constants for HTTP status”HTTP status and internal nginx status for Nginx.return.
See nginx HTTP Return Codes for the HTTP statuses.
The statuses from Nginx::OK (0) to Nginx::ABORT (-6) are internally used to control nginx processing flow.
They are defined in core/ngx_core.h.
| Name | Value |
|---|---|
| Nginx:: |
0 |
| Nginx:: |
-1 |
| Nginx:: |
-2 |
| Nginx:: |
-3 |
| Nginx:: |
-4 |
| Nginx:: |
-5 |
| Nginx:: |
-6 |
| Nginx:: |
100 |
| Nginx:: |
101 |
| Nginx:: |
102 |
| Nginx:: |
200 |
| Nginx:: |
201 |
| Nginx:: |
202 |
| Nginx:: |
204 |
| Nginx:: |
206 |
| Nginx:: |
300 |
| Nginx:: |
301 |
| Nginx:: |
302 |
| Nginx:: |
303 |
| Nginx:: |
304 |
| Nginx:: |
307 |
| Nginx:: |
400 |
| Nginx:: |
401 |
| Nginx:: |
403 |
| Nginx:: |
404 |
| Nginx:: |
405 |
| Nginx:: |
408 |
| Nginx:: |
409 |
| Nginx:: |
411 |
| Nginx:: |
412 |
| Nginx:: |
413 |
| Nginx:: |
414 |
| Nginx:: |
415 |
| Nginx:: |
416 |
| Nginx:: |
429 |
| Nginx:: |
444 |
| Nginx:: |
494 |
| Nginx:: |
494 |
| Nginx:: |
495 |
| Nginx:: |
496 |
| Nginx:: |
497 |
| Nginx:: |
499 |
| Nginx:: |
500 |
| Nginx:: |
501 |
| Nginx:: |
502 |
| Nginx:: |
503 |
| Nginx:: |
504 |
| Nginx:: |
507 |
Nginx::SSL Class
Section titled “Nginx::SSL Class”Nginx::RuntimeError when they are called anywhere else, for example in mruby_content_handler_code; in 2.7.0 such a call could crash the worker or return meaningless values.
A handshake whose code sets no certificate, also one whose code does not call Nginx::SSL.new, uses the server’s ssl_certificate and ssl_certificate_key (since 2.7.1; in 2.7.0 a handshake whose code did not call Nginx::SSL.new could get the certificate that an earlier handshake on the same worker had set, or fail).
Instance Methods
Section titled “Instance Methods”Nginx::SSL#servername -> string
Section titled “Nginx::SSL#servername -> string”Returns the SNI server name from the client. The client chooses this name, Treat it as untrusted input (see Trust boundary): look it up in a table of known names, and do not build a path from it.
http { mruby_init_code ' CERT_DIRS = { "example.com" => "/etc/nginx/certs/example.com", "www.example.com" => "/etc/nginx/certs/www.example.com", } ';
server { listen 443 ssl; ssl_certificate /etc/nginx/certs/default.crt; ssl_certificate_key /etc/nginx/certs/default.key;
mruby_ssl_handshake_handler_code ' ssl = Nginx::SSL.new dir = CERT_DIRS[ssl.servername] if dir ssl.certificate = "#{dir}/cert.pem" ssl.certificate_key = "#{dir}/key.pem" end '; }}The lookup is exact: the name is compared as the client sent it, including its case. A name that is not in CERT_DIRS, also an empty name from a client that sends none, keeps the certificate of ssl_certificate and ssl_certificate_key.
Nginx::SSL#certificate=(string)
Section titled “Nginx::SSL#certificate=(string)”Sets the certificate file path used for the connection. The worker reads the file during the handshake. Take the path from a table, not from the server name.
mruby_ssl_handshake_handler_code ' ssl = Nginx::SSL.new dir = CERT_DIRS[ssl.servername] if dir ssl.certificate = "#{dir}/cert.pem" ssl.certificate_key = "#{dir}/key.pem" end';CERT_DIRS is the table of the example under servername.
Nginx::SSL#certificate_key=(string)
Section titled “Nginx::SSL#certificate_key=(string)”Sets the certificate key file path used for the connection.
Set it together with certificate=; the handshake changes the certificate only when both are set.
Take the path from a table, not from the server name.
mruby_ssl_handshake_handler_code ' ssl = Nginx::SSL.new dir = CERT_DIRS[ssl.servername] if dir ssl.certificate = "#{dir}/cert.pem" ssl.certificate_key = "#{dir}/key.pem" end';CERT_DIRS is the table of the example under servername.
Nginx::SSL#certificate_data=(string)
Section titled “Nginx::SSL#certificate_data=(string)”Sets the certificate data used for the connection, as a string in PEM format (the certificate, then its chain).
Read the files once in the init code, so that the handshake does not read a file, and look the data up by server name.
The init code runs once, so a certificate that changes on disk reaches the handshake after nginx -s reload.
http { mruby_init_code ' CERT_DATA = {} ["example.com", "www.example.com"].each do |name| CERT_DATA[name] = [ File.read("/etc/nginx/certs/#{name}/cert.pem"), File.read("/etc/nginx/certs/#{name}/key.pem"), ] end ';
server { listen 443 ssl; ssl_certificate /etc/nginx/certs/default.crt; ssl_certificate_key /etc/nginx/certs/default.key;
mruby_ssl_handshake_handler_code ' ssl = Nginx::SSL.new data = CERT_DATA[ssl.servername] if data ssl.certificate_data = data[0] ssl.certificate_key_data = data[1] end '; }}Nginx::SSL#certificate_key_data=(string)
Section titled “Nginx::SSL#certificate_key_data=(string)”Sets the certificate key data used for the connection, as a string in PEM format.
Set it together with certificate_data=; the handshake changes the certificate by data only when both are set, and then it does not use the paths.
mruby_ssl_handshake_handler_code ' ssl = Nginx::SSL.new data = CERT_DATA[ssl.servername] if data ssl.certificate_data = data[0] ssl.certificate_key_data = data[1] end';CERT_DATA is the table of the example under certificate_data=.
Nginx::SSL.errlogger(log_level, string)
Section titled “Nginx::SSL.errlogger(log_level, string)”Sends an error to the log file via ngx_
Nginx::SSL.errlogger Nginx::LOG_ERR, "ngx_mruby error!"Nginx::SSL.log(log_level, string)
Section titled “Nginx::SSL.log(log_level, string)”Alias for Nginx::
Nginx::SSL#local_port -> integer
Section titled “Nginx::SSL#local_port -> integer”Returns the port number used for the connection.
mruby_ssl_handshake_handler_code ' ssl = Nginx::SSL.new Userdata.new.ssl_local_port = ssl.local_port';
location /local_port { mruby_content_handler_code "Nginx.rputs Userdata.new.ssl_local_port.to_s";}Nginx::SSL#tls_version -> string
Section titled “Nginx::SSL#tls_version -> string”Returns the name of the protocol like TLSv1.3 used for the connection.
This is a wrapper for SSL_get_version(). See SSL_
mruby_ssl_handshake_handler_code ' ssl = Nginx::SSL.new Userdata.new.ssl_tls_version = ssl.tls_version';
location /tls_version { mruby_content_handler_code "Nginx.rputs Userdata.new.ssl_tls_version.to_s";}Nginx::Request Class
Section titled “Nginx::Request Class”Instance Methods
Section titled “Instance Methods”Nginx::Request#scheme -> string
Section titled “Nginx::Request#scheme -> string”Returns the scheme name of the requested URL.
# curl https://127.0.0.1/
r = Nginx::Request.newr.scheme #=> httpsNginx::Request#content_type=(string)
Section titled “Nginx::Request#content_type=(string)”Set the content type to the response.
Notice: Unlike the name suggests, Nginx::Request#content_type=() and Nginx::Request#content_type() handle HTTP response, not request.
location /foo { mruby_content_handler_code ' r = Nginx::Request.new r.content_type = "text/plain" Nginx.rputs "This is a plain text" ';}% curl -v http://127.0.0.1:58080/foo
[snip]
< HTTP/1.1 200 OK< Date: Thu, 29 Nov 2018 07:55:22 GMT< Content-Type: text/plain< Content-Length: 20< Connection: keep-alive< hoge: fuga< Server: global_ngx_mruby<* Connection #0 to host 127.0.0.1 left intactThis is a plain textNginx::Request#content_type -> string
Section titled “Nginx::Request#content_type -> string”Returns the content type of the response.
r = Nginx::Request.newr.content_type = "text/plain"
# Do some other things
Nginx.echo r.content_type #=> text/plainNginx::Request#request_line -> string
Section titled “Nginx::Request#request_line -> string”Returns the HTTP request line.
# curl http://127.0.0.1/hello?a=1
r = Nginx::Request.newNginx.echo r.request_line #=> GET /hello?a=1 HTTP/1.1Nginx::Request#request_line=(string)
Section titled “Nginx::Request#request_line=(string)”Sets the string to the HTTP request line.
r = Nginx::Request.newNginx.echo r.request_line = 'GET /hello?a=1&b=1 HTTP/1.1'Nginx::Request#sub_request? -> true or false
Section titled “Nginx::Request#sub_request? -> true or false”Return true if the request is a sub request.
nginx provides a mechanism to internally send a sub request when received a request. See Authentication Based on Subrequest Result for how it works.
r = Nginx::Request.new
# location / { mruby_content_handler /path/to/hook.rb; }Nginx.echo r.sub_request?.to_s #=> "false"Nginx::Request#store -> Hash
Section titled “Nginx::Request#store -> Hash”Returns the store of the request, a Hash that is the same object in every
handler and filter of the request: the mruby_set handlers, the phase
handlers, the log handlers and the output header and body filters. The
first call creates it, empty. A handler uses it to pass values to a later
handler of the same request, without an nginx variable and without
turning the values into Strings. Since 3.0.0.
- The store belongs to the request, not to a location: it stays after an
internal redirect (
error_page,try_files, a named location,Nginx.redirectwith a local URI). - nginx keeps the store and the objects in it until it frees the request, after the log handlers. Do not keep the store in a global variable: the next request of the worker would see it.
- A subrequest gets an empty store of its own. It does not see the store of its main request, nor the main request the store of the subrequest. The store of a subrequest is kept until its main request is freed.
- A request whose handlers do not call the method allocates nothing for it.
- Outside a request, in the code of
mruby_init*,mruby_init_worker*,mruby_exit_worker*,mruby_ssl_handshake_handler*andmruby_server_context_handler_code, it raisesthis method can only be used while processing a request.
location /app { mruby_access_handler_code ' r = Nginx::Request.new r.store[:tenant] = r.headers_in["X-Tenant"].to_s '; try_files $uri @app;}
location @app { mruby_content_handler_code ' Nginx.rputs "tenant: #{Nginx::Request.new.store[:tenant]}\n" '; mruby_log_handler_code ' Nginx.log Nginx::LOG_NOTICE, "tenant=#{Nginx::Request.new.store[:tenant]}" ';}try_files sends a request for a file that does not exist to @app, an
internal redirect, and the content handler and the log handler there read
the value that the access handler stored.
Nginx::Request#uri -> string
Section titled “Nginx::Request#uri -> string”Returns an URI without the query parameters in the HTTP request line.
# curl http://127.0.0.1/hello?a=1
r = Nginx::Request.newNginx.echo r.uri #=> /helloNginx::Request#uri=(string)
Section titled “Nginx::Request#uri=(string)”Set the string to uri. An argument that is not a String raises TypeError. The other Request setters that share this behavior are #args=, #content_type=, #method=, #protocol=, #request_line= and #unparsed_uri=.
r = Nginx::Request.newNginx.echo r.uri = "/foo"Nginx::Request#unparsed_uri -> string
Section titled “Nginx::Request#unparsed_uri -> string”Returns an URI in the original HTTP request line.
# curl http://127.0.0.1/hello?a=1
r = Nginx::Request.newNginx.echo r.unparsed_uri #=> /hello?a=1Nginx::Request#unparsed_uri=(string)
Section titled “Nginx::Request#unparsed_uri=(string)”Sets the string to unparsed_uri.
r = Nginx::Request.newNginx.echo r.unparsed_uri = "/hello?a=1"Nginx::Request#method -> string
Section titled “Nginx::Request#method -> string”Returns the HTTP method of the request as a string like GET.
# curl http://127.0.0.1/hello?a=1
r = Nginx::Request.newNginx.echo r.method #=> GETNginx::Request#method=(string)
Section titled “Nginx::Request#method=(string)”Sets the string to method.
r = Nginx::Request.newNginx.echo r.method = "POST"Nginx::Request#protocol -> string
Section titled “Nginx::Request#protocol -> string”Returns the request protocol of the request like HTTP/1.1.
# curl http://127.0.0.1/hello?a=1
r = Nginx::Request.newNginx.echo r.protocol #=> HTTP/1.1Nginx::Request#protocol=(string)
Section titled “Nginx::Request#protocol=(string)”Sets the string to the request protocol
# curl http://127.0.0.1/hello?a=1
r = Nginx::Request.newNginx.echo r.protocol = "HTTP/1.0"Nginx::Request#args -> string
Section titled “Nginx::Request#args -> string”Returns the URL query parameters.
See Nginx::
# curl http://127.0.0.1/hello?a=1&b=2
r = Nginx::Request.newNginx.echo r.args #=> a=1&b=2Nginx::Request#args=(string)
Section titled “Nginx::Request#args=(string)”Sets the string to args.
r = Nginx::Request.newNginx.echo r.args "a=10&b=20"Nginx::var -> var
Section titled “Nginx::var -> var”Returns a Var instance of the request.
See Nginx::
r = Nginx::Request.newv = r.varv.exist? "foo" #=> falseNginx::Request#headers_in -> headers_in
Section titled “Nginx::Request#headers_in -> headers_in”Returns a Headers_in instance of the request.
See Nginx::
r = Nginx::Request.newheaders = r.headers_inheaders["User-Agent"] #=> curl/7.52.1Nginx::Request#headers_out -> headers_out
Section titled “Nginx::Request#headers_out -> headers_out”Returns a Headers_out instance of the request.
See Nginx::
r = Nginx::Request.newheaders = r.headers_outheaders["X-Request-Id"] = r.var.request_idNginx::Request#hostname -> string
Section titled “Nginx::Request#hostname -> string”Returns the host name. It’s same as nginx variable $host.
Therefore, the order of precedence is: host name in the request line,
host name in Host HTTP request header, or server name defined in nginx.conf.
# curl http://127.0.0.1:8001/hello?a=1
r = Nginx::Request.newNginx.echo r.hostname #=> "127.0.0.1"Nginx::Request#authority -> string
Section titled “Nginx::Request#authority -> string”Returns authority without userinfo.
# curl -v http://127.0.0.1:8001/hello?a=1
r = Nginx::Request.newNginx.echo r.authority #=> "127.0.0.1:8001"Nginx::Request#filename -> string
Section titled “Nginx::Request#filename -> string”Returns the requested filename. It’s same as nginx variable $request_filename.
# curl -v http://127.0.0.1/hello?a=1
r = Nginx::Request.newNginx.echo r.filename #=> /usr/local/nginx-1.4.4/html/helloNginx::Request#user -> string
Section titled “Nginx::Request#user -> string”Returns the user name of the Basic authentication.
# curl http://127.0.0.1/hello?a=1 -u matsumoto_r
r = Nginx::Request.newNginx.echo r.user #=> matsumoto_rNginx::Request#read_body -> integer
Section titled “Nginx::Request#read_body -> integer”Does nothing and always returns Nginx::
Nginx::Request#get_body -> string
Section titled “Nginx::Request#get_body -> string”Returns the request body as a string.
Notice: If you want to use the the method, you must use mruby_enable_read_request_body directive in nginx.conf to force reading the request body as below.
location /foo { mruby_enable_read_request_body on; # Force reading the request body mruby_access_handler_code ' req = Nginx::Request.new body = req.get_body # Get the body Nginx.log Nginx::LOG_ERR, "body:#{body}" Userdata.new.req_body = body # Set the body to Userdata used in the content handler '; mruby_content_handler_code ' Nginx.rputs Userdata.new.req_body ';}Nginx::Request#body -> string
Section titled “Nginx::Request#body -> string”Alias for Nginx::
Nginx::Request#document_root -> string
Section titled “Nginx::Request#document_root -> string”Returns the document root directory. It is configured by root directive.
See the ngx_
r = Nginx::Request.newr.document_root #=> /usr/local/nginx-1.4.4Nginx::Request#uri_args -> hash
Section titled “Nginx::Request#uri_args -> hash”Returns the URL query parameters as a hash.
# curl http://127.0.0.1/hello?a=1&b=2
r = Nginx::Request.newNginx.echo r.uri_args #=> {"a" => "1", "b" => "2"}Nginx::Request#uri_args=(hash)
Section titled “Nginx::Request#uri_args=(hash)”Set the hash to uri_args.
r = Nginx::Request.newr.uri_args = {"a" => "10", "b" => "20"}Nginx::Request#post_args -> hash
Section titled “Nginx::Request#post_args -> hash”Returns the request body as a hash.
The method assume the content type is application/x-www-form-urlencoded.
# curl http://127.0.0.1/hello?a=1&b=2
r = Nginx::Request.newNginx.echo r.uri_args #=> {"a" => "1", "b" => "2"}Return value examples of the URL related methods
Section titled “Return value examples of the URL related methods”Here is the return value examples of the above URL related methods. if you send a HTTP/1.1 GET request to https://user:pass@api.example.com:8080/foo?a=1&b=2, you will get the following values.
| Method | Return Value |
|---|---|
| scheme | https |
| request_line | GET /foo?a=1&b=2 HTTP/1.1 |
| uri | /foo |
| unparsed_uri | /foo?a=1&b=2 |
| method | GET |
| protocol | HTTP/1.1 |
| args | foo?a=1&b=2 |
| hostname | api.example.com |
| authority | api.example.com:8080 |
| filename | /path/to/document/root/foo |
| user | user |
| uri_args | {“a” => “1”, “b” => “2”} |
| document_root | /path/to/document |
Nginx::Server Class
Section titled “Nginx::Server Class”Instance Methods
Section titled “Instance Methods”Nginx::Server#add_listener(hash)
Section titled “Nginx::Server#add_listener(hash)”Create a listener on the specified IP address and the port in the hash.
The method works only in mruby_server_context_handler_code, while nginx reads the configuration.
Anywhere else, for example in a request handler, it raises a RuntimeError (add_listener can only be used in mruby_server_context_handler_code, since 2.7.1).
The :address must be a String, such as "127.0.0.1:58101" or "58102". Since 2.7.8, a missing :address or one that is not a String makes it raise TypeError (nil cannot be converted to String or Integer cannot be converted to String, with the class of the value), and nginx stops reading the configuration with that exception; up to 2.7.7 such a value could end nginx while it read the configuration.
s = Nginx::Server.news.add_listener({address: "127.0.0.1:58101"})s.add_listener({address: "58102"})s.add_listener({address: "58103", ssl: true})Here is an example to create multiple listeners on port 20001 to 30000.
http { server { mruby_server_context_handler_code ' s = Nginx::Server.new (20001..30000).each { |port| s.add_listener({address: port.to_s}) } ';
location /mruby { mruby_content_handler_code ' Nginx.rputs "Hello on port #{Nginx::Connection.new.local_port}" '; } }}Nginx::Server#document_root
Section titled “Nginx::Server#document_root”Returns the document root directory.
# curl http://127.0.0.1:8001/hello?a=1
s = Nginx::Server.newNginx.echo s.document_root # => /usr/local/nginx-1.4.4/htmlNginx::Server#realpath_root
Section titled “Nginx::Server#realpath_root”Returns the document root directory with symlinks resolved to real paths.
It’s same as nginx variable $realpath_root.
# curl http://127.0.0.1:8001/hello?a=1
s = Nginx::Server.newNginx.echo s.realpath_root # => /usr/local/nginx-1.4.4/htmlNginx::Server#path
Section titled “Nginx::Server#path”Alias for Nginx::
Nginx::Connection Class
Section titled “Nginx::Connection Class”Instance Methods
Section titled “Instance Methods”Nginx::Connection#remote_ip
Section titled “Nginx::Connection#remote_ip”Returns the client IP address. It’s same as nginx variable $remote_addr.
# curl http://192.168.0.2:8001/hello?a=1 on 192.168.0.1
c = Nginx::Connection.newNginx.echo c.remote_ip # => 192.168.0.1Nginx::Connection#remote_port
Section titled “Nginx::Connection#remote_port”Return the client port number. It’s same as nginx variable $remote_port.
# curl http://192.168.0.2:8001/hello?a=1 on 192.168.0.1
c = Nginx::Connection.newNginx.echo c.remote_port # => 54430Nginx::Connection#local_ip
Section titled “Nginx::Connection#local_ip”Returns the IP address that accepts the request. It’s same as nginx variable $server_addr.
# curl http://192.168.0.2:8001/hello?a=1 on 192.168.0.1
c = Nginx::Connection.newNginx.echo c.local_ip # => 192.168.0.2Nginx::Connection#local_port
Section titled “Nginx::Connection#local_port”Returns the port number that accepts the request. It’s same as nginx variable $server_port.
# curl http://192.168.0.2:8001/hello?a=1 on 192.168.0.1
c = Nginx::Connection.newNginx.echo c.local_port # => 8001Nginx::Var Class
Section titled “Nginx::Var Class”nginx supports embedded variables such as $http_host.
You can get or set the variables via Var class.
See Embedded Variables for
variables supported by the ngx_http_core_module.
You can use Var instance as below.
v = Nginx::Var.newNginx.echo "$http_host core variable is #{v.http_host}"v.backend = "192.168.0.1" # $backend is declared with set or mruby_variableNginx.echo "$backend is #{v.backend}"Also you can use your own variable.
Notice: You must declare the variable in nginx.conf with the set, mruby_set or mruby_set_code directive within the accessible context, or, since 3.0.0, with the mruby_variable directive in the http block. You can NOT add a new variable from mruby code.
mruby_variable declares a variable for scripts to assign without a set that runs in the request, so that a value that a server rewrite handler assigns is not overwritten by a set of the server.
location /foo { set $backend_user = "foo" mruby_set_code $auth ' r = Nginx::Request.new backend_user = r.var.backend_user backend_pass = lookup_pass_for(user) 'Basic ' + [backend_user + ':' + backend_pass].pack('m0') '; proxy_set_header Authorization $auth; proxy_pass http://backend.example.com;}A variable that a log handler (mruby_log_handler, mruby_log_handler_code) assigns is written by an access_log whose log_format names it: the log handlers run before access_log since 3.0.0 (see mruby_
Instance Methods
Section titled “Instance Methods”Nginx::Var#method_missing(symbol [, *args]) -> result
Section titled “Nginx::Var#method_missing(symbol [, *args]) -> result”It is designed for providing accessor to nginx variable.
The method is called when Nginx::Var#VARNAME or Nginx::Var#VARNAME= is evaluated.
Set the 2nd arg to the variable if the symbol ends with =. Otherwise, returns the value.
The variable is looked up by the name in lowercase. Since 2.7.2, a name that is empty or made only of = raises NoMethodError, and a setter called without a value raises ArgumentError and leaves the variable as it was.
Since 3.0.0, the first v.NAME or v.NAME = value of a name in a worker process also defines the accessor as a method of Nginx::Var, and the later accesses of that name in the worker call the method instead of method_missing. The method reads and writes the variable as method_missing does: the same values, nil when it reads a name that is not a variable, the same exceptions and the same lines in error.log. A worker defines:
- a getter and a setter for each declared variable that scripts use: the variables of nginx and its modules, and the ones that
setandmruby_variabledeclare; - a getter for the first 16 names of prefix variables that scripts use, the variables whose names start with a prefix that nginx defines, such as
arg_,http_,cookie_andupstream_http_. Any suffix makes such a name, so a worker keeps at most 16 of them.
Only a name in lowercase gets a method: the name has to be made of a to z, 0 to 9 and _ (with = at the end for a setter). v.Request_Method reads $request_method through method_missing and defines nothing. No method is defined for a name that is not a variable, for a setter of a prefix variable, for an instance of a subclass of Nginx::Var, when Nginx::Var is frozen, or when Nginx::Var or one of its ancestors already has a method of that name.
The defined methods show in introspection: after the first v.request_method in a worker, v.respond_to?(:request_method) returns true and Nginx::Var.instance_methods(false) lists request_method. What they show depends on the requests that the worker has served, so two workers can answer differently. To tell whether a variable exists, use Nginx::Var#exist?. Once the method exists, a method of the same name that a script defines later on Object or Kernel, for example with a def at the top level of handler code, no longer hides the variable from v.NAME.
Nginx::Connection#remote_ip, #remote_port, #local_ip and #local_port, Nginx::Server#document_root, #realpath_root and #path, and Nginx::Request#hostname, #authority, #filename, #user and #get_body read their variables from nginx directly. Since 3.0.0, a method that a script defines on Nginx::Var does not change what they return.
Nginx::Var#set(name, value)
Section titled “Nginx::Var#set(name, value)”Set the value to the nginx variable.
name is looked up in lowercase. Since 2.7.2, set does not change the String or Symbol passed as name.
v = Nginx::Request.new.varv.set "backend", "http://192.168.0.9/" # Set "http://192.168.0.9/" to $backendA name or a value that is not a String is converted with to_s. When to_s is missing, raises, or returns an object that is not a String, set raises that exception (a TypeError for the object that is not a String), and so does Nginx::Var#<name>=.
Since 3.0.0, set and Nginx::Var#<name>= raise when nginx cannot take the assignment, and the message names the variable as the script wrote it:
NameError(nginx variable $<name> is not defined (declare it with set or mruby_variable)) for a name that nginx does not know. A name that begins with a prefix of nginx, such asarg_orhttp_, counts as one when nosetormruby_setdeclares it (mruby_variabledoes not declare such names).RuntimeError(nginx variable $<name> cannot be changed by a script) for a variable that nginx does not let scripts change, such as$urior$http_host. Change the URI and the request headers with the setters ofNginx::RequestandNginx::Headers_in.RuntimeError(nginx variable $<name> cannot be assigned by a script: the configuration does not refer to it) for a variable without a set handler, such as one ofmaporgeo, that nothing in the configuration refers to: nginx keeps no value of it in the request.
A handler that does not rescue the exception ends as after any other exception: its request answers 500, a log handler logs it, and error.log has the mrb_run failed line of the exception. nginx -t cannot find these mistakes, because the code decides the name when it runs; they show at the first request that runs the assignment. On 2.x, the assignment wrote a line at the error level to error.log, returned nil, and the request went on with the variable unchanged.
The value that set and Nginx::Var#<name>= assign is the one that nginx’s set directive would assign: a variable with a set handler, such as $args or $limit_rate, gets it through that handler. set returns the value as a String.
Nginx::Var#.exist? -> true or false
Section titled “Nginx::Var#.exist? -> true or false”Returns true if the variable is defined.
If backend variable is not defined in nginx.conf, you will get false.
v = Nginx::Request.new.varv.exist? "backend" # => falseNginx::Headers_in Class
Section titled “Nginx::Headers_in Class”Headers_in class stores HTTP request headers.
The name comes from ngx_
Instance Methods
Section titled “Instance Methods”Nginx::Headers_in#[](string) -> string
Section titled “Nginx::Headers_in#[](string) -> string”Returns the value of the http request header.
hin = Nginx::Headers_in.newNginx.rputs hin["User-Agent"] #=> curl/7.29.0Nginx::Headers_in#[]=(string, string)
Section titled “Nginx::Headers_in#[]=(string, string)”Sets the value to the http request header. The name and the value must each be a String; a non-String raises TypeError.
hin = Nginx::Headers_in.newNginx.rputs hin["User-Agent"] #=> curl/7.29.0
hin["User-Agent"] = "test-agent"Nginx.rputs hin["User-Agent"] #=> test-agentNginx::Headers_in#all -> hash
Section titled “Nginx::Headers_in#all -> hash”Returns the all http request headers.
hin = Nginx::Headers_in.new
hin.all.keys.each do |k| Nginx.echo "#{k}: #{hin[k]}"end$ curl http://127.0.0.1:8001/hello#Host: 127.0.0.1:8001#User-Agent: curl/7.29.0#Accept: */*Nginx::Headers_in#delete(string)
Section titled “Nginx::Headers_in#delete(string)”Delete the field from the http request headers.
hin = Nginx::Headers_in.newhin["X-Remove-Header"] = "to be deleted!"hin.delete("X-Remove-Header")Nginx.rputs hin["X-Remove-Header"] #=> nilNginx::Headers_out Class
Section titled “Nginx::Headers_out Class”Headers_out class stores HTTP response headers.
The name comes from ngx_
Instance Methods
Section titled “Instance Methods”Nginx::Headers_out#[](string) -> string
Section titled “Nginx::Headers_out#[](string) -> string”Returns the value of the http response header.
hout = Nginx::Headers_out.newhout["X-NGX-MRUBY"] = "support"Nginx.rputs hout["X-NGX-MRUBY"] #=> supportNginx::Headers_out#[]=(string, string)
Section titled “Nginx::Headers_out#[]=(string, string)”Sets the value to the http response header. The name and the value must each be a String; a non-String raises TypeError.
hout = Nginx::Headers_out.newhout["X-NGX-MRUBY"] = "support"Nginx.rputs hout["X-NGX-MRUBY"] #=> supportNginx::Headers_out#all -> hash
Section titled “Nginx::Headers_out#all -> hash”Returns the all http response headers.
hout = Nginx::Headers_out.new
hout["X-NGX-MRUBY"] = "support"hout.all.keys.each do |k| Nginx.echo "#{k}: #{hout[k]}"end$ curl -v http://192.168.12.9:8001/hello?a=1#X-NGX-MRUBY: supportNginx::Headers_out#delete(string)
Section titled “Nginx::Headers_out#delete(string)”Delete the field from the http response headers.
hout = Nginx::Headers_out.newhout["X-Remove-Header"] = "to be deleted!"hout.delete("X-Remove-Header")Nginx.rputs hout["X-Remove-Header"] #=> nilNginx::Filter Class
Section titled “Nginx::Filter Class”Nginx::Nginx::Filter#body, #body= and #output raise a RuntimeError (Nginx::Filter#body can only be used in an output body filter): #body= and #output since 2.7.1, #body since 3.0.0 (it returned an empty string before the body filter had read the body, in a content handler and in a header filter).
Notice: You can NOT use Nginx.rputs and Nginx.echo in the output header and body handlers
(mruby_output_header_filter, mruby_output_body_filter and their _code forms).
Here is an example how it works.
location /foo { return 200 hello;}
location /bar { mruby_output_header_filter_code ' Nginx::Request.new.headers_out["X-Filter"] = "on" '; mruby_output_body_filter_code ' f = Nginx::Filter.new f.body = f.body.upcase '; return 200 hello;}$ curl -v http://127.0.0.1:59090/foo
[snip]
< HTTP/1.1 200 OK< Server: nginx/1.15.7< Date: Wed, 05 Dec 2018 06:27:19 GMT< Content-Type: text/plain< Content-Length: 5< Connection: keep-alive<* Connection #0 to host 127.0.0.1 left intacthello$ curl -v http://127.0.0.1:59090/bar
[snip]
< HTTP/1.1 200 OK< Server: nginx/1.15.7< Date: Wed, 05 Dec 2018 06:27:24 GMT< Content-Type: text/plain< Content-Length: 5< Connection: keep-alive< X-Filter: on<* Connection #0 to host 127.0.0.1 left intactHELLOInstance Methods
Section titled “Instance Methods”Nginx::Filter#body -> string
Section titled “Nginx::Filter#body -> string”Returns the response body.
Outside an output body filter it raises a RuntimeError (since 3.0.0). In a header filter, which runs before the body has been read, it returned an empty string from 2.7.1 (2.7.0 returned a string as long as Content-Length whose bytes were not the body, or raised an ArgumentError when the length was unknown or 10 MB or more).
To learn the length in a header filter, call Nginx::Var.new.sent_http_content_length, which reads the variable.
f = Nginx::Filter.newresponse = f.body.upcaseNginx::Filter#body=(string)
Section titled “Nginx::Filter#body=(string)”Sets the string to the response body.
The response is sent with exactly this 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.
A HEAD response with a known content length that is finalized by the output body filter sends its headers without body bytes and keeps an otherwise reusable connection available for the next request. This applies to both empty and nonempty replacement bodies. A 204 or 304 response through the output body filter, and a HEAD response without a known length through it, keep the connection as well, also when nginx needs more than one write for the header.
It can only be used in an output body filter; anywhere else it raises a RuntimeError (since 2.7.1).
A value that is not a String is converted with to_s. When to_s is missing or raises, body= raises that exception, and since 2.7.6 a to_s that returns something other than a String makes it raise TypeError; up to 2.7.5 such a to_s could end the worker process. In each case the body stays as it was.
f = Nginx::Filter.newf.body = "The original body is removed"An empty String sends the response with Content-Length: 0 and no body, and
so does a body filter that leaves the body of a response without a body
empty. 2.7.2 and earlier releases closed the connection there without a
response and logged zero size buf in writer; 2.7.3 sends the response as
well (see docs/releases/v3.0.0.md and
entry 8 of docs/releases/v2.7.3.md).
Nginx::Filter#output
Section titled “Nginx::Filter#output”Alias for Nginx::Filter#body=.
Nginx::Upstream Class
Section titled “Nginx::Upstream Class”You can access upstream configuration via Nginx::
http { upstream my_upstream { server 127.0.0.1:80; } server { location /foo { mruby_rewrite_handler_code ' u = Nginx::Upstream.new "my_upstream" u.server = "127.0.0.1:58081" # Change 'server' to 127.0.0.1:58081 from 127.0.0.1:80 Nginx.return Nginx::DECLINED '; proxy_pass http://my_upstream; } }}Instance Methods
Section titled “Instance Methods”Nginx::Upstream#new(string) -> upstream
Section titled “Nginx::Upstream#new(string) -> upstream”Creates and returns an Upstream instance.
The string is the whole name of an upstream {} block, compared case-insensitively as nginx compares upstream names. The method raises RuntimeError when no upstream has that name, and TypeError when the argument is not a String. Up to 2.7.2 the method compared only the length of the argument, so it also found the first upstream whose name started with it, and it did not check the class of the argument.
An object has its upstream only when initialize found it. On an object whose initialize raised, which a script can keep when it calls initialize again with send or creates the object with allocate, #keepalive_cache, #keepalive_cache=, #server and #server= raise ArgumentError (uninitialized Nginx::Upstream) since 2.7.9. Up to 2.7.8 they returned nil or ended the worker process (see the 2.7.9 release notes). An initialize that succeeds afterwards gives the object its upstream. A copy made with dup or clone has no upstream, because mruby copies the instance variables of the object and not its data: these methods raise the same ArgumentError on it, and the original object keeps its upstream. Up to 2.7.8 they ended the worker process on a copy. Where a script needs a second object for the same upstream, it creates one with Nginx::Upstream.new.
u = Nginx::Upstream.new "YOUR_UPSTREAM_NAME"Nginx::Upstream#keepalive_cache -> integer
Section titled “Nginx::Upstream#keepalive_cache -> integer”Returns the keepalive cache of the upstream.
u = Nginx::Upstream.new "YOUR_UPSTREAM_NAME"n = u.keepalive_cacheNginx::Upstream#keepalive_cache=(integer)
Section titled “Nginx::Upstream#keepalive_cache=(integer)”Sets the keepalive cache of the upstream.
u = Nginx::Upstream.new "YOUR_UPSTREAM_NAME"u.keepalive_cache = 0Nginx::Upstream#server -> string
Section titled “Nginx::Upstream#server -> string”Returns the server of the upstream.
u = Nginx::Upstream.new "YOUR_UPSTREAM_NAME"Nginx.echo u.server #=> 127.0.0.1:80Nginx::Upstream#server=(string)
Section titled “Nginx::Upstream#server=(string)”Sets the string to the server of the upstream.
The servers of the upstream block that are not backup must have one address in all: Nginx::Upstream.new raises RuntimeError for more, for example for two server lines, or for one whose host name nginx resolved to two addresses. backup servers are not counted, and the method does not change them. The new server is that peer’s for every later request that the worker sends to the upstream, not only for the current request, until the worker exits or the configuration is reloaded; each worker keeps its own. An upstream with a zone is not supported: since 2.7.3 the method raises RuntimeError for one and leaves its server. Up to 2.7.2 it changed the server, and the change was not valid in the other workers (see “Not changed by this release” of the Nginx::Upstream#server= entry in the 2.7.2 release notes).
The string is an IP address and a port: an IPv4 address is four decimal numbers, an IPv6 address goes in brackets, and unix: with a path names a UNIX-domain socket. The port is 80 when the string has none. A host name is not resolved, because the worker would serve no other client while it waited; give an IP address. An IPv4 address in a form that only a resolver reads, such as 127.1, and 255.255.255.255 count as host names here. The method raises TypeError when the argument is not a String (since 2.7.3), ArgumentError when the string is empty or 256 bytes or longer, when it holds a NUL byte (since 2.7.3), and when it is a host name or anything else that nginx cannot read as an address (since 3.0.0 for these two; see the entries of the 3.0.0 release notes on a host name and on the other strings), and RuntimeError when nginx fails while it reads the string; the server stays as it was then.
u = Nginx::Upstream.new "YOUR_UPSTREAM_NAME"s = u.server #=> 127.0.0.1:80u.server = "127.0.0.1:8080" #=> 127.0.0.1:8080Nginx::Async Class
Section titled “Nginx::Async Class”Instance Methods
Section titled “Instance Methods”Nginx::Async#sleep(msec)
Section titled “Nginx::Async#sleep(msec)”Sleeps in non-blocking way.
It’s currently supported in the set, post_read, server rewrite, rewrite, access and content handlers.
When the sleep ends, nginx calls the handler again, which goes on with the code after the sleep, and the phase of the handler handles its result as for a handler that did not wait (since 3.0.0).
An access handler without a result then goes on with the next access handler under satisfy all and allows the request under satisfy any; a 401 or 403 under satisfy any lets nginx try the next access handler; a post_read handler without a result goes on with the next phase.
While the handler waits, nginx does not run its code again.
When the client of an HTTP/1.x request closes the connection during the sleep, the code still goes on after it, because nginx does not read from the client while the handlers run.
When nginx ends the request during the sleep, for example when worker_shutdown_timeout expires in a worker that shuts down, the code after the sleep does not run, ensure clauses included; see Waiting without blocking.
On 2.x the timer ended the handler with the rules of the content phase: an access or post_read handler without a result answered and then closed the connection, and a 401 or 403 under satisfy any ended the request (see the release notes of 3.0.0).
An mruby_set* handler that sleeps sets its variable when the code returns, and the request goes on, as described under mruby_set.
In a content handler (mruby_content_handler*) nginx waits for the handler since 2.7.3: the code after the sleep runs, and the request gets the response that the handler writes or the status that it returns. Up to 2.7.2 the request ended at the sleep without a response (see “Known limitations” in the 2.7.1 release notes).
A handler of the location that Nginx.redirect sends the request to can sleep like any handler, since 3.0.0: the redirect takes effect when the calling handler ends (see Nginx.redirect). On 2.x a content handler there ended the request at the sleep.
After the sleep, a content handler can wait for Nginx::Async::HTTP.sub_request as well (since 3.0.0; 2.7.3 raises a RuntimeError there).
A rewrite or access handler that returns Nginx::DECLINED after the sleep lets the request go on to the next phase as without the sleep, and a later mruby handler that sets no status does not answer 500 (since 3.0.0 and 2.7.5; up to 2.7.4 the request went on with the status 500, see the 2.7.5 release notes).
In a log handler (mruby_log_handler, mruby_log_handler_code) and in the
output filters (mruby_output_header_filter*, mruby_output_body_filter*),
nginx cannot resume a handler that waits, so it raises a RuntimeError (since 2.7.1; in 2.7.0 a sleep in a log handler could crash the worker, and a sleep in a filter stopped the filter there and sent the response unfiltered).
If the handler raises an exception after the call returns, the request gets 500 and the output of Nginx.rputs is not sent, unless the response was already started, for example by the location that Nginx.redirect ran.
Then the 500 is not sent either.
This holds since 2.7.1; in 2.7.0 the client got no response, the output of Nginx.rputs with status 200, or the status that the handler had set before the exception.
Nginx::Async.sleep 3000 # Sleep 3000 millisecNginx::Async::HTTP Class
Section titled “Nginx::Async::HTTP Class”Instance Methods
Section titled “Instance Methods”Nginx::Async::HTTP#sub_request(location, string_or_hash=nil)
Section titled “Nginx::Async::HTTP#sub_request(location, string_or_hash=nil)”Sends a sub request in non-blocking way, waits for its end, and returns its response, an Nginx::Async::HTTP::Response with the same status, headers and body as Nginx::Async::HTTP.last_response (since 3.0.0; 2.x returns nil). The location must be a String; a non-String raises TypeError.
It’s supported in the post_read, server rewrite, rewrite, access and content handlers. In an mruby_set* handler it raises a RuntimeError, because nginx does not wait for a subrequest there: call it in a rewrite or access handler and set the variable with Nginx::Nginx::Async.sleep (since 3.0.0; 2.7.3 raises a RuntimeError there, because nginx would not finish the request after the subrequest).
Like Nginx::Async.sleep, it raises a RuntimeError in a log handler and in
the output filters (since 2.7.1; 2.7.0 started the subrequest there).
If the handler raises an exception after the call returns, the request gets 500 and the output of Nginx.rputs is not sent, unless the response was already started, for example by the location that Nginx.redirect ran.
Then the 500 is not sent either.
This holds since 2.7.1, as for Nginx::Async.sleep.
res = Nginx::Async::HTTP.sub_request "/example", "q1=foo&q2=bar" # Send a sub request with the parameters, and get its response
res = Nginx::Async::HTTP.last_response # The same response, also on 2.x
Nginx.rputs res.body #=> "hello world"Nginx.rputs res.headers #=> {"Date" => "Thu, 29 Nov 2018 07:55:22 GMT", ...}Nginx.rputs res.status #=> 200You can pass a hash instead of the string.
TODO: do we really need Utils.encode_parameters? It is called in sub_request().
Also is the following comment in test/conf/nginx.conf still true?
“# BUG?: using Nginx::
Nginx::Async::HTTP.sub_request "/example", Nginx::Utils.encode_parameters({q1: "foo", q2: "bar"})Nginx::Async::last_response -> http_response
Section titled “Nginx::Async::last_response -> http_response”Returns the response of the last sub request.
See Nginx::
Nginx::Async::HTTP::Response Class
Section titled “Nginx::Async::HTTP::Response Class”Response class returned from Nginx::
Instance Methods
Section titled “Instance Methods”Nginx::Async::HTTP::Response#body -> string
Section titled “Nginx::Async::HTTP::Response#body -> string”Returns the response body of the last sub request.
See Nginx::
Nginx::Async::HTTP::Response#headers -> hash
Section titled “Nginx::Async::HTTP::Response#headers -> hash”Returns the response headers of the last sub request.
See Nginx::
Nginx::Async::HTTP::Response#status -> integer
Section titled “Nginx::Async::HTTP::Response#status -> integer”Returns the HTTP response status of the last sub request.
See Nginx::
RACK Compatible API
Section titled “RACK Compatible API”rack-based-api mrbgem provides RACK compatible APIs. You can write mruby code in the RACK way as below.
location /hello { mruby_content_handler_code ' proc = Proc.new do |env| [200, {"Content-Type" => "text/plain"}, ["hello ngx_mruby world!"]] end run proc ';}Kernel Module Methods
Section titled “Kernel Module Methods”rack-based-api mrbgem adds run method to Kernel module. It takes care everything.
run(obj)
Section titled “run(obj)”Send a call message to the obj.
The obj must respond to call. It takes one argument, the environment.
It must return an array that contains the status, the headers and the body.
See The RACK specification for more details.
class MyApp def call(env) status = 200 headers = {"Content-Type" => "text/plain", "X-NGX-MRUBY-INTERACTION-ID" => Uuid.uuid} body = ["Got a request from " + env["REMOTE_ADDR"]] [status, headers, body] endendrun MyApp.newNginx::Stream class
Section titled “Nginx::Stream class”TODO: cleanup and add descriptions.
example
Section titled “example”stream { upstream dynamic_server0 { server 127.0.0.1:58080; }
server { listen 12346; mruby_stream_code ' c = Nginx::Stream::Connection.new "dynamic_server0" c.upstream_server = "192.168.0.3:54321" Nginx::Stream.log Nginx::Stream::LOG_NOTICE, "dynamic_server0 was changed to 192.168.0.3:54321" '; proxy_pass dynamic_server0; }}Class Methods
Section titled “Class Methods”Nginx::Stream.add_listener
Section titled “Nginx::Stream.add_listener”Create a listener on the specified IP address and the port in the hash.
Nginx::Stream.add_listener({address: "127.0.0.1:12350"})Nginx::Stream.add_listener({address: "12351"})See Nginx::
The method works only in mruby_stream_server_context_code, while nginx reads the configuration.
Anywhere else, for example in mruby_stream_code or mruby_stream_init_worker_code, it raises a RuntimeError (since 2.7.1).
As for Nginx::Server#add_listener, the :address must be a String: since 2.7.8, a missing :address or one that is not a String raises TypeError, and nginx stops reading the configuration.
Nginx::Stream.errlogger(log_level, string)
Section titled “Nginx::Stream.errlogger(log_level, string)”Nginx::Stream.errlogger Nginx::Stream::LOG_NOTICE, "logging something"Nginx::Stream.log(log_level, string)
Section titled “Nginx::Stream.log(log_level, string)”Alias for Nginx::Stream.errlogger.
Nginx::Stream.module_name -> string
Section titled “Nginx::Stream.module_name -> string”Returns the module name ngx_mruby-stream-module.
Nginx::Stream.module_name #=> "ngx_mruby-stream-module"Constants
Section titled “Constants”Constants for log levels
Section titled “Constants for log levels”Log levels for Nginx::Stream.errlogger that mirror nginx error log levels.
See Constants for log levels in the Nginx Class documentation for more details.
| Name | Description |
|---|---|
| Nginx:: |
Defined in core/ngx_log.h, but it’s never used |
| Nginx:: |
Emergency error log level |
| Nginx:: |
Alert error log level |
| Nginx:: |
Critical error log level |
| Nginx:: |
Error log level |
| Nginx:: |
Warning log level |
| Nginx:: |
Notice log level |
| Nginx:: |
Information log level |
| Nginx:: |
Debug log level |
Constants for status
Section titled “Constants for status”The values of the session status that Nginx::Stream::Connection.stream_status returns and .stream_status= sets.
| Name | Value |
|---|---|
| Nginx:: |
0 |
| Nginx:: |
-1 |
| Nginx:: |
-2 |
| Nginx:: |
-3 |
| Nginx:: |
-4 |
| Nginx:: |
-5 |
| Nginx:: |
-6 |
Nginx::Stream::Connection class
Section titled “Nginx::Stream::Connection class”- example
stream { upstream dynamic_server0 { server 127.0.0.1:58080; }
mruby_stream_init_code ' Userdata.new.new_upstream = "127.0.0.1:58081" ';
mruby_stream_init_worker_code ' p "ngx_mruby: STREAM: mruby_stream_init_worker_code" ';
mruby_stream_exit_worker_code ' p "ngx_mruby: STREAM: mruby_stream_exit_worker_code" ';
server { listen 12346; mruby_stream_code ' c = Nginx::Stream::Connection.new "dynamic_server0" c.upstream_server = Userdata.new.new_upstream '; proxy_pass dynamic_server0; }}Nginx::Stream::Connection#new
Section titled “Nginx::Stream::Connection#new”get the upstream configuration via upstream name
As for Nginx::Upstream.new, the string is the whole name of an upstream {} block of the stream {} block, compared case-insensitively; the method raises RuntimeError when no upstream has that name, and TypeError when the argument is not a String (since 2.7.3; up to 2.7.2 it also found an upstream whose name started with the argument).
On an object whose initialize raised, one created with allocate, or a copy made with dup or clone (mruby copies the instance variables of the object and not its data), #upstream_server and #upstream_server= raise ArgumentError (uninitialized Nginx::Stream::Connection) since 2.7.9; up to 2.7.8 they returned nil or ended the worker process (see the 2.7.9 release notes). The original of a copy keeps its upstream; where a script needs a second object for the same upstream, it creates one with Nginx::Stream::Connection.new. The other methods do not use the upstream and work on such an object.
# == nginx.conf ==# upstream dynamic_server0 {# server 127.0.0.1:58080;# }c = Nginx::Stream::Connection.new "dynamic_server0"Nginx::Stream::Connection#upstream_server
Section titled “Nginx::Stream::Connection#upstream_server”# == nginx.conf ==# upstream dynamic_server0 {# server 127.0.0.1:58080;# }c = Nginx::Stream::Connection.new "dynamic_server0"c.upstream_server #=> "127.0.0.1:58080"Nginx::Stream::Connection#upstream_server=
Section titled “Nginx::Stream::Connection#upstream_server=”Sets the server of the upstream that Nginx::Stream::Connection.new named. As for Nginx::Upstream#server=, the servers of the upstream block that are not backup must have one address in all, and backup servers are not changed. The new server is that peer’s for every later session that the worker sends to the upstream, until the worker exits or the configuration is reloaded; each worker keeps its own. An upstream with a zone is not supported: since 2.7.3 the method raises RuntimeError for one and leaves its server.
The string is an IP address and a port, such as 127.0.0.1:12345 or [::1]:12345, or unix: with a path; host names are not resolved and raise. A string without a port is accepted, and the port is then 0. The method raises TypeError when the argument is not a String (since 2.7.3), ArgumentError when the string is empty or 256 bytes or longer, when it holds a NUL byte, and when it is a host name or anything else that nginx cannot read as an address (since 3.0.0; 2.x raises RuntimeError for these, for a NUL byte since 2.7.3; see the 3.0.0 release notes), and RuntimeError when nginx fails while it reads the string; the server stays as it was then.
# == nginx.conf ==# upstream dynamic_server0 {# server 127.0.0.1:58080;# }c = Nginx::Stream::Connection.new "dynamic_server0"c.upstream_server #=> "127.0.0.1:58080"c.upstream_server = "192.168.0.3:54321"Nginx::Stream::Connection.stream_status
Section titled “Nginx::Stream::Connection.stream_status”get the current stream status
if Nginx::Stream::Connection.remote_ip == "127.0.0.1" current_status = Nginx::Stream::Connection.stream_status #=> Nginx::Stream::DECLINEDendNginx::Stream::Connection.stream_status=
Section titled “Nginx::Stream::Connection.stream_status=”if Nginx::Stream::Connection.remote_ip == "127.0.0.1" current_status = Nginx::Stream::Connection.stream_status #=> Nginx::Stream::DECLINED Nginx::Stream::Connection.stream_status = Nginx::Stream::ABORT Nginx::Stream.log Nginx::Stream::LOG_NOTICE, ¥ "current status=#{(current_status == Nginx::Stream::DECLINED) ? "NGX_DECLINED" : current_status} but deny from #{Nginx::Stream::Connection.remote_ip} return NGX_ABORT"endNginx::Stream::Connection.remote_ip
Section titled “Nginx::Stream::Connection.remote_ip”if Nginx::Stream::Connection.remote_ip == "127.0.0.1" # something access controlend- access control example
stream { server { listen 12347; mruby_stream_code ' if Nginx::Stream::Connection.remote_ip == "127.0.0.1" current_status = Nginx::Stream::Connection.stream_status Nginx::Stream::Connection.stream_status = Nginx::Stream::ABORT Nginx::Stream.log Nginx::Stream::LOG_NOTICE, "current status=#{(current_status == Nginx::Stream::DECLINED) ? "NGX_DECLINED" : current_status} but deny from #{Nginx::Stream::Connection.remote_ip} return NGX_ABORT" end '; proxy_pass dynamic_server1; }}Nginx::Stream::Connection.{remote_port,local_ip,local_addr,local_port,local_ip_port}
Section titled “Nginx::Stream::Connection.{remote_port,local_ip,local_addr,local_port,local_ip_port}”server { listen 127.0.0.1:12348; mruby_stream_code ' Nginx::Stream.log Nginx::Stream::LOG_NOTICE, "local is #{Nginx::Stream::Connection.local_ip}:#{Nginx::Stream::Connection.local_port} remote_port is #{Nginx::Stream::Connection.remote_ip}:#{Nginx::Stream::Connection.remote_port}" if Nginx::Stream::Connection.local_port != 12348 && Nginx::Stream::Connection.local_ip != "127.0.0.1" Nginx::Stream::Connection.stream_status = Nginx::Stream::ABORT end '; proxy_pass static_server0;}
server { listen 127.0.0.1:12349; mruby_stream_code ' Nginx::Stream.log Nginx::Stream::LOG_NOTICE, "local_ip_port is #{Nginx::Stream::Connection.local_ip_port}" if Nginx::Stream::Connection.local_ip_port != "127.0.0.1:12349" Nginx::Stream::Connection.stream_status = Nginx::Stream::ABORT end '; proxy_pass static_server0;}Nginx::Stream::Connection.{proxy_protocol_addr,proxy_protocol_ip}
Section titled “Nginx::Stream::Connection.{proxy_protocol_addr,proxy_protocol_ip}”On a listen ... proxy_protocol, returns the source address of the PROXY protocol header that nginx read when the connection was accepted, as a String. proxy_protocol_ip is another name of the same method, and both are also instance methods. The method returns nil when the connection has no such address: on a listen without proxy_protocol, and for the headers PROXY UNKNOWN (version 1) and LOCAL (version 2). This holds since 3.0.0 and 2.7.4.
server { listen 127.0.0.1:12350 proxy_protocol; mruby_stream_code ' if Nginx::Stream::Connection.proxy_protocol_addr != "192.0.2.10" Nginx::Stream::Connection.stream_status = Nginx::Stream::ABORT end '; proxy_pass static_server0;}Nginx::Stream::Async Class
Section titled “Nginx::Stream::Async Class”Method
Section titled “Method”Nginx::Stream::Async#sleep
Section titled “Nginx::Stream::Async#sleep”Do non-blocking sleep. It works in the code of mruby_stream and mruby_stream_code, which runs in the access phase of the stream session.
After the sleep, the session goes on as it does when the code does not sleep, by the result of the code: the next handler for Nginx::Stream::DECLINED (the default of Nginx::Stream::Connection.stream_status), the next phase for Nginx::Stream::OK, the wait of the session for Nginx::Stream::DONE and Nginx::Stream::AGAIN, and the end of the session for Nginx::Stream::ABORT or another status, and for an exception, which error.log records.
This holds since 2.7.3; up to 2.7.2 a session whose code raised or set a status other than Nginx::Stream::DECLINED after the sleep was neither ended nor continued, and an exception after the sleep also aborted the next session.
While the code of a TCP session sleeps, nginx reads nothing from the client, also on a listen ... proxy_protocol: the bytes that the client sends then stay for the phase after the code, such as proxy_pass, which sends them to the upstream. This holds since 3.0.0 and 2.7.4.
A session runs its code once (since 3.0.0 and 2.7.5): datagrams received while the code sleeps do not start it again or move the deadline of that sleep. The session’s first datagram remains available to the phase after the code. Later datagrams received during the wait are discarded: ngx_mruby does not queue them or replay their payloads to proxy_pass after the wait. This applies to each sleep when the code waits more than once. In 2.7.4, each such datagram started the code again in another fiber of the session, and only the last run went on after its sleep.
Once the code has resumed and the session reaches proxy_pass, nginx handles subsequent datagrams of that session normally; they do not run the Ruby code again. A configuration that needs every datagram to reach its upstream must avoid sleeping in the UDP stream handler, or arrange retransmission in its application protocol. Use the handler for session-level decisions, not processing that must run once for each datagram.
When worker_shutdown_timeout expires in a worker that shuts down, a session whose code waits ends: the code after the sleep does not run, and error.log gets shutdown timeout at the info level (since 3.0.0). In 2.x, a TCP session ends during the wait since 2.7.4, and a UDP session since 2.7.5; the TCP path logs the session ends during the wait of its code instead. See the entries “A UDP stream session runs its code once” and “A stream session that waits when worker_shutdown_timeout expires ends then” of the release notes of 3.0.0, and the 2.7.5 release notes.
# sleep 3000 millisecNginx::Stream::Async.sleep 3000