view release on metacpan or  search on metacpan

lib/UniEvent/HTTP/Request.pod  view on Meta::CPAN

=head2 follow_redirect([$bool])

Get/set C<follow_redirect> flag.

If set to true and the server's response code is one of C<300>, C<301>, C<302>, C<303>, C<307> or C<308>, will transparently
make another request to the destination described in response and use that another response. 

New request will be made to a location specified in C<Location> header in the response.
Headers C<Authorization>, C<Cookie>, C<Referer> in original request get removed for security reasons; so does C<ssl_ctx> if ssl is in use.
If precise control over this process is needed, consider setting C<redirect_callback> (see docs below).

If new response is a redirection again, will repeat this procedure
up to C<redirection_limit> times. If this limit is exceeded, request will finish with error C<UniEvent::HTTP::Error::redirection_limit>. If the limit is set to 0,
then request will finish with error C<UniEvent::HTTP::Error::unexpected_redirect> immediately on first redirection response.

If set to false, then just content of redirection response will be returned.


=head2 redirection_limit([$cnt])

Get/set redirection limit, see C<follow_redirect()>.


=head2 tcp_nodelay([$bool])

Get/set tcp nodelay feature.


=head2 tcp_hints([$hints])

Get/set DNS resolving hints. C<Hints> can be used to disambiguate domain name resolution in certain cases.
C<$hints> should be either a binary string created via C<UniEvent::Resolver::hints()>

    $request->tcp_hints(UniEvent::Resolver::hints(AF_INET, SOCK_STREAM, PF_INET));
    
    Or a hashref with the corresponding info

    $request->tcp_hints({
        family   => AF_INET,
        socktype => SOCK_STREAM,
        protocol => PF_INET,
        flags    => 0,
    });
    
See L<UniEvent::Resolver> for more info.


=head2 ssl_ctx([$ssl_ctx])

Get/set ssl context. By default, ssl context is autocreated when HTTPS location is requested, but for more precise control (validating server's certificate,
authorizing via ssl, etc) ssl context can be created by hand via L<Net::SSLeay> module and passed here.

After creating context via L<Net::SSLeay> and passing to this method, you can release context via C<CTX_free()> function from C<Net::SSLeay> as it is refcounted
and held by request object.

    my $ctx = Net::SSLeay::CTX_new();
    Net::SSLeay::CTX_use_certificate_file($ctx, "cert/ca.pem", Net::SSLeay::FILETYPE_PEM);
    Net::SSLeay::CTX_use_PrivateKey_file($ctx, "cert/ca.key", Net::SSLeay::FILETYPE_PEM);
    Net::SSLeay::CTX_check_private_key($ctx) or die "wtf?";
    
    $request->ssl_ctx($ctx);
    
    Net::SSLeay::CTX_free($ctx);


=head2 proxy([$url])

Get/set socks5 proxy url as string or L<URI::XS> object. Url scheme must be C<socks5>.

    $request->proxy("socks5://proxy.com:1234");
    $request->proxy("socks5://login:pass@proxy.com:1234");


=head2 response_callback($sub)

=head2 response_event()

Callbacks set via these methods will be invoked when response is fully received including all body or if an error occurs.

Callback signature:

    my ($request, $response, $error) = @_;
    
Where C<$request> is the original request object being executed.

C<$response> is a L<UniEvent::HTTP::Response> object containing all http response properties.

C<$error> is an optional L<XS::ErrorCode> object and if it is present then C<$response> may be undefined. If the error occured while receiving response, then
C<$response> will present and contain everything parsed till that moment. C<$error> can be one of listed in L<UniEvent::HTTP::Error>, L<Protocol::HTTP::Error> or
L<UniEvent::SystemError> and it can be nested, see L<XS::ErrorCode>.

See L<UniEvent/"EVENT CALLBACKS"> for differences between C<_callback> and C<_event> versions of methods.


=head2 partial_callback($sub)

=head2 partial_event()

Invoked one or more times, every time data arrives from network.

Callback signature and meaning of params are the same as for C<response_callback>:

    my ($request, $response, $error) = @_;
    
First time it is called when all headers arrived. From call to call response's body will grow until it's done or error occurs.
If $response->is_done() is true or C<$error> is set, then it's the last call.

The actual body part arrived is the difference between current body value and previous body value. If you only need that part, not the whole growing body
(for writing to disk / incremental parsing / saving memory) then just clear the body on each call (because new parts just append to current $response->body value).

    $request->partial_callback(sub {
        my ($req, $res, $error) = @_;
        if ($error) {
            ...
            return;
        }
        
        print $fh $res->body; # or asynchronously
        $res->body("");