Module: Ronin::Support::Web::WebSocket

Defined in:
lib/ronin/support/web/websocket.rb,
lib/ronin/support/web/websocket/mixin.rb,
lib/ronin/support/web/websocket/client.rb,
lib/ronin/support/web/websocket/server.rb,
lib/ronin/support/web/websocket/socket.rb,
lib/ronin/support/web/websocket/url_methods.rb

Overview

WebSocket helper methods.

Defined Under Namespace

Modules: Mixin, URLMethods Classes: Client, Server, Socket

Class Method Summary collapse

Class Method Details

.accept(url, ssl: {}, **kwargs) {|client| ... } ⇒ nil

Opens a WebSocket server, accepts a single connection, yields it to the given block, then closes both the connection and the server.

Parameters:

  • url (String, URI::WS, URI::WSS) —

    The ws:// or wss:// URL to connect to.

  • ssl (Hash{Symbol => Object}) (defaults to: {}) —

    Additional keyword arguments for Ronin::Support::Network::SSL.server.

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments for Ronin::Support::Web::WebSocket::Server#initialize.

Options Hash (ssl:):

  • :version (1, 1.1, 1.2, String, Symbol, nil) —

    The SSL version to use.

  • :verify (Symbol, Boolean) —

    Specifies whether to verify the SSL certificate. May be one of the following:

    • :none
    • :peer
    • :fail_if_no_peer_cert
    • :client_once
  • :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

    The RSA key to use for the SSL context.

  • :key_file (String) —

    The path to the SSL .key file.

  • :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

    The X509 certificate to use for the SSL context.

  • :cert_file (String) —

    The path to the SSL .crt file.

  • :ca_bundle (String) —

    Path to the CA certificate file or directory.

Options Hash (**kwargs):

  • :bind_host (String, nil) —

    The optional host to bind the server socket to.

  • :bind_port (Integer, nil) —

    The optioanl port to bind the server socket to. If not specified, it will default to the port of the URL.

  • :backlog (Integer) — default: 5 —

    The maximum backlog of pending connections.

Yields:

  • (client) —

    The given block will be passed the newly connected WebSocket client. After the block has finished, the WebSocket client will be closed.

Yield Parameters:

Returns:

  • (nil) 


349
350
351
352
353
354
355
356
 
# File 'lib/ronin/support/web/websocket.rb', line 349

def self.accept(url, ssl: {}, **kwargs)
  server(url, ssl: ssl, **kwargs) do |server|
    client = server.accept

    yield client if block_given?
    client.close
  end
end

.connect(url, ssl: {}, **kwargs) {|websocket| ... } ⇒ Client

Connects to a websocket.

Examples:

Connecting to a WebSocket server:

websocket_connect('ws://websocket-echo.com')
# => #<Ronin::Support::Web::WebSocket::Client: ...>

Creating a temporary WebSocket connection:

websocket_connect('ws://websocket-echo.com') do |websocket|
  # ...
end

Parameters:

  • url (String, URI::WS, URI::WSS) —

    The ws:// or wss:// URL to connect to.

  • ssl (Hash{Symbol => Object}) (defaults to: {}) —

    Additional keyword arguments for Ronin::Support::Network::SSL.connect.

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments for Ronin::Support::Web::WebSocket::Client#initialize.

Options Hash (ssl:):

  • :version (1, 1.1, 1.2, String, Symbol, nil) —

    The SSL version to use.

  • :verify (Symbol, Boolean) —

    Specifies whether to verify the SSL certificate. May be one of the following:

    • :none
    • :peer
    • :fail_if_no_peer_cert
    • :client_once
  • :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

    The RSA key to use for the SSL context.

  • :key_file (String) —

    The path to the SSL .key file.

  • :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

    The X509 certificate to use for the SSL context.

  • :cert_file (String) —

    The path to the SSL .crt file.

  • :ca_bundle (String) —

    Path to the CA certificate file or directory.

Options Hash (**kwargs):

  • :bind_host (String, nil) —

    The optional host to bind the server socket to.

  • :bind_port (Integer, nil) —

    The optioanl port to bind the server socket to. If not specified, it will default to the port of the URL.

Yields:

  • (websocket) —

    If a block is given, then it will be passed the WebSocket connection. Once the block has returned, the WebSocket connection will be closed.

Yield Parameters:

  • websocket (Client) —

    The WebSocket connection.

Returns:

  • (Client) —

    The WebSocket connection.



145
146
147
148
149
150
151
152
153
154
 
# File 'lib/ronin/support/web/websocket.rb', line 145

def self.connect(url, ssl: {}, **kwargs)
  client = Client.new(url, ssl: ssl, **kwargs)

  if block_given?
    yield client
    client.close
  else
    client
  end
end

.connect_and_send(data, url, type: :text, ssl: {}, **kwargs) {|websocket| ... } ⇒ Client

Connects to the WebSocket and sends the data.

