NAME

Mojo::UserAgent - Non-blocking I/O HTTP 1.1 and WebSocket user agent

SYNOPSIS

use Mojo::UserAgent;
my $ua = Mojo::UserAgent->new;

# Say hello to the unicode snowman with "Do Not Track" header
say $ua->get('www.☃.net?hello=there' => {DNT => 1})->res->body;

# Quick JSON API request with Basic authentication
say $ua->get('https://sri:s3cret@search.twitter.com/search.json?q=perl')
  ->res->json('/results/0/text');

# Extract data from HTML and XML resources
say $ua->get('mojolicio.us')->res->dom->html->head->title->text;

# Scrape the latest headlines from a news site
$ua->max_redirects(5)->get('www.reddit.com/r/perl/')
  ->res->dom('p.title > a.title')->each(sub { say $_->text });

# Form POST with exception handling
my $tx = $ua->post_form('search.cpan.org/search' => {q => 'mojo'});
if (my $res = $tx->success) { say $res->body }
else {
  my ($message, $code) = $tx->error;
  say "Error: $message";
}

# PUT request with content
my $tx
  = $ua->put('kraih.com' => {'Content-Type' => 'text/plain'} => 'Hello!');

# 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
my $tx = $ua->cert('tls.crt')->key('tls.key')->get('https://mojolicio.us');

# Blocking parallel requests (does not work inside a running event loop)
my $delay = Mojo::IOLoop->delay;
for my $url ('mojolicio.us', 'cpan.org') {
  $delay->begin;
  $ua->get($url => sub {
    my ($ua, $tx) = @_;
    $delay->end($tx->res->dom->at('title')->text);
  });
}
my @titles = $delay->wait;

# Non-blocking parallel requests (does work inside a running event loop)
my $delay = Mojo::IOLoop->delay(sub {
  my ($delay, @titles) = @_;
  ...
});
for my $url ('mojolicio.us', 'cpan.org') {
  $delay->begin;
  $ua->get($url => sub {
    my ($ua, $tx) = @_;
    $delay->end($tx->res->dom->at('title')->text);
  });
}
$delay->wait unless Mojo::IOLoop->is_running;

