Mojo::UserAgent - Non-blocking I/O HTTP and WebSocket user agent
use Mojo::UserAgent; # Say hello to the Unicode snowman with "Do Not Track" header my $ua = Mojo::UserAgent->new; say $ua->get('www.☃.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, $code) = $tx->error; say $code ? "$code response: $err" : "Connection error: $err"; } # 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('perlnews.org')->res->dom('h2 > a')->text->shuffle; # 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('latest.mojolicio.us') ->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'}); # Blocking concurrent requests (does not work inside a running event loop) my $delay = Mojo::IOLoop->delay; for my $url ('mojolicio.us', 'cpan.org') { my $end = $delay->begin(0); $ua->get($url => sub { my ($ua, $tx) = @_; $end->($tx->res->dom->at('title')->text); }); } my @titles = $delay->wait; # Non-blocking concurrent requests (does work inside a running event loop) my $delay = Mojo::IOLoop->delay(sub { my ($delay, @titles) = @_; ... }); for my $url ('mojolicio.us', 'cpan.org') { my $end = $delay->begin(0); $ua->get($url => sub { my ($ua, $tx) = @_; $end->($tx->res->dom->at('title')->text); }); } $delay->wait unless Mojo::IOLoop->is_running; # 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;
Mojo::UserAgent is a full featured non-blocking I/O HTTP and WebSocket user agent, with IPv6, TLS, SNI, IDNA, Comet (long polling), keep-alive, connection pooling, timeout, cookie, multipart, proxy, 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 as well as TLS support, the optional modules EV (4.0+), IO::Socket::IP (0.20+) and IO::Socket::SSL (1.84+) will be used automatically by Mojo::IOLoop if they are installed. Individual features can also be disabled with the MOJO_NO_IPV6 and MOJO_NO_TLS environment variables.
MOJO_NO_IPV6
MOJO_NO_TLS
See "USER AGENT" in Mojolicious::Guides::Cookbook for more.
Mojo::UserAgent inherits all events from Mojo::EventEmitter and can emit the following new ones.
$ua->on(error => sub { my ($ua, $err) = @_; ... });
Emitted if an error occurs that can't be associated with a transaction, fatal if unhandled.
$ua->on(error => sub { my ($ua, $err) = @_; say "This looks bad: $err"; });
$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.
CONNECT
$ua->on(start => sub { my ($ua, $tx) = @_; $tx->req->headers->header('X-Bender' => 'Bite my shiny metal ass!'); });
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.
MOJO_CA_FILE
# Show certificate authorities for debugging IO::Socket::SSL::set_defaults( SSL_verify_callback => sub { say "Authority: $_[2]" and return $_[0] });
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.
MOJO_CERT_FILE
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.
MOJO_CONNECT_TIMEOUT
10
my $cookie_jar = $ua->cookie_jar; $ua = $ua->cookie_jar(Mojo::UserAgent::CookieJar->new);
Cookie jar to use for this user agents requests, defaults to a Mojo::UserAgent::CookieJar object.
# Disable cookie jar $ua->cookie_jar(0);
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.
MOJO_INACTIVITY_TIMEOUT
20
0
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.
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.
MOJO_KEY_FILE
my $address = $ua->local_address; $ua = $ua->local_address('127.0.0.1');
Local address to bind to.
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.
5
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.
MOJO_MAX_REDIRECTS
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;
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.
MOJO_REQUEST_TIMEOUT
# Total limit of 5 seconds, of which 3 seconds may be spent connecting $ua->max_redirects(0)->connect_timeout(3)->request_timeout(5);
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 say $ua->server->url->port;
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');
Mojo::UserAgent inherits all methods from Mojo::EventEmitter and implements the following new ones.
my $tx = $ua->build_tx(GET => 'example.com'); my $tx = $ua->build_tx(PUT => 'http://example.com' => {DNT => 1} => 'Hi!'); my $tx = $ua->build_tx( PUT => 'http://example.com' => {DNT => 1} => form => {a => 'b'}); my $tx = $ua->build_tx( PUT => 'http://example.com' => {DNT => 1} => 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('Oh noes, it is IIS!') if $server =~ /IIS/; }); $tx = $ua->start($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.
my $tx = $ua->delete('example.com'); my $tx = $ua->delete('http://example.com' => {DNT => 1} => 'Hi!'); my $tx = $ua->delete( 'http://example.com' => {DNT => 1} => form => {a => 'b'}); my $tx = $ua->delete( 'http://example.com' => {DNT => 1} => 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 method). You can also append a callback to perform requests non-blocking.
DELETE
$ua->delete('http://example.com' => sub { my ($ua, $tx) = @_; say $tx->res->body; }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
my $tx = $ua->get('example.com'); my $tx = $ua->get('http://example.com' => {DNT => 1} => 'Hi!'); my $tx = $ua->get('http://example.com' => {DNT => 1} => form => {a => 'b'}); my $tx = $ua->get('http://example.com' => {DNT => 1} => 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 method). You can also append a callback to perform requests non-blocking.
GET
$ua->get('http://example.com' => sub { my ($ua, $tx) = @_; say $tx->res->body; }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
my $tx = $ua->head('example.com'); my $tx = $ua->head('http://example.com' => {DNT => 1} => 'Hi!'); my $tx = $ua->head( 'http://example.com' => {DNT => 1} => form => {a => 'b'}); my $tx = $ua->head( 'http://example.com' => {DNT => 1} => 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 method). You can also append a callback to perform requests non-blocking.
HEAD
$ua->head('http://example.com' => sub { my ($ua, $tx) = @_; say $tx->res->body; }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
my $tx = $ua->options('example.com'); my $tx = $ua->options('http://example.com' => {DNT => 1} => 'Hi!'); my $tx = $ua->options( 'http://example.com' => {DNT => 1} => form => {a => 'b'}); my $tx = $ua->options( 'http://example.com' => {DNT => 1} => 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 method). You can also append a callback to perform requests non-blocking.
OPTIONS
$ua->options('http://example.com' => sub { my ($ua, $tx) = @_; say $tx->res->body; }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
my $tx = $ua->patch('example.com'); my $tx = $ua->patch('http://example.com' => {DNT => 1} => 'Hi!'); my $tx = $ua->patch( 'http://example.com' => {DNT => 1} => form => {a => 'b'}); my $tx = $ua->patch( 'http://example.com' => {DNT => 1} => 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 method). You can also append a callback to perform requests non-blocking.
PATCH
$ua->patch('http://example.com' => sub { my ($ua, $tx) = @_; say $tx->res->body; }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
my $tx = $ua->post('example.com'); my $tx = $ua->post('http://example.com' => {DNT => 1} => 'Hi!'); my $tx = $ua->post( 'http://example.com' => {DNT => 1} => form => {a => 'b'}); my $tx = $ua->post( 'http://example.com' => {DNT => 1} => 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 method). You can also append a callback to perform requests non-blocking.
POST
$ua->post('http://example.com' => sub { my ($ua, $tx) = @_; say $tx->res->body; }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
my $tx = $ua->put('example.com'); my $tx = $ua->put('http://example.com' => {DNT => 1} => 'Hi!'); my $tx = $ua->put('http://example.com' => {DNT => 1} => form => {a => 'b'}); my $tx = $ua->put('http://example.com' => {DNT => 1} => 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 method). You can also append a callback to perform requests non-blocking.
PUT
$ua->put('http://example.com' => sub { my ($ua, $tx) = @_; say $tx->res->body; }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
my $tx = $ua->start(Mojo::Transaction::HTTP->new);
Perform blocking request. 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;
$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.
$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.
permessage-deflate
Sec-WebSocket-Extensions
my $headers = {'Sec-WebSocket-Extensions' => 'permessage-deflate'}; $ua->websocket('ws://example.com/foo' => $headers => sub {...});
You can set the MOJO_USERAGENT_DEBUG environment variable to get some advanced diagnostics information printed to STDERR.
MOJO_USERAGENT_DEBUG
STDERR
MOJO_USERAGENT_DEBUG=1
Mojolicious, Mojolicious::Guides, http://mojolicio.us.
To install Mojolicious, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojolicious
CPAN shell
perl -MCPAN -e shell install Mojolicious
For more information on module installation, please visit the detailed CPAN module installation guide.