Skip to content

Home

Jump to bottom Edit New page
MATSUMOTO, Ryosuke edited this page Mar 4, 2014 · 18 revisions

Welcome to ngx_mruby Pages Build Status

ngx_mruby mod_mruby performance

※ hello world simple benchmark, see details of blog entry.

Documents

What's ngx_mruby

ngx_mruby is A Fast and Memory-Efficient Web Server Extension Mechanism Using Scripting Language mruby for nginx.

# location /proxy {
#   mruby_set $backend "/path/to/proxy.rb";
#   proxy_pass   http://$backend;
# }

backends = [
  "test1",
  "test2",
  "test3",
]

r = Redis.new "192.168.12.251", 6379
r.get backends[rand(backends.length)]
  • see examples
  • Sample of Unified Ruby Code between Apache(mod_mruby) and nginx(ngx_mruby) for Web server extensions
  • You can implement some Web server software extensions by same Ruby code (as possible)
# Unified Ruby Code between Apache(mod_mruby) and nginx(ngx_mruby)
# for Web server extensions.
#
# Apache httpd.conf by mod_mruby
# 
# <Location /mruby>
#     mrubyHandlerMiddle "/path/to/unified_hello.rb"
# </Location>
#
# nginx ngxin.conf by ngx_mruby
#
# location /mruby {
#     mruby_content_handler "/path/to/unified_hello.rb";
# }
#

if server_name == "NGINX"
  Server = Nginx
elsif server_name == "Apache"
  Server = Apache
end

Server::rputs "Hello #{Server::module_name}/#{Server::module_version} world!"
# mod_mruby => "Hello mod_mruby/0.9.3 world!"
# ngx_mruby => "Hello ngx_mruby/0.0.1 world!"

Abstract

As the increase of large-scale and complex Web services, not only a development of Web applications but also an implementation of Web server extensions is required in many cases. The Web server extensions were mainly implemented in C language because of fast and memory-efficient behavior, but extension methods using scripting language are proposed with consideration of maintainability and productivity. However, if the existing methods primarily intended to enhance not the implementation of Web applications but the implementation of internal processing of the Web server, the problem remains in terms of speed, memory-efficiency and safety. Therefore, we propose a fast and memory-efficient Web server extension mechanism using scripting language. We design the architecture that a server process creates the region to save the state of the interpreter at the server process startup, and multiple scripts share the region in order to process fast when the script is called as internal processing from a Web server process. The server process frees the global variables table, the exception flag and the byte-code which cause the increase of memory usage mainly, in order to reduce the memory usage and extend safety by preventing interference between each scripts because of sharing the region. We implement the mechanism that can extend the internal processing of nginx easily by Ruby scripts using nginx and the embeddable scripting language mruby. It's called "ngx_mruby".

How to use

1. Download

$ git clone git://github.com/matsumoto-r/ngx_mruby.git
$ cd ngx_mruby
$ git submodule init
$ git submodule update
  • if you want more features, you can get mrbgems and write to build_config.rb
  • for example, use mruby-io and implement file base access check like .htaccess.
  • default mrbgems
    • gembox: mruby/mruby default mrbgems, mruby-randoma, mruby-env, mruby-print...
    • mruby-process: Process ::fork, ::kill, ::pid, ::ppid, ::waitpid...
    • mruby-pack: pack, unpack...
    • mruby-digest: MD5, RMD160, SHA1, SHA256, SHA384, SHA512 and HMAC Digests
    • mruby-jason: JSON::parse, JSON::stringify
    • mruby-redis: Redis#set, get, [], []=...
    • mruby-sleep: sleep, usleep...
    • mruby-userdata: https://github.com/matsumoto-r/mruby-userdata
    • mruby-hs-regexp: regexp engine
    • mruby-io: https://github.com/iij/mruby-io
  • We should implement ngx_mruby/mod_mruby extensions as mrbgems, as possible.
  • We recommend the contribute to mruby by implementing mrbgems.

2. Build

Using build.sh

# Default install
#  download nginx into ./build/
#  build with ngx_mruby into ./build/nginx

sh build.sh
# install with ENV

NGINX_CONFIG_OPT_ENV='--prefix=/usr/local/nginx-1.4.4' NGINX_SRC_ENV='/usr/local/src/nginx-1.4.4' sh build.sh

or Download Nginx, unpack, use configure for ngx_mruby, mruby build, ngx_mruby build.

$ cd ${NGX_MRUBY_SRC}
$ ./configure --with-ngx-src-root=${NGINX_SRC} --with-ngx-config-opt="--prefix=/usr/local/nginx"
$ make build_mruby
$ make

or configure with --add-module=${NGX_MRUBY_SRC} for nginx and make it

$ cd ${NGINX_SRC}
$ ./configure --prefix=/usr/local/nginx --add-module=${NGX_MRUBY_SRC} --add-module=${NGX_MRUBY_SRC}/dependence/ngx_devel_kit --add-module=${SOME_OTHER_MODULE}
$ make

3. Install

$ sudo make install

4. Add setting

location /mruby {
    mruby_content_handler '/usr/local/nginx/html/unified_hello.rb';
}

or file cache enabled

location /mruby {
    mruby_content_handler '/usr/local/nginx/html/unified_hello.rb' cache;
}

or inline code (cached)

location /mruby {
    mruby_content_handler_code '
      
      if server_name == "NGINX"
        Server = Nginx
      elsif server_name == "Apache"
        Server = Apache
      end
      
      Server::rputs "Hello #{Server::module_name}/#{Server::module_version} world!"
    
    ';
}

or Add handler

location ~ \.rb$ {
    mruby_add_handler on;
}

5. Create mruby script /usr/local/nginx/html/unified_hello.rb'

if server_name == "NGINX"
  Server = Nginx
elsif server_name == "Apache"
  Server = Apache
end

Server::rputs "Hello #{Server::module_name}/#{Server::module_version} world!"

6. Start nginx

/usr/local/nginx/sbin/nginx

7. Access http://127.0.0.1/mruby or http://127.0.0.1/unified_hello.rb 

Hello ngx_mruby/0.0.1 world!

Display above. Welcome mruby world for nginx!!

License

under the MIT License:

Add a custom footer
Add a custom sidebar
Clone this wiki locally