Mojo::Client - Async IO HTTP 1.1 And WebSocket Client
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;
Mojo::Client is a full featured async io HTTP 1.1 and WebSocket client with IPv6, TLS, epoll and kqueue support.
IPv6
TLS
epoll
kqueue
Optional modules IO::KQueue, IO::Epoll, IO::Socket::IP and IO::Socket::SSL are supported transparently and used if installed.
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.
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.
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.
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.
300
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.
singleton
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.
DELETE
$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.
GET
$client->get('http://kraih.com' => sub { print shift->res->body; })->start;
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.
HEAD
$client->head('http://kraih.com' => sub { print shift->res->headers->content_length; })->start;
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.
POST
$client->post('http://kraih.com' => sub { print shift->res->body; })->start;
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;
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.
PUT
$client->put('http://kraih.com' => sub { print shift->res->body; })->start;
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.
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.
Mojolicious, Mojolicious::Guides, http://mojolicious.org.
To install Mojolicious, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojolicious
CPAN shell
perl -MCPAN -e shell install Mojolicious
For more information on module installation, please visit the detailed CPAN module installation guide.