=head1 NAMEProtocol::HTTP::Request - HTTP request class=head1 SYNOPSISuse Protocol::HTTP::Request;# construction of new requestmy $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-datamy $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'],},});# populate form from URImy $req = Protocol::HTTP::Request->new({uri => '/path?login=user&pass=secret',form => ENCODING_MULTIPART});# populate URI from formmy $req = Protocol::HTTP::Request->new({uri => '/path',form => {enc_type => ENCODING_MULTIPART,fields => [login => 'user', pass => 'secret'],},});=head1 DESCRIPTIONThis class represents client HTTP request, which is specialization ofL<Protocol::HTTP::Message>. An instance of the class can be constructedeither direcly via C<new> method to send a new request (clients), orvia parsing incoming request with L<Protocol::HTTP::RequestParser> (servers).If it is acceptable to have a server reply with compressedpayload, then C<allow_compression> method should be invoked. It will setupC<Accept-Encoding> header in a request.When a new request is ready it can be serialized via C<to_string> method intobyte octets.=head1 METHODSAll methods of L<Protocol::HTTP::Message> also apply.=head2 new([\%params])Constructs new request from hashref of properties, i.e. C<method>, C<uri>,C<allow_compression>, C<headers>, C<body>, C<http_version>, C<chunked>,C<compress>, C<form>.See corresponding methods documentation below and in L<Protocol::HTTP::Message> to find out what these parameters support.C<allow_compression> should be an array ref if multiple values are passed.Parameter C<form> allows to post request data as C<multipart/form-data> (default) or asC<application/x-www-form-urlencoded>.In the simplest form it is just an array of fields and values, i.e.Protocol::HTTP::Request->new({form => [key1 => 'value1', key2 => 'value2'],});A form field value can be also be specified as array; this might be neededfor file posting to specify filename and content type additionally, i.e.Protocol::HTTP::Request->new({fields => [photo => ['sample.jpg' => $jpeg_content, 'image/jpeg']],});It is possible, however, to explicitly specify the type of encoding.=over=item ENCODING_MULTIPART=item ENCODING_URL=backFor example:Protocol::HTTP::Request->new({form => {enc_type => ENCODING_MULTIPART,fields => [key1 => 'value1', key2 => 'value2'],}});When it is encoded as C<multipart/form-data>, the request will usethe right method, e.g. if it is set to C<GET> it will be switched to C<POST>.Sometimes it can be handy to use pseudo-URI to populate form (posted asC<multipart/form-data>) from uri params, or populate URI from form.# GET /path?login=user&pass=secretmy $req = Protocol::HTTP::Request->new({uri => '/path',method => METHOD_GET,form => {enc_type => ENCODING_URL,fields => [login => 'user', pass => 'secret'],},});# POST with multipart/form-data via '/path' URImy $req = Protocol::HTTP::Request->new({uri => '/path?login=user&pass=secret',form => ENCODING_MULTIPART,});To let the URI population work C<form> should be empty, as in the example above.=head2 method_raw([$method])Get/set HTTP request method, e.g. C<GET>, C<POST> etc. in the first line of the requestPossible values:=over=item METHOD_GET=item METHOD_POST=item METHOD_PUT=item METHOD_DELETE=item METHOD_OPTIONS=item METHOD_HEAD=item METHOD_TRACE=item METHOD_CONNECT=item METHOD_UNSPECIFIEDThe special value to distinguish the case, when client developer did not specifythe desired method=back=head2 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=head2 uri([$uri])Set/get uri as L<URI::XS>. C<$uri> argument can be anything that one-argument constructor of L<URI::XS> supports (for example, string).=head2 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 theyhave different API than response cookies.=head2 cookie($name, [$value])Set/get single cookie.=head2 allow_compression($compression1, [$compression2, ...])Sets acceptable compression methods in the responce of the request, i.e.C<Accept-Encoding> header. Order of compression methods might be important.$request->allow_compression(Protocol::HTTP::Compression::gzip);See L<Protocol::HTTP::Compression> for the list of available compressions.=head2 allowed_compression()Returns the bit mask of desirable compression methods (i.e. specified atC<Accept-Encoding> header).if ($request->allowed_compression & Protocol::HTTP::Compression::gzip) {...;}See L<Protocol::HTTP::Compression> for the list of available compressions.=head2 to_string()Serializes a request into string for sending via network. If the compressionwas requested (see L<Protocol::HTTP::Message>), then it will be applied here.=head2 method_str()Returns stringified HTTP request method, e.g. C<"GET">, C<"POST"> etc.=head1 FUNCTIONS=head2 method_str($method)Returns corresponding string for a constant C<METHOD_*>, i.e. C<"GET">, C<"POST"> etc.=head1 SEE ALSOL<Protocol::HTTP>L<Protocol::HTTP::Message>L<Protocol::HTTP::Compression>L<Protocol::HTTP::CookieJar>L<URI::XS>=cut