steam-condenser 0.14.0 → 1.0.1

data/lib/steam/community/web_api.rb

@@ -1,32 +1,37 @@
 # 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 'json'
+require 'multi_json'
 require 'open-uri'
 
-require 'exceptions/web_api_exception'
+require 'errors/web_api_error'
 
-# This adds support for Steam Web API to classes needing this functionality.
+# This module provides functionality for accessing Steam's Web API
+#
 # The Web API requires you to register a domain with your Steam account to
 # acquire an API key. See http://steamcommunity.com/dev for further details.
+#
+# @author Sebastian
 module WebApi
 
-  @@api_key = nil
-
-  # Returns the Steam Web API key
+  # Returns the Steam Web API key currently used by Steam Condenser
+  #
+  # @return [String] The currently active Steam Web API key
   def self.api_key
     @@api_key
   end
 
-  # Sets the Steam Web API key.
+  # Sets the Steam Web API key
   #
-  # [+api_key+] The 128bit API key that has to be requested from
-  #             http://steamcommunity.com/dev
+  # @param [String] api_key The 128bit API key as a hexadecimal string that has
+  #        to be requested from http://steamcommunity.com/dev
+  # @raise [WebApiError] if the given API key is not a valid 128bit hexadecimal
+  #        string
   def self.api_key=(api_key)
     unless api_key.nil? || api_key.match(/^[0-9A-F]{32}$/)
-      raise WebApiException.new(:invalid_key)
+      raise WebApiError, :invalid_key
     end
 
     @@api_key = api_key
@@ -36,44 +41,57 @@ module WebApi
   # and version. Additional parameters are supplied via HTTP GET.
   # Data is returned as a JSON-encoded string.
   #
-  # [+interface+] The Web API interface to call, e.g. +ISteamUser+
-  # [+method+]    The Web API method to call, e.g. +GetPlayerSummaries+
-  # [+version+]   The API method version to use (default: 1)
-  # [+params+]    A Hash of additional parameters to supply via HTTP GET
+  # @param [String] interface The Web API interface to call, e.g. `ISteamUser`
+  # @param [String] method The Web API method to call, e.g.
+  #        `GetPlayerSummaries`
+  # @param [Fixnum] version The API method version to use
+  # @param [Hash<Symbol, Object>] params Additional parameters to supply via
+  #        HTTP GET
+  # @raise [WebApiError] if the request to Steam's Web API fails
+  # @return [String] The raw JSON data replied to the request
   def self.json(interface, method, version = 1, params = nil)
-    load(:json, interface, method, version, params)
+    get(:json, interface, method, version, params)
   end
 
   # Fetches JSON data from Steam Web API using the specified interface, method
   # and version. Additional parameters are supplied via HTTP GET.
   # Data is returned as a Hash containing the JSON data.
   #
-  # [+interface+] The Web API interface to call, e.g. +ISteamUser+
-  # [+method+]    The Web API method to call, e.g. +GetPlayerSummaries+
-  # [+version+]   The API method version to use (default: 1)
-  # [+params+]    A Hash of additional parameters to supply via HTTP GET
+  # @param [String] interface The Web API interface to call, e.g. `ISteamUser`
+  # @param [String] method The Web API method to call, e.g.
+  #        `GetPlayerSummaries`
+  # @param [Fixnum] version The API method version to use
+  # @param [Hash<Symbol, Object>] params Additional parameters to supply via
+  #        HTTP GET
+  # @raise [WebApiError] if the request to Steam's Web API fails
+  # @return [Hash<Symbol, Object>] The JSON data replied to the request
   def self.json!(interface, method, version = 1, params = nil)
     data = json(interface, method, version, params)
-    result = JSON.parse(data, { :symbolize_names => true })[:result]
+    result = MultiJson.decode(data, { :symbolize_keys => true })[:result]
 
     status = result[:status]
     if status != 1
-      raise WebApiException.new(:status_bad, status, result[:statusDetail])
+      raise WebApiError.new :status_bad, status, result[:statusDetail]
     end
 
     result
   end
 
   # Fetches data from Steam Web API using the specified interface, method and
