steam-condenser 0.13.1 → 0.14.0

data/lib/steam/servers/goldsrc_server.rb

@@ -1,15 +1,33 @@
-# 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 'steam/servers/game_server'
 require 'steam/sockets/goldsrc_socket'
 
+# This class represents a GoldSrc game server and can be used to query
+# information about and remotely execute commands via RCON on the server
+#
+# A GoldSrc game server is an instance of the Half-Life Dedicated Server (HLDS)
+# running games using Valve's GoldSrc engine, like Half-Life Deathmatch,
+# Counter-Strike 1.6 or Team Fortress Classic.
+#
+# @author Sebastian Staudt
+# @see SourceServer
 class GoldSrcServer
 
   include GameServer
 
+  # 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
+  # @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)
     super address, port
 
@@ -17,15 +35,29 @@ class GoldSrcServer
   end
 
   # Initializes the socket to communicate with the GoldSrc server
+  #
+  # @see GoldSrcSocket
   def init_socket
     @socket = GoldSrcSocket.new @ip_address, @port, @is_hltv
   end
 
+  # Saves the password for authenticating the RCON communication with the
+  # server
+  #
+  # @param [String] password The RCON password of the server
+  # @return [true] GoldSrc's RCON does not preauthenticate connections so this
+  #         method always returns `true`
+  # @see #rcon_exec
   def rcon_auth(password)
     @rcon_password = password
     true
   end
 
+  # Remotely executes a command on the server via RCON
+  #
+  # @param [String] command The command to execute on the server via RCON
+  # @return [String] The output of the executed command
+  # @see #rcon_auth
   def rcon_exec(command)
     @socket.rcon_exec(@rcon_password, command).strip
   end

data/lib/steam/servers/master_server.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
 
@@ -9,35 +9,59 @@ require 'steam/packets/s2m_heartbeat2_packet'
 require 'steam/servers/server'
 require 'steam/sockets/master_server_socket'
 
+# This class represents a Steam master server and can be used to get game
+# servers which are publicly available
+#
+# An intance of this class can be used much like Steam's server browser to get
+# a list of available game servers, including filters to narrow down the search
+# results.
+#
+# @author Sebastian Staudt
 class MasterServer
 
   include Server
 
+  # The master server address to query for GoldSrc game servers
   GOLDSRC_MASTER_SERVER = 'hl1master.steampowered.com', 27010
+
+  # The master server address to query for GoldSrc game servers
   SOURCE_MASTER_SERVER = 'hl2master.steampowered.com', 27011
 
+  # The region code for the US east coast
   REGION_US_EAST_COAST = 0x00
+
+  # The region code for the US west coast
   REGION_US_WEST_COAST = 0x01
+
+  # The region code for South America
   REGION_SOUTH_AMERICA = 0x02
+
+  # The region code for Europe
   REGION_EUROPE = 0x03
+
+  # The region code for Asia
   REGION_ASIA = 0x04
+
+  # The region code for Australia
   REGION_AUSTRALIA = 0x05
+
+  # The region code for the Middle East
   REGION_MIDDLE_EAST = 0x06
-  REGION_AFRICA = 0x07
-  REGION_ALL = 0xFF
 
-  # Creates a new instance of a master server object
-  def initialize(address, port)
-    super
+  # The region code for Africa
+  REGION_AFRICA = 0x07
 
-    @server_array = []
-  end
+  # The region code for the whole world
+  REGION_ALL = 0xFF
 
-  # Request a challenge number from the master server. This is used for further
-  # communication with the master server.
+  # Request a challenge number from the master server.
+  #
+  # This is used for further communication with the master server.
   #
-  # Please note that this is NOT needed for finding servers using the +servers+
-  # method
+  # @note Please note that this is **not** needed for finding servers using
+  #       {#servers}.
+  # @return The challenge number from the master server
+  # @see #send_heartbeat
   def challenge
     failsafe do
       @socket.send C2M_CHECKMD5_Packet.new
@@ -46,19 +70,43 @@ class MasterServer
   end
 
   # Initializes the socket to communicate with the master server
+  #
+  # @see MasterServerSocket
   def init_socket
     @socket = MasterServerSocket.new @ip_address, @port
   end
 
