minestat 2.3.0 → 3.0.0

data/lib/minestat.rb

@@ -22,66 +22,120 @@ require 'resolv'
 require 'socket'
 require 'timeout'
 
-##
-# Provides a ruby interface for polling Minecraft server status.
+# @author Lloyd Dilley
+
+# Provides a Ruby interface for polling the status of Minecraft servers
 class MineStat
   # MineStat version
-  VERSION = "2.3.0"
+  VERSION = "3.0.0"
+
   # Number of values expected from server
   NUM_FIELDS = 6
-  # Number of values expected from a 1.8b/1.3 server
+  private_constant :NUM_FIELDS
+
+  # Number of values expected from a 1.8b - 1.3 server
   NUM_FIELDS_BETA = 3
+  private_constant :NUM_FIELDS_BETA
+
   # Maximum number of bytes a varint can be
   MAX_VARINT_SIZE = 5
+  private_constant :MAX_VARINT_SIZE
+
   # Default TCP port
   DEFAULT_TCP_PORT = 25565
+
   # Bedrock/Pocket Edition default UDP port
   DEFAULT_BEDROCK_PORT = 19132
+
   # Default TCP/UDP timeout in seconds
   DEFAULT_TIMEOUT = 5
+
   # Bedrock/Pocket Edition packet offset in bytes (1 + 8 + 8 + 16 + 2)
-  # Unconnected pong (0x1C) = 1 byte
-  # Timestamp as a long = 8 bytes
-  # Server GUID as a long = 8 bytes
-  # Magic number = 16 bytes
-  # String ID length = 2 bytes
+  #   Unconnected pong (0x1C) = 1 byte
+  #   Timestamp as a long = 8 bytes
+  #   Server GUID as a long = 8 bytes
+  #   Magic number = 16 bytes
+  #   String ID length = 2 bytes
   BEDROCK_PACKET_OFFSET = 35
-
-  ##
-  # Stores constants that represent the results of a server ping
+  private_constant :BEDROCK_PACKET_OFFSET
+
+  # UT3/GS4 query handshake packet size in bytes (1 + 4 + 13)
+  #   Handshake (0x09) = 1 byte
+  #   Session ID = 4 bytes
+  #   Challenge token = variable null-terminated string up to 13 bytes(?)
+  QUERY_HANDSHAKE_SIZE = 18
+  private_constant :QUERY_HANDSHAKE_SIZE
+
+  # UT3/GS4 query handshake packet offset for challenge token in bytes (1 + 4)
+  #  Handshake (0x09) = 1 byte
+  #  Session ID = 4 bytes
+  QUERY_HANDSHAKE_OFFSET = 5
+  private_constant :QUERY_HANDSHAKE_OFFSET
+
+  # UT3/GS4 query full stat packet offset in bytes (1 + 4 + 11)
+  #   Stat (0x00) = 1 byte
+  #   Session ID = 4 bytes
+  #   Padding = 11 bytes
+  QUERY_STAT_OFFSET = 16
+  private_constant :QUERY_STAT_OFFSET
+
+  # These constants represent the result of a server request
   module Retval
     # The server ping completed successfully
     SUCCESS = 0
+
     # The server ping failed due to a connection error
     CONNFAIL = -1
+
     # The server ping failed due to a connection time out
     TIMEOUT = -2
+
     # The server ping failed for an unknown reason
     UNKNOWN = -3
   end
 
-  ##
-  # Stores constants that represent the different kinds of server
-  # list pings/requests that a Minecraft server might expect when
-  # being polled for status information.
+  # These constants represent the various protocols used when requesting server data
   module Request
     # Try everything
     NONE = -1
+
     # Server versions 1.8b to 1.3
     BETA = 0
+
     # Server versions 1.4 to 1.5
     LEGACY = 1
+
     # Server version 1.6
     EXTENDED = 2
+
     # Server versions 1.7 to latest
     JSON = 3
+
     # Bedrock/Pocket Edition
     BEDROCK = 4
