---
name: "HTTP::Parser::XS"
section: "3pm"
platform: "linux"
package: "libhttp-parser-xs-perl"
version: "0.17-2+b5"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/HTTP::Parser::XS"
---

# HTTP::Parser::XS(3pm)

a fast, primitive HTTP request parser

## 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

- •

  Kazuho Oku \<https://metacpan.org/author/KAZUHO\>

- •

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

- •

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

- •

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

## THANKS TO

- •

  nothingmuch \<https://metacpan.org/author/NUFFIN\>

- •

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

- •

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

## SEE ALSO

- •

  \<http://github.com/kazuho/picohttpparser\>

- •

  HTTP::Parser

- •

  HTTP::HeaderParser::XS

- •

  Plack

- •

  PSGI

## LICENSE

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