WebSocket/Endpoint/Server.pm

filter: Statementstmt 100% 10 / 10 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 3 / 3 Podpod n/a totaltotal 100% 13 / 13 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« WebSocket/Endpoint/Client.pm ↑ Summary WebSocket/Frame/binary.pm »
1 package Net::WebSocket::Endpoint::Server;
2  
3 10 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 10 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 10 ▶use parent qw(
Subroutine BEGIN: called CC=1 SCAR=0.0
7 Net::WebSocket::Endpoint
8 Net::WebSocket::Masker::Server
9 10 );
10  
11 =encoding utf-8
12  
13 =head1 NAME
14  
15 Net::WebSocket::Endpoint::Server
16  
17 =head1 SYNOPSIS
18  
19 my $ept = Net::WebSocket::Endpoint::Server->new(
20 parser => $parser_obj,
21  
22 out => $out_fh,
23  
24 #optional, # of pings to send before we send a close
25 max_pings => 5,
26  
27 #optional
28 on_data_frame => sub {
29 my ($frame_obj) = @_;
30  
31 #...
32 },
33 );
34  
35 my $msg_to_send = $ept->create_message('text', 'Hello!');
36  
37 if ( _we_timed_out_waiting_for_read_readiness() ) {
38 $ept->check_heartbeat();
39 }
40 else {
41  
42 #This should only be called when reading won’t produce an error.
43 #For example, in non-blocking I/O you’ll need a select() in front
44 #of this. (Blocking I/O can just call it and wait!)
45 $ept->get_next_message();
46  
47 #Check for this at the end of each cycle.
48 _custom_logic_to_finish_up() if $ept->is_closed();
49 }
50  
51 =head1 DESCRIPTION
52  
53 This module, like its twin, L<Net::WebSocket::Endpoint::Client>, attempts
54 to wrap up “obvious” bits of a WebSocket endpoint’s workflow into a
55 reusable component.
56  
57 The basic workflow is shown in the SYNOPSIS; descriptions of the individual
58 methods follow:
59  
60 =head1 METHODS
61  
62 =head2 I<CLASS>->new( %OPTS )
63  
64 Instantiate the class. Nothing is actually done here. Options are:
65  
66 =over
67  
68 =item * C<parser> (required) - An instance of L<Net::WebSocket::Parser>.
69  
70 =item * C<out> (required) - The endpoint’s output object. An
71 instance of L<IO::Framed> or a compatible class.
72  
73 =item * C<max_pings> (optional) - The maximum # of pings to send before
74 we send a C<close> frame (which ends the session).
75  
76 =item * C<on_data_frame> (optional) - A callback that receives every data
77 frame that C<get_next_message()> receives. Use this to facilitate chunking.
78  
79 If you want to avoid buffering a large message, you can do this:
80  
81 on_data_frame => sub {
82 #... however you’re going to handle this chunk
83  
84 $_[0] = (ref $_[0])->new(
85 payload => q<>,
86 fin => $_[0]->get_fin(),
87 );
88 },
89  
90 =back
91  
92 =head2 I<OBJ>->get_next_message()
93  
94 The “workhorse” method. It returns one of the following:
95  
96 =over
97  
98 =item * a data message if one is available
99  
100 =item * empty string if the Parser’s C<get_next_frame()> indicated
101 end-of-file without an exception
102  
103 =item * otherwise, undef
104  
105 =back
106  
107 This method also handles control frames that arrive before or among
108 message frames:
109  
110 =over
111  
112 =item * close: Respond (immediately) with the identical close frame.
113 See below for more information.
114  
115 =item * ping: Send the appropriate pong frame.
116  
117 =item * pong: As per the protocol specification.
118  
119 =back
120  
121 This method may not be called after a close frame has been sent (i.e.,
122 if the C<is_closed()> method returns true).
123  
124 =head2 I<OBJ>->create_message( FRAME_TYPE, PAYLOAD )
125  
126 Creates an unfragmented message with the given PAYLOAD.
127  
128 FRAME_TYPE can be either C<text> or C<binary> (for Net::WebSocket’s
129 default frame classes) or full package names (e.g., to use a custom
130 frame class).
131  
132 This is a convenience method that takes care of mask creation and module
133 loading for you.
134  
135 See L<Net::WebSocket::PMCE::deflate::Data> for similar functionality
136 to create a compressed message.
137  
138 =cut
139  
140 =head2 I<OBJ>->check_heartbeat()
141  
142 Ordinarily, sends a distinct ping frame to the remote server
143 and increments the ping counter. Once a sent ping is
144 received back (i.e., a pong), the ping counter gets reset.
145  
146 If the internal ping counter has already reached C<max_pings>, then we
147 send a PROTOCOL_ERROR close frame. Further I/O attempts on this object
148 will prompt an appropriate exception to be thrown.
149  
150 =head2 I<OBJ>->sent_close_frame()
151  
152 Returns a C<Net::WebSocket::Frame::close> object or undef to represent the
153 frame that the object has sent, either via the C<close()> method directly
154 or automatically via the internal handling of control messages.
155  
156 =head2 I<OBJ>->received_close_frame()
157  
158 Returns a C<Net::WebSocket::Frame::close> object or undef to represent the
159 frame that the object has received.
160  
161 =head2 I<OBJ>->is_closed()
162  
163 DEPRECATED: Returns 1 or 0 to indicate whether we have sent a close frame.
164 Note that C<sent_close_frame()> provides a more useful variant of the
165 same functionality; there is no good reason to use this method anymore.
166  
167 =head2 I<OBJ>->do_not_die_on_close()
168  
169 Ordinarily, receipt of a close frame prompts an exception after the
170 response close frame is sent. This is, arguably, a suboptimal design
171 choice since receipt of a close frame is a perfectly normal thing to happen;
172 i.e., it’s not “exception-al”. If you want to check for close yourself
173 instead, you can do so by calling this method.
174  
175 =head2 I<OBJ>->die_on_close()
176  
177 The inverse of C<do_not_die_on_close()>: restores
178 the default behavior when a close frame is received.
179  
180 =head1 WHEN A CLOSE FRAME IS RECEIVED
181  
182 C<get_next_message()> will automatically send a close frame in response
183 when it receives one. The received close frame is not returned to the
184 application but, like ping and pong, is handled transparently.
185  
186 Rationale: WebSocket is often billed as “TCP for the web”; however, the
187 protocol curiously diverges from TCP in not supporting “half-close”; a
188 WebSocket connection is either fully open (i.e., bidirectional) or fully
189 closed. (There is some leeway given for finishing up an in-progress message,
190 but this is a much more limited concept.)
191  
192 =head1 EXTENSIONS
193  
194 This module has several controls for supporting WebSocket extensions:
195  
196 =over
197  
198 =item * C<get_next_message()>’s returned messages will always contain
199 a C<get_frames()> method, which you can use to read the reserved bits
200 of the individual data frames.
201  
202 =item * You can create C<on_*> methods on a subclass of this module
203 to handle different types of control frames. (e.g., C<on_foo(FRAME)>)
204 to handle frames of type C<foo>.) The C<parser> object that you pass
205 to the constructor has to be aware of such messages; for more details,
206 see the documentation for L<Net::WebSocket::Parser>.
207  
208 =back
209  
210 =cut
211  
212 10 1;
« WebSocket/Endpoint/Client.pm ↑ Summary WebSocket/Frame/binary.pm »