HTTP::Parser::XS(3pm)

📦
version 0.17 · 11 versions
, in ubuntu stonking

💖 HTTP::Parser::XS 💖

okay so bestie, welcome to the HTTP::Parser::XS(3pm) page from the User Contributed Perl Documentation 🌸 this is the whole thing, every option, every return value, every author, nothing skipped, no cap. it's a fast, primitive HTTP request parser and lowkey also a response parser and we're gonna get into all of it 💅

✨ NAME ✨

HTTP::Parser::XS — a fast, primitive HTTP request parser 👑

🦋 SYNOPSIS 🦋

okay so here's the vibe, for HTTP servers:

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
    ...
}

and for HTTP clients:

# 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
}
yes bestie, that stray } after if($ret == -1) is literally what the page says. not me fixing it. copying it exactly, typos and all 🙈

🌈 DESCRIPTION 🌈

so what is this? HTTP::Parser::XS is a fast, primitive HTTP request/response parser. that's the whole premise, it's giving speed, it's giving minimal, it's giving icon ✨

  • 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 💖

and here's the part people always get wrong, so listen up: even though this distribution name ends in ::XS, a pure Perl implementation is supported, so you can use this module on compiler-less environments 🫶 like, no C compiler? no problem, she still shows up. periodt.

💅 FUNCTIONS 💅

parse_http_request($request_string, \%env)

tries to parse given request string, and if it's a slay, inserts variables into %env. for the name of the variables inserted, please refer to the PSGI specification (iykyk). 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. the way that it just... keeps them. iconic behaviour.

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. know them, love them, don't get surprised by them 💀

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.
bestie, that's literally what the page says — parse_http_request() twice. i am not the one who wrote it, i'm just the messenger 🫶

Copyright 2009- Kazuho Oku

🌸 AUTHORS 🌸

🎀 THANKS TO 🎀

🔥 SEE ALSO 🔥

💜 LICENSE 💜

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

and that's the whole entire page, bestie, we ate and left no crumbs 🍓 this was HTTP::Parser::XS from perl v5.42.3, dated 2026-08-19, manual section HTTP::Parser::XS(3pm) — mwah, go parse something 💋✨

📦 where this page comes from