+
+    # Unreal Tournament 3/GameSpy 4 query
+    QUERY = 5
   end
 
-  ##
-  # Instantiate an instance of MineStat and poll the specified server for information
-  def initialize(address, port = DEFAULT_TCP_PORT, timeout = DEFAULT_TIMEOUT, request_type = Request::NONE)
+  # Instantiates a MineStat object and polls the specified server for information
+  # @param address [String] Minecraft server address
+  # @param port [Integer] Minecraft server TCP or UDP port
+  # @param timeout [Integer] TCP/UDP timeout in seconds
+  # @param request_type [Request] Protocol used to poll a Minecraft server
+  # @param debug [Boolean] Enable or disable error output
+  # @return [MineStat] A MineStat object
+  # @example Simply connect to an address
+  #   ms = MineStat.new("minecraft.frag.land")
+  # @example Connect to an address on a certain TCP or UDP port
+  #   ms = MineStat.new("minecraft.frag.land", 25567)
+  # @example Same as above example and additionally includes a timeout in seconds
+  #   ms = MineStat.new("minecraft.frag.land", 25567, 3)
+  # @example Same as above example and additionally includes an explicit protocol to use
+  #   ms = MineStat.new("minecraft.frag.land", 25567, 3, MineStat::Request::QUERY)
+  # @example Connect to a Bedrock server and enable debug mode
+  #   ms = MineStat.new("minecraft.frag.land", 19132, 3, MineStat::Request::BEDROCK, true)
+  def initialize(address, port = DEFAULT_TCP_PORT, timeout = DEFAULT_TIMEOUT, request_type = Request::NONE, debug = false)
     @address = address    # address of server
     @port = port          # TCP/UDP port of server
     @online               # online or offline?
@@ -91,6 +145,8 @@ class MineStat
     @stripped_motd        # message of the day without formatting
     @current_players      # current number of players online
     @max_players          # maximum player capacity
+    @player_list          # list of players (UT3/GS4 query only)
+    @plugin_list          # list of plugins (UT3/GS4 query only)
     @protocol             # protocol level
     @json_data            # JSON data for 1.7 queries
     @favicon_b64          # base64-encoded favicon possibly contained in JSON 1.7 responses
@@ -101,13 +157,18 @@ class MineStat
     @request_type         # protocol version
     @connection_status    # status of connection ("Success", "Fail", "Timeout", or "Unknown")
     @try_all = false      # try all protocols?
+    @debug = debug        # debug mode
 
     @try_all = true if request_type == Request::NONE
     resolve_srv(address, port)
-    set_connection_status(attempt_protocols())
+    set_connection_status(attempt_protocols(request_type))
   end
 
   # Attempts to resolve SRV records
+  # @param address [String] Minecraft server address
+  # @param port [Integer] Minecraft server TCP or UDP port
+  # @return [Boolean] Whether or not SRV resolution was successful
+  # @since 2.3.0
   def resolve_srv(address, port)
     begin
       resolver = Resolv::DNS.new
@@ -115,13 +176,19 @@ class MineStat
       @address = res.target.to_s # SRV target
       @port = res.port.to_i      # SRV port
     rescue => exception          # primarily catch Resolv::ResolvError and revert if unable to resolve SRV record(s)
+      $stderr.puts exception if @debug
       @address = address
       @port = port
+      return false
     end
+    return true
   end
+  private :resolve_srv
 
   # Attempts the use of various protocols
-  def attempt_protocols()
+  # @param request_type [Request] Protocol used to poll a Minecraft server
+  # @return [Retval] Return value
+  def attempt_protocols(request_type)
     case request_type
       when Request::BETA
         retval = beta_request()
@@ -133,6 +200,8 @@ class MineStat
         retval = json_request()
       when Request::BEDROCK
         retval = bedrock_request()
+      when Request::QUERY
+        retval = query_request()
       else
         # Attempt various ping requests in a particular order. If the
         # connection fails, there is no reason to continue with subsequent
@@ -157,17 +226,24 @@ class MineStat
         unless @online || retval == Retval::SUCCESS
           retval = bedrock_request()
         end
