1Mojo::Transaction::WebSUoscekretC(o3n)tributed Perl DocuMmoejnot:a:tTiroannsaction::WebSocket(3)
2
3
4

NAME

6       Mojo::Transaction::WebSocket - WebSocket transaction
7

SYNOPSIS

9         use Mojo::Transaction::WebSocket;
10
11         # Send and receive WebSocket messages
12         my $ws = Mojo::Transaction::WebSocket->new;
13         $ws->send('Hello World!');
14         $ws->on(message => sub ($ws, $msg) { say "Message: $msg" });
15         $ws->on(finish => sub ($ws, $code, $reason) { say "WebSocket closed with status $code." });
16

DESCRIPTION

18       Mojo::Transaction::WebSocket is a container for WebSocket transactions,
19       based on RFC 6455 <https://tools.ietf.org/html/rfc6455> and RFC 7692
20       <https://tools.ietf.org/html/rfc7692>.
21

EVENTS

23       Mojo::Transaction::WebSocket inherits all events from Mojo::Transaction
24       and can emit the following new ones.
25
26   binary
27         $ws->on(binary => sub ($ws, $bytes) {...});
28
29       Emitted when a complete WebSocket binary message has been received.
30
31         $ws->on(binary => sub ($ws, $bytes) { say "Binary: $bytes" });
32
33   drain
34         $ws->on(drain => sub ($ws) {...});
35
36       Emitted once all data has been sent.
37
38         $ws->on(drain => sub ($ws) { $ws->send(time) });
39
40   finish
41         $ws->on(finish => sub ($ws, $code, $reason) {...});
42
43       Emitted when the WebSocket connection has been closed.
44
45   frame
46         $ws->on(frame => sub ($ws, $frame) {...});
47
48       Emitted when a WebSocket frame has been received.
49
50         $ws->on(frame => sub ($ws, $frame) {
51           say "FIN: $frame->[0]";
52           say "RSV1: $frame->[1]";
53           say "RSV2: $frame->[2]";
54           say "RSV3: $frame->[3]";
55           say "Opcode: $frame->[4]";
56           say "Payload: $frame->[5]";
57         });
58
59   json
60         $ws->on(json => sub ($ws, $json) {...});
61
62       Emitted when a complete WebSocket message has been received, all text
63       and binary messages will be automatically JSON decoded. Note that this
64       event only gets emitted when it has at least one subscriber.
65
66         $ws->on(json => sub ($ws, $hash) { say "Message: $hash->{msg}" });
67
68   message
69         $ws->on(message => sub ($ws, $msg) {...});
70
71       Emitted when a complete WebSocket message has been received, text
72       messages will be automatically decoded. Note that this event only gets
73       emitted when it has at least one subscriber.
74
75         $ws->on(message => sub ($ws, $msg) { say "Message: $msg" });
76
77   resume
78         $tx->on(resume => sub ($tx) {...});
79
80       Emitted when transaction is resumed.
81
82   text
83         $ws->on(text => sub ($ws, $bytes) {...});
84
85       Emitted when a complete WebSocket text message has been received.
86
87         $ws->on(text => sub ($ws, $bytes) { say "Text: $bytes" });
88

ATTRIBUTES

90       Mojo::Transaction::WebSocket inherits all attributes from
91       Mojo::Transaction and implements the following new ones.
92
93   compressed
94         my $bool = $ws->compressed;
95         $ws      = $ws->compressed($bool);
96
97       Compress messages with "permessage-deflate" extension.
98
99   established
100         my $bool = $ws->established;
101         $ws      = $ws->established($bool);
102
103       WebSocket connection established.
104
105   handshake
106         my $handshake = $ws->handshake;
107         $ws           = $ws->handshake(Mojo::Transaction::HTTP->new);
108
109       The original handshake transaction, usually a Mojo::Transaction::HTTP
110       object.
111
112   masked
113         my $bool = $ws->masked;
114         $ws      = $ws->masked($bool);
115
116       Mask outgoing frames with XOR cipher and a random 32-bit key.
117
118   max_websocket_size
119         my $size = $ws->max_websocket_size;
120         $ws      = $ws->max_websocket_size(1024);
121
122       Maximum WebSocket message size in bytes, defaults to the value of the
123       "MOJO_MAX_WEBSOCKET_SIZE" environment variable or 262144 (256KiB).
124

