1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
|
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.
|