minestat 0.2.1 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20bcda7c193a48fa96c641630b9a9c732c7b0042d711732c8c6a60774ea425e5
-  data.tar.gz: 39fe195c29631131ee3003d0931658556395efa64c1513cbaa28acde0240fea6
+  metadata.gz: b2824d765e8d40dd3a1087567b27a9a04c9df93427b344c8e47346a0a778f5be
+  data.tar.gz: 5974801cb768bc9a67cd789a0296b569c1f9b14442d7124135c3ddbd8d41886b
 SHA512:
-  metadata.gz: 59a25b2226f196216bffe13ba50f3ae4716c9110034bf1db23064fa0ea2b80436fd3e42a996a46a71e7a7041da0edd52767a0df92285b15a54a325545ee4d8f3
-  data.tar.gz: 8a18ab5dfecee0d7fc7adeb7b6e63c16165d499db8f679a27ad63833e082fffe52f040b482009b0941750f7eee819bb59ad3f24d8c924d2aef9b339488b83176
+  metadata.gz: fc7bb79f048f5d280405638d416cb74ef8e0da6873074bd6e1b70c8176c913fc5fa59ffb92aaa3673f972225851b533964402cfc76160d1d5caec4bf207c43a2
+  data.tar.gz: 885fb2073958d8a95f121ed7a45e230987520dd0878744650bfe6ec45082a75a1e5dc9d512e76aff6dad965b3a36e493a76e9e5e6bd085bde14d2dd562eb33e6

data/lib/minestat.rb

@@ -1,5 +1,5 @@
 # minestat.rb - A Minecraft server status checker
-# Copyright (C) 2014 Lloyd Dilley
+# Copyright (C) 2014-2021 Lloyd Dilley
 # http://www.dilley.me/
 #
 # This program is free software; you can redistribute it and/or modify
@@ -16,106 +16,225 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
+require 'json'
 require 'socket'
 require 'timeout'
 
+##
+# Provides a ruby interface for polling Minecraft server status.
 class MineStat
-  NUM_FIELDS = 6       # number of values expected from server
-  NUM_FIELDS_BETA = 3  # number of values expected from a 1.8b/1.3 server
-  DEFAULT_TIMEOUT = 5  # default TCP timeout in seconds
+  # MineStat version
+  VERSION = "2.1.1"
+  # Number of values expected from server
+  NUM_FIELDS = 6
+  # Number of values expected from a 1.8b/1.3 server
+  NUM_FIELDS_BETA = 3
+  # Maximum number of bytes a varint can be
+  MAX_VARINT_SIZE = 5
+  # Default TCP port
+  DEFAULT_PORT = 25565
+  # Default TCP timeout in seconds
+  DEFAULT_TIMEOUT = 5
 
+  ##
+  # Stores constants that represent the results of a server ping
   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
 
-  def initialize(address, port, timeout = DEFAULT_TIMEOUT)
-    @address = address
-    @port = port
+  ##
+  # Stores constants that represent the different kinds of server
+  # list pings/requests that a Minecraft server might expect when
+  # being polled for status information.
+  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
+  end
+
+  ##
+  # Instantiate an instance of MineStat and poll the specified server for information
+  def initialize(address, port = DEFAULT_PORT, timeout = DEFAULT_TIMEOUT, request_type = Request::NONE)
+    @address = address # address of server
+    @port = port       # TCP port of server
     @online            # online or offline?
     @version           # server version
     @motd              # message of the day
+    @stripped_motd     # message of the day without formatting
     @current_players   # current number of players online
     @max_players       # maximum player capacity
+    @protocol          # protocol level
+    @json_data         # JSON data for 1.7 queries
     @latency           # ping time to server in milliseconds
+    @timeout = timeout # TCP timeout
+    @server            # server socket
+    @request_type      # SLP protocol version
 
