steam-condenser 0.14.0 → 1.0.1

data/lib/steam/sockets/source_socket.rb

@@ -1,29 +1,35 @@
-# 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 'stringio_additions'
+require 'core_ext/stringio'
+require 'errors/timeout_error'
 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 Source engine (e.g. Team Fortress 2, Counter-Strike: Source)
+#
+# @author Sebastian Staudt
 class SourceSocket
 
   include SteamSocket
 
-  # 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. Additionally Source
+  # may compress big packets using bzip2. Those packets will be compressed.
+  #
+  # @return [SteamPacket] The packet replied from the server
   def reply
-    bytes_read = receive_packet 1400
+    receive_packet 1400
     is_compressed = false
 
     if @buffer.long == 0xFFFFFFFE
       split_packets = []
       begin
-        # Parsing of split packet headers
         request_id = @buffer.long
         is_compressed = ((request_id & 0x80000000) != 0)
         packet_count = @buffer.byte
@@ -36,16 +42,14 @@ class SourceSocket
           @buffer.short
         end
 
-        # 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

data/lib/steam/sockets/steam_socket.rb

@@ -1,44 +1,41 @@
-# 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 'ipaddr'
 require 'socket'
 
-require 'stringio_additions'
-require 'exceptions/timeout_exception'
+require 'core_ext/stringio'
+require 'errors/timeout_error'
 
-# This module defines common methods for sockets used to connect to game and
-# master servers.
+# This module implements common functionality for sockets used to connect to
+# game and master servers
 #
 # @author Sebastian Staudt
-# @see GoldSrcSocket
-# @see MasterServerSocket
-# @see RCONSocket
-# @see SourceSocket
-# @since 0.5.0
 module SteamSocket
 
-  # The default timeout
-  # @since 0.11.0
+  # The default socket timeout
   @@timeout = 1000
 
-  # Sets the timeout for socket operations. This usually only affects timeouts,
-  # i.e. when a server does not respond in time.
+  # Sets the timeout for socket operations
   #
-  # Due to the server-side implementation of the RCON protocol, each RCON
-  # request will also wait this amount of time after execution. So if you need
-  # RCON requests to execute fast, you should set this to a adequatly low
-  # value.
+  # Any request that takes longer than this time will cause a {TimeoutError}.
   #
-  # +timeout+ The amount of milliseconds before a request times out
+  # @param [Fixnum] timeout The amount of milliseconds before a request times
+  #        out
   def self.timeout=(timeout)
     @@timeout = timeout
   end
 
+  # Creates a new UDP socket to communicate with the server on the given IP
+  # address and port
+  #
+  # @param [String] ip_address Either the IP address or the DNS name of the
+  #        server
+  # @param [Fixnum] port The port the server is listening on
   def initialize(ip_address, port = 27015)
-    @socket       = UDPSocket.new
+    @socket = UDPSocket.new
     @socket.connect ip_address, port
   end
 
@@ -47,15 +44,21 @@ module SteamSocket
     @socket.close
   end
 
+  # Reads the given amount of data from the socket and wraps it into the buffer
+  #
+  # @param [Fixnum] buffer_length The data length to read from the socket
+  # @raise [SteamCondenser::TimeoutError] if no packet is received on time
+  # @return [Fixnum] The number of bytes that have been read from the socket
+  # @see StringIO
   def receive_packet(buffer_length = 0)
     if select([@socket], nil, nil, @@timeout / 1000.0).nil?
-      raise TimeoutException
+      raise SteamCondenser::TimeoutError
     end
 
     if buffer_length == 0
       @buffer.rewind
     else
-      @buffer = StringIO.allocate buffer_length
+      @buffer = StringIO.alloc buffer_length
     end
 
     data = @socket.recv @buffer.remaining
@@ -66,6 +69,13 @@ module SteamSocket
     bytes_read
   end
 
+  # Sends the given packet to the server
+  #
+  # This converts the packet into a byte stream first before writing it to the
+  # socket.
+  #
+  # @param [SteamPacket] data_packet The packet to send to the server
+  # @see SteamPacket#to_s
   def send(data_packet)
     puts "Sending data packet of type \"#{data_packet.class.to_s}\"." if $DEBUG
 

data/lib/steam/steam_player.rb

@@ -1,17 +1,81 @@
-# 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 'exceptions/steam_condenser_exception'
+require 'errors/steam_condenser_error'
 
 # The SteamPlayer class represents a player connected to a server
