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 => ['filename.pdf' => $pdf_content, 'application/pdf']],
});
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
There is no perl API for form files streaming, i.e. uploading large files. With the existing API all form files have to be available upfront, i.e. be in memory. As the file streaming capabilities require I/O, they should be available in the Protocol::HTTP derivatives, e.g. in UniEvent::HTTP.
FUNCTIONS
method_str($method)
Returns corresponding string for a constant METHOD_*, i.e. "GET", "POST" etc.