# Non-blocking WebSocket connection
$ua->websocket('ws://websockets.org:8787' => sub {
  my ($ua, $tx) = @_;
  $tx->on(finish  => sub { say 'WebSocket closed.' });
  $tx->on(message => sub {
    my ($tx, $message) = @_;
    say "WebSocket message: $message";
    $tx->finish;
  });
  $tx->send('hi there!');
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

DESCRIPTION

Mojo::UserAgent is a full featured non-blocking I/O HTTP 1.1 and WebSocket user agent with IPv6, TLS and libev support.

Optional modules EV, IO::Socket::IP and IO::Socket::SSL are supported transparently and used if installed. Individual features can also be disabled with the MOJO_NO_IPV6 and MOJO_NO_TLS environment variables.

EVENTS

Mojo::UserAgent can emit the following events.

`error`

$ua->on(error => sub {
  my ($ua, $err) = @_;
  ...
});

Emitted if an error happens that can't be associated with a transaction.

$ua->on(error => sub {
  my ($ua, $err) = @_;
  say "This looks bad: $err";
});

`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.

`ca`

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_ctx_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::CookieJar->new);

Cookie jar to use for this user agents requests, defaults to a Mojo::CookieJar object.

# Disable cookie jar
$ua->cookie_jar(0);

`http_proxy`

my $proxy = $ua->http_proxy;
$ua       = $ua->http_proxy('http://sri:secret@127.0.0.1:8080');

Proxy server to use for HTTP and WebSocket requests.

`https_proxy`

my $proxy = $ua->https_proxy;
$ua       = $ua->https_proxy('http://sri:secret@127.0.0.1:8080');

Proxy server to use for HTTPS and WebSocket requests.

`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);

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_connections = $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 cached ones, defaults to 5.

`max_redirects`

my $max_redirects = $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.

`name`

my $name = $ua->name;
$ua      = $ua->name('Mojolicious');

Value for User-Agent request header, defaults to Mojolicious (Perl).

`no_proxy`

my $no_proxy = $ua->no_proxy;
$ua          = $ua->no_proxy(['localhost', 'intranet.mojolicio.us']);

Domains that don't require a proxy server to be used.

`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);

`transactor`

my $t = $ua->transactor;
$ua   = $ua->transactor(Mojo::UserAgent::Transactor->new);

Transaction builder, defaults to a Mojo::UserAgent::Transactor object.

METHODS

Mojo::UserAgent inherits all methods from Mojo::EventEmitter and implements the following new ones.

`app`

my $app = $ua->app;
$ua     = $ua->app('MyApp');
$ua     = $ua->app(MyApp->new);

Application relative URLs will be processed with, defaults to the value of the MOJO_APP environment variable, which is usually a Mojo or Mojolicious object.

# Introspect
say $ua->app->secret;

# Change log level
$ua->app->log->level('fatal');

# Change application behavior
$ua->app->defaults(testing => 'oh yea!');

`app_url`

my $url = $ua->app_url;
my $url = $ua->app_url('http');
my $url = $ua->app_url('https');

Get absolute Mojo::URL object for app and switch protocol if necessary.

# Port currently used for processing relative URLs
say $ua->app_url->port;

`build_form_tx`

my $tx = $ua->build_form_tx('http://kraih.com' => {a => 'b'});
my $tx = $ua->build_form_tx('kraih.com', 'UTF-8', {a => 'b'}, {DNT => 1});

Alias for "form" in Mojo::UserAgent::Transactor.

`build_tx`

my $tx = $ua->build_tx(GET => 'kraih.com');
my $tx = $ua->build_tx(PUT => 'http://kraih.com' => {DNT => 1} => 'Hi!');

Alias for "tx" in Mojo::UserAgent::Transactor.

# Request with cookie
my $tx = $ua->build_tx(GET => 'kraih.com');
$tx->req->cookies({name => 'foo', value => 'bar'});
$ua->start($tx);

`build_websocket_tx`

my $tx = $ua->build_websocket_tx('ws://localhost:3000');
my $tx = $ua->build_websocket_tx('ws://localhost:3000' => {DNT => 1});

Alias for "websocket" in Mojo::UserAgent::Transactor.

`delete`

my $tx = $ua->delete('kraih.com');
my $tx = $ua->delete('http://kraih.com' => {DNT => 1} => 'Hi!');

Perform blocking HTTP DELETE request and return resulting Mojo::Transaction::HTTP object, takes the exact same arguments as "tx" in Mojo::UserAgent::Transactor (except for the method). You can also append a callback to perform requests non-blocking.

$ua->delete('http://kraih.com' => sub {
  my ($ua, $tx) = @_;
  say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

`detect_proxy`

$ua = $ua->detect_proxy;

Check environment variables HTTP_PROXY, http_proxy, HTTPS_PROXY, https_proxy, NO_PROXY and no_proxy for proxy information. Automatic proxy detection can be enabled with the MOJO_PROXY environment variable.

`get`

my $tx = $ua->get('kraih.com');
my $tx = $ua->get('http://kraih.com' => {DNT => 1} => 'Hi!');

Perform blocking HTTP GET request and return resulting Mojo::Transaction::HTTP object, takes the exact same arguments as "tx" in Mojo::UserAgent::Transactor (except for the method). You can also append a callback to perform requests non-blocking.

$ua->get('http://kraih.com' => sub {
  my ($ua, $tx) = @_;
  say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

`head`

my $tx = $ua->head('kraih.com');
my $tx = $ua->head('http://kraih.com' => {DNT => 1} => 'Hi!');

Perform blocking HTTP HEAD request and return resulting Mojo::Transaction::HTTP object, takes the exact same arguments as "tx" in Mojo::UserAgent::Transactor (except for the method). You can also append a callback to perform requests non-blocking.

$ua->head('http://kraih.com' => sub {
  my ($ua, $tx) = @_;
  say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

`need_proxy`

my $success = $ua->need_proxy('intranet.mojolicio.us');

Check if request for domain would use a proxy server.

`options`

my $tx = $ua->options('kraih.com');
my $tx = $ua->options('http://kraih.com' => {DNT => 1} => 'Hi!');

Perform blocking HTTP OPTIONS request and return resulting Mojo::Transaction::HTTP object, takes the exact same arguments as "tx" in Mojo::UserAgent::Transactor (except for the method). You can also append a callback to perform requests non-blocking.

$ua->options('http://kraih.com' => sub {
  my ($ua, $tx) = @_;
  say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

`patch`

my $tx = $ua->patch('kraih.com');
my $tx = $ua->patch('http://kraih.com' => {DNT => 1} => 'Hi!');

Perform blocking HTTP PATCH request and return resulting Mojo::Transaction::HTTP object, takes the exact same arguments as "tx" in Mojo::UserAgent::Transactor (except for the method). You can also append a callback to perform requests non-blocking.

$ua->patch('http://kraih.com' => sub {
  my ($ua, $tx) = @_;
  say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

`post`

my $tx = $ua->post('kraih.com');
my $tx = $ua->post('http://kraih.com' => {DNT => 1} => 'Hi!');

Perform blocking HTTP POST request and return resulting Mojo::Transaction::HTTP object, takes the exact same arguments as "tx" in Mojo::UserAgent::Transactor (except for the method). You can also append a callback to perform requests non-blocking.

$ua->post('http://kraih.com' => sub {
  my ($ua, $tx) = @_;
  say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

`post_form`

my $tx = $ua->post_form('http://kraih.com' => {a => 'b'});
my $tx = $ua->post_form('kraih.com', 'UTF-8', {a => 'b'}, {DNT => 1});

Perform blocking HTTP POST request with form data and return resulting Mojo::Transaction::HTTP object, takes the exact same arguments as "form" in Mojo::UserAgent::Transactor. You can also append a callback to perform requests non-blocking.

$ua->post_form('http://kraih.com' => {q => 'test'} => sub {
  my ($ua, $tx) = @_;
  say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

`put`

my $tx = $ua->put('kraih.com');
my $tx = $ua->put('http://kraih.com' => {DNT => 1} => 'Hi!');

Perform blocking HTTP PUT request and return resulting Mojo::Transaction::HTTP object, takes the exact same arguments as "tx" in Mojo::UserAgent::Transactor (except for the method). You can also append a callback to perform requests non-blocking.

$ua->put('http://kraih.com' => sub {
  my ($ua, $tx) = @_;
  say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

`start`

$ua = $ua->start($tx);

Process blocking transaction. You can also append a callback to perform transactions non-blocking.

$ua->start($tx => sub {
  my ($ua, $tx) = @_;
  say $tx->res->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

`websocket`

$ua->websocket('ws://localhost:3000' => sub {...});
$ua->websocket('ws://localhost:3000' => {DNT => 1} => sub {...});

Open a non-blocking WebSocket connection with transparent handshake, takes the exact same arguments as "websocket" in Mojo::UserAgent::Transactor.

$ua->websocket('ws://localhost:3000/echo' => sub {
  my ($ua, $tx) = @_;
  $tx->on(message => sub {
    my ($tx, $message) = @_;
    say $message;
  });
  $tx->send('Hi!');
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

DEBUGGING

You can set the MOJO_USERAGENT_DEBUG environment variable to get some advanced diagnostics information printed to STDERR.

MOJO_USERAGENT_DEBUG=1

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

EVENTS

error

start

ATTRIBUTES

ca

cert

connect_timeout

cookie_jar

http_proxy

https_proxy

inactivity_timeout

ioloop

key

local_address

max_connections

max_redirects

name

no_proxy

request_timeout

transactor

METHODS

app

app_url

build_form_tx

build_tx

build_websocket_tx

delete

detect_proxy

get

head

need_proxy

options

patch

post

post_form

put

start

websocket

DEBUGGING

SEE ALSO

Module Install Instructions

`error`

`start`

`ca`

`cert`

`connect_timeout`

`cookie_jar`

`http_proxy`

`https_proxy`

`inactivity_timeout`

`ioloop`

`key`

`local_address`

`max_connections`

`max_redirects`

`name`

`no_proxy`

`request_timeout`

`transactor`

`app`

`app_url`

`build_form_tx`

`build_tx`

`build_websocket_tx`

`delete`

`detect_proxy`

`get`

`head`

`need_proxy`

`options`

`patch`

`post`

`post_form`

`put`

`start`

`websocket`