+#
+# @author Sebastian Staudt
 class SteamPlayer
 
-  attr_reader :client_port, :connect_time, :id, :ip_address, :name, :loss,
-              :ping, :rate, :real_id, :score, :state, :steam_id
+  # Returns the client port of this player
+  #
+  # @return [Fixnum] The client port of the player
+  attr_reader :client_port
+
+  # Returns the time this player is connected to the server
+  #
+  # @return [Float] The connection time of the player
+  attr_reader :connect_time
+
+  # Returns the ID of this player
+  #
+  # @return [Fixnum] The ID of this player
+  attr_reader :id
+
+  # Returns the IP address of this player
+  #
+  # @return [String] The IP address of this player
+  attr_reader :ip_address
+
+  # Returns the nickname of this player
+  #
+  # @return [String] The name of this player
+  attr_reader :name
+
+  # Returns the packet loss of this player's connection
+  #
+  # @return [String] The packet loss of this player's connection
+  attr_reader :loss
+
+  # Returns the ping of this player
+  #
+  # @return [Fixnum] The ping of this player
+  attr_reader :ping
+
+  # Returns the rate of this player
+  #
+  # @return [Fixnum] The rate of this player
+  attr_reader :rate
+
+  # Returns the real ID (as used on the server) of this player
+  #
+  # @return [Fixnum] The real ID of this player
+  attr_reader :real_id
+
+  # Returns the score of this player
+  #
+  # @return [Fixnum] The score of this player
+  attr_reader :score
+
+  # Returns the connection state of this player
+  #
+  # @return [String] The connection state of this player
+  attr_reader :state
+
+  # Returns the SteamID of this player
+  #
+  # @return [String] The SteamID of this player
+  attr_reader :steam_id
 
-  # Creates a new SteamPlayer object based on the given information
+  # Creates a new player instance with the given information
+  #
+  # @param [Fixnum] id The ID of the player on the server
+  # @param [String] name The name of the player
+  # @param [Fixnum] score The score of the player
+  # @param [Float] connect_time The time the player is connected to the server
   def initialize(id, name, score, connect_time)
     @connect_time = connect_time
     @id = id
@@ -20,11 +84,15 @@ class SteamPlayer
     @extended = false
   end
 
-  # Extends this player object with additional information acquired using RCON
-  # status
+  # Extends a player object with information retrieved from a RCON call to
+  # the status command
+  #
+  # @param [String] player_data The player data retrieved from `rcon status`
+  # @raise [SteamCondenserError] if the information belongs to another
+  #         player
   def add_info(player_data)
     unless player_data[:name] == @name
-      raise SteamCondenserException.new('Information to add belongs to a different player.')
+      raise SteamCondenserError, 'Information to add belongs to a different player.'
     end
 
     @extended = true
@@ -47,16 +115,23 @@ class SteamPlayer
   end
 
   # Returns whether this player is a bot
+  #
+  # @return bool `true` if this player is a bot
   def bot?
     @steam_id == 'BOT'
   end
 
-  # Returns whether this player object has extended information
+  # Returns whether this player object has extended information gathered
+  # using RCON
+  #
+  # @return bool `true` if extended information for this player is available
   def extended?
     @extended
   end
 
-  # Returns a String representation of this player
+  # Returns a string representation of this player
+  #
+  # @return [String] A string representing this player
   def to_s
     if @extended
       "\##{@real_id} \"#{@name}\", SteamID: #{@steam_id}, Score: #{@score}, Time: #{@connect_time}"

data/lib/steam-condenser/community.rb

@@ -1,24 +1,24 @@
-# This code is free software; you can redistribute it and/or modify it under the
-# terms of the new BSD License.
-#
-# Copyright (c) 2010-2011, Sebastian Staudt
-
-module SteamCondenser
-
-  require 'steam-condenser/version'
-
-  # This module is used as a wrapper around Steam Condenser's Steam Community
-  # classes
-  #
-  # It does not provide any own functionality, but this file is used to easily
-  # require classes to interact with the Steam Community
-  #
-  # @author Sebastian Staudt
-  module Community
-
-    require 'steam/community/steam_id'
-    require 'steam/community/web_api' 
-
-  end
-
-end
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2010-2011, Sebastian Staudt
+
+module SteamCondenser
+
+  require 'steam-condenser/version'
+
+  # This module is used as a wrapper around Steam Condenser's Steam Community
+  # classes
+  #
+  # It does not provide any own functionality, but this file is used to easily
+  # require classes to interact with the Steam Community
+  #
+  # @author Sebastian Staudt
+  module Community
+
+    require 'steam/community/steam_id'
+    require 'steam/community/web_api'
+
+  end
+
+end

