openresty-component

1.Array Var Nginx Module  ArrayVarNginxModule
location /foo {
    array_split ',' $arg_files to=$array;

    # use the set_quote_sql_str directive in the ngx_set_misc
    # module to map to each element in the array $array:
    array_map_op set_quote_sql_str $array;

    array_map "name = $array_it" $array;

    array_join ' or ' $array to=$sql_condition;

    # well, we could feed it to ngx_drizzle to talk to MySQL, for example ;)
    echo "select * from files where $sql_condition";
}

2.AuthRequestNginxModule
location /private/ 
{ auth_request /auth; ... }
 location = /auth 
{ 
proxy_pass ... 
proxy_set_header X-Original-Uri $request_uri; 
... }

3.CoolkitNginxModule

ngx_coolkit is collection of small and useful nginx add-ons.

CONFIGURATION DIRECTIVES:
-------------------------

  override_method off | [methods] source (context: http, server, location)
  ------------------------------------------------------------------------
  Override HTTP method.

  default: none

CONFIGURATION VARIABLES:
------------------------

  $remote_passwd
  -----------------
  Decoded password from "Authorization" header (Basic HTTP Authentication).

  $location
  ---------
  Name of the matched location block.

EXAMPLE CONFIGURATION #1:
-------------------------
http {
    server {
        location / {
            override_method  $arg_method;
            proxy_pass       http://127.0.0.1:8100;
        }
    }
}

Pass request with changed HTTP method (based on "?method=XXX") to the backend.

EXAMPLE CONFIGURATION #2:
-------------------------
http {
    upstream database {
        postgres_server        127.0.0.1 dbname=test
                               user=monty password=some_pass;
    }

    server {
        location = /auth {
            internal;

            set_quote_sql_str  $user $remote_user;
            set_quote_sql_str  $pass $remote_passwd;

            postgres_pass      database;
            postgres_query     "SELECT login FROM users WHERE login=$user AND pass=$pass";
            postgres_rewrite   no_rows 403;
            postgres_output    none;
        }

        location / {
            auth_request       /auth;
            root               /files;
        }
    }
}

Restrict access to local files by authenticating against SQL database.

Required modules (other than ngx_coolkit):
- ngx_http_auth_request_module,
- ngx_postgres (PostgreSQL) or ngx_drizzle (MySQL, Drizzle, SQLite),
- ngx_set_misc.

4.Drizzle Nginx Module

Yichun Zhang, 26 Aug 2011 (created 21 Jun 2011)

 

This is an nginx upstream module that talks to MySQL and/or Drizzle database servers by libdrizzle.

This ngx_drizzle module is not enabled by default. You should specify the --with-http_drizzle_module optiotn while configuring OpenResty.

The libdrizzle C library is no longer bundled by OpenResty. You need to download the drizzle server tarball from https://launchpad.net/drizzle.

When you get the drizzle7 release tarball, you can install libdrizzle-1.0 like this:

tar xzvf drizzle7-VERSION.tar.gz
cd drizzle7-VERSION/
./configure --without-server
make libdrizzle-1.0
make install-libdrizzle-1.0

where VERSION is the drizzle7 release version number like 2011.06.20.

Please ensure that you have the python command point to a python2 interpreter. It's known that on recent Arch Linux distribution, python is linked to python3 by default, and while running make libdrizzle-1.0 will yield the following error:

File "config/pandora-plugin", line 185
    print "Dependency loop detected with %s" % plugin['name']
                                           ^
SyntaxError: invalid syntax
make: *** [.plugin.scan] Error 1

You can fix this by pointing python temporarily to python2.

When you install the libdrizzle-1.0 library to a custom path prefix, you can specify the libdrizzle prefix to OpenResty like this:

cd /path/to/ngx_openresty-VERSION/
./configure --with-libdrizzle=/path/to/drizzle --with-http_drizzle_module

