GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  MOJO::USERAGENT (3)

.ds Aq ’

NAME

Mojo::UserAgent - Non-blocking I/O HTTP and WebSocket user agent

CONTENTS

SYNOPSIS



  use Mojo::UserAgent;

  # Say hello to the Unicode snowman and include an Accept header
  my $ua = Mojo::UserAgent->new;
  say $ua->get(www.X.net?hello=there => {Accept => */*})->res->body;

  # Form POST (application/x-www-form-urlencoded) with exception handling
  my $tx = $ua->post(https://metacpan.org/search => form => {q => mojo});
  if (my $res = $tx->success) { say $res->body }
  else {
    my $err = $tx->error;
    die "$err->{code} response: $err->{message}" if $err->{code};
    die "Connection error: $err->{message}";
  }

  # Extract data from HTML and XML resources with CSS selectors
  say $ua->get(www.perl.org)->res->dom->at(title)->text;

  # Scrape the latest headlines from a news site
  say $ua->get(blogs.perl.org)
    ->res->dom->find(h2 > a)->map(text)->join("\n");

  # IPv6 PUT request with Content-Type header and content
  my $tx = $ua->put([::1]:3000 => {Content-Type => text/plain} => Hi!);

  # Quick JSON API request with Basic authentication
  my $value = $ua->get(https://sri:s3cret@example.com/test.json)->res->json;

  # JSON POST (application/json) with TLS certificate authentication
  my $tx = $ua->cert(tls.crt)->key(tls.key)
    ->post(https://example.com => json => {top => secret});

  # Search DuckDuckGo anonymously through Tor
  $ua->proxy->http(socks://127.0.0.1:9050);
  say $ua->get(api.3g2upl4pq6kufc4m.onion/?q=mojolicious&format=json)
    ->res->json(/Abstract);

  # Follow redirects to download Mojolicious from GitHub
  $ua->max_redirects(5)
    ->get(https://www.github.com/kraih/mojo/tarball/master)
    ->res->content->asset->move_to(/home/sri/mojo.tar.gz);

  # Non-blocking request
  $ua->get(mojolicious.org => sub {
    my ($ua, $tx) = @_;
    say $tx->res->dom->at(title)->text;
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

  # Concurrent non-blocking requests (synchronized with a delay)
  Mojo::IOLoop->delay(
    sub {
      my $delay = shift;
      $ua->get(mojolicious.org => $delay->begin);
      $ua->get(cpan.org        => $delay->begin);
    },
    sub {
      my ($delay, $mojo, $cpan) = @_;
      say $mojo->res->dom->at(title)->text;
      say $cpan->res->dom->at(title)->text;
    }
  )->wait;

  # WebSocket connection sending and receiving JSON messages
  $ua->websocket(ws://example.com/echo.json => sub {
    my ($ua, $tx) = @_;
    say WebSocket handshake failed! and return unless $tx->is_websocket;
    $tx->on(json => sub {
      my ($tx, $hash) = @_;
      say "WebSocket message via JSON: $hash->{msg}";
      $tx->finish;
    });
    $tx->send({json => {msg => Hello World!}});
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;



DESCRIPTION

Mojo::UserAgent is a full featured non-blocking I/O HTTP and WebSocket user agent, with IPv6, TLS, SNI, IDNA, HTTP/SOCKS5 proxy, Comet (long polling), keep-alive, connection pooling, timeout, cookie, multipart, gzip compression and multiple event loop support.

All connections will be reset automatically if a new process has been forked, this allows multiple processes to share the same Mojo::UserAgent object safely.

For better scalability (epoll, kqueue) and to provide non-blocking name resolution, SOCKS5 as well as TLS support, the optional modules EV (4.0+), Net::DNS::Native (0.15+), IO::Socket::Socks (0.64+) and IO::Socket::SSL (1.94+) will be used automatically if possible. Individual features can also be disabled with the MOJO_NO_NDN, MOJO_NO_SOCKS and MOJO_NO_TLS environment variables.

See USER AGENT in Mojolicious::Guides::Cookbook for more.

EVENTS

Mojo::UserAgent inherits all events from Mojo::EventEmitter and can emit the following new ones.

    start



  $ua->on(start => sub {
    my ($ua, $tx) = @_;
    ...
  });



Emitted whenever a new transaction is about to start, this includes automatically prepared proxy CONNECT requests and followed redirects.



  $ua->on(start => sub {
    my ($ua, $tx) = @_;
    $tx->req->headers->header(X-Bender => Bite my shiny metal ass!);
  });



ATTRIBUTES

Mojo::UserAgent implements the following attributes.

    ca



  my $ca = $ua->ca;
  $ua    = $ua->ca(/etc/tls/ca.crt);



Path to TLS certificate authority file used to verify the peer certificate, defaults to the value of the MOJO_CA_FILE environment variable. Also activates hostname verification.



  # Show certificate authorities for debugging
  IO::Socket::SSL::set_defaults(
    SSL_verify_callback => sub { say "Authority: $_[2]" and return $_[0] });



    cert



  my $cert = $ua->cert;
  $ua      = $ua->cert(/etc/tls/client.crt);



Path to TLS certificate file, defaults to the value of the MOJO_CERT_FILE environment variable.

    connect_timeout



  my $timeout = $ua->connect_timeout;
  $ua         = $ua->connect_timeout(5);



Maximum amount of time in seconds establishing a connection may take before getting canceled, defaults to the value of the MOJO_CONNECT_TIMEOUT environment variable or 10.

    cookie_jar



  my $cookie_jar = $ua->cookie_jar;
  $ua            = $ua->cookie_jar(Mojo::UserAgent::CookieJar->new);



Cookie jar to use for requests performed by this user agent, defaults to a Mojo::UserAgent::CookieJar object.



  # Ignore all cookies
  $ua->cookie_jar->ignore(sub { 1 });

  # Ignore cookies for public suffixes
  my $ps = IO::Socket::SSL::PublicSuffix->default;
  $ua->cookie_jar->ignore(sub {
    my $cookie = shift;
    return undef unless my $domain = $cookie->domain;
    return ($ps->public_suffix($domain))[0] eq ;
  });

  # Add custom cookie to the jar
  $ua->cookie_jar->add(
    Mojo::Cookie::Response->new(
      name   => foo,
      value  => bar,
      domain => mojolicious.org,
      path   => /perldoc
    )
  );



    inactivity_timeout



  my $timeout = $ua->inactivity_timeout;
  $ua         = $ua->inactivity_timeout(15);



Maximum amount of time in seconds a connection can be inactive before getting closed, defaults to the value of the MOJO_INACTIVITY_TIMEOUT environment variable or 20. Setting the value to 0 will allow connections to be inactive indefinitely.

    ioloop



  my $loop = $ua->ioloop;
  $ua      = $ua->ioloop(Mojo::IOLoop->new);



Event loop object to use for blocking I/O operations, defaults to a Mojo::IOLoop object.

    key



  my $key = $ua->key;
  $ua     = $ua->key(/etc/tls/client.crt);



Path to TLS key file, defaults to the value of the MOJO_KEY_FILE environment variable.

    local_address



  my $address = $ua->local_address;
  $ua         = $ua->local_address(127.0.0.1);



Local address to bind to.

    max_connections



  my $max = $ua->max_connections;
  $ua     = $ua->max_connections(5);



Maximum number of keep-alive connections that the user agent will retain before it starts closing the oldest ones, defaults to 5. Setting the value to 0 will prevent any connections from being kept alive.

    max_redirects



  my $max = $ua->max_redirects;
  $ua     = $ua->max_redirects(3);



Maximum number of redirects the user agent will follow before it fails, defaults to the value of the MOJO_MAX_REDIRECTS environment variable or 0.

    proxy



  my $proxy = $ua->proxy;
  $ua       = $ua->proxy(Mojo::UserAgent::Proxy->new);



Proxy manager, defaults to a Mojo::UserAgent::Proxy object.



  # Detect proxy servers from environment
  $ua->proxy->detect;

  # Manually configure HTTP proxy (using CONNECT for HTTPS)
  $ua->proxy->http(http://127.0.0.1:8080)->https(http://127.0.0.1:8080);

  # Manually configure Tor (SOCKS5)
  $ua->proxy->http(socks://127.0.0.1:9050)->https(socks://127.0.0.1:9050);



    request_timeout



  my $timeout = $ua->request_timeout;
  $ua         = $ua->request_timeout(5);



Maximum amount of time in seconds establishing a connection, sending the request and receiving a whole response may take before getting canceled, defaults to the value of the MOJO_REQUEST_TIMEOUT environment variable or 0. Setting the value to 0 will allow the user agent to wait indefinitely. The timeout will reset for every followed redirect.



  # Total limit of 5 seconds, of which 3 seconds may be spent connecting
  $ua->max_redirects(0)->connect_timeout(3)->request_timeout(5);



    server



  my $server = $ua->server;
  $ua        = $ua->server(Mojo::UserAgent::Server->new);



Application server relative URLs will be processed with, defaults to a Mojo::UserAgent::Server object.



  # Mock web service
  $ua->server->app(Mojolicious->new);
  $ua->server->app->routes->get(/time => sub {
    my $c = shift;
    $c->render(json => {now => time});
  });
  my $time = $ua->get(/time)->res->json->{now};

  # Change log level
  $ua->server->app->log->level(fatal);

  # Port currently used for processing relative URLs blocking
  say $ua->server->url->port;

  # Port currently used for processing relative URLs non-blocking
  say $ua->server->nb_url->port;



    transactor



  my $t = $ua->transactor;
  $ua   = $ua->transactor(Mojo::UserAgent::Transactor->new);



Transaction builder, defaults to a Mojo::UserAgent::Transactor object.



  # Change name of user agent
  $ua->transactor->name(MyUA 1.0);



METHODS

Mojo::UserAgent inherits all methods from Mojo::EventEmitter and implements the following new ones.

    build_tx



  my $tx = $ua->build_tx(GET => example.com);
  my $tx = $ua->build_tx(
    PUT => http://example.com => {Accept => */*} => Hi!);
  my $tx = $ua->build_tx(
    PUT => http://example.com => {Accept => */*} => form => {a => b});
  my $tx = $ua->build_tx(
    PUT => http://example.com => {Accept => */*} => json => {a => b});



Generate Mojo::Transaction::HTTP object with tx in Mojo::UserAgent::Transactor.



  # Request with custom cookie
  my $tx = $ua->build_tx(GET => https://example.com/account);
  $tx->req->cookies({name => user, value => sri});
  $tx = $ua->start($tx);

  # Deactivate gzip compression
  my $tx = $ua->build_tx(GET => example.com);
  $tx->req->headers->remove(Accept-Encoding);
  $tx = $ua->start($tx);

  # Interrupt response by raising an error
  my $tx = $ua->build_tx(GET => http://example.com);
  $tx->res->on(progress => sub {
    my $res = shift;
    return unless my $server = $res->headers->server;
    $res->error({message => Oh noes, it is IIS!}) if $server =~ /IIS/;
  });
  $tx = $ua->start($tx);



    build_websocket_tx



  my $tx = $ua->build_websocket_tx(ws://example.com);
  my $tx = $ua->build_websocket_tx(
    ws://example.com => {DNT => 1} => [v1.proto]);



Generate Mojo::Transaction::HTTP object with websocket in Mojo::UserAgent::Transactor.



  # Custom WebSocket handshake with cookie
  my $tx = $ua->build_websocket_tx(wss://example.com/echo);
  $tx->req->cookies({name => user, value => sri});
  $ua->start($tx => sub {
    my ($ua, $tx) = @_;
    say WebSocket handshake failed! and return unless $tx->is_websocket;
    $tx->on(message => sub {
      my ($tx, $msg) = @_;
      say "WebSocket message: $msg";
      $tx->finish;
    });
    $tx->send(Hi!);
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;



    delete



  my $tx = $ua->delete(example.com);
  my $tx = $ua->delete(http://example.com => {Accept => */*} => Hi!);
  my $tx = $ua->delete(
    http://example.com => {Accept => */*} => form => {a => b});
  my $tx = $ua->delete(
    http://example.com => {Accept => */*} => json => {a => b});



Perform blocking DELETE request and return resulting Mojo::Transaction::HTTP object, takes the same arguments as tx in Mojo::UserAgent::Transactor (except for the DELETE method, which is implied). You can also append a callback to perform requests non-blocking.



  $ua->delete(http://example.com => json => {a => b} => sub {
    my ($ua, $tx) = @_;
    say $tx->res->body;
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;



    get



  my $tx = $ua->get(example.com);
  my $tx = $ua->get(http://example.com => {Accept => */*} => Hi!);
  my $tx = $ua->get(
    http://example.com => {Accept => */*} => form => {a => b});
  my $tx = $ua->get(
    http://example.com => {Accept => */*} => json => {a => b});



Perform blocking GET request and return resulting Mojo::Transaction::HTTP object, takes the same arguments as tx in Mojo::UserAgent::Transactor (except for the GET method, which is implied). You can also append a callback to perform requests non-blocking.



  $ua->get(http://example.com => json => {a => b} => sub {
    my ($ua, $tx) = @_;
    say $tx->res->body;
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;



    head



  my $tx = $ua->head(example.com);
  my $tx = $ua->head(http://example.com => {Accept => */*} => Hi!);
  my $tx = $ua->head(
    http://example.com => {Accept => */*} => form => {a => b});
  my $tx = $ua->head(
    http://example.com => {Accept => */*} => json => {a => b});



Perform blocking HEAD request and return resulting Mojo::Transaction::HTTP object, takes the same arguments as tx in Mojo::UserAgent::Transactor (except for the HEAD method, which is implied). You can also append a callback to perform requests non-blocking.



  $ua->head(http://example.com => json => {a => b} => sub {
    my ($ua, $tx) = @_;
    say $tx->res->body;
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;



    options



  my $tx = $ua->options(example.com);
  my $tx = $ua->options(http://example.com => {Accept => */*} => Hi!);
  my $tx = $ua->options(
    http://example.com => {Accept => */*} => form => {a => b});
  my $tx = $ua->options(
    http://example.com => {Accept => */*} => json => {a => b});



Perform blocking OPTIONS request and return resulting Mojo::Transaction::HTTP object, takes the same arguments as tx in Mojo::UserAgent::Transactor (except for the OPTIONS method, which is implied). You can also append a callback to perform requests non-blocking.



  $ua->options(http://example.com => json => {a => b} => sub {
    my ($ua, $tx) = @_;
    say $tx->res->body;
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;



    patch



  my $tx = $ua->patch(example.com);
  my $tx = $ua->patch(http://example.com => {Accept => */*} => Hi!);
  my $tx = $ua->patch(
    http://example.com => {Accept => */*} => form => {a => b});
  my $tx = $ua->patch(
    http://example.com => {Accept => */*} => json => {a => b});



Perform blocking PATCH request and return resulting Mojo::Transaction::HTTP object, takes the same arguments as tx in Mojo::UserAgent::Transactor (except for the PATCH method, which is implied). You can also append a callback to perform requests non-blocking.



  $ua->patch(http://example.com => json => {a => b} => sub {
    my ($ua, $tx) = @_;
    say $tx->res->body;
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;



    post



  my $tx = $ua->post(example.com);
  my $tx = $ua->post(http://example.com => {Accept => */*} => Hi!);
  my $tx = $ua->post(
    http://example.com => {Accept => */*} => form => {a => b});
  my $tx = $ua->post(
    http://example.com => {Accept => */*} => json => {a => b});



Perform blocking POST request and return resulting Mojo::Transaction::HTTP object, takes the same arguments as tx in Mojo::UserAgent::Transactor (except for the POST method, which is implied). You can also append a callback to perform requests non-blocking.



  $ua->post(http://example.com => json => {a => b} => sub {
    my ($ua, $tx) = @_;
    say $tx->res->body;
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;



    put



  my $tx = $ua->put(example.com);
  my $tx = $ua->put(http://example.com => {Accept => */*} => Hi!);
  my $tx = $ua->put(
    http://example.com => {Accept => */*} => form => {a => b});
  my $tx = $ua->put(
    http://example.com => {Accept => */*} => json => {a => b});



Perform blocking PUT request and return resulting Mojo::Transaction::HTTP object, takes the same arguments as tx in Mojo::UserAgent::Transactor (except for the PUT method, which is implied). You can also append a callback to perform requests non-blocking.



  $ua->put(http://example.com => json => {a => b} => sub {
    my ($ua, $tx) = @_;
    say $tx->res->body;
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;



    start



  my $tx = $ua->start(Mojo::Transaction::HTTP->new);



Perform blocking request for a custom Mojo::Transaction::HTTP object, which can be prepared manually or with build_tx. You can also append a callback to perform requests non-blocking.



  my $tx = $ua->build_tx(GET => http://example.com);
  $ua->start($tx => sub {
    my ($ua, $tx) = @_;
    say $tx->res->body;
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;



    websocket



  $ua->websocket(ws://example.com => sub {...});
  $ua->websocket(
    ws://example.com => {DNT => 1} => [v1.proto] => sub {...});



Open a non-blocking WebSocket connection with transparent handshake, takes the same arguments as websocket in Mojo::UserAgent::Transactor. The callback will receive either a Mojo::Transaction::WebSocket or Mojo::Transaction::HTTP object, depending on if the handshake was successful.



  $ua->websocket(wss://example.com/echo => [v1.proto] => sub {
    my ($ua, $tx) = @_;
    say WebSocket handshake failed! and return unless $tx->is_websocket;
    say Subprotocol negotiation failed! and return unless $tx->protocol;
    $tx->on(finish => sub {
      my ($tx, $code, $reason) = @_;
      say "WebSocket closed with status $code.";
    });
    $tx->on(message => sub {
      my ($tx, $msg) = @_;
      say "WebSocket message: $msg";
      $tx->finish;
    });
    $tx->send(Hi!);
  });
  Mojo::IOLoop->start unless Mojo::IOLoop->is_running;



You can activate permessage-deflate compression by setting the Sec-WebSocket-Extensions header, this can result in much better performance, but also increases memory usage by up to 300KB per connection.



  $ua->websocket(ws://example.com/foo => {
    Sec-WebSocket-Extensions => permessage-deflate
  } => sub {...});



DEBUGGING

You can set the MOJO_USERAGENT_DEBUG environment variable to get some advanced diagnostics information printed to STDERR.



  MOJO_USERAGENT_DEBUG=1



SEE ALSO

Mojolicious, Mojolicious::Guides, <http://mojolicious.org>.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 MOJO::USERAGENT (3) 2016-03-16

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.