+        # UT3/GS4 query
+        unless @online || retval == Retval::SUCCESS
+          retval = query_request()
+        end
     end
     return retval
   end
+  private :attempt_protocols
 
   # Sets connection status
+  # @param retval [Retval] Return value
   def set_connection_status(retval)
     @connection_status = "Success" if @online || retval == Retval::SUCCESS
     @connection_status = "Fail" if retval == Retval::CONNFAIL
     @connection_status = "Timeout" if retval == Retval::TIMEOUT
     @connection_status = "Unknown" if retval == Retval::UNKNOWN
   end
+  private :set_connection_status
 
   # Strips message of the day formatting characters
   def strip_motd()
@@ -187,13 +263,13 @@ class MineStat
     @stripped_motd = @stripped_motd.force_encoding('UTF-8')
     @stripped_motd = @stripped_motd.gsub(/§./, "")
   end
+  private :strip_motd
 
-  ##
   # Establishes a connection to the Minecraft server
   def connect()
     begin
-      if @request_type == Request::BEDROCK || @request_type == "Bedrock/Pocket Edition"
-        @port = DEFAULT_BEDROCK_PORT if @port == DEFAULT_TCP_PORT && @try_all
+      if @request_type == Request::BEDROCK || @request_type == "Bedrock/Pocket Edition" || @request_type == "UT3/GS4 Query"
+        @port = DEFAULT_BEDROCK_PORT if @port == DEFAULT_TCP_PORT && @request_type != "UT3/GS4 Query" && @try_all
         start_time = Time.now
         @server = UDPSocket.new
         @server.connect(@address, @port)
@@ -205,15 +281,18 @@ class MineStat
     rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
       return Retval::CONNFAIL
     rescue => exception
-      #$stderr.puts exception
+      $stderr.puts exception if @debug
       return Retval::UNKNOWN
     end
     return Retval::SUCCESS
   end
+  private :connect
 
-  # Populates object fields after connecting
-  def parse_data(delimiter, is_beta = false)
+  # Validates server response based on beginning of the packet
+  # @return [String, Retval] Raw data received from a Minecraft server and the return value
+  def check_response()
     data = nil
+    retval = nil
     begin
       if @request_type == "Bedrock/Pocket Edition"
         if @server.recv(1, Socket::MSG_PEEK).unpack('C').first == 0x1C # unconnected pong packet
@@ -222,7 +301,15 @@ class MineStat
           @server.close
         else
           @server.close
-          return Retval::UNKNOWN
+          retval = Retval::UNKNOWN
+        end
+      elsif @request_type == "UT3/GS4 Query"
+        if @server.recv(1, Socket::MSG_PEEK).unpack('C').first == 0x00 # stat packet
+          data = @server.recv(4096)[QUERY_STAT_OFFSET..-1]
+          @server.close
+        else
+          @server.close
+          retval = Retval::UNKNOWN
         end
       else # SLP
         if @server.read(1).unpack('C').first == 0xFF # kick packet (255)
@@ -231,20 +318,31 @@ class MineStat
           @server.close
         else
           @server.close
-          return Retval::UNKNOWN
+          retval = Retval::UNKNOWN
         end
       end
-    rescue
-    #rescue => exception
-      #$stderr.puts exception
-      return Retval::UNKNOWN
+    rescue => exception
+      $stderr.puts exception if @debug
+      return nil, Retval::UNKNOWN
     end
+    retval = Retval::UNKNOWN if data == nil || data.empty?
+    return data, retval
+  end
+  private :check_response
 
-    if data == nil || data.empty?
-      return Retval::UNKNOWN
-    end
+  # Populates object fields after retrieving data from a Minecraft server
+  # @param delimiter [String] Delimiter used to split a string into an array
+  # @param is_beta [Boolean] Whether or not the Minecraft server is using version 1.8b to 1.3
+  def parse_data(delimiter, is_beta = false)
+    data, retval = check_response()
+    return retval if retval == Retval::UNKNOWN
 