+  # Returns a list of game server matching the given region and filters
+  #
+  # 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.
+  #
+  # Available filters:
+  #
+  # * `\type\d`: Request only dedicated servers
+  # * `\secure\1`: Request only secure servers
+  # * `\gamedir\[mod]`: Request only servers of a specific mod
+  # * `\map\[mapname]`: Request only servers running a specific map
+  # * `\linux\1`: Request only linux servers
+  # * `\emtpy\1`: Request only **non**-empty servers
+  # * `\full\`: Request only servers **not** full
+  # * `\proxy\1`: Request only spectator proxy servers
+  #
+  # @note Receiving all servers from the master server is taking quite some
+  #       time.
+  # @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
+  # @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 = '')
-    update_servers region_code, filters if @server_array.empty?
-    @server_array
-  end
-
-  def update_servers(region_code, filters)
     fail_count     = 0
     finished       = false
     current_server = '0.0.0.0:0'
+    server_array   = []
 
     failsafe do
       begin
@@ -70,7 +118,7 @@ class MasterServer
               finished = true
             else
               current_server = server
-              @server_array << server.split(':')
+              server_array << server.split(':')
             end
           end
           fail_count = 0
@@ -79,16 +127,22 @@ class MasterServer
         end
       end while !finished
     end
+
+    server_array
   end
 
   # Sends a constructed heartbeat to the master server
   #
   # This can be used to check server versions externally.
   #
-  # The reply from the master server – usually zero or more packets. Zero means
-  # either the heartbeat was accepted by the master or there was a timeout. So
-  # usually it's best to repeat a heartbeat a few times when not receiving any
-  # packets.
+  # @param [Hash<Symbol, Object>] The data to send with the heartbeat request
+  # @raise [SteamCondenserException] 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
+  #         was a timeout. So usually it's best to repeat a heartbeat a few
+  #         times when not receiving any packets.
+  # @see S2M_HEARTBEAT2_Packet
   def send_heartbeat(data)
     failsafe do
       @socket.send S2M_HEARTBEAT2_Packet.new(data)

data/lib/steam/servers/server.rb

@@ -7,10 +7,30 @@ require 'socket'
 
 # This module is included by all classes implementing server functionality
 #
-# It provides basic name resolution features.
+# It provides basic name resolution features and the ability to rotate between
+# different IP addresses belonging to a single DNS name.
+#
+# @author Sebastian Staudt
 module Server
 
+  # Returns a list of host names associated with this server
+  #
+  # @return [Array<String>] The host names of this server
+  attr_reader :host_names
+
+  # Returns a list of IP addresses associated with this server
+  #
+  # @return [Array<String>] The IP addresses of this server
+  attr_reader :ip_addresses
+
   # Creates a new server instance with the given address and port
+  #
+  # @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
+  # @see init_socket
+  # @raise [SteamCondenserException] if an host name cannot be resolved
   def initialize(address, port = nil)
     address = address.to_s
     address, port = address.split(':', 2) if address.include? ':'
@@ -33,8 +53,17 @@ module Server
 
   # Rotate this server's IP address to the next one in the IP list
   #
-  # This method will return +true+, if the IP list reached its end. If the list
-  # contains only one IP address, this method will instantly return +true+.
+  # If this method returns `true`, it indicates that all IP addresses have been
+  # used, hinting at the server(s) being unreachable. An appropriate action
+  # should be taken to inform the user.
+  #
+  # Servers with only one IP address will always cause this method to return
+  # `true` and the sockets will not be reinitialized.
+  #
+  # @return [Boolean] `true`, if the IP list reached its end. If the list
+  #         contains only one IP address, this method will instantly return
+  #         `true`
+  # @see #init_socket
   def rotate_ip
     return true if @ip_addresses.size == 1
 
@@ -54,6 +83,9 @@ module Server
   # 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.
+  #
+  # @param [Proc] proc The action to be executed in a failsafe way
+  # @see #rotate_ip
   def failsafe(&proc)
     begin
       proc.call
@@ -63,4 +95,11 @@ module Server
     end
   end
 
+  # Initializes the socket(s) to communicate with the server
+  #
+  # @abstract Must be implemented in including classes to prepare sockets for
+  #           server communication
+  def init_socket
+  end
+
 end

data/lib/steam/servers/source_server.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
 
@@ -12,20 +12,45 @@ require 'steam/servers/game_server'
 require 'steam/sockets/rcon_socket'
 require 'steam/sockets/source_socket'
 
+# This class represents a Source game server and can be used to query
+# information about and remotely execute commands via RCON on the server
+#
+# A Source game server is an instance of the Source Dedicated Server (SrcDS)
+# running games using Valve's Source engine, like Counter-Strike: Source,
+# Team Fortress 2 or Left4Dead.
+#
+# @author Sebastian Staudt
+# @see GoldSrcServer
 class SourceServer
 
   include GameServer
 