-    # Try the newest protocol first and work down. If the query succeeds or the
-    # connection fails, there is no reason to continue with subsequent queries.
-    # Attempts should continue in the event of a timeout however since it may
-    # be due to an issue during the handshake.
-    # Note: Newer server versions may still respond to older ping query types.
-    # For example, 1.13.2 responds to 1.4/1.5 queries, but not 1.6 queries.
-    # 1.7
-    retval = json_query(address, port, timeout)
-    # 1.6
-    unless retval == Retval::SUCCESS || retval == Retval::CONNFAIL
-      retval = new_query(address, port, timeout)
+    case request_type
+      when Request::BETA
+        retval = beta_request()
+      when Request::LEGACY
+        retval = legacy_request()
+      when Request::EXTENDED
+        retval = extended_legacy_request()
+      when Request::JSON
+        retval = json_request()
+      else
+        # Attempt various SLP ping requests in a particular order. If the request
+        # succeeds or the connection fails, there is no reason to continue with
+        # subsequent requests. Attempts should continue in the event of a timeout
+        # however since it may be due to an issue during the handshake.
+        # Note: Newer server versions may still respond to older SLP requests.
+        # For example, 1.13.2 responds to 1.4/1.5 queries, but not 1.6 queries.
+        # SLP 1.4/1.5
+        retval = legacy_request()
+        # SLP 1.8b/1.3
+        unless retval == Retval::SUCCESS || retval == Retval::CONNFAIL
+          retval = beta_request()
+        end
+        # SLP 1.6
+        unless retval == Retval::CONNFAIL
+          retval = extended_legacy_request()
+        end
+        # SLP 1.7
+        unless retval == Retval::CONNFAIL
+          retval = json_request()
+        end
     end
-    # 1.4/1.5
-    unless retval == Retval::SUCCESS || retval == Retval::CONNFAIL
-      retval = legacy_query(address, port, timeout)
+    @online = false unless retval == Retval::SUCCESS
+  end
+
+  # Strips message of the day formatting characters
+  def strip_motd()
+    unless @motd['text'] == nil
+      @stripped_motd = @motd['text']
+    else
+      @stripped_motd = @motd
     end
-    # 1.8b/1.3
-    unless retval == Retval::SUCCESS || retval == Retval::CONNFAIL
-      retval = beta_query(address, port, timeout)
+    unless @motd['extra'] == nil
+      json_data = @motd['extra']
+      unless json_data.nil? || json_data.empty?
+        json_data.each do |nested_hash|
+          @stripped_motd += nested_hash['text']
+        end
+      end
     end
+    @stripped_motd = @stripped_motd.gsub(/§./, "")
+  end
 
-    @online = false unless retval == Retval::SUCCESS
+  ##
+  # Establishes a connection to the Minecraft server
+  def connect()
+    begin
+      start_time = Time.now
+      @server = TCPSocket.new(@address, @port)
+      @latency = ((Time.now - start_time) * 1000).round
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
+      return Retval::CONNFAIL
+    rescue => exception
+      $stderr.puts exception
+      return Retval::UNKNOWN
+    end
+    return Retval::SUCCESS
+  end
+
+  # Populates object fields after connecting
+  def parse_data(delimiter, is_beta = false)
+    data = nil
+    begin
+      if @server.read(1).unpack('C').first == 0xFF # kick packet (255)
+        len = @server.read(2).unpack('n').first
+        data = @server.read(len * 2).force_encoding('UTF-16BE').encode('UTF-8')
+        @server.close
+      else
+        @server.close
+        return Retval::UNKNOWN
+      end
+    rescue => exception
+      #$stderr.puts exception
+      return Retval::UNKNOWN
+    end
+
+    if data == nil || data.empty?
+      return Retval::UNKNOWN
+    end
+
+    server_info = data.split(delimiter)
+    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
+        @motd = server_info[0]
+        strip_motd
+        @current_players = server_info[1].to_i
+        @max_players = server_info[2].to_i
+        @online = true
+      else
+        return Retval::UNKNOWN
+      end
+    else
+      if server_info != nil && server_info.length >= NUM_FIELDS
+        # server_info[0] contains the section symbol and 1
+        @protocol = server_info[1].to_i # contains the protocol version (51 for 1.9 or 78 for 1.6.4 for example)
+        @version = server_info[2]
+        @motd = server_info[3]
+        strip_motd
+        @current_players = server_info[4].to_i
+        @max_players = server_info[5].to_i
+        @online = true
+      else
+        return Retval::UNKNOWN
+      end
+    end
+    return Retval::SUCCESS
   end
 
