Class: Appium::Core::WebSocket

Inherits:
Object
  • Object
show all
Defined in:
lib/appium_lib_core/common/ws/websocket.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(url:, protocols: nil, options: {}) ⇒ WebSocket

A websocket client based on Faye::WebSocket::Client . Uses eventmachine to wait response from the peer. The eventmachine works on a thread. The thread will exit with close method.

Examples:

ws = WebSocket.new(url: "ws://#{host}:#{port}/ws/session/#{@session_id}/appium/device/logcat")
ws.client #=> #<Faye::WebSocket::Client:.....> # An instance of Faye::WebSocket::Client
ws.message 'some message' #=> nil. Send a message to the peer.
ws.close #=> Kill the thread which run a eventmachine.

Parameters:

  • url (String) —

    URL to establish web socket connection. If the URL has no port, the client use: ws: 80, wss: 443 ports.

  • protocols (Array) (defaults to: nil) —

    An array of strings representing acceptable subprotocols for use over the socket. The driver will negotiate one of these to use via the Sec-WebSocket-Protocol header if supported by the other peer. Default is nil. The protocols is equal to github.com/faye/faye-websocket-ruby/ ‘s one for client.

  • options (Hash) (defaults to: {}) —

    Initialize options for Faye client. Read github.com/faye/faye-websocket-ruby#initialization-options for more details. Default is {}.



42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/appium_lib_core/common/ws/websocket.rb', line 42

def initialize(url:, protocols: nil, options: {})
  @endpoint = url

  @ws_thread = Thread.new do
    # steep:ignore:start
    EM.run do
      @client ||= ::Faye::WebSocket::Client.new(url, protocols, options)

      @client.on :open do |_open|
        handle_open
      end

      @client.on :message do |message|
        handle_message_data(message.data)
      end

      @client.on :error do |_error|
        handle_error
      end

      @client.on :close do |close|
        handle_close(close.code, close.reason)
      end
    end
    # steep:ignore:end
  end
end

Instance Attribute Details

#client ⇒ Object (readonly)

Returns the value of attribute client.



21
22
23
 
# File 'lib/appium_lib_core/common/ws/websocket.rb', line 21

def client
  @client
end

#endpoint ⇒ Object (readonly)

Returns the value of attribute endpoint.



21
22
23
 
# File 'lib/appium_lib_core/common/ws/websocket.rb', line 21

def endpoint
  @endpoint
end

Instance Method Details

#close(code: nil, reason: 'close from ruby_lib_core') ⇒ Object

Closes the connection, sending the given status code and reason text, both of which are optional.

Examples:

ws = WebSocket.new(url: "ws://#{host}:#{port}/ws/session/#{@session_id}/appium/device/logcat")
ws.close reason: 'a something special reason'

Parameters:

  • code (Integer) (defaults to: nil) —

    A status code to send to the peer with close signal. Default is nil.

  • reason (String) (defaults to: 'close from ruby_lib_core') —

    A reason to send to the peer with close signal. Default is ‘close from ruby_lib_core’.



108
109
110
111
112
113
114
115
 
# File 'lib/appium_lib_core/common/ws/websocket.rb', line 108

def close(code: nil, reason: 'close from ruby_lib_core')
  if @client.nil?
    ::Appium::Logger.warn 'Websocket was closed'
  else
    @client.close code, reason
  end
  @ws_thread.exit
end

#handle_close(code, reason) ⇒ Object

Fires when either the client or the server closes the connection. The method gets code and reason attributes. They expose the status code and message sent by the peer that closed the connection.

Default is just put a error message. The methods also clear client instance and stop the eventmachine which is called in initialising this class.



160
161
162
163
164
165
166
 
# File 'lib/appium_lib_core/common/ws/websocket.rb', line 160

def handle_close(code, reason)
  ::Appium::Logger.debug("#{self.class} :close #{code} #{reason}")
  @client = nil
  # steep:ignore:start
  EM.stop
  # steep:ignore:end
end

#handle_error ⇒ Object

Fires when there is a protocol error due to bad data sent by the other peer. This event is purely informational, you do not need to implement error recovery.

Default is just put a error message.



149
150
151
 
# File 'lib/appium_lib_core/common/ws/websocket.rb', line 149

def handle_error
  ::Appium::Logger.error("#{self.class} :error")
end

#handle_message_data(data) ⇒ Object

Fires when the socket receives a message. The message gas one data attribute and this method can handle the data. The data is either a String (for text frames) or an Array of byte-sized integers (for binary frames).

Default is just put a debug message and puts the result on standard out. In general, users should override this handler to handle messages from the peer.



138
139
140
141
 
# File 'lib/appium_lib_core/common/ws/websocket.rb', line 138

def handle_message_data(data)
  ::Appium::Logger.debug("#{self.class} :message #{data}")
  $stdout << "#{data}\n"
end

#handle_open ⇒ Object

Fires when the socket connection is established. Event has no attributes.

Default is just put a debug message.



124
125
126
 
# File 'lib/appium_lib_core/common/ws/websocket.rb', line 124

def handle_open
  ::Appium::Logger.debug("#{self.class} :open")
end

#ping(message, &callback) ⇒ Object

Sends a ping frame with an optional message and fires the callback when a matching pong is received.

Examples:

ws = WebSocket.new(url: "ws://#{host}:#{port}/ws/session/#{@session_id}/appium/device/logcat")
ws.ping 'message'

Parameters:

  • message (String) —

    A message to send ping.

  • callback (Block) 


82
83
84
 
# File 'lib/appium_lib_core/common/ws/websocket.rb', line 82

def ping(message, &callback)
  @client.ping message, &callback
end

#send(message) ⇒ Object

Accepts either a String or an Array of byte-sized integers and sends a text or binary message over the connection to the other peer; binary data must be encoded as an Array.

Examples:

ws = WebSocket.new(url: "ws://#{host}:#{port}/ws/session/#{@session_id}/appium/device/logcat")
ws.send 'happy testing'

Parameters:

  • message (String, Array) —

    A message to send a text or binary message over the connection



95
96
97
 
# File 'lib/appium_lib_core/common/ws/websocket.rb', line 95

def send(message)
  @client.send message
end