.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mojo::Transaction::WebSocket 3pm"
.TH Mojo::Transaction::WebSocket 3pm 2024-03-24 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Mojo::Transaction::WebSocket \- WebSocket transaction
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Mojo::Transaction::WebSocket;
\&
\&  # Send and receive WebSocket messages
\&  my $ws = Mojo::Transaction::WebSocket\->new;
\&  $ws\->send(\*(AqHello World!\*(Aq);
\&  $ws\->on(message => sub ($ws, $msg) { say "Message: $msg" });
\&  $ws\->on(finish => sub ($ws, $code, $reason) { say "WebSocket closed with status $code." });
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Mojo::Transaction::WebSocket is a container for WebSocket transactions, based on RFC
6455 <https://tools.ietf.org/html/rfc6455> and RFC 7692 <https://tools.ietf.org/html/rfc7692>.
.SH EVENTS
.IX Header "EVENTS"
Mojo::Transaction::WebSocket inherits all events from Mojo::Transaction and can emit the following new ones.
.SS binary
.IX Subsection "binary"
.Vb 1
\&  $ws\->on(binary => sub ($ws, $bytes) {...});
.Ve
.PP
Emitted when a complete WebSocket binary message has been received.
.PP
.Vb 1
\&  $ws\->on(binary => sub ($ws, $bytes) { say "Binary: $bytes" });
.Ve
.SS drain
.IX Subsection "drain"
.Vb 1
\&  $ws\->on(drain => sub ($ws) {...});
.Ve
.PP
Emitted once all data has been sent.
.PP
.Vb 1
\&  $ws\->on(drain => sub ($ws) { $ws\->send(time) });
.Ve
.SS finish
.IX Subsection "finish"
.Vb 1
\&  $ws\->on(finish => sub ($ws, $code, $reason) {...});
.Ve
.PP
Emitted when the WebSocket connection has been closed.
.SS frame
.IX Subsection "frame"
.Vb 1
\&  $ws\->on(frame => sub ($ws, $frame) {...});
.Ve
.PP
Emitted when a WebSocket frame has been received.
.PP
.Vb 8
\&  $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]";
\&  });
.Ve
.SS json
.IX Subsection "json"
.Vb 1
\&  $ws\->on(json => sub ($ws, $json) {...});
.Ve
.PP
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.
.PP
.Vb 1
\&  $ws\->on(json => sub ($ws, $hash) { say "Message: $hash\->{msg}" });
.Ve
.SS message
.IX Subsection "message"
.Vb 1
\&  $ws\->on(message => sub ($ws, $msg) {...});
.Ve
.PP
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.
.PP
.Vb 1
\&  $ws\->on(message => sub ($ws, $msg) { say "Message: $msg" });
.Ve
.SS resume
.IX Subsection "resume"
.Vb 1
\&  $tx\->on(resume => sub ($tx) {...});
.Ve
.PP
Emitted when transaction is resumed.
.SS text
.IX Subsection "text"
.Vb 1
\&  $ws\->on(text => sub ($ws, $bytes) {...});
.Ve
.PP
Emitted when a complete WebSocket text message has been received.
.PP
.Vb 1
\&  $ws\->on(text => sub ($ws, $bytes) { say "Text: $bytes" });
.Ve
.SH ATTRIBUTES
.IX Header "ATTRIBUTES"
Mojo::Transaction::WebSocket inherits all attributes from Mojo::Transaction and implements the following new
ones.
.SS compressed
.IX Subsection "compressed"
.Vb 2
\&  my $bool = $ws\->compressed;
\&  $ws      = $ws\->compressed($bool);
.Ve
.PP
Compress messages with \f(CW\*(C`permessage\-deflate\*(C'\fR extension.
.SS established
.IX Subsection "established"
.Vb 2
\&  my $bool = $ws\->established;
\&  $ws      = $ws\->established($bool);
.Ve
.PP
WebSocket connection established.
.SS handshake
.IX Subsection "handshake"
.Vb 2
\&  my $handshake = $ws\->handshake;
\&  $ws           = $ws\->handshake(Mojo::Transaction::HTTP\->new);
.Ve
.PP
The original handshake transaction, usually a Mojo::Transaction::HTTP object.
.SS masked
.IX Subsection "masked"
.Vb 2
\&  my $bool = $ws\->masked;
\&  $ws      = $ws\->masked($bool);
.Ve
.PP
Mask outgoing frames with XOR cipher and a random 32\-bit key.
.SS max_websocket_size
.IX Subsection "max_websocket_size"
.Vb 2
\&  my $size = $ws\->max_websocket_size;
\&  $ws      = $ws\->max_websocket_size(1024);
.Ve
.PP
Maximum WebSocket message size in bytes, defaults to the value of the \f(CW\*(C`MOJO_MAX_WEBSOCKET_SIZE\*(C'\fR environment variable
or \f(CW262144\fR (256KiB).
.SH METHODS
.IX Header "METHODS"
Mojo::Transaction::WebSocket inherits all methods from Mojo::Transaction and implements the following new ones.
.SS build_message
.IX Subsection "build_message"
.Vb 4
\&  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);
.Ve
.PP
Build WebSocket message.
.SS client_read
.IX Subsection "client_read"
.Vb 1
\&  $ws\->client_read($data);
.Ve
.PP
Read data client-side, used to implement user agents such as Mojo::UserAgent.
.SS client_write
.IX Subsection "client_write"
.Vb 1
\&  my $bytes = $ws\->client_write;
.Ve
.PP
Write data client-side, used to implement user agents such as Mojo::UserAgent.
.SS closed
.IX Subsection "closed"
.Vb 1
\&  $tx = $tx\->closed;
.Ve
.PP
Same as "completed" in Mojo::Transaction, but also indicates that all transaction data has been sent.
.SS connection
.IX Subsection "connection"
.Vb 1
\&  my $id = $ws\->connection;
.Ve
.PP
Connection identifier.
.SS finish
.IX Subsection "finish"
.Vb 3
\&  $ws = $ws\->finish;
\&  $ws = $ws\->finish(1000);
\&  $ws = $ws\->finish(1003 => \*(AqCannot accept data!\*(Aq);
.Ve
.PP
Close WebSocket connection gracefully.
.SS is_websocket
.IX Subsection "is_websocket"
.Vb 1
\&  my $bool = $ws\->is_websocket;
.Ve
.PP
True, this is a Mojo::Transaction::WebSocket object.
.SS kept_alive
.IX Subsection "kept_alive"
.Vb 1
\&  my $bool = $ws\->kept_alive;
.Ve
.PP
Connection has been kept alive.
.SS local_address
.IX Subsection "local_address"
.Vb 1
\&  my $address = $ws\->local_address;
.Ve
.PP
Local interface address.
.SS local_port
.IX Subsection "local_port"
.Vb 1
\&  my $port = $ws\->local_port;
.Ve
.PP
Local interface port.
.SS parse_message
.IX Subsection "parse_message"
.Vb 1
\&  $ws\->parse_message([$fin, $rsv1, $rsv2, $rsv3, $op, $payload]);
.Ve
.PP
Parse WebSocket message.
.SS protocol
.IX Subsection "protocol"
.Vb 1
\&  my $proto = $ws\->protocol;
.Ve
.PP
Return negotiated subprotocol or \f(CW\*(C`undef\*(C'\fR.
.SS remote_address
.IX Subsection "remote_address"
.Vb 1
\&  my $address = $ws\->remote_address;
.Ve
.PP
Remote interface address.
.SS remote_port
.IX Subsection "remote_port"
.Vb 1
\&  my $port = $ws\->remote_port;
.Ve
.PP
Remote interface port.
.SS req
.IX Subsection "req"
.Vb 1
\&  my $req = $ws\->req;
.Ve
.PP
Handshake request, usually a Mojo::Message::Request object.
.SS res
.IX Subsection "res"
.Vb 1
\&  my $res = $ws\->res;
.Ve
.PP
Handshake response, usually a Mojo::Message::Response object.
.SS resume
.IX Subsection "resume"
.Vb 1
\&  $ws = $ws\->resume;
.Ve
.PP
Resume "handshake" transaction.
.SS send
.IX Subsection "send"
.Vb 6
\&  $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 {...});
.Ve
.PP
Send message or frame non-blocking via WebSocket, the optional drain callback will be executed once all data has been
written.
.PP
.Vb 3
\&  # Send "Ping" frame
\&  use Mojo::WebSocket qw(WS_PING);
\&  $ws\->send([1, 0, 0, 0, WS_PING, \*(AqHello World!\*(Aq]);
.Ve
.SS server_read
.IX Subsection "server_read"
.Vb 1
\&  $ws\->server_read($data);
.Ve
.PP
Read data server-side, used to implement web servers such as Mojo::Server::Daemon.
.SS server_write
.IX Subsection "server_write"
.Vb 1
\&  my $bytes = $ws\->server_write;
.Ve
.PP
Write data server-side, used to implement web servers such as Mojo::Server::Daemon.
.SS with_compression
.IX Subsection "with_compression"
.Vb 1
\&  $ws\->with_compression;
.Ve
.PP
Negotiate \f(CW\*(C`permessage\-deflate\*(C'\fR extension for this WebSocket connection.
.SS with_protocols
.IX Subsection "with_protocols"
.Vb 1
\&  my $proto = $ws\->with_protocols(\*(Aqv2.proto\*(Aq, \*(Aqv1.proto\*(Aq);
.Ve
.PP
Negotiate subprotocol for this WebSocket connection.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.