Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HTTP::Parser::XS(3)   User Contributed Perl Documentation  HTTP::Parser::XS(3)

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
       o   Kazuho Oku <https://metacpan.org/author/KAZUHO>

       o   gfx <https://metacpan.org/author/GFUJI>

       o   mala	<https://metacpan.org/author/MALA>

       o   tokuhirom <https://metacpan.org/author/TOKUHIROM>

THANKS TO
       o   nothingmuch <https://metacpan.org/author/NUFFIN>

       o   charsbar <https://metacpan.org/author/CHARSBAR>

       o   DOLMEN <https://metacpan.org/author/DOLMEN>

SEE ALSO
       o   <http://github.com/kazuho/picohttpparser>

       o   HTTP::Parser

       o   HTTP::HeaderParser::XS

       o   Plack

       o   PSGI

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

perl v5.24.1			  2014-12-15		   HTTP::Parser::XS(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | LIMITATIONS | COPYRIGHT | AUTHORS | THANKS TO | SEE ALSO | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=HTTP::Parser::XS&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help