NAME
    HTTP::Parser::XS - a fast, primitive HTTP request parser

SYNOPSIS
      use HTTP::Parser::XS qw(parse_http_request);

      # for HTTP servers
      my $ret = parse_http_request(
          "GET / HTTP/1.0\r\nHost: ...\r\n\r\n",
          \%env,
      );
      if ($ret == -2) {
          # request is incomplete
          ...
      } elsif ($ret == -1) {
          # request is broken
          ...
      } else {
          # $ret includes the size of the request, %env now contains a PSGI
          # request, if it is a POST / PUT request, read request content by
          # yourself
          ...
      }


      # for HTTP clients
      use HTTP::Parser::XS qw(parse_http_response HEADERS_AS_ARRAYREF);
      my %special_headers = (
        'content-length' => undef,
      );
      my($ret, $minor_version, $status, $message, $headers)
        = parse_http_response($response, HEADERS_AS_ARRAYREF, \%special_headers);

      if($ret == -1) }
        # response is incomplete
      }
      elsif($ret == -2) {
        # response is broken
      }
      else {
        # $ret is the length of the headers, starting the content body

        # the other values are the response messages. For example:
        # $status  = 200
        # $message = "OK"
        # $headers = [ 'content-type' => 'text/html', ... ]

        # and $special_headers{'content-length'} will be filled in
      }

DESCRIPTION
    HTTP::Parser::XS is a fast, primitive HTTP request/response parser.

    The request parser can be used either for writing a synchronous HTTP
    server or a event-driven server.

    The response parser can be used for writing HTTP clients.

    Note that even if this distribution name ends "::XS", pure Perl
    implementation is supported, so you can use this module on compiler-less
    environments.

FUNCTIONS
    parse_http_request($request_string, \%env)
        Tries to parse given request string, and if successful, inserts
        variables into %env. For the name of the variables inserted, please
        refer to the PSGI specification. The return values are:

        >=0     length of the request (request line and the request
                headers), in bytes

        -1      given request is corrupt

        -2      given request is incomplete

        Note that the semantics of PATH_INFO is somewhat different from
        Apache. First, HTTP::Parser::XS does not validate the variable; it
        does not raise an error even if PATH_INFO does not start with "/".
        Second, the variable is conformant to RFC 3875 (and PSGI / Plack) in
        the fact that "//" and ".." appearing in PATH_INFO are preserved
        whereas Apache transcodes them.

    parse_http_response($response_string, $header_format, \%special_headers)
        Tries to parse given response string. *$header_format* must be
        "HEADERS_AS_ARRAYREF", "HEADERS_AS_HASHREF", or "HEADERS_NONE",
        which are exportable constants.

        The optional *%special_headers* is for headers you specifically
        require. You can set any HTTP response header names, which must be
        lower-cased, and their default values, and then the values are
        filled in by "parse_http_response()". For example, if you want the
        "Cointent-Length" field, set its name with default values like "%h =
        ('content-length' => undef)" and pass it as *%special_headers*.
        After parsing, $h{'content-length'} is set if the response has the
        "Content-Length" field, otherwise it's not touched.

        The return values are:

        $ret    The parsering status, which is the same as
                "parse_http_response()". i.e. the length of the response
                headers in bytes, -1 for incomplete headers, or -2 for
                errors.

                If the given response string is broken or imcomplete,
                "parse_http_response()" returns only this value.

        $minor_version
                The minor version of the given response. i.e. 1 for
                HTTP/1.1, 0 for HTTP/1.0.

        $status The HTTP status of the given response. e.g. 200 for success.

        $message
                The HTTP status message. e.g. "OK" for success.

        $headers
                The HTTP headers for the given response. It is an ARRAY
                reference if *$header_format* is "HEADERS_AS_ARRAYREF", a
                HASH reference on "HEADERS_AS_HASHREF", an "undef" on
                "HEADERS_NONE".

                The names of the headers are normalized to lower-cased.

LIMITATIONS
    Both "parse_http_request()" and "parse_http_response()" in XS
    implementation have some size limitations.

  The number of headers
    The number of headers is limited to 128. If it exceeds, both parsing
    routines report parsing errors, i.e. return -1 for $ret.

  The size of header names
    The size of header names is limited to 1024, but the parsers do not the
    same action.

    "parse_http_request()" returns -1 if too-long header names exist.

    "parse_http_request()" simply ignores too-long header names.

COPYRIGHT
    Copyright 2009- Kazuho Oku

AUTHORS
    *   Kazuho Oku <https://metacpan.org/author/KAZUHO>

    *   gfx <https://metacpan.org/author/GFUJI>

    *   mala <https://metacpan.org/author/MALA>

    *   tokuhirom <https://metacpan.org/author/TOKUHIROM>

    *   makamaka <https://metacpan.org/author/MAKAMAKA>

THANKS TO
    *   nothingmuch <https://metacpan.org/author/NUFFIN>

    *   charsbar <https://metacpan.org/author/CHARSBAR>

    *   DOLMEN <https://metacpan.org/author/DOLMEN>

SEE ALSO
    *   <http://github.com/kazuho/picohttpparser>

    *   HTTP::Parser

    *   HTTP::HeaderParser::XS

    *   Plack

    *   PSGI

LICENSE
    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.