https://github.com/openresty/drizzle-nginx-module#rds-header-part

 drizzle_connect_timeout 1s;
 drizzle_send_query_timeout 2s;
 drizzle_recv_cols_timeout 1s;
 drizzle_recv_rows_timeout 1s;

 location /query {
     drizzle_query 'select sleep(10)';
     drizzle_pass my_backend;
     rds_json on;

     more_set_headers -s 504 'X-Mysql-Tid: $drizzle_thread_id';
 }

 location /kill {
     drizzle_query "kill query $arg_tid";
     drizzle_pass my_backend;
     rds_json on;
 }

 location /main {
     content_by_lua '
         local res = ngx.location.capture("/query")
         if res.status ~= ngx.HTTP_OK then
             local tid = res.header["X-Mysql-Tid"]
             if tid and tid ~= "" then
                 ngx.location.capture("/kill", { args = {tid = tid} })
             end
             return ngx.HTTP_INTERNAL_SERVER_ERROR;
         end
         ngx.print(res.body)
     '
 }

 5.Echo Nginx Module

This module wraps lots of Nginx internal APIs for streaming input and output, parallel/sequential subrequests, timers and sleeping, as well as various meta data accessing.

Basically it provides various utilities that help testing and debugging of other modules by trivially emulating different kinds of faked subrequest locations.

   location /hello {
     echo "hello, world!";
   }

   location /hello {
     echo -n "hello, ";
     echo "world!";
   }

   location /timed_hello {
     echo_reset_timer;
     echo hello world;
     echo "'hello world' takes about $echo_timer_elapsed sec.";
     echo hiya igor;
     echo "'hiya igor' takes about $echo_timer_elapsed sec.";
   }

   location /echo_with_sleep {
     echo hello;
     echo_flush;  # ensure the client can see previous output immediately
     echo_sleep   2.5;  # in sec
     echo world;
   }

   # in the following example, accessing /echo yields
   #   hello
   #   world
   #   blah
   #   hiya
   #   igor
   location /echo {
       echo_before_body hello;
       echo_before_body world;
       proxy_pass $scheme://127.0.0.1:$server_port$request_uri/more;
       echo_after_body hiya;
       echo_after_body igor;
   }
   location /echo/more {
       echo blah;
   }

   # the output of /main might be
   #   hello
   #   world
   #   took 0.000 sec for total.
   # and the whole request would take about 2 sec to complete.
   location /main {
       echo_reset_timer;

       # subrequests in parallel
       echo_location_async /sub1;
       echo_location_async /sub2;

       echo "took $echo_timer_elapsed sec for total.";
   }
   location /sub1 {
       echo_sleep 2;
       echo hello;
   }
   location /sub2 {
       echo_sleep 1;
       echo world;
   }

   # the output of /main might be
   #   hello
   #   world
   #   took 3.003 sec for total.
   # and the whole request would take about 3 sec to complete.
   location /main {
       echo_reset_timer;

       # subrequests in series (chained by CPS)
       echo_location /sub1;
       echo_location /sub2;

       echo "took $echo_timer_elapsed sec for total.";
   }
   location /sub1 {
       echo_sleep 2;
       echo hello;
   }
   location /sub2 {
       echo_sleep 1;
       echo world;
   }

   # Accessing /dup gives
   #   ------ END ------
   location /dup {
     echo_duplicate 3 "--";
     echo_duplicate 1 " END ";
     echo_duplicate 3 "--";
     echo;
   }

   # /bighello will generate 1000,000,000 hello's.
   location /bighello {
     echo_duplicate 1000_000_000 'hello';
   }

   # echo back the client request
   location /echoback {
     echo_duplicate 1 $echo_client_request_headers;
     echo "\r";

     echo_read_request_body;

     echo_request_body;
   }

   # GET /multi will yields
   #   querystring: foo=Foo
   #   method: POST
   #   body: hi
   #   content length: 2
   #   ///
   #   querystring: bar=Bar
   #   method: PUT
   #   body: hello
   #   content length: 5
   #   ///
   location /multi {
       echo_subrequest_async POST '/sub' -q 'foo=Foo' -b 'hi';
       echo_subrequest_async PUT '/sub' -q 'bar=Bar' -b 'hello';
   }
   location /sub {
       echo "querystring: $query_string";
       echo "method: $echo_request_method";
       echo "body: $echo_request_body";
       echo "content length: $http_content_length";
       echo '///';
   }

   # GET /merge?/foo.js&/bar/blah.js&/yui/baz.js will merge the .js resources together
   location /merge {
       default_type 'text/javascript';
       echo_foreach_split '&' $query_string;
           echo "/* JS File $echo_it */";
           echo_location_async $echo_it;
           echo;
       echo_end;
   }

   # accessing /if?val=abc yields the "hit" output
   # while /if?val=bcd yields "miss":
   location ^~ /if {
       set $res miss;
       if ($arg_val ~* '^a') {
           set $res hit;
           echo $res;
       }
       echo $res;
   }

