NAME

Mojo::UserAgent - Async IO HTTP 1.1 And WebSocket User Agent

SYNOPSIS

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

  # Grab the latest Mojolicious release :)
  my $latest = 'http://latest.mojolicio.us';
  print $ua->max_redirects(3)->get($latest)->res->body;

  # Quick JSON request
  my $trends = 'https://api.twitter.com/1/trends.json';
  print $ua->get($trends)->res->json->{trends}->[0]->{name};

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

  # Scrape the latest headlines from a news site
  my $news = 'http://digg.com';
  $ua->max_redirects(3);
  $ua->get($news)->res->dom('h3.story-item-title > a[href]')->each(
    my $e = shift;
    print "$e->{href}:\n";
    print $e->text, "\n";
  });

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

  # TLS certificate authentication
  $ua->cert('tls.crt')->key('tls.key')->get('https://mojolicio.us');

  # Websocket request
  $ua->websocket('ws://websockets.org:8787' => sub {
    my $tx = pop;
    $tx->on_finish(sub { Mojo::IOLoop->stop });
    $tx->on_message(sub {
      my ($tx, $message) = @_;
      print "$message\n";
      $tx->finish;
    });
    $tx->send_message('hi there!');
  });
  Mojo::IOLoop->start;

DESCRIPTION

Mojo::UserAgent is a full featured async io HTTP 1.1 and WebSocket user agent with IPv6, TLS, epoll and kqueue support.

Optional modules IO::KQueue, IO::Epoll, IO::Socket::IP and IO::Socket::SSL are supported transparently and used if installed.

ATTRIBUTES

Mojo::UserAgent implements the following attributes.

`cert`

  my $cert = $ua->cert;
  $ua      = $ua->cert('tls.crt');

Path to TLS certificate file, defaults to the value of MOJO_CERT_FILE.

`cookie_jar`

  my $cookie_jar = $ua->cookie_jar;
  $ua            = $ua->cookie_jar(Mojo::CookieJar->new);

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

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

`ioloop`

  my $loop = $ua->ioloop;
  $ua      = $ua->ioloop(Mojo::IOLoop->new);

Loop object to use for blocking io operations, by default a Mojo::IOLoop object will be used.

`keep_alive_timeout`

  my $keep_alive_timeout = $ua->keep_alive_timeout;
  $ua                    = $ua->keep_alive_timeout(15);

Maximum amount of time in seconds a connection can be inactive before being dropped, defaults to 15.

`key`

  my $key = $ua->key;
  $ua     = $ua->key('tls.crt');

Path to TLS key file, defaults to the value of MOJO_KEY_FILE.

`log`

  my $log = $ua->log;
  $ua     = $ua->log(Mojo::Log->new);

A Mojo::Log object used for logging, by default the application log will be used.

