NAME

Mojo::Client - Async IO HTTP 1.1 And WebSocket Client

SYNOPSIS

  use Mojo::Client;
  my $client = Mojo::Client->new;

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

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

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

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

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

  # TLS certificate authentication
  $client->cert('tls.crt')->key('tls.key')->get('https://mojolicio.us');
    
  # Parallel requests
  my $callback = sub { print shift->res->body };
  $client->get('http://mojolicio.us' => $callback);
  $client->get('http://search.cpan.org' => $callback);
  $client->start;

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

DESCRIPTION

Mojo::Client is a full featured async io HTTP 1.1 and WebSocket client with TLS, epoll and kqueue support.

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

ATTRIBUTES

Mojo::Client implements the following attributes.

app

  my $app = $client->app;
  $client = $client->app(MyApp->new);

A Mojo application to associate this client with. If set, local requests will be processed in this application.

cert

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

Path to TLS certificate file. Note that this attribute is EXPERIMENTAL and might change without warning!

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

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

http_proxy

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

Proxy server to use for HTTP and WebSocket requests.

https_proxy

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

Proxy server to use for HTTPS and WebSocket requests.

ioloop

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

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

keep_alive_timeout

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

Timeout in seconds for keep alive between requests, defaults to 15.

key

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

Path to TLS key file. Note that this attribute is EXPERIMENTAL and might change without warning!

log

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

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

max_connections

  my $max_connections = $client->max_connections;
  $client             = $client->max_connections(5);

Maximum number of keep alive connections that the client will retain before it starts closing the oldest cached ones, defaults to 5.

max_redirects

  my $max_redirects = $client->max_redirects;
  $client           = $client->max_redirects(3);

Maximum number of redirects the client will follow before it fails, defaults to 0.

no_proxy

  my $no_proxy = $client->no_proxy;
  $client      = $client->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  = $client->on_start;
  $client = $client->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. Note that this attribute is EXPERIMENTAL and might change without warning!

  $client->on_start(sub {
    my ($client, $tx) = @_;
    $tx->req->headers->header('X-Bender', 'Bite my shiny metal ass!');
  });

tx

  $client->tx;

The last finished transaction, only available from callbacks, usually a Mojo::Transaction::HTTP or Mojo::Transaction::WebSocket object.

user_agent

  my $user_agent = $client->user_agent;
  $client        = $client->user_agent('Mojolicious');

Value for User-Agent request header, defaults to Mojolicious (Perl). Note that this attribute is EXPERIMENTAL and might change without warning!

websocket_timeout

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

Timeout in seconds for WebSockets to be idle, defaults to 300.

METHODS

Mojo::Client inherits all methods from Mojo::Base and implements the following new ones.

new

  my $client = Mojo::Client->new;

Construct a new Mojo::Client object. Use singleton if you want to share keep alive connections with other clients.

async

  my $async = $client->async;

Clone client instance and start using the global shared Mojo::IOLoop singleton if it is running. Note that all cloned clients have their own keep alive connection queue, so you can quickly run out of file descriptors with too many active clients.

build_form_tx

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

Versatile Mojo::Transaction::HTTP builder for forms.

  my $tx = $client->build_form_tx('http://kraih.com/foo' => {test => 123});
  $tx->res->body(sub { print $_[1] });
  $client->start($tx);

build_tx

  my $tx = $client->build_tx(GET => 'mojolicio.us');
  my $tx = $client->build_tx(POST => 'http://mojolicio.us');
  my $tx = $client->build_tx(
    GET => 'http://kraih.com' => {Connection => 'close'}
  );
  my $tx = $client->build_tx(
    POST => 'http://kraih.com' => {Connection => 'close'} => 'Hi!'
  );

Versatile general purpose Mojo::Transaction::HTTP builder.

  # Streaming response
  my $tx = $client->build_tx(GET => 'http://mojolicio.us');
  $tx->res->body(sub { print $_[1] });
  $client->start($tx);

  # Custom socket
  my $tx = $client->build_tx(GET => 'http://mojolicio.us');
  $tx->connection($socket);
  $client->start($tx);

build_websocket_tx

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

Versatile Mojo::Transaction::HTTP builder for WebSocket handshakes. An upgrade to Mojo::Transaction::WebSocket will happen automatically after a successful handshake is performed.

clone

  my $clone = $client->clone;

Clone client the instance. Note that all cloned clients have their own keep alive connection queue, so you can quickly run out of file descriptors with too many active clients.

delete

  my $tx  = $client->delete('http://kraih.com');
  my $tx  = $client->delete('http://kraih.com' => {Connection => 'close'});
  my $tx  = $client->delete(
    'http://kraih.com' => {Connection => 'close'} => 'Hi!'
  );
  $client = $client->delete('http://kraih.com' => sub {...});
  $client = $client->delete(
    'http://kraih.com' => {Connection => 'close'} => sub {...}
  );
  $client = $client->delete(
    'http://kraih.com' => {Connection => 'close'} => 'Hi!' => sub {...}
  );

Prepare HTTP DELETE request.

  $client->delete('http://kraih.com' => sub {
    print shift->res->body;
  })->start;

The request will be performed right away and the resulting Mojo::Transaction::HTTP object returned if no callback is given.

  print $client->delete('http://kraih.com')->res->body;

detect_proxy

  $client = $client->detect_proxy;

Check environment variables HTTP_PROXY, http_proxy, HTTPS_PROXY, https_proxy, NO_PROXY and no_proxy for proxy information.

finish

  $client->finish;

Finish the WebSocket connection, only available from callbacks.

get

  my $tx  = $client->get('http://kraih.com');
  my $tx  = $client->get('http://kraih.com' => {Connection => 'close'});
  my $tx  = $client->get(
    'http://kraih.com' => {Connection => 'close'} => 'Hi!'
  );
  $client = $client->get('http://kraih.com' => sub {...});
  $client = $client->get(
    'http://kraih.com' => {Connection => 'close'} => sub {...}
  );
  $client = $client->get(
    'http://kraih.com' => {Connection => 'close'} => 'Hi!' => sub {...}
  );

Prepare HTTP GET request.

  $client->get('http://kraih.com' => sub {
    print shift->res->body;
  })->start;

The request will be performed right away and the resulting Mojo::Transaction::HTTP object returned if no callback is given.

  print $client->get('http://kraih.com')->res->body;
  my $tx  = $client->head('http://kraih.com');
  my $tx  = $client->head('http://kraih.com' => {Connection => 'close'});
  my $tx  = $client->head(
    'http://kraih.com' => {Connection => 'close'} => 'Hi!'
  );
  $client = $client->head('http://kraih.com' => sub {...});
  $client = $client->head(
    'http://kraih.com' => {Connection => 'close'} => sub {...}
  );
  $client = $client->head(
    'http://kraih.com' => {Connection => 'close'} => 'Hi!' => sub {...}
  );

Prepare HTTP HEAD request.

  $client->head('http://kraih.com' => sub {
    print shift->res->headers->content_length;
  })->start;

The request will be performed right away and the resulting Mojo::Transaction::HTTP object returned if no callback is given.

  print $client->head('http://kraih.com')->res->headers->content_length;

need_proxy

  my $need_proxy = $client->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!

on_finish

  $client->on_finish(sub {...});

Callback signaling that peer finished the WebSocket connection, only available from callbacks.

  $client->on_finish(sub {
    my $client = shift;
  });

on_message

  $client = $client->on_message(sub {...});

Receive messages via WebSocket, only available from callbacks.

  $client->on_message(sub {
    my ($client, $message) = @_;
  });

post

  my $tx  = $client->post('http://kraih.com');
  my $tx  = $client->post('http://kraih.com' => {Connection => 'close'});
  my $tx  = $client->post(
    'http://kraih.com' => {Connection => 'close'} => 'Hi!'
  );
  $client = $client->post('http://kraih.com' => sub {...});
  $client = $client->post(
    'http://kraih.com' => {Connection => 'close'} => sub {...}
  );
  $client = $client->post(
    'http://kraih.com',
    {Connection => 'close'},
    'message body',
    sub {...}
  );
  $client = $client->post(
    'http://kraih.com' => {Connection => 'close'} => 'Hi!' => sub {...}
  );

Prepare HTTP POST request.

  $client->post('http://kraih.com' => sub {
    print shift->res->body;
  })->start;

The request will be performed right away and the resulting Mojo::Transaction::HTTP object returned if no callback is given.

  print $client->post('http://kraih.com')->res->body;

post_form

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

Prepare HTTP POST request with form data.

  $client->post_form('http://kraih.com' => {q => 'test'} => sub {
    print shift->res->body;
  })->start;

The request will be performed right away and the resulting Mojo::Transaction::HTTP object returned if no callback is given.

  print $client->post_form('http://kraih.com' => {q => 'test'})->res->body;

put

  my $tx  = $client->put('http://kraih.com');
  my $tx  = $client->put('http://kraih.com' => {Connection => 'close'});
  my $tx  = $client->put(
    'http://kraih.com' => {Connection => 'close'} => 'Hi!'
  );
  $client = $client->put('http://kraih.com' => sub {...});
  $client = $client->put(
    'http://kraih.com' => {Connection => 'close'} => sub {...}
  );
  $client = $client->put(
    'http://kraih.com' => {Connection => 'close'} => 'Hi!' => sub {...}
  );

Prepare HTTP PUT request.

  $client->put('http://kraih.com' => sub {
    print shift->res->body;
  })->start;

The request will be performed right away and the resulting Mojo::Transaction::HTTP object returned if no callback is given.

  print $client->put('http://kraih.com')->res->body;

queue

  $client = $client->queue(@transactions);
  $client = $client->queue(@transactions => sub {...});

Queue a list of transactions for processing.

req

  my $req = $client->req;

The request object of the last finished transaction, only available from callbacks, usually a Mojo::Message::Request object.

res

  my $res = $client->res;

The response object of the last finished transaction, only available from callbacks, usually a Mojo::Message::Response object.

singleton

  my $client = Mojo::Client->singleton;

The global client object, used to access a single shared client instance from everywhere inside the process.

send_message

  $client = $client->send_message('Hi there!');

Send a message via WebSocket, only available from callbacks.

start

  $client = $client->start;
  $client = $client->start(@transactions);
  $client = $client->start(@transactions => sub {...});

Start processing all queued transactions. Will be blocking unless you have a global shared ioloop and use the async method.

test_server

  my $port = $client->test_server;
  my $port = $client->test_server('https');

Starts a test server for app if neccessary and returns the port number. Note that this method is EXPERIMENTAL and might change without warning!

websocket

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

Open a WebSocket connection with transparent handshake.

SEE ALSO

Mojolicious, Mojolicious::Guides, http://mojolicio.us.