Parameters:

  • data (String) —

    The data to send to the WebSocet.

  • url (String, URI::WS, URI::WSS) —

    The ws:// or wss:// URL to connect to.

  • type (:text, :binary, :ping, :pong, :close) (defaults to: :text) —

    The data frame type.

  • ssl (Hash{Symbol => Object}) (defaults to: {}) —

    Additional keyword arguments for Ronin::Support::Network::SSL.connect.

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments for Ronin::Support::Web::WebSocket::Client#initialize.

Options Hash (ssl:):

  • :version (1, 1.1, 1.2, String, Symbol, nil) —

    The SSL version to use.

  • :verify (Symbol, Boolean) —

    Specifies whether to verify the SSL certificate. May be one of the following:

    • :none
    • :peer
    • :fail_if_no_peer_cert
    • :client_once
  • :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

    The RSA key to use for the SSL context.

  • :key_file (String) —

    The path to the SSL .key file.

  • :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

    The X509 certificate to use for the SSL context.

  • :cert_file (String) —

    The path to the SSL .crt file.

  • :ca_bundle (String) —

    Path to the CA certificate file or directory.

Options Hash (**kwargs):

  • :bind_host (String, nil) —

    The optional host to bind the server socket to.

  • :bind_port (Integer, nil) —

    The optioanl port to bind the server socket to. If not specified, it will default to the port of the URL.

Yields:

  • (websocket) —

    If a block is given, then it will be passed the WebSocket connection. Once the block has returned, the WebSocket connection will be closed.

Yield Parameters:

  • websocket (Client) —

    The WebSocket connection.

Returns:

  • (Client) —

    The WebSocket connection.



190
191
192
193
194
195
196
 
# File 'lib/ronin/support/web/websocket.rb', line 190

def self.connect_and_send(data,url, type: :text, ssl: {}, **kwargs)
  client = connect(url, ssl: ssl, **kwargs)
  client.send(data, type: type)

  yield client if block_given?
  return client
end

.open?(url, ssl: {}, **kwargs) ⇒ Boolean?

Tests whether the WebSocket is open.

Parameters:

  • url (String, URI::WS, URI::WSS) —

    The ws:// or wss:// URL to connect to.

  • ssl (Hash{Symbol => Object}) (defaults to: {}) —

    Additional keyword arguments for Ronin::Support::Network::SSL.connect.

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments for Ronin::Support::Web::WebSocket::Client#initialize.

Options Hash (ssl:):

  • :version (1, 1.1, 1.2, String, Symbol, nil) —

    The SSL version to use.

  • :verify (Symbol, Boolean) —

    Specifies whether to verify the SSL certificate. May be one of the following:

    • :none
    • :peer
    • :fail_if_no_peer_cert
    • :client_once
  • :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

    The RSA key to use for the SSL context.

  • :key_file (String) —

    The path to the SSL .key file.

  • :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

    The X509 certificate to use for the SSL context.

  • :cert_file (String) —

    The path to the SSL .crt file.

  • :ca_bundle (String) —

    Path to the CA certificate file or directory.

Options Hash (**kwargs):

  • :bind_host (String, nil) —

    The optional host to bind the server socket to.

  • :bind_port (Integer, nil) —

    The optioanl port to bind the server socket to. If not specified, it will default to the port of the URL.

Returns:

  • (Boolean, nil) —

    Specifies whether the WebSocket is open. If the connection was not accepted, nil will be returned.



94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/ronin/support/web/websocket.rb', line 94

def self.open?(url, ssl: {}, **kwargs)
  uri  = URI(url)
  host = uri.host
  port = uri.port

  case uri.scheme
  when 'ws'
    Support::Network::TCP.open?(host,port,**kwargs)
  when 'wss'
    Support::Network::SSL.open?(host,port,**kwargs,**ssl)
  else
    raise(ArgumentError,"unsupported WebSocket URI scheme: #{url.inspect}")
  end
end

.send(data, url, type: :text, ssl: {}, **kwargs) ⇒ true

Connects to the WebSocket, sends the data, and closes the connection.

Parameters:

  • data (String) —

    The data to send to the WebSocet.

  • url (String, URI::WS, URI::WSS) —

    The ws:// or wss:// URL to connect to.

  • type (:text, :binary, :ping, :pong, :close) (defaults to: :text) —

    The data frame type.

  • ssl (Hash{Symbol => Object}) (defaults to: {}) —

    Additional keyword arguments for Ronin::Support::Network::SSL.connect.

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments for Ronin::Support::Web::WebSocket::Client#initialize.

Options Hash (ssl:):

  • :version (1, 1.1, 1.2, String, Symbol, nil) —

    The SSL version to use.

  • :verify (Symbol, Boolean) —

    Specifies whether to verify the SSL certificate. May be one of the following:

    • :none
    • :peer
    • :fail_if_no_peer_cert
    • :client_once
  • :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

    The RSA key to use for the SSL context.

  • :key_file (String) —

    The path to the SSL .key file.

  • :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

    The X509 certificate to use for the SSL context.

  • :cert_file (String) —

    The path to the SSL .crt file.

  • :ca_bundle (String) —

    Path to the CA certificate file or directory.

