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