steam-condenser 0.14.0 → 1.0.1

data/lib/steam/servers/goldsrc_server.rb

@@ -4,6 +4,7 @@
 # Copyright (c) 2008-2011, Sebastian Staudt
 
 require 'steam/servers/game_server'
+require 'steam/servers/master_server'
 require 'steam/sockets/goldsrc_socket'
 
 # This class represents a GoldSrc game server and can be used to query
@@ -19,13 +20,21 @@ class GoldSrcServer
 
   include GameServer
 
+  # Returns a master server instance for the default master server for GoldSrc
+  # games
+  #
+  # @return [MasterServer] The GoldSrc master server
+  def self.master
+    MasterServer.new *MasterServer::GOLDSRC_MASTER_SERVER
+  end
+
   # Creates a new instance of a GoldSrc server object
   #
   # @param [String] address Either an IP address, a DNS name or one of them
   #        combined with the port number. If a port number is given, e.g.
   #        'server.example.com:27016' it will override the second argument.
   # @param [Fixnum] port The port the server is listening on
-  # @raise [SteamCondenserException] if an host name cannot be resolved
+  # @raise [SteamCondenserError] if an host name cannot be resolved
   # @param [Boolean] is_hltv HLTV servers need special treatment, so this is
   #        used to determine if the server is a HLTV server
   def initialize(address, port = 27015, is_hltv = false)

data/lib/steam/servers/master_server.rb

@@ -3,6 +3,7 @@
 #
 # Copyright (c) 2008-2011, Sebastian Staudt
 
+require 'errors/timeout_error'
 require 'steam/packets/a2m_get_servers_batch2_packet'
 require 'steam/packets/c2m_checkmd5_packet'
 require 'steam/packets/s2m_heartbeat2_packet'
@@ -21,6 +22,9 @@ class MasterServer
 
   include Server
 
+  # The default number of allowed retries
+  @@retries = 3
+
   # The master server address to query for GoldSrc game servers
   GOLDSRC_MASTER_SERVER = 'hl1master.steampowered.com', 27010
 
@@ -54,13 +58,21 @@ class MasterServer
   # The region code for the whole world
   REGION_ALL = 0xFF
 
+  # Sets the number of consecutive requests that may fail, before getting
+  # the server list is cancelled (default: 3)
+  #
+  # @param [Fixnum] The number of allowed retries
+  def self.retries=(retries)
+    @@retries = retries
+  end
+
   # Request a challenge number from the master server.
   #
   # This is used for further communication with the master server.
   #
   # @note Please note that this is **not** needed for finding servers using
   #       {#servers}.
-  # @return The challenge number from the master server
+  # @return [Fixnum] The challenge number from the master server
   # @see #send_heartbeat
   def challenge
     failsafe do
@@ -80,8 +92,8 @@ class MasterServer
   #
   # Filtering:
   # Instead of filtering the results sent by the master server locally, you
-  # should at least use the following filters to narrow down the results sent by
-  # the master server.
+  # should at least use the following filters to narrow down the results sent
+  # by the master server.
   #
   # Available filters:
   #
@@ -99,33 +111,42 @@ class MasterServer
   # @param [Fixnum] region_code The region code to specify a location of the
   #        game servers
   # @param [String] filters The filters that game servers should match
+  # @param [Boolean] force Return a list of servers even if an error occured
+  #        while fetching them from the master server
+  # @raise [SteamCondenser::TimeoutError] if too many timeouts occur while
+  #        querying the master server
   # @return [Array<Array<String>>] A list of game servers matching the given
   #         region and filters
   # @see A2M_GET_SERVERS_BATCH2_Packet
-  def servers(region_code = MasterServer::REGION_ALL, filters = '')
+  # @see MasterServer.retries=
+  def servers(region_code = MasterServer::REGION_ALL, filters = '', force = false)
     fail_count     = 0
     finished       = false
     current_server = '0.0.0.0:0'
     server_array   = []
 
-    failsafe do
-      begin
-        @socket.send A2M_GET_SERVERS_BATCH2_Packet.new(region_code, current_server, filters)
+    begin
+      failsafe do
         begin
-          servers = @socket.reply.servers
-          servers.each do |server|
-            if server == '0.0.0.0:0'
-              finished = true
-            else
-              current_server = server
-              server_array << server.split(':')
+          @socket.send A2M_GET_SERVERS_BATCH2_Packet.new(region_code, current_server, filters)
+          begin
+            servers = @socket.reply.servers
+            servers.each do |server|
+              if server == '0.0.0.0:0'
+                finished = true
+              else
+                current_server = server
+                server_array << server.split(':')
+              end
             end
