ronin-support-web 0.1.0.rc1

data/lib/ronin/support/web/websocket/server.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+#
+# ronin-support-web - A web support library for ronin-rb.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-support-web is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support-web is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support-web.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/web/websocket/socket'
+require 'ronin/support/web/websocket/url_methods'
+require 'ronin/support/network/tcp'
+require 'ronin/support/network/ssl'
+
+require 'websocket'
+
+module Ronin
+  module Support
+    module Web
+      module WebSocket
+        #
+        # Represents a WebSocket server.
+        #
+        class Server
+
+          include URLMethods
+
+          # The underlying server socket.
+          #
+          # @return [TCPServer, OpenSSL::SSL::SSLServer]
+          attr_reader :socket
+
+          #
+          # Initializes the WebSocket server.
+          #
+          # @param [String, URI::WS, URI::WSS] url
+          #   The `ws://` or `wss://` URL.
+          #
+          # @param [String, nil] bind_host
+          #   The optional host to bind the server socket to.
+          #
+          # @param [Integer, nil] bind_port
+          #   The optioanl port to bind the server socket to. If not specified,
+          #   it will default to the port of the URL.
+          #
+          # @param [Integer] backlog
+          #   The maximum backlog of pending connections.
+          #
+          # @param [Hash{Symbol => Object}] ssl
+          #   Additional keyword arguments for
+          #   `Ronin::Support::Network::SSL.server`.
+          #
+          # @option ssl [1, 1.1, 1.2, String, Symbol, nil] :version
+          #   The SSL version to use.
+          #
+          # @option ssl [Symbol, Boolean] :verify
+          #   Specifies whether to verify the SSL certificate.
+          #   May be one of the following:
+          #
+          #   * `:none`
+          #   * `:peer`
+          #   * `:fail_if_no_peer_cert`
+          #   * `:client_once`
+          #
+          # @option ssl [Crypto::Key::RSA, OpenSSL::PKey::RSA, nil] :key
+          #   The RSA key to use for the SSL context.
+          #
+          # @option ssl [String] :key_file
+          #   The path to the SSL `.key` file.
+          #
+          # @option ssl [Crypto::Cert, OpenSSL::X509::Certificate, nil] :cert
+          #   The X509 certificate to use for the SSL context.
+          #
+          # @option ssl [String] :cert_file
+          #   The path to the SSL `.crt` file.
+          #
+          # @option ssl [String] :ca_bundle
+          #   Path to the CA certificate file or directory.
+          #
+          def initialize(url, bind_host: nil,
+                              bind_port: nil,
+                              backlog:   5,
+                              ssl:       {})
+            super(url)
+
+            @bind_host = bind_host
+            @bind_port = bind_port || @port
+
+            @socket = case @url.scheme
+                      when 'ws'
+                        Support::Network::TCP.server(
+                          host:    @bind_host,
+                          port:    @bind_port,
+                          backlog: backlog
+                        )
+                      when 'wss'
+                        Support::Network::SSL.server(
+                          host:    @bind_host,
+                          port:    @bind_port,
+                          backlog: backlog,
+                          **ssl
+                        )
+                      else
+                        raise(ArgumentError,"unsupported websocket scheme: #{url}")
+                      end
+          end
+
+          #
+          # Sets the connection backlog for the server socket.
+          #
+          # @param [Integer] backlog
+          #   The number of pending connection to allow.
+          #
+          def listen(backlog)
+            @socket.listen(backlog)
+          end
+
+          #
+          # Accepts a new WebSocket connection.
+          #
+          # @return [Client]
+          #   The new WebSocket connection to the server.
+          #
+          def accept
+            Client.new(@url,@socket.accept)
+          end
+
+          #
+          # Closes the WebSocket server's socket.
+          #
+          # @api public
+          #
+          def close
+            @socket.close
+          end
+
+          #
+          # Determines if the WebSocket server is closed?
+          #
+          # @return [Boolean]
+          #
+          # @api public
+          #
+          def closed?
+            @socket.closed?
+          end
+
+          #
+          # Represents a WebSocket client connected to the Websocket server.
+          #
+          class Client < Socket
+
+            #
+            # Initializes a WebSocket server client.
+            #
+            # @param [URI::WS, URI::WSS] url
+            #   The WebSocket server's `ws://` or `wss://` URL.
+            #
+            # @param [TCPSocket, OpenSSL::SSL::SSLSocket] socket
+            #   The client's connection socket.
+            #
+            # @api private
+            #
+            def initialize(url,socket)
+              super()
+
+              @url    = url
+              @socket = socket
+
+              receive_handshake!
+
+              set_frame_classes(
+                ::WebSocket::Frame::Incoming::Server,
+                ::WebSocket::Frame::Outgoing::Server
+              )
+            end
+
+            #
+            # Receives the WebSocket handshake.
+            #
+            # @api private
+            #
+            def receive_handshake!(**kwargs)
+              @handshake = ::WebSocket::Handshake::Server.new(
+                url: @url.to_s, **kwargs
+              )
+
+              @handshake << @socket.readpartial(1024) until @handshake.finished?
+
+              if @handshake.valid?
+                @socket.write(@handshake)
+              end
+            end
+
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/web/websocket/socket.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+#
+# ronin-support-web - A web support library for ronin-rb.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-support-web is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support-web is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support-web.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/web/websocket/url_methods'
+
+module Ronin
+  module Support
+    module Web
+      module WebSocket
+        #
+        # Base class for all WebSockets.
+        #
+        # @abstract
+        #
+        # @api private
+        #
+        class Socket
+
+          # The underlying socket.
+          #
+          # @return [TCPSocket, OpenSSL::SSL::SSLSocket]
+          attr_reader :socket
+
+          # The WebSocket handshake information.
+          #
+          # @return [::WebSocket::Handshake::Client, WebSocket::Handshake::Server]
+          attr_reader :handshake
+
+          #
+          # Indicates whether the handshake has finished.
+          #
+          # @return [Boolean]
+          #
+          # @api public
+          #
+          def handshake_finished?
+            @handshake.finished?
+          end
+
+          #
+          # Indicates whether the handshake was valid.
+          #
+          # @return [Boolean]
+          #
+          # @api public
+          #
+          def handshake_valid?
+            @handshake.valid?
+          end
+
+          #
+          # Sends a data frame.
+          #
+          # @param [#to_s] data
+          #   The data to send.
+          #
+          # @param [:text, :binary, :ping, :pong, :close] type
+          #   The data frame type.
+          #
+          # @api public
+          #
+          def send_frame(data, type: :text)
+            outgoing_frame = @outgoing_frame_class.new(
+                               version: @handshake.version,
+                               data:    data,
+                               type:    type
+                             )
+
+            @socket.write(outgoing_frame.to_s)
+          end
+
+          #
+          # Sends a data frame.
+          #
+          # @param [#to_s] data
+          #   The data to send.
+          #
+          # @param [Hash{Symbol => Object}] kwargs
+          #   Additional keyword arguments for {#send_frame}.
+          #
+          # @option kwargs [:text, :binary, :ping, :pong, :close] :type (:text)
+          #   The data frame type.
+          #
+          # @api public
+          #
+          # @see #send_frame
+          #
+          def send(data,**kwargs)
+            send_frame(data,**kwargs)
+          end
+
+          #
+          # Receives a data frame from the WebSocket.
+          #
+          # @return [WebSocket::Frame::Incoming::Client,
+          #          WebSocket::Frame::Incoming::Server]
+          #   The received websocket data frame.
+          #
+          # @api public
+          #
+          def recv_frame
+            frame = @incoming_frame_class.new(version: @handshake.version)
+
+            begin
+              # read data into the input frame
+              frame << @socket.readpartial(1024)
+            rescue EOFError
+              return nil
+            end
+
+            return frame.next
+          end
+
+          #
+          # Receives a data frame.
+          #
+          # @return [String, nil]
+          #
+          # @api public
+          #
+          def recv
+            data = recv_frame.data
+            data unless data.empty?
+          end
+
+          #
+          # Closes the socket.
+          #
+          # @api public
+          #
+          def close
+            @socket.close
+          end
+
+          #
+          # Determines if the socket is closed.
+          #
+          # @return [Boolean]
+          #
+          # @api public
+          #
+          def closed?
+            @socket.closed?
+          end
+
+          private
+
+          #
+          # Sets the frame classes to use.
+          #
+          # @param [Class<WebSocket::Frame::Incoming::Client>,
+          #         Class<WebSocket::Frame::Incoming::Server>] incoming_frame_class
+          #
+          # @param [Class<WebSocket::Frame::Outgoing::Client>,
+          #         Class<WebSocket::Frame::Outgoing::Server>] outgoing_frame_class
+          #
+          # @api private
+          #
+          def set_frame_classes(incoming_frame_class,outgoing_frame_class)
+            @incoming_frame_class = incoming_frame_class
+            @outgoing_frame_class = outgoing_frame_class
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/web/websocket/url_methods.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+#
+# ronin-support-web - A web support library for ronin-rb.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-support-web is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support-web is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support-web.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'uri'
+
+module Ronin
+  module Support
+    module Web
+      module WebSocket
+        #
+        # Mixin which accepts and parses a `ws://` or `wss://` URL.
+        #
+        # @api private
+        #
+        module URLMethods
+          # The parsed `ws://` or `wss://` URI.
+          #
+          # @return [URI::WS, URI::WSS]
+          #
+          # @api public
+          attr_reader :url
+
+          # The websocket host name.
+          #
+          # @return [String]
+          #
+          # @api public
+          attr_reader :host
+
+          # The websocket port.
+          #
+          # @return [Integer]
+          #
+          # @api public
+          attr_reader :port
+
+          # The websocket port.
+          #
+          # @return [String]
+          #
+          # @api public
+          attr_reader :path
+
+          #
+          # Sets the {#url}.
+          #
+          # @param [String] url
+          #   The `ws://` or `wss://` URL.
+          #
+          # @api public
+          #
+          def initialize(url)
+            @url  = URI(url)
+            @host = @url.host
+            @port = @url.port
+            @path = @url.path
+            @ssl  = (@url.scheme == 'wss')
+          end
+
+          #
+          # Determines whether the websocket uses SSL/TLS.
+          #
+          # @return [Boolean]
+          #
+          # @api public
+          #
+          def ssl?
+            @ssl
+          end
+        end
+      end
+    end
+  end
+end