-    server_info = data.split(delimiter)
+    server_info = nil
+    if @request_type == "UT3/GS4 Query"
+      server_info = data.split("\x00\x00\x01player_\x00\x00")
+    else
+      server_info = data.split(delimiter)
+    end
     if is_beta
       if server_info != nil && server_info.length >= NUM_FIELDS_BETA
         @version = ">=1.8b/1.3" # since server does not return version, set it
@@ -269,6 +367,25 @@ class MineStat
       else
         return Retval::UNKNOWN
       end
+    elsif @request_type == "UT3/GS4 Query"
+      if server_info != nil
+        @player_list = server_info[1].split(delimiter) unless server_info[1].nil? || server_info[1].empty?
+        server_info = Hash[*server_info[0].split(delimiter).flatten(1)]
+        @version = server_info["version"]
+        @motd = server_info["hostname"]
+        strip_motd
+        @current_players = server_info["numplayers"].to_i
+        @max_players = server_info["maxplayers"].to_i
+        unless server_info["plugins"].nil? || server_info["plugins"].empty?
+          # Vanilla servers do not send a list of plugins.
+          # Bukkit and derivatives send plugins in the form: Paper on 1.19.3-R0.1-SNAPSHOT: Essentials 2.19.7; EssentialsChat 2.19.7
+          @plugin_list = server_info["plugins"].split(':')
+          @plugin_list = @plugin_list[1].split(';').collect(&:strip) if @plugin_list.size > 1
+        end
+        @online = true
+      else
+        return Retval::UNKNOWN
+      end
     else # SLP
       if server_info != nil && server_info.length >= NUM_FIELDS
         # server_info[0] contains the section symbol and 1
@@ -285,18 +402,22 @@ class MineStat
     end
     return Retval::SUCCESS
   end
-
-  ##
-  # 1.8 beta through 1.3 servers communicate as follows for a ping request:
-  # 1. Client sends \xFE (server list ping)
-  # 2. Server responds with:
-  #   2a. \xFF (kick packet)
-  #   2b. data length
-  #   2c. 3 fields delimited by \u00A7 (section symbol)
-  # The 3 fields, in order, are:
-  #   * message of the day
-  #   * current players
-  #   * max players
+  private :parse_data
+
+  # 1.8b - 1.3 (SLP request)
+  # @note
+  #   1. Client sends 0xFE (server list ping)
+  #   2. Server responds with:
+  #     2a. 0xFF (kick packet)
+  #     2b. data length
+  #     2c. 3 fields delimited by \u00A7 (section symbol)
+  #   The 3 fields, in order, are:
+  #     * message of the day
+  #     * current players
+  #     * max players
+  # @return [Retval] Return value
+  # @since 0.2.1
+  # @see https://wiki.vg/Server_List_Ping#Beta_1.8_to_1.3
   def beta_request()
     retval = nil
     begin
@@ -310,7 +431,7 @@ class MineStat
     rescue Timeout::Error
       return Retval::TIMEOUT
     rescue => exception
-      $stderr.puts exception
+      $stderr.puts exception if @debug
       return Retval::UNKNOWN
     end
     if retval == Retval::SUCCESS
@@ -319,26 +440,29 @@ class MineStat
     end
     return retval
   end
-
-  ##
-  # 1.4 and 1.5 servers communicate as follows for a ping request:
-  # 1. Client sends:
-  #   1a. \xFE (server list ping)
-  #   1b. \x01 (server list ping payload)
-  # 2. Server responds with:
-  #   2a. \xFF (kick packet)
-  #   2b. data length
-  #   2c. 6 fields delimited by \x00 (null)
-  # The 6 fields, in order, are:
-  #   * the section symbol and 1
-  #   * protocol version
-  #   * server version
-  #   * message of the day
-  #   * current players
-  #   * max players
+  private :beta_request
+
+  # 1.4 and 1.5 (SLP request)
+  # @note
+  #   1. Client sends:
+  #     1a. 0xFE (server list ping)
+  #     1b. 0x01 (server list ping payload)
+  #   2. Server responds with:
+  #     2a. 0xFF (kick packet)
+  #     2b. data length
+  #     2c. 6 fields delimited by 0x00 (null)
+  #   The 6 fields, in order, are:
+  #     * the section symbol and 1
+  #     * protocol version
+  #     * server version
+  #     * message of the day
+  #     * current players
+  #     * max players
   #
