/ 
Mojolicious-4.21
River stage four • 1089 direct dependents • 1234 total dependents
⭐ Starred 2674 GitHub stars
/ Mojo::Transaction::WebSocket
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.

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.

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.

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::Transaction::WebSocket - WebSocket transaction

SYNOPSIS

use Mojo::Transaction::WebSocket;

# Send and receive WebSocket messages
my $ws = Mojo::Transaction::WebSocket->new;
$ws->send('Hello World!');
$ws->on(message => sub {
  my ($ws, $msg) = @_;
  say "Message: $msg";
});
$ws->on(finish => sub {
  my ($ws, $code, $reason) = @_;
  say "WebSocket closed with status $code.";
});

DESCRIPTION

Mojo::Transaction::WebSocket is a container for WebSocket transactions as described in RFC 6455. Note that 64bit frames require a Perl with support for quads or they are limited to 32bit.

EVENTS

Mojo::Transaction::WebSocket inherits all events from Mojo::Transaction and can emit the following new ones.

binary

$ws->on(binary => sub {
  my ($ws, $bytes) = @_;
  ...
});

Emitted when a complete WebSocket binary message has been received.

$ws->on(binary => sub {
  my ($ws, $bytes) = @_;
  say "Binary: $bytes";
});

drain

$ws->on(drain => sub {
  my $ws = shift;
  ...
});

Emitted once all data has been sent.

$ws->on(drain => sub {
  my $ws = shift;
  $ws->send(time);
});

finish

$ws->on(finish => sub {
  my ($ws, $code, $reason) = @_;
  ...
});

Emitted when transaction is finished.

frame

$ws->on(frame => sub {
  my ($ws, $frame) = @_;
  ...
});

Emitted when a WebSocket frame has been received.

$ws->unsubscribe('frame');
$ws->on(frame => sub {
  my ($ws, $frame) = @_;
  say "FIN: $frame->[0]";
  say "RSV1: $frame->[1]";
  say "RSV2: $frame->[2]";
  say "RSV3: $frame->[3]";
  say "Opcode: $frame->[4]";
  say "Payload: $frame->[5]";
});

json

$ws->on(json => sub {
  my ($ws, $json) = @_;
  ...
});

Emitted when a complete WebSocket message has been received, all text and binary messages will be automatically JSON decoded. Note that this event only gets emitted when it has at least one subscriber.

$ws->on(json => sub {
  my ($ws, $hash) = @_;
  say "Message: $hash->{msg}";
});

message

$ws->on(message => sub {
  my ($ws, $msg) = @_;
  ...
});

Emitted when a complete WebSocket message has been received, text messages will be automatically decoded. Note that this event only gets emitted when it has at least one subscriber.

$ws->on(message => sub {
  my ($ws, $msg) = @_;
  say "Message: $msg";
});

text

$ws->on(text => sub {
  my ($ws, $bytes) = @_;
  ...
});

Emitted when a complete WebSocket text message has been received.

$ws->on(text => sub {
  my ($ws, $bytes) = @_;
  say "Text: $bytes";
});

ATTRIBUTES

Mojo::Transaction::WebSocket inherits all attributes from Mojo::Transaction and implements the following new ones.

handshake

my $handshake = $ws->handshake;
$ws           = $ws->handshake(Mojo::Transaction::HTTP->new);

The original handshake transaction, defaults to a Mojo::Transaction::HTTP object.

masked

my $masked = $ws->masked;
$ws        = $ws->masked(1);

Mask outgoing frames with XOR cipher and a random 32bit key.

max_websocket_size

my $size = $ws->max_websocket_size;
$ws      = $ws->max_websocket_size(1024);

Maximum WebSocket message size in bytes, defaults to the value of the MOJO_MAX_WEBSOCKET_SIZE environment variable or 262144.

METHODS

Mojo::Transaction::WebSocket inherits all methods from Mojo::Transaction and implements the following new ones.

new