-  # 1.8b/1.3
-  # 1.8 beta through 1.3 servers communicate as follows for a ping query:
+  ##
+  # 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, and max players
-  def beta_query(address, port, timeout)
+  # The 3 fields, in order, are:
+  # * message of the day
+  # * current players
+  # * max players
+  def beta_request()
+    retval = nil
     begin
-      data = nil
-      Timeout::timeout(timeout) do
-        start_time = Time.now
-        server = TCPSocket.new(address, port)
-        @latency = ((Time.now - start_time) * 1000).round
-        server.write("\xFE")
-        if server.read(1).unpack('C').first == 0xFF # kick packet (255)
-          len = server.read(2).unpack('n').first
-          data = server.read(len * 2).force_encoding('UTF-16BE').encode('UTF-8')
-          server.close
-        else
-          server.close
-          return Retval::UNKNOWN
-        end
-      end
-
-      if data == nil || data.empty?
-        return Retval::UNKNOWN
-      else
-        server_info = data.split("\u00A7") # section symbol
-        if server_info != nil && server_info.length >= NUM_FIELDS_BETA
-          @version = "1.8b/1.3" # since server does not return version, set it
-          @motd = server_info[0]
-          @current_players = server_info[1]
-          @max_players = server_info[2]
-          @online = true
-        end
+      Timeout::timeout(@timeout) do
+        retval = connect()
+        return retval unless retval == Retval::SUCCESS
+        # Perform handshake and acquire data
+        @request_type = "SLP 1.8b/1.3 (beta)"
+        @server.write("\xFE")
+        retval = parse_data("\u00A7", true) # section symbol
       end
-    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
-      return Retval::CONNFAIL
     rescue Timeout::Error
       return Retval::TIMEOUT
     rescue => exception
       $stderr.puts exception
       return Retval::UNKNOWN
     end
-    return Retval::SUCCESS
+    return retval
   end
 
-  # 1.4/1.5
-  # 1.4 and 1.5 servers communicate as follows for a ping query:
+  ##
+  # 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)
@@ -123,57 +242,38 @@ class MineStat
   #   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, and max players
+  # 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.
-  def legacy_query(address, port, timeout)
+  def legacy_request()
+    retval = nil
     begin
-      data = nil
-      Timeout::timeout(timeout) do
-        start_time = Time.now
-        server = TCPSocket.new(address, port)
-        @latency = ((Time.now - start_time) * 1000).round
-        server.write("\xFE\x01")
-        if server.read(1).unpack('C').first == 0xFF # kick packet (255)
-          len = server.read(2).unpack('n').first
-          data = server.read(len * 2).force_encoding('UTF-16BE').encode('UTF-8')
-          server.close
-        else
-          server.close
-          return Retval::UNKNOWN
-        end
-      end
-
-      if data == nil || data.empty?
-        return Retval::UNKNOWN
-      else
-        server_info = data.split("\x00") # null
-        if server_info != nil && server_info.length >= NUM_FIELDS
-          # server_info[0] contains the section symbol and 1
-          # server_info[1] contains the protocol version (51 for example)
-          @version = server_info[2]
-          @motd = server_info[3]
-          @current_players = server_info[4]
-          @max_players = server_info[5]
-          @online = true
-        else
-          return Retval::UNKNOWN
-        end
+      Timeout::timeout(@timeout) do
+        retval = connect()
+        return retval unless retval == Retval::SUCCESS
+        # Perform handshake and acquire data
+        @request_type = "SLP 1.4/1.5 (legacy)"
+        @server.write("\xFE\x01")
+        retval = parse_data("\x00") # null
       end
-    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
-      return Retval::CONNFAIL
     rescue Timeout::Error
       return Retval::TIMEOUT
     rescue => exception
       $stderr.puts exception
       return Retval::UNKNOWN
     end
