NAME

Protocol::HTTP - very fast HTTP protocol incremental parser and serializer

SYNOPSIS

            

              
              
use Protocol::HTTP;
# client api - make request
my $request = Protocol::HTTP::Request->new({
    uri     => "http://crazypanda.ru/hello/world",
    headers => {MyHeader => "my value"},
    cookies => {coo1 => "val1", coo2 => "val2"},
    body    => "my body",
});
my $req_str = $request->to_string; # => like qr|GET /hello/world HTTP/1.1|
# server api - parse request
my ($state, $position, $error);
my $req_parser = Protocol::HTTP::RequestParser->new;
($request, $state, $position, $error) = $req_parser->parse($req_str);
if ($state == Protocol::HTTP::Message::STATE_DONE) {
    say $request->uri;
    say $request->method;
    say $request->body;
}
# server api - make response
my $response = Protocol::HTTP::Response->new({
    code    => 200,
    headers => {Lang => 'Perl'},
    body    => "Lorem ipsum dolor",
});
my $res_str = $response->to_string($request);
# client api - parse response
my $res_parser = Protocol::HTTP::ResponseParser->new;
$res_parser->set_context_request($request);
($response, $state, $position, $error) = $res_parser->parse($res_str);
say $response->code;
say $response->status;
say $response->body;
# compression with chunks
use Protocol::HTTP::Request 'METHOD_POST';
$request = Protocol::HTTP::Request->new({
    method   => METHOD_POST,
    uri      => "https://images.example.com/upload",
    chunked  => 1,
    compress => Protocol::HTTP::Compression::gzip,
});
say $request->to_string;                    # only http headers
say $request->make_chunk('hello-world');    # outputs first chunk
say $request->final_chunk();                # outputs final chunk
# cookies jar (for user-agents aka HTTP-clients)
my $jar = Protocol::HTTP::CookieJar->new;
$jar->populate($request);   # before request sent
$jar->collect($response);   # after response is received
            
          

DESCRIPTION

The Protocol::HTTP is a port of panda::protocol::http library, an RFC-compiant very fast HTTP protocol implementation, written in C++ with XS-adapters in perl. The module has dual Perl/C++ interface (see XS::Manifesto) so futher XS-bindings can be written on the top of Protocol::HTTP.

The following features are supported in the Protocol::HTTP: cookies, transparent (un)compression with Gzip or Brotli, transparent chunked transfer encoding for body streaming, respecting request's preferences when making response.

The module is a protocol implementation, by itself it does not perform any I/O activity.

Currenly supported HTTP versions are 1.0 and 1.1

REFERENCE

Protocol::HTTP::Request

Protocol::HTTP::Response

Protocol::HTTP::Message

Protocol::HTTP::RequestParser

Protocol::HTTP::ResponseParser

Protocol::HTTP::Compression

Protocol::HTTP::Error

Protocol::HTTP::CookieJar

CONSTANTS

error_category

The error category that all of Protocol::HTTP::Error errors have.

PERFORMANCE

Tests were performed on Xeon v3 2.9Ghz, Debian 10.

We can't make a fair benchmark because Protocol::HTTP is a complete HTTP protocol solution, while HTTP::Parser::XS only parses http header.

Nevertheless, <Protocol::HTTP> still runs significantly faster.

Benchmark script can be found in misc/bench.pl

            

              
              
==================== request with few headers
                      Rate     HTTP::Parser HTTP::Parser::XS   Protocol::HTTP
HTTP::Parser       19548/s               --             -97%             -99%
HTTP::Parser::XS  601510/s            2977%               --             -57%
Protocol::HTTP   1390157/s            7011%             131%               --
==================== request with many headers
                     Rate     HTTP::Parser HTTP::Parser::XS   Protocol::HTTP
HTTP::Parser       7657/s               --             -97%             -98%
HTTP::Parser::XS 240040/s            3035%               --             -53%
Protocol::HTTP   508970/s            6547%             112%               --
==================== response with many headers
                     Rate     HTTP::Parser HTTP::Parser::XS   Protocol::HTTP
HTTP::Parser       8295/s               --             -97%             -98%
HTTP::Parser::XS 289616/s            3391%               --             -45%
Protocol::HTTP   529329/s            6281%              83%               --
==================== response with many headers and 10KB body (only for Protocol::HTTP)
timethis for 1:  1 wallclock secs ( 1.08 usr +  0.00 sys =  1.08 CPU) @ 424769.44/s (n=458751)
            
          

SEE ALSO

Protocol::HTTP::Compression::Brotli

URI::XS

Protocol::WebSocket::Fast

rfc2616 (http 1.1)

rfc6265 (HTTP State Management Mechanism)

rfc7932 (brotli compression)

rfc1952 (gzip compression)

Same-Site Cookies draft

AUTHOR

Pronin Oleg <syber@cpan.org>

Ivan Baidakou <dmol@cpan.org>

Grigory Smorkalov <g.smorkalov@crazypanda.ru>

Andrew Selivanov <andrew.selivanov@gmail.com>

Crazy Panda LTD

LICENSE

You may distribute this code under the same terms as Perl itself.

cpanm Protocol::HTTP

perl -MCPAN -e shell
install Protocol::HTTP