data/lib/steam-condenser/servers.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) 2010-2011, Sebastian Staudt
 

data/lib/steam-condenser/version.rb

@@ -1,11 +1,11 @@
-# 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-2011, Sebastian Staudt
 
 module SteamCondenser
 
   # The current version of Steam Condenser
-  VERSION = '0.14.0'
+  VERSION = '1.0.1'
 
 end

data/steam-condenser.gemspec

@@ -0,0 +1,23 @@
+require 'bundler'
+
+require File.expand_path(File.dirname(__FILE__) + '/lib/steam-condenser/version')
+
+Gem::Specification.new do |s|
+  s.name        = 'steam-condenser'
+  s.version     = SteamCondenser::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = [ 'Sebastian Staudt' ]
+  s.email       = [ 'koraktor@gmail.com' ]
+  s.homepage    = 'http://koraktor.de/steam-condenser'
+  s.summary     = 'Steam Condenser - A Steam query library'
+  s.description = 'A multi-language library for querying the Steam Community, Source, GoldSrc servers and Steam master servers'
+
+  s.add_dependency 'bzip2-ruby', '~> 0.2.7'
+  s.add_dependency 'multi_json', '~> 1.0.3'
+  s.add_development_dependency 'rake', '~> 0.9.2'
+  s.add_development_dependency 'yard', '~> 0.7.2'
+
+  s.files              = FileList['**/*']
+  s.test_files         = FileList['test/**/*']
+  s.require_paths      = [ 'lib' ]
+end

data/test/query_tests.rb

@@ -1,14 +1,14 @@
-# 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 'ipaddr'
 require 'test/unit'
 
 $:.push File.join(File.dirname(__FILE__), '..', 'lib')
 
-require 'exceptions/timeout_exception'
+require 'errors/timeout_error'
 require 'steam/servers/goldsrc_server'
 require 'steam/servers/master_server'
 require 'steam/servers/source_server'
@@ -17,16 +17,16 @@ class QueryTests < Test::Unit::TestCase
 
   # This test tries to initialize an invalid GoldSrc server
   def test_invalid_goldsrc_server
-    assert_raise TimeoutException do
-      invalid_server = GoldSrcServer.new IPAddr.new("1.0.0.0")
+    assert_raise SteamCondenser::TimeoutError do
+      invalid_server = GoldSrcServer.new IPAddr.new('1.0.0.0')
       invalid_server.ping
     end
   end
 
   # This test tries to initialize an invalid Source server
   def test_invalid_source_server
-    assert_raise TimeoutException do
-      invalid_server = SourceServer.new IPAddr.new("1.0.0.0")
+    assert_raise SteamCondenser::TimeoutError do
+      invalid_server = SourceServer.new IPAddr.new('1.0.0.0')
       invalid_server.ping
     end
   end
@@ -36,9 +36,9 @@ class QueryTests < Test::Unit::TestCase
   def test_random_goldsrc_server
     assert_nothing_raised do
       master_server = MasterServer.new(*MasterServer::GOLDSRC_MASTER_SERVER)
-      servers = master_server.servers MasterServer::REGION_ALL, "\\type\\d\\empty\\1\\full\\1\\gamedir\\valve"
+      servers = master_server.servers MasterServer::REGION_ALL, '\type\d\empty\1\full\1\gamedir\valve'
 
-      assert !servers.empty?, "Got no servers from master server."
+      assert !servers.empty?, 'Got no servers from master server.'
 
       server = GoldSrcServer.new(*servers[rand(servers.length)])
       server.init
@@ -54,9 +54,9 @@ class QueryTests < Test::Unit::TestCase
   def test_random_source_server
     assert_nothing_raised do
       master_server = MasterServer.new(*MasterServer::SOURCE_MASTER_SERVER)
-      servers = master_server.servers MasterServer::REGION_ALL, "\\type\\d\\empty\\1\\full\\1\\gamedir\\tf"
+      servers = master_server.servers MasterServer::REGION_ALL, '\type\d\empty\1\full\1\gamedir\tf'
 
-      assert !servers.empty?, "Got no servers from master server."
+      assert !servers.empty?, 'Got no servers from master server.'
 
       server = SourceServer.new(*servers[rand(servers.length)])
       server.init