GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [PHP Manual] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

  [0-9] [Aa] [Bb] [Cc] [Dd] [Ee] [Ff] [Gg] [Hh] [Ii] [Jj] [Kk] [Ll] [Mm] [Nn] [Oo] [Pp] [Qq] [Rr] [Ss] [Tt] [Uu] [Vv] [Ww] [Xx] [Yy] [Zz]


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
Host: ...

",
             \%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

AUTHOR

       Kazuho Oku gfx mala tokuhirom

THANKS TO

       nothingmuch charsbar

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.



  All copyrights belong to their respective owners. Other content (c) 2014-2018, GNU.WIKI. Please report site errors to webmaster@gnu.wiki.
Page load time: 0.103 seconds. Last modified: November 04 2018 12:49:43.