Class: EventMachine::WebSocket::Connection

Inherits:
Connection
  • Object
show all
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

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ Connection

Returns a new instance of Connection.



39
40
41
42
43
44
45
46
47
 
# File 'lib/em-websocket/connection.rb', line 39

def initialize(options)
  @options = options
  @debug = options[:debug] || false
  @secure = options[:secure] || false
  @tls_options = options[:tls_options] || {}
  @data = ''

  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



221
222
223
 
# File 'lib/em-websocket/connection.rb', line 221

def max_frame_size
  @max_frame_size || WebSocket.max_frame_size
end

Instance Method Details

#close_websocket(code = nil, body = nil) ⇒ Object

Use this method to close the websocket connection cleanly This sends a close frame and waits for acknowlegement before closing the connection



52
53
54
55
56
57
58
59
60
61
 
# File 'lib/em-websocket/connection.rb', line 52

def close_websocket(code = nil, body = nil)
  if code && !(4000..4999).include?(code)
    raise "Application code may only use codes in the range 4000-4999"
  end

  # If code not defined then set to 1000 (normal closure)
  code ||= 1000

  close_websocket_private(code, body)
end

#dispatch(data) ⇒ Object 



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/em-websocket/connection.rb', line 103

def dispatch(data)
  if data.match(/\A<policy-file-request\s*\/>/)
    send_flash_cross_domain_file
    return false
  else
    debug [:inbound_headers, data]
    @data << data
    @handler = HandlerFactory.build(self, @data, @secure, @debug)
    unless @handler
      # The whole header has not been received yet.
      return false
    end
    @data = nil
    @handler.run
    return true
  end
end

#onclose(&blk) ⇒ Object 



12
 
# File 'lib/em-websocket/connection.rb', line 12

def onclose(&blk);    @onclose = blk;   end

#onerror(&blk) ⇒ Object 



13
 
# File 'lib/em-websocket/connection.rb', line 13

def onerror(&blk);    @onerror = blk;   end

#onmessage(&blk) ⇒ Object 



14
 
# File 'lib/em-websocket/connection.rb', line 14

def onmessage(&blk);  @onmessage = blk; end

#onopen(&blk) ⇒ Object

define WebSocket callbacks



11
 
# File 'lib/em-websocket/connection.rb', line 11

def onopen(&blk);     @onopen = blk;    end

#onping(&blk) ⇒ Object 



15
 
# File 'lib/em-websocket/connection.rb', line 15

def onping(&blk);     @onping = blk;    end

#onpong(&blk) ⇒ Object 



16
 
# File 'lib/em-websocket/connection.rb', line 16

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



173
174
175
176
177
178
179
 
# File 'lib/em-websocket/connection.rb', line 173

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)

Returns:

  • (Boolean) 


197
198
199
200
201
202
203
 
# File 'lib/em-websocket/connection.rb', line 197

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.



187
188
189
190
191
192
193
 
# File 'lib/em-websocket/connection.rb', line 187

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 



63
64
65
 
# File 'lib/em-websocket/connection.rb', line 63

def post_init
  start_tls(@tls_options) if @secure
end

#receive_data(data) ⇒ Object 



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/em-websocket/connection.rb', line 67

def receive_data(data)
  debug [:receive_data, data]

  if @handler
    @handler.receive_data(data)
  else
    dispatch(data)
  end
rescue HandshakeError => e
  debug [:error, e]
  trigger_on_error(e)
  # Errors during the handshake require the connection to be aborted
  abort
rescue WSProtocolError => e
  debug [:error, e]
  trigger_on_error(e)
  close_websocket_private(e.code)
rescue => e
  debug [:error, e]
  # These are application errors - raise unless onerror defined
  trigger_on_error(e) || raise(e)
  # There is no code defined for application errors, so use 3000
  # (which is reserved for frameworks)
  close_websocket_private(3000)
end

#request ⇒ Object 



205
206
207
 
# File 'lib/em-websocket/connection.rb', line 205

def request
  @handler ? @handler.request : {}
end

#send(data) ⇒ Object

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



142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/em-websocket/connection.rb', line 142

def send(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

#send_flash_cross_domain_file ⇒ Object 



121
122
123
124
125
126
127
128
129
130
 
# File 'lib/em-websocket/connection.rb', line 121

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

#state ⇒ Object 



209
210
211
 
# File 'lib/em-websocket/connection.rb', line 209

def state
  @handler ? @handler.state : :handshake
end

#trigger_on_close ⇒ Object 



24
25
26
 
# File 'lib/em-websocket/connection.rb', line 24

def trigger_on_close
  @onclose.call if @onclose
end

#trigger_on_error(reason) ⇒ Object 



33
34
35
36
37
 
# File 'lib/em-websocket/connection.rb', line 33

def trigger_on_error(reason)
  return false unless @onerror
  @onerror.call(reason)
  true
end

#trigger_on_message(msg) ⇒ Object 



18
19
20
 
# File 'lib/em-websocket/connection.rb', line 18

def trigger_on_message(msg)
  @onmessage.call(msg) if @onmessage
end

#trigger_on_open ⇒ Object 



21
22
23
 
# File 'lib/em-websocket/connection.rb', line 21

def trigger_on_open
  @onopen.call if @onopen
end

#trigger_on_ping(data) ⇒ Object 



27
28
29
 
# File 'lib/em-websocket/connection.rb', line 27

def trigger_on_ping(data)
  @onping.call(data) if @onping
end

#trigger_on_pong(data) ⇒ Object 



30
31
32
 
# File 'lib/em-websocket/connection.rb', line 30

def trigger_on_pong(data)
  @onpong.call(data) if @onpong
end

#unbind ⇒ Object 



93
94
95
96
97
98
99
100
101
 
# File 'lib/em-websocket/connection.rb', line 93

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