NAME
Protocol::HTTP::Request - HTTP request class
SYNOPSIS
use Protocol::HTTP::Request;
# construction of new request
my $req = Protocol::HTTP::Request->new({
method => METHOD_POST,
uri => "http://crazypanda.ru/hello/world",
http_version => 10,
headers => {MyHeader => "my value"},
cookies => {Lorem => 'ipsum'},
});
$req->method(); # => METHOD_POST
$req->uri(); # => isa 'URI::XS'
$req->uri->to_string; # => 'http://crazypanda.ru/hello/world'
$req->uri('/something');
$req->uri->to_string; # => '/something'
# we accept GZIP-compressed replies
$req->allow_compression(Protocol::HTTP::Compression::gzip);
$req->cookie('Location', 'Earth');
$req->cookie('Location'); # => 'Earth'
$req->cookies; # => is_deeply {Location => 'Earth', 'Lorem' => 'ipsum'}
# main serialization method
$req->to_string; # like qr/GET.*HTTP/1.0.*MyHeader.*my body/sm
# we are crazy enough to send compressed request
$req->compress(Protocol::HTTP::Compression::gzip, Protocol::HTTP::Compression::LEVEL_OPTIMAL);
# now $req->to_string would return a little bit different result
# uploading as multipart/form-data
my $req = Protocol::HTTP::Request->new({
form => [field1 => 'value1', field2 => 'value2'],
});
my $req = Protocol::HTTP::Request->new({
form => {
enc_type => ENCODING_MULTIPART,
fields => [field1 => 'value1', field2 => 'value2'],
},
});
# migrate from URI to form
my $req = Protocol::HTTP::Request->new({
uri => '/path?login=user&pass=secret',
form => ENCODING_URL
});DESCRIPTION
This class represents client HTTP request, which is specialization of Protocol::HTTP::Message. An instance of the class can be constructed either direcly via new method to send a new request (clients), or via parsing incoming request with Protocol::HTTP::RequestParser (servers).
If it is acceptable to have a server reply with compressed payload, then allow_compression method should be invoked. It will setup Accept-Encoding header in a request.
When a new request is ready it can be serialized via to_string method into byte octets.
METHODS
new([\%params])
Constructs new request from hashref of properties, i.e. method, uri, allow_compression, headers, body, http_version, chunked, compress, form.
See corresponding methods documentation below and in Protocol::HTTP::Message to find out what these parameters support.
allow_compression should be an array ref if multiple values are passed.
method_raw([$method])
Get/set HTTP request method, e.g. GET, POST etc. in the first line of the request
Possible values:
- METHOD_GET
- METHOD_POST
- METHOD_PUT
- METHOD_DELETE
- METHOD_OPTIONS
- METHOD_HEAD
- METHOD_TRACE
- METHOD_CONNECT
- METHOD_UNSPECIFIED
-
The special value to distinguish the case, when client developer did not specify the desired method
method([$method])
Deduces the used method, i.e. when it is unspecified it will be GET or POST (for multipart/form_data).
The setter-variant works as method_raw setter
uri([$uri])
Set/get uri as URI::XS. $uri argument can be anything that one-argument constructor of URI::XS supports (for example, string).
cookies([\%cookies])
Set/get all cookies at once as a hashref.
$req->cookies({coo1 => "val1", coo2 => "val2", ... });Please note, this is request cookies, i.e. set by client-side, and they have different API than response cookies.
cookie($name, [$value])
Set/get single cookie.
allow_compression($compression1, [$compression2, ...])
Sets acceptable compression methods in the responce of the request, i.e. Accept-Encoding header. Order of compression methods might be important.
$request->allow_compression(Protocol::HTTP::Compression::gzip);See Protocol::HTTP::Compression for the list of available compressions.
allowed_compression()
Returns the bit mask of desirable compression methods (i.e. specified at Accept-Encoding header).
if ($request->allowed_compression & Protocol::HTTP::Compression::gzip) {
...;
}See Protocol::HTTP::Compression for the list of available compressions.
to_string()
Serializes a request into string for sending via network. If the compression was requested (see Protocol::HTTP::Message), then it will be applied here.
method_str()
Returns stringified HTTP request method, e.g. "GET", "POST" etc.
form()
Allows to post data as multipart/form-data (default) or as application/x-www-form-urlencoded.
When it is encoded as multipart/form-data, the request will use the right method, e.g. if it is set to GET it will be switched to POST.
When form is empty, and it is encoded as multipart/form-data, it will move the parameters from the query part of the request URI into tht form. And vise versa, if it is encoded as application/x-www-form-urlencoded, it will add the form fields into the request URI.
Possible values for form encoding:
- ENCODING_MULTIPART
- ENCODING_URL
FUNCTIONS
method_str($method)
Returns corresponding string for a constant METHOD_*, i.e. "GET", "POST" etc.