gamequery 0.1.1

data/bin/gamequerytool

@@ -0,0 +1,566 @@
+#!/usr/bin/env ruby
+################################################################
+#
+# gamequerytool - query game servers
+#
+# (C) 2006 Erik Hollensbe <erik@hollensbe.org>, License details below
+#
+# Use 'gamequerytool -h' for usage instructions.
+#
+# The compilation of software known as gamequerytool is distributed under the
+# following terms:
+# Copyright (C) 2005-2006 Erik Hollensbe. All rights reserved.
+#
+# Redistribution and use in source form, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+#
+# THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+# SUCH DAMAGE.
+#
+################################################################
+
+
+#
+# rubygems hack
+#
+
+begin
+  require 'rubygems'
+rescue LoadError => e
+end
+begin
+  require 'gamequery'
+  require 'ip'
+rescue LoadError => e
+  $stderr.puts "gamequerytool requires the gamequery and ip libraries be installed."
+  $stderr.puts "You can find them both via rubygems or at http://rubyforge.org."
+  exit -1
+end
+
+GAMEQUERYTOOL_VERSION = "0.1.0"
+
+require 'optparse'
+require 'ostruct'
+require 'rexml/document'
+require 'rexml/element'
+require 'rexml/xmldecl'
+require 'csv'
+
+#
+# Option parser
+#
+
+def get_options
+  options = OpenStruct.new
+  # our options
+  options.ip_address  = nil
+  options.port        = nil
+  options.output_type = :standard
+  options.query_type  = nil
+  options.server_type = nil
+  options.region      = :other
+  options.verbose     = false
+  options.filters     = []
+
+  optparse = OptionParser.new do |opts|
+    opts.banner = "Usage: #{File.basename $0} <ip_address:port> [options]"
+    opts.separator ""
+    opts.separator "Required Arguments:"
+
+    opts.on("-s", "--server-type [TYPE]", [:hlds, :source],
+            "Type of server to contact:",
+            "\thlds: Half-Life 1 based servers",
+            "\tsource: Half-Life 2 based servers") do |server_type|
+      options.server_type = server_type
+    end
+
+    opts.on("-m", "--master-query", "Run a master server query instead of a normal one") do
+      unless options.query_type.nil?
+        $stderr.puts "Error: Master and Server queries are incompatible."
+        $stderr.puts opts
+        exit -1
+      end
+
+      options.query_type = :master
+    end
+
+    opts.on("-q", "--query-type [TYPE]", [:info, :players, :rules, :full, :ping],
+            "Type of (server-oriented) query (incompatible with -m):",
+            "\tping: get alive status and response time",
+            "\tinfo: server information query",
+            "\tplayers: player information query",
+            "\trules: rules information query",
+            "\tfull: combines info/players/rules") do |query_type|
+
+      unless options.query_type.nil?
+        $stderr.puts "Error: Master and Server queries are incompatible."
+        $stderr.puts opts
+        exit -1
+      end
+
+      options.query_type = query_type
+    end
+
+    opts.separator ""
+    opts.separator "Options:"
+
+    opts.on("-r", "--region [REGION]", 
+            [:us_east, :us_west, :south_america, 
+              :europe, :asia, :australia, :middle_east,
+              :africa, :other],
+            "Region for master server query:",
+            "\tus_east, us_west, south_america, europe, asia,",
+            "\taustralia, middle_east, africa, or other (the default)") do |region|
+      options.region = region
+    end
+
+    opts.on("-o", "--output-type [TYPE]", [:standard, :xml, :csv],
+            "Type of output to produce (standard, xml, csv)") do |output_type|
+      options.output_type = output_type
+    end
+
+    opts.on("-v", "--[no-]verbose", 
+            "Run verbosely.") do |verbose|
+      options.verbose = verbose
+    end
+
+    opts.on("-h", "--help", "This help message.") do
+      $stderr.puts opts
+      exit -1
+    end
+
+    opts.on("--version", "Print the version information.") do
+      $stderr.puts "This is gamequerytool version #{GAMEQUERYTOOL_VERSION},"
+      $stderr.puts "it is located at #{File.expand_path $0}."
+      exit -1
+    end
+
+    opts.separator ""
+    opts.separator "Filters (only work with Master Server Queries):"
+
+    opts.on("--filter-empty", "Remove empty servers from the listing.") do
+      options.filters.push [:empty, true]
+    end
+
+    opts.on("--filter-full", "Remove full servers from the listing.") do
+      options.filters.push [:full, true]
+    end
+
+    opts.on("--filter-insecure", "Remove insecure servers from the listing") do
+      options.filters.push [:secure, true]
+    end
+
+    opts.on("--filter-dedicated-only", "Show dedicated servers only") do 
+      options.filters.push [:type, 'd']
+    end
+
+    opts.on("--filter-linux-only", "Show servers running on the Linux OS") do
+      options.filters.push [:linux, true]
+    end
+    
+    opts.on("--filter-proxy-only", "Show spectator proxy servers") do |spec|
+      options.filters.push [:proxy, spec]
+    end
+
+    opts.on("--filter-gamedir [GAMEDIR]", "Only show servers running under [GAMEDIR] (mod)") do |gd|
+      options.filters.push [:gamedir, gd]
+    end
+
+    opts.on("--filter-map [MAPNAME]", "Only show servers running [MAPNAME]") do |map|
+      options.filters.push [:map, map]
+    end
+    
+    opts.separator ""
+    opts.separator "Note: the default IP:port combination will be used with master queries if one is not provided."
+    opts.separator ""
+  end
+
+  if ARGV[0].nil?
+    $stderr.puts optparse
+    exit -1
+  end
+
+  ip, port = [nil, nil]
+
+  #
+  # validate the IP:port specification if we have one.
+  #
+  
+  unless ARGV[0].match(/^-/)
+    error = false
+    ip, port = ARGV.shift.split(":")
+    begin
+      ip = IP::Address.new(ip)
+      tmp = port.to_i
+      error = true if tmp.to_s != port
+      port = tmp
+    rescue IP::AddressException => e
+      error = true
+    end
+
+    if error
+      $stderr.puts "Please use a valid IP:port specification."
+      $stderr.puts optparse
+      exit -1
+    end
+  end
+
+  optparse.parse!
+
+  options.ip_address = ip ? ip.ip_address : nil
+  options.port = port
+
+  if (ip.nil? or port.nil?) and options.query_type != :master
+    $stderr.puts "Server queries require a IP:port specification."
+    $stderr.puts optparse
+    exit -1
+  end
+  
+  if [options.query_type, options.server_type].include? nil
+    $stderr.puts "Query type and Server type are required."
+    $stderr.puts optparse
+    exit -1
+  end
+
+  return options
+
+end
+
+#
+# Verbose output
+#
+
+def verbose(string)
+  $stderr.puts string if $options.verbose
+end
+
+#
+# Output an assembled XML document.
+#
+
+def output_xml(root)
+  verbose("Writing XML")
+  REXML::XMLDecl.new("1.0").write($stdout, 2)
+  $stdout.puts
+  REXML::Document.new.add(root).write($stdout, 2)
+end
+
+#
+# Output master server query information according to format.
+#
+
+def output_master_query(queryinfo)
+  case $options.output_type
+  when :standard
+    verbose("Outputting in standard mode")
+    queryinfo.each { |server| puts "#{server.ip}:#{server.port}" }
+  when :xml
+    verbose("Outputting in XML mode")
+    root   = REXML::Element.new("gamequery")
+    master = REXML::Element.new("master")
+    server = REXML::Element.new("server")
+    ip     = REXML::Element.new("ip")
+    port   = REXML::Element.new("port")
+
+    master.add_attribute("type", $options.server_type)
+    root.add_element(master)
+    
+    queryinfo.each do |s|
+      s_ip        = REXML::Element.new(ip)
+      s_port      = REXML::Element.new(port)
+      s_ip.text   = s.ip
+      s_port.text = s.port
+      s_server    = REXML::Element.new(server)
+      s_server.add_element(s_ip)
+      s_server.add_element(s_port)
+      master.add_element(s_server)
+    end
+
+    output_xml(root)
+  when :csv
+    verbose("Outputting in CSV mode")
+    
+    queryinfo.each do |server|
+      puts CSV.generate_line([server.ip, server.port])
+    end
+  end
+end
+
+#
+# Output server query information according to format.
+#
+
+def output_server_query(queryinfo)
+  case $options.output_type
+  when :standard
+    verbose("Outputting in standard mode")
+    if queryinfo[:info]
+      verbose("Outputting server information")
+      info = queryinfo[:info]
+      format = "%-20.20s | %37.37s"
+      puts "Server Information:"
+      puts "-" * 60
+      [ 
+        ["Server Name", info.server_name],
+        ["Game", info.game_description],
+        ["Mod Name (gamedir)", info.gamedir],
+        ["Map", info.map],
+        ["Players", "#{info.numplayers}/#{info.maxplayers}"],
+        ["Bots", info.numbots],
+        ["Server OS", info.os],
+        ["Dedicated", info.dedicated ? 'yes' : 'no'],
+        ["Require Password", info.password ? 'yes' : 'no'],
+        ["Using VAC", info.secure ? 'yes' : 'no'],
+      ].each { |feh| puts format % feh }
+      puts
+    end
+    if queryinfo[:players]
+      verbose("Outputting player information")
+      format = "%3.3s | %35.35s | %5.5s | %8.8s"
+      puts "Player List: #{queryinfo[:players].num_players} players"
+      puts "%3.3s | %35.35s | %5.5s | %8.8s " % %w(No. Name Kills Time) 
+      puts "-" * 60
+      queryinfo[:players].each do |player|
+        seconds  = player.time.ceil
+        minutes  = seconds / 60
+        hours    = minutes / 60
+
+        seconds -= minutes * 60
+        minutes -= hours * 60
+
+        time = "#{"%02d" % (hours > 0 ? hours : 0)}:#{"%02d" % (minutes > 0 ? minutes : 0)}:#{"%02d" % seconds}"
+
+        puts format % [player.index, player.name, player.kills, time]
+      end
+      puts
+    end
+    if queryinfo[:rules]
+      verbose("Outputting rule information")
+      puts "Rules: #{queryinfo[:rules].num_rules}"
+      puts "-" * 60
+      format = "%-25.25s | %32.32s"
+      queryinfo[:rules].rules.each_key { |rule_name| puts format % [rule_name,queryinfo[:rules].rules[rule_name]] }
+      puts
+    end
+    if queryinfo[:ping]
+      verbose("Outputting ping information")
+      ping = queryinfo[:ping] == -1 ? 'Unable to contact' : "#{queryinfo[:ping]}ms"
+      puts "Ping: #{ping}"
+      puts
+    end
+  when :xml
+    verbose("Outputting in XML mode")
+    root   = REXML::Element.new("gamequery")
+    server = REXML::Element.new("server")
+
+    server.add_attribute("ip_address", $options.ip_address)
+    server.add_attribute("port", $options.port)
+
+    root.add_element(server)
+
+    if queryinfo[:info]
+      verbose("Outputting server information")
+      info = REXML::Element.new("info")
+      server.add_element(info)
+      
+      [:type, :version, :server_name, :map, :gamedir, :game_description,
+        :appid, :numplayers, :maxplayers, :numbots, :dedicated, :os, :password, 
+        :secure, :game_version, :host, :modded, :mod_info, :mod_download_ftp,
+        :mod_version, :mod_size, :mod_server_side, :mod_custom_client, :response_type].each do |sym|
+        
+        node = REXML::Element.new(sym.to_s)
+        node.text = queryinfo[:info].send(sym).to_s
+        info.add_element(node)
+      end
+    end
+    if queryinfo[:players]
+      verbose("Outputting player information")
+      players = REXML::Element.new("players")
+      player  = REXML::Element.new("player")
+      name    = REXML::Element.new("name")
+      index   = REXML::Element.new("index")
+      time    = REXML::Element.new("time")
+      kills   = REXML::Element.new("kills")
+
+      server.add_element(players)
+      
+      queryinfo[:players].each do |p|
+        p_player = REXML::Element.new(player)
+        p_name   = REXML::Element.new(name)
+        p_index  = REXML::Element.new(index)
+        p_time   = REXML::Element.new(time)
+        p_kills  = REXML::Element.new(kills)
+        
+        p_name.text  = p.name
+        p_index.text = p.index
+        p_time.text  = p.time
+        p_kills.text = p.kills
+
+        [p_name, p_index, p_time, p_kills].each { |x| p_player.add_element(x) }
+        players.add_element(p_player)
+      end
+    end
+    if queryinfo[:rules]
+      verbose("Outputting rule information")
+      rules = REXML::Element.new("rules")
+      rule  = REXML::Element.new("rule")
+      rules.add_attribute("amount", queryinfo[:rules].num_rules)
+
+      queryinfo[:rules].rules.each_key do |rule_name| 
+        new_rule = REXML::Element.new(rule)
+        new_rule.add_attribute("name", rule_name)
+        new_rule.text = queryinfo[:rules].rules[rule_name]
+        rules.add_element(new_rule)
+      end
+
+      server.add_element(rules)
+    end
+    if queryinfo[:ping]
+      verbose("Outputting ping information")
+      ping = REXML::Element.new("ping")
+      ping.text = queryinfo[:ping]
+      server.add_element(ping)
+    end
+    
+    output_xml(root)
+  when :csv
+    verbose("Outputting in CSV mode")
+
+    if queryinfo[:info]
+      [:type, :version, :server_name, :map, :gamedir, :game_description,
+        :appid, :numplayers, :maxplayers, :numbots, :dedicated, :os, :password, 
+        :secure, :game_version, :host, :modded, :mod_info, :mod_download_ftp,
+        :mod_version, :mod_size, :mod_server_side, :mod_custom_client, :response_type].each do |sym|
+        puts CSV.generate_line(["info", sym, queryinfo[:info].send(sym).to_s.chomp])
+      end
+    end
+    if queryinfo[:players]
+      queryinfo[:players].each do |player|
+        puts CSV.generate_line(["player", player.index, player.name, player.kills, player.time])
+      end
+    end
+    if queryinfo[:rules]
+      queryinfo[:rules].rules.each_key do |rule_name|
+        puts CSV.generate_line(["rule", rule_name, queryinfo[:rules].rules[rule_name]])
+      end
+    end
+    if queryinfo[:ping]
+      puts CSV.generate_line(["ping", queryinfo[:ping]])
+    end
+  end
+end
+
+#
+# Automates server queries, for those types
+# that actually use multiple queries.
+#
+
+def server_query(gq, type)
+  verbose("Initiating '#{type.to_s}' server query to #{$options.ip_address}:#{$options.port}")
+  case type
+  when :info
+    return gq.get_info
+  when :players
+    return gq.get_players
+  when :rules
+    return gq.get_rules
+  when :ping
+    t = (Time.now.to_f * 1000).ceil
+    if gq.ping
+      t2 = (Time.now.to_f * 1000).ceil
+      return t2 - t
+    end
+    return -1
+  end
+end
+
+################################################################
+#
+# Start main code
+#
+################################################################
+
+$options = get_options
+
+begin
+
+  case $options.query_type
+  when :master
+    region_map = {
+      :us_east       => GameQuery::Master::Steam::REGION_US_EAST,
+      :us_west       => GameQuery::Master::Steam::REGION_US_WEST,
+      :south_america => GameQuery::Master::Steam::REGION_SOUTH_AMERICA,
+      :europe        => GameQuery::Master::Steam::REGION_EUROPE,
+      :asia          => GameQuery::Master::Steam::REGION_ASIA,
+      :australia     => GameQuery::Master::Steam::REGION_AUSTRALIA,
+      :middle_east   => GameQuery::Master::Steam::REGION_MIDDLE_EAST,
+      :africa        => GameQuery::Master::Steam::REGION_AFRICA,
+      :other         => GameQuery::Master::Steam::REGION_OTHER
+    }
+
+    if $options.ip_address.nil?
+      $options.ip_address = GameQuery::Master::Steam::MASTER_SERVER
+      
+      case $options.server_type
+      when :hlds
+        $options.port = GameQuery::Master::Steam::HLDS_MASTER_PORT
+      when :source
+        $options.port = GameQuery::Master::Steam::SOURCE_MASTER_PORT
+      end
+    end
+    
+    verbose("Initiating #{$options.server_type} master query for region '#{$options.region}' to #{$options.ip_address}:#{$options.port}")
+
+    gq = GameQuery::Master::Steam.new($options.ip_address,
+                                      $options.port,
+                                      region_map[$options.region])
+    $options.filters.each do |filter|
+      verbose("Setting filter #{filter[0]} = #{filter[1]}")
+      gq.filter.send((filter[0].to_s + '=').to_sym, filter[1])
+    end
+    verbose("Outputting return data")
+    output_master_query(gq.send_query)
+  else
+    gq = GameQuery::Server::Steam.new($options.ip_address, $options.port)
+    case $options.query_type
+    when :full
+      info    = server_query(gq, :info)
+      players = server_query(gq, :players)
+      rules   = server_query(gq, :rules)
+      ping    = server_query(gq, :ping)
+      output_server_query({
+                            :info    => info,
+                            :players => players,
+                            :rules   => rules,
+                            :ping    => ping
+                          })
+    else
+      output_server_query({ $options.query_type => server_query(gq, $options.query_type) })
+    end
+  end
+  
+rescue GameQuery::ConnectException => e
+  $stderr.puts "Error: A connection error occured (perhaps the host isn't available?)"
+  exit -1
+rescue GameQuery::ParseException => e
+  $stderr.puts "Error: The tool had trouble processing the response from the server."
+  exit -1
+rescue Exception => e
+  $stderr.puts "Error: An unknown error occured (#{e.class.to_s})"
+  verbose(e.backtrace.join("\n"))
+  exit -1
+end
+
+exit 0