-    return Retval::SUCCESS
+    return retval
   end
 
-  # 1.6
-  # 1.6 servers communicate as follows for a ping query:
+  ##
+  # 1.6 servers communicate as follows for a ping request:
   # 1. Client sends:
   #   1a. \xFE (server list ping)
   #   1b. \x01 (server list ping payload)
@@ -189,64 +289,45 @@ class MineStat
   #   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, and max players
+  # 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.
-  def new_query(address, port, timeout)
+  def extended_legacy_request()
+    retval = nil
     begin
-      data = nil
-      Timeout::timeout(DEFAULT_TIMEOUT) do
-        start_time = Time.now
-        server = TCPSocket.new(address, port)
-        @latency = ((Time.now - start_time) * 1000).round
-        server.write("\xFE\x01\xFA")
-        server.write("\x00\x0B") # 11 (length of "MC|PingHost")
-        server.write('MC|PingHost'.encode('UTF-16BE').force_encoding('ASCII-8BIT'))
-        server.write([7 + 2 * address.length].pack('n'))
-        server.write("\x4E")     # 78 (protocol version of 1.6.4)
-        server.write([address.length].pack('n'))
-        server.write(address.encode('UTF-16BE').force_encoding('ASCII-8BIT'))
-        server.write([port].pack('N'))
-        if server.read(1).unpack('C').first == 0xFF # kick packet (255)
-          len = server.read(2).unpack('n').first
-          data = server.read(len * 2).force_encoding('UTF-16BE').encode('UTF-8')
-          server.close
-        else
-          server.close
-          return Retval::UNKNOWN
-        end
-      end
-
-      if data == nil || data.empty?
-        return Retval::UNKNOWN
-      else
-        server_info = data.split("\x00") # null
-        if server_info != nil && server_info.length >= NUM_FIELDS
-          # server_info[0] contains the section symbol and 1
-          # server_info[1] contains the protocol version (78 for example)
-          @version = server_info[2]
-          @motd = server_info[3]
-          @current_players = server_info[4]
-          @max_players = server_info[5]
-          @online = true
-        else
-          return Retval::UNKNOWN
-        end
+      Timeout::timeout(@timeout) do
+        retval = connect()
+        return retval unless retval == Retval::SUCCESS
+        # Perform handshake and acquire data
+        @request_type = "SLP 1.6 (extended legacy)"
+        @server.write("\xFE\x01\xFA")
+        @server.write("\x00\x0B") # 11 (length of "MC|PingHost")
+        @server.write('MC|PingHost'.encode('UTF-16BE').force_encoding('ASCII-8BIT'))
+        @server.write([7 + 2 * @address.length].pack('n'))
+        @server.write("\x4E")     # 78 (protocol version of 1.6.4)
+        @server.write([@address.length].pack('n'))
+        @server.write(@address.encode('UTF-16BE').force_encoding('ASCII-8BIT'))
+        @server.write([@port].pack('N'))
+        retval = parse_data("\x00") # null
       end
-    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
-      return Retval::CONNFAIL
     rescue Timeout::Error
       return Retval::TIMEOUT
     rescue => exception
       $stderr.puts exception
       return Retval::UNKNOWN
     end
-    return Retval::SUCCESS
+    return retval
   end
 
-  # 1.7
-  # 1.7 to current servers communicate as follows for a ping query:
+  ##
+  # 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)
@@ -261,9 +342,128 @@ class MineStat
   # {'players': {'max': 20, 'online': 0},
   # 'version': {'protocol': 404, 'name': '1.13.2'},
   # 'description': {'text': 'A Minecraft Server'}}