+            fail_count = 0
+          rescue SteamCondenser::TimeoutError
+            raise $! if (fail_count += 1) == @@retries
           end
-          fail_count = 0
-        rescue TimeoutException
-          raise $! if (fail_count += 1) == 3
-        end
-      end while !finished
+        end while !finished
+      end
+    rescue SteamCondenser::TimeoutError
+      raise $! unless force
     end
 
     server_array
@@ -136,7 +157,7 @@ class MasterServer
   # This can be used to check server versions externally.
   #
   # @param [Hash<Symbol, Object>] The data to send with the heartbeat request
-  # @raise [SteamCondenserException] if heartbeat data is missing the
+  # @raise [SteamCondenserError] if heartbeat data is missing the
   #        challenge number or the reply cannot be parsed
   # @return [Array<SteamPacket>] Zero or more reply packets from the server.
   #         Zero means either the heartbeat was accepted by the master or there
@@ -150,7 +171,7 @@ class MasterServer
       reply_packets = []
       begin
         loop { reply_packets << @socket.reply }
-      rescue TimeoutException
+      rescue SteamCondenser::TimeoutError
       end
     end
 

data/lib/steam/servers/server.rb

@@ -30,7 +30,7 @@ module Server
   #        'server.example.com:27016' it will override the second argument.
   # @param [Fixnum] port The port the server is listening on
   # @see init_socket
-  # @raise [SteamCondenserException] if an host name cannot be resolved
+  # @raise [SteamCondenserError] if an host name cannot be resolved
   def initialize(address, port = nil)
     address = address.to_s
     address, port = address.split(':', 2) if address.include? ':'
@@ -79,10 +79,9 @@ module Server
 
   # Execute an action in the context of this server's current IP address
   #
-  # Any failure, i.e. an exception, will cause the IP to rotate to the next IP
-  # in the server's IP list and the execution will be repeated for the next IP
-  # address. If the IP rotation reaches the end of the list, the exception will
-  # be reraised.
+  # Any failure will cause the IP to rotate to the next IP in the server's IP
+  # list and the execution will be repeated for the next IP address. If the IP
+  # rotation reaches the end of the list, the error will be reraised.
   #
   # @param [Proc] proc The action to be executed in a failsafe way
   # @see #rotate_ip

data/lib/steam/servers/source_server.rb

@@ -3,12 +3,13 @@
 #
 # Copyright (c) 2008-2011, Sebastian Staudt
 
-require 'exceptions/rcon_no_auth_exception'
+require 'errors/rcon_no_auth_error'
 require 'steam/packets/rcon/rcon_auth_request'
 require 'steam/packets/rcon/rcon_auth_response'
 require 'steam/packets/rcon/rcon_exec_request'
 require 'steam/packets/rcon/rcon_terminator'
 require 'steam/servers/game_server'
+require 'steam/servers/master_server'
 require 'steam/sockets/rcon_socket'
 require 'steam/sockets/source_socket'
 
@@ -25,6 +26,14 @@ class SourceServer
 
   include GameServer
 
+  # Returns a master server instance for the default master server for Source
+  # games
+  #
+  # @return [MasterServer] The Source master server
+  def self.master
+    MasterServer.new *MasterServer::GOLDSRC_MASTER_SERVER
+  end
+
   # Creates a new instance of a server object representing a Source server,
   # i.e. SrcDS instance
   #
@@ -32,7 +41,7 @@ class SourceServer
   #        combined with the port number. If a port number is given, e.g.
   #        'server.example.com:27016' it will override the second argument.
   # @param [Fixnum] port The port the server is listening on
-  # @raise [SteamCondenserException] if an host name cannot be resolved
+  # @raise [SteamCondenserError] if an host name cannot be resolved
   def initialize(address, port = 27015)
     super
   end
@@ -50,6 +59,7 @@ class SourceServer
   #
   # @param [String] password The RCON password of the server
   # @return [Boolean] whether authentication was successful
+  # @see #rcon_authenticated?
   # @see #rcon_exec
   def rcon_auth(password)
     @rcon_request_id = rand 2**16
@@ -58,9 +68,9 @@ class SourceServer
     @rcon_socket.reply
     reply = @rcon_socket.reply
 
-    raise RCONNoAuthException.new if reply.request_id == -1
+    raise RCONNoAuthError if reply.request_id == -1
 
-    reply.request_id == @rcon_request_id
+    @rcon_authenticated = reply.request_id == @rcon_request_id
   end
 
   # Remotely executes a command on the server via RCON
@@ -69,13 +79,18 @@ class SourceServer
   # @return [String] The output of the executed command
   # @see #rcon_auth
   def rcon_exec(command)
