1HTTP::Parser::XS(3) User Contributed Perl Documentation HTTP::Parser::XS(3)
2
6 HTTP::Parser::XS - a fast, primitive HTTP request parser
7
9 use HTTP::Parser::XS qw(parse_http_request);
10 # for HTTP servers
12 my $ret = parse_http_request(
13 "GET / HTTP/1.0\r\nHost: ...\r\n\r\n",
14 \%env,
15 );
16 if ($ret == -2) {
17 # request is incomplete
18 ...
19 } elsif ($ret == -1) {
20 # request is broken
21 ...
22 } else {
23 # $ret includes the size of the request, %env now contains a PSGI
24 # request, if it is a POST / PUT request, read request content by
25 # yourself
26 ...
27 }
28 # for HTTP clients
31 use HTTP::Parser::XS qw(parse_http_response HEADERS_AS_ARRAYREF);
32 my %special_headers = (
33 'content-length' => undef,
34 );
35 my($ret, $minor_version, $status, $message, $headers)
36 = parse_http_response($response, HEADERS_AS_ARRAYREF, \%special_headers);
37 if($ret == -1) }
39 # response is incomplete
40 }
41 elsif($ret == -2) {
42 # response is broken
43 }
44 else {
45 # $ret is the length of the headers, starting the content body
46 # the other values are the response messages. For example:
48 # $status = 200
49 # $message = "OK"
50 # $headers = [ 'content-type' => 'text/html', ... ]
51 # and $special_headers{'content-length'} will be filled in
53 }
54
56 HTTP::Parser::XS is a fast, primitive HTTP request/response parser.
57 The request parser can be used either for writing a synchronous HTTP
59 server or a event-driven server.
60 The response parser can be used for writing HTTP clients.
62 Note that even if this distribution name ends "::XS", pure Perl
64 implementation is supported, so you can use this module on compiler-
65 less environments.
66
68 parse_http_request($request_string, \%env)
69 Tries to parse given request string, and if successful, inserts
70 variables into %env. For the name of the variables inserted,
71 please refer to the PSGI specification. The return values are:
72 >=0 length of the request (request line and the request
74 headers), in bytes
75 -1 given request is corrupt
77 -2 given request is incomplete
79 Note that the semantics of PATH_INFO is somewhat different from
81 Apache. First, HTTP::Parser::XS does not validate the variable; it
82 does not raise an error even if PATH_INFO does not start with "/".
83 Second, the variable is conformant to RFC 3875 (and PSGI / Plack)
84 in the fact that "//" and ".." appearing in PATH_INFO are preserved
85 whereas Apache transcodes them.
86 parse_http_response($response_string, $header_format,
88 \%special_headers)
89 Tries to parse given response string. $header_format must be
90 "HEADERS_AS_ARRAYREF", "HEADERS_AS_HASHREF", or "HEADERS_NONE",
91 which are exportable constants.
92 The optional %special_headers is for headers you specifically
94 require. You can set any HTTP response header names, which must be
95 lower-cased, and their default values, and then the values are
96 filled in by parse_http_response(). For example, if you want the
97 "Cointent-Length" field, set its name with default values like "%h
98 = ('content-length' => undef)" and pass it as %special_headers.
99 After parsing, $h{'content-length'} is set if the response has the
100 "Content-Length" field, otherwise it's not touched.
101 The return values are:
103 $ret The parsering status, which is the same as
105 parse_http_response(). i.e. the length of the response
106 headers in bytes, -1 for incomplete headers, or -2 for
107 errors.
108 If the given response string is broken or imcomplete,
110 parse_http_response() returns only this value.
111 $minor_version
113 The minor version of the given response. i.e. 1 for
114 HTTP/1.1, 0 for HTTP/1.0.
115 $status The HTTP status of the given response. e.g. 200 for
117 success.
118 $message
120 The HTTP status message. e.g. "OK" for success.
121 $headers
123 The HTTP headers for the given response. It is an ARRAY
124 reference if $header_format is "HEADERS_AS_ARRAYREF", a
125 HASH reference on "HEADERS_AS_HASHREF", an "undef" on
126 "HEADERS_NONE".
127 The names of the headers are normalized to lower-cased.
129
131 Both parse_http_request() and parse_http_response() in XS
132 implementation have some size limitations.
133 The number of headers
135 The number of headers is limited to 128. If it exceeds, both parsing
136 routines report parsing errors, i.e. return -1 for $ret.
137 The size of header names
139 The size of header names is limited to 1024, but the parsers do not the
140 same action.
141 parse_http_request() returns -1 if too-long header names exist.
143 parse_http_request() simply ignores too-long header names.
145
147 Copyright 2009- Kazuho Oku
148
150 • Kazuho Oku <https://metacpan.org/author/KAZUHO>
151 • gfx <https://metacpan.org/author/GFUJI>
153 • mala <https://metacpan.org/author/MALA>
155 • tokuhirom <https://metacpan.org/author/TOKUHIROM>
157
159 • nothingmuch <https://metacpan.org/author/NUFFIN>
160 • charsbar <https://metacpan.org/author/CHARSBAR>
162 • DOLMEN <https://metacpan.org/author/DOLMEN>
164
166 • <http://github.com/kazuho/picohttpparser>
167 • HTTP::Parser
169 • HTTP::HeaderParser::XS
171 • Plack
173 • PSGI
175
177 This library is free software; you can redistribute it and/or modify it
178 under the same terms as Perl itself.
179perl v5.38.0 2023-07-20 HTTP::Parser::XS(3)