Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
An Nginx module for bringing the power of "echo", "sleep", "time" and more to Nginx's config file
C Perl Other

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
src
test
.gitignore
README
config

README

Description

An nginx module for bringing the power of sh's "echo" command to Nginx's config file.

Installation

Grab the nginx source code from http://nginx.net/ (version 0.7.62
and 0.8.19 have been tested on my side), for example,
the version 0.8.19 and then build the source with this module:

    $ wget 'http://sysoev.ru/nginx/nginx-0.8.19.tar.gz'
    $ tar -xzvf nginx-0.8.19.tar.gz
    $ cd nginx-0.8.19/
    $ ./configure --prefix=/opt/nginx \
        --add-module=/path/to/echo-nginx-module

Configuration

This is a sample configuration snippet in your nginx.conf file:

    http {
        ...
        server {
            ...

            default_type text/plain;

            location /hello {
                echo 'hello, world';
                echo;
                echo hello world;
            }

            location /echoback {
                echo "------------------------";
                echo_client_request_headers;
            }

            location /server {
                echo "Server name: $server_name";
                echo "Server address: $server_addr";
                echo "Server port: $server_port";
                echo "Server protocol: $server_protocol";
            }

            location /echo_with_sleep {
                echo 'before sleep';
                echo_sleep 1;
                echo 'after sleep';
            }
            ...
        }
        ...
    }

As you can see, the directives currently provided by this module are
"echo", "echo_client_request_headers", and "echo_sleep".

The "echo_sleep" directive is a non-blocking sleep on the server side. So if your
nginx worker process is "sleeping" for one request, it could serve other requests
*at the same time*. On my laptop, with only 1 nginx worker process, my nginx can
achieve 5500+ requests per second at the concurrency level of 10k.

After starting the nginx server, one can query it these ways:

    $ curl 'http://localhost/hello'
    hello, world

    hello world

    $ curl 'http://localhost/echoback'
    ------------------------
    GET /echoback HTTP/1.1
    User-Agent: curl/7.18.2 (i486-pc-linux-gnu) libcurl/7.18.2 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.10
    Host: localhost
    Accept: */*

    $ curl 'http://localhost/server'
    Server name: localhost
    Server address: 127.0.0.1
    Server port: 80
    Server protocol: HTTP/1.1

    $ time curl 'http://localhost/echo_with_sleep'
    before sleep
    after sleep

    real    0m1.018s
    user    0m0.012s
    sys     0m0.008s

Test suite

This module comes with a Perl-driven test suite. The test cases are
declarative too. Thanks to the Test::Base module in the Perl world.

To run it on your side:

    $ cd test
    $ PATH=/path/to/your/nginx-with-echo-module:$PATH prove -r t

You need to terminate any nginx processes before running the test
suite if you have changed the nginx server binary.

Contact me

Contact the author by agentzh at gmail dot com whenever you have any questions.

Something went wrong with that request. Please try again.