data/lib/gamequery.rb

@@ -0,0 +1,775 @@
+require 'socket'
+
+#
+# GameQuery - Query game servers
+#
+# Version:: 0.1.1
+# Author:: Erik Hollensbe <erik@hollensbe.org>
+# License:: BSD
+# Contact:: erik@hollensbe.org
+# Copyright:: Copyright (c) 2005-2006 Erik Hollensbe
+#
+# = Synopsis
+#
+#   # returning a master server query
+#   gq = GameQuery::Master::Steam.new(
+#          GameQuery::Master::Steam::MASTER_SERVER,
+#          GameQuery::Master::Steam::SOURCE_MASTER_PORT,
+#          GameQuery::Master::Steam::REGION_OTHER)
+#   gq.send_query.each { |server| puts [server.ip, server.port].join(":") }
+#
+#   # getting a query from a specific server
+#   gq = GameQuery::Server::Steam.new('127.0.0.1', 27015)
+#   gq.get_info.maxplayers => 20
+#
+# = Note
+# 
+# While expansion is planned, current queries are limited
+# to Valve Software's "Steam"-based games: Half-Life 1 (Goldsrc) and
+# Half-Life 2 (Source) games in particular. Hunting down the little
+# differences in several of the protocols not yet supported has
+# produced troublesome results, especially when it comes to finding
+# the equivalent of a 'master' server to query to find guinea pigs to
+# test against. As a result, I will gladly accept patches that help
+# with other game types.
+#
+# = Class Structure
+#
+# GameQuery has a similar class structure to my other game-related
+# module, RCon. There are several important namespaces:
+#
+# == GameQuery::Master
+#
+# This contains classes that query master server databases. In game
+# parlance, this means that this is a server you query to get the
+# names of active, registered servers. The current classes supported
+# are:
+# 
+# * GameQuery::Master::Steam - Query Steam master servers
+#       * GameQuery::Master::Steam::Filter - Helper class to build
+#         Steam-based master query filters.
+#
+# == GameQuery::Server
+#
+# This namespace has classes to get data from individual servers.
+#
+# * GameQuery::Server::Steam - Query Steam servers
+#
+# == GameQuery::Response
+#
+# Contains classes to return well-formed responses, and in the right
+# cases, provide operations on the response set.
+#
+# * GameQuery::Response::Master - Responses from master servers of any
+#   type. 
+# * GameQuery::Response::Steam - Several specific responses that
+#   related to querying steam-based servers.
+#       * GameQuery::Response::Steam::Info - Returns info about the server
+#         itself. 
+#       * GameQuery::Response::Steam::Player - Returns info about the
+#         players that are on the server.
+#       * GameQuery::Response::Steam::Rules - Returns info about the rules
+#         that the server has set.
+#
+# == Exception Classes
+#
+# * GameQuery::ConnectException - Thrown when a connect was attempted
+#   but failed
+# * GameQuery::ParseException - Thrown when data was improperly
+#   parsed.
+#
+# = Further Documentation
+#
+# Please see the individual RDoc for each listed class for more
+# information on usage.
+#
+
+class GameQuery
+
+  #
+  # Thrown in the case of a connection attempt that resulted in an
+  # error. Please see individual methods to locate what throws this.
+  #
+
+  class ConnectException < Exception
+  end
+
+  #
+  # Thrown in the case of a connection attempt that resulted in an
+  # error. Please see individual methods to locate what throws this.
+  #
+
+  class ParseException < Exception
+  end
+
+  class Master #:nodoc:
+
+    #
+    # Used for master queries to get lists of steam-based servers
+    #
+    # See GameQuery::Master::Steam.new for more information.
+    #
+
+    class Steam
+
+      # master server IP addresses and ports
+
+      MASTER_SERVER      = "207.173.177.11"
+      SOURCE_MASTER_PORT = 27011
+      HLDS_MASTER_PORT   = 27010
+
+      # region codes
+
+      REGION_US_EAST       = 0x00
+      REGION_US_WEST       = 0x01
+      REGION_SOUTH_AMERICA = 0x02
+      REGION_EUROPE        = 0x03
+      REGION_ASIA          = 0x04
+      REGION_AUSTRALIA     = 0x05
+      REGION_MIDDLE_EAST   = 0x06
+      REGION_AFRICA        = 0x07
+      REGION_OTHER         = 0xFF
+
+      #
+      # Creates a new GameQuery::Master::Steam object
+      #
+      # * The region is a 8-bit integer, the accepted values are
+      #   constants in this namespace.
+      # * Server is the name of a valid master server. The constant
+      #   MASTER_SERVER contains the ip for a current working master
+      #   server that serves both HLDS and Source master lists.
+      # * Port is the port to connect to. Note that different lists
+      #   are provided on different ports. For this reason, the
+      #   constants HLDS_MASTER_PORT and SOURCE_MASTER_PORT are provided
+      #   to aid with connecting to the server listed in MASTER_SERVER.
+      #
+      # If you cannot connect to this server, you will need to provide
+      # your own server/port. The region is a part of the protocol,
+      # and most likely won't change.
+      #
+
+      attr_accessor :filter
+      attr_accessor :region
+
+      def initialize(server, port, region)
+        @server = server
+        @port = port
+        @filter = GameQuery::Master::Steam::Filter.new()
+        @region = region
+        # this is what steam sends....
+        @ip = "0.0.0.0:0"
+        self
+      end
+
+      #
+      # Sends the query and returns the output.
+      #
+      # Returns a GameQuery::Response::Master object on success.
+      #
+      # Throws a GameQuery::ConnectException if it can't read
+      # from the server.
+      #
+
+      def send_query
+        retval = []
+        packet = ""
+        
+        # send the query
+        sock = UDPSocket.new
+        sock.connect(@server, @port)
+        sock.print [?1, @region, @ip, @filter.generate_filter_data].pack("CCZ*Z*")
+
+        raise GameQuery::ConnectException.new unless IO.select([sock], nil, nil, 10)
+
+        # get the return
+        loop do 
+          tmp = sock.recv(8192)
+          packet << tmp
+          break if tmp.length < 8192
+          break unless IO.select([sock], nil, nil, 10)
+        end
+        
+        # strip first 6 bytes
+        packet = packet[6..-1]
+
+        while packet.length > 0
+          tmp = packet.slice!(0..5)
+
+          # type switch: String -> Array
+
+          # NOTE: Valve uses network signed here for the port, which
+          # is uncharacteristic compared to other protocols 
+          tmp = tmp.unpack("CCCCn")
+                              
+          port = tmp.pop.to_s
+          retval.push([tmp.join('.'), port])
+        end
+       
+        return GameQuery::Response::Master.new(retval)
+      end
+         
+      #
+      # Compose filters to send to the steam master servers.
+      #
+      # == Filter names and acceptable data
+      #
+      # Values that take 1/0 can also be set to true/false, the value
+      # being converted at set time. 
+      #
+      # type:: this is either 'd' or 'l', for dedicated or listen servers. 
+      # secure:: this is 1 or 0 depending on VAC support.
+      # gamedir:: this is the name of the 'game directory' or mod that you want to query specifically for.
+      # map:: name of map.
+      # linux:: set to 1 to only get linux servers back. 0 will return all servers.
+      #--
+      # TODO: really, empty/full should be fixed.
+      #++
+      # empty:: set to 1 to get servers that aren't empty.
+      # full:: set to 1 to get servers that aren't full.
+      # proxy:: set to 1 to get servers that are spectator proxies.
+      #
+      # == Usage
+      # 
+      # All methods are accessor-style, meaning you can do this:
+      #
+      #    f = GameQuery::Master::Steam::Filter.new
+      #    f.empty = 1
+      #    f.empty # returns '\empty\1'
+      #
+      # And so on.
+      #
+
+      class Filter
+ 
+        TYPES = [:type, :secure, :gamedir, :map, :linux, :empty, :full, :proxy]
+
+        TYPES.each do |type|
+          method_name = (type.to_s + '=').to_sym
+          
+          GameQuery::Master::Steam::Filter.send(:define_method, type) do
+            x = nil
+            self.instance_eval("x = @{#type.to_s}")
+            x
+          end
+          GameQuery::Master::Steam::Filter.send(:define_method, method_name) do |s|
+            # coerce true/false to numeric equivalents
+            if s == true or s == false
+              s = s ? 1 : 0
+            end
+
+            s = s.to_s
+
+            if s.nil? or s.length == 0
+              self.instance_variable_set(("@"+type_to_s).to_sym, nil)
+            else
+              self.instance_variable_set(("@"+type.to_s).to_sym, "\\#{type.to_s}\\#{s}")
+            end
+          end
+        end
+ 
+        #
+        # This returns the string containing the filter definitions
+        # formatted for use in a Steam master query.
+        #
+        # It does not include items that are set to nil.
+        #
+
+        def generate_filter_data
+          return [@type, @secure, @gamedir, 
+            @map, @linux, @empty, 
+            @full, @proxy].reject { |x| x.nil? }.join("")
+        end
+
+      end # Filter
+    end # Steam
+  end # Master
+
+  class Server #:nodoc:
+
+    #
+    # Query Servers that answer to the Steam network protocols.
+    #
+    # Those familiar with the protocol know that a challenge must be
+    # sent: this suite does it, but the challenge protocol is not
+    # exposed (for a variety of reasons). The challenge value is
+    # treated ephemeral and is generated for each query that requires
+    # it.
+    #
+    # The +get_info+ routine does not require a challenge.
+    #
+    # All public methods in this class will return a
+    # GameQuery::ConnectException on connection failure or error.
+    #
+    #--
+    # valve's best docs on this are at:
+    # http://www.valve-erc.com/srcsdk/Code/Networking/serverqueries.html#A2S_INFO
+    #++
+
+    class Steam
+
+      #
+      # Instantiate a new GameQuery::Server::Steam object
+      #
+      # Takes a server and a port.
+      #
+
+      def initialize(server, port)
+        @server = server
+        @port = port
+        @sock = nil
+      end
+      
+      #
+      # Sends a query to get all the information from a server
+      # regarding the players that are on it.
+      #
+      # Returns a GameQuery::Response::Steam::Player object.
+      #
+
+      def get_players
+        challenge = get_challenge
+        
+        @sock.print [0xFFFFFFFF, 0x55, challenge].pack("VCV")
+        packet = read_socket
+        
+        # response header
+
+        response_code, num_players = packet.slice!(0..1).unpack("aC")
+
+        players = []
+        
+        while packet.length > 0
+          tmp = packet.unpack("CZ*")
+          
+          len = tmp[1].length
+          packet.slice!(0..len+1)
+          
+          # we have to do this to ensure that size is proper when decoding little-endian floats. (arg)
+          # this may not work at all.
+          tmp.push(packet.slice!(0..7).unpack("Ve"))
+          
+          # BUG: the kills amount (tmp[2]) has an odd anomaly that I haven't tracked down yet.
+          # however, when this bug occurs, the amount filled in the kills portion is 4294967295
+          # I imagine it's a packing issue.
+
+          tmp.flatten!
+          players.push(tmp)
+        end
+
+        return GameQuery::Response::Steam::Player.new(num_players, players)
+      end
+
+      #
+      # Returns the rules for the server as a
+      # GameQuery::Response::Steam::Rules object.
+      #
+
+      def get_rules
+        challenge = get_challenge
+        
+        @sock.print [0xFFFFFFFF, 0x56, challenge].pack("VCV")
+        packet = read_socket
+        require 'pp'
+
+        # HL1 responses are different here, as well.
+        # there is some garbage (an extra 9 bytes) that is sent along with
+        # HL1 responses. Since the response code is supposed to be the same,
+        # we can rely on that to find out if we need to remove extra bytes.
+
+        response_code, num_rules = packet.slice!(0..2).unpack("av")
+
+        if response_code != 'E'
+          # if we're here, HL1 will send additional data every packet.
+          # to the best of my knowledge, this is junk.
+          # HACK: THIS IS A HORRIBLE MESS
+          packet.sub!(/\376\377\377\377.{5}/, "")
+          # pull the 6 bytes off the front.
+          packet.slice!(0..5)
+          # do it again
+          response_code, num_rules = packet.slice!(0..2).unpack("av")
+        end
+
+        rules = []
+        
+        while packet.length > 0
+          tmp = packet.unpack("Z*Z*")
+          # length of each, + 1 for the nulls
+          packet.slice!(0..(tmp[0].length + tmp[1].length + 1))
+          rules.push(tmp)
+        end
+
+        return GameQuery::Response::Steam::Rules.new(num_rules, rules)
+      end
+
+      #
+      # Gets information about the server itself. Returns a
+      # GameQuery::Response::Steam::Info object.
+      #
+      # Note that while the query sent is the same for both HL2 and
+      # HL1, the responses are quite different, and while much of the
+      # data overlaps, not all of it does. HL1 and HL2 responses will
+      # contains different sets of data as a result. The remaining
+      # fields will be set to 'nil'.
+      #
+
+      def get_info
+        # NOTE: no challenge is needed here
+        establish_connection
+
+        @sock.print [0xFFFFFFFF, ?T, "Source Engine Query"].pack("VCZ*")
+        packet = read_socket
+        #
+        # HL1 and HL2 take the same query, but they provide separate (?!?!) responses
+        # we'll have to parse out the type first, so we know how to unpack the rest of
+        # the output.
+        #
+        type = packet.unpack("a")[0]
+        
+        ary = nil
+        if type == 'I'
+          # HL2
+          return GameQuery::Response::Steam::Info.new(packet.unpack("CCZ*Z*Z*Z*vCCCaaCCZ*"),
+                                                       GameQuery::Response::Steam::Info::SOURCE)
+        elsif type == 'm'
+          # HL1
+          return GameQuery::Response::Steam::Info.new(packet.unpack("CZ*Z*Z*Z*Z*CCCaaCCZ*Z*Z*VVCCCC"),
+                                                       GameQuery::Response::Steam::Info::HLDS)
+        end
+
+        # we don't know what it is, annoy our user with an error!
+        raise GameQuery::ParseException.new
+
+      end
+
+      #
+      # Pings the server. Merely returns a true/false depending on if
+      # the server responded.
+      #
+      # While HL1 still supports the legacy ping protocol, HL2 doesn't
+      # (and doesn't appear to have a replacement
+      # implementation). What we do here is send a challenge and
+      # return true/false depending on if we got a response that
+      # makes sense.
+      #
+      # Recording response time is the user's responsibility.
+      #
+
+      def ping
+        return ! get_challenge.nil?
+      end
+
+      ################################################################
+      #
+      # BEGIN PRIVATE METHODS
+      #
+      ################################################################
+
+      private
+      
+      #
+      # Obtain a challenge value
+      #
+      
+      def get_challenge
+        establish_connection
+
+        @sock.print [0xFFFFFFFF, 0x57].pack("VC")
+        return read_socket.unpack("aV")[1]
+      end
+
+      #
+      # Create a socket if it's needed
+      #
+
+      def establish_connection
+        if @sock.nil?
+          @sock = UDPSocket.new
+          @sock.connect(@server, @port)
+        end
+      end
+
+      
+      #
+      # Read from the socket and return a response. Throws a
+      # GameQuery::ConnectException on IO.select troubles.
+      #
+
+      def read_socket
+        packet = ""
+
+        raise GameQuery::ConnectException.new unless IO.select([@sock], nil, nil, 10)
+
+        # get the return
+        loop do 
+          tmp = @sock.recv(8192)
+          packet << tmp
+          break unless IO.select([@sock], nil, nil, 0.1)
+        end
+
+        # this is always the same value, and we never need it.
+        # NOTE: see additional work in get_rules and get_info for HL1
+        packet.slice!(0..3)
+
+        return packet
+      end
+    end
+  end # Server
+
+  class Response #:nodoc:
+
+    #
+    # Master response class.
+    #
+    # All queries which get information from something that resembles
+    # a 'master' server, or a server that provides information
+    # regarding other servers, should return an object of this type.
+    #
+    # This module mixes in the +Enumerable+ module, all methods
+    # contained in there should be available to it.
+    #
+    # It is not recommended that you construct these outside the query
+    # classes - they are merely used to provide a friendly response to
+    # queries.
+    #
+
+    class Master
+      include Enumerable
+
+      GameServer = Struct.new(:ip, :port)
+
+      #
+      # Constructor. Do not use this unless you know what you are doing.
+      #
+
+      def initialize(array)
+        @servers = []
+
+        array.each do |server|
+          @servers.push(GameServer.new(*server))
+        end
+      end
+      
+      #
+      # This will return GameQuery::Response::Master::GameServer
+      # structures each time it is called, iterating through the list
+      # of them.
+      #
+      # It's primary function is to aid the +Enumerable+ module.
+      #
+
+      def each
+        @servers.each { |server| yield server }
+      end
+    end
+
+    class Steam #:nodoc:
+
+      #
+      # Source Info class.
+      #
+      # Lots of other protocol information is included in here that
+      # most people will have no use for. I have only covered what I
+      # have deemed "important", however, most of the parts are named
+      # very similarly to the protocol documentation on the web, so if
+      # you're curious what a specific part means, please consult that.
+      #
+      # = Attributes
+      #
+      # Attributes are coerced into boolean values or native types
+      # (such as integers) whenever possible.
+      #
+      # == server_name
+      #
+      # The published name of the server, normally controlled by the
+      # 'hostname' cvar.
+      #
+      # == map
+      #
+      # The name of the map being played.
+      #
+      # == gamedir
+      #
+      # The name of the game directory loaded. This is normally the
+      # 'short name' of the modification.
+      #
+      # == game_description
+      #
+      # The name of the game (or modification) being played. This is
+      # normally the 'long name' of the modification.
+      #
+      # == numplayers
+      #
+      # Number of people currently playing on the server.
+      #
+      # == maxplayers
+      #
+      # Maximum number of people allowed on the server.
+      #
+      # == numbots
+      #
+      # Number of bots on the server.
+      #
+      # == dedicated
+      #
+      # This is set to 'true' if this server is configured to run as a
+      # 'dedicated' (no client running) server.
+      #
+      # == os
+      # 
+      # The Operating System the server runs on. 'Windows' or 'Linux'.
+      #
+      # == password
+      #
+      # Set to 'true' if a password is required.
+      # 
+      # == secure
+      #
+      # Set to 'true' if running some form of Valve Anti-Cheat.
+      #
+      # == game_version
+      #
+      # Version of the server that is running.
+      #
+      # == host
+      #
+      # IP:port information on the server. This is HL1-only.
+      #
+      # == modded
+      #
+      # 'true' if the server is running a modification. HL1-only.
+      #
+      # == mod_info, mod_download_ftp, mod_version, mod_size, mod_server_side, mod_custom_client
+      #
+      # Various server variables which are HL1-only and will only
+      # exist if 'modded' is true.
+      #
+
+      class Info
+        SOURCE = 0
+        HLDS   = 1
+
+        attr_reader(:type, :version, :server_name, :map, :gamedir, :game_description,
+                    :appid, :numplayers, :maxplayers, :numbots, :dedicated, :os, :password, 
+                    :secure, :game_version, :host, :modded, :mod_info, :mod_download_ftp,
+                    :mod_version, :mod_size, :mod_server_side, :mod_custom_client, :response_type)
+
+        def initialize(array, response_type=SOURCE)
+          case response_type
+          when SOURCE
+            @response_type = :source
+            (@type, @version, @server_name, @map, @gamedir, @game_description,
+             @appid, @numplayers, @maxplayers, @numbots, @dedicated, @os, @password,
+             @secure, @game_version) = array
+          when HLDS
+            @response_type = :hlds
+            (@type, @host, @server_name, @map, @gamedir, @game_description, @numplayers, 
+             @maxplayers, @version, @dedicated, @os, @password, @modded, @mod_info,
+             @mod_download_ftp, dummy, @mod_version, @mod_size, @mod_server_side,
+             @mod_custom_client, @secure, @numbots) = array
+          end
+          
+          # booleans to be coerced
+          @dedicated = @dedicated == 'd'
+          @password = @password == 1
+          @secure = @secure == 1
+          @modded = @modded == 1
+          @mod_server_side = @mod_server_side == 1
+          @mod_custom_client = @mod_custom_client == 1
+
+          # OS is Windows or Linux. Coerce.
+
+          @os = @os == 'w' ? 'Windows' : 'Linux'
+        end
+      end
+
+      #
+      # Source Player Info class
+      #
+      # Includes the +Enumerable+ module and all of it's
+      # functions. Allows iterating over a list of player
+      # information. See
+      # GameQuery::Response::Steam::Player::PlayerInfo for the
+      # structure of each player portion.
+      #
+      # Also, the attribute +num_players+ will return the total number
+      # of players currently on the server. This is also available via
+      # an 'info' query, if you just need that information.
+      #
+
+      class Player
+        
+        include Enumerable
+
+        #
+        # Player Information struct.
+        #
+        # +index+ is the number of player they are on the server. This
+        # number remains with them until they disconnect.
+        #
+        # +time+ is the time they have been on the server, in floating
+        # point form, in _seconds_.
+        #
+        # Also note that in HL2-based (Source) games, names can be in
+        # UTF-8. I highly recommend using the 'iconv' module to sort
+        # out how you want to best represent that information.
+        #
+
+        PlayerInfo = Struct.new(:index, :name, :kills, :time)
+
+        attr_reader :num_players
+        
+        def initialize(num_players, array)
+          @players = []
+          @num_players = num_players
+
+          array.each do |player|
+            pi = PlayerInfo.new(*player)
+            @players.push(pi)
+          end
+        end
+
+        def each
+          @players.each { |player| yield player }
+        end
+      end
+
+      
+      #
+      # Source Rules Info Class
+      #
+      # +num_rules+ contains an integer value with the number of rules
+      # in the +rules+ hash
+      #
+      # +rules+ is a hash which contains the rule name as a key and
+      # the value as... the value. Every effort has been made to
+      # convert to proper types when possible.
+      #
+
+      class Rules
+        attr_reader :num_rules
+        attr_reader :rules
+        
+        def initialize(num_rules, array)
+          @num_rules = num_rules
+          @rules = Hash.new
+          
+          array.each do |rule|
+            # cheap integer conversion
+            tmp = rule[1].to_i
+            if tmp.to_s == rule[1]
+              rule[1] = tmp
+            else
+              # cheap float conversion
+              tmp = rule[1].to_f
+              if tmp.to_s == rule[1]
+                rule[1] = tmp
+              end
+            end
+
+            @rules[rule[0]] = rule[1]
+          end
+        end
+      end # Rules
+    end # Server
+  end # Response
+end # GameQuery

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: gamequery
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+date: 2006-02-28 00:00:00 -08:00
+summary: Ruby class to work with Half-Life and Source Engine "user" queries
+require_paths: 
+- lib
+email: erik@hollensbe.org
+homepage: 
+rubyforge_project: gamequery
+description: 
+autorequire: gamequery
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Erik Hollensbe
+files: 
+- lib/gamequery.rb
+- bin/gamequerytool
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: 
+- gamequerytool
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: ip
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.1
+    version: