NAME
MojoX::UserAgent - An asynchronous user-agent for the Mojo Web Framework.
SYNOPSIS
use MojoX::UserAgent;
my $ua = MojoX::UserAgent->new;
# Simple
$ua->default_done_cb(
sub {
my ($ua, $tx) = @_;
$tx->has_error
? print $tx->error
: print $tx->res;
}
);
$ua->get('http://www.google.com/');
$ua->run_all;
# More Complicated
my $tx = MojoX::UserAgent::Transaction->new(
{ url => 'http://www.some.host.com/bla/',
method => 'POST',
ua => $ua,
id => '123456',
headers => {
'Expect' => '100-continue',
'Content-Type' => 'text/plain'
},
body => 'Hello!',
callback => sub {
my ($ua, $tx) = @_;
ok(!$tx->has_error, 'Completed');
is($tx->id, '123456', 'Request ID');
is($tx->res->code, 200, 'Status 200');
}
}
};
$ua->spool($tx);
while (1) {
$ua->crank_all;
# do other stuff
# ...
last if $ua->is_idle;
}DESCRIPTION
MojoX::UserAgent is an asynchronous user-agent built upon the Mojo Web Framework. It supports basic session cookies, follows redirections automatically and implements opportunistic HTTP request pipelining.
ATTRIBUTES
MojoX::UserAgent implements the following attributes.
allow_post_redirect
Defaults to 1. Controls whether to allow a POST to be redirected to a GET for another resource on a 301 or 302 response. Default value immitates common browser behavior (and goes against the current HTTP/1.1 specification).
agent
Defaults to 'Mozilla/5.0 (compatible; MojoX::UserAgent/$VERSION)'. The User-Agent string that is used with every request that is made.
app
Defaults to undef. If set, MojoX::UserAgent will send transactions to your application via Mojo's builtin facility for doing so. This doesn't require any network connectivity, and the application doesn't need to be started separately. Great for testing.
cookie_jar
The place where session cookies are stored. See MojoX::UserAgent::CookieJar.
default_done_cb
Defaults to a not particularly useful sub. This is the sub that is used as a callback for every transaction for which a different callback is not provided. Set it. When invoked, this sub is passed two arguments: the UserAgent object that performed the transaction and the transaction itself.
default_headers
Defaults to undef. When set to a hash reference, the given key/value pairs will be added as header names and values to every outgoing request, unless a different value for a given header is already set in a given MojoX::UserAgent::Transaction object. Example:
$ua->default_headers({ 'Accept-Language' => 'en-us,en;q=0.5'});follow_redirects
Defaults to 1. Whether or not to follow HTTP redirects.
pipeline_method
Defaults to 'none'. Other possible values are 'horizontal' and 'vertical'.
redirect_limit
Defaults to 10. Number of redirections to allow for any transaction.
validate_cookie_paths
Defaults to 0. When activated, cookie paths must be a prefix of the current request URL.
METHODS
MojoX::UserAgent inherits all methods from Mojo::Base and implements the following new ones.
new
my $ua = MojoX::UserAgent->new;cookies_for_url
my $cookies = $ua->cookies_for_url('http://www.foo.bar.com/baz/');Get currently active cookies for a given URL. This is a callback used by MojoX::UserAgent::Transaction in order to add cookies to a request that is about to be sent. Pass in either a URL string or a Mojo::URL object. Returns a reference to an array of Mojo::Cookie::Request objects.
crank_all
my $active = $ua->crank_all;Perform a single IO operation on all currently active connections. Returns the total number of currently active connections. Note that this number could be zero without the UA being idle, since transactions are added to the queue at the beginning of the cycle. Use is_idle to test whether the UA is done with all currently spooled requests.
crank_dest
Perform a single IO operation on all currently active connections to a given server. Returns the total number of currently active connections. Note that this number could be zero without the UA being idle, since transactions are added to the queue at the beginning of the cycle. It is not currently recommended that you use this method directly - use crank_all instead.
get
my $sub = sub { ... };
$ua->get('http://www.bar.foo.com/baz/', $sub);A helper method to queue a simple GET request. The second argument is facultative. If not provided, the default_done_cb will be used.
is_idle
my $idle = $ua->is_idle;True if and only if the UserAgent currently has no outstanding transactions.
maxconnections
Use as a set-once attribute. Sets the maximum number of concurrent connections to a given server. Any value change will be ignored unless is_idle is true.
maxpipereqs
Use as a set-once attribute. Sets the maximum number of transactions that may be pipelined to a given server over a given connection. Any value change will be ignored unless is_idle is true.
post
my $sub = sub { ... };
$ua->post('http://www.bar.foo.com/baz/', $sub);A helper method to queue a simple POST request. The second argument is facultative. If not provided, the default_done_cb will be used. Note that for more complex requests, you should instantiate a MojoX::UserAgent::Transaction directly and then spool it yourself.
run_all
$ua->run_all;A blocking method that only returns when all spooled transactions (including intervening redirects) are finished.
spool
my $tx = MojoX::UserAgent::Transaction->new(
{ [...]
}
);
$self->spool($tx);Spool one or a series of MojoX::UserAgent::Transaction objects. Please see the MojoX::UserAgent::Transaction POD for information on how to instantiate such objects.
AUTHOR
Pascal Gaudette <acajou@gmail.com> - http://github.com/Acajou
LICENSE
See LICENSE file.