+    raise RCONNoAuthError unless @rcon_authenticated
+
     @rcon_socket.send RCONExecRequest.new(@rcon_request_id, command)
     @rcon_socket.send RCONTerminator.new(@rcon_request_id)
 
     response = ''
     begin
       response_packet = @rcon_socket.reply
-      raise RCONNoAuthException.new if response_packet.is_a? RCONAuthResponse
+      if response_packet.is_a? RCONAuthResponse
+        @rcon_authenticated = false
+        raise RCONNoAuthError
+      end
       response << response_packet.response
     end while response.length == 0 || response_packet.response.size > 0
 

data/lib/steam/sockets/goldsrc_socket.rb

@@ -1,52 +1,65 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
 # Copyright (c) 2008-2011, Sebastian Staudt
 
-require 'stringio_additions'
-require 'exceptions/rcon_ban_exception'
-require 'exceptions/rcon_no_auth_exception'
+require 'core_ext/stringio'
+require 'errors/rcon_ban_error'
+require 'errors/rcon_no_auth_error'
+require 'errors/timeout_error'
 require 'steam/packets/steam_packet_factory'
 require 'steam/packets/rcon/rcon_goldsrc_request'
 require 'steam/sockets/steam_socket'
 
-# The SourceSocket class is a sub class of SteamSocket respecting the
-# specifications of the Source query protocol.
+# This class represents a socket used to communicate with game servers based on
+# the GoldSrc engine (e.g. Half-Life, Counter-Strike)
+#
+# @author Sebastian Staudt
 class GoldSrcSocket
 
   include SteamSocket
 
+  # Creates a new socket to communicate with the server on the given IP address
+  # and port
+  #
+  # @param [String] ipaddress Either the IP address or the DNS name of the
+  #        server
+  # @param [Fixnum] port_number The port the server is listening on
+  # @param [Boolean] is_hltv `true` if the target server is a HTLV instance.
+  #        HLTV behaves slightly different for RCON commands, this flag
+  #        increases compatibility.
   def initialize(ipaddress, port_number = 27015, is_hltv = false)
     super ipaddress, port_number
+
     @is_hltv = is_hltv
   end
 
-  # Reads a packet from the channel. The Source query protocol specifies a
-  # maximum packet size of 1400 byte. Greater packets will be split over several
-  # UDP packets. This method reassembles split packets into single packet
-  # objects.
+  # Reads a packet from the socket
+  #
+  # The Source query protocol specifies a maximum packet size of 1,400 bytes.
+  # Bigger packets will be split over several UDP packets. This method
+  # reassembles split packets into single packet objects.
+  #
+  # @return [SteamPacket] The packet replied from the server
   def reply
-    bytes_read = receive_packet 1400
+    receive_packet 1400
 
     if @buffer.long == 0xFFFFFFFE
       split_packets = []
       begin
-        # Parsing of split packet headers
         request_id = @buffer.long
         packet_number_and_count = @buffer.byte
         packet_count = packet_number_and_count & 0xF
         packet_number = (packet_number_and_count >> 4) + 1
 
-        # Caching of split packet data
         split_packets[packet_number - 1] = @buffer.get
 
         puts "Received packet #{packet_number} of #{packet_count} for request ##{request_id}" if $DEBUG
 
-        # Receiving the next packet
         if split_packets.size < packet_count
           begin
             bytes_read = receive_packet
-          rescue TimeoutException
+          rescue SteamCondenser::TimeoutError
             bytes_read = 0
           end
         else
@@ -64,15 +77,25 @@ class GoldSrcSocket
     packet
   end
 
+  # Executes the given command on the server via RCON
+  #
+  # @param [String] password The password to authenticate with the server
+  # @param [String] command The command to execute on the server
+  # @raise [RCONBanError] if the IP of the local machine has been banned on the
+  #        game server
+  # @raise [RCONNoAuthError] if the password is incorrect
+  # @return [RCONGoldSrcResponse] The response replied by the server
+  # @see #rcon_challenge
+  # @see #rcon_send
   def rcon_exec(password, command)
-    rcon_challenge if @rcon_challenge.nil? or @is_hltv
+    rcon_challenge if @rcon_challenge.nil? || @is_hltv
 
     rcon_send "rcon #{@rcon_challenge} #{password} #{command}"
     rcon_send "rcon #{@rcon_challenge} #{password}"
     if @is_hltv
       begin
         response = reply.response
-      rescue TimeoutException
+      rescue SteamCondenser::TimeoutError
         response = ''
       end
     else
@@ -80,9 +103,9 @@ class GoldSrcSocket
     end
 
     if response.strip == 'Bad rcon_password.'
-      raise RCONNoAuthException
+      raise RCONNoAuthError
     elsif response.strip == 'You have been banned from this server.'
