NAME¶
Mojo::UserAgent - Non-blocking I/O HTTP and WebSocket user agent
SYNOPSIS¶
use Mojo::UserAgent;
# Say hello to the Unicode snowman with "Do Not Track" header
my $ua = Mojo::UserAgent->new;
say $ua->get('www.X.net?hello=there' => {DNT => 1})->res->body;
# Form POST with exception handling
my $tx = $ua->post('https://metacpan.org/search' => form => {q => 'mojo'});
if (my $res = $tx->success) { say $res->body }
else {
my $err = $tx->error;
die "$err->{code} response: $err->{message}" if $err->{code};
die "Connection error: $err->{message}";
}
# Quick JSON API request with Basic authentication
say $ua->get('https://sri:s3cret@example.com/search.json?q=perl')
->res->json('/results/0/title');
# Extract data from HTML and XML resources
say $ua->get('www.perl.org')->res->dom->html->head->title->text;
# Scrape the latest headlines from a news site with CSS selectors
say $ua->get('blogs.perl.org')->res->dom('h2 > a')->text->shuffle;
# Search DuckDuckGo anonymously through Tor
$ua->proxy->http('socks://127.0.0.1:9050');
say $ua->get('api.3g2upl4pq6kufc4m.onion/?q=mojolicious&format=json')
->res->json('/Abstract');
# IPv6 PUT request with content
my $tx
= $ua->put('[::1]:3000' => {'Content-Type' => 'text/plain'} => 'Hello!');
# Follow redirects to grab the latest Mojolicious release :)
$ua->max_redirects(5)
->get('https://www.github.com/kraih/mojo/tarball/master')
->res->content->asset->move_to('/Users/sri/mojo.tar.gz');
# TLS certificate authentication and JSON POST
my $tx = $ua->cert('tls.crt')->key('tls.key')
->post('https://example.com' => json => {top => 'secret'});
# Non-blocking concurrent requests
Mojo::IOLoop->delay(
sub {
my $delay = shift;
$ua->get('mojolicio.us' => $delay->begin);
$ua->get('cpan.org' => $delay->begin);
},
sub {
my ($delay, $mojo, $cpan) = @_;
say $mojo->res->dom->at('title')->text;
say $cpan->res->dom->at('title')->text;
}
)->wait;
# Non-blocking WebSocket connection sending and receiving JSON messages
$ua->websocket('ws://example.com/echo.json' => sub {
my ($ua, $tx) = @_;
say 'WebSocket handshake failed!' and return unless $tx->is_websocket;
$tx->on(json => sub {
my ($tx, $hash) = @_;
say "WebSocket message via JSON: $hash->{msg}";
$tx->finish;
});
$tx->send({json => {msg => 'Hello World!'}});
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
DESCRIPTION¶
Mojo::UserAgent is a full featured non-blocking I/O HTTP and WebSocket user
agent, with IPv6, TLS, SNI, IDNA, HTTP/SOCKS5 proxy, Comet (long polling),
keep-alive, connection pooling, timeout, cookie, multipart, gzip compression
and multiple event loop support.
All connections will be reset automatically if a new process has been forked,
this allows multiple processes to share the same Mojo::UserAgent object
safely.
For better scalability (epoll, kqueue) and to provide IPv6, SOCKS5 as well as
TLS support, the optional modules EV (4.0+), IO::Socket::IP (0.20+),
IO::Socket::Socks (0.64+) and IO::Socket::SSL (1.84+) will be used
automatically if they are installed. Individual features can also be disabled
with the "MOJO_NO_IPV6", "MOJO_NO_SOCKS" and
"MOJO_NO_TLS" environment variables.
See "USER AGENT" in Mojolicious::Guides::Cookbook for more.
EVENTS¶
Mojo::UserAgent inherits all events from Mojo::EventEmitter and can emit the
following new ones.
start¶
$ua->on(start => sub {
my ($ua, $tx) = @_;
...
});
Emitted whenever a new transaction is about to start, this includes
automatically prepared proxy "CONNECT" requests and followed
redirects.
$ua->on(start => sub {
my ($ua, $tx) = @_;
$tx->req->headers->header('X-Bender' => 'Bite my shiny metal ass!');
});
ATTRIBUTES¶
Mojo::UserAgent implements the following attributes.
my $ca = $ua->ca;
$ua = $ua->ca('/etc/tls/ca.crt');
Path to TLS certificate authority file, defaults to the value of the
"MOJO_CA_FILE" environment variable. Also activates hostname
verification.
# Show certificate authorities for debugging
IO::Socket::SSL::set_defaults(
SSL_verify_callback => sub { say "Authority: $_[2]" and return $_[0] });
cert¶
my $cert = $ua->cert;
$ua = $ua->cert('/etc/tls/client.crt');
Path to TLS certificate file, defaults to the value of the
"MOJO_CERT_FILE" environment variable.
connect_timeout¶
my $timeout = $ua->connect_timeout;
$ua = $ua->connect_timeout(5);
Maximum amount of time in seconds establishing a connection may take before
getting canceled, defaults to the value of the
"MOJO_CONNECT_TIMEOUT" environment variable or 10.
cookie_jar¶
my $cookie_jar = $ua->cookie_jar;
$ua = $ua->cookie_jar(Mojo::UserAgent::CookieJar->new);
Cookie jar to use for requests performed by this user agent, defaults to a
Mojo::UserAgent::CookieJar object.
# Disable extraction of cookies from responses
$ua->cookie_jar->extracting(0);
inactivity_timeout¶
my $timeout = $ua->inactivity_timeout;
$ua = $ua->inactivity_timeout(15);
Maximum amount of time in seconds a connection can be inactive before getting
closed, defaults to the value of the "MOJO_INACTIVITY_TIMEOUT"
environment variable or 20. Setting the value to 0 will allow connections to
be inactive indefinitely.
ioloop¶
my $loop = $ua->ioloop;
$ua = $ua->ioloop(Mojo::IOLoop->new);
Event loop object to use for blocking I/O operations, defaults to a Mojo::IOLoop
object.
key¶
my $key = $ua->key;
$ua = $ua->key('/etc/tls/client.crt');
Path to TLS key file, defaults to the value of the "MOJO_KEY_FILE"
environment variable.
local_address¶
my $address = $ua->local_address;
$ua = $ua->local_address('127.0.0.1');
Local address to bind to.
max_connections¶
my $max = $ua->max_connections;
$ua = $ua->max_connections(5);
Maximum number of keep-alive connections that the user agent will retain before
it starts closing the oldest ones, defaults to 5. Setting the value to 0 will
prevent any connections from being kept alive.
max_redirects¶
my $max = $ua->max_redirects;
$ua = $ua->max_redirects(3);
Maximum number of redirects the user agent will follow before it fails, defaults
to the value of the "MOJO_MAX_REDIRECTS" environment variable or 0.
proxy¶
my $proxy = $ua->proxy;
$ua = $ua->proxy(Mojo::UserAgent::Proxy->new);
Proxy manager, defaults to a Mojo::UserAgent::Proxy object.
# Detect proxy servers from environment
$ua->proxy->detect;
# Manually configure HTTP proxy (using CONNECT for HTTPS)
$ua->proxy->http('http://127.0.0.1:8080')->https('http://127.0.0.1:8080');
# Manually configure Tor (SOCKS5)
$ua->proxy->http('socks://127.0.0.1:9050')->https('socks://127.0.0.1:9050');
request_timeout¶
my $timeout = $ua->request_timeout;
$ua = $ua->request_timeout(5);
Maximum amount of time in seconds establishing a connection, sending the request
and receiving a whole response may take before getting canceled, defaults to
the value of the "MOJO_REQUEST_TIMEOUT" environment variable or 0.
Setting the value to 0 will allow the user agent to wait indefinitely. The
timeout will reset for every followed redirect.
# Total limit of 5 seconds, of which 3 seconds may be spent connecting
$ua->max_redirects(0)->connect_timeout(3)->request_timeout(5);
server¶
my $server = $ua->server;
$ua = $ua->server(Mojo::UserAgent::Server->new);
Application server relative URLs will be processed with, defaults to a
Mojo::UserAgent::Server object.
# Introspect
say for @{$ua->server->app->secrets};
# Change log level
$ua->server->app->log->level('fatal');
# Port currently used for processing relative URLs blocking
say $ua->server->url->port;
# Port currently used for processing relative URLs non-blocking
say $ua->server->nb_url->port;
transactor¶
my $t = $ua->transactor;
$ua = $ua->transactor(Mojo::UserAgent::Transactor->new);
Transaction builder, defaults to a Mojo::UserAgent::Transactor object.
# Change name of user agent
$ua->transactor->name('MyUA 1.0');
METHODS¶
Mojo::UserAgent inherits all methods from Mojo::EventEmitter and implements the
following new ones.
build_tx¶
my $tx = $ua->build_tx(GET => 'example.com');
my $tx = $ua->build_tx(
PUT => 'http://example.com' => {Accept => '*/*'} => 'Hi!');
my $tx = $ua->build_tx(
PUT => 'http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->build_tx(
PUT => 'http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
Generate Mojo::Transaction::HTTP object with "tx" in
Mojo::UserAgent::Transactor.
# Request with custom cookie
my $tx = $ua->build_tx(GET => 'example.com');
$tx->req->cookies({name => 'foo', value => 'bar'});
$tx = $ua->start($tx);
# Deactivate gzip compression
my $tx = $ua->build_tx(GET => 'example.com');
$tx->req->headers->remove('Accept-Encoding');
$tx = $ua->start($tx);
# Interrupt response by raising an error
my $tx = $ua->build_tx(GET => 'example.com');
$tx->res->on(progress => sub {
my $res = shift;
return unless my $server = $res->headers->server;
$res->error({message => 'Oh noes, it is IIS!'}) if $server =~ /IIS/;
});
$tx = $ua->start($tx);
build_websocket_tx¶
my $tx = $ua->build_websocket_tx('ws://example.com');
my $tx = $ua->build_websocket_tx(
'ws://example.com' => {DNT => 1} => ['v1.proto']);
Generate Mojo::Transaction::HTTP object with "websocket" in
Mojo::UserAgent::Transactor.
delete¶
my $tx = $ua->delete('example.com');
my $tx = $ua->delete('http://example.com' => {Accept => '*/*'} => 'Hi!');
my $tx = $ua->delete(
'http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->delete(
'http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
Perform blocking "DELETE" request and return resulting
Mojo::Transaction::HTTP object, takes the same arguments as "tx" in
Mojo::UserAgent::Transactor (except for the "DELETE" method, which
is implied). You can also append a callback to perform requests non-blocking.
$ua->delete('http://example.com' => sub {
my ($ua, $tx) = @_;
say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
get¶
my $tx = $ua->get('example.com');
my $tx = $ua->get('http://example.com' => {Accept => '*/*'} => 'Hi!');
my $tx = $ua->get(
'http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->get(
'http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
Perform blocking "GET" request and return resulting
Mojo::Transaction::HTTP object, takes the same arguments as "tx" in
Mojo::UserAgent::Transactor (except for the "GET" method, which is
implied). You can also append a callback to perform requests non-blocking.
$ua->get('http://example.com' => sub {
my ($ua, $tx) = @_;
say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
head¶
my $tx = $ua->head('example.com');
my $tx = $ua->head('http://example.com' => {Accept => '*/*'} => 'Hi!');
my $tx = $ua->head(
'http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->head(
'http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
Perform blocking "HEAD" request and return resulting
Mojo::Transaction::HTTP object, takes the same arguments as "tx" in
Mojo::UserAgent::Transactor (except for the "HEAD" method, which is
implied). You can also append a callback to perform requests non-blocking.
$ua->head('http://example.com' => sub {
my ($ua, $tx) = @_;
say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
options¶
my $tx = $ua->options('example.com');
my $tx = $ua->options('http://example.com' => {Accept => '*/*'} => 'Hi!');
my $tx = $ua->options(
'http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->options(
'http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
Perform blocking "OPTIONS" request and return resulting
Mojo::Transaction::HTTP object, takes the same arguments as "tx" in
Mojo::UserAgent::Transactor (except for the "OPTIONS" method, which
is implied). You can also append a callback to perform requests non-blocking.
$ua->options('http://example.com' => sub {
my ($ua, $tx) = @_;
say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
patch¶
my $tx = $ua->patch('example.com');
my $tx = $ua->patch('http://example.com' => {Accept => '*/*'} => 'Hi!');
my $tx = $ua->patch(
'http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->patch(
'http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
Perform blocking "PATCH" request and return resulting
Mojo::Transaction::HTTP object, takes the same arguments as "tx" in
Mojo::UserAgent::Transactor (except for the "PATCH" method, which is
implied). You can also append a callback to perform requests non-blocking.
$ua->patch('http://example.com' => sub {
my ($ua, $tx) = @_;
say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
post¶
my $tx = $ua->post('example.com');
my $tx = $ua->post('http://example.com' => {Accept => '*/*'} => 'Hi!');
my $tx = $ua->post(
'http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->post(
'http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
Perform blocking "POST" request and return resulting
Mojo::Transaction::HTTP object, takes the same arguments as "tx" in
Mojo::UserAgent::Transactor (except for the "POST" method, which is
implied). You can also append a callback to perform requests non-blocking.
$ua->post('http://example.com' => sub {
my ($ua, $tx) = @_;
say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
put¶
my $tx = $ua->put('example.com');
my $tx = $ua->put('http://example.com' => {Accept => '*/*'} => 'Hi!');
my $tx = $ua->put(
'http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->put(
'http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
Perform blocking "PUT" request and return resulting
Mojo::Transaction::HTTP object, takes the same arguments as "tx" in
Mojo::UserAgent::Transactor (except for the "PUT" method, which is
implied). You can also append a callback to perform requests non-blocking.
$ua->put('http://example.com' => sub {
my ($ua, $tx) = @_;
say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
start¶
my $tx = $ua->start(Mojo::Transaction::HTTP->new);
Perform blocking request for a custom Mojo::Transaction::HTTP object, which can
be prepared manually or with "build_tx". You can also append a
callback to perform requests non-blocking.
my $tx = $ua->build_tx(GET => 'http://example.com');
$ua->start($tx => sub {
my ($ua, $tx) = @_;
say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
websocket¶
$ua->websocket('ws://example.com' => sub {...});
$ua->websocket(
'ws://example.com' => {DNT => 1} => ['v1.proto'] => sub {...});
Open a non-blocking WebSocket connection with transparent handshake, takes the
same arguments as "websocket" in Mojo::UserAgent::Transactor. The
callback will receive either a Mojo::Transaction::WebSocket or
Mojo::Transaction::HTTP object, depending on if the handshake was successful.
$ua->websocket('ws://example.com/echo' => sub {
my ($ua, $tx) = @_;
say 'WebSocket handshake failed!' and return unless $tx->is_websocket;
$tx->on(finish => sub {
my ($tx, $code, $reason) = @_;
say "WebSocket closed with status $code.";
});
$tx->on(message => sub {
my ($tx, $msg) = @_;
say "WebSocket message: $msg";
$tx->finish;
});
$tx->send('Hi!');
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
You can activate "permessage-deflate" compression by setting the
"Sec-WebSocket-Extensions" header, this can result in much better
performance, but also increases memory usage by up to 300KB per connection.
my $headers = {'Sec-WebSocket-Extensions' => 'permessage-deflate'};
$ua->websocket('ws://example.com/foo' => $headers => sub {...});
DEBUGGING¶
You can set the "MOJO_USERAGENT_DEBUG" environment variable to get
some advanced diagnostics information printed to "STDERR".
MOJO_USERAGENT_DEBUG=1
SEE ALSO¶
Mojolicious, Mojolicious::Guides, <
http://mojolicio.us>.