-  # version. Additional parameters are supplied via HTTP GET.
-  # Data is returned as a String in the given format.
+  # version. Additional parameters are supplied via HTTP GET. Data is returned
+  # as a string in the given format.
   #
-  # [+format+]    The format to load from the API ('json', 'vdf', or 'xml')
-  # [+interface+] The Web API interface to call, e.g. +ISteamUser+
-  # [+method+]    The Web API method to call, e.g. +GetPlayerSummaries+
-  # [+version+]   The API method version to use (default: 1)
-  # [+params+]    A Hash of additional parameters to supply via HTTP GET
-  def self.load(format, interface, method, version = 1, params = nil)
+  # @param [Symbol] format The format to load from the API (`:json`, `:vdf`, or
+  #        `:xml`)
+  # @param [String] interface The Web API interface to call, e.g. `ISteamUser`
+  # @param [String] method The Web API method to call, e.g.
+  #        `GetPlayerSummaries`
+  # @param [Fixnum] version The API method version to use
+  # @param [Hash<Symbol, Object>] params Additional parameters to supply via
+  #        HTTP GET
+  # @raise [WebApiError] if the request to Steam's Web API fails
+  # @return [String] The data as replied by the Web API in the desired format
+  def self.get(format, interface, method, version = 1, params = nil)
     version = version.to_s.rjust(4, '0')
     url = "http://api.steampowered.com/#{interface}/#{method}/v#{version}/"
     params = {} unless params.is_a?(Hash)
@@ -89,8 +107,8 @@ module WebApi
     rescue OpenURI::HTTPError
       status = $!.io.status[0]
       status = [status, ''] unless status.is_a? Array
-      raise WebApiException.new(:unauthorized) if status[0].to_i == 401
-      raise WebApiException.new(:http_error, status[0].to_i, status[1])
+      raise WebApiError, :unauthorized if status[0].to_i == 401
+      raise WebApiError.new :http_error, status[0].to_i, status[1]
     end
   end
 

data/lib/steam/packets/c2m_checkmd5_packet.rb

@@ -22,7 +22,7 @@ class C2M_CHECKMD5_Packet
 
   # Returns the raw data representing this packet
   #
-  # @return string A string containing the raw data of this request packet
+  # @return [String] A string containing the raw data of this request packet
   def to_s
     [@header_data, 0xFF].pack('c2')
   end

data/lib/steam/packets/m2a_server_batch_packet.rb

@@ -3,6 +3,7 @@
 #
 # Copyright (c) 2008-2011, Sebastian Staudt
 
+require 'errors/packet_format_error'
 require 'steam/packets/steam_packet'
 
 # This packet class represents a M2A_SERVER_BATCH response replied by a master
@@ -26,12 +27,12 @@ class M2A_SERVER_BATCH_Packet
   # Creates a new M2A_SERVER_BATCH response object based on the given data
   #
   # @param [String] data The raw packet data replied from the server
-  # @raises PacketFormatException if the packet data is not well formatted
+  # @raise [PacketFormatError] if the packet data is not well formatted
   def initialize(data)
     super M2A_SERVER_BATCH_HEADER, data
 
     unless @content_data.byte == 0x0A
-      raise PacketFormatException.new('Master query response is missing additional 0x0A byte.')
+      raise PacketFormatError, 'Master query response is missing additional 0x0A byte.'
     end
 
     @servers = []

data/lib/steam/packets/m2s_requestrestart_packet.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) 2011, Sebastian Staudt
 
@@ -12,7 +12,7 @@ require 'steam/packets/steam_packet'
 # outdated.
 #
 # @author Sebastian Staudt
-# @see MasterServer#sendHeartbeat
+# @see MasterServer#send_heartbeat
 class M2S_REQUESTRESTART_Packet
 
   include SteamPacket

data/lib/steam/packets/rcon/rcon_packet_factory.rb

@@ -3,8 +3,8 @@
 #
 # Copyright (c) 2008-2011, Sebastian Staudt
 
