view release on metacpan or  search on metacpan

lib/Net/Async/HTTP.pm  view on Meta::CPAN

   use Future::AsyncAwait;

   use IO::Async::Loop;
   use Net::Async::HTTP;
   use URI;

   my $loop = IO::Async::Loop->new();

   my $http = Net::Async::HTTP->new();

   $loop->add( $http );

   my $response = await $http->do_request(
      uri => URI->new( "http://www.cpan.org/" ),
   );

   print "Front page of http://www.cpan.org/ is:\n";
   print $response->as_string;

=head1 DESCRIPTION

This object class implements an asynchronous HTTP user agent. It sends
requests to servers, returning L<Future> instances to yield responses when
they are received. The object supports multiple concurrent connections to
servers, and allows multiple requests in the pipeline to any one connection.
Normally, only one such object will be needed per program to support any
number of requests.

As well as using futures the module also supports a callback-based interface.

This module optionally supports SSL connections, if L<IO::Async::SSL> is
installed. If so, SSL can be requested either by passing a URI with the
C<https> scheme, or by passing a true value as the C<SSL> parameter.

=head2 Connection Pooling

There are three ways in which connections to HTTP server hosts are managed by
this object, controlled by the value of C<max_connections_per_host>. This
controls when new connections are established to servers, as compared to
waiting for existing connections to be free, as new requests are made to them.

They are:

=over 2

=item max_connections_per_host = 1

This is the default setting. In this mode, there will be one connection per
host on which there are active or pending requests. If new requests are made
while an existing one is outstanding, they will be queued to wait for it.

If pipelining is active on the connection (because both the C<pipeline> option
is true and the connection is known to be an HTTP/1.1 server), then requests
will be pipelined into the connection awaiting their response. If not, they
will be queued awaiting a response to the previous before sending the next.

=item max_connections_per_host > 1

In this mode, there can be more than one connection per host. If a new request
is made, it will try to re-use idle connections if there are any, or if they
are all busy it will create a new connection to the host, up to the configured
limit.

=item max_connections_per_host = 0

In this mode, there is no upper limit to the number of connections per host.
Every new request will try to reuse an idle connection, or else create a new
one if all the existing ones are busy.

=back

These modes all apply per hostname / server port pair; they do not affect the
behaviour of connections made to differing hostnames, or differing ports on
the same hostname.

=cut

$metrics->make_gauge( requests_in_flight =>
   description => "Count of the number of requests sent that have not yet been completed",
   # no labels
);
$metrics->make_counter( requests  =>
   description => "Number of HTTP requests sent",
   labels      => [qw( method )],
);
$metrics->make_counter( responses =>
   description => "Number of HTTP responses received",
   labels      => [qw( method code )],
);
$metrics->make_timer( request_duration =>
   description => "Duration of time spent waiting for responses",
   # no labels
);
$metrics->make_distribution( response_bytes =>
   name        => [qw( response bytes )],
   description => "The size in bytes of responses received",
   units       => "bytes",
   # no labels
);

sub _init
{
   my $self = shift;

   $self->{connections} = {}; # { "$host:$port" } -> [ @connections ]

   $self->{read_len}  = READ_LEN;
   $self->{write_len} = WRITE_LEN;

   $self->{max_connections_per_host} = $DEFAULT_MAX_CONNS_PER_HOST;

   $self->{ssl_params} = {};
}

sub _remove_from_loop
{
   my $self = shift;

   foreach my $conn ( map { @$_ } values %{ $self->{connections} } ) {
      $conn->close;
   }

   $self->SUPER::_remove_from_loop( @_ );
}

=head1 PARAMETERS

The following named parameters may be passed to C<new> or C<configure>: