Reference

Mojo::Client(3pm)

Async IO HTTP 1.1 And WebSocket Client

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

SEE ALSO

Mojolicious, Mojolicious::Guides, <http://mojolicious.org>.