.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "HTTP::Parser::XS 3pm" .TH HTTP::Parser::XS 3pm "2018-11-01" "perl v5.28.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" HTTP::Parser::XS \- a fast, primitive HTTP request parser .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use HTTP::Parser::XS qw(parse_http_request); \& \& # for HTTP servers \& my $ret = parse_http_request( \& "GET / HTTP/1.0\er\enHost: ...\er\en\er\en", \& \e%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 = ( \& \*(Aqcontent\-length\*(Aq => undef, \& ); \& my($ret, $minor_version, $status, $message, $headers) \& = parse_http_response($response, HEADERS_AS_ARRAYREF, \e%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 = [ \*(Aqcontent\-type\*(Aq => \*(Aqtext/html\*(Aq, ... ] \& \& # and $special_headers{\*(Aqcontent\-length\*(Aq} will be filled in \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" HTTP::Parser::XS is a fast, primitive \s-1HTTP\s0 request/response parser. .PP The request parser can be used either for writing a synchronous \s-1HTTP\s0 server or a event-driven server. .PP The response parser can be used for writing \s-1HTTP\s0 clients. .PP Note that even if this distribution name ends \f(CW\*(C`::XS\*(C'\fR, \fBpure Perl\fR implementation is supported, so you can use this module on compiler-less environments. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .IP "parse_http_request($request_string, \e%env)" 4 .IX Item "parse_http_request($request_string, %env)" Tries to parse given request string, and if successful, inserts variables into \f(CW%env\fR. For the name of the variables inserted, please refer to the \s-1PSGI\s0 specification. The return values are: .RS 4 .IP ">=0" 8 .IX Item ">=0" length of the request (request line and the request headers), in bytes .IP "\-1" 8 .IX Item "-1" given request is corrupt .IP "\-2" 8 .IX Item "-2" given request is incomplete .RE .RS 4 .Sp Note that the semantics of \s-1PATH_INFO\s0 is somewhat different from Apache. First, HTTP::Parser::XS does not validate the variable; it does not raise an error even if \s-1PATH_INFO\s0 does not start with \*(L"/\*(R". Second, the variable is conformant to \s-1RFC 3875\s0 (and \s-1PSGI\s0 / Plack) in the fact that \*(L"//\*(R" and \*(L"..\*(R" appearing in \s-1PATH_INFO\s0 are preserved whereas Apache transcodes them. .RE .ie n .IP "parse_http_response($response_string, $header_format, \e%special_headers)" 4 .el .IP "parse_http_response($response_string, \f(CW$header_format\fR, \e%special_headers)" 4 .IX Item "parse_http_response($response_string, $header_format, %special_headers)" Tries to parse given response string. \fI\f(CI$header_format\fI\fR must be \&\f(CW\*(C`HEADERS_AS_ARRAYREF\*(C'\fR, \f(CW\*(C`HEADERS_AS_HASHREF\*(C'\fR, or \f(CW\*(C`HEADERS_NONE\*(C'\fR, which are exportable constants. .Sp The optional \fI\f(CI%special_headers\fI\fR is for headers you specifically require. You can set any \s-1HTTP\s0 response header names, which must be lower-cased, and their default values, and then the values are filled in by \&\f(CW\*(C`parse_http_response()\*(C'\fR. For example, if you want the \f(CW\*(C`Cointent\-Length\*(C'\fR field, set its name with default values like \f(CW\*(C`%h = (\*(Aqcontent\-length\*(Aq => undef)\*(C'\fR and pass it as \&\fI\f(CI%special_headers\fI\fR. After parsing, \f(CW$h{\*(Aqcontent\-length\*(Aq}\fR is set if the response has the \f(CW\*(C`Content\-Length\*(C'\fR field, otherwise it's not touched. .Sp The return values are: .RS 4 .ie n .IP "$ret" 8 .el .IP "\f(CW$ret\fR" 8 .IX Item "$ret" The parsering status, which is the same as \f(CW\*(C`parse_http_response()\*(C'\fR. i.e. the length of the response headers in bytes, \f(CW\*(C`\-1\*(C'\fR for incomplete headers, or \f(CW\*(C`\-2\*(C'\fR for errors. .Sp If the given response string is broken or imcomplete, \f(CW\*(C`parse_http_response()\*(C'\fR returns only this value. .ie n .IP "$minor_version" 8 .el .IP "\f(CW$minor_version\fR" 8 .IX Item "$minor_version" The minor version of the given response. i.e. \f(CW1\fR for \s-1HTTP/1.1,\s0 \f(CW0\fR for \s-1HTTP/1.0.\s0 .ie n .IP "$status" 8 .el .IP "\f(CW$status\fR" 8 .IX Item "$status" The \s-1HTTP\s0 status of the given response. e.g. \f(CW200\fR for success. .ie n .IP "$message" 8 .el .IP "\f(CW$message\fR" 8 .IX Item "$message" The \s-1HTTP\s0 status message. e.g. \f(CW\*(C`OK\*(C'\fR for success. .ie n .IP "$headers" 8 .el .IP "\f(CW$headers\fR" 8 .IX Item "$headers" The \s-1HTTP\s0 headers for the given response. It is an \s-1ARRAY\s0 reference if \fI\f(CI$header_format\fI\fR is \f(CW\*(C`HEADERS_AS_ARRAYREF\*(C'\fR, a \s-1HASH\s0 reference on \&\f(CW\*(C`HEADERS_AS_HASHREF\*(C'\fR, an \f(CW\*(C`undef\*(C'\fR on \f(CW\*(C`HEADERS_NONE\*(C'\fR. .Sp The names of the headers are normalized to lower-cased. .RE .RS 4 .RE .SH "LIMITATIONS" .IX Header "LIMITATIONS" Both \f(CW\*(C`parse_http_request()\*(C'\fR and \f(CW\*(C`parse_http_response()\*(C'\fR in \s-1XS\s0 implementation have some size limitations. .SS "The number of headers" .IX Subsection "The number of headers" The number of headers is limited to \f(CW128\fR. If it exceeds, both parsing routines report parsing errors, i.e. return \f(CW\*(C`\-1\*(C'\fR for \f(CW$ret\fR. .SS "The size of header names" .IX Subsection "The size of header names" The size of header names is limited to \f(CW1024\fR, but the parsers do not the same action. .PP \&\f(CW\*(C`parse_http_request()\*(C'\fR returns \f(CW\*(C`\-1\*(C'\fR if too-long header names exist. .PP \&\f(CW\*(C`parse_http_request()\*(C'\fR simply ignores too-long header names. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2009\- Kazuho Oku .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Kazuho Oku .IP "\(bu" 4 gfx .IP "\(bu" 4 mala .IP "\(bu" 4 tokuhirom .SH "THANKS TO" .IX Header "THANKS TO" .IP "\(bu" 4 nothingmuch .IP "\(bu" 4 charsbar .IP "\(bu" 4 \&\s-1DOLMEN\s0 .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 .IP "\(bu" 4 HTTP::Parser .IP "\(bu" 4 HTTP::HeaderParser::XS .IP "\(bu" 4 Plack .IP "\(bu" 4 \&\s-1PSGI\s0 .SH "LICENSE" .IX Header "LICENSE" This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.