**********************************************************************
* Author  : Brian Maher <maherb at brimworks dot com>
* Library : lua-http-parser - Lua 5.1 interface to ry's http-parser
*
* The MIT License
*
* Copyright (c) 2009-1010 Brian Maher
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
**********************************************************************

To use this library, you need joyent's http-parser, get it here:
    git clone git://github.com/joyent/http-parser.git

To build this library, you need luarocks, get it here:
    http://www.luarocks.org/en/Download

    Then build it like this:

    luarocks make CFLAGS=-g

Loading the library:

    If you built the library as a loadable package
        [local] lhp = require 'http.parser'

    If you compiled the package statically into your application, call
    the function "luaopen_http_parser(L)". It will create a table with the
    http parser functions and leave it on the top of the stack.

To test the library run:

    ./test.lua

    ...assuming that the `lua` on your PATH properly uses the luarocks
    installed module.

API:

    parser = lhp.request {
        on_url          = function(url)  ... end
        on_header       = function(hkey, hval) ... end
        on_body         = function(body) ... end

        on_message_begin    = function() ... end
        on_message_complete = function() ... end
        on_headers_complete = function() ... end
    }
    parser = lhp.response { ... }

        Create a new HTTP parser to handle either an HTTP request or
        HTTP response respectively.  Pass in a table of callbacks that
        are ran when the parser encounters the various fields.  All
        callbacks will be ran with the full value for that field with
        on_body being the notible exception.

        You can treat the on_body handler as an LTN12 "source" since
        it is always garanteed to send a terminating on_body(nil)
        event when the complete body has been read.  Note that the
        on_body(nil) event will even be sent if there is an empty
        body.

        NOTE: Ry's http parser may call any of these callbacks with a
        partial value if the input_bytes are split on a "token"
        boundary.  At this point we always assume that you will want
        everything except the body to be buffered, but if you have a
        valid use case for manually setting which callbacks are
        buffered, please send an email to the author.

    bytes_read = parser:execute(input_bytes)

        Feed the parser some partial input.  Returns how many bytes
        where read.  A short read may happen if a request is being
        "upgraded" or was an invalid format.  See parser:is_upgrade()
        below to differentiate between these two events (if you want
        to support an upgraded protocol).

        NOTE: If the input_bytes causes more than about 2000 event
        callbacks to be executed a short read will occur and any
        attempt to continue the parse will fail.  If this is a
        problem, restrict your input to < 8K input_bytes at a time,
        although in general this is probaly more of a symptom of a
        DDoS attack and therefore returning status 400 (Bad Request)
        is probably the best thing to do anyways.

    parser:should_keep_alive()

        Returns true if this TCP connection should be "kept alive"
        so that it can be re-used for a future request/response.
        If this returns false and you are the server, then respond
        with the "Connection: close" header.  If you are the client,
        then simply close the connection.

    parser:is_upgrade()

        Returns true if the input request wants to "upgrade" to a
        different protocol.

    parser:version()

        Returns HTTP version as two numbers (major, minor).

    parser:method()

        Returns the name of the request method.  This is only valid
        on HTTP requests.

    parser:error()

        Returns errno(number), error name(string), error description(string).

    parser:reset()

        Re-initialize HTTP parser clearing any previous error/state.

    parser:status_code()

        Returns the HTTP status code of a response.  This is only valid
        on HTTP responses.