-require 'stringio_additions'
-require 'exceptions/packet_format_exception'
+require 'core_ext/stringio'
+require 'errors/packet_format_error'
 require 'steam/packets/steam_packet_factory'
 require 'steam/packets/rcon/rcon_auth_response'
 require 'steam/packets/rcon/rcon_exec_response'
@@ -21,7 +21,7 @@ module RCONPacketFactory
   # Creates a new packet object based on the header byte of the given raw data
   #
   # @param [String] raw_data The raw data of the packet
-  # @raise [PacketFormatException] if the packet header is not recognized
+  # @raise [PacketFormatError] if the packet header is not recognized
   # @return [RCONPacket] The packet object generated from the packet data
   def self.packet_from_data(raw_data)
     byte_buffer = StringIO.new raw_data
@@ -36,7 +36,7 @@ module RCONPacketFactory
       when RCONPacket::SERVERDATA_RESPONSE_VALUE then
         return RCONExecResponse.new(request_id, data)
       else
-        raise PacketFormatException.new("Unknown packet with header #{header.to_s(16)} received.")
+        raise PacketFormatError, "Unknown packet with header #{header.to_s(16)} received."
     end
   end
 

data/lib/steam/packets/request_with_challenge.rb

@@ -11,7 +11,7 @@ module RequestWithChallenge
 
   # Returns the raw data representing this packet
   #
-  # @return string A string containing the raw data of this request packet
+  # @return [String] A string containing the raw data of this request packet
   def to_s
     [0xFF, 0xFF, 0xFF, 0xFF, @header_data, @content_data.string.to_i].pack('c5l')
   end

data/lib/steam/packets/s2a_info_base_packet.rb

@@ -27,7 +27,7 @@ module S2A_INFO_BasePacket
   def generate_info_hash
     @info_hash = Hash[
       *instance_variables.map { |var|
-        [var[1..-1], instance_variable_get(var)] if var != '@content_data' && var != '@header_data'
+        [var[1..-1].to_sym, instance_variable_get(var)] if var != '@content_data' && var != '@header_data'
       }.compact.flatten
     ]
   end

data/lib/steam/packets/s2a_info_detailed_packet.rb

@@ -3,15 +3,15 @@
 #
 # Copyright (c) 2008-2011 Sebastian Staudt
 
-require "steam/packets/s2a_info_base_packet"
+require 'steam/packets/s2a_info_base_packet'
 
 # This class represents a S2A_INFO_DETAILED response packet sent by a GoldSrc
 # server
 #
-# This is deprecated by 10/24/2008. GoldSrc servers use the same format as
-# Source servers now (see {S2A_INFO2_Packet}).
-#
 # @author Sebastian Staudt
+# @deprecated Only outdated GoldSrc servers (before 10/24/2008) use this
+#             format. Newer ones use the same format as Source servers now (see
+#             {S2A_INFO2_Packet}).
 # @see GameServer#update_server_info
 class S2A_INFO_DETAILED_Packet
 
@@ -39,14 +39,14 @@ class S2A_INFO_DETAILED_Packet
 
     if @is_mod
       @mod_info = {}
-      @mod_info['url_info'] = @content_data.cstring
-      @mod_info['url_dl'] = @content_data.cstring
+      @mod_info[:url_info] = @content_data.cstring
+      @mod_info[:url_dl] = @content_data.cstring
       @content_data.byte
       if @content_data.remaining == 12
-        @mod_info['mod_version'] = @content_data.long
-        @mod_info['mod_size'] = @content_data.long
-        @mod_info['sv_only'] = @content_data.byte == 1
-        @mod_info['cl_dll'] = @content_data.byte == 1
+        @mod_info[:mod_version] = @content_data.long
+        @mod_info[:mod_size] = @content_data.long
+        @mod_info[:sv_only] = @content_data.byte == 1
+        @mod_info[:cl_dll] = @content_data.byte == 1
         @secure = @content_data.byte == 1
         @number_of_bots = @content_data.byte
       end

data/lib/steam/packets/s2a_player_packet.rb

