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://mojolicious.org/Mojolicious-latest.tar.gz';
print $client->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('mojolicious.org')->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";
}

# Parallel requests
my $callback = sub { print shift->res->body };
$client->get('http://mojolicious.org' => $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 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::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: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.

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

`tx`

$client->tx;

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

`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},
    {Expect => 'fun'}
);
my $tx = $client->build_form_tx(
    'http://kraih.com/foo',
    'UTF-8',
    {test => 123},
    {Expect => 'fun'}
);
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 => 'mojolicious.org');
my $tx = $client->build_tx(POST => '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 Mojo::Transaction::HTTP builder.

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

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

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

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;

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

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.

	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

app

cookie_jar

http_proxy

https_proxy

ioloop

keep_alive_timeout

log

max_connections

max_redirects

tx

websocket_timeout

METHODS

new

async

build_form_tx

build_tx

build_websocket_tx

clone

delete

detect_proxy

finish

get

head

on_finish

on_message

post

post_form

put

queue

req

res

singleton

send_message

start

test_server

websocket

SEE ALSO

Module Install Instructions

`app`

`cookie_jar`

`http_proxy`

`https_proxy`

`ioloop`

`keep_alive_timeout`

`log`

`max_connections`

`max_redirects`

`tx`

`websocket_timeout`

`new`

`async`

`build_form_tx`

`build_tx`

`build_websocket_tx`

`clone`

`delete`

`detect_proxy`

`finish`

`get`

`head`

`on_finish`

`on_message`

`post`

`post_form`

`put`

`queue`

`req`

`res`

`singleton`

`send_message`

`start`

`test_server`

`websocket`