steam-condenser 0.12.0 → 0.13.0

data/README.md

@@ -11,7 +11,8 @@ Currently it is implemented in Java, PHP and Ruby.
 * Ruby 1.8.6 or newer
 
   The following gems are required:
-  * `bzip2-ruby` (for Source servers sending compressed responses)
+  * `bzip2-ruby (for Source servers sending compressed responses)
+  * `json` (for the Web API features)
 
 ## License
 
@@ -22,6 +23,7 @@ included LICENSE file.
 ## Credits
 
 * Sebastian Staudt -- koraktor(at)gmail.com
+* DeFirence -- defirence(at)defirence.za.net
 
 ## See Also
 

data/lib/exceptions/web_api_exception.rb

@@ -0,0 +1,49 @@
+# 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
+
+require 'exceptions/steam_condenser_exception'
+
+# This exceptions is raised when a Steam Web API request or a related action
+# fails. This can have various reasons.
+class WebApiException < SteamCondenserException
+
+  # Creates a new WebApiException with an error message according to the given
+  # +cause+. If this cause is +:status_bad+ (which will origin from the Web API
+  # itself) or +:http_error+ the details about this failed request will be
+  # taken from +status_code+ and +status_message+.
+  #
+  # * +:http_errpr+:   An error in the HTTP request itself will result in an
+  #                    exception with this reason.
+  # * +:invalid_key+:  This occurs when trying to set a Web API key that isn't
+  #                    valid, i.e. a 128 bit integer in a hexadecimal string.
+  # * +:status_bad+:   This is caused by a succesful request that fails for
+  #                    some Web API internal reason (e.g. a invalid argument).
+  #                    Details about this failed request will be taken from
+  #                    +status_code+ and +status_message+.
+  # * +:unauthorized+: This happens when a Steam Web API request is rejected as
+  #                    unauthorized. This most likely means that you did not
+  #                    specify a valid Web API key using +WebAPI.api_key=+. A
+  #                    Web API key can be obtained from
+  #                    http://steamcommunity.com/dev/apikey.
+  #
+  # Other undefined reasons will cause a generic error message.
+  def initialize(cause, status_code = nil, status_message = '')
+    case cause
+      when :http_error then
+        message = "The Web API request has failed due to an HTTP error: #{status_message} (status code: #{status_code})."
+      when :invalid_key then
+        message = 'This is not a valid Steam Web API key.'
+      when :status_bad then
+        message = "The Web API request failed with the following error: #{status_message} (status code: #{status_code})."
+      when :unauthorized then
+        message = 'Your Web API request has been rejected. You most likely did not specify a valid Web API key.'
+      else
+        message = 'An unexpected error occured while executing a Web API request.'
+    end
+
+    super message
+  end
+
+end

data/lib/steam/community/app_news.rb

@@ -0,0 +1,69 @@
+# 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
+
+require 'json'
+
+require 'steam/community/web_api'
+
+# The AppNews class is a representation of Steam news and can be used to load
+# current news about specific games
+class AppNews
+
+  attr_reader :app_id, :author, :contents, :date, :feed_label, :feed_name,
+              :gid, :title, :url
+
+  # Loads the news for the given game with the given restrictions
+  #
+  # [+app_id+]     The unique Steam Application ID of the game (e.g. +440+ for
+  #                Team Fortress 2). See
+  #                http://developer.valvesoftware.com/wiki/Steam_Application_IDs
+  #                for all application IDs
+  # [+count+]      The maximum number of news to load (default: 5). There's no
+  #                reliable way to load all news. Use really a really great
+  #                number instead
+  # [+max_length+] The maximum content length of the news (default: nil). If a
+  #                maximum length is defined, the content of the news will only
+  #                be at most +max_length+ characters long plus an ellipsis
+  def self.news_for_app(app_id, count = 5, max_length = nil)
+    params = { :appid => app_id, :count => count, :maxlength => max_length }
+    data = WebApi.json('ISteamNews', 'GetNewsForApp', 1, params)
+
+    news_items = []
+    JSON.parse(data, { :symbolize_names => true })[:appnews][:newsitems][:newsitem].each do |news_data|
+      news_items << AppNews.new(app_id, news_data)
+    end
+
+    news_items
+  end
+
+  # Returns whether this news items originates from a source other than Steam
+  # itself (e.g. an external blog)
+  def external?
+    @external
+  end
+
+  private
+
+  # Creates a new instance of an AppNews news item with the given data
+  #
+  # [+app_id+]    The unique Steam Application ID of the game (e.g. +440+ for
+  #               Team Fortress 2). See
+  #               http://developer.valvesoftware.com/wiki/Steam_Application_IDs
+  #               for all application IDs
+  # [+news_data+] The news data extracted from JSON
+  def initialize(app_id, news_data)
+    @app_id      = app_id
+    @author      = news_data[:autor]
+    @contents    = news_data[:contents].strip
+    @data        = Time.at(news_data[:date])
+    @external    = news_data[:is_external_url]
+    @feed_label  = news_data[:feedlabel]
+    @feed_name   = news_data[:feedname]
+    @gid         = news_data[:gid]
+    @title       = news_data[:title]
+    @url         = news_data[:url]
+  end
+
+end

data/lib/steam/community/game_achievement.rb

@@ -3,14 +3,43 @@
 #
 # Copyright (c) 2008-2010, Sebastian Staudt
 
+require 'json'
+
+require 'steam/community/web_api'
+
 # The GameAchievement class represents a specific achievement for a single game
 # and for a single user
 class GameAchievement
 
   attr_reader :app_id, :name, :steam_id64, :timestamp
 
+  # Loads the global unlock percentages of all achievements for the given game
+  #
+  # [+app_id+] The unique Steam Application ID of the game (e.g. +440+ for
+  #            Team Fortress 2). See
+  #            http://developer.valvesoftware.com/wiki/Steam_Application_IDs
+  #            for all application IDs
+  def self.global_percentages(app_id)
+    percentages = {}
+
+    data = WebApi.json('ISteamUserStats', 'GetGlobalAchievementPercentagesForApp', 1, { :gameid => app_id })
+    JSON.parse(data, { :symbolize_names => true })[:achievementpercentages][:achievements][:achievement].each do |percentage|
+      percentages[percentage[:name].to_sym] = percentage[:percent]
+    end
+
+    percentages
+  end
+
   # Creates the achievement with the given name for the given user and game
   # and achievement data
+  #
+  # [+steam_id64+]       The 64bit SteamID of the player this achievement
+  #                      belongs to
+  # [+app_id+]           The unique Steam Application ID of the game (e.g.
+  #                      +440+ for Team Fortress 2). See
+  #                      http://developer.valvesoftware.com/wiki/Steam_Application_IDs
+  #                      for all application IDs
+  # [+achievement_data+] The achievement data extracted from JSON
   def initialize(steam_id64, app_id, achievement_data)
     @app_id     = app_id
     @name       = achievement_data.elements['name'].text

data/lib/steam/community/steam_id.rb

@@ -177,7 +177,7 @@ class SteamId
       if game.elements['globalStatsLink'].nil?
         @games[game_name] = false
       else
-        friendly_name = game.elements['globalStatsLink'].text.match(/http:\/\/steamcommunity.com\/stats\/([0-9a-zA-Z:]+)\/achievements\//)[1]
+        friendly_name = game.elements['globalStatsLink'].text.match(/http:\/\/steamcommunity.com\/stats\/([^?\/]+)\/achievements\//)[1]
         @games[game_name] = friendly_name.downcase
       end
     end

data/lib/steam/community/tf2/tf2_golden_wrench.rb

@@ -0,0 +1,43 @@
+# 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
+
+require 'json'
+require 'steam/community/steam_id'
+require 'steam/community/web_api'
+
+# Represents the special Team Fortress 2 item Golden Wrench. It includes the
+# ID of the item, the serial number of the wrench, a reference to the SteamId
+# of the owner and the date this player crafted the wrench
+class TF2GoldenWrench
+
+  attr_reader :date, :id, :number, :owner
+
+  @@golden_wrenches = nil
+
+  # Returns an array of all golden wrenches (as instances of TF2GoldenWrench)
+  def self.golden_wrenches
+    if @@golden_wrenches.nil?
+      @@golden_wrenches = []
+
+      data = JSON.parse(WebApi.json('ITFItems_440', 'GetGoldenWrenches'), { :symbolize_names => true })
+      data[:results][:wrenches][:wrench].each do |wrench_data|
+        @@golden_wrenches << TF2GoldenWrench.new(wrench_data)
+      end
+    end
+
+    @@golden_wrenches
+  end
+
+  private
+
+  # Creates a new instance of TF2GoldenWrench with the given data
+  def initialize(wrench_data)
+    @date   = Time.at(wrench_data[:timestamp])
+    @id     = wrench_data[:itemID]
+    @number = wrench_data[:wrenchNumber]
+    @owner  = SteamId.new(wrench_data[:steamID], false)
+  end
+
+end

data/lib/steam/community/tf2/tf2_inventory.rb

@@ -0,0 +1,51 @@
+# 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
+
+require 'steam/community/cacheable'
+require 'steam/community/tf2/tf2_item'
+require 'steam/community/web_api'
+
+# Represents the inventory (aka. Backpack) of a Team Fortress 2 player
+class TF2Inventory
+
+  include Cacheable
+  cacheable_with_ids :steam_id64
+
+  attr_reader :items, :steam_id64
+
+  # Creates a new inventory object for the given SteamID64. This calls update
+  # to fetch the data and create the TF2Item instances contained in this
+  # players backpack
+  def initialize(steam_id64, fetch_now = true)
+    @steam_id64 = steam_id64
+
+    super(fetch_now)
+  end
+
+  # Returns the item at the given position in the backpack. The positions range
+  # from 1 to 100 instead of the usual array indices (0 to 99).
+  def [](index)
+    @items[index - 1]
+  end
+
+  # Updates the contents of the backpack using Steam Web API
+  def fetch
+    result = WebApi.json!('ITFItems_440', 'GetPlayerItems', 1, { :SteamID => @steam_id64 })
+
+    @items = []
+    result[:items][:item].each do |item_data|
+      unless item_data.nil?
+        item = TF2Item.new(item_data)
+        @items[item.backpack_position - 1] = item
+      end
+    end
+  end
+
+  # Returns the number of items in the user's backpack
+  def size
+    @items.size
+  end
+
+end

data/lib/steam/community/tf2/tf2_item.rb

@@ -0,0 +1,106 @@
+# 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
+
+require 'steam/community/web_api'
+
+# Represents a Team Fortress 2 item
+class TF2Item
+
+  CLASSES = [ :scout, :sniper, :soldier, :demoman, :medic, :heavy, :pyro, :spy ]
+
+  attr_reader :attributes, :backpack_position, :class, :count, :defindex, :id,
+              :level, :name, :quality, :slot, :type
+
+  @@attribute_schema = nil
+
+  @@item_schema = nil
+
+  @@schema_language = 'en'
+
+  # Returns the attribute schema
+  #
+  # The attribute schema is fetched first if not done already
+  def self.attribute_schema
+    update_schema if @@attribute_schema.nil?
+
+    @@attribute_schema
+  end
+
+  # Returns the item schema
+  #
+  # The item schema is fetched first if not done already
+  def self.item_schema
+    update_schema if @@item_schema.nil?
+
+    @@item_schema
+  end
+
+  # Sets the language the schema should be fetched in (default is: +'en'+)
+  def self.schema_language=(language)
+    @@schema_language = language
+  end
+
+  # Creates a new instance of a TF2Item with the given data
+  def initialize(item_data)
+    update_schema if @@item_schema.nil?
+
+    @defindex          = item_data[:defindex]
+
+    @backpack_position = item_data[:inventory] & 0xffff
+    @class             = @@item_schema[@defindex][:item_class]
+    @count             = item_data[:quantity]
+    @id                = item_data[:id]
+    @level             = item_data[:level]
+    @name              = @@item_schema[@defindex][:item_name]
+    @quality           = @@qualities[item_data[:quality]]
+    @slot              = @@item_schema[@defindex][:item_slot]
+    @type              = @@item_schema[@defindex][:item_type_name]
+
+    @equipped = {}
+    CLASSES.each_index do |class_id|
+      @equipped[CLASSES[class_id]] = (item_data[:inventory] & (1 << 16 + class_id) != 0)
+    end
+
+    unless @@item_schema[@defindex][:attributes].nil?
+      @attributes = @@item_schema[@defindex][:attributes][:attribute]
+    end
+  end
+
+  # Returns the class symbols for each class this player has equipped this item
+  def classes_equipped?
+    @equipped.reject { |class_id, equipped| !equipped }
+  end
+
+  # Returns whether this item is equipped by this player at all
+  def equipped?
+    @equipped.has_value? true
+  end
+
+  protected
+
+  # Updates the item schema (this includes attributes and qualities) using the
+  # +GetSchema+ method of interface +ITFItems_440+
+  def update_schema
+    params = {}
+    params[:language] = @@schema_language unless @@schema_language.nil?
+    result = WebApi.json!('ITFItems_440', 'GetSchema', 1, params)
+
+    @@attribute_schema = {}
+    result[:attributes][:attribute].each do |attribute_data|
+      @@attribute_schema[attribute_data[:name]] = attribute_data
+    end
+
+    @@item_schema = []
+    result[:items][:item].each do |item_data|
+      @@item_schema[item_data[:defindex]] = item_data
+    end
+
+    @@qualities = []
+    result[:qualities].each do |quality, id|
+      @@qualities[id] = quality
+    end
+  end
+
+end

data/lib/steam/community/tf2/tf2_stats.rb

@@ -5,6 +5,7 @@
 
 require 'steam/community/game_stats'
 require 'steam/community/tf2/tf2_class_factory'
+require 'steam/community/tf2/tf2_inventory'
 
 # The TF2Stats class represents the game statistics for a single user in Team
 # Fortress 2
@@ -22,6 +23,16 @@ class TF2Stats < GameStats
     end
   end
 
+  # Returns the current Team Fortress 2 inventory (a.k.a. backpack) of this
+  # player
+  def inventory
+    if @inventory.nil?
+      @inventory = TF2Inventory.new(steam_id64)
+    end
+
+    @inventory
+  end
+
   # Returns a Hash of TF2Class for this user containing all Team Fortress 2
   # classes. If the classes haven't been parsed already, parsing is done now.
   def class_stats

data/lib/steam/community/web_api.rb

@@ -0,0 +1,96 @@
+# 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
+
+require 'json'
+require 'open-uri'
+
+require 'exceptions/web_api_exception'
+
+# This adds support for Steam Web API to classes needing this functionality.
+# 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.
+module WebApi
+
+  @@api_key = nil
+
+  # Returns the Steam Web API key
+  def self.api_key
+    @@api_key
+  end
+
+  # Sets the Steam Web API key.
+  #
+  # [+api_key+] The 128bit API key that has to be requested from
+  #             http://steamcommunity.com/dev
+  def self.api_key=(api_key)
+    unless api_key.nil? || api_key.match(/^[0-9A-F]{32}$/)
+      raise WebApiException.new(:invalid_key)
+    end
+
+    @@api_key = api_key
+  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 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
+  def self.json(interface, method, version = 1, params = nil)
+    load(: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
+  def self.json!(interface, method, version = 1, params = nil)
+    data = json(interface, method, version, params)
+    result = JSON.parse(data, { :symbolize_names => true })[:result]
+
+    status = result[:status]
+    if status != 1
+      raise WebApiException.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.
+  #
+  # [+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)
+    version = version.to_s.rjust(4, '0')
+    url = "http://api.steampowered.com/#{interface}/#{method}/v#{version}/"
+    params = {} unless params.is_a?(Hash)
+    params[:format] = format
+    params[:key] = WebApi.api_key
+
+    unless params.nil? && params.empty?
+      url += '?' + params.map { |k,v| "#{k}=#{v}" }.join('&')
+    end
+
+    begin
+      open(url, { :proxy => true }).read
+    rescue OpenURI::HTTPError
+      status = $!.io.status[0]
+      raise WebApiException.new(:unauthorized) if status[0].to_i == 401
+      raise WebApiException.new(:http_error, status[0].to_i, status[1])
+    end
+  end
+
+end

data/lib/steam/packets/a2s_player_packet.rb

@@ -10,8 +10,8 @@ require 'steam/packets/steam_packet'
 # server.
 class A2S_PLAYER_Packet
 
-  include RequestWithChallenge
   include SteamPacket
+  include RequestWithChallenge
 
   # Creates a new A2S_PLAYER request object including the challenge_number
   def initialize(challenge_number = -1)

data/lib/steam/packets/a2s_rules_packet.rb

@@ -1,16 +1,16 @@
 # 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/packets/request_with_challenge'
 require 'steam/packets/steam_packet'
 
-# Creates a new A2A_RULES request object including the challenge_number
+# Creates a new A2S_RULES request object including the challenge_number
 class A2S_RULES_Packet
 
-  include RequestWithChallenge
   include SteamPacket
+  include RequestWithChallenge
 
   # Creates a new A2S_RULES request object including the challenge_number
   def initialize(challenge_number = -1)

data/lib/steam/packets/c2m_checkmd5_packet.rb

@@ -0,0 +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
+
+require 'steam/packets/steam_packet'
+
+# The C2M_CHECKMD5 packet type is used to initialize (challenge) master server
+# communication.
+class C2M_CHECKMD5_Packet
+
+  include SteamPacket
+
+  # Creates a new challenge request packet for master server communication
+  def initialize
+    super C2M_CHECKMD5_HEADER
+  end
+
+  # Returns a byte array representation of the packet data
+  def to_s
+    [@header_data, 0xFF].pack('c2')
+  end
+
+end

data/lib/steam/packets/m2c_isvalidmd5_packet.rb

@@ -0,0 +1,25 @@
+# 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
+
+require 'steam/packets/steam_packet'
+
+# A packet of type M2S_ISVALIDMD5 is used by the master server to provide a
+# challenge number to a game server
+class M2C_ISVALIDMD5_Packet
+
+  include SteamPacket
+
+  # Returns the challenge number to use for master server communication
+  attr_reader :challenge
+
+  # Creates a new response packet with the data from the master server
+  def initialize(data)
+    super M2C_ISVALIDMD5_HEADER, data
+
+    @content_data.byte
+    @challenge = @content_data.long
+  end
+
+end

data/lib/steam/packets/m2s_requestrestart_packet.rb

@@ -0,0 +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) 2011, Sebastian Staudt
+
+require 'steam/packets/steam_packet'
+
+# The M2S_REQUESTRESTART packet type is used to by master servers to request a
+# game server restart, e.g. when using outdated versions.
+class M2S_REQUESTRESTART_Packet
+
+  include SteamPacket
+
+  # Returns the challenge number used for master server communication
+  attr_reader :challenge
+
+  # Creates a new server restart request packet sent by a master server
+  def initialize(data)
+    super C2M_CHECKMD5_HEADER, data
+
+    @challenge = @content_data.long
+  end
+
+end

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

@@ -22,7 +22,7 @@ module RCONPacket
     @request_id = request_id
   end
 
-  def bytes
+  def to_s
     [@content_data.length + 8, @request_id, @header_data, @content_data.string].pack('V3a*')
   end
 

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

@@ -16,7 +16,6 @@ module RCONPacketFactory
   def self.packet_from_data(raw_data)
     byte_buffer = StringIO.new raw_data
 
-    byte_buffer.long
     request_id = byte_buffer.long
     header = byte_buffer.long
     data = byte_buffer.cstring

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

@@ -0,0 +1,20 @@
+# 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
+
+require 'steam/packets/rcon/rcon_packet'
+
+# This class is used to determine the end of a RCON response from Source
+# servers. Packets of this type are sent after the actual RCON command and the
+# empty response packet from the server will indicate the end of the response.
+class RCONTerminator
+
+  include RCONPacket
+
+  # Creates a new RCONTerminator instance for the given request ID
+  def initialize(request_id)
+    super request_id, RCONPacket::SERVERDATA_RESPONSE_VALUE, nil
+  end
+
+end

data/lib/steam/packets/s2a_info2_packet.rb

@@ -1,12 +1,12 @@
 # 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/packets/s2a_info_base_packet'
 
-# The S2A_INFO2_Packet class represents the response to a A2A_INFO
-# request send to a Source server.
+# The S2A_INFO2_Packet class represents the response to a A2S_INFO request sent
+# to a Source server.
 class S2A_INFO2_Packet
 
   include S2A_INFO_BasePacket