`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 MOJO_MAX_REDIRECTS 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. Note that this attribute is EXPERIMENTAL and might change without warning!

`on_start`

  my $cb = $ua->on_start;
  $ua    = $ua->on_start(sub {...});

Callback to be invoked 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!');
  });

`transactor`

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

Transaction builder, by default a Mojo::UserAgent::Transactor object. Note that this attribute is EXPERIMENTAL and might change without warning!

`websocket_timeout`

  my $websocket_timeout = $ua->websocket_timeout;
  $ua                   = $ua->websocket_timeout(300);

Maximum amount of time in seconds a WebSocket connection can be inactive before being dropped, defaults to 300.

METHODS

Mojo::UserAgent inherits all methods from Mojo::Base 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 MOJO_APP.

  print $ua->app->secret;
  $ua->app->log->level('fatal');
  $ua->app->defaults(testing => 'oh yea!');

`build_form_tx`

  my $tx = $ua->build_form_tx('http://kraih.com/foo' => {test => 123});

Alias for the form method in Mojo::UserAgent::Transactor.

`build_tx`

  my $tx = $ua->build_tx(GET => 'mojolicio.us');

Alias for the tx method in Mojo::UserAgent::Transactor.

`build_websocket_tx`

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

Alias for the websocket method in Mojo::UserAgent::Transactor.

`delete`

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

Perform blocking HTTP DELETE request and return resulting Mojo::Transaction::HTTP object. You can also append a callback to perform requests non-blocking.

  $ua->delete('http://kraih.com' => sub {
    print pop->res->body;
    Mojo::IOLoop->stop;
  });
  Mojo::IOLoop->start;

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

`get`

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

Perform blocking HTTP GET request and return resulting Mojo::Transaction::HTTP object. You can also append a callback to perform requests non-blocking.

  $ua->get('http://kraih.com' => sub {
    print pop->res->body;
    Mojo::IOLoop->stop;
  });
  Mojo::IOLoop->start;

`head`

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

Perform blocking HTTP HEAD request and return resulting Mojo::Transaction::HTTP object. You can also append a callback to perform requests non-blocking.

  $ua->head('http://kraih.com' => sub {
    print pop->res->body;
    Mojo::IOLoop->stop;
  });
  Mojo::IOLoop->start;

`need_proxy`

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

Check if request for domain would use a proxy server. Note that this method is EXPERIMENTAL and might change without warning!

`post`

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

Perform blocking HTTP POST request and return resulting Mojo::Transaction::HTTP object. You can also append a callback to perform requests non-blocking.

  $ua->post('http://kraih.com' => sub {
    print pop->res->body;
    Mojo::IOLoop->stop;
  });
  Mojo::IOLoop->start;

`post_form`

  my $tx = $ua->post_form('http://kraih.com/foo' => {test => 123});
  my $tx = $ua->post_form(
    'http://kraih.com/foo'
    'UTF-8',
    {test => 123}
  );
  my $tx  = $ua->post_form(
    'http://kraih.com/foo',
    {test => 123},
    {Accept => '*/*'}
  );
  my $tx  = $ua->post_form(
    'http://kraih.com/foo',
    'UTF-8',
    {test => 123},
    {Accept => '*/*'}
  );
  my $tx = $ua->post_form(
    'http://kraih.com/foo',
    {file => {file => '/foo/bar.txt'}}
  );
  my $tx= $ua->post_form(
    'http://kraih.com/foo',
    {file => {content => 'lalala'}}
  );
  my $tx = $ua->post_form(
    'http://kraih.com/foo',
    {myzip => {file => $asset, filename => 'foo.zip'}}
  );

Perform blocking HTTP POST request with form data and return resulting Mojo::Transaction::HTTP object. You can also append a callback to perform requests non-blocking.

  $ua->post_form('http://kraih.com' => {q => 'test'} => sub {
    print pop->res->body;
    Mojo::IOLoop->stop;
  });
  Mojo::IOLoop->start;

`put`

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

Perform blocking HTTP PUT request and return resulting Mojo::Transaction::HTTP object. You can also append a callback to perform requests non-blocking.

  $ua->put('http://kraih.com' => sub {
    print pop->res->body;
    Mojo::IOLoop->stop;
  });
  Mojo::IOLoop->start;

`start`

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

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

  $ua->start($tx => sub {
    print pop->res->body;
    Mojo::IOLoop->stop;
  });
  Mojo::IOLoop->start;

`test_server`

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

Starts a test server for app if necessary and returns absolute Mojo::URL object for it. Note that this method is EXPERIMENTAL and might change without warning!

`websocket`

  $ua->websocket('ws://localhost:3000' => sub {...});
  $ua->websocket(
    'ws://localhost:3000' => {'User-Agent' => 'Agent 1.0'} => sub {...}
  );

Open a non-blocking WebSocket connection with transparent handshake.

  $ua->websocket('ws://localhost:3000/echo' => sub {
    my $tx = pop;
    $tx->on_finish(sub  { Mojo::IOLoop->stop });
    $tx->on_message(sub {
      my ($tx, $message) = @_;
      print "$message\n";
    });
    $tx->send_message('Hi!');
  });
  Mojo::IOLoop->start;

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

ATTRIBUTES

cert

cookie_jar

http_proxy

https_proxy

ioloop

keep_alive_timeout

key

log

max_connections

max_redirects

name

no_proxy

on_start

transactor

websocket_timeout

METHODS

app

build_form_tx

build_tx

build_websocket_tx

delete

detect_proxy

get

head

need_proxy

post

post_form

put

start

test_server

websocket