Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
HTTP 1.1 chunked-encoding request body support for Nginx
C Perl Ragel in Ruby Host Shell

Fetching latest commit…

Cannot retrieve the latest commit at this time

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

README

Name
    chunkin-nginx-module - HTTP 1.1 chunked-encoding request body support
    for Nginx.

    *This module is not distributed with the Nginx source.* See the
    installation instructions.

Version
    This document describes chunkin-nginx-module v0.06
    (<http://github.com/agentzh/chunkin-nginx-module/downloads>) released on
    Nov 16, 2009.

Synopsis
      chunkin on;
      location { ... }
      ...

Description
    This module adds HTTP 1.1 chunked input support for Nginx without the
    need of patching the Nginx core.

    Behind the scene, it registers an access-phase handler that will eagerly
    read and decode incoming request bodies when a "Transfer-Encoding:
    chunked" header triggers a 411 error page in Nginx (hey, that's what you
    have to pay for avoiding patching the core ;)). For requests that are
    not in the "chunked" transfer encoding, this module is a "no-op".

    To enable the magic, just turn on the "chunkin" config option like this:

        chunkin on;
        location /foo { ... }
        ....

    No other modification is required in your nginx.conf file. (The
    "chunkin" directive is not allowed in the location block BTW.)

    WARNING: This module is in its very early phase in development and is
    considered *highly experimental*. But you're encouraged to play and test
    it in your non-production environment and report any quirks that you
    find.

    Efforts have been made to reduce data copying and dynamic memory
    allocation, thus unfortunately raising the risk of potential buffer
    handling bugs caused by premature optimizations :P

    This module is not supposed to be merged into the Nginx core because
    I've used Ragel to generate the chunked encoding parser for joy :)

Directives
  chunkin
    syntax: *chunkin on|off*

    default: *off*

    context: *http, server*

    Enables or disables this module's hooks.

Installation
    Grab the nginx source code from nginx.net (<http://nginx.net/>), for
    example, the version 0.8.24 (see nginx compatibility), and then build
    the source with this module:

        $ wget 'http://sysoev.ru/nginx/nginx-0.8.24.tar.gz'
        $ tar -xzvf nginx-0.8.24.tar.gz
        $ cd nginx-0.8.24/

        # Here we assume you would install you nginx under /opt/nginx/.
        $ ./configure --prefix=/opt/nginx \
            --add-module=/path/to/chunkin-nginx-module

        $ make -j2
        $ make install

    Download the latest version of the release tarball of this module from
    chunkin-nginx-module file list
    (<http://github.com/agentzh/chunkin-nginx-module/downloads>).

  For Developers
    The chunked parser is generated by Ragel
    (<http://www.complang.org/ragel/>). If you want to regenerate the
    parser's C file, i.e., src/chunked_parser.c
    (<http://github.com/agentzh/chunkin-nginx-module/blob/master/src/chunked
    _parser.c>), use the following command from the root of the chunkin
    module's source tree:

        $ ragel -G2 src/chunked_parser.rl

Compatibility
    The following versions of Nginx should work with this module:

    *   0.8.x (last tested version is 0.8.24)

    *   0.7.x >= 0.7.21 (last tested version is 0.7.63)

    Earlier versions of Nginx like 0.6.x and 0.5.x will *not* work.

    If you find that any particular version of Nginx above 0.7.21 does not
    work with this module, please consider reporting a bug.

Report Bugs
    Although a lot of effort has been put into testing and code tuning,
    there must be some serious bugs lurking somewhere in this module. So
    whenever you are bitten by any quirks, please don't hesitate to

    1.  send a bug report or even patches to <agentzh@gmail.com>,

    2.  or create a ticket on the issue tracking interface
        (<http://github.com/agentzh/chunkin-nginx-module/issues>) provided
        by GitHub.

Source Repository
    Available on github at agentzh/chunkin-nginx-module
    (<http://github.com/agentzh/chunkin-nginx-module>).

ChangeLog
  v0.06
    *   minor optimization: we won't traverse the output chain link if the
        chain count is not large enough.

Test Suite
    This module comes with a Perl-driven test suite. The test cases
    (<http://github.com/agentzh/chunkin-nginx-module/tree/master/test/t/>)
    are declarative
    (<http://github.com/agentzh/chunkin-nginx-module/blob/master/test/t/sani
    ty.t>) too. Thanks to the Test::Base
    (<http://search.cpan.org/perldoc?Test::Base>) module in the Perl world.

    To run it on your side:

        $ cd test
        $ PATH=/path/to/your/nginx-with-chunkin-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.

    At the moment, LWP::UserAgent
    (<http://search.cpan.org/perldoc?LWP::UserAgent>) is used by the test
    scaffold
    (<http://github.com/agentzh/chunkin-nginx-module/blob/master/test/lib/Te
    st/Nginx/LWP.pm>) for simplicity.

    Because a single nginx server (by default, "localhost:1984") is used
    across all the test scripts (".t" files), it's meaningless to run the
    test suite in parallel by specifying "-jN" when invoking the "prove"
    utility.

    Some parts of the test suite requires modules proxy and echo to be
    enabled as well when building Nginx.

Known Issues
    1.  "client_body_in_single_buffer on" may *not* be obeyed for short
        contents and fast network.

    2.  "client_body_in_file_only on" may *not* be obeyed for short contents
        and fast network.

TODO
    Fix the known issues.

Getting involved
    You'll be very welcomed to submit patches to the author or just ask for
    a commit bit to the source repository on GitHub.

Author
    agentzh (章亦春) *<agentzh@gmail.com>*

    This wiki page is also maintained by the author himself, and everybody
    is encouraged to improve this page as well.

Copyright & License
    The basic client request body reading code is based on the
    "ngx_http_read_client_request_body" function and its utility functions
    in the Nginx 0.8.20 core. This part of code is copyrighted by Igor
    Sysoev.

    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.

See Also
    *   The original thread on Nginx mailing list that inspires this
        module's development: "'Content-Length' header for POSTs"
        (<http://forum.nginx.org/read.php?2,4453,20543>).

    *   The original blog post
        (<http://agentzh.spaces.live.com/blog/cns!FF3A735632E41548!481.entry
        >) about this module's initial development.

    *   The echo module for Nginx module's automated testing.

Something went wrong with that request. Please try again.