https://github.com/openresty/echo-nginx-module
6.EncryptedSessionNginxModule

# key must be of 32 bytes long
encrypted_session_key "abcdefghijklmnopqrstuvwxyz123456";

# iv must not be longer than 16 bytes
#   default: "deadbeefdeadbeef" (w/o quotes)
encrypted_session_iv "1234567812345678";

# default: 1d (1 day)
encrypted_session_expires 3600; # in sec

location /encrypt {
    set $raw 'text to encrypted'; # from the ngx_rewrite module
    set_encrypt_session $session $raw;
    set_encode_base32 $session; # from the ngx_set_misc module

    add_header Set-Cookie 'my_login=$session';  # from the ngx_headers module

    # your content handler goes here...
}

location /decrypt {
    set_decode_base32 $session $cookie_my_login; # from the ngx_set_misc module
    set_decrypt_session $raw $session;

    if ($raw = '') {
        # bad session
    }

    # your content handler goes here...
}

Description

This module provides encryption and decryption support for nginx variables based on AES-256 with Mac.

This module is usually used with the ngx_set_misc module and the standard rewrite module's directives.

This module can be used to implement simple user login and ACL.

Usually, you just decrypt data in nginx level, and pass the unencrypted data to your FastCGI/HTTP backend, as in

location /blah {
    set_decrypt_session $raw_text $encrypted;

    # this directive is from the ngx_set_misc module
    set_escape_uri $escaped_raw_text $raw_text;

    fastcgi_param QUERY_STRING "uid=$uid";
    fastcgi_pass unix:/path/to/my/php/or/python/fastcgi.sock;
}

Lua web applications running directly on ngx_lua can call this module's directives directly from within Lua code:

local raw_text = ndk.set_var.set_decrypt_session(encrypted_text)

 

7.FormInputNginxModule

set_form_input $variable;
set_form_input $variable argument;

set_form_input_multi $variable;
set_form_input_multi $variable argument;

example:

#nginx.conf

location /foo {
    # ensure client_max_body_size == client_body_buffer_size
    client_max_body_size 100k;
    client_body_buffer_size 100k;

    set_form_input $data;    # read "data" field into $data
    set_form_input $foo foo; # read "foo" field into $foo
}

location /bar {
    # ensure client_max_body_size == client_body_buffer_size
    client_max_body_size 1m;
    client_body_buffer_size 1m;

    set_form_input_multi $data; # read all "data" field into $data
    set_form_input_multi $foo data; # read all "data" field into $foo

    array_join ' ' $data; # now $data is an string
    array_join ' ' $foo;  # now $foo is an string
}

8.

 # set the Server output header
 more_set_headers 'Server: my-server';

 # set and clear output headers
 location /bar {
     more_set_headers 'X-MyHeader: blah' 'X-MyHeader2: foo';
     more_set_headers -t 'text/plain text/css' 'Content-Type: text/foo';
     more_set_headers -s '400 404 500 503' -s 413 'Foo: Bar';
     more_clear_headers 'Content-Type';

     # your proxy_pass/memcached_pass/or any other config goes here...
 }

 # set output headers
 location /type {
     more_set_headers 'Content-Type: text/plain';
     # ...
 }

 # set input headers
 location /foo {
     set $my_host 'my dog';
     more_set_input_headers 'Host: $my_host';
     more_set_input_headers -t 'text/plain' 'X-Foo: bah';

     # now $host and $http_host have their new values...
     # ...
 }

 # replace input header X-Foo *only* if it already exists
 more_set_input_headers -r 'X-Foo: howdy';

8.HeadersMoreNginxModule

Description

This module allows you to add, set, or clear any output or input header that you specify.

This is an enhanced version of the standard headers module because it provides more utilities like resetting or clearing "builtin headers" like Content-Type, Content-Length, and Server.