-  # The protocol version corresponds with the server version and can be the
-  # same for different server versions.
+  #   The protocol version corresponds with the server version and can be the
+  #   same for different server versions.
+  # @return [Retval] Return value
+  # @see https://wiki.vg/Server_List_Ping#1.4_to_1.5
   def legacy_request()
     retval = nil
     begin
@@ -352,7 +476,7 @@ class MineStat
     rescue Timeout::Error
       return Retval::TIMEOUT
     rescue => exception
-      $stderr.puts exception
+      $stderr.puts exception if @debug
       return Retval::UNKNOWN
     end
     if retval == Retval::SUCCESS
@@ -361,34 +485,38 @@ class MineStat
     end
     return retval
   end
-
-  ##
-  # 1.6 servers communicate as follows for a ping request:
-  # 1. Client sends:
-  #   1a. \xFE (server list ping)
-  #   1b. \x01 (server list ping payload)
-  #   1c. \xFA (plugin message)
-  #   1d. \x00\x0B (11 which is the length of "MC|PingHost")
-  #   1e. "MC|PingHost" encoded as a UTF-16BE string
-  #   1f. length of remaining data as a short: remote address (encoded as UTF-16BE) + 7
-  #   1g. arbitrary 1.6 protocol version (\x4E for example for 78)
-  #   1h. length of remote address as a short
-  #   1i. remote address encoded as a UTF-16BE string
-  #   1j. remote port as an int
-  # 2. Server responds with:
-  #   2a. \xFF (kick packet)
-  #   2b. data length
-  #   2c. 6 fields delimited by \x00 (null)
-  # The 6 fields, in order, are:
-  #   * the section symbol and 1
-  #   * protocol version
-  #   * server version
-  #   * message of the day
-  #   * current players
-  #   * max players
+  private :legacy_request
+
+  # 1.6 (SLP request)
+  # @note
+  #   1. Client sends:
+  #     1a. 0xFE (server list ping)
+  #     1b. 0x01 (server list ping payload)
+  #     1c. 0xFA (plugin message)
+  #     1d. 0x00 0x0B (11 which is the length of "MC|PingHost")
+  #     1e. "MC|PingHost" encoded as a UTF-16BE string
+  #     1f. length of remaining data as a short: remote address (encoded as UTF-16BE) + 7
+  #     1g. arbitrary 1.6 protocol version (0x4E for example for 78)
+  #     1h. length of remote address as a short
+  #     1i. remote address encoded as a UTF-16BE string
+  #     1j. remote port as an int
+  #   2. Server responds with:
+  #     2a. 0xFF (kick packet)
+  #     2b. data length
+  #     2c. 6 fields delimited by 0x00 (null)
+  #   The 6 fields, in order, are:
+  #     * the section symbol and 1
+  #     * protocol version
+  #     * server version
+  #     * message of the day
+  #     * current players
+  #     * max players
   #
   # The protocol version corresponds with the server version and can be the
   # same for different server versions.
+  # @return [Retval] Return value
+  # @since 0.2.0
+  # @see https://wiki.vg/Server_List_Ping#1.6
   def extended_legacy_request()
     retval = nil
     begin
@@ -409,7 +537,7 @@ class MineStat
     rescue Timeout::Error
       return Retval::TIMEOUT
     rescue => exception
-      $stderr.puts exception
+      $stderr.puts exception if @debug
       return Retval::UNKNOWN
     end
     if retval == Retval::SUCCESS
@@ -418,23 +546,27 @@ class MineStat
     end
     return retval
   end
