--- name: "Mojo::Transaction::WebSocket" section: "3pm" platform: "linux" package: "libmojolicious-perl" version: "9.39+dfsg-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Mojo::Transaction::WebSocket" --- # Mojo::Transaction::WebSocket(3pm) WebSocket transaction ## 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 ($ws, $msg) { say "Message: $msg" }); $ws->on(finish => sub ($ws, $code, $reason) { say "WebSocket closed with status $code." }); ``` ## DESCRIPTION Mojo::Transaction::WebSocket is a container for WebSocket transactions, based on RFC 6455 \ and RFC 7692 \. ## EVENTS Mojo::Transaction::WebSocket inherits all events from Mojo::Transaction and can emit the following new ones. ### binary ``` $ws->on(binary => sub ($ws, $bytes) {...}); ``` Emitted when a complete WebSocket binary message has been received. ``` $ws->on(binary => sub ($ws, $bytes) { say "Binary: $bytes" }); ``` ### drain ``` $ws->on(drain => sub ($ws) {...}); ``` Emitted once all data has been sent. ``` $ws->on(drain => sub ($ws) { $ws->send(time) }); ``` ### finish ``` $ws->on(finish => sub ($ws, $code, $reason) {...}); ``` Emitted when the WebSocket connection has been closed. ### frame ``` $ws->on(frame => sub ($ws, $frame) {...}); ``` Emitted when a WebSocket frame has been received. ``` $ws->on(frame => sub ($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 ($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 ($ws, $hash) { say "Message: $hash->{msg}" }); ``` ### message ``` $ws->on(message => sub ($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 ($ws, $msg) { say "Message: $msg" }); ``` ### resume ``` $tx->on(resume => sub ($tx) {...}); ``` Emitted when transaction is resumed. ### text ``` $ws->on(text => sub ($ws, $bytes) {...}); ``` Emitted when a complete WebSocket text message has been received. ``` $ws->on(text => sub ($ws, $bytes) { say "Text: $bytes" }); ``` ## ATTRIBUTES Mojo::Transaction::WebSocket inherits all attributes from Mojo::Transaction and implements the following new ones. ### compressed ``` my $bool = $ws->compressed; $ws = $ws->compressed($bool); ``` Compress messages with `"permessage-deflate"` extension. ### established ``` my $bool = $ws->established; $ws = $ws->established($bool); ``` WebSocket connection established. ### handshake ``` my $handshake = $ws->handshake; $ws = $ws->handshake(Mojo::Transaction::HTTP->new); ``` The original handshake transaction, usually a Mojo::Transaction::HTTP object. ### masked ``` my $bool = $ws->masked; $ws = $ws->masked($bool); ``` Mask outgoing frames with XOR cipher and a random 32-bit 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` (256KiB). ## METHODS Mojo::Transaction::WebSocket inherits all methods from Mojo::Transaction and implements the following new ones. ### build\_message ``` my $frame = $ws->build_message({binary => $bytes}); my $frame = $ws->build_message({text => $bytes}); my $frame = $ws->build_message({json => {test => [1, 2, 3]}}); my $frame = $ws->build_message($chars); ``` Build WebSocket message. ### client\_read ``` $ws->client_read($data); ``` Read data client-side, used to implement user agents such as Mojo::UserAgent. ### client\_write ``` my $bytes = $ws->client_write; ``` Write data client-side, used to implement user agents such as Mojo::UserAgent. ### closed ``` $tx = $tx->closed; ``` Same as "completed" in Mojo::Transaction, but also indicates that all transaction data has been sent. ### connection ``` my $id = $ws->connection; ``` Connection identifier. ### finish ``` $ws = $ws->finish; $ws = $ws->finish(1000); $ws = $ws->finish(1003 => 'Cannot accept data!'); ``` Close WebSocket connection gracefully. ### is\_websocket ``` my $bool = $ws->is_websocket; ``` True, this is a Mojo::Transaction::WebSocket object. ### kept\_alive ``` my $bool = $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\_message ``` $ws->parse_message([$fin, $rsv1, $rsv2, $rsv3, $op, $payload]); ``` Parse WebSocket message. ### protocol ``` my $proto = $ws->protocol; ``` Return negotiated subprotocol or `"undef"`. ### 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, $payload]); $ws = $ws->send($chars); $ws = $ws->send($chars => sub {...}); ``` Send message or frame non-blocking via WebSocket, the optional drain callback will be executed once all data has been written. ``` # Send "Ping" frame use Mojo::WebSocket qw(WS_PING); $ws->send([1, 0, 0, 0, WS_PING, 'Hello World!']); ``` ### server\_read ``` $ws->server_read($data); ``` Read data server-side, used to implement web servers such as Mojo::Server::Daemon. ### server\_write ``` my $bytes = $ws->server_write; ``` Write data server-side, used to implement web servers such as Mojo::Server::Daemon. ### with\_compression ``` $ws->with_compression; ``` Negotiate `"permessage-deflate"` extension for this WebSocket connection. ### with\_protocols ``` my $proto = $ws->with_protocols('v2.proto', 'v1.proto'); ``` Negotiate subprotocol for this WebSocket connection. ## SEE ALSO Mojolicious, Mojolicious::Guides, \.