Mojo::Transaction::WebSocket - WebSocket transaction
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."; });
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.
Mojo::Transaction::WebSocket inherits all events from Mojo::Transaction and can emit the following new ones.
$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"; });
$ws->on(drain => sub { my $ws = shift; ... });
Emitted once all data has been sent.
$ws->on(drain => sub { my $ws = shift; $ws->send(time); });
$ws->on(finish => sub { my ($ws, $code, $reason) = @_; ... });
Emitted when transaction is finished.
$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]"; });
$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}"; });
$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"; });
$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"; });
Mojo::Transaction::WebSocket inherits all attributes from Mojo::Transaction and implements the following new ones.
my $handshake = $ws->handshake; $ws = $ws->handshake(Mojo::Transaction::HTTP->new);
The original handshake transaction, defaults to a Mojo::Transaction::HTTP object.
my $masked = $ws->masked; $ws = $ws->masked(1);
Mask outgoing frames with XOR cipher and a random 32bit key.
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.
262144
Mojo::Transaction::WebSocket inherits all methods from Mojo::Transaction and implements the following new ones.
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.
frame
PING
CLOSE
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');
my $success = $ws->client_challenge;
Check WebSocket handshake challenge client-side, used to implement user agents.
$ws->client_handshake;
Perform WebSocket handshake client-side, used to implement user agents.
$ws->client_read($data);
Read data client-side, used to implement user agents.
my $bytes = $ws->client_write;
Write data client-side, used to implement user agents.
my $connection = $ws->connection;
Connection identifier or socket.
$ws = $ws->finish; $ws = $ws->finish(1000); $ws = $ws->finish(1003 => 'Cannot accept data!');
Close WebSocket connection gracefully.
my $true = $ws->is_websocket;
True.
my $kept_alive = $ws->kept_alive;
Connection has been kept alive.
my $address = $ws->local_address;
Local interface address.
my $port = $ws->local_port;
Local interface port.
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]";
my $address = $ws->remote_address;
Remote interface address.
my $port = $ws->remote_port;
Remote interface port.
my $req = $ws->req;
Handshake request, usually a Mojo::Message::Request object.
my $res = $ws->res;
Handshake response, usually a Mojo::Message::Response object.
$ws = $ws->resume;
Resume handshake transaction.
handshake
$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!']);
$ws->server_close;
Transaction closed server-side, used to implement web servers.
$ws->server_handshake;
Perform WebSocket handshake server-side, used to implement web servers.
$ws->server_read($data);
Read data server-side, used to implement web servers.
my $bytes = $ws->server_write;
Write data server-side, used to implement web servers.
You can set the MOJO_WEBSOCKET_DEBUG environment variable to get some advanced diagnostics information printed to STDERR.
STDERR
MOJO_WEBSOCKET_DEBUG=1
Mojolicious, Mojolicious::Guides, http://mojolicio.us.
To install Mojolicious, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojolicious
CPAN shell
perl -MCPAN -e shell install Mojolicious
For more information on module installation, please visit the detailed CPAN module installation guide.