@@ -3,6 +3,7 @@
 #
 # Copyright (c) 2008-2011, Sebastian Staudt
 
+require 'errors/packet_format_error'
 require 'steam/packets/steam_packet'
 
 # This class represents a S2A_PLAYER response sent by a game server
@@ -23,8 +24,11 @@ class S2A_PLAYER_Packet
   # Creates a new S2A_PLAYER response object based on the given data
   #
   # @param [String] content_data The raw packet data sent by the server
+  # @raise [PacketFormatError] if the packet data is not well formatted
   def initialize(content_data)
-    raise Exception.new('Wrong formatted S2A_PLAYER packet.') if content_data.nil?
+    if content_data.nil?
+      raise PacketFormatError, 'Wrong formatted S2A_PLAYER packet.'
+    end
 
     super S2A_PLAYER_HEADER, content_data
 

data/lib/steam/packets/s2a_rules_packet.rb

@@ -25,7 +25,9 @@ class S2A_RULES_Packet
   #
   # @param [String] content_data The raw packet data sent by the server
   def initialize(content_data)
-    raise Exception.new('Wrong formatted S2A_RULES response packet.') if content_data.nil?
+    if content_data.nil?
+      raise PacketFormatError, 'Wrong formatted S2A_RULES response packet.'
+    end
 
     super SteamPacket::S2A_RULES_HEADER, content_data
 
@@ -37,8 +39,7 @@ class S2A_RULES_Packet
       rule  = @content_data.cstring
       value = @content_data.cstring
 
-      # This is a workaround for servers sending corrupt replies
-      break if rule.empty? or value.empty?
+      break if rule.empty? || value.empty?
 
       @rules_hash[rule] = value
     end

data/lib/steam/packets/s2m_heartbeat2_packet.rb

@@ -45,13 +45,13 @@ class S2M_HEARTBEAT2_Packet
   #
   # @param [Hash<Symbol, Object>] data The data to send with the heartbeat. The
   #        data contents are merge with the values from {DEFAULT_DATA}.
-  # @raise [SteamCondenserException] when the required challenge number is
+  # @raise [SteamCondenserError] when the required challenge number is
   #        missing
   def initialize(data = {})
     data = DEFAULT_DATA.merge data
 
     if data[:challenge].nil?
-      raise SteamCondenserException.new 'You have to provide a challenge number when sending a heartbeat to a master server.'
+      raise SteamCondenserError, 'You have to provide a challenge number when sending a heartbeat to a master server.'
     end
 
     bytes = 0x0A.chr

data/lib/steam/packets/steam_packet.rb

@@ -3,7 +3,7 @@
 #
 # Copyright (c) 2008-2011, Sebastian Staudt
 
-require 'stringio_additions'
+require 'core_ext/stringio'
 
 # This module implements the basic functionality used by most of the packets
 # used in communication with master, Source or GoldSrc servers.

data/lib/steam/packets/steam_packet_factory.rb

@@ -3,7 +3,10 @@
 #
 # Copyright (c) 2008-2011, Sebastian Staudt
 
-require 'exceptions/steam_condenser_exception'
+require 'bzip2-ruby'
+require 'zlib'
+
+require 'errors/packet_format_error'
 require 'steam/packets/s2a_info_detailed_packet'
 require 'steam/packets/a2s_info_packet'
 require 'steam/packets/s2a_info2_packet'
@@ -31,7 +34,7 @@ module SteamPacketFactory
   # Creates a new packet object based on the header byte of the given raw data
   #
   # @param [String] raw_data The raw data of the packet
-  # @raise [SteamCondenserException] if the packet header is not recognized
+  # @raise [SteamCondenserError] if the packet header is not recognized
   # @return [SteamPacket] The packet object generated from the packet data
   def self.packet_from_data(raw_data)
     header = raw_data[0].ord
@@ -71,7 +74,7 @@ module SteamPacketFactory
       when SteamPacket::S2A_LOGSTRING_HEADER
         return S2A_LOGSTRING_Packet.new(data)
       else
