1HTTP::Parser::XS(3)   User Contributed Perl Documentation  HTTP::Parser::XS(3)
2
3
4

NAME

6       HTTP::Parser::XS - a fast, primitive HTTP request parser
7

SYNOPSIS

9         use HTTP::Parser::XS qw(parse_http_request);
10
11         # 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
29
30         # 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
38         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
47           # the other values are the response messages. For example:
48           # $status  = 200
49           # $message = "OK"
50           # $headers = [ 'content-type' => 'text/html', ... ]
51
52           # and $special_headers{'content-length'} will be filled in
53         }
54

DESCRIPTION

56       HTTP::Parser::XS is a fast, primitive HTTP request/response parser.
57
58       The request parser can be used either for writing a synchronous HTTP
59       server or a event-driven server.
60
61       The response parser can be used for writing HTTP clients.
62
63       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

FUNCTIONS

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
73           >=0     length of the request (request line and the request
74                   headers), in bytes
75
76           -1      given request is corrupt
77
78           -2      given request is incomplete
79
80           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
87       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
93           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
102           The return values are:
103
104           $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
109                   If the given response string is broken or imcomplete,
110                   parse_http_response() returns only this value.
111
112           $minor_version
113                   The minor version of the given response.  i.e. 1 for
114                   HTTP/1.1, 0 for HTTP/1.0.
115
116           $status The HTTP status of the given response. e.g. 200 for
117                   success.
118
119           $message
120                   The HTTP status message. e.g. "OK" for success.
121
122           $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
128                   The names of the headers are normalized to lower-cased.
129

LIMITATIONS

131       Both parse_http_request() and parse_http_response() in XS
132       implementation have some size limitations.
133
134   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
138   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
142       parse_http_request() returns -1 if too-long header names exist.
143
144       parse_http_request() simply ignores too-long header names.
145
147       Copyright 2009- Kazuho Oku
148

AUTHORS

150       •   Kazuho Oku <https://metacpan.org/author/KAZUHO>
151
152       •   gfx <https://metacpan.org/author/GFUJI>
153
154       •   mala <https://metacpan.org/author/MALA>
155
156       •   tokuhirom <https://metacpan.org/author/TOKUHIROM>
157

THANKS TO

159       •   nothingmuch <https://metacpan.org/author/NUFFIN>
160
161       •   charsbar <https://metacpan.org/author/CHARSBAR>
162
163       •   DOLMEN <https://metacpan.org/author/DOLMEN>
164

SEE ALSO

166       •   <http://github.com/kazuho/picohttpparser>
167
168       •   HTTP::Parser
169
170       •   HTTP::HeaderParser::XS
171
172       •   Plack
173
174       •   PSGI
175

LICENSE

177       This library is free software; you can redistribute it and/or modify it
178       under the same terms as Perl itself.
179
180
181
182perl v5.38.0                      2023-07-20               HTTP::Parser::XS(3)
Impressum