Options Hash (**kwargs):

  • :bind_host (String, nil) —

    The optional host to bind the server socket to.

  • :bind_port (Integer, nil) —

    The optioanl port to bind the server socket to. If not specified, it will default to the port of the URL.

Returns:

  • (true) 


223
224
225
226
227
228
229
 
# File 'lib/ronin/support/web/websocket.rb', line 223

def self.send(data,url, type: :text, ssl: {}, **kwargs)
  connect(url, ssl: ssl, **kwargs) do |client|
    client.send(data, type: type)
  end

  return true
end

.server(url, ssl: {}, **kwargs) {|server| ... } ⇒ Server

Starts a WebSocket server.

Parameters:

  • url (String, URI::WS, URI::WSS) —

    The ws:// or wss:// URL to connect to.

  • ssl (Hash{Symbol => Object}) (defaults to: {}) —

    Additional keyword arguments for Ronin::Support::Network::SSL.server.

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments for Ronin::Support::Web::WebSocket::Server#initialize.

Options Hash (ssl:):

  • :version (1, 1.1, 1.2, String, Symbol, nil) —

    The SSL version to use.

  • :verify (Symbol, Boolean) —

    Specifies whether to verify the SSL certificate. May be one of the following:

    • :none
    • :peer
    • :fail_if_no_peer_cert
    • :client_once
  • :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

    The RSA key to use for the SSL context.

  • :key_file (String) —

    The path to the SSL .key file.

  • :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

    The X509 certificate to use for the SSL context.

  • :cert_file (String) —

    The path to the SSL .crt file.

  • :ca_bundle (String) —

    Path to the CA certificate file or directory.

Options Hash (**kwargs):

  • :bind_host (String, nil) —

    The optional host to bind the server socket to.

  • :bind_port (Integer, nil) —

    The optioanl port to bind the server socket to. If not specified, it will default to the port of the URL.

  • :backlog (Integer) — default: 5 —

    The maximum backlog of pending connections.

Yields:

  • (server) —

    If a block is given, then it will be passed the WebSocket server. Once the block has returned, the WebSocket server will be closed.

Yield Parameters:

  • server (Server) —

    The WebSocket server.

Returns:

  • (Server) —

    The WebSocket server.



271
272
273
274
275
276
277
278
279
280
 
# File 'lib/ronin/support/web/websocket.rb', line 271

def self.server(url, ssl: {}, **kwargs)
  server = Server.new(url, ssl: ssl, **kwargs)

  if block_given?
    yield server
    server.close
  else
    server
  end
end

.server_loop(url, ssl: {}, **kwargs) {|client| ... } ⇒ nil

Creates a new WebSocket server listening on a given host and port, accepting clients in a loop.

Parameters:

  • url (String, URI::WS, URI::WSS) —

    The ws:// or wss:// URL to connect to.

  • ssl (Hash{Symbol => Object}) (defaults to: {}) —

    Additional keyword arguments for Ronin::Support::Network::SSL.server.

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments for Ronin::Support::Web::WebSocket::Server#initialize.

Options Hash (ssl:):

  • :version (1, 1.1, 1.2, String, Symbol, nil) —

    The SSL version to use.

  • :verify (Symbol, Boolean) —

    Specifies whether to verify the SSL certificate. May be one of the following:

    • :none
    • :peer
    • :fail_if_no_peer_cert
    • :client_once
  • :key (Crypto::Key::RSA, OpenSSL::PKey::RSA, nil) —

    The RSA key to use for the SSL context.

  • :key_file (String) —

    The path to the SSL .key file.

  • :cert (Crypto::Cert, OpenSSL::X509::Certificate, nil) —

    The X509 certificate to use for the SSL context.

  • :cert_file (String) —

    The path to the SSL .crt file.

  • :ca_bundle (String) —

    Path to the CA certificate file or directory.

Options Hash (**kwargs):

  • :bind_host (String, nil) —

    The optional host to bind the server socket to.

  • :bind_port (Integer, nil) —

    The optioanl port to bind the server socket to. If not specified, it will default to the port of the URL.

  • :backlog (Integer) — default: 5 —

    The maximum backlog of pending connections.

Yields:

  • (client) —

    The given block will be passed the newly connected WebSocket client. After the block has finished, the WebSocket client will be closed.

Yield Parameters:

Returns:

  • (nil) 


310
311
312
313
314
315
316
317
318
319
 
# File 'lib/ronin/support/web/websocket.rb', line 310

def self.server_loop(url, ssl: {}, **kwargs)
  server(url, ssl: ssl, **kwargs) do |server|
    loop do
      client = server.accept

      yield client if block_given?
      client.close
    end
  end
end