---
name: "Mojo::Client"
section: "3pm"
platform: "linux"
package: "libmojolicious-perl"
version: "0.999926-1+squeeze2"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/Mojo::Client"
---

# 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: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\_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\>.