-  def json_query(address, port, timeout)
-    return Retval::UNKNOWN # ToDo: Implement me!
+  def json_request()
+    retval = nil
+    begin
+      Timeout::timeout(@timeout) do
+        retval = connect()
+        return retval unless retval == Retval::SUCCESS
+        # Perform handshake
+        @request_type = "SLP 1.7 (JSON)"
+        payload = "\x00\x00"
+        payload += [@address.length].pack('c') << @address
+        payload += [@port].pack('n')
+        payload += "\x01"
+        payload = [payload.length].pack('c') << payload
+        @server.write(payload)
+        @server.write("\x01\x00")
+        @server.flush
+
+        # Acquire data
+        _total_len = unpack_varint
+        return Retval::UNKNOWN if unpack_varint != 0
+        json_len = unpack_varint
+        json_data = recv_json(json_len)
+        @server.close
+
+        # Parse data
+        json_data = JSON.parse(json_data)
+        @json_data = json_data
+        @protocol = json_data['version']['protocol'].to_i
+        @version = json_data['version']['name']
+        @motd = json_data['description']
+        strip_motd
+        @current_players = json_data['players']['online'].to_i
+        @max_players = json_data['players']['max'].to_i
+        if !@version.empty? && !@motd.empty? && !@current_players.nil? && !@max_players.nil?
+          @online = true
+        else
+          retval = Retval::UNKNOWN
+        end
+      end
+    rescue Timeout::Error
+      return Retval::TIMEOUT
+    rescue JSON::ParserError
+      return Retval::UNKNOWN
+    rescue => exception
+      $stderr.puts exception
+      return Retval::UNKNOWN
+    end
+    return retval
+  end
+
+  # Reads JSON data from the socket
+  def recv_json(json_len)
+    json_data = ""
+    begin
+      loop do
+        remaining = json_len - json_data.length
+        data = @server.recv(remaining)
+        @server.flush
+        json_data += data
+        break if json_data.length >= json_len
+      end
+    rescue => exception
+      $stderr.puts exception
+    end
+    return json_data
   end
 
-  attr_reader :address, :port, :online, :version, :motd, :current_players, :max_players, :latency
+  # Returns value of varint type
+  def unpack_varint()
+    vint = 0
+    i = 0
+    while i <= MAX_VARINT_SIZE
+      data = @server.read(1)
+      return 0 if data.nil? || data.empty?
+      data = data.ord
+      vint |= (data & 0x7F) << 7 * i
+      break if (data & 0x80) != 128
+      i += 1
+    end
+    return vint
+  end
+
+  # Returns the Minecraft server IP
+  attr_reader :address
+
+  # Returns the Minecraft server TCP port
+  attr_reader :port
+
+  # Returns a boolean describing whether the server is online or offline
+  attr_reader :online
+
+  # Returns the Minecraft version that the server is running
+  attr_reader :version
+
+  # Returns the full version of the MOTD
+  #
+  # If you just want the MOTD text, use stripped_motd
+  attr_reader :motd
+
+  # Returns just the plain text contained within the MOTD
+  attr_reader :stripped_motd
+
+  # Returns the current player count
+  attr_reader :current_players
+
+  # Returns the maximum player count
+  attr_reader :max_players
+
+  # Returns the SLP (Server List Ping) protocol level
+  #
+  # This is arbitrary and varies by Minecraft version.
+  # However, multiple Minecraft versions can share the same
+  # protocol level
+  attr_reader :protocol
+
+  # Returns the complete JSON response data for queries to Minecraft
+  # servers with a version greater than or equal to 1.7
+  attr_reader :json_data
+
+  # Returns the ping time to the server in ms
+  attr_reader :latency
+
+  # Returns the SLP (Server List Ping) protocol version
+  attr_reader :request_type
 end

metadata

@@ -1,18 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: minestat
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 2.1.1
 platform: ruby
 authors:
 - Lloyd Dilley
 - Stepan Melnikov
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-04-26 00:00:00.000000000 Z
+date: 2021-09-27 00:00:00.000000000 Z
 dependencies: []
 description: MineStat polls Minecraft server data such as version, motd, current players,
-  and max players using a variety of programming languages.
+  and max players.
 email:
 - minecraft@frag.land
 executables: []
@@ -24,7 +24,7 @@ homepage: https://github.com/FragLand/minestat
 licenses:
 - GPL-3.0
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -39,9 +39,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6.2
-signing_key: 
+rubygems_version: 3.2.22
+signing_key:
 specification_version: 4
 summary: Minecraft server status checker
 test_files: []