Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
An Nginx module for bringing the power of "echo", "sleep", "time" and more to Nginx's config file
C Perl Shell

Fetching latest commit…

Cannot retrieve the latest commit at this time

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

README

Description

This is an Nginx module for bringing the power of "echo", "sleep", "time" and
more to Nginx's config file.

Installation

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

    $ wget 'http://sysoev.ru/nginx/nginx-0.8.20.tar.gz'
    $ tar -xzvf nginx-0.8.20.tar.gz
    $ cd nginx-0.8.20/
    $ ./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_flush;  # need this to force flushing outputs before sleep
                echo_sleep 1;  # sleep for 1 sec here...
                echo 'after sleep';
            }

            location /timed_sleep {
                echo_sleep 0.03;
                echo "$echo_timer_elapsed sec elapsed.";

                echo_reset_timer;
                echo_sleep 0.02;
                echo "$echo_timer_elapsed sec elapsed.";
            }
            ...
        }
        ...
    }

As you can see, the directives currently provided by this module are
"echo", "echo_client_request_headers", "echo_sleep", "echo_flush",
and "echo_reset_timer". And there's also an "echo_blocking_sleep"
directive for completeness.

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.

On the other hand, "echo_blocking_sleep" is a blocking version of
"echo_sleep" and it will freeze the whole Nginx worker process. It's
provided merely meant to be compared with "echo_sleep". And you should
never use it for production.

The "echo_flush" directive is needed whenever you need to force flushing the previous
outputs potentially buffered without sending to the client.

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

    $ curl 'http://localhost/timed_sleep'
    0.032 sec elapsed.
    0.020 sec elapsed.

Variables

This module implements the $echo_timer_elapsed variable.

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.

TODO

* Add echo_before_body and echo_after_body (output) filter directives.
* Add echo_location and echo_location_async directives.
* Add echo_file and echo_cached_file directives.

Copyright & License

Copyright (c) 2009, Taobao Inc., Alibaba Group ( http://www.taobao.com ).
Copyright (c) 2009, agentzh <agentzh@gmail.com>.

This module is licensed under the terms of the BSD license.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

    * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

    * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

    * Neither the name of the Taobao Inc. nor the names of its
    contributors may be used to endorse or promote products derived from
    this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Contact the author

Please write to agentzh at gmail dot com whenever you have any questions.

Something went wrong with that request. Please try again.