GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  HTTP::PARSER::XS (3)

.ds Aq ’

NAME

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

CONTENTS

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, <B>pure PerlB> 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.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 HTTP::PARSER::XS (3) 2014-12-15

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.