METHODS

126       Mojo::Transaction::WebSocket inherits all methods from
127       Mojo::Transaction and implements the following new ones.
128
129   build_message
130         my $frame = $ws->build_message({binary => $bytes});
131         my $frame = $ws->build_message({text   => $bytes});
132         my $frame = $ws->build_message({json   => {test => [1, 2, 3]}});
133         my $frame = $ws->build_message($chars);
134
135       Build WebSocket message.
136
137   client_read
138         $ws->client_read($data);
139
140       Read data client-side, used to implement user agents such as
141       Mojo::UserAgent.
142
143   client_write
144         my $bytes = $ws->client_write;
145
146       Write data client-side, used to implement user agents such as
147       Mojo::UserAgent.
148
149   closed
150         $tx = $tx->closed;
151
152       Same as "completed" in Mojo::Transaction, but also indicates that all
153       transaction data has been sent.
154
155   connection
156         my $id = $ws->connection;
157
158       Connection identifier.
159
160   finish
161         $ws = $ws->finish;
162         $ws = $ws->finish(1000);
163         $ws = $ws->finish(1003 => 'Cannot accept data!');
164
165       Close WebSocket connection gracefully.
166
167   is_websocket
168         my $bool = $ws->is_websocket;
169
170       True, this is a Mojo::Transaction::WebSocket object.
171
172   kept_alive
173         my $bool = $ws->kept_alive;
174
175       Connection has been kept alive.
176
177   local_address
178         my $address = $ws->local_address;
179
180       Local interface address.
181
182   local_port
183         my $port = $ws->local_port;
184
185       Local interface port.
186
187   parse_message
188         $ws->parse_message([$fin, $rsv1, $rsv2, $rsv3, $op, $payload]);
189
190       Parse WebSocket message.
191
192   protocol
193         my $proto = $ws->protocol;
194
195       Return negotiated subprotocol or "undef".
196
197   remote_address
198         my $address = $ws->remote_address;
199
200       Remote interface address.
201
202   remote_port
203         my $port = $ws->remote_port;
204
205       Remote interface port.
206
207   req
208         my $req = $ws->req;
209
210       Handshake request, usually a Mojo::Message::Request object.
211
212   res
213         my $res = $ws->res;
214
215       Handshake response, usually a Mojo::Message::Response object.
216
217   resume
218         $ws = $ws->resume;
219
220       Resume "handshake" transaction.
221
222   send
223         $ws = $ws->send({binary => $bytes});
224         $ws = $ws->send({text   => $bytes});
225         $ws = $ws->send({json   => {test => [1, 2, 3]}});
226         $ws = $ws->send([$fin, $rsv1, $rsv2, $rsv3, $op, $payload]);
227         $ws = $ws->send($chars);
228         $ws = $ws->send($chars => sub {...});
229
230       Send message or frame non-blocking via WebSocket, the optional drain
231       callback will be executed once all data has been written.
232
233         # Send "Ping" frame
234         use Mojo::WebSocket qw(WS_PING);
235         $ws->send([1, 0, 0, 0, WS_PING, 'Hello World!']);
236
237   server_read
238         $ws->server_read($data);
239
240       Read data server-side, used to implement web servers such as
241       Mojo::Server::Daemon.
242
243   server_write
244         my $bytes = $ws->server_write;
245
246       Write data server-side, used to implement web servers such as
247       Mojo::Server::Daemon.
248
249   with_compression
250         $ws->with_compression;
251
252       Negotiate "permessage-deflate" extension for this WebSocket connection.
253
254   with_protocols
255         my $proto = $ws->with_protocols('v2.proto', 'v1.proto');
256
257       Negotiate subprotocol for this WebSocket connection.
258

SEE ALSO

260       Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.
261
262
263
264perl v5.36.0                      2023-01-20   Mojo::Transaction::WebSocket(3)
Impressum