+  # Creates a new instance of a server object representing a Source server,
+  # i.e. SrcDS instance
+  #
+  # @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
   def initialize(address, port = 27015)
     super
   end
 
   # Initializes the sockets to communicate with the Source server
+  #
+  # @see RCONSocket
+  # @see SourceSocket
   def init_socket
     @rcon_socket = RCONSocket.new @ip_address, @port
     @socket      = SourceSocket.new @ip_address, @port
   end
 
+  # Authenticates the connection for RCON communication with the server
+  #
+  # @param [String] password The RCON password of the server
+  # @return [Boolean] whether authentication was successful
+  # @see #rcon_exec
   def rcon_auth(password)
     @rcon_request_id = rand 2**16
 
@@ -38,22 +63,21 @@ class SourceServer
     reply.request_id == @rcon_request_id
   end
 
+  # Remotely executes a command on the server via RCON
+  #
+  # @param [String] command The command to execute on the server via RCON
+  # @return [String] The output of the executed command
+  # @see #rcon_auth
   def rcon_exec(command)
     @rcon_socket.send RCONExecRequest.new(@rcon_request_id, command)
     @rcon_socket.send RCONTerminator.new(@rcon_request_id)
-    response_packets = []
 
+    response = ''
     begin
       response_packet = @rcon_socket.reply
-      redo if response_packet.nil?
       raise RCONNoAuthException.new if response_packet.is_a? RCONAuthResponse
-      response_packets << response_packet
-    end while response_packet.response.size > 0
-
-    response = ''
-    response_packets.each do |packet|
-      response << packet.response
-    end
+      response << response_packet.response
+    end while response.length == 0 || response_packet.response.size > 0
 
     response.strip
   end

data/lib/stringio_additions.rb

@@ -1,44 +1,89 @@
-# 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) 2010, Sebastian Staudt
+# Copyright (c) 2010-2011, Sebastian Staudt
 
 require 'stringio'
 
+# This extends the `StringIO` class from Ruby's standard library. It adds some
+# methods to handle byte-wise input from a `StringIO` object.
+#
+# @author Sebastian Staudt
 class StringIO
 
+  # Creates a new instance of `StringIO` with the given size and fills it with
+  # zero-bytes.
+  #
+  # @param [Fixnum] size The size the new instance should have
+  # @return [StringIO] A new `StringIO` instance with the given size, filled
+  #         with zero-bytes
   def self.allocate(size)
     new "\0" * size
   end
 
+  # Reads a single byte from the current position of the byte stream
+  #
+  # @return [Fixnum] The numeric value of the byte at the current position
   def byte
     read(1)[0].ord
   end
 
+  # Reads a floating-point integer (32 bit) from the current position of the
+  # byte stream
+  #
+  # @return [Float] The floating-point integer read from the byte stream
   def float
     read(4).unpack('e')[0]
   end
 
+  # Reads the whole remaining content of the byte stream from the current
+  # position to the end
+  #
+  # @return [String] The remainder of the byte stream starting from the current
+  #         position of the byte stream
   def get
     read remaining
   end
 
+  # Reads an unsigned long integer (32 bit) from the current position of the
+  # byte stream
+  #
+  # @return [Fixnum] The unsigned long integer read from the byte stream
   def long
     read(4).unpack('V')[0]
   end
 
+  # Returns the remaining number of bytes from the current position to the end
+  # of the byte stream
+  #
+  # @return [Fixnum] The number of bytes until the end of the stream
   def remaining
     size - pos
   end
 
+  # Reads an unsigned short integer (16 bit) from the current position of the
+  # byte stream
+  #
+  # @return [Fixnum] The unsigned short integer read from the byte stream
   def short
     read(2).unpack('v')[0]
   end
 
+  # Reads a signed long integer (32 bit) from the current position of the byte
+  # stream
+  #
+  # @return [Fixnum] The signed long integer read from the byte stream
   def signed_long
     read(4).unpack('l')[0]
   end
 
+  # Reads a zero-byte terminated string from the current position of the byte
+  # stream
+  #
+  # This reads the stream up until the first occurance of a zero-byte or the
+  # end of the stream. The zero-byte is not included in the returned string.
+  #
+  # @return [String] The zero-byte terminated string read from the byte stream
   def cstring
     gets("\0")[0..-2]
   end