Debian Codegraph @

README

raw
1 NAME
2
3 AnyEvent::WebSocket::Client - WebSocket client for AnyEvent
4
5 VERSION
6
7 version 0.55
8
9 SYNOPSIS
10
11 use AnyEvent::WebSocket::Client 0.12;
12
13 my $client = AnyEvent::WebSocket::Client->new;
14
15 $client->connect("ws://localhost:1234/service")->cb(sub {
16
17 # make $connection an our variable rather than
18 # my so that it will stick around. Once the
19 # connection falls out of scope any callbacks
20 # tied to it will be destroyed.
21 our $connection = eval { shift->recv };
22 if($@) {
23 # handle error...
24 warn $@;
25 return;
26 }
27
28 # send a message through the websocket...
29 $connection->send('a message');
30
31 # recieve message from the websocket...
32 $connection->on(each_message => sub {
33 # $connection is the same connection object
34 # $message isa AnyEvent::WebSocket::Message
35 my($connection, $message) = @_;
36 ...
37 });
38
39 # handle a closed connection...
40 $connection->on(finish => sub {
41 # $connection is the same connection object
42 my($connection) = @_;
43 ...
44 });
45
46 # close the connection (either inside or
47 # outside another callback)
48 $connection->close;
49
50 });
51
52 ## uncomment to enter the event loop before exiting.
53 ## Note that calling recv on a condition variable before
54 ## it has been triggered does not work on all event loops
55 #AnyEvent->condvar->recv;
56
57 DESCRIPTION
58
59 This class provides an interface to interact with a web server that
60 provides services via the WebSocket protocol in an AnyEvent context. It
61 uses Protocol::WebSocket rather than reinventing the wheel. You could
62 use AnyEvent and Protocol::WebSocket directly if you wanted finer grain
63 control, but if that is not necessary then this class may save you some
64 time.
65
66 The recommended API was added to the AnyEvent::WebSocket::Connection
67 class with version 0.12, so it is recommended that you include that
68 version when using this module. The older version of the API has since
69 been deprecated and removed.
70
71 ATTRIBUTES
72
73 timeout
74
75 Timeout for the initial connection to the web server. The default is
76 30.
77
78 ssl_no_verify
79
80 If set to true, then secure WebSockets (those that use SSL/TLS) will
81 not be verified. The default is false.
82
83 ssl_ca_file
84
85 Provide your own CA certificates file instead of using the system
86 default for SSL/TLS verification.
87
88 protocol_version
89
90 The protocol version. See Protocol::WebSocket for the list of supported
91 WebSocket protocol versions.
92
93 subprotocol
94
95 List of subprotocols to request from the server. This class will throw
96 an exception if none of the protocols are supported by the server.
97
98 http_headers
99
100 Extra headers to include in the initial request. May be either
101 specified as a hash reference, or an array reference. For example:
102
103 AnyEvent::WebSocket::Client->new(
104 http_headers => {
105 'X-Foo' => 'bar',
106 'X-Baz' => [ 'abc', 'def' ],
107 },
108 );
109
110 AnyEvent::WebSocket::Client->new(
111 http_headers => [
112 'X-Foo' => 'bar',
113 'X-Baz' => 'abc',
114 'X-Baz' => 'def',
115 ],
116 );
117
118 Will generate:
119
120 X-Foo: bar
121 X-Baz: abc
122 X-Baz: def
123
124 Although, the order cannot be guaranteed when using the hash style.
125
126 max_payload_size
127
128 The maximum payload size for received frames. Currently defaults to
129 whatever Protocol::WebSocket defaults to.
130
131 max_fragments
132
133 The maximum number of fragments for received frames. Currently defaults
134 to whatever Protocol::WebSocket defaults to.
135
136 env_proxy
137
138 If you set true to this boolean attribute, it loads proxy settings from
139 environment variables. If it finds valid proxy settings, connect method
140 will use that proxy.
141
142 Default: false.
143
144 For ws WebSocket end-points, first it reads ws_proxy (or WS_PROXY)
145 environment variable. If it is not set or empty string, then it reads
146 http_proxy (or HTTP_PROXY). For wss WebSocket end-points, it reads
147 wss_proxy (WSS_PROXY) and https_proxy (HTTPS_PROXY) environment
148 variables.
149
150 METHODS
151
152 connect
153
154 my $cv = $client->connect($uri)
155 my $cv = $client->connect($uri, $host, $port);
156
157 Open a connection to the web server and open a WebSocket to the
158 resource defined by the given URL. The URL may be either an instance of
159 URI::ws, URI::wss, or a string that represents a legal WebSocket URL.
160
161 You can override the connection host and port by passing them in as the
162 second and third argument. These values (if provided) are passed
163 directly into AnyEvent::Socket's tcp_connect function, so please note
164 that function's idiosyncrasies in the AnyEvent::Socket documentation.
165 In particular, you can pass in unix/ as the host and a filesystem path
166 as the "port" to connect to a unix domain socket.
167
168 This method will return an AnyEvent condition variable which you can
169 attach a callback to. The value sent through the condition variable
170 will be either an instance of AnyEvent::WebSocket::Connection or a
171 croak message indicating a failure. The synopsis above shows how to
172 catch such errors using eval.
173
174 FAQ
175
176 My program exits before doing anything, what is up with that?
177
178 See this FAQ from AnyEvent:
179 AnyEvent::FAQ#My-program-exits-before-doing-anything-whats-going-on.
180
181 It is probably also a good idea to review the AnyEvent documentation if
182 you are new to AnyEvent or event-based programming.
183
184 My callbacks aren't being called!
185
186 Make sure that the connection object is still in scope. This often
187 happens if you use a my $connection variable and don't save it
188 somewhere. For example:
189
190 $client->connect("ws://foo/service")->cb(sub {
191
192 my $connection = eval { shift->recv };
193
194 if($@)
195 {
196 warn $@;
197 return;
198 }
199
200 ...
201 });
202
203 Unless $connection is saved somewhere it will get deallocated along
204 with any associated message callbacks will also get deallocated once
205 the connect callback is executed. One way to make sure that the
206 connection doesn't get deallocated is to make it a our variable (as in
207 the synopsis above) instead.
208
209 CAVEATS
210
211 This is pretty simple minded and there are probably WebSocket features
212 that you might like to use that aren't supported by this distribution.
213 Patches are encouraged to improve it.
214
215 SEE ALSO
216
217 * AnyEvent::WebSocket::Connection
218
219 * AnyEvent::WebSocket::Message
220
221 * AnyEvent::WebSocket::Server
222
223 * AnyEvent
224
225 * URI::ws
226
227 * URI::wss
228
229 * Protocol::WebSocket
230
231 * Net::WebSocket::Server
232
233 * Net::Async::WebSocket
234
235 * RFC 6455 The WebSocket Protocol
236 <http://tools.ietf.org/html/rfc6455>
237
238 AUTHOR
239
240 Author: Graham Ollis <[email protected]>
241
242 Contributors:
243
244 Toshio Ito (debug-ito, TOSHIOITO)
245
246 José Joaquín Atria (JJATRIA)
247
248 Kivanc Yazan (KYZN)
249
250 Yanick Champoux (YANICK)
251
252 Fayland Lam (FAYLAND)
253
254 Daniel Kamil Kozar (xavery)
255
256 COPYRIGHT AND LICENSE
257
258 This software is copyright (c) 2013-2022 by Graham Ollis.
259
260 This is free software; you can redistribute it and/or modify it under
261 the same terms as the Perl 5 programming language system itself.
262