NAME

Protocol::HTTP::Message - base class for HTTP request and response

SYNOPSIS

    $message->headers(); # as hash ref
    $message->headers($hashref); # set headers
    $message->headers_size();

    $message->header('Host'); # header value
    $message->header('host'); # header names are case-insensitive, same value
    $message->header('not_existing_header');  # undef
    $message->header('Host', 'crazypanda.ru'); # set single header

    $message->body();         # string
    $message->http_version(); # 10 or 11
    $message->http_version(11);

    $message->multiheader('X-Lang', 'C++', 'Perl'); # add multiple values
    my @vals = $message->multiheader('x-lang'); # ("C++", "Perl")

    $message->body(); # body as string
    $message->body('some-payload'); # set body

    $message->compress(Protocol::HTTP::Compression::gzip, Protocol::HTTP::Compression::LEVEL_MAX);
    my $type = $message->compression();
    my ($type, $level) = $message->compression();

    # making chunks example
    $message = Protocol::HTTP::Response->new({
        chunked => 1,
    });
    # response can now be sent via $message->to_string;

    $message->chunked();
    $message->chunked(1);
    my $chunk1 = $message->make_chunk('loper ipsum dolor');
    my $chunk2 = $message->make_chunk('sit amet');
    my $final_chunk = $message->final_chunk();

DESCRIPTION

This class is base class for Protocol::HTTP::Request and Protocol::HTTP::Response designed to share common code between them. It is an abstract class and cannot be constructed directly.

A message with payload can be serialized and send to network two ways: either as a single string or as a split into multiple pieces. When the whole payload is available upfront, it is convenient to sent it as a message body, i.e. the message is serialized as a single string.

Otherwise, when the complete payload is not ready, it can be serialized and send to network later or/and by pieces. This is chunked message transfer. The final (empty) chunk have to be sent to mark message end.

The body and chunked message transfers are mutually exclusive.

METHODS

new([\%params])

params are the common parameters passed to either Protocol::HTTP::Request's new Protocol::HTTP::Response's new.

Valid parameters are: headers, body, chunked, compress, http_version.

See corresponding methods documentation for more info.

body and chunked are mutually exclusive.

compress is either a compression type constant or an array ref of compression type and compression level. See Protocol::HTTP::Compression.

This method can't be called directly.

headers([\%headers])

Get/set hash-ref of message headers. In case of the getter all header names are lower-cased for convenience.

header($name, [$value])

As a getter, returns header's value. If header $name has multiple values, returns the last value.

As a setter, sets new single value for a header. If this header previously had multiple values, then all of them get replaced with a new single value.

If $value is undef, then removes header $name from headers.

$name is case-insensitive.

    $message->header("Header1", "val");
    say $message->header("header1"); # "val"

    $message->header("Header2", "");

    # Header1: val
    # Header2: 

    $message->header("header1", undef);

    # Header2: 

multiheader($name, [$value1, $value2, ...])

As a getter, returns a list of values for header $name.

As a setter, adds a header with the same name for each supplied value. Does not remove any previously defined values for header $name

$name is case-insensitive.

    $message->multiheader('lang', 'C++', 'Perl');
    
    # lang: C++
    # lang: Perl
    
    $message->multiheader('lang', 'PHP');

    # lang: C++
    # lang: Perl
    # lang: PHP
    
    my @vals = $message->multiheader('Lang'); # "C++", "Perl", "PHP"
    my $val  = $message->header('lang'); # "PHP"
    
    $message->header('Lang', "Java");
    my @vals = $message->multiheader('Lang'); # "Java"

headers_size()

Returns the number of headers in the message

body([$string])

Get/set body.

Performance note on the getter: underhood the body might arrive fragmented, and in Perl interface the body must be presented as single string, it is concatenated on the fly in XS from the underlying pieces. In other words, it is ineffective to call the method body multiple times, and it is adviced to cache it.

http_version([$value])

Get/set HTTP protocol version. Possible values are 10 or 11. If you don't set anything then 11 (HTTP 1.1) will be used.

compress($method, [$level])

Marks newly created message for compression with the provided method and level. If level is not specified, it is defaulted to LEVEL_MIN, which is optimal for server-side applications.

Calling this method only makes sense for newly created messages, not for parsed ones.

See Protocol::HTTP::Compression for available constants.

compression()

Returns compression used in the message. In scalar context returns only compression method. In list context, returns compression method and compression level.

See Protocol::HTTP::Compression for available constants.

chunked([$value])

Getter and setter for the chunked marker of a message. On serialization the Transfer-Encoding header will be set to chunked.

make_chunk($string)

Wraps a string into http chunk and returns the result. Compression may occur at this time if configured.

final_chunk([$string])

Finalizes chunked HTTP message, i.e. final (empty) chunk is returned. If optional $string is provided, make_chunk($string) is added before final chunk.

CONSTANTS

The following constants are available when request or response are parsed and reflect the parsing state. The parsing state by itself is not part of the message.

STATE_HEADERS

STATE_BODY

STATE_CHUNK

STATE_CHUNK_BODY

STATE_CHUNK_TRAILER

STATE_DONE

STATE_ERROR

SEE ALSO

Protocol::HTTP

Protocol::HTTP::Request

Protocol::HTTP::Response

Protocol::HTTP::Compression

cpanm Protocol::HTTP

perl -MCPAN -e shell
install Protocol::HTTP