-      raise RCONBanException
+      raise RCONBanError
     end
 
     begin
@@ -93,17 +116,25 @@ class GoldSrcSocket
     response
   end
 
+  # Requests a challenge number from the server to be used for further requests
+  #
+  # @raise [RCONBanError] if the IP of the local machine has been banned on the
+  #        game server
+  # @see #rcon_send
   def rcon_challenge
     rcon_send 'challenge rcon'
     response = reply.response.strip
 
-    if response == 'You have been banned from this server.'
-      raise RCONBanException
+    if response.strip == 'You have been banned from this server.'
+      raise RCONBanError
     end
 
     @rcon_challenge = response[14..-1]
   end
 
+  # Wraps the given command in a RCON request packet and send it to the server
+  #
+  # @param [String] command The RCON command to send to the server
   def rcon_send(command)
     send RCONGoldSrcRequest.new(command)
   end

data/lib/steam/sockets/master_server_socket.rb

@@ -1,18 +1,28 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
-# Copyright (c) 2008-2010, Sebastian Staudt
+# Copyright (c) 2008-2011, Sebastian Staudt
 
+require 'errors/packet_format_error'
 require 'steam/sockets/steam_socket'
 
+# This class represents a socket used to communicate with master servers
+#
+# @author Sebastian Staudt
 class MasterServerSocket
 
   include SteamSocket
 
+  # Reads a single packet from the socket
+  #
+  # @raise [PacketFormatError] if the packet has the wrong format
+  # @return [SteamPacket] The packet replied from the server
   def reply
     receive_packet 1500
 
-    raise Exception.new("Master query response has wrong packet header.") unless @buffer.long == 0xFFFFFFFF
+    unless @buffer.long == 0xFFFFFFFF
+      raise PacketFormatError, 'Master query response has wrong packet header.'
+    end
 
     SteamPacketFactory.packet_from_data(@buffer.get)
   end

data/lib/steam/sockets/rcon_socket.rb

@@ -1,5 +1,5 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
 #
 # Copyright (c) 2008-2011, Sebastian Staudt
 
@@ -7,15 +7,29 @@ require 'ipaddr'
 require 'socket'
 require 'timeout'
 
-require 'exceptions/rcon_ban_exception'
+require 'errors/rcon_ban_error'
+require 'errors/timeout_error'
 require 'steam/packets/rcon/rcon_packet'
 require 'steam/packets/rcon/rcon_packet_factory'
 require 'steam/sockets/steam_socket'
 
+# This class represents a socket used for RCON communication with game servers
+# based on the Source engine (e.g. Team Fortress 2, Counter-Strike: Source)
+#
+# The Source engine uses a stateful TCP connection for RCON communication and
+# uses an additional socket of this type to handle RCON requests.
+#
+# @author Sebastian Staudt
 class RCONSocket
 
   include SteamSocket
 
+  # Creates a new TCP socket to communicate with the server on the given IP
+  # address and port
+  #
+  # @param [String, IPAddr] ip Either the IP address or the DNS name of the
+  #        server
+  # @param [Fixnum] port The port the server is listening on
   def initialize(ip, port)
     ip = IPSocket.getaddress(ip) unless ip.is_a? IPAddr
 
@@ -24,27 +38,46 @@ class RCONSocket
     @socket = nil
   end
 
-  # Closes the underlying socket if it exists
+  # Closes the underlying TCP socket if it exists
+  #
+  # SteamSocket#close
   def close
     super unless @socket.nil?
   end
 
+  # Connects a new TCP socket to the server
+  #
+  # @raise [SteamCondenser::TimeoutError] if the connection could not be
+  #        established
   def connect
     begin
       timeout(@@timeout / 1000.0) { @socket = TCPSocket.new @ip, @port }
     rescue Timeout::Error
-      raise TimeoutException
+      raise SteamCondenser::TimeoutError
     end
   end
 
+  # Sends the given RCON packet to the server
+  #
+  # @param [RCONPacket] data_packet The RCON packet to send to the server
+  # @see #connect
   def send(data_packet)
     connect if @socket.nil? || @socket.closed?
 
     super
   end
 
+  # Reads a packet from the socket
+  #
+  # The Source RCON protocol allows packets of an arbitrary sice transmitted
+  # using multiple TCP packets. The data is received in chunks and concatenated
+  # into a single response packet.
+  #
+  # @raise [RCONBanError] if the IP of the local machine has been banned on the
+  #        game server
+  # @return [RCONPacket] The packet replied from the server
   def reply
-    raise RCONBanException if receive_packet(4) == 0
+    raise RCONBanError if receive_packet(4) == 0
 
     @buffer.rewind
     remaining_bytes = @buffer.long