-        raise SteamCondenserException.new("Unknown packet with header 0x#{header.to_s(16)} received.")
+        raise PacketFormatError, "Unknown packet with header 0x#{header.to_s(16)} received."
     end
   end
 
@@ -79,30 +82,23 @@ module SteamPacketFactory
   # packet object
   #
   # @param [Array<String>] split_packets An array of packet data
-  # @param [true, false] is_compressed whether the data of this packet is
+  # @param [Boolean] is_compressed whether the data of this packet is
   #        compressed
   # @param [Fixnum] packet_checksum The CRC32 checksum of the decompressed
   #        packet data
-  # @raise [SteamCondenserException] if the bz2 gem is not installed
-  # @raise [PacketFormatException] if the calculated CRC32 checksum does not
-  #        match the expected value
+  # @raise [SteamCondenserError] if the bz2 gem is not installed
+  # @raise [PacketFormatError] if the calculated CRC32 checksum does not match
+  #        the expected value
   # @return [SteamPacket] The reassembled packet
   # @see packet_from_data
   def self.reassemble_packet(split_packets, is_compressed = false, packet_checksum = 0)
     packet_data = split_packets.join ''
 
     if is_compressed
-      require 'zlib'
-
-      begin
-        require 'bz2'
-        packet_data = BZ2.uncompress(packet_data)
-      rescue LoadError
-        raise SteamCondenserException.new('You need to install the libbzip2 interface for Ruby.')
-      end
+      packet_data = Bzip2.decompress packet_data
 
       unless Zlib.crc32(packet_data) == packet_checksum
-        raise PacketFormatException.new('CRC32 checksum mismatch of uncompressed packet data.')
+        raise PacketFormatError, 'CRC32 checksum mismatch of uncompressed packet data.'
       end
     end
 

data/lib/steam/servers/game_server.rb

@@ -3,7 +3,8 @@
 #
 # Copyright (c) 2008-2011, Sebastian Staudt
 
-require 'exceptions/steam_condenser_exception'
+require 'errors/steam_condenser_error'
+require 'errors/timeout_error'
 require 'steam/steam_player'
 require 'steam/packets/a2s_info_packet'
 require 'steam/packets/a2s_player_packet'
@@ -24,11 +25,6 @@ module GameServer
 
   include Server
 
-  REQUEST_CHALLENGE = 0
-  REQUEST_INFO = 1
-  REQUEST_PLAYER = 2
-  REQUEST_RULES = 3
-
   # Parses the player attribute names supplied by `rcon status`
   #
   # @param [String] status_header The header line provided by `rcon status`
@@ -87,9 +83,11 @@ module GameServer
   #        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
+
+    @rcon_authenticated = false
   end
 
   # Returns the last measured response time of this server
@@ -134,8 +132,13 @@ module GameServer
   # @return [Boolean] whether the authentication was successful
   # @see #rcon_exec
   def rcon_auth(password)
+    raise NotImplementedError
   end
 
+  # Returns whether the RCON connection to this server is already authenticated
+  #
+  # @return [Boolean] `true` if the RCON connection is authenticated
+  # @see #rcon_auth
   def rcon_authenticated?
     @rcon_authenticated
   end
@@ -148,6 +151,7 @@ module GameServer
   # @return [String] The output of the executed command
   # @see #rcon_auth
   def rcon_exec(command)
+    raise NotImplementedError
   end
 
   # Returns the settings applied on the server. These settings are also called
@@ -189,30 +193,30 @@ module GameServer
   # Depending on the given request type this will fill the various data
   # attributes of the server object.
   #
-  # @param [Fixnum] request_type The type of request to send to the server
+  # @param [Symbol] request_type The type of request to send to the server
   # @param [Boolean] repeat_on_failure Whether the request should be repeated,
   #        if the replied packet isn't expected. This is useful to handle
   #        missing challenge numbers, which will be automatically filled in,
   #        although not requested explicitly.
-  # @raise [SteamCondenserException] if either the request type or the response
+  # @raise [SteamCondenserError] if either the request type or the response
   #        packet is not known
   def handle_response_for_request(request_type, repeat_on_failure = true)
     begin
       case request_type
