NAME

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

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

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