It also allows you to specify an optional HTTP status code criteria using the -s option and an optional content type criteria using the -t option while modifying the output headers with the more_set_headers and more_clear_headers directives. For example,

 more_set_headers -s 404 -t 'text/html' 'X-Foo: Bar';

You can also specify multiple MIME types to filter out in a single -t option. For example,

more_set_headers -t 'text/html text/plain' 'X-Foo: Bar';

Never use other paramemters like charset=utf-8 in the -t option values; they will not work as you would expect.

Input headers can be modified as well. For example

 location /foo {
     more_set_input_headers 'Host: foo' 'User-Agent: faked';
     # now $host, $http_host, $user_agent, and
     #   $http_user_agent all have their new values.
 }

The option -t is also available in the more_set_input_headers and more_clear_input_headers directives (for request header filtering) while the -s option is not allowed.

Unlike the standard headers module, this module's directives will by default apply to all the status codes, including 4xx and 5xx.

9.IconvNginxModule

#nginx.conf

 location /foo {
     set $src '你好'; #in UTF-8
     set_iconv $dst $src from=utf8 to=gbk; #now $dst holds 你好 in GBK
 }

 #everything generated from /foo will be converted from utf8 to gbk
 location /bar {
     iconv_filter from=utf-8 to=gbk;
     iconv_buffer_size 1k;
     #content handler here
 }

10.lua-nginx-module

 # set search paths for pure Lua external libraries (';;' is the default path):
 lua_package_path '/foo/bar/?.lua;/blah/?.lua;;';

 # set search paths for Lua external libraries written in C (can also use ';;'):
 lua_package_cpath '/bar/baz/?.so;/blah/blah/?.so;;';

 server {
     location /lua_content {
         # MIME type determined by default_type:
         default_type 'text/plain';

         content_by_lua_block {
             ngx.say('Hello,world!')
         }
     }

     location /nginx_var {
         # MIME type determined by default_type:
         default_type 'text/plain';

         # try access /nginx_var?a=hello,world
         content_by_lua_block {
             ngx.say(ngx.var.arg_a)
         }
     }

     location = /request_body {
         client_max_body_size 50k;
         client_body_buffer_size 50k;

         content_by_lua_block {
             ngx.req.read_body()  -- explicitly read the req body
             local data = ngx.req.get_body_data()
             if data then
                 ngx.say("body data:")
                 ngx.print(data)
                 return
             end

             -- body may get buffered in a temp file:
             local file = ngx.req.get_body_file()
             if file then
                 ngx.say("body is in file ", file)
             else
                 ngx.say("no body found")
             end
         }
     }

     # transparent non-blocking I/O in Lua via subrequests
     # (well, a better way is to use cosockets)
     location = /lua {
         # MIME type determined by default_type:
         default_type 'text/plain';

         content_by_lua_block {
             local res = ngx.location.capture("/some_other_location")
             if res then
                 ngx.say("status: ", res.status)
                 ngx.say("body:")
                 ngx.print(res.body)
             end
         }
     }

     location = /foo {
         rewrite_by_lua_block {
             res = ngx.location.capture("/memc",
                 { args = { cmd = "incr", key = ngx.var.uri } }
             )
         }

         proxy_pass http://blah.blah.com;
     }

     location = /mixed {
         rewrite_by_lua_file /path/to/rewrite.lua;
         access_by_lua_file /path/to/access.lua;
         content_by_lua_file /path/to/content.lua;
     }

     # use nginx var in code path
     # CAUTION: contents in nginx var must be carefully filtered,
     # otherwise there'll be great security risk!
     location ~ ^/app/([-_a-zA-Z0-9/]+) {
         set $path $1;
         content_by_lua_file /path/to/lua/app/root/$path.lua;
     }

     location / {
        client_max_body_size 100k;
        client_body_buffer_size 100k;

        access_by_lua_block {
            -- check the client IP address is in our black list
            if ngx.var.remote_addr == "132.5.72.3" then
                ngx.exit(ngx.HTTP_FORBIDDEN)
            end

            -- check if the URI contains bad words
            if ngx.var.uri and
                   string.match(ngx.var.request_body, "evil")
            then
                return ngx.redirect("/terms_of_use.html")
            end

            -- tests passed
        }

        # proxy_pass/fastcgi_pass/etc settings
     }
 }