my $ws = Mojo::Transaction::WebSocket->new;

Construct a new Mojo::Transaction::WebSocket object and subscribe to frame event with default message parser, which also handles PING and CLOSE frames automatically.

build_frame

my $bytes = $ws->build_frame($fin, $rsv1, $rsv2, $rsv3, $op, $payload);

Build WebSocket frame.

# Binary frame with FIN bit and payload
say $ws->build_frame(1, 0, 0, 0, 2, 'Hello World!');

# Text frame with payload but without FIN bit
say $ws->build_frame(0, 0, 0, 0, 1, 'Hello ');

# Continuation frame with FIN bit and payload
say $ws->build_frame(1, 0, 0, 0, 0, 'World!');

# Close frame with FIN bit and without payload
say $ws->build_frame(1, 0, 0, 0, 8, '');

# Ping frame with FIN bit and payload
say $ws->build_frame(1, 0, 0, 0, 9, 'Test 123');

# Pong frame with FIN bit and payload
say $ws->build_frame(1, 0, 0, 0, 10, 'Test 123');

client_challenge

my $success = $ws->client_challenge;

Check WebSocket handshake challenge client-side, used to implement user agents.

client_handshake

$ws->client_handshake;

Perform WebSocket handshake client-side, used to implement user agents.

client_read

$ws->client_read($data);

Read data client-side, used to implement user agents.

client_write

my $bytes = $ws->client_write;

Write data client-side, used to implement user agents.

connection

my $connection = $ws->connection;

Connection identifier or socket.

finish

$ws = $ws->finish;
$ws = $ws->finish(1000);
$ws = $ws->finish(1003 => 'Cannot accept data!');

Close WebSocket connection gracefully.

is_websocket

my $true = $ws->is_websocket;

True.

kept_alive

my $kept_alive = $ws->kept_alive;

Connection has been kept alive.

local_address

my $address = $ws->local_address;

Local interface address.

local_port

my $port = $ws->local_port;

Local interface port.

parse_frame

my $frame = $ws->parse_frame(\$bytes);

Parse WebSocket frame.

# Parse single frame and remove it from buffer
my $frame = $ws->parse_frame(\$buffer);
say "FIN: $frame->[0]";
say "RSV1: $frame->[1]";
say "RSV2: $frame->[2]";
say "RSV3: $frame->[3]";
say "Opcode: $frame->[4]";
say "Payload: $frame->[5]";

remote_address

my $address = $ws->remote_address;

Remote interface address.

remote_port

my $port = $ws->remote_port;

Remote interface port.

req

my $req = $ws->req;

Handshake request, usually a Mojo::Message::Request object.

res

my $res = $ws->res;

Handshake response, usually a Mojo::Message::Response object.

resume

$ws = $ws->resume;

Resume handshake transaction.

send

$ws = $ws->send({binary => $bytes});
$ws = $ws->send({text   => $bytes});
$ws = $ws->send({json   => {test => [1, 2, 3]}});
$ws = $ws->send([$fin, $rsv1, $rsv2, $rsv3, $op, $bytes]);
$ws = $ws->send(Mojo::ByteStream->new($chars));
$ws = $ws->send($chars);
$ws = $ws->send($chars => sub {...});

Send message or frame non-blocking via WebSocket, the optional drain callback will be invoked once all data has been written.

# Send "Ping" frame
$ws->send([1, 0, 0, 0, 9, 'Hello World!']);

server_close

$ws->server_close;

Transaction closed server-side, used to implement web servers.

server_handshake

$ws->server_handshake;

Perform WebSocket handshake server-side, used to implement web servers.

server_read

$ws->server_read($data);

Read data server-side, used to implement web servers.

server_write

my $bytes = $ws->server_write;

Write data server-side, used to implement web servers.

DEBUGGING

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

MOJO_WEBSOCKET_DEBUG=1

SEE ALSO

Mojolicious, Mojolicious::Guides, http://mojolicio.us.