Class: EventMachine::WebSocket::Connection
- Inherits:
-
Connection
- Object
- Connection
- EventMachine::WebSocket::Connection
- Includes:
- Debugger
- Defined in:
- lib/em-websocket/connection.rb
Constant Summary collapse
- ENCODING_SUPPORTED =
Cache encodings since it’s moderately expensive to look them up each time
"string".respond_to?(:force_encoding)
- UTF8 =
Encoding.find("UTF-8")
- BINARY =
Encoding.find("BINARY")
Instance Attribute Summary collapse
-
#max_frame_size ⇒ Object
Returns the maximum frame size which this connection is configured to accept.
Instance Method Summary collapse
-
#close(code = nil, body = nil) ⇒ Object
(also: #close_websocket)
Use this method to close the websocket connection cleanly This sends a close frame and waits for acknowlegement before closing the connection.
- #close_timeout ⇒ Object
- #dispatch(data) ⇒ Object
-
#initialize(options) ⇒ Connection
constructor
A new instance of Connection.
- #onbinary(&blk) ⇒ Object
- #onclose(&blk) ⇒ Object
- #onerror(&blk) ⇒ Object
- #onmessage(&blk) ⇒ Object
-
#onopen(&blk) ⇒ Object
define WebSocket callbacks.
- #onping(&blk) ⇒ Object
- #onpong(&blk) ⇒ Object
-
#ping(body = '') ⇒ Object
Send a ping to the client.
-
#pingable? ⇒ Boolean
Test whether the connection is pingable (i.e. the WebSocket draft in use is >= 01).
-
#pong(body = '') ⇒ Object
Send an unsolicited pong message, as allowed by the protocol.
- #post_init ⇒ Object
- #receive_data(data) ⇒ Object
-
#send_binary(data) ⇒ Object
Send a WebSocket binary frame.
- #send_flash_cross_domain_file ⇒ Object
-
#send_text(data) ⇒ Object
(also: #send)
Send a WebSocket text frame.
- #state ⇒ Object
- #supports_close_codes? ⇒ Boolean
- #trigger_on_binary(msg) ⇒ Object
- #trigger_on_close(event = {}) ⇒ Object
- #trigger_on_error(reason) ⇒ Object
- #trigger_on_message(msg) ⇒ Object
- #trigger_on_open(handshake) ⇒ Object
- #trigger_on_ping(data) ⇒ Object
- #trigger_on_pong(data) ⇒ Object
- #unbind ⇒ Object
Constructor Details
#initialize(options) ⇒ Connection
Returns a new instance of Connection.
41 42 43 44 45 46 47 48 49 50 51 52 |
# File 'lib/em-websocket/connection.rb', line 41 def initialize() @options = @debug = [:debug] || false @secure = [:secure] || false @secure_proxy = [:secure_proxy] || false @tls_options = [:tls_options] || {} @close_timeout = [:close_timeout] @handler = nil debug [:initialize] end |
Instance Attribute Details
#max_frame_size ⇒ Object
Returns the maximum frame size which this connection is configured to accept. This can be set globally or on a per connection basis, and defaults to a value of 10MB if not set.
The behaviour when a too large frame is received varies by protocol, but in the newest protocols the connection will be closed with the correct close code (1009) immediately after receiving the frame header
247 248 249 |
# File 'lib/em-websocket/connection.rb', line 247 def max_frame_size defined?(@max_frame_size) ? @max_frame_size : WebSocket.max_frame_size end |
Instance Method Details
#close(code = nil, body = nil) ⇒ Object Also known as: close_websocket
Use this method to close the websocket connection cleanly This sends a close frame and waits for acknowlegement before closing the connection
57 58 59 60 61 62 63 |
# File 'lib/em-websocket/connection.rb', line 57 def close(code = nil, body = nil) if code && !acceptable_close_code?(code) raise "Application code may only use codes from 1000, 3000-4999" end close_websocket_private(code, body) end |
#close_timeout ⇒ Object
251 252 253 |
# File 'lib/em-websocket/connection.rb', line 251 def close_timeout @close_timeout || WebSocket.close_timeout end |
#dispatch(data) ⇒ Object
101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 |
# File 'lib/em-websocket/connection.rb', line 101 def dispatch(data) if data.match(/\A<policy-file-request\s*\/>/) send_flash_cross_domain_file else @handshake ||= begin handshake = Handshake.new(@secure || @secure_proxy) handshake.callback { |upgrade_response, handler_klass| debug [:accepting_ws_version, handshake.protocol_version] debug [:upgrade_response, upgrade_response] self.send_data(upgrade_response) @handler = handler_klass.new(self, @debug) @handshake = nil trigger_on_open(handshake) } handshake.errback { |e| debug [:error, e] trigger_on_error(e) # Handshake errors require the connection to be aborted abort } handshake end @handshake.receive_data(data) end end |
#onbinary(&blk) ⇒ Object
13 |
# File 'lib/em-websocket/connection.rb', line 13 def onbinary(&blk); @onbinary = blk; end |
#onclose(&blk) ⇒ Object
10 |
# File 'lib/em-websocket/connection.rb', line 10 def onclose(&blk); @onclose = blk; end |
#onerror(&blk) ⇒ Object
11 |
# File 'lib/em-websocket/connection.rb', line 11 def onerror(&blk); @onerror = blk; end |
#onmessage(&blk) ⇒ Object
12 |
# File 'lib/em-websocket/connection.rb', line 12 def (&blk); @onmessage = blk; end |
#onopen(&blk) ⇒ Object
define WebSocket callbacks
9 |
# File 'lib/em-websocket/connection.rb', line 9 def onopen(&blk); @onopen = blk; end |
#onping(&blk) ⇒ Object
14 |
# File 'lib/em-websocket/connection.rb', line 14 def onping(&blk); @onping = blk; end |
#onpong(&blk) ⇒ Object
15 |
# File 'lib/em-websocket/connection.rb', line 15 def onpong(&blk); @onpong = blk; end |
#ping(body = '') ⇒ Object
Send a ping to the client. The client must respond with a pong.
In the case that the client is running a WebSocket draft < 01, false is returned since ping & pong are not supported
195 196 197 198 199 200 201 |
# File 'lib/em-websocket/connection.rb', line 195 def ping(body = '') if @handler @handler.pingable? ? @handler.send_frame(:ping, body) && true : false else raise WebSocketError, "Cannot ping before onopen callback" end end |
#pingable? ⇒ Boolean
Test whether the connection is pingable (i.e. the WebSocket draft in use is >= 01)
219 220 221 222 223 224 225 |
# File 'lib/em-websocket/connection.rb', line 219 def pingable? if @handler @handler.pingable? else raise WebSocketError, "Cannot test whether pingable before onopen callback" end end |
#pong(body = '') ⇒ Object
Send an unsolicited pong message, as allowed by the protocol. The client is not expected to respond to this message.
em-websocket automatically takes care of sending pong replies to incoming ping messages, as the protocol demands.
209 210 211 212 213 214 215 |
# File 'lib/em-websocket/connection.rb', line 209 def pong(body = '') if @handler @handler.pingable? ? @handler.send_frame(:pong, body) && true : false else raise WebSocketError, "Cannot ping before onopen callback" end end |
#post_init ⇒ Object
68 69 70 |
# File 'lib/em-websocket/connection.rb', line 68 def post_init start_tls(@tls_options) if @secure end |
#receive_data(data) ⇒ Object
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 |
# File 'lib/em-websocket/connection.rb', line 72 def receive_data(data) debug [:receive_data, data] if @handler @handler.receive_data(data) else dispatch(data) end rescue => e debug [:error, e] # There is no code defined for application errors, so use 3000 # (which is reserved for frameworks) close_websocket_private(3000, "Application error") # These are application errors - raise unless onerror defined trigger_on_error(e) || raise(e) end |
#send_binary(data) ⇒ Object
Send a WebSocket binary frame.
182 183 184 185 186 187 188 |
# File 'lib/em-websocket/connection.rb', line 182 def send_binary(data) if @handler @handler.send_frame(:binary, data) else raise WebSocketError, "Cannot send binary before onopen callback" end end |
#send_flash_cross_domain_file ⇒ Object
131 132 133 134 135 136 137 138 139 140 |
# File 'lib/em-websocket/connection.rb', line 131 def send_flash_cross_domain_file file = '<?xml version="1.0"?><cross-domain-policy><allow-access-from domain="*" to-ports="*"/></cross-domain-policy>' debug [:cross_domain, file] send_data file # handle the cross-domain request transparently # no need to notify the user about this connection @onclose = nil close_connection_after_writing end |
#send_text(data) ⇒ Object Also known as: send
Send a WebSocket text frame.
A WebSocketError may be raised if the connection is in an opening or a closing state, or if the passed in data is not valid UTF-8
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 |
# File 'lib/em-websocket/connection.rb', line 152 def send_text(data) # If we're using Ruby 1.9, be pedantic about encodings if ENCODING_SUPPORTED # Also accept ascii only data in other encodings for convenience unless (data.encoding == UTF8 && data.valid_encoding?) || data.ascii_only? raise WebSocketError, "Data sent to WebSocket must be valid UTF-8 but was #{data.encoding} (valid: #{data.valid_encoding?})" end # This labels the encoding as binary so that it can be combined with # the BINARY framing data.force_encoding(BINARY) else # TODO: Check that data is valid UTF-8 end if @handler @handler.send_text_frame(data) else raise WebSocketError, "Cannot send data before onopen callback" end # Revert data back to the original encoding (which we assume is UTF-8) # Doing this to avoid duping the string - there may be a better way data.force_encoding(UTF8) if ENCODING_SUPPORTED return nil end |
#state ⇒ Object
235 236 237 |
# File 'lib/em-websocket/connection.rb', line 235 def state @handler ? @handler.state : :handshake end |
#supports_close_codes? ⇒ Boolean
227 228 229 230 231 232 233 |
# File 'lib/em-websocket/connection.rb', line 227 def supports_close_codes? if @handler @handler.supports_close_codes? else raise WebSocketError, "Cannot test before onopen callback" end end |
#trigger_on_binary(msg) ⇒ Object
20 21 22 |
# File 'lib/em-websocket/connection.rb', line 20 def trigger_on_binary(msg) @onbinary.call(msg) if defined? @onbinary end |
#trigger_on_close(event = {}) ⇒ Object
26 27 28 |
# File 'lib/em-websocket/connection.rb', line 26 def trigger_on_close(event = {}) @onclose.call(event) if defined? @onclose end |
#trigger_on_error(reason) ⇒ Object
35 36 37 38 39 |
# File 'lib/em-websocket/connection.rb', line 35 def trigger_on_error(reason) return false unless defined? @onerror @onerror.call(reason) true end |
#trigger_on_message(msg) ⇒ Object
17 18 19 |
# File 'lib/em-websocket/connection.rb', line 17 def (msg) @onmessage.call(msg) if defined? @onmessage end |
#trigger_on_open(handshake) ⇒ Object
23 24 25 |
# File 'lib/em-websocket/connection.rb', line 23 def trigger_on_open(handshake) @onopen.call(handshake) if defined? @onopen end |
#trigger_on_ping(data) ⇒ Object
29 30 31 |
# File 'lib/em-websocket/connection.rb', line 29 def trigger_on_ping(data) @onping.call(data) if defined? @onping end |
#trigger_on_pong(data) ⇒ Object
32 33 34 |
# File 'lib/em-websocket/connection.rb', line 32 def trigger_on_pong(data) @onpong.call(data) if defined? @onpong end |
#unbind ⇒ Object
91 92 93 94 95 96 97 98 99 |
# File 'lib/em-websocket/connection.rb', line 91 def unbind debug [:unbind, :connection] @handler.unbind if @handler rescue => e debug [:error, e] # These are application errors - raise unless onerror defined trigger_on_error(e) || raise(e) end |