-
-  ##
-  # 1.7 to current servers communicate as follows for a ping request:
-  # 1. Client sends:
-  #   1a. \x00 (handshake packet containing the fields specified below)
-  #   1b. \x00 (request)
-  # The handshake packet contains the following fields respectively:
-  #     1. protocol version as a varint (\x00 suffices)
-  #     2. remote address as a string
-  #     3. remote port as an unsigned short
-  #     4. state as a varint (should be 1 for status)
-  # 2. Server responds with:
-  #   2a. \x00 (JSON response)
-  # An example JSON string contains:
-  # {'players': {'max': 20, 'online': 0},
-  # 'version': {'protocol': 404, 'name': '1.13.2'},
-  # 'description': {'text': 'A Minecraft Server'}}
+  private :extended_legacy_request
+
+  # >=1.7 (SLP request)
+  # @note
+  #   1. Client sends:
+  #     1a. 0x00 (handshake packet containing the fields specified below)
+  #     1b. 0x00 (request)
+  #   The handshake packet contains the following fields respectively:
+  #       1. protocol version as a varint (0x00 suffices)
+  #       2. remote address as a string
+  #       3. remote port as an unsigned short
+  #       4. state as a varint (should be 1 for status)
+  #   2. Server responds with:
+  #     2a. 0x00 (JSON response)
+  #   An example JSON string contains:
+  #     {'players': {'max': 20, 'online': 0},
+  #     'version': {'protocol': 404, 'name': '1.13.2'},
+  #     'description': {'text': 'A Minecraft Server'}}
+  # @return [Retval] Return value
+  # @since 0.3.0
+  # @see https://wiki.vg/Server_List_Ping#Current_.281.7.2B.29
   def json_request()
     retval = nil
     begin
@@ -483,7 +615,7 @@ class MineStat
     rescue JSON::ParserError
       return Retval::UNKNOWN
     rescue => exception
-      $stderr.puts exception
+      $stderr.puts exception if @debug
       return Retval::UNKNOWN
     end
     if retval == Retval::SUCCESS
@@ -492,8 +624,11 @@ class MineStat
     end
     return retval
   end
+  private :json_request
 
   # Reads JSON data from the socket
+  # @param json_len [Integer] Length of the JSON data received from the Minecraft server
+  # @return [String] JSON data received from the Mincraft server
   def recv_json(json_len)
     json_data = ""
     begin
@@ -505,12 +640,15 @@ class MineStat
         break if json_data.length >= json_len
       end
     rescue => exception
-      $stderr.puts exception
+      $stderr.puts exception if @debug
     end
     return json_data
   end
+  private :recv_json
 
-  # Returns value of varint type
+  # Decodes the value of a varint type
+  # @return [Integer] Value decoded from a varint type
+  # @see https://en.wikipedia.org/wiki/LEB128
   def unpack_varint()
     vint = 0
     i = 0
@@ -524,34 +662,38 @@ class MineStat
     end
     return vint
   end
-
-  ##
-  # Bedrock/Pocket Edition servers communicate as follows for an unconnected ping request:
-  # 1. Client sends:
-  #   1a. \x01 (unconnected ping packet containing the fields specified below)
-  #   1b. current time as a long
-  #   1c. magic number
-  #   1d. client GUID as a long
-  # 2. Server responds with:
-  #   2a. \x1c (unconnected pong packet containing the follow fields)
-  #   2b. current time as a long
-  #   2c. server GUID as a long
-  #   2d. 16-bit magic number
-  #   2e. server ID string length
-  #   2f. server ID as a string
-  # The fields from the pong response, in order, are:
-  #   * edition
-  #   * MotD line 1
-  #   * protocol version
-  #   * version name
-  #   * current player count
-  #   * maximum player count
-  #   * unique server ID
-  #   * MotD line 2
-  #   * game mode as a string
-  #   * game mode as a numeric
-  #   * IPv4 port number
-  #   * IPv6 port number
+  private :unpack_varint
+
+  # Bedrock/Pocket Edition (unconnected ping request)
+  # @note
+  #   1. Client sends:
+  #     1a. 0x01 (unconnected ping packet containing the fields specified below)
+  #     1b. current time as a long
+  #     1c. magic number
+  #     1d. client GUID as a long
+  #   2. Server responds with:
+  #     2a. 0x1c (unconnected pong packet containing the follow fields)
+  #     2b. current time as a long
+  #     2c. server GUID as a long
+  #     2d. 16-bit magic number
+  #     2e. server ID string length
+  #     2f. server ID as a string
+  #   The fields from the pong response, in order, are:
+  #     * edition
+  #     * MotD line 1
+  #     * protocol version
+  #     * version name
+  #     * current player count
+  #     * maximum player count
+  #     * unique server ID
+  #     * MotD line 2
+  #     * game mode as a string
+  #     * game mode as a numeric
+  #     * IPv4 port number
+  #     * IPv6 port number
+  # @return [Retval] Return value
+  # @since 2.2.0
+  # @see https://wiki.vg/Raknet_Protocol#Unconnected_Ping
   def bedrock_request()
     retval = nil
     begin
