SYNOPSIS

use Mojo::Client;
my $client = Mojo::Client->new;
# Grab the latest Mojolicious release :)
my $latest = 'http://mojolicious.org/Mojolicious-latest.tar.gz';
print $client->get($latest)->success->body;
# Quick JSON request
my $trends = 'http://search.twitter.com/trends.json';
print $client->get($trends)->success->json->{trends}->[0]->{name};
# Extract data from HTML and XML resources
my $home = 'http://mojolicious.org';
print $client->get($home)->success->dom->at('title')->text;
# 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";
}
# Parallel requests
my $callback = sub { print shift->res->body };
$client->get('http://mojolicious.org' => $callback);
$client->get('http://search.cpan.org' => $callback);
$client->process;
# Async request
$client->async->get(
'http://kraih.com' => sub {
my $client = shift;
print $client->res->code;
}
)->process;
# Websocket request
$client->websocket(
'ws://websockets.org:8787' => sub {
my $client = shift;
$client->receive_message(
sub {
my ($client, $message) = @_;
print "$message\n";
$client->finish;
}
);
$client->send_message('hi there!');
}
)->process;

DESCRIPTION

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

Optional modules IO::KQueue, IO::Epoll, IO::Socket::INET6 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.

cookie_jar

    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:[email protected]:8080');

Proxy server to use for HTTP and WebSocket requests.

https_proxy

    my $proxy = $client->https_proxy;
    $client   = $client->https_proxy('http://sri:[email protected]: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.

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_keep_alive_connections

    my $max_keep_alive_connections = $client->max_keep_alive_connections;
    $client                        = $client->max_keep_alive_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.

tls_ca_file

    my $tls_ca_file = $client->tls_ca_file;
    $client         = $client->tls_ca_file('/etc/tls/cacerts.pem');

TLS certificate authority file to use, defaults to the "MOJO_CA_FILE" environment variable. Note that IO::Socket::SSL must be installed for HTTPS support.

tls_verify_cb

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

Callback to verify your TLS connection, by default the client will accept most certificates. Note that IO::Socket::SSL must be installed for HTTPS support.

tx

    $client->tx;

The last finished transaction, only available from callbacks.

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 and cookies with other clients

async

    my $async = $client->async;

Clone client instance and start using the global shared Mojo::IOLoop singleton.

    $client->async->get('http://mojolicious.org' => sub {
        my $client = shift;
        print $client->res->body;
    })->process;

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},
        {Expect => '100-continue'}
    );
    my $tx = $client->build_form_tx(
        'http://kraih.com/foo',
        'UTF-8',
        {test => 123},
        {Expect => '100-continue'}
    );
    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 transaction builder for forms.

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

build_tx

    my $tx = $client->build_tx(GET => 'http://mojolicious.org');
    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 transaction builder.

    my $tx = $client->build_tx(GET => 'http://mojolicious.org');
    $tx->res->body(sub { print $_[1] });
    $client->process($tx);

clone

    my $clone = $client->clone;

Clone client instance.

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 {...}
    );

Send a HTTP "DELETE" request.

finish

    $client->finish;

Finish the WebSocket connection, only available from callbacks.

finished

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

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

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

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 {...}
    );

Send a HTTP "GET" request.

head

    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 {...}
    );

Send a HTTP "HEAD" request.

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 {...}
    );

Send a HTTP "POST" request.

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},
        {Expect => '100-continue'}
    );
    my $tx  = $client->post_form(
        'http://kraih.com/foo',
        'UTF-8',
        {test => 123},
        {Expect => '100-continue'}
    );
    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},
        {Expect => '100-continue'},
        sub {...}
    );
    $client = $client->post_form(
        'http://kraih.com/foo',
        'UTF-8',
        {test => 123},
        {Expect => '100-continue'},
        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 {...}
    );

Send a HTTP "POST" request with form data.

process

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

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

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 {...}
    );

Send a HTTP "PUT" request.

queue

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

Queue a list of transactions for processing. HTTP 1.1 transactions can also be pipelined by wrapping them in an arrayref. Note that following redirects and WebSocket upgrades don't work for pipelined transactions.

    $client->queue([$tx, $tx2] => sub {
        my ($client, $p) = @_;
    });

receive_message

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

Receive messages via WebSocket, only available from callbacks.

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

req

    my $req = $client->req;

The request object of the last finished transaction, only available from callbacks.

res

    my $res = $client->res;

The response object of the last finished transaction, only available from callbacks.

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->send_message('Hi there!');

Send a message via WebSocket, only available from callbacks.

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.

websocket_challenge

    my $solution = $client->websocket_challenge($key1, $key2, $key3);

Calculate the solution for a websocket challenge.