| 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 |
|