@@ -571,7 +713,73 @@ class MineStat
     rescue Timeout::Error
       return Retval::TIMEOUT
     rescue => exception
-      $stderr.puts exception
+      $stderr.puts exception if @debug
+      return Retval::UNKNOWN
+    end
+    if retval == Retval::SUCCESS
+      set_connection_status(retval)
+    end
+    return retval
+  end
+  private :bedrock_request
+
+  # Unreal Tournament 3/GameSpy 4 (UT3/GS4) query protocol
+  # @note
+  #   1. Client sends:
+  #     1a. 0xFE 0xFD (query identifier)
+  #     1b. 0x09 (handshake)
+  #     1c. arbitrary session ID (4 bytes)
+  #   2. Server responds with:
+  #     2a. 0x09 (handshake)
+  #     2b. session ID (4 bytes)
+  #     2c. challenge token (variable null-terminated string)
+  #   3. Client sends:
+  #     3a. 0xFE 0xFD (query identifier)
+  #     3b. 0x00 (stat)
+  #     3c. arbitrary session ID (4 bytes)
+  #     3d. challenge token (32-bit integer in network byte order)
+  #     3e. padding (4 bytes -- 0x00 0x00 0x00 0x00); omit padding for basic stat (which does not supply the version)
+  #   4. Server responds with:
+  #     4a. 0x00 (stat)
+  #     4b. session ID (4 bytes)
+  #     4c. padding (11 bytes)
+  #     4e. key/value pairs of multiple null-terminated strings containing the fields below:
+  #         hostname, game type, game ID, version, plugin list, map, current players, max players, port, address
+  #     4f. padding (10 bytes)
+  #     4g. list of null-terminated strings containing player names
+  # @return [Retval] Return value
+  # @since 3.0.0
+  # @see https://wiki.vg/Query
+  def query_request()
+    retval = nil
+    begin
+      Timeout::timeout(@timeout) do
+        @request_type = "UT3/GS4 Query"
+        retval = connect()
+        return retval unless retval == Retval::SUCCESS
+        payload = "\xFE\xFD\x09\x0B\x03\x03\x0F"
+        @server.write(payload)
+        @server.flush
+        if @server.recv(1, Socket::MSG_PEEK).unpack('C').first == 0x09 # query handshake packet
+          # Session ID generated by the server is not used -- use a static session ID instead such as 0x0B 0x03 0x03 0x0F. 
+          #session_id = @server.recv(QUERY_HANDSHAKE_OFFSET, Socket::MSG_PEEK)[1..-1].unpack('l>')
+          challenge_token = @server.recv(QUERY_HANDSHAKE_SIZE)[QUERY_HANDSHAKE_OFFSET..-1]
+          payload = "\xFE\xFD\x00\x0B\x03\x03\x0F".force_encoding('ASCII-8BIT')
+          # Use the full stat below by stripping the null terminator from the challenge token and padding the end
+          # of the payload  with "\x00\x00\x00\x00". The basic stat response does not include the server version.
+          payload += [challenge_token.rstrip.to_i].pack('l>').force_encoding('ASCII-8BIT')
+          payload += "\x00\x00\x00\x00".force_encoding('ASCII-8BIT')
+          @server.write(payload)
+          @server.flush          
+        else
+          return Retval::UNKNOWN
+        end
+        retval = parse_data("\x00") # null
+      end
+    rescue Timeout::Error
+      return Retval::TIMEOUT
+    rescue => exception
+      $stderr.puts exception if @debug
       return Retval::UNKNOWN
     end
     if retval == Retval::SUCCESS
