Security Advisories (10)

CPANSA-Mojolicious-2022-03 (2022-12-10)

Mojo::DOM did not correctly parse <script> tags.

CPANSA-Mojolicious-2021-02 (2021-06-01)

Small sessions could be used as part of a brute-force attack to decode the session secret.

https://github.com/mojolicious/mojo/pull/1791

CVE-2021-47208 (2021-03-16)

A bug in format detection can potentially be exploited for a DoS attack.

CVE-2018-25100 (2018-02-13)

Mojo::UserAgent::CookieJar leaks old cookies because of the missing host_only flag on empty domain.

CPANSA-Mojolicious-2015-01 (2015-02-02)

Directory traversal on Windows

CPANSA-Mojolicious-2018-03 (2018-05-19)

Mojo::UserAgent was not checking peer SSL certificates by default.

CVE-2020-36829 (2020-11-10)

Mojo::Util secure_compare can leak the string length. By immediately returning when the two strings are not the same length, the function allows an attacker to guess the length of the secret string using timing attacks.

https://github.com/mojolicious/mojo/pull/1601

CPANSA-Mojolicious-2018-02 (2018-05-11)

GET requests with embedded backslashes can be used to access local files on Windows hosts

CPANSA-Mojolicious-2014-01 (2014-10-07)

Context sensitivity of method param could lead to parameter injection attacks.

https://github.com/mojolicious/mojo/commit/a815d4797145f872ef6e9f1270841eda1d410afb

CVE-2024-58134 (2025-05-03)

Mojolicious versions from 0.999922 for Perl uses a hard coded string, or the application's class name, as a HMAC session secret by default. These predictable default secrets can be exploited to forge session cookies. An attacker who knows or guesses the secret could compute valid HMAC signatures for the session cookie, allowing them to tamper with or hijack another user's session.

NAME

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

SYNOPSIS

use Mojo::UserAgent;

# Say hello to the Unicode snowman with "Do Not Track" header
my $ua = Mojo::UserAgent->new;
say $ua->get('www.☃.net?hello=there' => {DNT => 1})->res->body;

# Form POST 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}";
}

# Quick JSON API request with Basic authentication
say $ua->get('https://sri:s3cret@example.com/search.json?q=perl')
  ->res->json('/results/0/title');

# Extract data from HTML and XML resources
say $ua->get('www.perl.org')->res->dom->html->head->title->text;

# Scrape the latest headlines from a news site with CSS selectors
say $ua->get('blogs.perl.org')->res->dom('h2 > a')->text->shuffle;

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

# Follow redirects to grab the latest Mojolicious release :)
$ua->max_redirects(5)->get('latest.mojolicio.us')
  ->res->content->asset->move_to('/Users/sri/mojo.tar.gz');

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

# Non-blocking concurrent requests
my $delay = Mojo::IOLoop->delay(sub {
  my ($delay, @titles) = @_;
  say for @titles;
});
for my $url ('mojolicio.us', 'cpan.org') {
  my $end = $delay->begin(0);
  $ua->get($url => sub {
    my ($ua, $tx) = @_;
    $end->($tx->res->dom->at('title')->text);
  });
}
$delay->wait;

# Non-blocking 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, Comet (long polling), keep-alive, connection pooling, timeout, cookie, multipart, proxy, 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 IPv6 as well as TLS support, the optional modules EV (4.0+), IO::Socket::IP (0.20+) and IO::Socket::SSL (1.84+) will be used automatically by Mojo::IOLoop if they are installed. Individual features can also be disabled with the MOJO_NO_IPV6 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.

error

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

Emitted if an error occurs that can't be associated with a transaction, fatal if unhandled.

$ua->on(error => sub {
  my ($ua, $err) = @_;
  say "This looks bad: $err";
});

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, 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 this user agents requests, defaults to a Mojo::UserAgent::CookieJar object.

# Disable cookie jar
$ua->cookie_jar(0);

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;

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.

# Introspect
say for @{$ua->server->app->secrets};

# 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' => {DNT => 1} => 'Hi!');
my $tx = $ua->build_tx(
  PUT => 'http://example.com' => {DNT => 1} => form => {a => 'b'});
my $tx = $ua->build_tx(
  PUT => 'http://example.com' => {DNT => 1} => json => {a => 'b'});

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

# Request with custom cookie
my $tx = $ua->build_tx(GET => 'example.com');
$tx->req->cookies({name => 'foo', value => 'bar'});
$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 => '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.

delete

my $tx = $ua->delete('example.com');
my $tx = $ua->delete('http://example.com' => {DNT => 1} => 'Hi!');
my $tx = $ua->delete(
  'http://example.com' => {DNT => 1} => form => {a => 'b'});
my $tx = $ua->delete(
  'http://example.com' => {DNT => 1} => 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 method). You can also append a callback to perform requests non-blocking.

$ua->delete('http://example.com' => 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' => {DNT => 1} => 'Hi!');
my $tx = $ua->get('http://example.com' => {DNT => 1} => form => {a => 'b'});
my $tx = $ua->get('http://example.com' => {DNT => 1} => 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 method). You can also append a callback to perform requests non-blocking.

$ua->get('http://example.com' => 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' => {DNT => 1} => 'Hi!');
my $tx = $ua->head(
  'http://example.com' => {DNT => 1} => form => {a => 'b'});
my $tx = $ua->head(
  'http://example.com' => {DNT => 1} => 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 method). You can also append a callback to perform requests non-blocking.

$ua->head('http://example.com' => 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' => {DNT => 1} => 'Hi!');
my $tx = $ua->options(
  'http://example.com' => {DNT => 1} => form => {a => 'b'});
my $tx = $ua->options(
  'http://example.com' => {DNT => 1} => 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 method). You can also append a callback to perform requests non-blocking.

$ua->options('http://example.com' => 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' => {DNT => 1} => 'Hi!');
my $tx = $ua->patch(
  'http://example.com' => {DNT => 1} => form => {a => 'b'});
my $tx = $ua->patch(
  'http://example.com' => {DNT => 1} => 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 method). You can also append a callback to perform requests non-blocking.

$ua->patch('http://example.com' => 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' => {DNT => 1} => 'Hi!');
my $tx = $ua->post(
  'http://example.com' => {DNT => 1} => form => {a => 'b'});
my $tx = $ua->post(
  'http://example.com' => {DNT => 1} => 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 method). You can also append a callback to perform requests non-blocking.

$ua->post('http://example.com' => 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' => {DNT => 1} => 'Hi!');
my $tx = $ua->put('http://example.com' => {DNT => 1} => form => {a => 'b'});
my $tx = $ua->put('http://example.com' => {DNT => 1} => 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 method). You can also append a callback to perform requests non-blocking.

$ua->put('http://example.com' => 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. 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.

$ua->websocket('ws://example.com/echo' => sub {
  my ($ua, $tx) = @_;
  say 'WebSocket handshake failed!' and return unless $tx->is_websocket;
  $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.

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

DEBUGGING

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

MOJO_USERAGENT_DEBUG=1

	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

EVENTS

error

start

ATTRIBUTES

ca

cert

connect_timeout

cookie_jar

inactivity_timeout

ioloop

key

local_address

max_connections

max_redirects

proxy

request_timeout

server

transactor

METHODS

build_tx

build_websocket_tx

delete

get

head

options

patch

post

put

start

websocket

DEBUGGING

SEE ALSO

Module Install Instructions