-        when GameServer::REQUEST_CHALLENGE then
+        when :challenge then
           request_packet = A2S_SERVERQUERY_GETCHALLENGE_Packet.new
           expected_response = S2C_CHALLENGE_Packet
-        when GameServer::REQUEST_INFO then
+        when :info then
           request_packet = A2S_INFO_Packet.new
           expected_response = S2A_INFO_BasePacket
-        when GameServer::REQUEST_PLAYER then
+        when :players then
           request_packet = A2S_PLAYER_Packet.new(@challenge_number)
           expected_response = S2A_PLAYER_Packet
-        when GameServer::REQUEST_RULES then
+        when :rules then
           request_packet = A2S_RULES_Packet.new(@challenge_number)
           expected_response = S2A_RULES_Packet
         else
-          raise SteamCondenserException.new("Called with wrong request type.")
+          raise SteamCondenserError, 'Called with wrong request type.'
       end
 
       send_request request_packet
@@ -227,14 +231,14 @@ module GameServer
       elsif response_packet.kind_of? S2C_CHALLENGE_Packet
         @challenge_number = response_packet.challenge_number
       else
-        raise SteamCondenserException.new("Response of type #{response_packet.class} cannot be handled by this method.")
+        raise SteamCondenserError, "Response of type #{response_packet.class} cannot be handled by this method."
       end
 
       unless response_packet.kind_of? expected_response
         puts "Expected #{expected_response}, got #{response_packet.class}." if $DEBUG
         handle_response_for_request(request_type, false) if repeat_on_failure
       end
-    rescue TimeoutException
+    rescue SteamCondenser::TimeoutError
       puts "Expected #{expected_response}, but timed out." if $DEBUG
     end
   end
@@ -263,22 +267,24 @@ module GameServer
   # @see #handle_response_for_request
   # @see #players
   def update_players(rcon_password = nil)
-    handle_response_for_request GameServer::REQUEST_PLAYER
+    handle_response_for_request :players
 
-    unless rcon_password.nil? || @player_hash.nil? || @player_hash.empty?
+    unless @rcon_authenticated
+      return if rcon_password.nil?
       rcon_auth rcon_password
-      players = rcon_exec('status').lines.select do |line|
-        line.start_with?('#') && line != "#end\n"
-      end.map do |line|
-        line[1..-1].strip
-      end
-      attributes = GameServer.player_status_attributes players.shift
+    end
+
+    players = rcon_exec('status').lines.select do |line|
+      line.start_with?('#') && line != "#end\n"
+    end.map do |line|
+      line[1..-1].strip
+    end
+    attributes = GameServer.player_status_attributes players.shift
 
-      players.each do |player|
-        player_data = GameServer.split_player_status(attributes, player)
-        if @player_hash.key? player_data[:name]
-          @player_hash[player_data[:name]].add_info player_data
-        end
+    players.each do |player|
+      player_data = GameServer.split_player_status(attributes, player)
+      if @player_hash.key? player_data[:name]
+        @player_hash[player_data[:name]].add_info player_data
       end
     end
   end
@@ -292,7 +298,7 @@ module GameServer
   # @see #handle_response_for_request
   # @see #rules
   def update_rules
-    handle_response_for_request GameServer::REQUEST_RULES
+    handle_response_for_request :rules
   end
 
   # Sends a A2S_INFO request to the server and updates this server's basic
@@ -305,7 +311,7 @@ module GameServer
   # @see #handle_response_for_request
   # @see #server_info
   def update_server_info
-    handle_response_for_request GameServer::REQUEST_INFO
+    handle_response_for_request :info
   end
 
   # Sends a A2S_SERVERQUERY_GETCHALLENGE request to the server and updates the
@@ -318,7 +324,7 @@ module GameServer
   # @see #handle_response_for_request
   # @see #init
   def update_challenge_number
-    handle_response_for_request GameServer::REQUEST_CHALLENGE
+    handle_response_for_request :challenge
   end
 
   # Sends a A2S_INFO request to the server and measures the time needed for the