@@ -579,62 +787,89 @@ class MineStat
     end
     return retval
   end
+  private :query_request
 
-  # Returns the Minecraft server IP
+  # Address (hostname or IP address) of the Minecraft server
   attr_reader :address
 
-  # Returns the Minecraft server TCP port
+  # Port (TCP or UDP) of the Minecraft server
   attr_reader :port
 
-  # Returns a boolean describing whether the server is online or offline
+  # Whether or not the Minecraft server is online
   attr_reader :online
 
-  # Returns the Minecraft version that the server is running
+  # Minecraft server version
   attr_reader :version
 
-  # Returns the game mode (Bedrock/Pocket Edition only)
+  # Game mode
+  # @note Bedrock/Pocket Edition only
+  # @since 2.2.0
   attr_reader :mode
 
-  # Returns the full version of the MotD
-  #
-  # If you just want the MotD text, use stripped_motd
+  # Full message of the day (MotD)
+  # @note If only the plain text MotD is relevant, use {#stripped_motd}
+  # @see #stripped_motd
   attr_reader :motd
 
-  # Returns just the plain text contained within the MotD
+  # Plain text contained within the message of the day (MotD)
+  # @note If the full MotD is desired, use {#motd}
+  # @see #motd
   attr_reader :stripped_motd
 
-  # Returns the current player count
+  # Current player count
   attr_reader :current_players
 
-  # Returns the maximum player count
+  # Maximum player limit
   attr_reader :max_players
 
-  # Returns the protocol level
-  #
-  # This is arbitrary and varies by Minecraft version.
-  # However, multiple Minecraft versions can share the same
-  # protocol level
+  # List of players
+  # @note UT3/GS4 query only
+  # @since 3.0.0
+  attr_reader :player_list
+
+  # List of plugins
+  # @note UT3/GS4 query only
+  # @since 3.0.0
+  attr_reader :plugin_list
+
+  # Protocol level
+  # @note This is arbitrary and varies by Minecraft version (may also be shared by multiple Minecraft versions)
   attr_reader :protocol
 
-  # Returns the complete JSON response data for queries to Minecraft
-  # servers with a version greater than or equal to 1.7
+  # Complete JSON response data
+  # @note Received using SLP 1.7 (JSON) queries
+  # @since 0.3.0
   attr_reader :json_data
 
-  # Returns the base64-encoded favicon from JSON 1.7 queries
+  # Base64-encoded favicon
+  # @note Received using SLP 1.7 (JSON) queries
+  # @since 2.2.2
   attr_reader :favicon_b64
 
-  # Returns the decoded favicon from JSON 1.7 queries
+  # Decoded favicon
+  # @note Received using SLP 1.7 (JSON) queries
+  # @since 2.2.2
   attr_reader :favicon
 
-  # Returns the ping time to the server in ms
+  # Ping time to the server in milliseconds (ms)
+  # @since 0.2.1
   attr_reader :latency
 
-  # Returns the protocol version
+  # TCP/UDP timeout in seconds
+  # @since 0.1.2
+  attr_accessor :timeout
+
+  # Protocol used to request data from a Minecraft server
   attr_reader :request_type
 
-  # Returns the connection status
+  # Connection status
+  # @since 2.2.2
   attr_reader :connection_status
 
-  # Returns whether or not all ping protocols should be attempted
+  # Whether or not all protocols should be attempted
   attr_reader :try_all
+
+  # Whether or not debug mode is enabled
+  # @since 3.0.0
+  attr_reader :debug
 end